Subagent driven development

Subagent-Driven Development

Dispatch fresh subagent per task with two-stage review after each.

Core principle: Fresh subagent per task + two-stage review (spec then quality) + diff-based validation = high quality, fast iteration

Quick Reference

Phase	Actor	Action	Exit Condition
1	Controller	Read plan, extract tasks, capture BASE_SHA, create task list	All tasks tracked with BASE_SHA
2	Subagent	Implement (templates/implementer.md)	Commit exists + tests pass + report includes HEAD_SHA
3	Subagent	Spec review (templates/spec-reviewer.md)	Reviewer checked diff(BASE..HEAD) and returned ✅ or file:line issues
4	Subagent	Quality review (templates/code-quality-reviewer.md)	Reviewer approved diff or returned severity-tagged issues
5	Controller	Update state, mark complete, loop to step 2	All tasks done
6	Subagent	Final review of entire implementation	Approved
7	Controller	Use finishing-a-development-branch	Branch complete

Task Contract

Every task must satisfy these constraints:

Scope:

• One task = one commit (or tight commit stack)
• No drive-by refactors; no formatting churn
• No unrelated file changes

Verification:

• All tests pass (run full suite or affected subset)
• Lint/typecheck pass (if applicable)
• Commands actually executed (not assumed)

Report must include:

• BASE_SHA (from controller)
• HEAD_SHA (after commit)
• Commands run (exact, copy-pasteable)
• Test output summary (pass/fail + counts)
• Files changed (list)
• Scope confirmation ("No unrelated changes")

State Tracking

Controller maintains per-task record:

{
  task_id: string,
  base_sha: string,      # Captured before implementer starts
  head_sha: string,      # From implementer report after commit
  status: pending|in_progress|spec_review|quality_review|complete,
  spec_review_cycles: number,
  quality_review_cycles: number
}

Update state after each phase transition.

Process

Setup (Once)

1. Read plan file once
2. Extract all tasks with full text and context
3. Capture current HEAD as BASE_SHA for first task
4. Create task list with all tasks (status: pending)

Per Task Loop

1. Record BASE_SHA for this task (current HEAD)
2. Dispatch implementer with full task text + context + BASE_SHA
3. If questions: Answer completely, re-dispatch with answers
4. Implementer completes: implements, tests, commits, reports HEAD_SHA
5. Update state: Record HEAD_SHA, set status to spec_review
6. Dispatch spec reviewer with task requirements + diff(BASE_SHA..HEAD_SHA)
7. If spec issues: Implementer fixes → spec reviewer re-reviews → increment cycle count → repeat until ✅
8. Update state: Set status to quality_review
9. Dispatch code quality reviewer with BASE_SHA, HEAD_SHA
10. If quality issues: Implementer fixes → quality reviewer re-reviews → increment cycle count → repeat until ✅
11. Update state: Set status to complete, BASE_SHA for next task = current HEAD_SHA

Completion

1. Dispatch final code reviewer for entire implementation (first BASE_SHA to final HEAD_SHA)
2. Use finishing-a-development-branch skill

Prompt Templates

• templates/implementer.md — Implementation subagent
• templates/spec-reviewer.md — Spec compliance verification (diff-based)
• templates/code-quality-reviewer.md — Code quality assessment (diff-based)

See references/example-workflow.md for complete walkthrough with SHA tracking.

Red Flags

Never:

• Skip reviews (spec compliance OR code quality)
• Proceed with unfixed issues
• Dispatch parallel implementers in same working tree (conflicts)
• Make subagent read plan file (provide full text)
• Skip BASE_SHA/HEAD_SHA tracking
• Let reviewers assess "the repo" instead of the specific diff
• Accept reports without required fields (SHA, commands, test output)

Parallel clarification: "Parallel sessions" (separate branches/worktrees) is fine via executing-plans. "Parallel implementers" touching same working tree is forbidden.

If subagent asks questions: Answer clearly and completely before they proceed.

If reviewer finds issues: Implementer fixes → reviewer re-reviews specific diff → repeat until approved.

If implementer discovers required refactor: Stop, report to controller, request plan amendment. Don't bulldoze.

Dependencies

Requires: writing-plans (creates the plan)

Subagents use: test-driven-development, requesting-code-review (template)

Completes with: finishing-a-development-branch

Alternative: executing-plans (for parallel sessions/branches, not parallel implementers)

Environment notes: This skill assumes availability of: git (for SHA tracking), a task list tool (TodoWrite or equivalent), and ability to dispatch subagents. Adapt tool names to your environment.