dasha-ws/ai-dev-framework/build-feature

build-feature

Purpose

/build-feature implements one work item of a target project in code: the production code, the automated tests that belong to it, and the implementation-side configuration, migrations and artifacts that the approved scope requires. It works from the actual repository state and hands the result to verification.

• Substantial work implements the current reviewed Tech Spec, .claude/work/<work-item-name>/tech-spec.md. A real microchange is work where a separate Tech Spec would be decoration. The user's request is then the work instruction.
• It is an implementation skill, not an independent verification or review gate. It calls no reviewer.
• It can be entered again when a downstream gate returns a concrete finding whose root cause is implementation-side (step 2).
• Done means ready for the applicable verification. It does not mean tested, reviewed, documented or deploy-ready. What follows is governed by "Next skills".

When to use

• Substantial work whose current Tech Spec has passed /review-spec.
• A real microchange: a typo, a small obvious text edit, an obvious one-line fix, a very small isolated bugfix, or another truly microscopic change with no new product, architecture or substantial technical decision.
• Continuing a partially implemented work item.
• Correcting a concrete implementation-side finding returned by /test-feature, /review-code, /update-docs or /deploy-check.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing. Stop and suggest /init-project.
• Substantial work has no Tech Spec, or its current version has no established /review-spec PASS: /tech-spec or /review-spec first.
• The work needs a change of requirements, a substantive redesign of the Tech Spec or a substantive architecture decision: route upstream (step 3).
• The user wants independent testing (/test-feature), a code review (/review-code), documentation updated (/update-docs) or deployment readiness checked (/deploy-check).
• The request covers several work items. One per run.

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The reviewed Tech Spec (substantial work), or the user's request (microchange).
• The applicable upstream requirements spec: the Feature Spec of the work item, or the Product Spec for an initial product implementation.
• The framework structure created by `/init-project`. For substantial work: root CLAUDE.md, .claude/skills/project-context/SKILL.md, in .claude/skills/project-context/context/ the files product.md, architecture.md, development.md and infrastructure.md, plus .claude/product/product-spec.md and .claude/work/. For a microchange: root CLAUDE.md and the router.
• The codebase, its tests and its configuration.
• The concrete downstream finding and its evidence, on a return after a downstream gate.
• The user, for the few questions only they can settle (step 5).

Files to read

Read before writing any code. All reads are read-only.

• Substantial work: the root CLAUDE.md; the router; the current reviewed Tech Spec; the applicable upstream requirements spec; the current architecture.md; the relevant parts of development.md and infrastructure.md; ux-guide.md if the work item is user-facing and the router marks it as relevant; the relevant code, tests and configuration. The Product Spec only where it is needed to understand a requirement.
• Microchange: the root CLAUDE.md, the router, the minimum relevant context, and the affected code, tests and configuration.

Do not load the whole repository without a reason. Never read real .env files, credentials, tokens or passwords, and never expose secrets.

Execution steps

1. Confirm the target and the project rules

Verify that the working directory is a target project, not the framework repo, and that the framework structure required for the mode exists (see "Inputs"). If any of it is missing: stop, say what is missing and suggest /init-project. Do not create the structure yourself and do not rebuild it from memory.

Follow the target project's root CLAUDE.md and conventions: commands, style, testing, file layout, local workflow. They may refine how the work is done. They cannot silently override a mandatory ai-dev-framework gate or allow requirements or architecture drift. If a project instruction directly conflicts with a mandatory framework rule and both cannot be satisfied: do not pick the convenient one. Stop, report the conflict and ask for a decision.

2. Decide the mode, the work item and the entry

Mode. Substantial work or a real microchange. Never relabel substantial work as a microchange for speed: new product behaviour, an architecture question, a new dependency, a schema or contract, or any technical decision that is not obvious makes it substantial and needs a reviewed Tech Spec. If a microchange turns out to be substantive, stop and route upstream (step 3). No "just this once". For a real microchange the request is the work instruction. No Tech Spec is created, the Tech Spec prerequisite of step 3 is skipped, and everything else applies in proportion: a minimally sufficient change, a test only if the behaviour change really needs one, proportional developer verification, and no new dependency.

