plan-tasks

根据已批准的需求和设计，使用该技能集中的 templates/tasks.md（按顺序查找：与此 SKILL.md 同目录的 templates/、${CLAUDE_PLUGIN_ROOT}/templates，否则使用 ../../../templates），生成 docs/specs/<YYYY-MM-DD>-<feature>/tasks.md。每个任务块的所有栏位（Files、Interfaces、Depends-on、Steps、_Requirements:_）都是必填项——不要添加每任务风险标签、决策面标记或 Human-review-order（原因见第 3 步的门禁表）。面向熟练的实现者撰写；他们对这个代码库没有任何背景信息，只能看到自己的任务和全局约束：他们不能靠猜测确定的名称、路径、类型、命令，必须写在 Files / Interfaces / Reuse / 页脚中，不能写成 Steps 里的说明文字（见精简步骤）。为每个步骤创建一个待办项（1–4；如果有跟踪器，则加上 5）——这是此技能自己的清单，与 design-solution 和 execute 系列各自的清单分开；只有满足相应的**完成条件：**后才能勾选。

第 1 步：标题和全局约束

目标（一个句子）、架构（2–3 个句子）、技术栈，以及 Execution-mode: <unset|continuous|story-unit>（保持为 unset；绝不能根据规模/级别/习惯自行设定——模式回写只在退出时进行）。接着是全局约束：项目级规则必须指向一个规范来源路径和哈希，并由每个任务引用（不得复制）。如果存在 ## Team 且其中有成员名单/级别覆盖 → 仅据此推导级别和任务分配方式（独行：不要假装多人协作；小团队/多人团队：可选自由格式备注，绝不新增必填字段）；如果没有 Team → 使用功能开发前的默认设置。如果存在 docs/architecture/ 架构主干 → 也纳入其中的硬性 **ARCH-N** 不变量，使每个任务都继承这些约束。按下方顺序确定来源——命中首个来源即为唯一事实来源（SSOT）；绝不另行编造一套：

顺序	来源	覆盖范围
1	docs/standards/，若存在（INDEX.md + 领域文件，如 testing.md、errors-logging.md）	命名、国际化、项目规范、测试、错误/日志记录
2，然后 3	若 docs/standards/ 不存在，则使用 docs/product/guidelines.md（仅作为旧版回退，且仅当其中包含对应的规则正文时使用——只有指针不算）；否则使用 docs/agents/project.md	测试/代码检查/类型检查命令、命名/国际化规则、禁止的更改

**完成条件：**已写明目标、架构、技术栈、Execution-mode:（通常为 unset）和全局约束来源路径/哈希；已确定约束来源，且未另行编造并行 SSOT。

第 2 步：文件结构和检索

在编写任务前，列出计划中要创建或修改的所有文件，并为每个文件说明其职责（一行）。未列入映射的文件不得由任何任务触及。

编写文件结构时查阅系统文档（可选）

如果此步骤要编写或修订文件结构/路径布局，请阅读与本文档同目录的 system-docs-consult.md 并严格遵循其中的说明——它会确定代码库/规范的权威来源、冲突处理方式，以及在相关文档缺失或不具权威性时的无操作路径。

完成映射后、编写任务正文之前（第 3 步），执行一次检索：必需的子技能：对映射路径使用 load-subgraph 执行 blast_radius，然后以 cluster(feature CODE) 为唯一焦点执行检索。编写 Files/Reuse 时保留检索得到的包；对于有依据的声明（一个归属位置），遵循 skills/execution/load-subgraph/references/grounded-claims.md——结果为空/稀疏并非门禁条件，但在声称不存在之前，必须先说明覆盖范围。

**完成条件：**所有要创建/修改的文件都已映射，并附有一行职责说明；且 blast_radius/cluster(feature CODE) 已各运行一次（如果 specs/seeds 缺失，则无操作）。

第 3 步：纵向切片任务

**契约：**任务是一个垂直切片——拥有独立测试周期和评审结论的最小单元；只有在评审者可能拒绝一个任务、同时批准相邻任务时，才拆分。形态：每个用户故事的每个任务都应产出一个可演示的端到端成果；仅为后续切片铺路的预先重构应作为独立的更早任务（“先让改动变容易，再做容易的改动”），通过 Depends-on 边关联——绝不能在故事任务中埋入横向分层。

每个任务包含以下栏位：

