SKILL.md
Subagent-Driven Development
One fresh implementer subagent per task, a task review after each, one broad whole-branch review at the end. Fresh context per task means no pollution; you stay coordinator and keep your own context for routing decisions, not diffs.
The loop
- Read the plan once. Note global constraints. Create a todo per task. Scan for conflicts: tasks that contradict each other or the constraints. Batch every conflict into one question for the human before Task 1, not one interrupt each mid-run.
- Check the ledger. If
.progress/ledger.mdexists, tasks marked complete are done. Resume at the first unmarked task. Never re-dispatch a completed task. - Per task: a. Extract the task's full text into a brief file. Dispatch an implementer with the brief path, one line of project context, interfaces from earlier tasks, and a report-file path. Never paste the whole plan or prior-task history into the prompt. b. Answer implementer questions before letting it proceed. c. On DONE: generate a diff package (see below), dispatch a task reviewer with the brief, report, and diff paths plus the plan's global constraints copied verbatim. d. Reviewer must return two verdicts: spec compliance and code quality. Critical or Important findings: dispatch a fix subagent with all findings, then re-review. Minor findings: log them in the ledger for the final review to triage. e. On clean review, append to the ledger:
Task N: complete (commits <base>..<head>, review clean). - After all tasks: dispatch one final whole-branch reviewer on the most capable model with the diff from the branch's merge base. If it returns findings, dispatch ONE fix subagent with the complete list, not one per finding.
- Finish the branch: merge or PR per the project's convention.
Read references/dispatch-contracts.md before writing your first dispatch prompt. It defines the implementer and reviewer contracts, the diff-package recipe, and the report-file convention.
Diff packages
Reviewers read one file, not your pasted diff. Record BASE (current commit) before dispatching each implementer, then:
{ git log --oneline BASE..HEAD; git diff --stat BASE..HEAD; git diff -U10 BASE..HEAD; } > /tmp/task-N-review.txtNever use HEAD~1 as BASE. Multi-commit tasks lose everything but the last commit.
Model selection
Use the least capable model that can do the role, and always name the model explicitly in the dispatch. An omitted model inherits your session's, usually the most expensive.
| Work | Model tier |
|---|---|
| Transcription of complete code from the plan, single-file mechanical fixes | Cheapest |
| Implementation from prose, multi-file integration, all reviewers | Mid |
| Design judgment, debugging across the codebase | Standard/high |
| Final whole-branch review | Most capable |
Turn count beats token price: the cheapest models take 2-3x the turns on multi-step work and cost more overall. Cheap tier only when the task is genuinely mechanical.
Implementer statuses
| Status | Your move |
|---|---|
| DONE | Package the diff, dispatch reviewer |
| DONE_WITH_CONCERNS | Read concerns. Correctness or scope concerns: resolve before review. Observations: note and proceed |
| NEEDS_CONTEXT | Provide the missing context, re-dispatch |
| BLOCKED | Context problem: add context. Reasoning problem: stronger model. Too large: split the task. Plan wrong: escalate to the human |
Never retry a BLOCKED subagent unchanged. Something must change: context, model, or task size.
Durable progress
Conversation memory does not survive compaction. Controllers that lost their place have re-dispatched entire completed task sequences, the most expensive failure this workflow has. The ledger file is the recovery map: the commits it names exist in git even when you no longer remember creating them. After compaction, trust the ledger and git log over recollection.
Good vs bad
Bad dispatch: 40k characters of pasted plan, prior task summaries, and "also check all uses of this function anywhere, and don't flag the magic number, the plan chose it." The subagent drowns, and you pre-judged a finding to dodge a review loop.
Good dispatch: "Task 4 of the payments plan. Read /tmp/task-4-brief.md first; it is your requirements with exact values. Task 3 exported applyDiscount(cart: Cart): Cart from src/pricing.ts. Write your full report to /tmp/task-4-report.md; return status, commits, one-line test summary, concerns. Model: mid-tier."
Verification
Before marking any task complete, open the reviewer's report. Expect: spec verdict is a pass, quality verdict is approved, and every "cannot verify from diff" item has been resolved by you against the plan. If any is missing, the task is not complete: dispatch the fix, re-review, and only then write the ledger line.
Completion checklist
- [ ] Working in an isolated workspace, not main
- [ ] Plan conflict scan done before Task 1
- [ ] Every task: fresh implementer, brief file, task review with both verdicts
- [ ] All Critical/Important findings fixed and re-reviewed
- [ ] Ledger line written per completed task
- [ ] Final whole-branch review run on the most capable model
- [ ] Final findings fixed by one fix subagent, not many
Any box unchecked: not done. Fix or say so.
Footguns
- Parallel implementers. Two subagents editing one worktree conflict. Implementation dispatches are sequential, always.
- Fixing reviewer findings yourself. You pollute your coordinator context with implementation detail. Dispatch a fix subagent with the findings verbatim.
- Reviewer prompts that pre-judge. "Do not flag X", "at most Minor", "the plan chose this" all rig the review. Let the reviewer raise it; adjudicate in the loop. A plan-mandated defect is the human's call: present the finding beside the plan text and ask which governs.
- Accepting a fix report without test evidence. Every fix dispatch must name its covering tests and return the command plus output. No evidence, no re-review.
Red flags
- "The tasks are small, I'll skip the per-task review"
- "The implementer said it passed, good enough"
- "I'll just fix this one finding myself, faster than dispatching"
- "Close enough on spec compliance"
- "I'll paste the last three task summaries so it has context"
Each is the same move: trading the gate for speed. The gate exists because subagent reports are claims, not evidence. No verdict pair on file, no completed task, whatever wording the excuse uses.