write-plan

根据已批准的需求和设计，生成 docs/specs/<YYYY-MM-DD>-<feature>/tasks.md。从技能集的 templates/tasks.md 开始——作为插件安装时，将 templates/ 解析为 ${CLAUDE_PLUGIN_ROOT}/templates；否则，相对于此 SKILL.md 使用 ../../../templates。任务块中的每个槽位（Files、Interfaces、Depends-on、Steps、_Requirements:_）都是必填项。不要编写逐任务风险标签、决策面标记或 Human-review-order 章节——风险根据实际差异与 allocate-attention 风险 glob 的匹配情况衡量；当 Execution-mode: story-unit 时，审查单元会在 execute-story 阶段根据用户故事推导（参见该技能）。

开始前，先为每个步骤（1–4；如果仓库使用问题跟踪器，再加上 5）创建待办事项，并按顺序完成——此技能管理自己的列表，与上游的 write-design 列表和下游的 execute 系列列表相互独立。只有满足相应的 Done when: 条件时，才勾选该事项。

面向技能娴熟、但对该代码库或问题领域一无所知的实现者来编写；他们只能看到自己的任务和全局约束。任务中必须包含他们所需的每个名称、路径、命令和类型。

Step 1: 标题和全局约束

目标（一个句子）、架构（2–3 句）、技术栈。标题中还必须包含以下字段：

Execution-mode: <unset | continuous | story-unit>

提供了一种路线。模式是必须填写的字段。 在 Exit 之前，值保持为 unset——切勿根据计划大小、分级或习惯臆造 continuous/story-unit。此字段没有项目级默认值。

然后编写 Global Constraints：从设计和 docs/agents/project.md 原样复制项目级规则——测试、lint、类型检查命令，命名和 i18n 规则，以及禁止进行的更改。每个任务的要求都默认包含本节内容；它会随每个任务说明一起传递。当存在 ## Team，且其中包含非空的团队名单或分级覆盖设置时，只根据该节确定分级并应用任务打包方式：Solo 任务不要假装有多个负责人；Small/Multi 可添加可选的自由格式负责人/审查备注（绝不能新增必填任务字段）。缺少 Team 时，使用功能开发前的默认设置。

如果存在 docs/architecture/ 架构主干，还要将其中严格的 **ARCH-N** 不变量纳入 Global Constraints，使每个任务都继承这些约束；如果不存在架构主干，则无需纳入任何内容。面向人的工程规则（命名、i18n、团队规范）应取自 docs/product/guidelines.md（如果存在），否则按上述说明取自 docs/agents/project.md——如果存在 guidelines 文档，相关规则应以该文档为准。

Done when: 已写明 Goal、Architecture、Tech Stack、Execution-mode:（可以仍为 unset）和 Global Constraints；且该节中的每条命令、命名/i18n 规则及 ARCH-N 不变量，均已从源文件原样复制，而非改写。

Step 2: 先列出文件结构

先列出计划创建或修改的每个文件，并为其写明一行职责说明，之后再编写任务。文件若未列入清单，任何任务都不得触碰。

Done when: 计划创建或修改的每个文件都已列入清单，并附有一行职责说明。

步骤 3：将任务拆分为垂直切片

**约定 — 任务是一个垂直切片：**它是最小的工作单元，拥有自己的测试周期，并值得单独给出评审结论。只有当评审者可以拒绝一个任务，同时批准其相邻任务时，才进行拆分。

形式：如果工作对应一个用户故事，每个任务应有一个可演示的端到端结果。仅为后续切片铺路的预重构应作为更早的独立任务（“先让修改变简单，再进行简单的修改”），并通过 Depends-on 边连接 — 而不能成为在故事任务中埋入横向分层的借口。

每个任务：

