subagent-driven-development

Subagent-Driven Development

An orchestration pattern for executing multi-task implementation plans by dispatching one fresh subagent per task, reviewing each task through two gates (spec compliance, then code quality), and advancing only after both gates pass. The orchestrator stays lean - it coordinates, briefs, reviews, and hands off. It never implements.

Core Principles

Principle	Meaning
One fresh agent per task	Each task gets a new subagent with curated context. No inherited conversation history, no accumulated drift. The agent sees only what the brief provides.
Two-stage review	Every task passes through spec compliance (does it match the brief?) and then code quality (is it correct, clean, and tested?). Both must pass before advancing.
Structured hand-offs	When task N produces artifacts that task N+1 needs, pass a compressed summary (diff, test manifest, notes) - never raw conversation history.
Orchestrator stays lean	The orchestrator reads the plan, dispatches agents, reviews output, and decides next steps. It does not implement, debug, or accumulate working-memory bloat.
Fail fast, fix forward	When a review gate fails, return specific feedback to the subagent for a focused fix cycle. After two failed fix attempts, re-scope or escalate - do not loop indefinitely.

When to Use

Situation	Why this pattern fits
Written plan with 3+ sequential tasks	Each task benefits from isolated execution and a review checkpoint
Tasks that build on each other (feature branches, migrations)	Structured hand-offs prevent context corruption between steps
Long implementation sessions that risk context exhaustion	Fresh agents per task keep each execution window small and precise
Quality-sensitive work requiring audit trails	Two-stage review produces documented accept/reject decisions per task
Delegating to less capable models for mechanical work	Tight briefs and review gates compensate for reduced reasoning capacity

When NOT to Use

Situation	Better alternative
Single task or trivial change	Direct execution - the overhead of briefing and review is not justified
Fully independent tasks with no ordering dependency	dispatching-parallel-agents - fan them out simultaneously
Exploratory or research work with unclear scope	Manual iteration - you need to discover the shape before you can brief it
Tasks that require deep shared state across every step	Single long-running session with periodic checkpoints
Fewer than 3 tasks	Execute directly and self-review - the ceremony exceeds the value

The Loop

Execute one task at a time through this seven-phase cycle. The orchestrator drives each phase.

Phase 1: Brief the Subagent

Compose a task brief containing everything the subagent needs to execute independently. The brief is the subagent's entire world - anything not in the brief does not exist for it.

Include:

• Task identifier and goal (one sentence)
• Input artifacts (file paths, interface signatures, test fixtures)
• Context from prior tasks (hand-off summary, not full history)
• Acceptance criteria (observable, testable conditions)
• Out-of-scope boundaries (what the agent must NOT touch)
• Failure handling instructions (what to do when stuck)

See Task Brief Template for the full structure.

Phase 2: Dispatch with Isolation

Launch the subagent with a fresh context window. Provide the brief as the initial prompt. If the platform supports worktree isolation, use it - the subagent should not be able to corrupt the main working tree.

Key rules:

• Never paste the full plan into the subagent - only the current task brief
• Never let the subagent inherit the orchestrator's conversation history
• Preload only the skills the subagent needs for this specific task

Phase 3: Receive Artifacts

The subagent completes work and reports back with one of four statuses:

