工作流系统
Spec-First 的 workflow 不是强制状态机，而是一组按证据缺口分工的入口。它们共同服务一条主链：
Codebase -> Spec -> Plan -> Tasks -> Code -> Review -> Knowledge正确使用方式不是“每次从头跑完”，而是判断当前缺少什么：缺 WHAT，进入需求或 PRD；缺 HOW，进入 plan；缺可执行切片，派生 task pack；缺实现，work；缺因果链，debug；缺质量判断，review；缺复用，compound。
入口分工
| 缺口 | 首选入口 | 核心产物 |
|---|---|---|
| 想法很多，不知道做什么 | spec-ideate | 候选方向、拒绝理由、推荐进入 brainstorm 的主题 |
| 需求散、验收不清 | spec-brainstorm | docs/brainstorms/*-requirements.md |
| 存量系统增量需要 PRD 级 WHAT/WHY | spec-prd | artifact_kind: prd-requirements 的 requirements |
| 目标明确但实现路径不清 | spec-plan | docs/plans/*-plan.md |
| 计划大、依赖和文件边界复杂 | spec-write-tasks | docs/tasks/*-tasks.md task pack |
| 已可执行 | spec-work | scoped diff、验证结果、closeout evidence |
| 有失败症状或回归 | spec-debug | root cause、修复、回归验证 |
| 有指标和预算的改进 | spec-optimize | baseline、实验记录、保留方案 |
| 已有 diff 或文档需要判断 | spec-code-review / spec-doc-review | structured findings、residual risks |
| 已解决问题值得复用 | spec-compound / spec-compound-refresh | docs/solutions/**/* |
spec-write-tasks 是 standalone skill，不是公开 spec-* workflow。它的定位是从 settled plan 派生执行索引，不替代 plan。
WHAT 与 HOW 分离
上游 workflow 的关键边界是不要让计划替产品做决定：
| 阶段 | 回答的问题 | 不做什么 |
|---|---|---|
| Ideate | 哪些方向值得探索 | 不写需求、不写计划 |
| Brainstorm | 用户、场景、边界、验收是什么 | 不做实现设计 |
| PRD | Brownfield 增量的 change delta 和 current-state evidence 是否足够 | 不创建第二套 docs/prds/ |
| Plan | 如何实现、改哪些文件、怎么验证 | 不执行代码 |
spec-prd 的输出仍写在 docs/brainstorms/*-requirements.md，这样 requirements -> plan -> tasks -> work 的链路保持单一，不额外引入 PRD 目录作为第二真源。
Plan 到 Tasks
小计划可以直接交给 spec-work。只有当计划具备明显执行复杂度时，才值得先生成 task pack：
- implementation units 较多
- 文件范围跨模块
- 任务之间有依赖或并行机会
- 验证面跨 unit / integration / smoke
- 需要明确
stop_if、test_focus和 file ownership
Task pack 的边界是 derived execution index：
| 字段 | 作用 |
|---|---|
source_plan | 唯一 source plan |
source_plan_hash | 证明 task pack 相对当前 plan 新鲜 |
spec_id | 串联 requirements、plan、task pack |
dependencies / wave | 执行顺序与并行机会 |
files | 任务声明的主要文件边界 |
test_focus | 当前切片验证重点 |
done_signal | 任务完成信号 |
stop_if | 触发停止和回到 plan 的条件 |
执行前应使用 CLI 校验结构和 hash：
spec-first tasks validate docs/tasks/<task-pack>.md --repo .执行、调试与优化
spec-work、spec-debug、spec-optimize 不是一个“大执行按钮”的三个名字，而是三种证据姿态。
| 入口 | 适合 | 必须避免 |
|---|---|---|
spec-work | 计划或 task pack 已可执行，需要交付 scoped diff | scope 不清时继续写代码 |
spec-debug | 失败、回归、stack trace、异常行为 | 没复现就直接猜修复 |
spec-optimize | 有可重复 measurement、预算和停止条件 | 把模糊“变好一点”当优化目标 |
Debug 可以回到 work，也可以暴露需求或架构问题后回到 plan。Optimize 的结果也应进入 review 或 work closeout，而不是只保留“模型觉得更好”的主观结论。
结构化评审
Review 的目标不是让更多 agent 说话，而是把不同视角的发现合成为可行动、可验证、可降噪的 finding set。
| 机制 | 作用 |
|---|---|
| Diff scope | 所有 reviewer 的共同事实底座 |
| Persona selection | 按 diff 风险选择 correctness、security、testing、maintainability 等视角 |
| Dispatch gate | 宿主不支持 subagent 或未授权时走 single-agent fallback |
| Finding schema | 用 severity、confidence、evidence、owner、autofix_class 描述问题 |
| Synthesis | 校验、去重、置信度门控、分区 safe/gated/manual/advisory |
| Coverage | 披露未验证、降级、失败 reviewer、provider limitation |
外部工具或 provider 可以帮助 reviewer 定位，但不能单独形成高置信 finding。结论必须能回到 diff、source、tests、logs、contracts 或用户证据。
知识沉淀
Compound 的职责是把已经解决的问题转成下次可复用的团队知识，而不是把完整会话历史塞进文档。
适合沉淀：
- 稳定 root cause 和排查顺序
- 已验证的修复模式
- 不适合的方案及原因
- 项目内可复用边界
- 下次遇到同类问题先看哪里
不适合沉淀：
- 未验证猜测
- 原始敏感日志
- 一次性中间状态
- 与当前代码无关的历史噪音
常见误用
| 误用 | 纠偏 |
|---|---|
| 每次都从 brainstorm 开始 | 当前目标清楚时直接 plan/work/review |
| 需求没清楚就 plan | 回到 brainstorm 或 PRD |
| 大计划直接塞给 work | 先考虑 task pack |
| task pack 修改了计划 scope | 回到 source plan，重新派生 |
| review 自动写 solution docs | review 只建议 compound，不替代知识晋升 |
| provider 输出直接当结论 | 作为候选，回到直接证据确认 |
阅读下一步
- Workflow 命令总览：查看每个入口的命令名和输入输出。
- Todo 与任务系统：深入理解 task pack、hash、验证和执行边界。
- 契约与质量门禁：理解 workflow 之间如何 handoff、验证和 closeout。