Subagent-Driven Development
Delegate each task to a brand-new subagent for plan execution, with a two-stage review after each task completion: first review specification compliance, then review code quality.
Why Use Subagents: You delegate tasks to dedicated agents with isolated contexts. By carefully designing their instructions and contexts, you ensure they stay focused and successfully complete tasks. 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 Principle: One brand-new subagent per task + two-stage review (spec first, then quality) = high-quality, rapid 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)
- Brand-new subagent per task (no context pollution)
- Two-stage review after each task: first specification compliance, then code quality
- Faster iteration (no manual intervention required between tasks)
Process
dot
digraph process {
rankdir=TB;
subgraph cluster_per_task {
label="每个任务";
"分派实现子智能体 (./implementer-prompt.md)" [shape=box];
"实现子智能体有疑问?" [shape=diamond];
"回答问题，提供上下文" [shape=box];
"实现子智能体实现、测试、提交、自审" [shape=box];
"分派规格审查子智能体 (./spec-reviewer-prompt.md)" [shape=box];
"规格审查子智能体确认代码匹配规格?" [shape=diamond];
"实现子智能体修复规格差距" [shape=box];
"分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [shape=box];
"代码质量审查子智能体通过?" [shape=diamond];
"实现子智能体修复质量问题" [shape=box];
"在 TodoWrite 中标记任务完成" [shape=box];
}
"读取计划，提取所有任务的完整文本，记录上下文，创建 TodoWrite" [shape=box];
"还有剩余任务?" [shape=diamond];
"分派最终代码审查子智能体审查整体实现" [shape=box];
"使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
"读取计划，提取所有任务的完整文本，记录上下文，创建 TodoWrite" -> "分派实现子智能体 (./implementer-prompt.md)";
"分派实现子智能体 (./implementer-prompt.md)" -> "实现子智能体有疑问?";
"实现子智能体有疑问?" -> "回答问题，提供上下文" [label="是"];
"回答问题，提供上下文" -> "分派实现子智能体 (./implementer-prompt.md)";
"实现子智能体有疑问?" -> "实现子智能体实现、测试、提交、自审" [label="否"];
"实现子智能体实现、测试、提交、自审" -> "分派规格审查子智能体 (./spec-reviewer-prompt.md)";
"分派规格审查子智能体 (./spec-reviewer-prompt.md)" -> "规格审查子智能体确认代码匹配规格?";
"规格审查子智能体确认代码匹配规格?" -> "实现子智能体修复规格差距" [label="否"];
"实现子智能体修复规格差距" -> "分派规格审查子智能体 (./spec-reviewer-prompt.md)" [label="重新审查"];
"规格审查子智能体确认代码匹配规格?" -> "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [label="是"];
"分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" -> "代码质量审查子智能体通过?";
"代码质量审查子智能体通过?" -> "实现子智能体修复质量问题" [label="否"];
"实现子智能体修复质量问题" -> "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [label="重新审查"];
"代码质量审查子智能体通过?" -> "在 TodoWrite 中标记任务完成" [label="是"];
"在 TodoWrite 中标记任务完成" -> "还有剩余任务?";
"还有剩余任务?" -> "分派实现子智能体 (./implementer-prompt.md)" [label="是"];
"还有剩余任务?" -> "分派最终代码审查子智能体审查整体实现" [label="否"];
"分派最终代码审查子智能体审查整体实现" -> "使用 superpowers:finishing-a-development-branch";
}
Model Selection
Use the lowest-cost model capable of each role to save costs and improve speed.
Mechanical Implementation Tasks (isolated functions, clear specifications, 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 specifications → 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 requires unprovided information. Provide the missing context and re-delegate.
BLOCKED: The implementer cannot complete the task. Evaluate the blocking reason:
- If it's a context issue, provide more context and re-delegate with the same model
- If the task requires stronger reasoning, re-delegate with a stronger model
- If the task is too large, split it into smaller parts
- If the plan itself is problematic, 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
- - Delegate implementation subagent
./spec-reviewer-prompt.md
./code-quality-reviewer-prompt.md
Example Workflow
你：我正在使用子智能体驱动开发来执行这个计划。
[一次性读取计划文件：docs/superpowers/plans/feature-plan.md]
[提取全部 5 个任务的完整文本和上下文]
[用所有任务创建 TodoWrite]
任务 1：Hook 安装脚本
[获取任务 1 的文本和上下文（已提取）]
[分派实现子智能体，附带完整任务文本 + 上下文]
实现者："在我开始之前——hook 应该安装在用户级别还是系统级别？"
你："用户级别（~/.config/superpowers/hooks/）"
实现者："明白了。现在开始实现……"
[稍后] 实现者：
- 实现了 install-hook 命令
- 添加了测试，5/5 通过
- 自审：发现遗漏了 --force 参数，已添加
- 已提交
[分派规格合规审查]
规格审查者：✅ 符合规格 - 所有需求已满足，无多余内容
[获取 git SHA，分派代码质量审查]
代码审查者：优点：测试覆盖好，代码整洁。问题：无。通过。
[标记任务 1 完成]
任务 2：恢复模式
[获取任务 2 的文本和上下文（已提取）]
[分派实现子智能体，附带完整任务文本 + 上下文]
实现者：[无疑问，直接开始]
实现者：
- 添加了 verify/repair 模式
- 8/8 测试通过
- 自审：一切正常
- 已提交
[分派规格合规审查]
规格审查者：❌ 问题：
- 缺失：进度报告（规格要求"每 100 项报告一次"）
- 多余：添加了 --json 参数（未被要求）
[实现者修复问题]
实现者：移除了 --json 参数，添加了进度报告
[规格审查者再次审查]
规格审查者：✅ 现在符合规格
[分派代码质量审查]
代码审查者：优点：扎实。问题（重要）：魔法数字（100）
[实现者修复]
实现者：提取了 PROGRESS_INTERVAL 常量
[代码审查者再次审查]
代码审查者：✅ 通过
[标记任务 2 完成]
...
[所有任务完成后]
[分派最终代码审查]
最终审查者：所有需求已满足，可以合并
完成！
Advantages
Compared to Manual Execution:
- Subagents naturally follow TDD
- Brand-new context per task (no confusion)
- Parallel-safe (subagents don't interfere with each other)
- Subagents can ask questions (both 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 complete 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 actually effective
- Specification compliance prevents over/under-building
- Code quality ensures good implementation
Cost:
- More subagent calls (each task requires implementer + 2 reviewers)
- Controller needs more preparation (pre-extract all tasks)
- Review loops increase iteration count
- But catches issues early (cheaper than debugging later)
Red Lines
Never:
- Start implementation on the main/master branch without explicit user consent
- Skip reviews (specification compliance or code quality)
- Proceed with unresolved issues
- Delegate multiple implementation subagents in parallel (causes conflicts)
- Let subagents read plan files (provide complete text instead)
- 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 issues = implementer fixes = re-review)
- Let the implementer's self-review replace formal review (both are needed)
- Start code quality review before specification compliance review passes (wrong order)
- Move to the next task while any review has unresolved issues
If a subagent asks a question:
- Answer clearly and completely
- Provide additional context if necessary
- Don't rush them into implementation
If a reviewer finds issues:
- The implementer (same subagent) fixes them
- The reviewer re-reviews
- Repeat until passed
- Don't skip re-review
If a subagent fails:
- Delegate a fix subagent with specific instructions
- Don't attempt manual fixes (context pollution)
Integration
Required Workflow Skills:
- superpowers:using-git-worktrees - Required: Set up isolated workspaces 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 completed
Subagents Should Use:
- superpowers:test-driven-development - Subagents follow TDD for each task
Alternative Workflows:
- superpowers:executing-plans - For parallel sessions instead of same-session execution