build-feature

name

build-feature

description

Orchestrate parallel implementation of a feature specification by dispatching coder agents wave-by-wave with spec-compliance and code-quality review gates between waves. Use this skill when the user says "implement this feature", "start implementing", "run the spec", "execute the plan", "continue implementing", or wants to begin coding a previously planned feature from a docs/specs/YYYY-MM-DD-{feature-name}/ folder. Also use when the user says "/build-feature" or drags a spec folder into the conversation and asks to implement it. This skill does NOT write code itself - it orchestrates coder subagents that work in parallel.

Build Feature

Orchestrate the parallel implementation of a feature specification by dispatching coder agents wave by wave. This skill reads a spec folder created by plan-feature, uses spec.json as the machine-readable contract, spawns coder agents for each ready task, runs a behavior-preserving simplification pass, runs spec-compliance review before code-quality review, and appends execution evidence to implementation-log.md.

The orchestrator never writes code itself when subagents are available. Its job is to:

1. Parse the spec manifest and determine what to do next
2. Give each coder agent exactly the context it needs
3. Verify task output against the approved design and task specs
4. Run a behavior-preserving simplification pass on changed implementation files
5. Verify code quality, integration, security, simplicity, and maintainability
6. Manage the fix loop if either review stage finds issues
7. Track progress in spec.json, task files, README checkboxes, and implementation-log.md

Prerequisites

A docs/specs/YYYY-MM-DD-{feature-name}/ directory containing:

• README.md with wave assignments and task status checkboxes
• spec.json with task IDs, waves, dependencies, file ownership, status values, and verification commands
• requirements.md with feature context
• action-required.md with manual human actions
• implementation-log.md for append-only execution notes
• tasks/task-{nn}-*.md files, one self-contained task per implementation unit

The matching approved design must exist at docs/design/YYYY-MM-DD-{feature-name}/design.md.

This structure is produced by the plan-feature skill. If the user does not have a spec folder, suggest creating one first.

Status Values

Use these values exactly:

• pending - not started
• in-progress - currently assigned or being worked
• blocked - cannot proceed without user action or an external environment change
• needs-context - implementation needs clarification or missing project context
• done-with-concerns - implementation completed but review concerns remain
• review-failed - a spec or code review failed and fixes are required
• complete - accepted after required review and verification

Only complete maps to a checked README checkbox. Every other status maps to an unchecked checkbox.

Orchestration

Step 1: Load the Spec

