implement-spec

name	implement-spec
description	Implement a design spec from specs/ — reads the spec, plans the work, implements each item with tests and docs, then commits. Use when the user says "implement spec", "build spec", or references a spec file to implement.
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, track, 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.
   • 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 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.

Step 3: Implement

For each task in the approved plan:

3a. Write the code

• Read all files you plan to modify before changing them.
• Follow existing code patterns — match style, naming, error handling, and structure of surrounding code.
• Keep changes minimal and focused on what the spec requires.
• For new API routes: add them to internal/apicontract/routes.go first, then run make api-contract to regenerate the JS route file.

3b. Write tests

• Every new or changed behavior must have tests.
• Backend: add Go tests in the same package (_test.go files).
• Frontend: add tests in ui/js/__tests__/ using vitest.
• Tests must cover the happy path and at least one error/edge case.

3c. Verify

After implementing each task:

1. Run make fmt and make lint — fix any issues.
2. Run go vet ./...
3. Run go test ./... for backend changes.
4. Run make test-frontend for frontend changes.
5. Fix any failures before moving on.

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 relevant guide in docs/guide/.
• Update docs/internals/ if internal architecture changed.
• Update CLAUDE.md if new routes, env vars, or conventions were added.

3e. Commit

• Stage only the files for this task.
• Write a scoped, imperative commit message matching the repo style (e.g., internal/handler: 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:

1. Run the full test suite: make test
2. Run make build to confirm the binary builds cleanly.
3. If any tests fail, diagnose and fix before finishing.

Step 5: Update specs and epic index

After all tasks are implemented (or partially implemented if focus instructions were given), update the spec file, related specs, and the epic index:

5a. Update the implemented spec frontmatter and body

1. Update frontmatter status — set to complete (or leave at validated and add a note if only focused items were implemented).
2. Update updated date — set to today's date.
3. Update dispatched_task_id — if this is a leaf spec dispatched to the board, ensure the task ID is recorded.
4. Document deviations — if the implementation differs from what the spec prescribed (different signatures, renamed fields, extra/fewer methods, reordered steps, skipped items, etc.), add an ## Implementation notes section at the end of the spec documenting each deviation:
   • What the spec said vs. what was actually done
   • Why the deviation was necessary (codebase constraint, user decision, discovered during implementation, etc.) If the implementation matched the spec exactly, omit this section.

5b. Update specs/README.md

1. Read specs/README.md.
2. Update the Status column for this spec's row (e.g., Not started → **Complete**, or **In progress** (N/M tasks done)).
3. If the implementation changes any dependency relationships, ordering rationale, or milestone descriptions, update those too.

5c. Update related specs (reverse dependency / impact analysis)

Check whether the implementation affects other specs:

1. Reverse depends_on scan — grep all spec files for depends_on entries that reference this spec's path. These are the specs that depend on this one. If this spec is now complete, those dependents may be unblocked.
2. If this spec introduces or changes interfaces that downstream specs reference (e.g., new types, new API routes, renamed fields), update those specs to reflect the actual implementation.
3. If another spec lists this one in depends_on and the dependency is now satisfied, note that the dependent is unblocked.
4. Only make factual corrections — do not redesign other specs.

5d. Commit

Commit all spec and index updates together as a single small commit (e.g., specs: mark 01-sandbox-backends as complete, update README).

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 — match the conventions in CLAUDE.md and the surrounding code. This project uses stdlib net/http (no framework), vanilla JS (no framework), and per-task directory storage.
• Follow the implementation checklist — every task must have tests, docs, and a quick refactoring pass (per CLAUDE.md).