Subagent-Driven Development

Execute plans by assigning a brand-new subagent to each task, followed by a two-stage review after each task completion: first review specification compliance, then review code quality.

Why Use Subagents: You delegate tasks to specialized agents with isolated contexts. By carefully designing their instructions and context, you ensure they stay focused and successfully complete the task. They should not inherit your session context or history—you precisely construct everything they need. This also preserves your own context for coordinating work.

Core Principles: One new subagent per task + two-stage review (spec first, then quality) = high-quality, fast iteration

When to Use

dot

digraph when_to_use {
    "有实现计划?" [shape=diamond];
    "任务基本独立?" [shape=diamond];
    "留在当前会话?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "手动执行或先头脑风暴" [shape=box];

    "有实现计划?" -> "任务基本独立?" [label="是"];
    "有实现计划?" -> "手动执行或先头脑风暴" [label="否"];
    "任务基本独立?" -> "留在当前会话?" [label="是"];
    "任务基本独立?" -> "手动执行或先头脑风暴" [label="否 - 紧密耦合"];
    "留在当前会话?" -> "subagent-driven-development" [label="是"];
    "留在当前会话?" -> "executing-plans" [label="否 - 并行会话"];
}

Comparison with Executing Plans (Parallel Sessions):

Same session (no context switching)
New subagent per task (no context contamination)
Two-stage review after each task: first specification compliance, then code quality
Faster iteration (no manual intervention between tasks)

Process

dot

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="每个任务";
        "Assign Implementation Subagent (./implementer-prompt.md)" [shape=box];
        "Does Implementation Subagent have questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementation Subagent implements, tests, commits, self-reviews" [shape=box];
        "Assign Specification Review Subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Does Specification Review Subagent confirm code matches specs?" [shape=diamond];
        "Implementation Subagent fixes specification gaps" [shape=box];
        "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Does Code Quality Review Subagent approve?" [shape=diamond];
        "Implementation Subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract full text of all tasks, record context, create TodoWrite" [shape=box];
    "Are there remaining tasks?" [shape=diamond];
    "Assign Final Code Review Subagent to review overall implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract full text of all tasks, record context, create TodoWrite" -> "Assign Implementation Subagent (./implementer-prompt.md)";
    "Assign Implementation Subagent (./implementer-prompt.md)" -> "Does Implementation Subagent have questions?";
    "Does Implementation Subagent have questions?" -> "Answer questions, provide context" [label="Yes"];
    "Answer questions, provide context" -> "Assign Implementation Subagent (./implementer-prompt.md)";
    "Does Implementation Subagent have questions?" -> "Implementation Subagent implements, tests, commits, self-reviews" [label="No"];
    "Implementation Subagent implements, tests, commits, self-reviews" -> "Assign Specification Review Subagent (./spec-reviewer-prompt.md)";
    "Assign Specification Review Subagent (./spec-reviewer-prompt.md)" -> "Does Specification Review Subagent confirm code matches specs?";
    "Does Specification Review Subagent confirm code matches specs?" -> "Implementation Subagent fixes specification gaps" [label="No"];
    "Implementation Subagent fixes specification gaps" -> "Assign Specification Review Subagent (./spec-reviewer-prompt.md)" [label="Re-review"];
    "Does Specification Review Subagent confirm code matches specs?" -> "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" [label="Yes"];
    "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" -> "Does Code Quality Review Subagent approve?";
    "Does Code Quality Review Subagent approve?" -> "Implementation Subagent fixes quality issues" [label="No"];
    "Implementation Subagent fixes quality issues" -> "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" [label="Re-review"];
    "Does Code Quality Review Subagent approve?" -> "Mark task complete in TodoWrite" [label="Yes"];
    "Mark task complete in TodoWrite" -> "Are there remaining tasks?";
    "Are there remaining tasks?" -> "Assign Implementation Subagent (./implementer-prompt.md)" [label="Yes"];
    "Are there remaining tasks?" -> "Assign Final Code Review Subagent to review overall implementation" [label="No"];
    "Assign Final Code Review Subagent to review overall implementation" -> "Use superpowers:finishing-a-development-branch";
}

Model Selection

Use the lowest-cost model capable of handling each role to save costs and improve speed.

Mechanical Implementation Tasks (isolated functions, clear specs, 1-2 files): Use fast, cheap models. Most implementation tasks are mechanical when plans are written in sufficient detail.

Integration and Judgment Tasks (multi-file coordination, pattern matching, debugging): Use standard models.

Architecture, Design and Review Tasks: Use the strongest available model.

Task Complexity Signals:

Involves 1-2 files with complete specs → Cheap model
Involves multiple files with integration considerations → Standard model
Requires design judgment or extensive codebase understanding → Strongest model

Handling Implementer Status

The Implementation Subagent reports one of four statuses. Handle each status accordingly:

DONE: Proceed to specification compliance review.