1. Resolve the spec folder. Accept either the full dated folder name or an undated feature name.
   • If the full dated folder exists, use it.
   • For undated names, search docs/specs/*-{feature-name}.
   • If there are no matches, ask for the spec folder or suggest plan-feature.
   • If there is exactly one match, use it.
   • If there are multiple matches, list the candidates and ask the user which one to execute. Do not silently choose the newest match.
2. Derive the matching design path at docs/design/<resolved-spec-folder-name>/design.md.
3. Read these files:
   • <resolved-spec-folder>/spec.json
   • <resolved-spec-folder>/README.md
   • <resolved-spec-folder>/requirements.md
   • <resolved-spec-folder>/action-required.md
   • <resolved-spec-folder>/implementation-log.md
   • docs/design/<resolved-spec-folder-name>/design.md
4. Run the spec preflight:
   • README.md, spec.json, requirements.md, action-required.md, implementation-log.md, tasks/, and the matching design file must exist.
   • spec.json.designPath must equal docs/design/<resolved-spec-folder-name>/design.md.
   • spec.json.specPath must equal docs/specs/<resolved-spec-folder-name>.
   • spec.json.implementationLogPath must equal docs/specs/<resolved-spec-folder-name>/implementation-log.md.
   • spec.json.allowedTaskStatuses must contain exactly the status values listed above.
   • The README Design link must point to ../../design/<resolved-spec-folder-name>/design.md.
   • Every task linked in README must exist under tasks/.
   • Every task file under tasks/ must be linked from README.
   • Every task in spec.json.tasks[] must point to an existing task file.
   • Every task file under tasks/ must be represented in spec.json.tasks[].
   • Every task file must contain ## Status with one of the allowed status values.
   • Every task file must contain ## Wave with a positive integer.
   • Every task file must contain ## Verification Plan, ### RED, ### GREEN, and ### Final Verification.
   • README checkbox state, task file status, and spec.json.tasks[].status must agree.
   • Task file IDs must be unique.
   • Tasks in the same wave must not overlap in spec.json.tasks[].files.create or spec.json.tasks[].files.modify.
   • If any check fails, stop and report the exact files to fix before dispatching agents.
5. Parse spec.json.tasks[] as the source of truth for task IDs, waves, statuses, dependencies, file ownership, and verification commands.
6. Determine the current wave: the first wave that has any task whose status is not complete.
7. If all tasks in all waves are complete, report "All tasks complete!" and stop.

This makes the skill resumable. If invoked on a partially completed spec, it picks up exactly where the manifest says it left off.

Step 2: Process Each Wave

For each wave starting from the current one, execute Steps 3 through 9 below, then advance to the next wave.

Before starting a wave, append a dated entry to implementation-log.md with the wave number, task IDs, starting statuses, and planned verification commands.

Step 3: Prepare Wave Tasks

1. Read all incomplete task files for this wave from the tasks/ subfolder.

2. Confirm every task dependency in dependsOn has status complete. If not, mark the task blocked, update README/task file/manifest consistently, append the blocker to implementation-log.md, and stop.

3. Check for file overlaps from spec.json.tasks[].files.create and spec.json.tasks[].files.modify across all incomplete tasks in this wave. If any file appears in more than one task, warn the user:

   Warning: File overlap detected in Wave {N}:
   - {file-path} is owned by both task-{nn} and task-{mm}
   
   Options:
   1. Proceed anyway with conflict risk
   2. Run these tasks sequentially instead of in parallel
   

   Wait for the user's decision before proceeding.

4. Update each dispatched task to in-progress in spec.json, its task file, and README checkbox state. Append the assignment to implementation-log.md.

Step 4: Dispatch Coder Agents

Host Adapter

Before dispatching, choose the host adapter:

Host	Coder dispatch	Simplifier dispatch	Review dispatch
Claude Code	Task tool with the strongest available coding/general agent	Task tool with s-kit-code-simplifier when available, otherwise the simplifier prompt	Task tool with a review-focused prompt
Copilot CLI	task with agent_type: "general-purpose" unless a coding-specific type exists	task with agent_type: "general-purpose" and the simplifier prompt	task with agent_type: "general-purpose" and the review prompt
Codex with multi-agent enabled	spawn_agent for each coder prompt, then wait for all spawned agents	spawn_agent once with the simplifier prompt	spawn_agent once with the review prompt
No subagent tool	Report the limitation and ask whether to execute the wave sequentially in the current session	Run the simplification pass sequentially only if the user chose current-session execution	Report the limitation and ask whether to execute the wave sequentially in the current session

For each incomplete task in the wave, spawn one coder agent using the selected host adapter. Spawn all coder agents for the wave in a single message when the host supports parallel dispatch.

Read references/coder-prompt-template.md and construct each agent's prompt by filling in:

• {requirements}: full text of requirements.md
• {design}: full text of the matching docs/design/YYYY-MM-DD-{feature-name}/design.md
• {spec_manifest}: the relevant spec.json task entry and global paths/status rules
• {completed_tasks_summary}: for each previously completed task, a one-paragraph summary of what was implemented and what files were created/modified
• {task_content}: full text of the task file being assigned

The coder agents should not commit their changes.

Step 5: Collect Results

Wait for all coder agents in the wave to complete. Each agent should report:

• Files created
• Files modified
• Verification commands run, with results
• A summary of what was implemented
• Final task status recommendation: complete, blocked, needs-context, or done-with-concerns
• Any concerns, skipped checks, or follow-up needed

If any agent fails, returns an error, or reports missing context, set that task to needs-context or blocked as appropriate, update spec files consistently, append the outcome to implementation-log.md, and continue collecting remaining results. Report unresolved failures before review.

Step 5A: Simplification Pass

After coder or fix agents complete and before review, run one behavior-preserving simplification pass for the current wave.

1. Build the changed-file scope from the latest coder or fix completion reports and the current wave's spec.json.tasks[].files.create and spec.json.tasks[].files.modify entries. Restrict the simplifier to this set. If an agent reports no changed files, use that task's manifest file ownership as the fallback scope.
2. Spawn one simplifier agent using the selected host adapter. Prefer the named s-kit-code-simplifier agent when the host supports bundled agents. Otherwise, read references/simplifier-prompt-template.md and construct the prompt by filling in:
   • {wave_number}: current wave number
   • {requirements}: full text of requirements.md
   • {design}: full text of the matching docs/design/YYYY-MM-DD-{feature-name}/design.md
   • {task_summaries}: for each task in this wave, the task title, manifest entry, task file content, files created/modified, verification evidence, and coder or fixer completion summary
   • {changed_files}: the exact changed-file scope for this wave
   • {verification_commands}: the targeted commands from spec.json.tasks[].verificationCommands plus any affected project-level lint, typecheck, or test commands
3. The simplifier may edit only files in the changed-file scope and may return no-op when the implementation is already clear. It must preserve behavior, avoid unrelated fixes, and rerun relevant verification after edits.
4. Collect the simplifier result and append its status, files modified, simplifications, verification evidence, and concerns to implementation-log.md.
5. Include the coder or fixer completion summary, simplifier summary, and simplifier verification evidence in the task summaries passed to later review agents.
6. If the simplifier reports blocked, fails verification, changes behavior, or edits outside the changed-file scope, set the affected tasks to review-failed, append the details to implementation-log.md, and go to Step 7.

Step 6A: Spec Compliance Review

Spawn a single review agent using the selected host adapter.

Read references/review-prompt-template.md and construct the prompt with {review_type} set to Spec Compliance. Fill in:

• {wave_number}: current wave number
• {requirements}: full text of requirements.md
• {design}: full text of the matching docs/design/YYYY-MM-DD-{feature-name}/design.md
• {task_summaries}: for each task in this wave, the task title, manifest entry, task file content, coder or fixer completion summary, simplifier summary, and simplifier verification evidence
• {verification_commands}: the targeted commands from spec.json.tasks[].verificationCommands

The review agent should verify:

1. The implementation matches the approved design.
2. Each task meets its Technical Details, Verification Plan, and Acceptance Criteria.
3. Each task stayed within scope and did not add unrelated behavior.
4. Manual action assumptions match action-required.md.
5. The manifest, task file status, and README checkbox updates are consistent.
6. The simplification pass stayed within the changed-file scope and did not alter approved behavior.

Return a structured verdict: PASS or FAIL with specific issues grouped by task.

If this review fails, do not run code-quality review yet. Set affected tasks to review-failed, append the verdict to implementation-log.md, and go to Step 7.

Step 6B: Code Quality Review

Run this only after simplification and spec-compliance review pass.

Spawn a single review agent using the selected host adapter and the same references/review-prompt-template.md, with {review_type} set to Code Quality.

The review agent should:

1. Run the listed verification commands and report results. Fix nothing.
2. Check integration across task outputs: imports, types, module boundaries, configuration, environment assumptions, and generated artifacts.
3. Check maintainability, simplicity, security, performance, error handling, and adherence to project conventions.
4. Check that no hidden branding/path cleanup regressions or workflow invariant regressions were introduced when the repo has those checks.

Return a structured verdict: PASS or FAIL with specific issues grouped by task.

If this review fails, set affected tasks to review-failed, append the verdict to implementation-log.md, and go to Step 7.

Step 7: Fix Loop

If Step 5A fails or either review returns FAIL:

1. Parse the issues from the simplifier result or review: source, file paths, descriptions, severity, and suggested fixes.
2. Group issues by the task they most closely relate to, using spec.json.tasks[].files.create and spec.json.tasks[].files.modify.
3. For each group, spawn a coder agent with a fix prompt. Read references/fix-prompt-template.md and fill in:
   • {issues}: the specific issues for this task group, including whether they came from simplification, spec-compliance review, or code-quality review
   • {task_content}: the original task file for context
4. After fix agents complete, append the fix result to implementation-log.md.
5. Re-run Step 5A, then Step 6A. Only run Step 6B after Step 5A and Step 6A pass.

Cap at 3 simplification/review cycles per wave. If the third cycle still fails, stop and report to the user:

Wave {N} review failed after 3 cycles. Outstanding issues:
{list of remaining issues}

Options:
1. Fix these manually and re-run /build-feature
2. Proceed to the next wave anyway
3. Stop here

Step 8: Complete the Wave

After both reviews pass, or the user explicitly chooses to proceed:

1. Update task files: for each accepted task, change the Status field to complete; if proceeding with concerns, use done-with-concerns.

2. Update spec.json.tasks[].status to match each task file.

3. Update README.md checkboxes: [x] only for complete; [ ] for all other statuses.

4. Append the simplification result, spec-compliance verdict, code-quality verdict, verification evidence, and final task statuses to implementation-log.md.

5. Commit policy: do not commit if the user asked not to commit. Otherwise, follow the repository's delivery instructions for commits.

6. Report wave completion:

   Wave {N} of {total} complete.
   
   Tasks completed:
   - task-{nn}-{name}: {one-line summary}
   - task-{mm}-{name}: {one-line summary}
   
   Spec compliance review: PASS
   Simplification: {status}
   Code quality review: PASS
   Commit: {hash or "not committed by request"}
   
   Next: Wave {N+1} has {count} tasks ready for parallel execution.
   

Step 9: Final Integration Review

After all waves are complete:

1. Run project-level verification one final time.
2. Spawn a spec-compliance review agent for the full feature scope.
3. Spawn a code-quality review agent for the full feature scope only if spec compliance passes.
4. Append final verification commands, review verdicts, and any residual concerns to implementation-log.md.
5. Report the final status:

Feature "{feature}" implementation complete.

Waves completed: {N}/{N}
Total tasks: {T}

Verification:
- Project verification: {PASS/FAIL}
- Full spec compliance review: {PASS/FAIL with notes}
- Full code quality review: {PASS/FAIL with notes}

Next steps:
- Review the changes
- Push and create a PR when ready

Error Handling

• Coder agent failure: mark the task as needs-context, blocked, or review-failed depending on the failure. Report to the user and append the event to implementation-log.md.
• Dependency not complete: mark the dependent task as blocked, report the missing dependency, and stop before dispatching the wave.
• Verification failure after fix attempts: report the specific errors and ask the user whether to commit anyway or fix manually.
• All tasks already complete: report completion and stop.
• Missing spec folder: ask the user to provide the feature name or suggest creating a spec with plan-feature.
• Ambiguous undated spec name: list all matching dated spec folders and ask the user to choose one.
• Preflight failure: report the failing invariant and stop before dispatching agents.

Key Principles

• The orchestrator does not write code when subagents are available. Its job is dispatch, review, and progress tracking. If the current environment has no subagent tool, report that limitation and execute tasks sequentially in the current session only when the user explicitly asks to continue.
• spec.json is the orchestration contract. README checkboxes and task file status fields mirror it.
• Each coder agent gets exactly one task. This keeps each agent's context focused and manageable.
• Completed task summaries are brief. One paragraph per task, not the full file contents. This keeps coder agent prompts from growing unbounded as waves progress.
• Review is two-stage. Spec compliance catches "built the wrong thing" before code-quality review spends time on implementation quality.
• Progress is append-only in implementation-log.md. The log records what happened, what was verified, what failed, and what was accepted.