栏位	规则
Files, Reuse, Interfaces, Depends-on	Files：Create / Modify / Test，每个路径都必须用反引号明确固定（例如 `src/foo/bar.ts`）；绝不把行号或范围拼进路径标记中（禁止 path:86-103）——范围应写在周围的说明文字中，或单独标注（仅适用于新计划；P1 所有权提取仍接受已编写的 tasks.md 中沿用的旧式拼接形式）。Reuse：本任务所依赖的具体现有代码／库／模式，必须从设计部分的 Reuse: 行中逐字复制——使用相同的 <rung> — <concrete target> 语法（例如 Reuse: existing — src/util/dates:parseISO (rung 2)）；只复制，不要重新解释——Step 4 会将其与设计中的对应行核对。Interfaces：Consumes / Produces——相邻任务共享的名称和类型，让独立实现者知道要调用什么。Depends-on：本任务确实依赖的较早任务——即其接口被本任务 Consumes 或其文件是本任务构建基础的任务——格式为 Depends-on: Task 2, Task 4，或 Depends-on: none。并行信号：两个任务既不共享文件，也不共享接口时，不要声明依赖边，这样连续的 build-in-waves 调度器便可在接口互不重叠且工作树隔离安全时，将它们放入同一就绪集；省略此行时，默认依赖所有较早任务（安全但完全串行）——过度声明会造成不必要的串行执行，声明不足则会被执行器的文件不重叠检查拦截，避免发生冲突。此规则用于构建波次——绝不要仅为整理评审单元而重排或缩减依赖，导致错误描述任务所需内容。
步骤（简洁，3–8 个复选框）	细小的复选框步骤（每项 2–5 分钟，每个任务优先 3–8 项），按 TDD 循环：编写失败测试（完整代码，描述行为，而不是在应用／测试源代码中嵌入需求 ID）→ 运行，确认出现所述失败 → 实现（完整代码）→ 运行，确认通过 → 使用说明改动内容的常规提交主题进行提交（不要求或教授使用 Implements: / Guards: 尾注）。不要在这里写长篇大论——那会扩大评审范围；单个执行者需要的详细操作说明应在执行时写入执行简报（.skills/<CODE>/task-N-brief.md），而共享计划应将标识符（路径、类型名称、命令）保留在 Files / Interfaces / Reuse 中，避免简报凭空编造 API。
页脚	`_Requirements: CODE-N.M, CODE-N.M_`——本任务实现或保障的 ID；每个任务都必须有一个。默认：一个故事的 ID（故事编号 N 相同）；多个故事的页脚会在 build-by-story 中将这些故事合并为一个评审单元（这是计划质量信号——不是禁令，也不是谎报 Depends-on 的理由）。ID 应写在此页脚（以及需求／设计）中，而不是生产源码或测试标题中。任何栏位中都不得出现占位内容——“TBD”、“添加适当的错误处理”、“类似 Task 3”，或引用了某个未在任何任务中定义的类型——这些都是计划缺陷；计划发布前必须修复。

想法	实际情况
“总是应该先做预先重构——让改动变容易”	通过 Depends-on 进行预先重构没有问题；但在 build-by-story 中，评审单元仍应遵循故事引用
“我会加上 Risk: high，让评审者注意”	没有此字段。实际差异上的风险 glob 会取代 Agent 标签
“我会写上 Human review order，让人知道先看什么”	已被取代：从故事推导出的单元就是评审顺序；没有使用方的第二份手写清单毫无意义
完成条件： Step 2 映射中的每个文件都至少由 1 个任务覆盖，且每个任务都写成一个包含自身测试周期的纵向切片——槽位／占位符的整洁性检查属于 Step 4，不属于此处。

一个三元组，一个计划

本规则的归属位置——Step 4 和 Exit 只在此处引用本规则。

将已批准设计和需求中的每个纵向切片都写入此 tasks.md。一个功能三元组就是一个计划。frame-change / plan-milestones 负责独立子系统或全新的功能形态，不负责这个三元组中遗留的切片。只有用户删除需求时，才缩减范围。只有结果仍是一个纵向切片时，才合并（Step 3）。

想法	实际情况
“28 个任务——把剩余部分分解到后续 ROAD，这样就能通过 Approve”	这个三元组的剩余切片留在此文件中。这样拆分会割裂功能。
“我会把各层合并成一个巨型任务，让文件看起来更小”	横向掩盖仍然是 Step 3 的计划缺陷。

