SuperAPI AI Directory

subagent-driven-development

Coding & development

View repository

Updated 10-16 09:29

About this skill

Subagent-Driven Development

Execute per the plan: dispatch a brand-new implementer subagent for each task; after each task is complete, do a two-stage review (first spec compliance, then code quality).

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

When to Use

digraph when_to_use {
    "有 implementation plan?" [shape=diamond];
    "任务大多独立?" [shape=diamond];
    "是否留在当前 session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "先手动执行或先 brainstorm" [shape=box];
"有 implementation plan?" -> "任务大多独立?" [label="是"];
"有 implementation plan?" -> "先手动执行或先 brainstorm" [label="否"];
"任务大多独立?" -> "是否留在当前 session?" [label="是"];
"任务大多独立?" -> "先手动执行或先 brainstorm" [label="否 - 强耦合"];
"是否留在当前 session?" -> "subagent-driven-development" [label="是"];
"是否留在当前 session?" -> "executing-plans" [label="否 - 独立/并行 session"];

}


**对比 Executing Plans(独立 session):**
- 同一 session(无上下文切换)
- 每 task 新 subagent(避免上下文污染)
- 每 task 自动两阶段 review(先 spec,再质量)
- 迭代更快(task 之间无需人类中断)

## The Process

```dot
digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "派发 implementer subagent(./implementer-prompt.md)" [shape=box];
        "implementer 有问题要问?" [shape=diamond];
        "回答问题并补充上下文" [shape=box];
        "implementer 实现/测试/提交/self-review" [shape=box];
        "派发 spec reviewer(./spec-reviewer-prompt.md)" [shape=box];
        "spec reviewer 确认满足 spec?" [shape=diamond];
        "implementer 修复 spec 缺口" [shape=box];
        "派发 code quality reviewer(./code-quality-reviewer-prompt.md)" [shape=box];
        "code quality reviewer 通过?" [shape=diamond];
        "implementer 修复质量问题" [shape=box];
        "在 TodoWrite 标记 task 完成" [shape=box];
    }

    "读取 plan,提取全部 tasks(含原文与上下文),创建 TodoWrite" [shape=box];
    "还有 task 吗?" [shape=diamond];
    "派发最终 code reviewer(全局 review)" [shape=box];
    "使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "读取 plan,提取全部 tasks(含原文与上下文),创建 TodoWrite" -> "派发 implementer subagent(./implementer-prompt.md)";
    "派发 implementer subagent(./implementer-prompt.md)" -> "implementer 有问题要问?";
    "implementer 有问题要问?" -> "回答问题并补充上下文" [label="是"];
    "回答问题并补充上下文" -> "派发 implementer subagent(./implementer-prompt.md)";
    "implementer 有问题要问?" -> "implementer 实现/测试/提交/self-review" [label="否"];
    "implementer 实现/测试/提交/self-review" -> "派发 spec reviewer(./spec-reviewer-prompt.md)";
    "派发 spec reviewer(./spec-reviewer-prompt.md)" -> "spec reviewer 确认满足 spec?";
    "spec reviewer 确认满足 spec?" -> "implementer 修复 spec 缺口" [label="否"];
    "implementer 修复 spec 缺口" -> "派发 spec reviewer(./spec-reviewer-prompt.md)" [label="re-review"];
    "spec reviewer 确认满足 spec?" -> "派发 code quality reviewer(./code-quality-reviewer-prompt.md)" [label="是"];
    "派发 code quality reviewer(./code-quality-reviewer-prompt.md)" -> "code quality reviewer 通过?";
    "code quality reviewer 通过?" -> "implementer 修复质量问题" [label="否"];
    "implementer 修复质量问题" -> "派发 code quality reviewer(./code-quality-reviewer-prompt.md)" [label="re-review"];
    "code quality reviewer 通过?" -> "在 TodoWrite 标记 task 完成" [label="是"];
    "在 TodoWrite 标记 task 完成" -> "还有 task 吗?";
    "还有 task 吗?" -> "派发 implementer subagent(./implementer-prompt.md)" [label="是"];
    "还有 task 吗?" -> "派发最终 code reviewer(全局 review)" [label="否"];
    "派发最终 code reviewer(全局 review)" -> "使用 superpowers:finishing-a-development-branch";
}

Prompt Templates

  • ./implementer-prompt.md: dispatch implementer subagent
  • ./spec-reviewer-prompt.md: dispatch spec compliance reviewer subagent
  • ./code-quality-reviewer-prompt.md: dispatch code quality reviewer subagent

Example Workflow

你:我正在使用 Subagent-Driven Development 来执行这个计划。

[只读一次计划文件:docs/plans/feature-plan.md]
[提取 5 个 tasks 的完整原文与上下文]
[创建 TodoWrite,包含所有 tasks]

Task 1:安装 hook 脚本

[拿到 Task 1 原文与上下文(已提前提取)]
[派发 implementer subagent,附上完整 task 文本 + 上下文]

Implementer:“开始前确认下:hook 应该安装在 user 级还是 system 级?”

你:“user 级(~/.config/superpowers/hooks/)”

Implementer:“收到,开始实现……”
[稍后] Implementer:
  - 实现 install-hook 命令
  - 添加测试,5/5 通过
  - 自检(self-review):发现漏了 --force flag,已补上
  - 已提交

[派发 spec compliance reviewer]
Spec reviewer:✅ 满足 spec——需求齐全,没有多做

[获取 git SHAs,派发 code quality reviewer]
Code reviewer:优点:覆盖好、代码干净。问题:无。结论:通过。

[标记 Task 1 完成]

Task 2:Recovery modes

[派发 implementer subagent]
Implementer:[无问题,直接做]
Implementer:
  - 新增 verify/repair modes
  - 8/8 tests 通过
  - 自检(self-review):OK
  - 已提交

[派发 spec compliance reviewer]
Spec reviewer:❌ 问题:
  - 缺失:进度汇报(spec 写了“每 100 项报告一次”)
  - 多做:新增了 --json flag(未要求)

[implementer 修复]
Implementer:移除 --json flag,新增进度汇报

[spec reviewer 复审]
Spec reviewer:✅ 现在满足 spec

[派发 code quality reviewer]
Code reviewer:优点:扎实。问题(重要):magic number(100)

[implementer 修复]
Implementer:抽出 PROGRESS_INTERVAL 常量

[code quality reviewer 复审]
Code reviewer:✅ 通过

[标记 Task 2 完成]

...

[全部 tasks 完成后]
[派发最终 code-reviewer]
Final reviewer:需求满足,可以合并

完成!

Advantages

Compared with manual execution:

  • subagents follow TDD more naturally
  • new context per task (no confusion)
  • parallel-safe (subagents do not interfere with each other)
  • subagents can ask questions before starting work or during the process

Compared with Executing Plans:

  • same session (no handoff needed)
  • continuous progress (no waiting)
  • review checkpoints automated

Efficiency gains:

  • the controller does not need to repeatedly read files (extract once, keep reusing)
  • the controller selects and provides the most needed context
  • subagents get complete information from the start
  • problems surface before work starts (not discovered only after completion)

Quality gates:

  • self-review catches a round of problems first
  • two-stage review: spec compliance → code quality
  • the review loop ensures fixes actually take effect
  • spec compliance prevents doing too much/too little
  • code quality ensures the implementation itself is good enough

Cost:

  • more subagent calls (per task: implementer + 2 reviewers)
  • the controller needs more upfront preparation (extract all tasks in advance)
  • the review loop increases the number of iterations
  • but it catches problems earlier (cheaper than later debugging)

Red Flags

Never:

  • skip review (either spec or quality)
  • continue moving forward with unfixed issues
  • dispatch multiple implementers in parallel (will conflict)
  • let the subagent read the plan file itself (the full text should be provided)
  • skip scene-setting context (the subagent needs to understand where the task fits)
  • ignore the subagent's questions (answer first, then let it continue)
  • accept "close enough" for spec compliance (reviewer found problems = not done yet)
  • skip the review loop (reviewer finds problems → implementer fixes → must be reviewed again)
  • use the implementer's self-review to replace a real review (both are needed)
  • do code quality review before spec compliance ✅(wrong order)
  • move on to the next task while either review still has open issues

If the subagent asks questions:

  • answer clearly and completely
  • add context when needed
  • do not rush it to skip understanding and start writing directly

If the reviewer raises issues:

  • the implementer (the same subagent) fixes them
  • the reviewer re-reviews
  • repeat until it passes
  • do not skip re-review

If subagent fails:

  • dispatch a fix subagent, give specific instructions
  • Do not fix manually yourself (to avoid context pollution)

Integration

Required workflow skills:

  • superpowers:writing-plans: generate the plan to execute
  • superpowers:requesting-code-review: template/specification for reviewer subagent
  • superpowers:finishing-a-development-branch: wrap-up after all tasks are completed

Subagent should use:

  • superpowers:test-driven-development: each task follows TDD

Alternative workflow:

  • superpowers:executing-plans: suitable for independent/parallel sessions