subagent-driven-development

Subagent-Driven Development

Execute the plan by dispatching a new subagent for each task, with two-stage review after each task: first specification compliance review, then code quality review.

Core principles: One new subagent per task + two-stage review (specification first, then quality) = high quality, rapid iteration

Announce at the start:"I am using the subagent-driven-development skill to dispatch subagents according to the plan and perform two-stage reviews."

When to use

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
"Stay in this session?" -> "subagent-driven-development" [label="yes"];
"Stay in this session?" -> "executing-plans" [label="no - parallel session"];

}

**与 Executing Plans（并行会话）相比：**
- 同一会话（无上下文切换）
- 每任务一个新子智能体（无上下文污染）
- 每任务后两阶段审查：先规格符合性，再代码质量
- 更快迭代（任务间无人为介入）

## 流程

```dot
digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./references/implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./references/spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./references/code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers:finishing-development" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./references/implementer-prompt.md)";
    "Dispatch implementer subagent (./references/implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./references/implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./references/spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./references/spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./references/spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./references/code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./references/code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./references/code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./references/implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use finishing-development";
}

Prompt templates

• references/implementer-prompt.md - Dispatch implementer subagent
• references/spec-reviewer-prompt.md - Dispatch specification compliance reviewer subagent
• references/code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent

Advantages

Compared with manual execution:

• Subagents naturally follow TDD
• New context for each task (no confusion)
• Parallel-safe (subagents do not interfere with each other)
• Subagents can ask questions (before, during, and after work)

Compared with Executing Plans:

• Same session (no handoff)
• Continuous progress (no waiting)
• Automatic review checkpoints

Efficiency improvements:

• No file reading overhead (controller provides full text)
• Controller provides only the needed context
• Subagents receive complete information in advance
• Problems are exposed before work starts (rather than afterward)

Quality gates:

• Self-review catches problems before handoff
• Two-stage review: specification compliance, then code quality
• The review loop ensures fixes are effective
• Specification compliance prevents over/under-implementation
• Code quality ensures the implementation is good

Red flags

Never:

• Begin implementation on the main/master branch without the user's explicit consent
• Skip review (specification compliance or code quality)
• Continue with unfixed issues
• Dispatch multiple implementer subagents in parallel (they will conflict)
• Have subagents read the plan file (provide the full text instead)
• Skip background setting (subagents need to understand where the task fits)
• Ignore subagent questions (answer before letting them continue)
• Accept "close enough" on specification compliance (specification review finds problems = not done)
• Skip the review loop (reviewer finds problems = implementer fixes = review again)
• Replace actual review with implementer self-review (both are needed)
• Start code quality review before specification compliance ✅(wrong order)
• Move to the next task when either review has unresolved issues

If a subagent asks a question:

• Answer clearly and completely
• Provide additional context when necessary
• Do not rush them into implementation

If the reviewer finds problems:

• The implementer (same subagent) fixes them
• The reviewer reviews again
• Repeat until it passes
• Do not skip re-review

If a subagent's task fails:

• Dispatch a fix subagent with specific instructions
• Do not fix manually (this causes context pollution)

Integration

Required workflow skills:

• spec-init - Required: set up an isolated workspace before starting
• spec-plan - Create the plan executed by this skill
• requesting-code-review - Code review template for the reviewer sub-agent
• finishing-development - Perform development wrap-up confirmation after all tasks are complete

Sub-agents should use:

• test-driven-development - Sub-agents follow TDD for each task

Alternative workflow:

• spec-execute - For parallel sessions rather than same-session execution