Step 4：覆盖范围与一致性检查

检查项	规则
覆盖范围：audit-trace、行为步骤、seam-table	必需子技能：使用 audit-trace——每项已批准的需求都必须至少被 1 个任务页脚引用（未引用的 ID 表示覆盖不完整，或应说明理由后删除）；仅限文档，测试源代码中不得出现 ID。每个页脚 ID 都需要一个断言行为的 TDD 步骤（或手动／验收步骤），使用领域语言——测试源代码中绝不能出现 [CODE-N.M]、/// REQ: 或 @CODE-N.M；在任务报告／Spec review 中建立 ID 与测试的映射，不要放入生产代码目录。覆盖不等于每个 ID 对应一个测试：如果多个 ID 在同一接缝处具有相同的行为形态（某条规则应用于多个输入、多个默认值），就用一个数据驱动测试覆盖，并为每个 ID 设置一行，页脚仍须引用每个 ID。如果 design.md 有 “Seams for testing” 表格，每一行中的每个 ID 都必须在该接缝处规划测试／验收步骤——承诺覆盖却未覆盖的 ID 属于覆盖遗漏：添加步骤，不要重新编号。
类型／名称 + Reuse 一致性 + reuse-miss	同一函数在所有提及它的任务中必须使用相同名称和签名。标记任何 Reuse: 行与设计部分的 Reuse: 行不一致的任务。还要标记任何 Files Create 所创建的内容已由扫描摘要或已安装依赖提供的任务——应基于已有内容构建（这是 inspect-change 中 reuse-miss 在任务粒度上的对应项；仅供提醒，不是硬性阻断）。
规格对齐 + 上游回写同步	重新阅读一次 requirements.md，逐项核对每条验收标准与声称覆盖它的任务。如果某项需求被证实为错误或不可行（而不仅仅是未覆盖），就在 requirements.md 中更正，并重新提交审批；不要把变通方案藏在任务中，让错误需求继续存在——满足错误需求的计划只会交付错误结论。
独立计划审查（派发审查，不要自行审查）	上述检查仅针对文档，应留在此处；与代码库的比对则不属于此处。派发审查子 Agent，并提供计划、requirements.md、design.md 和代码库；要求其针对真实代码验证计划中声称存在的每个符号、签名、路径、导入项和硬编码测试值——伪造的基准值或猜测的 API 是典型的计划缺陷；引用 file:line，默认标记问题。将发现写入 .skills/<CODE>/plan-review.md；提供执行方案前先修复（没有子 Agent？就自行比对）。检查 一个三元组，一个计划（只有一个归属位置）。

完成条件： 每个需求 ID 都有任务页脚，且在约定的接缝处规划了行为测试；audit-trace、接缝表对照和占位符扫描均无问题。

步骤 5（可选）：发布到问题跟踪器

如果仓库没有跟踪器（不存在 docs/agents/issue-tracker.md，或 Tracker： 为空 / none）→ 跳过此步骤（不算待处理）。否则，阅读此文件旁边的 publish-recipe.md 并严格遵循：确定 Publish unit、撰写问题正文，并将 ID 记录在 .skills/<CODE>/ 下。 默认且唯一对跟踪器可见的单元：每个计划对应 一个功能问题，由功能 PR 关闭。

想法	实际情况
“四项任务 → 四个问题，这样 Agent 就能并行领取”	各批次会读取 tasks.md + Depends-on。跟踪器噪声不等于并行处理
“子问题既能保留层级，又不会产生噪声”	在 feature 单元下，任务不是跟踪器工单
“publish-issues 总是表示每个切片一个问题”	仅适用于非 triad 路径。此步骤遵循 Publish unit
“我会发布任务；用户可以关闭多余的问题”	在 feature 单元下，多余的问题就是缺陷
“任务很多——配置肯定是指 tasks”	数量从不决定 Publish unit；只有文件中的行或用户明确指示才决定

危险信号 — 步骤 5

• 在 feature 单元下：超过一个 triad 问题，或任何标题类似计划任务的问题（Task N:）
• 仅凭计划规模就设置或假定 Publish unit: tasks
• 遇到权限错误后改为发布任务问题

