spec-plan

Spec 计划

编写一份比例适当、清晰到任何工程师都能照着执行的计划。所选规划模式决定计划是保留在对话中，还是成为持久化的结构化产物。此技能不会编写代码或启动实现。

atelier-orchestrator 负责自动分类，人类可以覆盖其判断。直接调用此技能且未选择模式时，使用 Spec 支持的计划。如果 Inline 规划发现存在大量设计或协调需求，请在呈现计划前询问人类是否切换为 Spec 支持的计划。

终止边界

此技能只生成一份计划，然后停止：

• Inline 模式在对话中呈现计划，不更改任何仓库文件。
• Spec 支持的模式仅根据已批准的 design.md 创建或更新 plan.json。

规划草稿和批注周期都应留在对话中。不要修改 design.md、持久化 Markdown 计划草稿、创建跟踪条目、调用其他工作流技能或编辑实现文件。即使人类在同一请求中要求规划并实现，这些规则仍然适用。此技能完成后，必须另行明确请求才能开始实现。

规划规则

• 围绕所需行为组织任务，而不是每层一个任务。
• 简要列出必须保留的行为。
• 对每项任务，指出要复用、修改或删除的现有代码。
• 将每个新抽象对应到当前需求及其现有使用方。
• 只有在至少两个现有使用方体现出相同需求时，才引入共享基础设施。
• 按变更的契约和活跃边界对测试分组。不要在各层重复 CRUD 矩阵。
• 在各模块的接口处规划测试，不要越过接口测试（参见 oracle-codebase-design）。

比例审查关卡

呈现任何计划前，将计划的规模和概念与所请求的行为进行比较。如果范围明确的迁移或重构引入了共享基础设施、不相关的行为，或计划规模远超所变更的行为，请停下来简化计划。

挑战审查关卡

呈现计划前，将草稿计划及其设计上下文并行分发给两个只读子 Agent。明确选择每个 Agent（参见 atelier-orchestrator 中的 Delegation）：

1. **设计审查：**检查架构适配性、分层和数据模型边界、API 契约，以及任务顺序是否遵循依赖关系。
2. **批判性挑战：**质疑假设，查找遗漏情况、范围蔓延和未经证实的需求，并提出更简单的替代方案。

每个 Agent 最多返回五条有证据支持的发现。纳入有效发现，说明理由后舍弃其余发现，并附上一条简短的 已审查 说明，列出所做的更改。

每份 Spec 支持的计划都必须通过此关卡。只有当 Inline 计划涉及数据模型、API 契约或多个模块或层时，才运行此关卡；小范围、边界明确的编辑可跳过。每份草稿只运行一次；除非计划结构发生变化，否则在人类批注修订时不要重新运行。

输出

Inline 计划（明确选择时）

不生成仓库产物，也不创建任务跟踪条目。阅读 references/plan_template.md，并按其结构在对话中呈现计划。省略可选小节，不要显示空标题。

内联计划工作流

阅读足够多的代码库内容，以确定当前行为、边界、受影响的文件以及具体的验证方式。计划的细致程度应与实现风险相称。使用已确认的文件和符号级详细信息填写模板，并纳入相关的跨文件连接或顺序约束。提交计划前，应用 Planning Rules、Proportionality Gate 和 Challenge Gate。

不要凭空编造阶段、任务 ID、依赖关系图、验收矩阵、design.md、plan.json、跟踪器条目或测试框架待办事项。对话就是计划产物。

告诉用户：“内联计划已准备好，等待审核。”

停止。等待用户审核。

如果用户要求调整，将调整应用到当前计划，并使用 references/plan_template.md 重新呈现完整的更新后计划。包含未更改的部分，以便用户审核一份完整统一的计划。绝不要只回复更改的文本、受影响的部分、摘要或确认信息。即使只更正一个词，也算计划修订：请将其纳入计划并重新完整呈现。

