/spec-implement

name: spec-implement
description: >
  Continue an approved Spec-backed workflow when the user says "implement", "go", "start", or
  "do it". After Codex Plan Mode, persist the next missing design.md or plan.json artifact and
  stop. When both artifacts exist, execute plan.json with TDD and report between batches.
user-invocable: true

Spec Implement

Execute the approved Spec-backed Plan. Track progress when it uses tracked tasks. Report. Stop when blocked.

**Announce at start:** "I'm using the spec-implement skill to execute this plan."

This skill does not make design decisions or change approved content. It may persist approved content from the conversation when Plan Mode could not write the required artifact. If the plan is wrong, go back to spec-plan. If the design is wrong, go back to spec-brainstorm.

Prerequisites

Resolve required artifacts in order before starting product implementation:

1. If `docs/specs/YYYY-MM-DD-<feature>/design.md` is missing, write it from the approved design in the current conversation. Validate the file, report its path, and stop. Do not create `plan.json` or start implementation in the same invocation. 2. Otherwise, if `docs/specs/YYYY-MM-DD-<feature>/plan.json` is missing, write it from the approved plan in the current conversation. Validate it against the schema in `spec-plan`, report its path, and stop. Do not start implementation in the same invocation. 3. If the approved content needed for the next missing artifact is not available in the current conversation, stop and tell the human what content is unavailable. Do not ask the human to create the file. 4. When both artifacts exist, verify that any tracker entries selected during planning are available, along with `docs/agents/issue-tracker.md` when tracking is configured. 5. Verify that you are not on main/master without explicit user consent. Create a branch or use a git worktree first.

Each invocation creates at most one missing artifact. Only proceed to product implementation when both approved artifacts existed at the start of the invocation.

---

Step 1: Load and Review the Plan

Read plan.json critically before writing code. Look for:

• Unclear or ambiguous tasks
• Missing file paths or incomplete validation criteria
• Tasks that conflict with each other
• Dependencies that don't match what you see in the codebase
• Existing code or platform behavior that already satisfies a planned capability
• Duplicate IDs, parsers, errors, schemas, lifecycle handling, or test utilities
• Shared abstractions with fewer than two current consumers
• Tests whose only purpose is validating a new wrapper

If planned machinery fails these checks, stop before implementing it and return to `spec-plan` with a smaller revision for human review. Preserve the approved behavior and scope; do not force an unsupported structure through implementation.

For other concerns, **raise them with the human before starting**. Don't guess. Don't assume. Don't force through blockers.

If no concerns, proceed. Use existing tracker entries when present.

---

Step 2: Choose Execution Style

If the human has not specified an execution style, ask.

Autonomous Mode

> "Implement it all. Don't stop until you're done."

• Execute all tasks in dependency order
• Track progress when the Spec-backed Plan has tracker entries
• Run type checking / linting continuously
• Only stop if blocked

Batched Mode (default)

> "Do a few tasks at a time."

• Execute 3-5 tasks
• Stop and report: what was done, test output, anything unexpected
• Wait for human feedback before continuing

Subagent Mode

> "Use subagents."

• Invoke **code-subagents** for dispatch patterns and review cycle
• Fresh subagent per task — no context pollution
• One combined plan and code-quality review per completed batch
• Independent tasks dispatch in parallel, dependent tasks run sequentially

Default to batched if the human hasn't expressed a preference.

---

Step 3: Execute the Plan

Preserve the approved behavior and scope. Treat the plan's proposed structure as a hypothesis that must remain supported by repository evidence.

For each task, find the next unblocked task directly from `plan.json`. When tracker entries exist, use `docs/agents/issue-tracker.md` to keep their execution state in sync; tracker state never overrides the plan's dependency graph.

When a tracker exists, mark it in progress according to `docs/agents/issue-tracker.md`.

For each task

Read the task's **inputs** and **description** first.

For behavior-changing code tasks, write tests that cover the validation criteria before writing implementation. For documentation, configuration, migration, or verification-only tasks, use the task's stated validation instead. Invoke an installed language-specific testing skill when needed.

1. Read task inputs and description
2. Write failing tests (cover validation criteria)
3. Run them — verify they fail for the RIGHT reason
4. Implement minimal code to make tests pass
5. Refactor if needed (tests stay green)

For behavior-changing code, do NOT write implementation before tests. Do NOT skip "verify it fails." Do NOT write more code than needed to pass the test.

Verify the task against its **validation** and acceptance criteria.

After each batch: Validate and commit

Run the task's focused validation and inspect the local diff for accidental or out-of-scope changes. Report deviations and unexpected findings. Use **code-commit** for any commit; plan approval does not bypass its approval gate. Comprehensive **code-review** happens in **spec-finish**.

On completion

When a tracker exists, mark the task complete according to `docs/agents/issue-tracker.md`.

Referencing existing code

When the plan or human references existing implementations ("make it look like the users table"), read the referenced code before making changes. A reference communicates all implicit requirements w