zeroz-lab Plan — 任务分解
入口/出口
- 入口: 已批准 spec（
docs/features/YYYYMMDD-<name>/01-spec.md）+ 已批准 design（如 required） - 出口:
docs/features/<name>/03-plan.md；大型/并行任务额外产出docs/features/<name>/plans/*.md+ 用户批准 - 指向: 用户批准 plan 后必须调用
build-workflow-execute - 输出路径: → build-workflow-execute
- 前置加载: CANON.md
- 辅助参考:
task-templates.md（任务模板、Subplan Contract、Parallel Safety 判定、代码示例规则）、plan-review.md（Plan Review Army 详细规则）
何时不使用
- 变更只涉及 1-2 个文件且 scope 明显
- spec 已经包含明确定义的任务（此时直接进入 build）
Agent Dispatch Contract
/plan 主执行 persona 是 agents/task-planner.md。
- Plan Review Army 在 Step 7.5 按
plan-review.md最少触发条件选择agents/plan-ceo-reviewer.md、agents/plan-eng-reviewer.md、agents/plan-design-reviewer.md、agents/plan-security-reviewer.md - 标准变更至少 CEO + Eng；大型、安全、合规或
--full才全开 - 未被选中的 reviewer 不产出占位反馈；所有已选 reviewer 反馈在 plan 批准前分级处理
核心锚点
Vertical Slicing
每个任务交付一个完整、可独立验证的功能路径。不按技术层水平切片。
执行规则：
- Software：一个任务 = 一个用户路径（schema + API + UI），不拆成"建所有 DB → 建所有 API → 建所有 UI"
- Content（document/article）：一个章节 = 一个任务（目标 + 草稿 + 事实核查 + 编辑验证）
- Deck：一组连续页面 = 一个任务（标题 + 内容 + 视觉 + speaker notes）
- 任务标题出现 "and" = 拆分信号
Plan Topology
按依赖关系和并行需求选择拓扑。
执行规则：
serial：有序依赖、共享文件、小任务 → 只写03-plan.mdparallel：无共享文件、无顺序依赖，且共享契约已冻结 →03-plan.md+ 多个plans/*.md，标记parallel_safegated-parallel：共享契约先定，后续可并行 →03-plan.md+plans/01-contracts.md+ 后续子计划- 实现顺序按依赖图自底向上；只有
Parallel Execution Matrix标记parallel_safe: yes的子计划才能并行
Bite-sized Tasks
每个任务 3-7 步、≤5 文件、2-5 分钟可执行操作。
执行规则：
- Software 任务用 RED → GREEN → REFACTOR 结构；非 software 用产物切片 + 验证证据结构
- 禁止占位符：TBD/TODO/"implement later"/"添加适当的错误处理"（无具体代码）= plan 失败
- 给执行 agent 提供方向和约束，不提供完整实现（复杂算法/安全逻辑/精确产物除外）
核心流程
Step 1：进入只读模式
不写代码。读取 spec、design 和相关代码库，识别模式和依赖。
单计划 vs 多计划决策门：
- XS/S 任务：只写
03-plan.md - M/L 或跨子系统：
03-plan.md总控 +plans/*.md子计划 - 有共享契约但可拆分：先写
plans/01-contracts.md，后续子计划基于契约并行
Step 2：识别依赖图和 Plan Topology（锚点执行）
先读取 artifact_type 选择依赖图模型（software/content/deck/visual），再按 Plan Topology 锚点选择拓扑。
Step 3：确定文件结构
映射出哪些文件会被创建或修改。每个文件一个明确职责；一起变化的放一起；遵循现有模式。
如果 01-spec.md 的 Documentation Impact 不是 feature_only，这里还必须映射 project doc 写入面：哪些是 root docs，哪些是 project docs，哪些继续留在 feature docs。
Step 4：垂直切片（锚点执行）
Step 5：写 bite-sized 任务（锚点执行）
任务模板见 task-templates.md。
Step 6：排序、Topology 和检查点
排列任务使依赖满足、系统保持可工作、高风险任务放前面、每 2-3 个任务设验证检查点。
多计划模式下 03-plan.md 必须包含：Subplans + Parallel Execution Matrix + Integration Order + Shared Contracts。任何子计划没有 Write Scope / Shared Contracts / Global Invariants / Cross-check Command / Semantic Independence Reason 不能分派；两个 parallel_safe 子计划 Write Scope 不能重叠，且共享契约必须已冻结。
Step 6.5：写 Project Doc Sync Plan
如果 spec 声明 project_truth_changed: yes 或 doc_intent != feature_only，03-plan.md 必须额外写：
Must update：本次必须同步的项目级文档路径Optional update：可选同步，但不是发布门Stage owner：由/build、/review或/ship哪个阶段收口Verification method：如何判断这些文档已兑现Deferred docs with reason：明确延后项和原因
即使 doc_intent: feature_only，也要显式写 Project Doc Sync Plan，并说明 not-needed。
Step 7：自审
写完 plan 后对照以下 10 项检查：
- Spec 覆盖：每条 spec 要求能找到对应任务
- 占位符扫描：无 TBD/TODO/"implement later"/"添加适当的错误处理"
- 类型一致性：后续任务的函数签名匹配前面定义的
- Subplans 完整：每个
plans/*.md存在且有 Subplan Contract - 并行安全：
parallel_safe子计划无重叠写入，且语义独立性已说明 - 收口顺序：release/ship 类子计划默认串行
- 任务独立性：每个任务有验收标准、独立验证步骤、依赖已标注
- 验证完整性：每个验证步骤有具体命令 + 预期输出 + 失败诊断
- 代码示例风格：最小示例 + 意图注释，无完整实现逻辑
- 任务粒度：≤5 文件、3-7 步、标题无 "and"
- 文档同步：如果 spec 要求同步 project docs，plan 已写
Project Doc Sync Plan
Step 7.5：Plan Review Army
自审通过后按风险升级执行 Review Army。详见 plan-review.md。
Step 8：用户批准
验证失败处理
| 失败场景 | 处理方式 |
|---|---|
| 用户拒绝 plan | 问清原因，修改 plan，重新提交 |
| plan 遗漏 spec 需求 | 补充任务；每条 spec 需求必须能找到对应任务 |
| 依赖关系不正确 | 重做依赖图验证 |
| 任务过大 | 分解到 ≤5 文件；标题出现 "and" = 拆分 |
| 验收条件缺失 | 强制补充；无验收条件的任务不能进入 build |
| parallel_safe 写入重叠 | 标记为串行，调整 Integration Order |
| shared contract / global invariant 未冻结 | 改为 gated-parallel 或串行 |
| spec 要求同步 project docs 但 plan 未写 owner / verification | 阻塞。补 Project Doc Sync Plan 后再进入 build |
常见说辞
| 说辞 | 现实 | 后果 |
|---|---|---|
| "边做边想" | 10 分钟计划节省数小时。 | 无计划遗漏 2-3 个依赖，每个导致 2-4 小时返工 |
| "任务很明显不需要写下来" | 写下来暴露隐藏依赖和边界情况。 | 未记录的"明显"任务隐藏 1-2 个边界，上线后 bug |
| "计划就是开销" | 计划就是任务。没计划的实现只是在打字。 | 无计划 → 依赖混乱 → 集成阶段 >50% 代码需重排 |
| "之后补验收条件" | 没有验收条件就无法判断"做完"。 | 后补验收条件倾向顺应已实现行为，遗漏被永久锁定 |
红旗
- 没有书面任务清单就开始实现
- 任务说"实现功能"但没有验收条件
- plan 中没有验证步骤
- spec 里说要同步 project docs，但 plan 没写
Project Doc Sync Plan - 所有任务都是 L 或 XL 大小
- 阶段之间没有检查点
- 依赖顺序没有执行
- plan 中任务标题出现 "and"（= 两个任务）
验证清单
- 每个任务有验收条件和验证步骤
- 任务依赖已识别并正确排序
- 没有任务超过 ~5 个文件
- 主要阶段间设了检查点
- plan 没有占位符
- spec 每个需求在 plan 中都有对应任务
-
Project Doc Sync Plan已存在；需要同步时包含 owner / verification / deferred reason - 多计划任务有 Subplans、Parallel Execution Matrix、Integration Order
-
parallel_safe子计划之间没有重叠写入 - 用户已审查并批准 plan
好坏示例
Good — 垂直切片 + 验收条件
Task 1: 用户注册 — Files: User.ts, register.ts, RegisterForm.tsx
Step 1: 定义 schema → 验证: prisma validate
Step 2: 实现 API → 验证: curl POST /api/register → 201
Step 3: 实现 UI → 验证: 浏览器提交表单 → 成功提示
Verification: npm test --coverage --grep register > 80%
Bad — 水平切片 + 无验收
Task 1: 建数据库（整个 schema）
Task 2: 建所有 API
Task 3: 建所有 UI
→ 水平切片: Task 3 完成前无法验证任何用户路径
→ 无验收条件: "建完"无法判定
→ 依赖链过长: 任何前置阻塞后续全部
输出模板
### Plan — <feature-name>
Plan Topology: [serial / parallel / gated-parallel] | artifact_type: [software/...]
Project Doc Sync Plan:
- Must update: [paths or none]
- Optional update: [paths or none]
- Stage owner: [phase / task]
- Verification method: [review / validate / manual]
- Deferred docs with reason: [items or none]
Task 清单:
| Task N | 标题 | 文件数 | 验收条件 | 验证命令 | 依赖 |
|--------|------|-------|---------|---------|------|
| 1 | [标题] | [N] | [条件] | [命令] | [无/Task N] |
子计划索引（如适用）:
| 子计划 | Write Scope | Shared Contracts | Cross-check Command | parallel_safe | 依赖 | 验证 |
|--------|------------|------------------|---------------------|--------------|------|------|
| plans/01-*.md | [范围] | [契约] | [命令] | [yes/no] | [依赖] | [命令] |
Parallel Execution Matrix（如适用）:
| A | B | safe | 无重叠 |
|---|---|------|--------|
| [1] | [2] | [yes/no] | [✓/✗] |
用户批准: [已批准 / 待批准]