每次修订都会使先前的批准失效。每次修订后的计划都以“内联计划已准备好，等待审核。”结尾，并停止，直到用户明确批准该完整版本。当前计划获批前，不要开始实现。

用户批准内联计划后，确认计划已获批并停止。不要在同一次调用中开始实现。之后用户明确要求实现时，可根据 atelier-orchestrator 中的 Inline execution safeguards，直接执行已获批的对话计划；不使用 spec-implement、spec-finish、code-subagents 或任务跟踪。

基于规范的计划产物

docs/specs/YYYY-MM-DD-<feature-name>/
├── design.md  ← From spec-brainstorm (approved)
└── plan.json  ← This skill's output

计划最初以对话草稿的形式呈现，供用户批注；获批后，再转换为结构化的 plan.json。

plan.json 架构

{
  "feature": "user-authentication",
  "spec": "docs/specs/2026-03-08-user-auth/design.md",
  "goal": "Add email/password authentication with session management",
  "preserved_behavior": [
    "Existing sessions remain valid"
  ],
  "phases": [
    {
      "id": "P1",
      "name": "Authenticate with email and password",
      "tasks": [
        {
          "id": "T1",
          "name": "Accept valid credentials and reject invalid credentials",
          "depends_on": [],
          "inputs": [
            "User schema from design.md",
            "Validation rules (email format, password strength)"
          ],
          "description": "Create UserEntity with email and password fields. Implement validation using a Result type. Password must be hashed, never stored plaintext.",
          "files": {
            "reuse": ["src/auth/password.ts"],
            "create": ["src/entities/user.ts", "tests/entities/user.test.ts"],
            "modify": [],
            "delete": []
          },
          "new_abstractions": [
            {
              "name": "UserEntity",
              "requirement": "Validate email/password credentials",
              "consumers": ["POST /sessions"]
            }
          ],
          "validation": {
            "tests": [
              "rejects empty email",
              "rejects invalid email format",
              "rejects weak password",
              "accepts valid user input"
            ],
            "acceptance": [
              "All validation tests pass",
              "User.fromRequest returns Result<User>",
              "No direct throws — all errors via Result"
            ]
          }
        }
      ]
    }
  ]
}

顶层字段

字段	类型	描述
feature	string	kebab-case 格式的功能名称
spec	string	已批准的 design.md 路径
goal	string	用一句话描述目标
preserved_behavior	string[]	必须保持不变的现有行为简表
phases	Phase[]	按依赖顺序排列的实现阶段

阶段字段

字段	类型	描述
id	string	阶段标识符（P1、P2……）
name	string	阶段名称（例如“领域模型”“数据访问”）
tasks	Task[]	此阶段中的任务

任务字段

字段	类型	描述
id	string	任务标识符（T1、T2……）
name	string	此任务实现的内容
depends_on	string[]	必须先完成的任务 ID
inputs	string[]	开始前需要了解的信息
description	string	要构建的内容、关键决策和约束
files	{reuse, create, modify, delete}	要复用、修改或删除的现有代码，以及要创建的文件
new_abstractions	{name, requirement, consumers}[]	与现有需求及当前使用方对应的新抽象
validation	{tests, acceptance}	验证任务是否完成的方式

---

基于规范的步骤 1：编写计划草稿

阅读已批准的 design.md，对草稿应用 Challenge Gate，然后在对话中呈现计划草稿。不要将草稿写入 design.md，也不要创建单独的草稿文件。

计划质量

编写计划时，应假设实现者：

• 了解语言和框架
• 不熟悉此代码库的具体模式
• 需要明确的边界和验证标准
• 如果计划含糊，会选择阻力最小的路径

任务结构

每个任务都应自成一体，并包含：

• 输入：开始前需要了解或准备的内容（来自规范、现有代码）
• 描述：要构建的内容、关键设计决策和约束
• 文件：要复用、修改或删除的确切现有代码，以及要创建的文件
• 新抽象：说明每项抽象的当前需求和现有使用方；如果任务不新增抽象，则使用空列表
• 验证：按变更契约和当前边界分组的测试，以及验收标准

