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 /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 /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 using EnterPlanMode. 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 /spec:drive): plan-mode approval is an interactive gate — it hangs an unattended /goal loop. So when this skill is invoked by /spec:drive under a goal, or with an explicit auto token in the arguments, the goal itself is the standing approval: skip EnterPlanMode 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 /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 /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.