feature - create the active implementation spec

Context reuse: Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.

This skill plans one feature and stops before implementation. Its output is blueprint/context/current-feature.md.

Start

First action: Before project inspection, preflight, or any other tool call, publish the feature activity as running when blueprint/.state/ exists. Combine that write with the first context-gathering tool batch when the adapter supports it.

Read blueprint/config.json only for settings that affect the spec. Invalid configuration stops mutating work and points to /doctor.

Confirm that blueprint/context/current-feature.md is the empty stub. If it contains active work, stop and direct the user to resume or complete it.

Resolve the target from blueprint/build-plan.md:

• Use the requested number or name when it matches a checklist item.
• With no argument, use the first unchecked leaf item.
• Read only the matching checklist line, its parent, and nearby text needed to understand the hierarchy.
• If a plain list has no checkboxes, treat its first item as unchecked and offer to convert the plan after the spec review.

State the selected feature in one sentence.

Build one authoritative feature packet

Gather the smallest packet that can answer what must be built:

1. Search blueprint/context/project-overview.md for the feature number, title, and distinctive nouns from the target line. Read the matching feature passage plus only the data-model, stack, UI, security, or deployment passages it directly depends on. Do not read the whole overview by default.
2. Inspect the repository once, starting from paths named by those passages. Follow only relevant imports, callers, tests, schemas, and configuration. Batch related searches and reads when supported.
3. Use the Commands section already loaded from AGENTS.md. Read it from disk only when it is absent or changed. Read only applicable sections of blueprint/context/coding-standards.md.
4. Run the declared Verify command once when it exists. Record only observed results. Do not start a dev server.

Finish context gathering in at most four tool rounds after this skill starts: target and overview matches, one batched repository inspection, applicable standards only if needed, and Verify. Combine or skip rounds when possible. Do not inspect skill directories, ai-interaction.md, findings, review records, history, or templates during normal planned-feature work. Do not create scratch code or run implementation probes while writing a spec. Put a check in the relevant build step when a repository detail cannot be confirmed from existing evidence.

The plans and overview define product intent. The repository defines current reality. Do not invent presets, defaults, limits, permissions, money rules, destructive behavior, stored fields, or API contracts. A familiar label is not a complete contract when it has multiple reasonable meanings. Put unresolved material choices under an Open questions heading and in the review handoff. Stop without writing the spec when implementation cannot begin safely until one is answered. Do not block on a reversible internal implementation detail with no user-visible, security, persisted-data, or interoperability consequence. Choose the simplest repository-native option, record it in the spec, and require a test seam when the value is nondeterministic. Planned future persistence alone does not make a current in-memory representation a product decision when no stored data or external compatibility exists yet.

If project-overview.md is 20,000 bytes or larger, stop and ask for /overview instead of loading it. If the target is too large for one reviewable branch, propose sub-features and wait for approval before editing the user-owned build plan. After approval, add lettered checklist items under the parent and spec only the first one.

New feature not in the plan

Do not silently add scope. Search for a duplicate, then propose one checkbox line and its placement. Include a project-plan.md edit only when the request changes the product direction, users, data, stack, monetization, UI, or deployment. Wait for approval, update the plans, run the installed overview skill, and then resume this skill. Bugs and small unplanned changes belong in /fix.

Write the final spec once

Draft and critique in context, then write blueprint/context/current-feature.md once. A later write is only for a mechanical correction or user-requested revision. Record **Branch:** with the full configured feature branch, then use these headings:

• Goal
• Design reference, only for visual or replication work
• In scope
• Out of scope
• Build loop
• Build steps
• Files / areas
• Data / contracts
• Testing
• Notes for the AI
• Open questions, only when a product decision remains unresolved

Build steps are ordered checklist items. Each step must leave the project working, stay small enough to review, and end with a concrete Done when that names observable behavior and the relevant check. Follow workflow.stepReview and workflow.checkpointCommits from config in the Build loop. /complete creates the final feature commit.

The spec must preserve every explicit contract in the feature packet, including applicable project-wide UX and security requirements. Do not discard a required state because the current fixture cannot trigger it yet. Keep later features out, define authorization and tenant boundaries, identify client and server responsibilities, and name exact files or areas supported by repository evidence. Add focused tests for logic when a test command exists. Add browser coverage only when a Browser tests command exists and it is proportionate. Do not claim live, visual, persisted-data, or integration evidence that was not run.

Build the branch value from the configured feature prefix plus the feature title in lowercase kebab-case. Replace each run of characters other than ASCII letters and digits with one hyphen and trim edge hyphens.

For visual replication, require an existing screenshot or reference. Store a provided image under blueprint/reference/ and link it. If prototypes/ exists, use its relevant HTML and theme.css; port shared tokens before feature UI.

Critique gate

Before the single write, check these failure classes:

• Missing happy, loading, empty, invalid, denied, and unexpected-error behavior that applies to the feature.
• A product contract from the packet that was omitted, weakened, or contradicted.
• Scope added from guesswork or pulled forward from a later feature.
• An oversized or incorrectly ordered build step.
• A data or API contract leaves a required type, format or encoding, generator, uniqueness rule, default, lifecycle state, serialization rule, or stable result and error shape for later work to reinterpret.
• A security-sensitive flow leaves the trusted actor source, repository-first tenant scope, atomic uniqueness or mutation boundary, idempotency, or redaction behavior implicit.
• User-controlled text lacks a safe rendering rule, or validation and error feedback lacks the relevant label, association, announcement, focus, or clearing behavior.
• A new file, asset, import, or route is not reachable through the current runtime and server behavior.
• An authorization or URL shape later work would have to reinterpret.
• A done-when that cannot be observed or a test claim the repository cannot run.
• A prerequisite that makes the final Verify gate impossible.

If a prerequisite is absent, incomplete, untracked, or unverified, say which one the evidence shows. Do not bury repair inside this feature. Stop with the exact /fix or user decision required.

Otherwise write the tightened spec, update activity to ready, and stop for review. Lead with a short note naming what the critique changed, or say that it found no material change. Never implement from this skill.