不要提供确切的代码片段。不要提供实现细节。任务说明要做什么以及如何验证， 而不是如何编写代码。

任务排序

按所需行为和实际依赖关系排列任务。若多个层的变更共同实现并验证同一项契约，就将它们放在同一个任务中；不要按层拆分任务。

任务规模

每个任务应耗时 15–60 分钟。如果耗时更长，则拆分为更小的任务。

告知人工审阅者：“计划草案已准备好，等待审阅。”

停止。等待人工审阅。

---

有规范支撑的第 2 步：批注周期

人工审阅者直接在计划草案中添加批注——包括更正、否决、领域知识、业务约束，或“完全删除此项”。

You write plan → Human adds inline notes → You address all notes → Repeat 1-6x

当人工审阅者说“我添加了批注”时：

1. 重新阅读整份文档
2. 处理每一条批注
3. 更新计划
4. 不要创建任务。不要实施。

“暂不实施”的约束至关重要。在人工审阅者明确批准前，计划都尚未就绪。

指导模式

模式	示例	操作
更正假设	“使用 PATCH，而不是 PUT”	修正
否决方案	“删除缓存，我们不需要它”	彻底移除
添加约束	“队列消费者已经会处理重试”	调整结构
覆盖选择	“使用 drizzle:generate，而不是原始 SQL”	直接覆盖
调整章节方向	“在列表上显示，而不是在条目上显示”	重新考虑该章节
缩减范围	“移除下载功能，现在不实现”	移除，不留存根

---

有规范支撑的第 3 步：创建结构化任务

人工审阅者批准后——“看起来不错”“已批准”“创建任务”——将计划转换为 plan.json。

操作内容

1. 将带批注的计划草案转换为结构化的 plan.json
2. 每个任务对应一个单元，包含输入、描述、文件和验证
3. 在 depends_on 字段中记录任务之间的依赖关系
4. 不要创建跟踪器条目，也不要修改 plan.json 以外的任何文件

验证

创建 plan.json 后，请验证：

• 每个任务都有 ID 和 depends_on 字段
• 依赖关系构成有效的 DAG（无环）
• 每个任务都包含输入、描述和验证
• 保留的行为简短明确
• 每个任务都明确指出要复用、修改或删除的代码
• 每项新抽象都说明其当前需求和现有使用方
• 共享基础设施至少有两个当前使用方，且它们确实存在相同需求
• 文件路径完整且具体
• 验证标准具体、可测试，并按变更契约和当前边界分组
• 计划通过比例性门槛

---

交接

创建 plan.json 后，报告其路径并停止。

告知人工审阅者：

“规划已完成。计划已写入 docs/specs/<path>/plan.json。可通过单独调用 spec-implement 来执行该计划。”

不要调用 spec-implement，不要提供执行模式，也不要开始实施。人工审阅者必须另行发起实施请求。

如果细微的实现偏差不会改变已批准的行为、范围、架构、公开契约或主要依赖关系，可在文中记录，并反映到 plan.json 中。重大变更应返回 spec-plan 重新审批；设计变更应返回 spec-brainstorm。有关迭代模式，请参阅 atelier-orchestrator。

---

快速参考

所选模式／用户说	你要做的事
内联／“写一份计划”	按模板展示完整的内联计划，然后停止
内联／“我添加了备注”	应用这些更改，重新展示完整的更新后内联计划，并停止以等待再次批准
内联／“已批准”	确认已批准并停止；不创建任何产物，也不实施
基于规范／“写一份计划”	根据 design.md 编写计划草稿，然后停止
基于规范／“我添加了备注”	重新阅读并处理所有备注，切勿实施
基于规范／“已批准”／“创建任务”	仅创建 plan.json，报告其路径，然后停止