Work item. Exactly one, from the current Tech Spec. If the Tech Spec describes several or the request mixes several, do not merge them: take the one the Tech Spec and the user point to, and ask if that is unclear. No neighbouring feature "while we are here". If the work item depends on unfinished work: when the Tech Spec already provides for it and it only affects the order, keep the order. If it blocks a safe implementation, stop and report the blocker. Never implement someone else's work item quietly.

Work item id. For substantial work the id is the name of the work-item folder under .claude/work/. A microchange has no folder: choose a short kebab-case id that is neither a folder under .claude/work/ or .claude/work/completed/ nor the id of a different change in .claude/work/status.md (run powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check). If the ledger already has a scope row with that id and the request plainly continues that same change, reuse it. If it is unclear whether it is the same change, ask. Never reuse an id for a different change.

Entry. One of three:

• First implementation. Nothing of the work exists in the code yet.
• Partial implementation. Inspect the current implementation and continue from its real state. Do not assume a clean start and do not recreate finished work blindly. Uncommitted changes that are visibly the earlier partial implementation of this same work item are the state to continue from. They remain part of the baseline and are never overwritten blindly. If it is unclear which changes belong to that work and which are unrelated user work, the recovery boundary of step 4 applies.
• Return after a downstream finding. The finding comes from /test-feature, /review-code, /update-docs or /deploy-check. The root cause decides the route, not the gate that found the problem. /build-feature takes only an implementation-side finding: an implementation defect, a test-code defect that belongs to the implementation work, a concrete code or configuration defect (a security one included), or an implementation defect found while documenting. Not build work: a requirement, Tech Spec, design or architecture problem goes upstream (step 3), a documentation-only problem goes to /update-docs, and a deployment environment, access or tooling prerequisite goes to its owner. Read the finding and its evidence and work from the current implementation. A defect in the implementation of an already approved design does not need a new Tech Spec. A finding never widens the approved scope. For a microchange the request and the finding are the basis.

3. Check the prerequisite and the current sources

Sources. The Product Spec and the reviewed Feature Spec define the requirements. The reviewed Tech Spec defines the design of substantial work. architecture.md defines the agreed durable architecture. Project context holds durable constraints. Code shows the current implementation, which is not intended behaviour just because it exists. /build-feature does not re-review any of them. It only notices a known mismatch or change and routes it.

The prerequisite (substantial work). The current version of the Tech Spec must have a /review-spec PASS. That PASS already covers the upstream prerequisites that /review-spec checks. It counts as reliably established in exactly three cases:

1. the current conversation or workflow contains a /review-spec PASS for this very version, and the Tech Spec has had no substantive change since;
2. the user explicitly confirms that the current version already got a PASS and has not changed in substance since;
3. the workflow ledger .claude/work/status.md has a review-spec row with the subject <id>/tech-spec that powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check reports FRESH (see templates/work/status.md). The script decides freshness. A STALE or missing row is not established.

In every other case it is not established. Never infer it from the Tech Spec existing, git history, commits, timestamps, comments, naming or status fields in the spec. If it is not established: do not implement. Stop and suggest /review-spec. If the conversation or a FRESH ledger row already establishes it, do not ask for a ritual confirmation.

Sources that changed after the PASS. The same rule of reliable establishment applies. If it is reliably shown that after the PASS the applicable upstream requirements or the agreed architecture.md changed substantively, the old PASS is not a sufficient basis. Do not run a re-review here. Stop and route upstream by root cause:

• it is not known whether the Tech Spec is still correct against the current sources: /review-spec;
• the Tech Spec obviously needs substantive design changes: /tech-spec → /review-spec;
• the requirements change has not passed the workflow and gate it needs: the matching requirements workflow first (/product-spec or /new-feature-spec);
• the architecture needs an unfinished architecture workflow or review: /architecture first.

"Route upstream" anywhere in this skill means this mapping. Never fix a source of truth silently.

4. Read the current state, take the baseline and set the recovery boundary

Read what "Files to read" lists for the mode. Before the first change, find out the real state: the affected files, modules and components, the existing interfaces and contracts, the existing tests, the dependencies in use, the conventions, and what exists now as against what the Tech Spec plans to create. Do not invent filenames, classes, modules, tables, APIs, queues, services, dependencies, commands, a test framework or a deployment setup. A planned artifact that does not exist yet is created only if this work item is the one that must create it. An artifact that another unfinished work item must create does not exist yet (see step 2).