soc-build

SOC Build — 子智能体驱动的实现

通过为每个任务派发全新的子智能体来执行 OpenSpec 任务。

为什么用子智能体： 每个子智能体获得隔离的上下文和精确构建的指令。它们从不继承会话历史——你可以精确构建它们所需的内容。这样可以保留你自己的上下文用于协调。

核心原则： 每个任务使用全新子智能体 + 基于设计上下文的自我规划 + 自审 + 验收标准验证 = 高质量、快速迭代。一个任务只有在满足 tasks.md 中定义的所有验收标准后才能算完成。

自我规划模型： 实现者子智能体接收任务标识符（task ID、标题、变更名、项目根、spec 路径、门禁配置），自己从磁盘读 proposal.md、tasks.md、design.md 的相关切片。它们自己规划实现方法——要修改哪些文件、构建什么接口、采用什么测试策略——而不是依赖逐步指令。每个子智能体在明确架构约束内自行推理实现方案，同时避免编排器上下文随任务数线性放大。

持续执行： 任务之间不要暂停。连续执行所有任务。唯一可以停止的原因是：无法解决的 BLOCKED 状态、真正阻碍进展的歧义、连续 3 个任务失败、或者所有任务完成。

何时使用

当 openspec/changes/<name>/ 下存在 OpenSpec 变更，且有包含未完成任务的 tasks.md 文件时。

触发方式

/soc-build              # 自动检测当前活动的变更
/soc-build <name>       # 指定要构建的变更

执行流程

1. 确定变更 — 如果没有指定名称，自动检测 openspec/changes/ 中的活动变更（排除 archive/）。如果有歧义，使用 AskUserQuestion 选择。
2. 解析 tasks.md — 读取 openspec/changes/<name>/tasks.md，提取未完成的任务（[ ]），按 ID 排序。对于每个任务，同时提取可选的 [gates: ...] 注解作为该任务的门禁配置（详见下方任务门禁配置语法）；如果没有，默认为所有检测到的门禁。
3. 解析 spec 结构 — 记录 spec 目录路径供子智能体使用（不再预先读取 proposal.md / design.md 内容）
4. 对每个任务执行： a. 在 tasks.md 中标记任务为 🔄 in_progress b. 派发子智能体(subagent)，传入 task ID + 标题 + spec 路径 + 门禁配置（填入 ./implementer-prompt.md 模板）——子智能体从磁盘自己读需要的 spec 切片，自主规划和实现 c. 验证任务级验收标准 — 子智能体必须确认：
   • 任务产出的单元测试已编写并通过（仅 scope 内的测试：覆盖本任务所新增或修改模块的所有测试）
   • 全量测试套件 + 全量覆盖率不在任务级检查 d. 所有验收标准满足 → 在 tasks.md 中标记任务为 [x] ✅ e. 如果任务在重试后仍然失败 → 标记为 ❌
5. 处理失败：
   • 单个任务失败：重试一次
   • 连续 2 次失败：暂停整个流程，通知用户
6. 全部任务完成后，派发subagent执行全部测试套件及lint、构建等基础验证，并完成本次变更所涉及的相关功能的集成测试直到通过。
7. 完成后输出摘要报告后停止，提示用户：

   "所有任务已完成。请验收，确认后运行 /soc-archive 归档。"

子智能体上下文（路径而非内容）

编排器传给子智能体的载荷是最小化的标识符 + 路径，不传文件内容。子智能体自己读自己需要的部分。

Implementer 子智能体接收：

字段	值	来源
Task ID	如 1.2	从 tasks.md 中提取
任务标题	1 行人类可读标题	从 tasks.md 中抠出对应任务行
变更名称	<change-name>	调用方提供
项目根目录	[project-root]	调用方提供
Spec 目录	openspec/changes/<change-name>/	由变更名推导
门禁配置	来自 [gates: ...] 注解,或默认"所有检测到的门禁"	从 tasks.md 任务行提取

Implementer 自己从磁盘读：proposal.md（全文,通常 <5KB）、tasks.md（定位自己、抠出 AC）、design.md（仅 ## Task N section 或 grep 关键字定位的相关切片）。

tasks.md 中的状态标记

• [ ] — 待处理
• [ ] 🔄 in_progress — 正在处理
• [x] ✅ — 已完成
• [ ] ❌ — 失败

任务级 test 门禁只跑 scope 内测试，全量测试套件在全部任务完成后执行。

处理实现者状态

• DONE： 推进到下一个任务
• DONE_WITH_CONCERNS： 关注点会汇总到最终摘要报告，提示成员在归档前重点验证。继续推进
• NEEDS_CONTEXT： 提供缺失的上下文，重新派发
• BLOCKED： 评估阻碍——提供上下文、升级模型、或将任务拆分成更小的部分。永远不要在不做任何改变的情况下用同样的方法重试。

报告格式

所有任务完成后，输出：

SOC Build Complete: <name>
Total: N tasks | ✅ Passed: X | ❌ Failed: Y
测试及验证摘要，后续处理建议