loom-subagent-driven-development

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.md
• combined-reviewer-prompt.md
• test-reporter-prompt.md

熔断配置

从 .loom/workflow.yaml 的 defaults 读取全局配置，step 级别配置可覆盖全局值：

# 全局默认（workflow.yaml defaults 区块）
max_retries: 3          # 单个 task 的最大修复重试次数
timeout_minutes: 30     # 单个 subagent 的超时时间（分钟）

每个 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。

1. 读取 specs/<date+feature>/plan.md Task 概览和 specs/<date+feature>/tasks/TN.md 详细内容，创建任务追踪列表。
2. 读取 specs/<date+feature>/requirements.json 与 specs/<date+feature>/traceability.json，确认每个 task frontmatter 的 behavior_ids 已在账本中映射到该 task。
3. 读取 .loom/workflow.yaml 的 defaults，获取 max_retries 和 timeout_minutes；当前 step 有 config 字段时以 step 级别为准。
4. 读取 .loom/contexts/subagent-context.md，必要时读取 specs/<date+feature>/spec.md 相关章节。
5. 对每个 task，执行以下循环（retry_count 初始为 0）：