plan

计划

你正在运行 Agent 工具包流水线的 plan 阶段。脊柱阶段 3。你的任务是将已确认的 architecture.md + decisions.md 决策拆解为 plan.md 中完整、详尽的任务清单。进入 implement 前，不得遗留任何未解决的重大歧义。

运行辅助脚本

此技能将辅助脚本打包在自身的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设为此技能的绝对路径——文件末尾的 此技能的基础目录 会显示该路径——然后从项目根目录运行脚本（脚本会操作项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。切勿引用 packages/build/——此路径仅存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

此处不做任何架构决策。如果遇到本应在 specify 阶段解决的歧义，请标记出来，并告知用户重新运行 specify（退回处理）。不要自行编造答案。

计划必须为每个部分的实现者提供所需上下文、可观察结果、约束和验证方式，但不能替其决定私有实现机制。

计划是功能规格说明，而非实现产物。描述外部相关的输入、输出、状态转换、验证、错误、不变量、顺序保证和验收依据。不要规定私有控制流、辅助功能拆分、本地数据结构、内部调用顺序、源代码主体、类似特定编程语言的伪代码或围栏代码块。列出公开或已确认的符号；仅当 decisions.md 固定了相关契约时，才附上一行签名。实现者自行选择惯用、符合语言习惯的本地／私有／可逆实现机制。

前置条件

加载 manifest.yaml。验证：

• phase 为 plan（specify 审批状态为 approved）。
• approvals.plan 为 pending。
• architecture.md 和 decisions.md 均存在。

如果前置条件不满足，请告知用户具体问题。

先加载 change-brief.md，然后仅在计划需要相关决策或衔接点时打开 architecture.md 和 decisions.md。阅读 references/engineering-fundamentals.md。对范围内涉及的每种语言，在可用时使用其 idioms 技能；如果相应工具包不可用，则遵循仓库惯例和工具链。运用这些指导，避免计划违背语言惯例，但不要过度约束私有实现方式。

阶段 1：拆分章节

将实现划分为逻辑章节。规则：

• 每个章节都可独立执行。实现者只需阅读正在处理的章节。
• 章节应对应组件、功能或层，而非随意按行数划分。
• 每个章节结束时，测试基线必须为绿色（不进行逐章节重构）。
• 最后一个实现章节之后，计划必须包含一个评审章节（对整个变更进行独立评审 + 保持行为不变的重构），随后进行文档协调（不可妥协）。

自主选择符合惯例的章节划分方式。只有在不同划分方案跨越重大性边界时才询问用户；否则，不要为常规拆分寻求确认。

阶段 2：编写 plan.md

对于每个章节，使用 references/templates/plan.md.tmpl：

测试任务

• 对本章节涉及的每个确定衔接点，至少设置一个测试任务。标签：[seam: <id>, firmness: firm]
• 根据需要为软衔接点设置测试任务。标签：[seam: internal, firmness: soft]
• 每个章节中，测试任务必须排在实现任务之前（先失败、后通过）。
• 写明具体断言（测试必须验证什么）和计划使用的文件路径。

实现任务

• 每项任务都是一个具体、范围明确的成果。指定文件或已确认的契约，但不要为实现者臆造私有辅助项、类型、特征或拆分方式。
• 包含目标文件路径。
• 提供足够上下文以确定所需成果：目标路径、已确认的契约（如有）、可观察行为、相关状态转换、验证/错误语义、不变量和验收证据。
• 将私有辅助项、本地表示、控制流和等效的惯用机制留给 implement 决定。
• 引用所实现的决策或验收标准：(implements [SEAM-<id>]) 或 (per decisions.md Q<n>)。

例如，持久化任务应说明经过验证的输入、原子性或顺序保证、获批的错误契约以及可观察结果。它不应规定私有辅助项、七步控制流方案或函数体。由 implement 决定惯用的源代码表达方式。

验证任务（每个章节）

• [ ] 运行测试 — 章节达到通过基线

审查章节任务（所有章节完成后执行一次）

• [ ] 由新的审计员进行一次广泛且适用的探索审查；记录一个合并的 RV-NNN 阻断/主要问题批次，包含类别、证据、影响和替代方案
• [ ] 针对整个批次实施一次保持行为不变的修正（firm-seam 测试保持通过）
• [ ] 修正后完整测试套件通过
• [ ] 由不同的新验证员仅检查原始 RV ID；最多进行一次针对性修正/复核；使用 review-log.mjs 记录批准

阶段 3：可追溯性检查

定稿前，验证：

1. architecture.md 和 decisions.md 中的每项验收标准都至少对应一项任务。
2. 每个 firm seam 都至少有一项 firm-seam 测试任务。
3. architecture.md 中每项获批的重构都有明确的任务。

在 plan.md 中填写可追溯性表。如果有任何标准未覆盖，添加缺失的任务。

阶段 4：退回检查

如果规划过程中发现一个或多个缺失的重要决策，将它们合并后停止。告知用户：

"我发现决策中有一项本应由 specify 解决的歧义：[描述]。我无法为此编写可靠的计划任务。请运行 specify 解决后再继续。"

记录退回事项：

  node "$SKILL_DIR/scripts/kickback-log.mjs" --id <id> --type defect --phase plan --impact specify --missed "<description>"

缺少重要决策时使用 --impact specify。如果只需更改清单可追溯性或任务细节，则使用 --impact plan；这会保留 specify 的批准状态。不要臆造答案，也不要在相关产物解决前继续。

阶段 5：写入文件

写入：.changes/active/<id>/plan.md

阶段 6：批准

说明章节数、任务总数、firm-seam 测试数和可追溯性检查结果。询问：

"可追溯性检查已通过。所有 firm seam 都有测试任务。批准前将运行确定性的产物验证。你是否批准该计划？（这将进入 implement 阶段。）"

批准后：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval plan --approve

告知用户：接下来运行 implement。

参考文件

• references/seam-and-test-taxonomy.md — 稳定性模型、测试任务标注规则
• references/manifest-schema.md — 退回事项记录
• references/change-lifecycle.md — implement 的预期内容
• references/adversarial-review.md — 有界审查周期和 RV-* 问题
• references/templates/plan.md.tmpl
• idioms 技能 — 加载范围内所有可用的 pack
• references/engineering-fundamentals.md — 跨语言的数据、状态、抽象和有界资源指导