writing-plans

编写计划

创建可执行的实施计划，降低执行者的理解偏差——开展规模较大的 Phase 1 → Phase 6 工作，并在 /goal 中运行（见下文）。

推荐：在 /goal 中运行

在 Claude Code 内置的 /goal（v2.1.139+）下启动，确保运行会持续到提交计划，而不是中途停止：

/goal "Claude has narrated a successful plan commit (with commit hash) and reported the Phase 4 reflection sub-agent verdicts inline" /superpowers:writing-plans <design-path>

/goal 是由用户输入的外层包装器（技能无法在运行过程中为自身启用它），其评估器只会评判 Claude 在对话记录中的描述内容——应针对描述的输出来措辞条件（提交哈希、Phase 4 反思摘要原文），而不是文件系统状态。完整语义及条件措辞见：../../skills/references/goal-wrapper.md。

关键：中止检查（首先运行）

从解析后的设计文件夹中读取 bdd-specs.md。统计 Scenario: 的出现次数。符合以下任一条件时，中止——不要分解任务：

• bdd-specs.md 中的 BDD 场景少于 3 个，或
• 估算的任务总数少于 5 个（按 2× BDD 场景数 + 1 个设置任务 估算，或优先采用设计 _index.md 中明确写出的 “Task Estimate” 提示）

此 OR 门控可拦截“2 个 BDD 场景 + 多个设置任务”这类 AND 门控会放行的情况。

中止响应（原样输出）：

设计内容过于单薄，不适合完整的任务分解流程（BDD < 3 或估算任务数 < 5）。改为直接起草一页的轻量计划。若要强制运行完整流程，请重新调用 /superpowers:writing-plans --force <design-path>。

然后只编写一个 _index.md（不创建单任务文件、不进行 Phase 4 反思、不运行计划评估器），并退出。--force 标记（$ARGUMENTS 中的字面值，区分大小写，必须是完整标记）可绕过此检查。

关键：合理性检查（中止检查之后运行）

从解析后的设计文件夹中读取 _index.md。如果 grep 命中以下任一内容，则中止——不要分解任务：

grep -nE "STATUS:.*NOT.JUSTIFIED|DESIGN-NOT-YET-JUSTIFIED|DESIGN-CONSIDERED-DEFERRED|DO NOT IMPLEMENT" "<resolved-design-folder>/_index.md"

此检查可拦截明确标记为“未获准推进”的设计（完整语义见：docs/retros/checklists/design-v1.md JUST-01；触发案例见：docs/retros/2026-05-09-v3-considered-deferred.md）。

命中时，按确定性规则拒绝（该标记具有决定性——不得作其他解释）：

1. 输出一行说明：Refusing: <design-path>/_index.md:{N} is marked NOT-JUSTIFIED — '{matched text}'. Re-invoke /superpowers:brainstorming to revise the design, or pass --justify-override to bypass this gate.
2. 不再继续，直接退出。

覆盖选项：传入 --justify-override（$ARGUMENTS 中的字面值，区分大小写，必须是完整标记）可绕过此拒绝，并继续执行“首要操作”。

禁止事项：不得混淆 --force（仅绕过规模门控）与 --justify-override（仅绕过合理性门控）——两者相互独立；对单薄设计使用 --force 并不能绕过 NOT-JUSTIFIED 拒绝。

首要操作——解析设计路径

