/subagent-driven-development

name: subagent-driven-development
description: Sequential subagent execution with two-stage review gates for implementation plans. Use when executing multi-task plans in current session, when tasks need fresh subagent context to avoid pollution, when formal review cycles (spec compliance then code quality) are required between tasks, or when you need diff-based validation of each task before proceeding.

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.