implement

name	implement
description	Implement a technical design by decomposing it into dependency-ordered vertical slices, executing each with TDD red-green, reviewing each via an isolated sub-agent, and persisting progress to a state file so work survives session restarts. Use when the user has a tech design (doc or settled conversation) and says "implement", "start building", "let's code this", "实现吧", "开始实现", "按这个方案做", "把设计落地".

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.

Verify external contracts before writing boundary code

Any code that talks to something outside this repo — an HTTP/RPC API, a DB column, a wire format — must be verified against ground truth before the struct or query is written, and the evidence shown (file:line or fetched doc, with the verbatim field names):

• External API: read an existing client of the same service in this codebase, or the upstream handler/spec itself. Prose descriptions in the design doc are not evidence — they rot.
• DB column comparisons: grep the WRITE path (where the column is assigned), not just the read path. A filter that compares a column to a value no writer ever stores compiles, passes unit tests against fake data, and matches zero rows in production.
• If no ground truth can be found, STOP and flag it rather than guess — wrong contracts pass mocked tests and fail only in production.

Review (every slice, non-negotiable)

After a slice's code is complete, dispatch an isolated reviewer with the code-review skill's sub-agent pattern: zero conversation context, given only the git range, the design doc path, what the slice claims to do, and any intentional deviations (so they aren't re-reported). Ask it to check correctness, races, conventions, tests, security, and design compliance, with severity-ranked findings.

Then: verify each finding before acting — reviewers are sometimes wrong; push back with technical reasoning when they are. Fix Critical now, Important before the next wave, Minor if cheap. Record the review summary in the state file. No performative agreement — fix and show the result.

Deviation rules

Situation	Action
Bug found while implementing	Fix now, note in the slice report
Design is missing a small detail	Decide, implement, note it
Environment/dependency blocker	Work around, note it, surface at the checkpoint
Architectural change (new boundary, changed contract/schema)	STOP and ask the user

Update the design doc in the same branch when the implementation legitimately diverges — the doc describes current state, and a doc that lies is worse than no doc.

Phase 3 — verification before the PR

Four levels, in order:

1. Exists — everything the design names is present.
2. Substantive — no stubs: scan the diff for empty bodies, panic("unimplemented"), tests without assertions, leftover TODOs.
3. Wired — every new surface is reachable: handlers registered, tools advertised, hooks attached, config read. Unwired code is a bug.
4. Functional — the project's full test suite (with the race detector if it's a Go project), formatter, and vet/linter all clean; every acceptance criterion from Phase 1 checked off. Where feasible, one real end-to-end smoke (run the binary, hit the endpoint, observe the behavior) — unit-green is not the same as works.

Then: push the branch, open a PR whose description covers what landed, review findings fixed, and deviations from the design. Delete the state file. Report: slices completed, tests added, review findings (any patterns?), deviations, anything left for manual verification.

Key principles

• Vertical over horizontal; tracer bullet first; learn before fanning out.
• One behavior = one commit; review every slice; verify, don't trust.
• The state file is always current — any session can crash and resume.
• Auto-fix bugs and blockers; stop and ask before architectural change.
• Match the codebase's conventions — comment density, naming, test style — not your own defaults.