subagent-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subagent-Driven Development

Subagent驱动开发

Execute beads epic by dispatching parallel subagents for independent issues, with two-stage review after each completion.

REQUIRED BACKGROUND: You MUST understand

superpowers-bd:beads

before using this skill. Preconditions: Beads epic exists with dependencies set. If not ->

plan2beads

first. If separate session ->

executing-plans

instead. Announce at start: "I'm using Subagent-Driven Development to execute beads epic [epic-id]."

通过为独立任务调度并行子代理来执行beads epic，每个任务完成后进行两阶段评审。

必备背景知识： 使用本技能前，你必须理解

superpowers-bd:beads

。 前置条件： 存在已设置依赖关系的Beads epic。如果不存在，请先执行

plan2beads

。如果是独立会话，请改用

executing-plans

。 启动时声明： “我将使用Subagent驱动开发来执行beads epic [epic-id]。”

Quick Start

快速开始

Load epic:
```
bd show <epic-id>
```
, parse children and Key Decisions
Check for
```
temp/sdd-checkpoint-{epic_id}.json
```
-- if found, restore state (budget_tier, wave_receipts, closed_issues, metrics), print "Resuming epic {id} from wave {N+1}", jump to LOADING (skip step 3)
Ask budget tier (max-20x / max-5x / pro-api) -- sets model matrix for session
Verify
```
temp/
```
exists (do NOT run
```
mkdir
```
)
```
bd ready
```
, filter to epic children
Check file conflicts, cap wave at 3, serialize wave file map into prompts
Dispatch implementers (
```
run_in_background: true
```
) -- sub-agents self-read from beads
Each returns: spec review -> code review -> verification -> evidence ->
```
bd close
```
Post
```
[WAVE-SUMMARY]
```
to epic comments, cleanup
```
temp/<epic>*
```
, write checkpoint, retain 2-line receipt
Repeat from 5 until all closed
Print completion report, run
```
finishing-a-development-branch
```

加载epic：
```
bd show <epic-id>
```
，解析子任务和关键决策
检查是否存在
```
temp/sdd-checkpoint-{epic_id}.json
```
——如果找到，恢复状态（预算层级、阶段执行记录、已关闭任务、指标），打印“从第{N+1}阶段恢复epic {id}的执行”，跳转到LOADING步骤（跳过步骤3）
询问预算层级（max-20x / max-5x / pro-api）——为会话设置模型矩阵
验证
```
temp/
```
目录存在（请勿执行
```
mkdir
```
）
执行
```
bd ready
```
，筛选出epic的子任务
检查文件冲突，将每阶段任务上限设为3，将阶段文件映射序列化为提示词
调度实现代理（
```
run_in_background: true
```
）——子代理从beads中自行读取信息
每个代理返回：规格评审 → 代码评审 → 验证 → 证据提交 →
```
bd close
```
向epic评论区发布
```
[WAVE-SUMMARY]
```
，清理
```
temp/<epic>*
```
，写入检查点，保留2行执行记录
从步骤5重复执行，直到所有任务关闭
打印完成报告，执行
```
finishing-a-development-branch
```

Budget Tier Selection

预算层级选择

Ask tier once at session start. Each task's

complexity:*

label (set during planning) selects the model; tier ceiling caps it. Code reviewer and verifier use tier defaults.

在会话开始时询问一次层级。每个任务的

complexity:*

标签（规划阶段设置）用于选择模型；层级上限会限制模型的选择。代码评审和验证代理使用层级默认模型。

Implementer Models

实现代理模型

Tier	simple	standard	complex
max-20x	haiku	sonnet	opus
max-5x	haiku	sonnet	opus
pro/api	haiku	sonnet	sonnet

层级	simple	standard	complex
max-20x	haiku	sonnet	opus
max-5x	haiku	sonnet	opus
pro/api	haiku	sonnet	sonnet

Spec Reviewer Models

规格评审代理模型

Tier	simple	standard	complex
max-20x	haiku	haiku	sonnet
max-5x	haiku	haiku	sonnet
pro/api	haiku	haiku	haiku

层级	simple	standard	complex
max-20x	haiku	haiku	sonnet
max-5x	haiku	haiku	sonnet
pro/api	haiku	haiku	haiku

