| name | build-cognitive-execution-engine |
| description | 任务执行引擎——选择正确的执行模式。当 plan 已批准需要写代码，或提到"执行""实现""编码" |
执行引擎 — 3 种执行模式
入口/出口
- 入口:
build-workflow-plan 完成，任务列表已就绪
- 出口: 所有任务完成 + 测试通过 + 代码合并
- 指向: 全部任务完成后建议
/review
- 输出路径: → verify-workflow-review
- 前置加载: CANON.md +
build-quality-tdd/SKILL.md + build-workflow-execute/SKILL.md
何时不使用
- 还没有批准的 plan 或任务列表
- 当前只是探索、诊断或写 spec/design，不进入实现
- 只有一个微小文档或配置改动，不需要选择执行模式
任务输入契约
执行引擎只消费 /plan 已批准的任务列表：implement this plan task-by-task。
- 每个
### Task N 是一个执行单元，必须有验收条件和验证证据
plans/*.md 子计划也是执行单元；子计划内部仍按 ### Task N 逐项执行- 引擎可以选择 inline / subagent / parallel，但不能重新创建正式任务列表
- 任何 subagent 输入都必须绑定一个明确的
Task N 或 plans/*.md 子计划
Subagent Operating Principle
Subagent 的目标是隔离高噪音上下文、执行专项任务、压缩可决策信息；并行只是可选收益，不是默认目标。
适合分派 subagent：
- 大量搜索、日志、测试输出、diff 或文件读取会污染主 session
- 任务能独立完成，主 session 只需要摘要、证据、风险和下一步
- 需要限制工具权限、Read Scope 或 Write Scope
- 多个模块、假设或风险点能独立验证
不适合分派 subagent：
- 小改动、简单格式化、单文件连续编辑
- 需要频繁 human partner 确认的决策
- plan -> implementation -> testing 之间强共享上下文且必须由主 session 连续判断
- 输出摘要会比任务本身更长
每次分派必须写清：Goal、Task Source、Selected Persona、Read Scope、Write Scope、Forbidden Actions、Allowed Tools、Output Limit、Completion Criteria。
默认优先 read-only；只有 implementer / debugger 类型任务允许 Edit / Write。
返回内容不得包含原始日志、完整 diff、大段代码、长篇推理或无关背景。默认压缩到 1200 字以内；最后一行必须是单行 JSON：{"status":"...","changed_files":[],"test_results":[],"artifact_paths":[]}。
Agent Dispatch Contract
执行引擎选择执行模式时，也必须选择明确 persona；persona 选择不改变 Task N / Write Scope / Verification Evidence。
- Plan / mode selection →
agents/task-planner.md
- Software implementation →
agents/software-engineer.md
- API contract task →
agents/api-designer.md first, then agents/software-engineer.md
- Data schema / migration task →
agents/data-architect.md first, then agents/software-engineer.md
- Document / article task →
agents/content-writer.md
- Deck task →
agents/content-writer.md for narrative first, then agents/visual-designer.md for layout
- Visual task →
agents/visual-designer.md
Mode B fan-out can use different personas in parallel only when their Write Scope does not overlap and semantic independence is explicit. Mode C implementer/reviewer prompts must name the selected persona and include its required skills, inputs, outputs, scope, allowed tools, output limit, and completion criteria.
三种执行模式
模式 A: 直接执行
主 agent 按 ### Task N 顺序执行。适用单文件修改、简单 bug 修复、配置变更。
规则：实现 → 测试验证 → 记录/提交 → 下一个 Task N。当前 Task N 验证未通过前不进入下一个。每个任务 < 100 行变更。不要同时开多个实现分支。
模式 B: 并行 Fan-Out
面对 2+ 个真正独立的 Task N 或 plans/*.md 子计划（无共享文件、无共享状态、无顺序依赖），一次性分派。
规则：
- 一个消息分派所有 subagent（真正并行）
- 每个 subagent 独立上下文、独立文件、独立结果
- 并行输入必须来自
Parallel Execution Matrix 中明确 parallel_safe: yes 的 task 或子计划
- 每个 subagent 只能修改所属子计划的
Write Scope
- 分派完 → 等结果 → 审查 → 合并
禁止并行： 任务有依赖关系、修改同一文件、共享 DB schema 变更、共享 API/type/flag/config/test 契约未冻结、子计划缺 Write Scope / Verification Evidence / Merge Checkpoint / Cross-check Command / Semantic Independence Reason、release/export/ship 收口子计划。
gated-parallel
当 Plan Topology 是 gated-parallel：主 agent 先串行执行 contracts/gated/serial 子计划 → 共享契约验证通过 → 才分派依赖该契约的 parallel_safe 子计划。契约变化时已分派子计划全部作废。
分派模板： 每个 subagent 必须指定 Goal、Task Source、Selected Persona、Write Scope、Read Scope、Forbidden Actions、Allowed Tools、Shared Contracts、Global Invariants、Verification Evidence、Cross-check Command、Merge Checkpoint、Output Limit、Completion Criteria。最后一行输出 JSON 包含 status + changed_files + test_results + artifact_paths。
模式 C: Subagent Pre-Review Gate 流水线
用于高复杂度任务（跨多模块、关键业务逻辑、需安全审查）。
流程： Implementer subagent → 返回 status → Spec Gate subagent（独立验证）→ Code Quality Gate subagent（五轴审查）。
定位： 这是 build 阶段的内部保险丝，不是 formal /review。通过此 gate 只表示“允许继续集成 / 进入正式审查候选”，不表示“已经完成正式审查”。
关键规则：
- Implementer 输入必须包含具体 Task N / 子计划路径、验收条件、Write Scope、Verification Evidence
- Implementer / reviewer 输入必须包含 Allowed Tools、Forbidden Actions、Output Limit 和 Completion Criteria
- 每个 subagent 新鲜上下文 — 不传递前一个 subagent 对话历史
- Spec Gate 不信任 Implementer 报告 — 独立验证
- Code Quality Gate 必须等 spec 合规确认后才开始
- 严禁并行分派 Implementer
- 审查阶段串行门控：先 Spec Gate，SPEC_MATCH 后才分派 Code Quality Gate
- Mode C 结果不得写成 APPROVED / LGTM / READY TO MERGE；formal
/review 仍需单独产出 04-review.md
提示词模板： 使用 implementer-prompt.md、spec-reviewer-prompt.md、quality-reviewer-prompt.md。
Subagent 模型选择
| 复杂度 | 模型 | 适用 |
|---|
| 低 | Haiku / 廉价模型 | 样板代码、格式变更、copy-paste 重构 |
| 中 | Sonnet / 标准模型 | 常规实现、CRUD、前端组件 |
| 高 | Opus / 能力最强模型 | 核心业务逻辑、复杂算法、安全关键代码 |
原则： 不省不该省的钱。Entity 关系重构用 Opus，改颜色变量用 Haiku。
Fan-Out 合并
并行 agent 返回后：全部 DONE → 合并变更 + 跑全量测试；有失败 → 回退失败 agent 变更 + 重新分派；有冲突 → 合并有效部分 + 手动处理冲突。
合并前必做：
何时不使用这些模式
- 不用模式 B 当任务有顺序依赖/共享文件，或
Parallel Execution Matrix 没有证明 parallel_safe
- 不用模式 C 当任务简单到 1 个 agent 20 分钟能完成 — 两阶段审查是复杂任务保险，不是流程税
- 不用 subagent 处理需要实时人类确认的决策 — 主 agent 直接问
- 不用 subagent 处理同一文件内的连续小修改 — 主 agent 串行执行更清晰
- 不用 subagent 只为了"多开几个 agent" — 没有噪音隔离、权限收窄或独立验证价值就保持 inline
常见说辞
| 说辞 | 现实 | 后果 |
|---|
| "分派太慢，我直接写" | 1 个复杂任务 subagent 做 15min > 你猜 2h。并行 3 个 15min vs 串行 45min。 | 主 agent 猜测实现 > 单次返工 30-50%，总耗时 2-3x |
| "并行不会冲突" | 两个 agent 改同一文件 = 必定合并冲突。 | 合并冲突手动解决 > 30min/冲突，严重时丢弃一个 agent 全部变更 |
| "build 里已经审过了，不用 /review" | Mode C 只是 pre-review gate，不能替代 formal /review。 | 缺少独立 formal review → 合并质量门失效 → 返工和漏检风险叠加 |
| "跳过审查，代码看起来对" | 两阶段审查防止"看起来对但不符 spec"的错误。 | 无审查 → Implementer 偏离 spec → 合入不合规代码 → 返工 > 2x |
| "再分派一次也一样" | 第一次偏离 → 补约束 → 第二次才可能对。 | 不补约束重分派 → 同样偏离 → 3 次循环浪费 45+ min |
| "多开几个 agent 更保险" | 未限定目标、工具和输出上限的 subagent 会把噪音变成多份噪音摘要。 | 主 session 被重复背景、完整日志和无关建议污染，决策质量下降 |
红旗 — STOP
- 没有明确
Task N 或子计划就分派 subagent
- Subagent 派发缺 Goal / Scope / Forbidden Actions / Allowed Tools / Output Limit / Completion Criteria
- 模式 B 任务之间不是真正独立的（隐式依赖或共享文件）
- Subagent 报告 "DONE" 但没有 changed_files 列表
- Subagent 返回原始日志、完整 diff、大段代码或长篇推理
- Spec Gate 报告 SPEC_MATCH 但没提供独立验证证据
- 连续 3 次 Implementer 返回 ISSUES — 约束/任务描述可能有问题
- 两个并行 agent 在改同一文件 — 回退，串行化
- subagent 修改了 Write Scope 外文件 — 回退变更，重新分派或串行执行
parallel_safe 不是来自 Parallel Execution Matrix 的显式结论 — 停止并行- 子计划缺
Cross-check Command 或 Semantic Independence Reason 却被标为 parallel_safe
- Code Quality Gate 发现了 Spec Gate 应发现的问题 — 审查顺序错了
- Subagent 上下文不包含 spec 文档 — 盲区工作
验证清单
验证失败处理
| 失败场景 | 处理方式 |
|---|
| Implementer 返回 BLOCKED | 人类介入。不猜测原因，不静默跳过 |
| Implementer 返回 NEEDS_CONTEXT | 提供更多上下文，重新分派 |
| Spec Gate 返回 SPEC_GAP | 退回 Implementer 修正，列出具体 gap |
| Code Quality Gate 发现 Spec Gate 应发现的问题 | STOP，重走 Spec → Quality 顺序 |
| 连续 3 次 Implementer 返回 ISSUES | STOP。回到 /plan 修补，不第四次分派 |
| 并行 agent changed_files 越界 | 回退越界 agent，降级串行或重切 Write Scope |
| 并行 agent 文件冲突 | 合并有效部分，冲突部分串行重做 |
| Cross-check Command 失败 | 视为语义耦合未被控制，回退相关并行结果并降级串行 |
| 全量测试合并后失败 | 定位失败 agent，回退其变更，修复后重跑 |
输出模板
### Execution Engine 交付记录
**执行模式**: [inline / subagent / parallel fan-out]
**任务来源**: [03-plan.md Task N / plans/*.md 子计划名]
**任务完成状态**:
| Task N | 状态 | changed_files | test_results | 验证证据 |
|--------|------|--------------|-------------|---------|
| [Task N] | DONE / BLOCKED / NEEDS_CONTEXT | [文件列表] | [通过/失败] | [描述] |
**并行结果**（如适用）:
- Agent 1: [status] — Write Scope: [范围] — changed_files ⊆ Write Scope ✓/✗
- Agent 2: [status] — Write Scope: [范围] — changed_files ⊆ Write Scope ✓/✗
**Cross-check 结果**: [命令 + PASS/FAIL]
**合并后全量验证**: [通过 / 失败 — 具体原因]