1. 解析设计路径：
   • 如果 $ARGUMENTS 提供了路径（例如 docs/plans/YYYY-MM-DD-topic-design/），则使用该路径。
   • 否则，选择 YYYY-MM-DD-*-design/ 下按名称排序最后的 *-design/ 文件夹——取名称中日期前缀最高的文件夹，而不是文件系统修改时间：ls -1d docs/plans/*-design/ 2>/dev/null | sort | tail -1（不要使用 ls -t——按修改时间排序会让编辑过的旧文件夹排在新文件夹之前）。直接使用所得结果，不要暂停确认。
   • 如果 docs/plans/ 下不存在 *-design/ 文件夹，则拒绝并输出：Refusing: no design folder found under docs/plans/. Run /superpowers:brainstorming first, or pass the design folder path explicitly. 然后退出。
2. 在同一轮中继续执行初始化。

初始化

1. 设计检查：确认文件夹包含 _index.md 和 bdd-specs.md。起草前查阅文档索引：运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" show <design-path>。如果状态为 expired:，则拒绝执行——输出一行说明，注明已过期的状态，然后退出，不创建计划文件夹。接着查阅记忆：运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active，并在第 1 阶段前读取主题最相关的匹配项。
2. 上下文：完整阅读 bdd-specs.md。这是任务的事实来源。

背景知识

核心概念：明确优于隐含、任务粒度细、验证驱动、上下文独立。

强制要求：单元测试任务必须使用测试替身隔离外部依赖（数据库／网络／第三方 API）。所有其他分解不变量均由第 2 阶段的步骤 1–7 强制执行。

第 1 阶段：计划结构

定义目标、架构、约束和上下文。

1. 阅读规格：阅读设计文件夹中的 bdd-specs.md。
2. 起草结构：使用 ./references/structure-template.md 概述计划。
3. 编写上下文部分：在 _index.md 中填写 ## Context：说明此项工作的必要性（动机、约束、以往事故）；对于现有代码变更，添加当前状态与目标状态对比表（全新项目可省略）。
4. 编写全局约束部分：在 _index.md 中填写 ## Global Constraints 部分——每个批次和每项任务都必须遵守的跨任务不变量（这些约束确保并行批次安全）。每条项目列出一个不变量，不写说明文字；仅当设计完全没有跨领域约束时才省略（这种情况很少见）。类别和示例：./references/structure-template.md §Global Constraints。

阶段 2：任务分解

将工作拆分为小任务，并映射到具体的 BDD 场景。

禁止：不得在流程中要求用户选择粒度、批准分解方案或确认计划；请自动执行步骤 1-7 及以下补充要求。阶段 4 反思是质量关卡，提交后的 git show 差异是审计界面。

• 基础任务（设置、共享架构、类型、配置、存储）使用比功能任务对更小的 NNN 编号
• 将某个功能的所有场景合并到一个测试文件中；仅当该功能跨越相互独立的服务边界（例如前端与后端）时才拆分

1. 引用场景：关键：每个任务文件都必须使用 Gherkin 语法，明确包含完整的 BDD 场景内容，确保内容自包含，而不只是引用 bdd-specs.md，这样执行者无需切换文件即可看到完整场景。格式：./references/structure-template.md §BDD Scenario。
2. 定义验证：关键：验证步骤必须运行 BDD 规范（例如 npm test tests/login.spec.ts）。
3. 强制排序：对于每个功能 NNN，测试任务（task-NNN-<feature>-test）必须通过 depends-on 排在对应实现任务（task-NNN-<feature>-impl）之前。
4. 声明依赖：强制要求：每个任务文件都必须包含 **depends-on** 字段，且只列出真正的技术前置条件——即输出是此任务启动所必需的其他任务。禁止：仅为了规定执行顺序而串联任务。独立性规则和示例：./references/task-granularity-and-verification.md §Dependency Rules。
5. 创建任务文件：强制要求：每个任务创建一个 .md 文件。文件名格式：task-<NNN>-<feature>-<type>.md（例如 task-001-setup.md、task-002-feature-test.md / task-002-feature-impl.md——同一功能的测试和实现任务共享 NNN 前缀；类型：test、impl、config、refactor；完整模板：./references/structure-template.md §Task Files）。
   • 合理控制任务粒度：如果某个独立的设置、配置或文档任务只有一个功能任务会使用其产出，不要单独创建该任务；应将其合并到需要它的任务中。只有当 2 个或更多下游任务共享其产出时，单独创建 task-001-setup 才合理；伪独立的设置任务会造成虚假的并行性，并增加批次数量。
6. 声明接口：强制要求：每个任务文件都必须包含 ## Interfaces 部分（位于 ## BDD Scenario 之后），声明此任务提供或使用的契约（函数签名、类型、API 端点、事件名称、CLI 标志）。通过 depends-on 关联的任务应通过这些部分衔接，这样并行批次就能在合并前验证接口兼容性。
7. 描述做什么，而非怎么做：禁止：不得生成实现代码。描述要实现的内容；## Interfaces 部分中的接口签名用于定义契约，但不得包含实现逻辑。

阶段 3：验证与文档

验证完整性，保存，并在同一轮迭代中进入阶段 4。

1. 验证：检查提交边界是否有效，以及任务是否不存在含糊不清的描述。如果未通过，不要暂停；请在同一轮迭代中返回阶段 2，修复有问题的任务，然后重新验证。
2. 保存：写入 docs/plans/YYYY-MM-DD-<topic>-plan/ 文件夹。
   • 关键：_index.md 必须包含带有内联 YAML 元数据的“执行计划”部分
   • 关键：_index.md 必须包含“任务文件引用”部分，并链接所有任务文件
   • 关键：_index.md 必须包含“BDD 覆盖情况”部分，确认已覆盖所有场景
   • 关键：_index.md 必须包含“依赖链”部分，并附带可视化依赖关系图（将在阶段 4 填写）
   • YAML 元数据和文件引用示例：./references/structure-template.md §Execution Plan

阶段 4：计划反思

提交前，通过并行启动全新的子 Agent（各自在隔离的上下文中，不受主规划会话影响），验证计划质量。

通过 Agent 工具并行启动 3 个子 Agent，subagent_type=general-purpose（完整提示词模板：./references/reflection.md）：

1. BDD 覆盖审查——每个设计场景都有对应任务；输出覆盖矩阵、无对应任务的场景和额外任务
2. 依赖图审查——检查 depends-on 是否正确、有无循环和缺失依赖；输出依赖图
3. 任务完整性审查——检查每个任务是否包含必需结构（BDD 场景、文件、步骤、验证）；输出不完整任务列表

其他子 Agent（按需启动）：Red-Green 配对审查、文件冲突审查。

整合并更新：

1. 收集所有子 Agent 的发现并按影响程度排序
2. 更新计划文件以修复问题
3. 强制要求：将子 Agent 2 的依赖图添加到 _index.md 的“Dependency Chain”部分
4. 重新验证已更新的部分
5. 在本轮输出中内联记录反思摘要（每个子 Agent 的判定和所做更改各 1 行）——这是用户提交后通过 git show 查看审计记录的内容；不要暂停等待批准

输出：更新后的计划、_index.md 中的依赖图、内联反思摘要——可进入阶段 5。

中途取消（仅限在 /goal 下；用户插入“abort”“cancel”或“start over”）：用一行说明后停止——不提交、不进入阶段 5；用户若要重试，可用新的要求重新调用。

多轮续接（仅限在中断后的轮次由 /goal 包装时）：不要从阶段 1 重新开始——运行 Glob "docs/plans/*-plan/_index.md"，读取正在进行的计划文件夹，并根据文件系统指示的阶段继续：任务文件已存在，但 _index.md 缺少 YAML tasks: 块或 References/Coverage 部分 → 阶段 3；_index.md 已完整，但没有“Dependency Chain”图 → 阶段 4；计划已完成但尚未提交 → 阶段 5；已提交 → 阶段 6。

子 Agent 是唯一的计划质量审查者（不另设计划模式评估器；用户将在提交后通过 git show 审查）。它们会以 docs/retros/checklists/plan-v{N}.md 为评审标准。清单中任何一项判定为 FAIL 时，都要修复相应计划文件并重新运行该子 Agent——不要提交存在未处理 FAIL 项的计划。

清单缺失时自动生成：启动反思子 Agent 前，如果不存在 plan-v{N}.md，运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/seed-checklists.sh" plan docs/retros/checklists/plan-v1.md（退出码 0 = 已生成，3 = 已存在 → 继续，1/2 = 中止），然后在每个子 Agent 的提示词中传入解析后的清单路径。

必须：每个反思子 Agent 的提示词都必须包含指令，要求其读取解析后的清单文件，并将每一项作为二元 PASS/FAIL 标准进行评审（./references/reflection.md §Checklist Binding 中的模板包含此指令——不得删去）。未使用清单的子 Agent 提供的只是缺乏依据的意见，而非判定。

阶段 5：Git 提交

使用 git-agent 提交计划文件夹（失败时回退）。

操作： 0. 将计划写入 docs 索引（在 git add 之前）：运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert plan <new-plan-path> --status active --summary "<one-line>"。关键：不得延后——索引更新必须与计划文件夹一同提交。 0.5. 关键：不得延后：条件式记忆写入步骤，仅当阶段 4 的子 Agent 未能首次通过、需要修复后重跑时触发——写入 docs/memory/pitfall_<slug>.md，记录误报原因，然后运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/pitfall_<slug>.md --status active --summary "<one-line>" --category pitfall。如果所有子 Agent 首次均通过，则不执行。

1. 在一条链式命令中暂存并提交整个文件夹——单独运行 git add 会被 git 插件的钩子拒绝：git add docs/plans/YYYY-MM-DD-<topic>-plan/ && git-agent commit --no-stage --intent "add implementation plan for <topic>" --co-author "Claude <Model> <Version> <[email protected]>"
2. 如果出现身份验证错误，使用 --free 标志重试
3. 回退：如果 git-agent 不可用或失败，则通过 Skill 工具调用 /git:commit 技能；完整回退流程见 ../../skills/references/git-commit.md

阶段 6：转入执行

输出：

计划已完成。要执行此计划，请使用 /superpowers:executing-plans。

禁止：不得提出直接开始实现。

退出标准

目标和约束明确，任务已拆解并列出文件及验证方法，包含 BDD 步骤和提交边界，不含含糊任务；反思已完成，所有失败项均已解决，Git 提交已完成。

参考资料

• ./references/structure-template.md - 计划和任务文件模板
• ./references/task-granularity-and-verification.md - 任务拆分、验证和依赖规则
• ./references/reflection.md - 用于计划反思的子 Agent 提示词
• ../../skills/references/git-commit.md - Git 提交模式
• ../../skills/references/goal-wrapper.md - /goal 语义和条件表述（共享）