speckit-plan

speckit-plan

本技能内容源自 GitHub Spec Kit 官方提示词模板。

• 上游：https://github.com/github/spec-kit
• 许可：MIT License, Copyright GitHub, Inc.（完整文本见同目录 LICENSE.txt）
• 适配说明：官方模板面向斜杠命令场景；原文中的 $ARGUMENTS 指用户在对话中给出的请求， 跨命令引用（如 speckit.plan）在本技能体系中对应同名的 speckit-* 技能。 其余内容保持与上游一致，未作改写。

---

用户输入

$ARGUMENTS

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

执行前检查

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

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取该文件并查找 hooks.before_plan 键下的条目
• 如果 YAML 无法解析或无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后正常继续
• 过滤掉 enabled 明确为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对其余每个钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 对每个可执行钩子，根据其 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. 设置：从仓库根目录运行 {SCRIPT}，并解析 JSON 获取 FEATURE_SPEC、IMPL_PLAN、FEATURE_DIR、BRANCH。对于参数中的单引号，例如 "I'm Groot"，使用转义语法，例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

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

3. 执行规划工作流：遵循 IMPL_PLAN 模板中的结构，以便：

   • 填写技术上下文（将未知项标记为 "需要澄清"）
   • 根据宪章填写宪章检查部分
   • 评估关卡（若存在未合理说明的违规，则报错）
   • 阶段 0：生成 research.md（解决所有需要澄清的事项）
   • 阶段 1：生成 data-model.md、contracts/、quickstart.md
   • 设计完成后重新评估宪章检查

执行后强制钩子

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

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

• 如果文件不存在，或者 hooks.after_plan 下未注册任何钩子，则跳到完成报告。
• 如果文件存在，则读取文件并查找 hooks.after_plan 键下的条目。
• 如果 YAML 无法解析或无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包含解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后继续完成报告。
• 过滤掉 enabled 明确设为 false 的钩子。没有 enabled 字段的钩子默认视为已启用。
• 对于其余钩子，不要尝试解读或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 对于每个可执行钩子，根据其 optional 标记输出以下内容：
  • 强制钩子（optional: false）——每个强制钩子都必须输出 EXECUTE_COMMAND:：

    ## 扩展钩子
    
    **自动钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述代码块后，必须实际调用钩子，并等待其执行完毕后才能继续。调用方式应与在此 Agent/会话中自行运行命令相同（调用方式可能与字面上的 {command} ID 不同，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出代码块并不会运行钩子。
  • 可选钩子（optional: true）：

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

完成报告

命令在 Phase 1 设计阶段结束。报告分支、IMPL_PLAN 路径和生成的制品。

阶段

Phase 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，格式如下：

   • 决策：[所选方案]
   • 理由：[选择该方案的原因]
   • 已考虑的替代方案：[评估过的其他方案]

输出：解决所有 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

关键规则

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

完成条件

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