完成条件： 已跳过（没有跟踪器 / 无法发布），或使用 feature 单元且恰好有一个功能问题（合并后的 ID、计划路径、ID 均记录在 .skills/<CODE>/ 下），或使用 tasks 单元，且每项计划任务对应一个问题并已记录 ID。

变更图 — 操作者要求查看时

当操作者要求查看计划会如何变更内容——图片、示意图、地图——展示中必须包含变更图。必需的子技能：使用 craft-page，图示任务为 before/after structure；编写 .skills/<CODE>/change-map.html 并提供其路径。此前四次基线运行都要求绘制图片：一次没有画，三次用 ASCII 画了功能自身的调用链，而没有一次展示 REFUND 的 Task 4 会重写同一个 invoiceView——其中一次画出了合并后的签名 invoiceView(invoice, refunds, today)，但两个计划都没有这个签名。

这些文件是计划中 **Files:** 行列出的每个路径，包括文档——早期有一张 haiku 风格的地图漏掉了计划要修改的 docs/api.md，也因此遗漏了它的负责人。对每个路径运行 grep -ln '<path>' docs/specs/*/tasks.md。页面应展示：

1. 这些文件中的每一个，标明是新增还是已更改，并注明其在 docs/agents/project.md Ownership notes 中的负责人。
2. 计划在这些文件之间新增或更改的调用和导入。
3. 每个已更改接口的外部使用方（设计中的 Surface: 行）。
4. 在图示本身上：grep 列出的其他计划中，凡其 requirements.md 状态不是 Shipped 的，都应作为该文件上的冲突标出，并注明各计划写出的签名或变更。

即使回复中的内嵌图片“涵盖了相同内容”，也不算变更图：三张基线图片都是内嵌图片，而且没有一张标出冲突。

完成条件：页面包含上述全部四项，且每个冲突都标在图示上。

退出

步骤	规则
1–2. 呈现	呈现文件并停止——对话中的同意不等于批准；获批的是书面计划，且 execute 系列只会对获批的 tasks.md 运行。遵循一个三元组，一个计划（一个归属位置）。
3. 获批后	设置 Status: Approved。将 Execution-mode: 保持为 unset（或不做更改）；不要自行填写 continuous 或 story-unit。
4. 提供三条路径	恰好三条，只问一个问题——不要先询问 continuous 还是 story-unit（这类访谈已废弃）；模式回写由所选技能负责。build-by-story：子 Agent 路径，根据故事拆分为需人工把关的审查单元（写入 story-unit）。build-in-waves：子 Agent 波次，任务之间无需人工暂停（写入 continuous）。build-inline：控制器使用 test-first 按顺序实现，不使用实现者子 Agent（将 continuous 作为记录信息写入；不运行单元关卡）。建议（仅标记，不臆造模式）：当面向用户的 UI/UX、Team Solo/Small，或 requirements.md 中有≥2 个行为故事时，将 build-by-story（推荐） 标为首选——仍须提供全部三条路径，仍须等待用户选择；没有符合条件的触发因素时，不做标记（不臆造模式，也不按规模默认——见下方关卡表）。
5–6. 选择后，更新 INDEX	说明技能名称并移交——必需子技能：使用所选的 build-in-waves、build-by-story 或 build-inline（对于两条子 Agent 路径，如果尚无隔离工作区，优先使用必需子技能：先使用 isolate-workspace）。然后确认 docs/specs/INDEX.md 中该功能对应行的 Status: 与其 requirements.md 一致。

想法	实际情况
“PM 说只要标记为 Approved——continuous 显而易见”	提供三个技能。不要臆造模式。
“我先问 continuous 还是 story-unit，然后再提供路径”	只问一个问题：选择三个技能中的哪一个。
“我现在就填写 Execution-mode，这样计划看起来才完整”	模式由执行技能填写。

退出红旗

• 在提供三个技能之前询问 continuous 还是 story-unit
• 设置 Status: Approved 时臆造 Execution-mode:
• 因为任务数量而将这个三元组剩余部分拆分到新的 ROAD
• 只提供一条路径，或将“LGTM，开始构建”视为 build-in-waves
• 满足“建议”条件时，未在 build-by-story 上标注“（推荐）”

完成条件：****一个三元组，一个计划得到遵循，Status: Approved， 已指定三个执行技能之一（并在用户选择后移交）， 此处未臆造 Execution-mode:，且 INDEX.md 中的对应行一致。