name	build-workflow-execute
description	按计划增量生成软件或内容产物。当 plan 已批准需要开始实现，或提到"实现""编码""开始做"
argument-hint	[artifact-type] [--parallel-safe]

Execute — 增量生成

入口/出口

入口: 已批准 plan（docs/features/<name>/03-plan.md + 可选 docs/features/<name>/plans/*.md）
出口: 软件代码或内容产物 + 验证证据 + ADR（如有决策）
指向: 完成 → verify-workflow-review；遇到 Bug → verify-workflow-debug
输出路径: → verify-workflow-review
前置加载: CANON.md + build-quality-tdd/SKILL.md + build-cognitive-execution-engine/SKILL.md

何时不使用

探索性原型（标注 // UNTESTED 可跳过 TDD，但受 HARD GATE 约束）
纯配置变更（加环境变量、改 CI 配置）— 直接提交，不需要增量循环

前置

先读取计划拓扑，再调用 build-cognitive-execution-engine 选择执行模式。

读取顺序：

读取 docs/features/<name>/03-plan.md 总控计划
如果存在 docs/features/<name>/plans/*.md，按文件编号逐份读取子计划
从总控计划确认 Plan Topology、Subplans、Parallel Execution Matrix、Integration Order
验证每个子计划都有 Write Scope、Read Scope、Shared Contracts、Global Invariants、Parallel Safety、Verification Evidence、Cross-check Command、Merge Checkpoint

Task-by-task Execution Contract

For execution: implement this plan task-by-task.

03-plan.md 中每个 ### Task N 是 /build 的最小执行单元。
plans/*.md 中每个 ### Task N 是该子计划内的最小执行单元。
当前 Task N 的验证步骤未通过前，不进入下一个 Task N。
只有 Parallel Execution Matrix 明确证明 parallel_safe: yes 时，才允许并行执行多个 task 或 subplan。
/build 不重新创建任务列表。执行中发现任务缺失、验收标准缺失或切片无法执行时，记录 PLAN GAP，必要时回到 /plan 修补。
build 阶段任何 pre-review / implementation gate 结果只用于内部质量门，不能替代 formal /review

执行模式：

inline — 当前会话直接执行
subagent — 每任务或每个复杂子计划一个新 subagent，用于隔离高噪音上下文、专项执行和压缩结论 + 两阶段审查
parallel — 仅对 parallel_safe 子计划并行 subagent

选择模式时必须记录原因：

大量搜索、测试日志、diff、文件读取或专项审查会污染主 session → 可选择 subagent
多个子计划 parallel_safe: yes 且 Write Scope 不重叠 → 可选择 parallel
小修改、同一文件连续编辑、强共享上下文或需要频繁确认 → 保持 inline

没有 Parallel Execution Matrix 或没有 parallel_safe 证据时，降级为 serial 执行。降级原因必须写入 build 记录。

Agent Dispatch Contract

/build 的主流程由本技能和 build-cognitive-execution-engine 控制；persona 只在被阶段技能选中后执行对应 Task N 或子计划。

agents/task-planner.md：只用于读取计划、提取 task queue、检查 Parallel Execution Matrix 和选择 inline / subagent / parallel；不得在 /build 中重写正式任务列表。
agents/software-engineer.md：artifact_type: software 的默认 implementer，执行 TDD、实现和验证。
agents/api-designer.md：当 Task N 是 API 契约、endpoint shape、request/response/error contract 或版本策略时先执行；输出契约后交给 software-engineer 实现。
agents/data-architect.md：当 Task N 涉及 schema、migration、索引、约束或数据迁移策略时先执行；输出数据契约后交给 software-engineer 实现。
agents/content-writer.md：document / article / deck 的内容切片 implementer。
agents/visual-designer.md：visual 和 deck 的版式/视觉切片 implementer；deck 必须等 content-writer 完成叙事骨架后再进入 layout。
并行分派只允许给 Parallel Execution Matrix 证明 parallel_safe 的 Task N 或子计划；每个 persona 的 changed_files 必须落在 Write Scope 内，并满足 Shared Contracts / Global Invariants / Cross-check Command 合同。

再读取 spec 的 artifact_type，按需加载领域技能：

software（默认）→ 确认 02-design.md 已批准；加载 build-quality-tdd + 按子领域加载 build-frontend-* / build-backend-api-design / build-backend-database / build-backend-service-patterns
document / article → 加载 build-content-writing；涉及版式时加载 build-content-layout
deck → 先 build-content-writing 完成叙事骨架 → 再 build-content-layout 做视觉层级。顺序执行，不并行。
visual → 加载 build-content-layout，涉及文案时加载 build-content-writing

Plan Topology 执行规则

`serial`

按 ### Task N 顺序直接执行。存在 plans/*.md 时按文件编号顺序执行子计划，每个子计划内按 Task N 顺序。不分派并行 subagent。

`gated-parallel`

先串行执行 contracts / serial / gated 子计划
验证共享契约通过（API、schema、design、content、brand 或导出规格已稳定）
确认 Write Scope 不重叠、共享契约已冻结后，调用 build-cognitive-execution-engine fan-out
并行子计划全部完成并通过验证后，先运行各自 Cross-check Command，再按 Integration Order 串行合并和全量验证

`parallel`

fan-out 必须同时满足：Parallel Execution Matrix 列出 parallel_safe: yes、依赖已完成、有明确 Write Scope、任意两个子计划 Write Scope 不重叠、共享契约已冻结、全局不变量可被 Cross-check Command 独立验证。

不满足时：缺 Write Scope / Cross-check Command / Semantic Independence Reason → STOP 回 /plan；共享写入 → 降级串行；release/export/ship 标 parallel_safe → STOP 收口任务必须串行；共享契约未完成 → 按 gated-parallel 先执行契约。

增量循环

每个 Task N：实现 → 测试 → 验证 → 记录/提交 → 下一个 Task N

Step 1：选切片策略

计划拓扑优先 — 03-plan.md 定义了拓扑时按拓扑执行
Task-by-task 优先 — 计划已列出 ### Task N 时按 task queue 执行，不合并
垂直切片（推荐） — 一次建一条完整路径（DB + API + UI）
风险优先切片 — 最难/最不确定的部分先做
契约优先切片 — 先定接口契约，前后端并行

Step 2-4：实现 → 测试 → 验证

Step 2：实现让测试通过的最小代码。不提前抽象、不加未要求的功能。
Step 3：每个切片后跑对应验证。software 先 TDD（build-quality-tdd）；document/article 事实核查 + 逻辑链 + 语气；deck 叙事线 + 信息密度 + speaker notes；visual 视觉层级 + 对齐 + 对比度。
Step 4：software 测试通过 + 构建成功 + 类型检查 + Lint + 新功能按预期；非软件产物 review 证据齐全 + 导出物能打开且符合 spec。

Step 5：提交

用描述性信息提交。一个提交一个逻辑变更。

Step 6：循环

进入下一个切片，不要重新开始。多计划模式下循环单位是子计划：子计划内按任务切片循环；结束时记录 changed_files / artifact_paths / test_results；主 agent 按 Integration Order 合并并跑全量验证。

任务偏离处理

阻塞（外部依赖缺失） → 记录阻塞项，跳过当前切片，切到下一个独立切片
技术障碍 → STOP。调用 build-cognitive-decision-record 记录问题，执行备选方案
PLAN GAP → STOP。记录缺口，回到 /plan 修补，不在 build 中创建新任务
scope creep → 记录为 "NOTED"，不移出当前任务范围
预计耗时翻倍 → 和用户沟通

纪律规则

Rule 0：Simple First（YAGNI + Rule of Three）

写任何代码前问："最简单的能工作的方法是什么？"三个相似的代码行 > 一个过早的抽象。第三次使用场景出现前不建抽象。

Rule 0.5：Scope Discipline

只改该改的。看到值得改进但不相关的内容 → 记录 NOTICED BUT NOT TOUCHING，不改。不改相邻代码、不重构未改文件的 import、不删不理解的内容。

Rule 1-3

一个提交 = 一个逻辑变更。不混重构和新功能。
每个切片后项目必须能构建，已有测试必须通过。
不完整功能用 feature flag（process.env.FEATURE_X === 'true'）隔离。

Rule 4-5

新代码默认保守行为，opt-in 而非 opt-out。
新增文件容易回滚；修改最小化；migration 要有 rollback；删除和替换不在同一个提交。

遇到架构决策 → 写 ADR

调用 build-cognitive-decision-record/SKILL.md，产出到 docs/features/<name>/adr/<num>-<title>.md。

验证失败处理

失败场景	处理方式
测试失败	新代码 → 修复直到通过；已有测试 → 检查回归并修复
构建失败	检查错误信息，修复编译/类型错误，不跳过
检查点门未通过	STOP。标记未通过项 → 回到对应任务修复 → 重新运行检查点 → 全部绿色才继续
子计划缺 Write Scope / Cross-check Command / Semantic Independence Reason	STOP。不能分派 subagent，回到 `/plan` 修补
PLAN GAP	STOP。记录缺口，回到 `/plan` 修补
两个 parallel_safe 子计划写同一路径	降级串行或回到 `/plan` 重新切分
shared contract / global invariant cross-check 失败	降级串行，必要时回到 `/plan` 重切分
release/export/ship 标 parallel_safe	STOP。收口任务必须串行
切片比预期复杂	评估分解。预计耗时翻倍时与用户沟通
架构决策阻塞	停止实现，记录 ADR，执行备选方案
Scope creep	记录为 "NOTED"，不移出当前范围

验证证据

输出或记录必须包含：

输入/来源: 读取的 spec、plan、代码、反馈或发布上下文
执行动作: 实际完成的检查、生成、修复、导出或发布步骤
验证结果: 命令、审查结论、产物路径、截图或人工确认
阻塞/回退: 未通过项、回退路径或需要 human partner 决策的问题

常见说辞

说辞	现实	后果
"先写代码，测试最后一起跑"	Bug 叠加。切片 1 的 bug 让切片 2-5 都错。	Bug 延迟发现 → 定位成本线性增长 → 5 切片叠加 ≥ 4h，vs 每切片 < 5min
"一次做完更快"	感觉更快直到 500 行改了之后找不到哪行出的问题。	大提交出错回退范围 = 全部；小提交回退范围 = 最后一个切片，差距 10-50x
"这个改动太小不需要单独提交"	小提交没成本。大提交隐藏 bug 并让回滚困难。	混合提交回退行为变更 → 格式化也丢失 → 额外 30-60 分钟
"之后加 feature flag"	功能不完整就不暴露给用户。现在加 flag。	无 flag → 出问题只能回滚整个部署 → 全部用户受影响 vs flag 关闭 < 1min
"顺便重构一下"	重构混在新功能里让审查和回滚都更难。	混合提交无法独立 revert 重构 → 丢失格式化改进

红旗

写了超过 100 行还没有跑测试
一个切片里包含多个不相关的变更
未读取 plans/*.md 就开始执行多计划任务
跳过 ### Task N 顺序，按自己理解重组任务
在 /build 中临时创建新的正式任务列表
没有 Parallel Execution Matrix 却并行分派 subagent
subagent 修改超出子计划 Write Scope 的文件
parallel_safe 子计划之间出现 changed_files 冲突
"让我快速加这个" scope 膨胀
跳过测试/验证以加快速度
切片之间构建失败或测试中断
累积大量未提交变更
在第三个使用场景出现前就建抽象
为一次性操作建工具文件

验证清单

每个切片后：

多计划任务额外检查：

已读取 03-plan.md 和所有 plans/*.md
Plan Topology 已决定执行模式
每个子计划内的 ### Task N 已逐项完成并记录证据
Parallel Execution Matrix 支持所有 fan-out 决策
每个并行子计划的 Cross-check Command 已通过
每个 subagent 的 changed_files 没有越过 Write Scope
合并后全量验证通过

好坏示例

Good — 增量切片 + TDD

Task 1: 用户注册 API → RED（写失败测试）→ GREEN（最小实现让测试通过）→ Commit（feat: add user registration endpoint）。一个逻辑变更，描述性信息。

Bad — 大批量 + 跳过测试

一次性写 500 行包含注册、登录、任务创建、列表查询 → 无测试 Bug 叠加 → 单次提交包含 4 功能回滚丢全部 → 无 feature flag 注册失败时全部暴露 → 无垂直切片任何一步阻塞后续全卡。

输出模板

### Build Execute 交付记录

**Plan 来源**: [03-plan.md / plans/*.md 子计划名]
**执行模式**: [inline / subagent / parallel]
**模式选择原因**: [噪音隔离 / 独立验证 / parallel_safe / inline 简单连续执行]
**artifact_type**: [software / document / article / deck / visual]

**Task 完成状态**:
| Task N | 实现描述 | 测试结果 | 验证证据 | 提交 SHA |
|--------|---------|---------|---------|---------|
| Task 1 | [描述] | PASS / FAIL | [证据] | [SHA] |

**PLAN GAP**（如有）: [缺口描述 + 处理方式]
**ADR**（如有）: [adr/<num>-<title>.md 路径]
**合并后全量验证**: [通过 / 失败]