Wf Spec Implement

Implement a Spec

Implement the design spec at $ARGUMENTS. The first token is the spec file path (e.g., specs/04-file-explorer.md). Remaining tokens are optional focus instructions — if provided, implement only the specified items/sections instead of the full spec.

Step 0: Parse arguments and read the spec

1. Extract the spec file path (first token of $ARGUMENTS).
2. Read the spec file in full. If the path doesn't exist, check specs/ for a matching filename.
3. Parse YAML frontmatter — extract structured fields between --- fences: title, status, depends_on, affects, effort, created, updated, author, dispatched_task_id. These drive readiness checks and completion updates below.
4. Read specs/README.md to understand where this spec sits in the track organization and dependency graph.
5. Extract any focus instructions from the remaining tokens.

Step 1: Assess readiness

Before writing any code, verify:

1. Spec lifecycle gate — check the frontmatter status field:
   • validated → ready to implement. Proceed.
   • drafted → warn the user that the spec has not been reviewed/validated. Ask whether to proceed anyway.
   • vague → stop. The spec is not ready for implementation.
   • testing → the implementation already landed and the drift verdict is pending. Do not re-implement; run /wf-spec-wrapup to render the verdict.
   • complete → already done. Confirm with the user before re-implementing.
   • stale → warn the user the spec may not match reality. Suggest /wf-spec-refine first.
2. Dependencies are met — read the depends_on list from frontmatter. For each dependency path, read that spec's frontmatter and confirm its status is complete. If any dependency is not complete, report which ones block this spec and ask the user how to proceed.
3. Spec is current — use the affects list from frontmatter to locate the relevant code files. Skim the spec for file paths, function names, and API references. If any look stale, update them (or flag to the user) before proceeding.
4. No conflicts — run git status to confirm the working tree is clean. If dirty, ask the user how to proceed.

Step 2: Build a plan

Break the spec into an ordered list of implementation tasks. For each task:

• State what will be built or changed
• List the files that will be created or modified
• Note any test files needed
• Note any doc files that need updating

Present this plan to the user for approval (in Claude Code, through plan mode). Group tasks into logical commits (small, focused). Order tasks so each commit leaves the project in a working state.

Wait for user approval before proceeding. The user may adjust scope, reorder items, or skip sections.

Autonomous mode (goal-driven / driven by /wf-spec-drive): plan-mode approval is an interactive gate — it hangs an unattended /goal loop. So when this skill is invoked by /wf-spec-drive under a goal, or with an explicit auto token in the arguments, the goal itself is the standing approval: skip plan mode and the approval wait, and go straight to Step 3. Stay conservative — keep commits small, and if the plan turns out ambiguous, risky, or larger than a single focused leaf, stop and report (surfacing it to the goal loop / user) rather than guessing. Reserve autonomous mode for leaf specs you can build in one pass; anything needing real design judgment should still pause for a human.

Step 3: Implement

For each task in the approved plan:

3a. Write the code

• Read all files you plan to modify before changing them.
• Discover the repository's working agreements and commands from files such as AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README.md, package manifests, build files, and CI workflows. Treat the live repository as authoritative.
• Follow existing code patterns — match style, naming, error handling, and structure of surrounding code.
• Keep changes minimal and focused on what the spec requires.
• When changing a generated surface, find and edit its source of truth, then run the repository's documented generation command.

3b. Write tests

• Follow the repository's test framework, placement, naming, and coverage conventions.
• Every new or changed behavior must have a focused test. Every bug fix needs a regression test that fails without the fix.
• Cover the happy path and relevant error or boundary cases in proportion to the change's risk.

3c. Verify

After implementing each task, run the repository's documented gates in this order where they exist:

1. Format and lint the changed files.
2. Run the smallest relevant test target for fast feedback.
3. Run the broader test suite required by the repository.
4. Run build, type-check, generation-drift, or static-analysis checks required by the affected area.
5. Fix every failure before moving on. If no command is documented, infer it from package manifests and CI, then report the command you chose.

3d. Update docs

If the task adds, removes, or modifies any API route, CLI flag, env variable, data model field, or user-visible behavior:

• Update the repository's relevant user guide or reference page.
• Update architecture or internals documentation when internal contracts changed.
• Update repository instruction files when commands or conventions changed.

3e. Commit

• Stage only the files for this task.
• Write a scoped, imperative commit message matching the repo style (e.g., api: add file content endpoint).
• Do NOT push unless the user explicitly asks.

3f. Update progress

After each commit, mark the completed task done and show the user a brief status update: what was done, what's next.

Step 4: Final verification

After all tasks are implemented, run the full verification set required by the repository, including its test suite and build or type-check command where they exist. If any gate fails, diagnose and fix it before finishing.