---
name: wf-spec-implement
description: Build a spec: plan the work, implement each item with tests and docs, commit, then finalize. The only skill here that writes production code. Use when the user says "implement spec" or "build spec", or names a spec file to build.
argument-hint: <spec-file> [items to focus on...]
user-invocable: true
---

# 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.

## Step 5: Finalize the spec

How you finalize depends on whether the **whole** spec shipped or only a subset
(focus instructions, deferred/blocked items).

### 5a. Full implementation → delegate to wrap-up

If every item in the spec was implemented, do not hand-roll the completion
write-up here — invoke **`/wf-spec-wrapup <spec-file>`**. It owns the canonical
finalization: driving the spec through the `testing` gate to `complete` (or
`stale` on significant drift) — never a raw `validated → complete` jump — writing
the `## Outcome` section (What Shipped + Design Evolution + the
decisions/surprises/follow-ups detail), updating `specs/README.md`, the
reverse-dependency scan, and the single spec commit. This keeps direct-implement and dispatch converging on one finalizer and
one section convention, instead of two skills writing divergent sections.

Hand wrap-up the knowledge you accumulated this session as the Outcome source —
the commit SHAs, the judgment calls, the deviations from the spec, the gotchas —
so it documents what actually happened rather than reconstructing it from git.
If a deviation made the spec body itself wrong, fix the body inline (wrap-up's
Outcome explains the change; the body must read as current reality).

### 5b. Partial implementation → lightweight in-place notes

If only a subset shipped, do NOT mark the spec complete (that would let wrap-up
close it). Instead:

1. Leave `status` at `validated` (the lifecycle has no `in_progress` /
   `implemented` state — a spec stays `validated` until it goes through `testing`
   to `complete`, which only the full-completion wrap-up does); set `updated` to
   today; record `dispatched_task_id` if this is a dispatched leaf.
2. Append an `## Implementation notes` section capturing the running state, with
   tight bullets (omit a subsection only if genuinely empty):
   - **Status** — commit SHAs/PR, date, and that the spec is *partially* done.
   - **What was done** — concrete changes that shipped, grouped by area
     (backend / frontend / docs / tests), linking primary files or commits.
   - **What was not done** — spec items skipped/deferred/descoped, each with
     *why* (out of scope this pass, blocked by X, user deferred, found
     unnecessary) and whether a follow-up is expected.
   - **Decisions made during implementation** — choices not spelled out in the
     spec (naming, error semantics, defaults, schema shapes, ordering, UX
     micro-details, test strategy), each with its reasoning. Most valuable
     subsection — captures judgment that would otherwise be lost.
   - **Deviations from the spec** — where the implementation intentionally
     differs (signatures, renamed fields, reordered/removed/added items); what
     the spec said vs. what was done, and why. Fix a now-wrong spec body inline.
   - **Surprises / gotchas** — hidden coupling, fragile assumptions, perf
     cliffs, test-infra quirks, undocumented external behavior.
   - **Follow-ups** — concrete next steps not done here; link new specs/issues,
     or write "None."
3. Update the `specs/README.md` status column to the in-progress state and run
   the reverse-`depends_on` scan for factual corrections to dependents only.
4. Commit the spec + README updates as one small commit
   (e.g., `specs: record partial progress on <spec-name>`).

Run `/wf-spec-wrapup` later, once the remaining items land, to do the full
completion write-up.

## Step 6: Summary

Report to the user:
- What was implemented (list of commits with one-line descriptions)
- What was deferred or skipped (if any), and why
- Any follow-up work or known limitations
- Whether the spec is now fully done or if items remain

## Guidelines

- **Read before writing** — never modify a file you haven't read in this session.
- **One logical change per commit** — don't bundle unrelated changes.
- **No over-engineering** — implement exactly what the spec says. Don't add
  features, abstractions, or configurability beyond what's specified.
- **Ask when ambiguous** — if the spec is unclear or contradicts the codebase,
  ask the user rather than guessing.
- **Preserve existing patterns** — follow the repository's instruction files
  and the surrounding code rather than importing conventions from another
  project.
- **Follow the repository checklist** — include the tests, docs, and review
  steps required by the project being changed.