Subagent-Driven Development

Relevant source files

• skills/executing-plans/SKILL.md
• skills/subagent-driven-development/SKILL.md
• skills/subagent-driven-development/code-quality-reviewer-prompt.md
• skills/subagent-driven-development/implementer-prompt.md
• skills/subagent-driven-development/spec-reviewer-prompt.md

Purpose and Scope

This page documents the subagent-driven-development skill, which executes implementation plans by dispatching fresh subagents per task with two-stage review. This skill enables autonomous execution of independent tasks in the current session, with automated quality gates ensuring both spec compliance and code quality.

For writing the plans that this skill executes, see Writing Implementation Plans. For batch execution with human checkpoints instead, see Executing Plans in Batches. For the overall workflow context, see Complete Workflow Pipeline.

Sources: skills/subagent-driven-development/SKILL.md1-10 README.md11-15

Overview

Subagent-driven development is an execution mode that prioritizes speed and quality through a controller-subagent architecture. The controlling agent reads the implementation plan once, extracts all tasks, then dispatches fresh subagents for each task. After each task completes, two reviewer subagents verify the work: one checks spec compliance, the other checks code quality.

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

This approach differs fundamentally from traditional execution:

• Fresh context per task: Each implementation subagent starts with clean context, preventing confusion from previous tasks
• Automated quality gates: Spec compliance and code quality reviews happen automatically, no human in the loop
• Continuous progress: All tasks execute in the same session without waiting for human review
• Explicit review loops: If reviewers find issues, the implementer fixes them and reviews happen again until approved

Sources: skills/subagent-driven-development/SKILL.md1-11 README.md11-15

When to Use This Skill

Decision Criteria

Use subagent-driven-development when:

• You have an implementation plan (from writing-plans)
• Tasks are mostly independent (can execute in any order)
• You want execution in the current session (no context switch)
• You want automated quality gates (no human review between tasks)

Use executing-plans instead when:

• You need human checkpoints between batches
• You're working in a parallel session (different conversation)
• You prefer manual control over pacing

Don't use either when:

• Tasks are tightly coupled (must execute in specific order)
• Plan doesn't exist yet (brainstorm and plan first)

Sources: skills/subagent-driven-development/SKILL.md12-38

Architecture

Controller-Subagent Model

Key architectural decisions:

1. Controller reads plan once: The controller agent loads the plan file at the start and extracts all tasks. This avoids repeated file reading overhead in subagents.

2. Controller provides full task text: When dispatching subagents, the controller includes the complete task specification plus relevant context. Subagents never read the plan file directly.

3. Fresh subagent per task: Each implementation task gets a new subagent with clean context. This prevents confusion from previous tasks' implementations.

4. Separate reviewer subagents: Spec and quality reviews use distinct subagents, each focused on a single concern. This prevents conflating "does it match the spec?" with "is it well-built?"

5. Review loops: If a reviewer finds issues, the same implementer subagent fixes them (maintaining context), then the reviewer reviews again. This loop continues until approved.

Sources: skills/subagent-driven-development/SKILL.md39-82 skills/subagent-driven-development/SKILL.md167-197

Process Flow

Complete Execution Sequence

Step-by-Step Details

1. Setup Phase

• Controller reads plan file once: skills/subagent-driven-development/SKILL.md96-98
• Extracts all task text and context upfront
• Creates TodoWrite with all tasks for tracking

2. Per-Task Execution

• Controller gets next incomplete task (text already extracted)
• Dispatches implementer subagent with full task specification
• Implementer may ask questions before starting work
• Controller answers questions, providing additional context if needed
• Implementer implements using test-driven-development skill
• Implementer self-reviews before completing
• Implementer commits the work

3. Two-Stage Review