DONE_WITH_CONCERNS: The implementer completed the work but flagged concerns. Read these concerns before proceeding. If concerns relate to correctness or scope, resolve them before review. If they are just observational notes (e.g., "This file is getting large"), record them and proceed with review.

NEEDS_CONTEXT: The implementer needs information not provided. Supply the missing context and reassign.

BLOCKED: The implementer cannot complete the task. Evaluate the blocking reason:

If it's a context issue, provide more context and reassign with the same model
If the task requires stronger reasoning, reassign with a stronger model
If the task is too large, split it into smaller parts
If the plan itself has issues, escalate to a human

Never ignore escalations or retry with the same model without making changes. If the implementer says they're stuck, something needs to change.

Prompt Templates

```
./implementer-prompt.md
```
- Assign Implementation Subagent
```
./spec-reviewer-prompt.md
```
- Assign Specification Compliance Review Subagent
```
./code-quality-reviewer-prompt.md
```
- Assign Code Quality Review Subagent

Example Workflow

You: I'm using subagent-driven development to execute this plan.

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

Task 1: Hook Installation Script

[Get Task 1 text and context (already extracted)]
[Assign Implementation Subagent with full task text + context]

Implementer: "Before I start — should the hook be installed at user level or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: "Got it. Starting implementation now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passed
  - Self-review: Missing --force parameter, added it
  - Committed

[Assign Specification Compliance Review]
Spec Reviewer: ✅ Complies with specs - All requirements met, no extra content

[Get git SHA, assign Code Quality Review]
Code Reviewer: Pros: Good test coverage, clean code. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery Mode

[Get Task 2 text and context (already extracted)]
[Assign Implementation Subagent with full task text + context]

Implementer: [No questions, starts directly]
Implementer:
  - Added verify/repair mode
  - 8/8 tests passed
  - Self-review: All good
  - Committed

[Assign Specification Compliance Review]
Spec Reviewer: ❌ Issues:
  - Missing: Progress reporting (spec requires "report every 100 items")
  - Extra: Added --json parameter (not requested)

[Implementer fixes issues]
Implementer: Removed --json parameter, added progress reporting

[Spec Reviewer re-reviews]
Spec Reviewer: ✅ Now complies with specs

[Assign Code Quality Review]
Code Reviewer: Pros: Solid. Issue (important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code Reviewer re-reviews]
Code Reviewer: ✅ Approved

[Mark Task 2 complete]

...

[After all tasks are complete]
[Assign Final Code Review]
Final Reviewer: All requirements met, ready for merge

Done!

Advantages

Compared to Manual Execution:

Subagents naturally follow TDD
New context per task (no confusion)
Parallel-safe (subagents don't interfere with each other)
Subagents can ask questions (before and during work)

Compared to Executing Plans:

Same session (no handoff)
Continuous progress (no waiting)
Automated review checkpoints

Efficiency Improvements:

No file reading overhead (controller provides full text)
Controller precisely curates required context
Subagents get complete information upfront
Questions are raised before work starts (not after)

Quality Gates:

Self-review catches issues before handoff
Two-stage review: specification compliance, then code quality
Review loops ensure fixes are effective
Specification compliance prevents over/under building
Code quality ensures good implementation

Cost:

More subagent calls (each task needs implementer + 2 reviewers)
Controller needs more preparation (extract all tasks upfront)
Review loops increase iteration count
But catches issues early (cheaper than late debugging)

Red Lines

Never:

Start implementation on main/master branch without explicit user consent
Skip reviews (specification compliance or code quality)
Proceed with unresolved issues
Assign multiple implementation subagents in parallel (causes conflicts)
Let subagents read plan files (should provide full text)
Skip laying out scenario context (subagents need to understand where the task fits)
Ignore subagent questions (answer before letting them proceed)
Accept "close enough" on specification compliance (issues found by spec reviewer = incomplete)
Skip review loops (reviewer finds issue = implementer fixes = re-review)
Let implementer's self-review replace formal review (both are needed)
Start code quality review before specification compliance review passes (wrong order)
Move to next task while any review has unresolved issues

If Subagent Asks Questions:

Answer clearly and completely
Provide additional context if necessary
Don't rush them into implementation

If Reviewer Finds Issues:

Implementer (same subagent) fixes
Reviewer re-reviews
Repeat until approved
Don't skip re-review

If Subagent Fails:

Assign a fix subagent with specific instructions
Don't attempt manual fixes (context contamination)

Integration

Required Workflow Skills:

superpowers:using-git-worktrees - Required: Set up isolated workspace before starting
superpowers:writing-plans - Create plans for this skill to execute
superpowers:requesting-code-review - Code review templates for review subagents
superpowers:finishing-a-development-branch - Wrap up after all tasks are complete

Subagents Should Use:

superpowers:test-driven-development - Subagents follow TDD for each task

Alternative Workflow:

superpowers:executing-plans - For parallel sessions instead of same-session execution

subagent-driven-development

NPX Install

Tags

SKILL.md Content (Chinese)