Other Roles (unchanged by complexity)

其他角色（不受复杂度影响）

Tier	Code Reviewer	N Reviews	Verifier	Simplify
max-20x	sonnet	3	opus	Yes
max-5x	sonnet	3	opus	Yes
pro/api	haiku	1	sonnet	Skip

Default: if

complexity:*

label missing, use

standard

. Store tier selection for session -- don't ask again per wave.

层级	代码评审代理	评审次数	验证代理	简化处理
max-20x	sonnet	3	opus	是
max-5x	sonnet	3	opus	是
pro/api	haiku	1	sonnet	跳过

默认规则：如果缺少

complexity:*

标签，使用

standard

复杂度。会话内保留层级选择，请勿在每个阶段重复询问。

The Process

执行流程

LOADING: bd ready -> filter to epic -> check file conflicts -> cap at 3
DISPATCH: serialize wave file map -> bd update --status=in_progress -> dispatch async
MONITOR: poll TaskOutput(block=False, timeout=5000) -> route completions
REVIEW: spec review -> code review (N if tier allows) -> gap closure (max 3 attempts)
CLOSE: extract evidence -> bd close --reason -> simplify (if 2+ tasks) -> wave summary
-> loop back to LOADING until all closed -> COMPLETE

LOADING: bd ready → 筛选epic子任务 → 检查文件冲突 → 任务上限设为3
DISPATCH: 序列化阶段文件映射 → bd update --status=in_progress → 异步调度
MONITOR: 轮询TaskOutput(block=False, timeout=5000) → 路由完成的任务
REVIEW: 规格评审 → 代码评审（次数由层级决定） → 差距修复（最多3次尝试）
CLOSE: 提取证据 → bd close --reason → 简化处理（如果任务数≥2） → 阶段总结
-> 循环回到LOADING直到所有任务关闭 → 完成

Key Rules (GUARDS)

核心规则（防护机制）

Never: dispatch blocked issues, dispatch cross-epic issues, dispatch file-conflicting issues in same wave, skip

bd update --status=in_progress

, skip

bd close

after review, skip reviews, start code review before spec passes.

Always: check

bd ready

before each wave, compare file lists for conflicts,

bd close

immediately after review passes, re-check

bd ready

after each close.

Deadlock:

bd ready

empty but issues remain open -> check

bd blocked

for circular deps or forgotten closes.

Failure: Crash -> restart fresh. >2 review rejections -> pause for human. >3 verification failures -> escalate. See failure-recovery.md.

禁止： 调度被阻塞的任务、调度跨epic的任务、在同一阶段调度存在文件冲突的任务、跳过

bd update --status=in_progress

、评审通过后跳过

bd close

、跳过评审环节、规格评审未通过就开始代码评审。

必须： 每个阶段开始前检查

bd ready

、对比文件列表排查冲突、评审通过后立即执行

bd close

、每次关闭任务后重新检查

bd ready

。

死锁处理：

bd ready

为空但仍有未关闭任务 → 检查

bd blocked

是否存在循环依赖或遗漏的关闭操作。

故障处理： 崩溃 → 重新启动。评审被拒绝超过2次 → 暂停等待人工介入。验证失败超过3次 → 升级处理。详见failure-recovery.md。

State Machine

状态机

INIT [checkpoint?] -> LOADING (resume at wave N+1)
INIT -> LOADING -> DISPATCH -> MONITOR -> REVIEW -> CLOSE [+checkpoint] -> LOADING (loop)
                                                                        -> COMPLETE [cleanup]
REVIEW -> PENDING_HUMAN (verification >3 attempts)

初始化 [检查是否存在检查点?] → LOADING（从第N+1阶段恢复）
初始化 → LOADING → DISPATCH → MONITOR → REVIEW → CLOSE [+保存检查点] → LOADING（循环）
                                                                        → 完成 [清理]
REVIEW → 等待人工介入（验证失败超过3次）

Context Window Management

上下文窗口管理

After each wave CLOSE, write a checkpoint to

temp/sdd-checkpoint-{epic_id}.json

(see checkpoint-recovery.md). This enables seamless recovery after auto-compact or

/clear