Status	Orchestrator action
Done	Proceed to Stage 1 review
Done with concerns	Read concerns, assess whether they affect correctness or scope, then proceed to review
Needs context	Provide the missing information and re-dispatch (do NOT guess on the subagent's behalf)
Blocked	Assess the blocker - provide context, re-scope the task, or escalate to a human

Phase 4: Stage 1 Review - Spec Compliance

Verify that the output matches the brief's acceptance criteria. This is a mechanical check: does the artifact do what was asked?

Checklist:

• Every acceptance criterion from the brief is satisfied
• No out-of-scope changes were introduced
• Files modified match the expected scope
• Tests exist for the specified behavior
• No unrelated regressions in the test suite

If Stage 1 fails: return specific findings to the subagent with the failing criteria. The subagent fixes and resubmits. After two failed attempts, re-scope the task or escalate.

See Review Rubric for the full spec compliance checklist.

Phase 5: Stage 2 Review - Code Quality

Once spec compliance passes, evaluate the quality of the implementation. This is a judgment call: is the code correct, clean, and maintainable?

Checklist:

• Correctness beyond the spec (edge cases, error handling, concurrency)
• Code style and conventions match the project
• No code smells (duplication, long methods, feature envy)
• Security considerations addressed (input validation, injection prevention)
• Performance is reasonable (no N+1 queries, no unbounded allocations)
• Tests are meaningful (behavior-focused, not implementation-coupled)

If Stage 2 fails: return prioritized findings. Critical issues must be fixed. Suggestions can be deferred if the orchestrator judges them non-blocking.

See Review Rubric for the full quality checklist.

Phase 6: Decide

The orchestrator makes one of three decisions:

Decision	When	Action
Accept	Both review stages pass	Mark task complete, proceed to hand-off
Return with feedback	Review found fixable issues	Send specific feedback, subagent fixes and resubmits for re-review
Abort	Task is fundamentally mis-scoped or blocked	Stop, re-plan the task, or escalate to a human

Never accept with known open issues. Never defer critical findings to "clean up later."

Phase 7: Hand Off to Next Task

Prepare the hand-off summary for the next task's brief. Include only what the next subagent needs:

• What changed (files modified, interfaces added)
• What was tested (test names, coverage scope)
• Decisions made during implementation that affect downstream tasks
• Any deviations from the original plan

See Handoff Patterns for structured hand-off formats.

---

Task Brief

A task brief is the contract between the orchestrator and the subagent. It must be self-contained - the subagent should be able to execute the task using only the brief and the codebase, with no additional conversation.

Essential sections:

1. Task ID and goal - what to accomplish in one sentence
2. Inputs - file paths, interface contracts, test fixtures
3. Context - relevant decisions from prior tasks (hand-off summary)
4. Acceptance criteria - observable conditions that define "done"
5. Out of scope - explicit boundaries on what NOT to change
6. Failure handling - what to do when stuck (report back, do not guess)

See Task Brief Template for the complete template with examples.

---

Two-Stage Review Rubric

The two stages serve different purposes and must not be combined or skipped:

Stage	Purpose	Character
Stage 1: Spec Compliance	Does the output match the brief?	Mechanical - checkable against acceptance criteria
Stage 2: Code Quality	Is the implementation well-crafted?	Judgmental - requires expertise and context

Stage 1 must pass before Stage 2 begins. There is no value in reviewing code quality on an implementation that does not meet its specification.

See Review Rubric for the detailed rubric with severity levels.

---

Handoff Patterns

When tasks have sequential dependencies, the orchestrator must pass structured state from task N to task N+1. The goal is minimal, precise context - not a dump of everything that happened.

Three formats, chosen by dependency depth:

Format	When to use	Contents
Diff summary	Light dependency (new file, new interface)	Changed files, added signatures, test names
Decision log	Design choices affect downstream tasks	Decisions made, alternatives rejected, rationale
Full hand-off	Deep dependency (task N+1 modifies what task N created)	Diff summary + decision log + architectural notes

See Handoff Patterns for templates and examples.

---

Anti-Patterns

Anti-Pattern	Why it fails	Fix
Shared long context	Accumulated conversation history causes drift, hallucination, and contradictions	One fresh agent per task with curated brief
Skipped review gates	Errors compound across tasks, discovered late when fixing is expensive	Both stages are mandatory - no exceptions
"Looks fine" reviews	Without a rubric, reviews are superficial and miss systematic issues	Use the structured rubric for both stages
Oversized tasks	Tasks too large for a single agent to hold in context, leading to partial or incorrect output	Split until each task fits comfortably in one execution window
Pasting the full plan	Subagent is overwhelmed with irrelevant context from other tasks	Provide only the current task brief and hand-off summary
Infinite fix loops	Subagent cannot resolve an issue after repeated attempts, wasting tokens and time	Cap at two fix attempts, then re-scope or escalate
Skipping hand-offs	Next subagent lacks critical context from the previous task, leading to inconsistencies	Always produce a hand-off summary, even when dependency seems light
Orchestrator implements	Orchestrator starts writing code instead of delegating, accumulating context bloat	The orchestrator coordinates. Subagents implement. No exceptions.

See Anti-Patterns for detailed analysis and recovery strategies.

---

Quality Checklist

Before advancing from one task to the next:

• Task brief was self-contained (subagent did not ask for plan-level context)
• Subagent executed with fresh context (no inherited history)
• Stage 1 review confirmed all acceptance criteria are met
• Stage 2 review confirmed code quality standards are satisfied
• All critical and warning findings are resolved (not deferred)
• Tests pass - both new tests and the full existing suite
• Hand-off summary is prepared for the next task
• No out-of-scope changes were introduced
• Orchestrator context remains lean (no implementation details accumulated)

---

Critical Rules

1. One agent, one task. Never reuse a subagent across tasks. Fresh context prevents drift and ensures each task is evaluated on its own merits.

2. Both review stages are mandatory. Spec compliance and code quality serve different purposes. Skipping either one allows a different class of defect to pass through.

3. Stage 1 before Stage 2. Do not review code quality on an implementation that does not meet its specification. Fix the spec gap first.

4. Brief is the contract. If it is not in the brief, the subagent is not responsible for it. Write complete briefs.

5. Cap fix attempts at two. If the subagent cannot resolve an issue after two rounds of feedback, the task scope is wrong or the agent lacks capability. Re-scope or escalate.

6. Orchestrator never implements. The moment the orchestrator starts writing code, it accumulates context that degrades its coordination ability. Delegate everything.

7. Hand-off summaries, not history dumps. Pass compressed, structured state between tasks. The next subagent needs decisions and artifacts, not a transcript of what happened.

8. Fail fast on blockers. When a subagent reports blocked status, address it immediately. Do not queue it for later or hope the next task will unblock it.

9. Scope discipline. Each task should be completable in a single agent session. If it requires multiple sessions, it is too large - split it.

10. Audit trail. Record the accept/reject decision for each review stage on each task. This is your implementation log.

---

Reference Files

Reference	Contents
Task Brief Template	Complete template for per-task subagent briefs with field descriptions and examples
Review Rubric	Two-stage review rubric with checklists, severity levels, and decision criteria
Handoff Patterns	Structured formats for passing state between dependent tasks
Anti-Patterns	Detailed analysis of common failures with detection signals and recovery strategies

Integration with Other Skills

Situation	Recommended Skill
Creating the plan this skill executes	writing-plans
Tasks are fully independent - parallelize instead of sequencing	dispatching-parallel-agents
Stage 2 review technique and structured feedback	requesting-code-review
Verifying task output with evidence before accepting	verification-before-completion
Implementing a task using TDD inside the subagent	testing / design-patterns
Natural dispatch target for implementation tasks	implementer agent
Natural dispatch target for review tasks	reviewer agent
Completing the branch after all tasks pass	finishing-branch