• **文件：**创建 / 修改（确切路径；已知时注明行范围）/ 测试。
• **复用：**本任务所基于的具体现有代码、库或模式 — 从设计部分的 Reuse: 行原样沿用，并保持相同的 <rung> — <concrete target> 语法，以便实现者知道要基于它构建，而不是重新实现它（例如，Reuse: existing — src/util/dates:parseISO (rung 2)，从设计部分的 Reuse: 行原样复制）。 步骤 4 会根据设计部分的 Reuse: 行核对它，因此应复制，而不是重新解释。
• **接口：**使用 / 产出 — 相邻任务共享的名称和类型。这个部分能让独立实现者知道该如何调用。
• **依赖项：**本任务真正依赖的先前任务 — 即本任务使用其接口，或基于其文件构建的任务 — 写作 Depends-on: Task 2, Task 4；若没有前置依赖，则写作 Depends-on: none。这是并行信号：两个任务若不共享文件和接口，就不声明依赖边，这样 execute-plan 就能在同一个并行批次中同时执行它们。省略此行时，任务会退回到依赖所有先前任务 — 安全，但完全串行。过度声明依赖会造成不必要的串行；依赖声明不足则会在发生冲突前被执行器的文件互斥检查捕获。
• **步骤：**简短的复选框任务（每项 2–5 分钟），遵循 TDD 周期：失败的测试（完整代码）→ 运行，预期出现所述失败 → 实现（完整代码）→ 运行，预期通过 → 提交，并附上 Implements: CODE-N.M 标记。
• 页脚：_Requirements: CODE-N.M, CODE-N.M_ — 本任务实现或保障的 ID。每个任务都必须有页脚。默认：一个故事的 ID（故事编号 N 相同）。多个故事的页脚会将这些故事合并为 execute-story 下的一个评审单元（这是计划质量信号 — 并非禁止这样做，也不是谎报 Depends-on 的理由）。

Depends-on 决定构建批次。如果仅为整理评审单元而调整顺序或缩减依赖会歪曲任务的实际需求，则绝不要这样做。

想法	实际情况
“总应该先做预重构 — 让修改变简单”	通过 Depends-on 添加预重构没问题；在 execute-story 中，评审单元仍由故事引用决定
“我要加上 Risk: high，让评审者注意”	没有这个字段。实际差异内容上的风险 glob 会取代 Agent 标签
“我要写 Human review order，告诉人类应该先看什么”	已被取代：源自故事的单元就是评审顺序；没有使用方的第二份自定义列表毫无意义
“PM 说直接标记 Approved 就行 — 连续模式显而易见”	显而易见不等于已写明。Execution-mode 为空就不算 Approved
“五分钟后开会 / 计划花了 40 分钟 — 跳过模式问题”	时间和沉没成本会改变何时询问，而不是模式是否是一个字段
“四个任务 → 默认连续模式”	没有基于规模的默认值。由用户选择连续模式或故事单元模式

不要使用占位内容。“TBD”、“添加适当的错误处理”、“与 Task 3 类似”，或某个类型被引用但没有在任何任务中定义 — 这些都是计划错误。计划发布前必须修复。

**完成标准：**步骤 2 地图中的每个文件都至少由一个任务覆盖，并且每个任务都写成带有自身测试周期的垂直切片。条目和占位内容是否规范，由步骤 4 检查，而非本步骤检查。

步骤 4：覆盖与一致性检查

• 运行追踪检查（必需子技能：使用 trace）：每项已批准的需求都必须至少在 1 个任务页脚中被引用。未被引用的 ID 表示计划不完整（或者应当划掉该需求并说明原因）。
• 检查测试覆盖，而不只是引用： 每个需求 ID 还必须出现在某个任务步骤中的测试注释里（Vitest 标题中的 [CODE-N.M]、Rust 测试上的 /// REQ: CODE-N.M、Playwright 标签中的 @CODE-N.M）——不能只出现在页脚中。页脚引用没有带标签的测试，现在通过追踪检查（Approved → W1），但功能一旦标记为 Implemented，就会在 E2 中失败。只有真实测试断言了守卫或负向需求，该需求才算覆盖；如果某种行为无法单独进行单元测试，就给端到端测试任务或已有的、能够覆盖该行为的测试加上标签——一个测试可以包含多个 ID。
• 对照设计中的接缝表： 如果 design.md 中有“用于测试的接缝”表格，每行中的每个 ID 都必须在计划中的某个测试上加标签。设计承诺覆盖但计划未加标签的 ID 属于覆盖缺失——添加测试，不要重新编号。
• 任务之间的类型/名称必须保持一致：同一个函数在提及它的每个任务中都必须具有相同的名称和签名。
• 组件级复用遗漏： 标记任何 Files Create 中创建了扫描摘要或已安装依赖项中已有内容的任务——应基于已有内容构建，而不是重新实现。这是 code-review 针对功能重叠提出的 reuse-miss 在任务粒度上的对应项；它是建议性发现，不是硬性阻止项。
• 复用一致性： 标记任何 Reuse: 行与其所实现的设计部分中的 Reuse: 行不一致的任务。
• 规范对齐：重新阅读一次 requirements.md，逐项核对每条标准与声称满足它的任务。
• 上游同步回写：如果规划发现某项需求按原文表述是错误的或不可行的——而不只是未覆盖——请在 requirements.md 中更正并重新提交审批。不要把变通方案藏在任务中，却让错误需求原样保留；满足错误需求的计划会把错误一并交付。