• Stage 1: Spec Compliance - Dispatch spec reviewer subagent with ./spec-reviewer-prompt.md

  • Checks if code matches spec exactly
  • Identifies missing requirements (spec gaps)
  • Identifies extra features not requested (scope creep)
  • If issues found: implementer fixes, spec reviewer reviews again
  • If approved: proceed to stage 2

• Stage 2: Code Quality - Dispatch quality reviewer subagent with ./code-quality-reviewer-prompt.md

  • Checks code quality, best practices, patterns
  • Reports issues by severity (critical/important/minor)
  • If issues found: implementer fixes, quality reviewer reviews again
  • If approved: task complete

4. Task Completion

• Mark task complete in TodoWrite
• If more tasks remain: continue to next task
• If all tasks complete: dispatch final code reviewer for entire implementation

5. Finishing

• Use finishing-a-development-branch skill
• Verify all tests pass
• Choose merge/PR/keep/discard
• Clean up worktree

Sources: skills/subagent-driven-development/SKILL.md39-82 skills/subagent-driven-development/SKILL.md91-165

Prompt Templates

The skill includes three prompt template files that define how subagents are dispatched:

Template Files and Roles

Template File	Role	Dispatched When	Focus
./implementer-prompt.md	Implementation subagent	At start of each task	Write code, follow TDD, self-review
./spec-reviewer-prompt.md	Spec compliance reviewer	After implementation complete	Verify code matches spec exactly
./code-quality-reviewer-prompt.md	Code quality reviewer	After spec review passes	Check best practices, patterns, quality

Prompt file to dispatch mapping (per task):

Sources: skills/subagent-driven-development/implementer-prompt.md1-79 skills/subagent-driven-development/spec-reviewer-prompt.md1-62 skills/subagent-driven-development/code-quality-reviewer-prompt.md1-19

Usage Pattern

Controller dispatches subagent:

Implementer subagent may ask questions:

• Questions must be answered before implementation begins
• Controller provides answers, potentially with additional context
• Once questions answered, implementer proceeds with implementation

Review dispatch includes git context:

Review loops:

• If reviewer finds issues, the same implementer subagent fixes them
• Reviewer reviews again after fixes
• Loop continues until reviewer approves

Sources: skills/subagent-driven-development/SKILL.md85-90 skills/subagent-driven-development/SKILL.md100-165

Two-Stage Review System

Why Separate Spec and Quality Reviews

The two-stage review architecture separates two distinct concerns that often conflict:

1. Spec Compliance Review: "Does this code do exactly what was requested?"

   • Checks: Missing requirements, extra features
   • Binary: spec met or not met
   • First gate: prevents building wrong thing

2. Code Quality Review: "Is this code well-built?"

   • Checks: Best practices, patterns, maintainability
   • Graduated: critical/important/minor issues
   • Second gate: ensures good implementation

Why this order matters: Checking quality before spec compliance wastes effort. If code doesn't match the spec, quality doesn't matter yet. Fix spec compliance first, then ensure quality.

Spec Compliance Review

Spec reviewer focuses on:

• Missing requirements: Does code implement everything specified?
• Extra features: Does code include things not requested? (scope creep)
• Exact match: Code should do what spec says, nothing more, nothing less

Common spec issues:

• Progress reporting missing when spec required it
• JSON flags added when not requested
• Edge cases from spec not handled
• User-facing text doesn't match spec wording

Sources: skills/subagent-driven-development/SKILL.md116-145

Code Quality Review

Quality reviewer focuses on:

• Design patterns: Are appropriate patterns used?
• Best practices: Does code follow language/framework conventions?
• Maintainability: Magic numbers, duplication, naming, structure
• Test coverage: Are tests comprehensive?

Common quality issues:

• Magic numbers (should be constants)
• Code duplication (should be extracted)
• Unclear naming
• Missing error handling
• Test gaps

Issue severity levels:

• Critical: Must fix before approval (security issues, data loss risks)
• Important: Should fix (maintainability, clarity)
• Minor: Nice to have (style preferences)

