| name | loom-subagent-driven-development |
| description | Execute plan tasks via isolated subagents with reviewer checkpoints. Handles DONE/BLOCKED/NEEDS_CONTEXT states. Use when: a confirmed plan should be implemented through isolated subagents with reviewer checkpoints.
|
| when_to_use | Execute a confirmed plan through isolated subagents with reviewer checkpoints. |
| argument-hint | <spec_dir> |
| user-invocable | true |
Subagent 编码执行
触发条件
重要：subagent 模式会增加约 4-15x token 消耗，不应默认用于所有任务。
仅在以下条件满足任意一条时才使用本 skill：
- 涉及 3 个以上 task 文件
- 预计改动 5 个以上源文件
- 需要跨模块搜索或并行探索
- 有安全、数据一致性、迁移或权限风险
- 主上下文已严重污染，需要隔离重试
不满足以上条件时，由主 agent 直接执行，不派发 subagent。
此外仍需满足：
specs/<date+feature>/plan.md、requirements.json、traceability.json 和 tasks/ 已存在。- git worktree 已创建（或明确不需要隔离分支）。
- 用户确认 plan 后进入执行阶段。
产物根目录
本阶段的 specDir 是 specs/<date+feature>/。所有阶段产物都必须写入该目录内；禁止在项目根目录写 test-report.md、traceability.json、progress.md、task-states/、handoffs/ 或复制 plan.md、tasks/。
核心机制
每个 task 派发一个 fresh subagent；实现后由 reviewer 做合并审查（spec 合规 + 代码质量）。审查、测试或验证失败时，提取修复指令，派发 implementer 的修复模式，只传递修复指令 + .loom/contexts/subagent-context.md。
每个 fresh subagent 都必须以 task handoff 作为跨会话边界：上游只传递必要 spec 片段、task、subagent-context 和相关 handoff，不把主会话的原始讨论、大段搜索输出或长日志整体塞入子会话。
详细状态处理、执行循环和红线见 references/execution-details.md。派发前必须读取相关 prompt 模板：
implementer-prompt.mdcombined-reviewer-prompt.mdtest-reporter-prompt.md
熔断配置
从 .loom/workflow.yaml 的 defaults 读取全局配置，step 级别配置可覆盖全局值：
max_retries: 3
timeout_minutes: 30
每个 task 独立计算重试次数，不跨 task 累计。
执行前准备
启动执行阶段前，若 loom CLI 已安装，运行批次调度分析：
loom tasks --spec-dir specs/<date+feature>
输出会告知哪些 task 可以并行（无 owns 冲突 + 无依赖），哪些必须串行。以此结果决定派发策略，而非自行判断。
Handoff 协议（任务交接）
每个 subagent task 完成后必须生成交接文件 specs/<date+feature>/handoffs/TN.json，格式：
{
"task_id": "T1",
"status": "done",
"summary": "认证接口已完成，JWT 密钥从环境变量 JWT_SECRET 读取，未硬编码",
"artifacts": ["src/auth/index.ts", "tests/auth.test.ts"],
"exported_interfaces": [
{
"name": "Authenticate",
"path": "src/auth/index.ts",
"signature": "(token: string) => Promise<User>"
}
],
"breaking_changes": []
}
下游 task 的 subagent 派发前必须读取上游 handoff 作为紧凑索引，并按 artifacts 定向核对当前源码。handoff 不覆盖源码事实；自动保存的指纹过期时必须刷新 handoff。
-
读取 specs/<date+feature>/plan.md Task 概览和 specs/<date+feature>/tasks/TN.md 详细内容，创建任务追踪列表。
-
读取 specs/<date+feature>/requirements.json 与 specs/<date+feature>/traceability.json，确认每个 task frontmatter 的 behavior_ids 已在账本中映射到该 task。
-
读取 .loom/workflow.yaml 的 defaults，获取 max_retries 和 timeout_minutes；当前 step 有 config 字段时以 step 级别为准。
-
读取 .loom/contexts/subagent-context.md，必要时读取 specs/<date+feature>/spec.md 相关章节。
-
对每个 task，执行以下循环（retry_count 初始为 0）：
LOOP:
派发 implementer（首次实现 或 修复模式）
若 subagent 超时（> timeout_minutes）：
→ 通过 loom task/pipeline 状态记录失败，progress.md 由 loom 自动更新
→ 上报用户：任务名、已耗时、建议（拆分 task 或手动介入）
→ 停止当前 task，等待用户指示，禁止自动重试超时任务
处理状态：
DONE / DONE_WITH_CONCERNS → 继续派发 reviewer
NEEDS_CONTEXT → 补充上下文后重新派发，不计入 retry_count
BLOCKED → 上报用户，等待解除后继续，不计入 retry_count
派发 combined reviewer
若 reviewer PASS：
→ 进入下一个 task
若 reviewer FAIL：
retry_count += 1
若 retry_count > max_retries：
→ 触发熔断（见"熔断处理"）
否则：
→ 提取修复指令，派发 implementer（修复模式），回到 LOOP 顶部
-
每个 task PASS 后，更新 specs/<date+feature>/traceability.json：该 task 的每个 behavior_ids 都必须补齐真实持久化测试文件引用到 tests，并记录对应 evidence 引用到 evidence。
-
所有 task PASS 后，派发 test-reporter。
-
test-reporter 编写持久化集成测试、运行回归测试、对照 spec/requirements/traceability 验证并输出 specs/<date+feature>/test-report.md，同时复核 traceability.json 中每个 behavior 的 tests 和 evidence 都指向真实文件。
-
test-reporter FAIL 时提取修复指令，派发 implementer（修复模式），再重跑 test-reporter。
- test-reporter 的修复重试同样受
max_retries 限制，超限触发熔断。
-
执行阶段整体完成后写入 specs/<date+feature>/handoffs/executing.json，摘要说明已完成 task、验证命令、traceability.json 更新情况、关键产物和遗留风险。
traceability.json 执行闭环
planning 阶段只负责把 requirements.json 中的 REQ 与 behaviors 映射到 task；executing 阶段必须把 behavior 级账本补到可验证闭环：
{
"requirements": {
"REQ-001": {
"tasks": ["T1"],
"tests": ["tests/example.test.js"],
"evidence": ["evidence/test.log"],
"behaviors": {
"REQ-001-B01": {
"tasks": ["T1"],
"tests": ["tests/example.test.js#covers REQ-001-B01"],
"evidence": ["evidence/test.log"]
}
}
}
}
}
- 每个 task 文件的
behavior_ids 必须逐项更新到 traceability.json 对应 behavior。
tests 必须引用持久化测试文件，可带 #测试名 或 ::测试名 定位；不得引用临时文件或不存在路径。evidence 必须引用 specs/<date+feature>/evidence/ 下真实日志或 receipt，且与 test-report.md 的 evidence receipt 一致。- 不能只更新 REQ 级
tasks/tests/evidence，必须同步更新 behavior 级 tasks/tests/evidence。
- 若某个 behavior 没有可写测试或证据，返回 BLOCKED 或 NEEDS_CONTEXT，禁止把 task 标记为 done。
熔断处理
触发条件：单个 task 的 retry_count > max_retries，或 subagent 超时。
熔断后必须执行以下步骤，禁止自动继续：
- 通过 loom task/pipeline 状态记录熔断原因（已重试 N 次 / 超时），让
progress.md 自动反映失败状态；不要手动编辑 progress.md。
- 输出熔断报告给用户，包含：
- 等待用户明确选择，禁止自动推进。
上下文规则
何时开 fresh session
- 每个独立 task 的首次实现。
- 需要隔离重试的复杂修复。
- prototype 或高风险实验，不应污染主上下文。
- 并行任务确认无共享文件冲突后。
何时不新开 session
- reviewer 要求的同一 task 小修复，优先使用修复模式传递结构化指令。
- 上游 handoff 缺失或过期时，先补 handoff 或核对源码，不用新会话掩盖上下文缺口。
首次实现模式传入：
specs/<date+feature>/spec.md 相关章节specs/<date+feature>/requirements.json 中当前 task 的 Requirement 与 behavior 条目specs/<date+feature>/traceability.json 中当前 task 的 REQ/behavior 映射specs/<date+feature>/tasks/TN.md.loom/contexts/subagent-context.md
修复模式只传入：
- reviewer / test-reporter / verification 输出中的结构化修复指令
.loom/contexts/subagent-context.md- 原 task 的 Requirement ID、behavior_ids 与对应验收标准（只传相关行，不传全文）
不要在修复模式重新传递完整 task 和 spec 全文。
关键红线
- 禁止在 spec 未批准、plan 未确认前开始实现。
- 禁止跳过 reviewer 审查或 test-reporter。
- 禁止有未修复 BLOCKER 时进入下一个 task。
- 禁止默认并行派发；需要并行时使用
loom-dispatching-parallel-agents。
- 禁止把测试文件作为临时验证后删除。
- 禁止在未补齐
traceability.json behavior 级 tests 与 evidence 时把 task 标记为 done。
- 禁止在熔断后自动继续，必须等待用户指示。
- 禁止对超时任务自动重试。
模型选择策略
使用最强大的模型来处理每个角色，以节省成本并提高效率：
机械实现任务（隔离函数、1-2 个文件、Requirement ID 与验收映射完整、上下文无 UNKNOWN）：使用快速、便宜的模型。只有事实已落盘且不存在接口/安全判断时，才把任务视为机械实现
集成和判断任务（多文件协调、模式匹配、调试）：使用标准模型
架构、设计和审查任务：使用可用的最强模型
任务复杂度信号：
- 触及 1-2 个文件、Requirement ID/验收映射完整、无 UNKNOWN、无公开接口或安全影响 → 便宜模型
- 任一关键事实为 UNKNOWN、handoff 指纹过期或源码与 handoff 冲突 → 标准模型
- 触及多个文件且有集成问题 → 标准模型
- 需要设计判断或广泛的代码库理解 → 最强模型
完成条件
全部 task、reviewer、test-reporter 通过，traceability.json 中每个 behavior_ids 对应 behavior 都有真实 tests 与 evidence 引用，并完成 specs/<date+feature>/handoffs/executing.json。阶段结束后压缩原始派发记录、review 往返和长测试日志；下一阶段只依赖 specs/<date+feature>/spec.md、specs/<date+feature>/requirements.json、specs/<date+feature>/plan.md、specs/<date+feature>/tasks/、specs/<date+feature>/traceability.json、specs/<date+feature>/test-report.md、specs/<date+feature>/progress.md 和必要 handoff。