独立计划审查——派发审查，不要自我审查。 上述检查仅针对文档，应在此处完成；与代码库的对照则不应在此处完成。派发一个审查子代理，提供计划、requirements.md、design.md 和代码仓库；让它对照真实代码核实计划中声称的每个符号、签名、路径、导入和硬编码测试值——虚构的预期值或猜测的 API 是典型的计划缺陷——并引用 file:line，默认标记问题。将发现写入 .skills/<slug>-plan-review.md；在提供执行方案前修复。（没有子代理？请自行对照代码完成检查。）

完成条件： 每个需求 ID 都有任务页脚引用和带标签的测试，追踪检查通过，设计接缝表中的所有 ID 都已覆盖，且占位符扫描通过。

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

如果仓库使用问题跟踪器（docs/agents/issue-tracker.md），请按依赖顺序将每个任务发布为一个问题——在支持的情况下使用原生子问题和阻塞链接；问题正文描述行为和接口（绝不包含文件路径），并包括验收标准和 Requirements covered: 列表。

这是重量级、可追踪的发布路径——每个问题都包含其需求 ID。对于记录从未经过规范三件套流程的工作（原始对话或想法），用户应改用 file-issues；不要在那里重复创建这些任务。

完成条件： tasks.md 中的每个任务都有对应问题，每个问题都包含其 Requirements covered: 列表，阻塞链接与计划的依赖顺序一致。未配置跟踪器 → 跳过此步骤，不视为待办。

退出

向用户展示 FILE，然后停下来等待批准——对话中的同意不算批准；获批的是书面计划，而 execute 系列技能只会在获批的 tasks.md 上运行。

Execution-mode 是批准的一部分，而非执行路径。 在设置 Status: Approved 之前，用户必须选择 Execution-mode: continuous 或 Execution-mode: story-unit，并且你必须将该值写入标头。 unset、空值或缺失 → 不要设置 Status: Approved。绝不要因为该字段为空就默认使用 continuous；空值意味着尚未批准。

模式	含义
continuous	任务之间无需人工暂停（子 Agent 路径）
story-unit	根据故事划分、需要人工把关的审查单元（子 Agent 路径）

写入模式并且用户批准计划后，设置 Status: Approved，并提供恰好三种执行路径（如何运行；对于 inline，此选择与模式正交）：

1. execute-plan —— 当 Execution-mode: continuous 且需要子 Agent 工作波次时使用（continuous 的推荐默认选项）。优先通过 worktrees 使用隔离工作区。
2. execute-story —— 当 Execution-mode: story-unit 时使用（单元关卡必需；story-unit 不要提供 execute-plan）。优先使用 worktrees。
3. execute-inline —— 控制器使用 tdd 按顺序实现，不使用实现子 Agent（适用于无子 Agent 的环境，或用户希望逐步查看每个步骤的情况）。适用于任一标头模式；不会运行单元关卡。

先说出与所选模式对应的技能；如果用户选择不使用子 Agent，则说出 execute-inline。确认 docs/specs/INDEX.md 中该功能对应行的 Status: 与其 requirements.md 中的状态一致。

完成条件： 用户已批准书面的 tasks.md，Execution-mode: 为 continuous 或 story-unit，Status: 显示 Approved，已说出对应的 execute 技能，并且 INDEX.md 中的行与之匹配。