speckit-plan

用户输入

$ARGUMENTS

继续之前，必须考虑用户输入（如果不为空）。

执行前检查

检查扩展钩子（规划前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取该文件并查找 hooks.before_plan 键下的条目
• 如果 YAML 无法解析或无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），且未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后正常继续
• 筛除 enabled 明确设为 false 的钩子。未设置 enabled 字段的钩子默认视为启用。
• 对于其余钩子，不要尝试解读或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 根据钩子命令名称构造命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：

  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选前置钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    
    等待钩子命令完成后，再继续到大纲部分。
    

    输出上述内容后，必须实际调用钩子，并等待其完成后再继续。按照你在此 Agent/会话中自行运行命令的方式来运行它（实际调用方式可能与显示的 {command} ID 不同，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出该内容并不能运行钩子。

• 如果没有注册任何钩子，或者 .specify/extensions.yml 不存在，则默默跳过

大纲

1. 设置：从仓库根目录运行 .specify/scripts/bash/setup-plan.sh --json，并解析 JSON 中的 FEATURE_SPEC、IMPL_PLAN、FEATURE_DIR、BRANCH。对于参数中的单引号，例如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 加载上下文：读取 FEATURE_SPEC 和 .specify/memory/constitution.md。加载 IMPL_PLAN 模板（已复制）。

3. 执行规划工作流：按照 IMPL_PLAN 模板的结构：

   • 填写 Technical Context（将未知项标记为 "NEEDS CLARIFICATION"）
   • 根据 constitution 填写 Constitution Check 部分
   • 评估各关卡（未获合理说明的违规项标记为 ERROR）
   • 阶段 0：生成 research.md（解决所有 NEEDS CLARIFICATION）
   • 阶段 1：生成 data-model.md、contracts/、quickstart.md
   • 设计完成后重新评估 Constitution Check

强制性执行后钩子

在向用户报告完成之前，必须完成本节。

检查项目根目录中是否存在 .specify/extensions.yml。

• 如果文件不存在，或 hooks.after_plan 下未注册任何钩子，则跳转至完成报告。
• 如果文件存在，请读取并查找 hooks.after_plan 键下的条目。
• 如果 YAML 无法解析或无效，请勿默默跳过：告知用户无法读取 .specify/extensions.yml（包含解析器错误），并说明未检查任何钩子，包括在那里注册的任何强制性（optional: false）钩子，然后继续生成完成报告。
• 筛除 enabled 明确设为 false 的钩子。未包含 enabled 字段的钩子默认视为已启用。
• 对于每个剩余的钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null／空值，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 根据钩子命令名称构建命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行的钩子，根据其 optional 标志执行以下操作：

  • 强制性钩子（optional: false）——每个强制性钩子都必须输出 EXECUTE_COMMAND:：

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述区块后，必须实际调用该钩子，并等待其完成后再继续。以你在此 Agent／会话中自行运行命令的方式运行它（实际调用方式可能与上方显示的 {command} 标识不同，例如，skills 模式 Agent 会以 /skill:speckit-... 或 $speckit-... 的形式运行）。

  • 可选钩子（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

完成报告

命令在 Phase 1 设计结束后终止。报告分支、IMPL_PLAN 路径和生成的产物。

阶段

阶段 0：大纲与调研

1. 从上方的技术上下文中提取未知项：

   • 对于每个 NEEDS CLARIFICATION → 调研任务
   • 对于每项依赖 → 最佳实践任务
   • 对于每项集成 → 模式任务

2. 生成并分派调研 Agent：

   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   

3. 在 research.md 中汇总调研结果，格式如下：

   • Decision：[选择的方案]
   • Rationale：[选择该方案的原因]
   • Alternatives considered：[评估过的其他方案]

输出：包含所有已解决 NEEDS CLARIFICATION 的 research.md

阶段 1：设计与契约

前置条件： 已完成 research.md

1. 从功能规格中提取实体 → data-model.md：

   • 实体名称、字段、关系
   • 需求中的验证规则
   • 适用时的状态转换

2. 定义接口契约（如果项目有外部接口）→ /contracts/：

   • 确定项目向用户或其他系统公开了哪些接口
   • 记录适合项目类型的契约格式
   • 示例：库的公共 API、CLI 工具的命令模式、Web 服务的端点、解析器的语法、应用的 UI 契约
   • 如果项目纯属内部使用（构建脚本、一次性工具等），则跳过

3. 创建快速入门验证指南 → quickstart.md：

   • 记录可运行的验证场景，以证明功能端到端正常工作
   • 包含前置条件、设置命令、测试／运行命令及预期结果
   • 使用指向契约和数据模型详情的链接或引用，避免重复
   • 不要包含完整的实现代码、模型／服务／控制器主体、迁移文件或完整测试套件
   • 此文档应作为验证／运行指南；实现细节应放在 tasks.md 和实现阶段

输出：data-model.md、/contracts/*、quickstart.md

关键规则

• 文件系统操作使用绝对路径；文档中的引用使用项目相对路径
• 遇到关卡失败或未解决的疑问时报告错误

完成条件

• 已执行规划工作流并生成设计文档
• 已按上述“强制执行后钩子”中的规则分发或跳过扩展钩子
• 已向用户报告完成情况，并提供分支、计划路径和生成的文档