Sources: skills/subagent-driven-development/SKILL.md145-156

Review Loop Mechanics

Both review types follow the same loop pattern:

1. Reviewer dispatched after implementation or previous fix
2. Reviewer identifies issues (or approves)
3. If issues found:
   • Same implementer subagent fixes them (maintains context)
   • Reviewer dispatched again
   • Loop continues until approved
4. Once approved: proceed to next stage (or next task)

Critical constraint: Code quality review MUST NOT start until spec compliance is approved. Checking quality before spec wastes effort on code that might need to be rewritten or removed.

Sources: skills/subagent-driven-development/SKILL.md67-77 skills/subagent-driven-development/SKILL.md186-191

Red Flags and Anti-Patterns

What Not To Do

The skill explicitly prohibits several patterns that cause problems:

Process violations:

• Never start implementation on main or master branch without explicit user consent
• Never skip reviews (spec compliance OR code quality)
• Never proceed with unfixed issues from reviewers
• Never dispatch multiple implementation subagents in parallel (causes conflicts)
• Never start code quality review before spec compliance is approved (wrong order)
• Never move to next task while either review has open issues

Context pollution:

• Never make subagent read plan file (controller provides full text)
• Never skip scene-setting context (subagent needs to understand where task fits)
• Don't try to fix failed tasks manually (use fix subagent instead)

Review shortcuts:

• Never accept "close enough" on spec compliance (spec reviewer found issues = not done)
• Never skip review loops (reviewer found issues = implementer fixes = review again)
• Never let implementer self-review replace actual review (both are needed)

Question handling:

• Never ignore subagent questions (answer before letting them proceed)
• Never rush subagents into implementation (let them ask questions first)

Sources: skills/subagent-driven-development/SKILL.md199-229

Integration with Other Skills

Required Skills

These skills MUST be used as part of the subagent-driven-development workflow:

Skill	When Used	Purpose
using-git-worktrees	Before starting	Set up isolated workspace on separate branch
writing-plans	Before starting	Create the implementation plan to execute
finishing-a-development-branch	After all tasks	Complete development, choose merge/PR/keep/discard

Sources: skills/subagent-driven-development/SKILL.md230-237

Skills Used by Subagents

Subagents automatically use these skills during their work:

Skill	Used By	Purpose
test-driven-development	Implementer subagents	Enforce RED-GREEN-REFACTOR cycle
requesting-code-review	Reviewer subagents	Code review template and structure

Sources: skills/subagent-driven-development/SKILL.md238-240

Alternative Workflow

Skill	When to Use Instead	Key Difference
executing-plans	Parallel session or human checkpoints needed	Batch execution with manual review vs automated review

For detailed comparison, see Executing Plans in Batches.

Sources: skills/subagent-driven-development/SKILL.md241-243

Advantages and Trade-offs

Advantages Over Manual Execution

Fresh context per task:

• No confusion from previous implementations
• Each subagent starts clean
• Parallel-safe (subagents don't interfere with each other)

Natural TDD adherence:

• Subagents follow test-driven-development naturally
• Less context = less temptation to shortcut

Question surfacing:

• Subagent can ask questions before AND during work
• Clarifications happen upfront, not after implementation
• Controller can provide exactly the context needed

Sources: skills/subagent-driven-development/SKILL.md167-174

Advantages Over Executing-Plans

Same session execution:

• No context switch to parallel conversation
• Continuous progress without waiting

Automated quality gates:

• Reviews happen automatically
• No human review needed between tasks
• Issues caught immediately

Efficiency gains:

• No file reading overhead (controller provides full text)
• Controller curates exactly what context is needed
• Subagent gets complete information upfront

Sources: skills/subagent-driven-development/SKILL.md175-185

Quality Gates and Iteration

Self-review catches early issues:

• Implementer reviews own work before handoff
• Obvious problems fixed before formal review

Two-stage review prevents conflation:

• Spec compliance ensures right thing built
• Code quality ensures it's well-built
• Separation prevents "looks good enough" shortcuts

Review loops ensure fixes work:

• Reviewer checks fixes, not just initial implementation
• Loop continues until actually fixed
• No "close enough" accepted

Sources: skills/subagent-driven-development/SKILL.md186-191

Cost Considerations

Higher upfront cost:

• More subagent invocations (implementer + 2 reviewers per task)
• Controller does prep work (extracting all tasks upfront)
• Review loops add iterations

Lower overall cost:

• Catches issues early (cheaper than debugging later)
• Prevents building wrong thing (spec review catches scope issues)
• Prevents low-quality implementations (quality review catches maintenance issues)
• Autonomous execution for hours reduces human time

Sources: skills/subagent-driven-development/SKILL.md192-198 README.md13-15

Implementation Details

File Structure

skills/subagent-driven-development/
├── SKILL.md                           # Main skill documentation
├── implementer-prompt.md              # Prompt for implementation subagent
├── spec-reviewer-prompt.md            # Prompt for spec compliance reviewer
└── code-quality-reviewer-prompt.md    # Prompt for quality reviewer

Sources: skills/subagent-driven-development/SKILL.md85-90

Key Code Entities

The skill is purely documentation-based, but it integrates with several code systems:

Platform-native tools used:

• TodoWrite tool (or platform equivalent) for task tracking
• Task tool (or @mention on OpenCode, spawn_agent on Codex) for subagent dispatch
• Skill tool for loading prompt templates
• Git for commit tracking and reviewer context

Platform-specific mappings:

Abstract Tool	Claude Code	OpenCode	Codex
TodoWrite	Native TodoWrite	update_plan	update_plan
Task	Native Task (subagent system)	@mention	spawn_agent
Skill	Native Skill	Native skill	CLI use-skill

For tool mapping details, see Tool Mapping Layer.

Workflow tool usage map (concept → code entity):

Sources: skills/subagent-driven-development/SKILL.md85-90 skills/subagent-driven-development/SKILL.md230-243 skills/subagent-driven-development/code-quality-reviewer-prompt.md10-18

Sources: skills/subagent-driven-development/SKILL.md1-243

Workflow Integration Points

Before using this skill:

1. brainstorming - design must be approved
2. using-git-worktrees - isolated workspace must be set up
3. writing-plans - implementation plan must exist

During use:

• Implementer subagents use test-driven-development
• Reviewer subagents use requesting-code-review template

After completion:

• finishing-a-development-branch - verify tests, choose completion option

Sources: skills/subagent-driven-development/SKILL.md230-243 README.md80-94

Example Execution Trace

The skill documentation includes a complete example showing the full controller-subagent interaction:

Setup:

[Read plan file once: docs/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]

Task 1: Successful first-pass:

[Dispatch implementer with full task text]
Implementer: "Before I begin - should hook be user or system level?"
Controller: "User level (~/.config/superpowers/hooks/)"
Implementer: Implements, tests (5/5 passing), self-reviews, commits

[Dispatch spec reviewer]
Spec reviewer: ✅ Spec compliant

[Dispatch quality reviewer]
Quality reviewer: Approved

Task 2: Review loops:

[Dispatch implementer]
Implementer: Implements, 8/8 tests passing, commits

[Dispatch spec reviewer]
Spec reviewer: ❌ Issues:
  - Missing: Progress reporting (spec required)
  - Extra: --json flag (not requested)

[Implementer fixes, commits]
[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now

[Dispatch quality reviewer]
Quality reviewer: Issues (Important): Magic number (100)

[Implementer fixes, extracts PROGRESS_INTERVAL constant]
[Quality reviewer reviews again]
Quality reviewer: ✅ Approved

Full trace at skills/subagent-driven-development/SKILL.md91-165

Sources: skills/subagent-driven-development/SKILL.md91-165