On seeing
<sdd-checkpoint-recovery>
in session context: Read the checkpoint file and resume from the next wave. Do NOT re-ask budget tier.

At COMPLETE: Delete

temp/sdd-checkpoint-{epic_id}.json

and

temp/metrics-{epic_id}.json

每个阶段完成CLOSE后，将检查点写入

temp/sdd-checkpoint-{epic_id}.json

（详见checkpoint-recovery.md）。这支持在自动压缩或

/clear

操作后无缝恢复。

当会话上下文中出现
<sdd-checkpoint-recovery>
时：读取检查点文件，从下一个阶段恢复执行。请勿重新询问预算层级。

完成时： 删除

temp/sdd-checkpoint-{epic_id}.json

和

temp/metrics-{epic_id}.json

。

Prompt Templates

提示词模板

./implementer-prompt.md

{issue_id}

{epic_id}

{file_ownership_list}

{wave_file_map}

{dependency_ids}

{wave_number}

./spec-reviewer-prompt.md

{issue_id}

{wave_number}

./code-quality-reviewer-prompt.md

{issue_id}

{base_sha}

{head_sha}

{wave_number}

{code_reviewer_path}

skills/epic-verifier/verifier-prompt.md

{epic_id}

{base-sha}

{head-sha}

{test-command}

```
./simplifier-dispatch-guidance.md
```
-- post-wave simplification (skip on pro/api, skip single-task waves)

./implementer-prompt.md

{issue_id}

{epic_id}

{file_ownership_list}

{wave_file_map}

{dependency_ids}

{wave_number}

./spec-reviewer-prompt.md

{issue_id}

{wave_number}

./code-quality-reviewer-prompt.md

{issue_id}

{base_sha}

{head_sha}

{wave_number}

{code_reviewer_path}

skills/epic-verifier/verifier-prompt.md

{epic_id}

{base-sha}

{head-sha}

{test-command}

```
./simplifier-dispatch-guidance.md
```
-- 阶段后简化处理（pro/api层级跳过，单任务阶段跳过）

Integration

集成说明

plan2beads -- must run first to create epic
superpowers-bd:finishing-a-development-branch -- after COMPLETE state
superpowers-bd:test-driven-development -- subagents use for implementation
superpowers-bd:rule-of-five-code / rule-of-five-tests -- subagents use for artifacts >50 lines (code or test variant)
superpowers-bd:executing-plans -- alternative for parallel session

plan2beads -- 必须先执行此技能来创建epic
superpowers-bd:finishing-a-development-branch -- 进入完成状态后执行
superpowers-bd:test-driven-development -- 子代理在实现时使用
superpowers-bd:rule-of-five-code / rule-of-five-tests -- 子代理在处理超过50行的工件（代码或测试变体）时使用
superpowers-bd:executing-plans -- 并行会话的替代方案

Companion Files

配套文件

metrics-tracking.md: Wave/epic summary templates, cost formulas
background-execution.md: Polling pseudocode, review pipeline parallelism
verification-and-evidence.md: Gap closure loop, evidence extraction
wave-orchestration.md: TaskCreate/TaskUpdate tracking calls
example-workflow.md: Complete 3-wave worked example
failure-recovery.md: Timeout, rejection loop, deadlock, bd errors
dispatch-and-conflict.md: Dispatch routing, file conflict algorithm, parallel dispatch
checkpoint-recovery.md: Checkpoint schema, write timing, recovery logic, edge cases
context-loading.md: Self-read pattern, report tags, orchestrator vs sub-agent responsibilities

metrics-tracking.md: 阶段/epic总结模板、成本计算公式
background-execution.md: 轮询伪代码、评审流水线并行机制
verification-and-evidence.md: 差距修复循环、证据提取
wave-orchestration.md: TaskCreate/TaskUpdate跟踪调用
example-workflow.md: 完整的3阶段工作流示例
failure-recovery.md: 超时、拒绝循环、死锁、bd错误处理
dispatch-and-conflict.md: 调度路由、文件冲突算法、并行调度
checkpoint-recovery.md: 检查点 schema、写入时机、恢复逻辑、边缘情况
context-loading.md: 自读取模式、报告标签、编排器与子代理的职责划分