Implement

Take a technical design and turn it into working, reviewed code — slice by slice, test-first, with progress checkpointed to disk so a new session can resume exactly where the last one stopped.

Inputs

One of:

• A path to a tech design document
• "implement the design" — use the design settled in conversation context

If neither exists, stop and ask for the design first.

State persistence

State file: .octo/implement-state.json in the repository root (create .octo/ if needed; add it to .gitignore if not ignored — the state file is session machinery, never committed).

On startup, always check for this file first.

• Exists → read it, summarize progress, ask: "Found an in-progress implementation. Resume from where we left off?" Resume honors each slice's status; "no" means ask whether to start fresh (overwrite) or abort.
• Missing → start at Phase 1.

{
  "tech_design_path": "path or '(conversation)'",
  "branch": "feat/...",
  "updated_at": "RFC3339",
  "waves": [
    { "wave": 1, "mode": "sequential",
      "slices": [
        { "slice": 1, "title": "...", "status": "pending|in_progress|review|done|skipped",
          "acceptance_criteria": ["..."], "files_owned": ["..."],
          "tests_added": 0, "review_summary": "", "deviations": "", "commit_sha": "" }
      ] }
  ]
}

Update the file on every status transition (slice starts, enters review, done with commit SHA + review summary + deviations). Delete it when everything is done — a clean exit leaves no state behind.

Resuming: done/skipped skip; review re-runs or finishes the review; in_progress checks git log for partial commits and continues from them or restarts the slice; pending starts normally.

Phase 1 — readiness gate, then decompose

Readiness gate. Before slicing, verify the design is concrete enough to code from: every API has method + path + request/response shape, every schema has fields + types, every external call names its counterpart. If something is too vague to implement without guessing, list exactly what's missing and ask the user (use ask_user_question for each decision) — do NOT decompose on top of vague specs; slices built on guesses produce guessed code.

Decompose into vertical slices. Each slice cuts through all layers end-to-end (schema → logic → surface → tests), never a horizontal slab. Group slices into waves by dependency:

• Wave 1 is always a tracer bullet: one thin end-to-end slice that proves the architecture, run inline so its lessons inform the rest.
• Dependencies before dependents; data layer before consumers.
• Slices within a wave must own disjoint file sets — that's what makes a wave parallelizable. If two slices need the same file, different waves.
• Honesty over parallelism: a tightly-coupled feature is often one sequential wave per slice. Say so instead of forcing a fan-out.

Present the breakdown (slice titles, scope, acceptance criteria, wave grouping) and confirm with the user before writing the state file — unless the user has already told you to proceed autonomously.

Phase 2 — execute wave by wave

Branch discipline

Work on a fresh branch off the latest default branch. Never start a new piece of work on a branch whose PR already has auto-merge armed — after a PR is created, the next slice batch gets a new branch.

The TDD cadence (every slice, no exceptions)

(This section is the rhythm. Hold to the usual test-quality bar as you go: test behavior over implementation, mock only what you don't own, and add wire-contract tests for boundary structs.)

For EACH behavior in the slice:

1. Write ONE failing test — actual test code, not a description.
2. Run it; confirm RED (and that it fails for the right reason).
3. Write the minimal implementation.
4. Run it; confirm GREEN.
5. Run the package's full tests; refactor if needed; still GREEN.
6. Commit immediately — one behavior, one commit, bisectable.

Banned in any plan, prompt, or code you produce: "TODO", "TBD", "implement later", "add proper error handling", "similar to slice N", steps that describe WHAT without showing the code. If you can't write the code, the design decision isn't made yet — go back and make it.

Sequential slices (the common case)

Run inline, full cadence above, then review (below), then next slice.

Parallel waves (only when file sets are truly disjoint)

Spawn one sub_agent per slice. Each sub-agent works in its own git worktree — follow the absolute-path rule from the worktree-isolate skill: octo has no session working directory, so every command is git -C "$WT" … / cd "$WT" && … in a single terminal call, and every file tool gets the worktree's absolute path. The sub-agent prompt must be self-contained: slice scope, acceptance criteria, owned files (absolute paths), interface contracts, the design doc path, the TDD cadence, and the deviation rules below — sub-agents have no conversation context.

After a wave: review each slice, merge each worktree branch back, resolve any conflict (a conflict means the slices weren't independent — note it), run the full suite on the merged result.

If sub_agent is unavailable in this session, run the slices sequentially inline and say so.