openspec-new-change

使用实验性的制品驱动方法开始一项新变更。

存储库选择： 如果用户指定了某个存储库（存储库是指在这台机器上注册的独立 OpenSpec 仓库），或要处理的工作位于某个存储库中，请运行 openspec store list --json 以查找已注册的存储库 ID，然后在读取或写入规范和变更的命令（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）中传入 --store <id>。选定后，在整个工作流中始终使用 --store <id>。下方所有未指定存储库的此类命令示例都是简写形式：运行前请追加该标志。例如，运行 openspec status --change "<name>" --json --store "<id>"，而不是下方所示的未指定存储库形式。其他命令不接受此标志。命令输出的提示已包含该标志；后续命令也要保留它。未指定存储库时，命令会作用于最近的本地 openspec/ 根目录。

项目检查： 以下步骤适用于已使用 OpenSpec 的项目。在第一个会写入内容的步骤（new change、archive、sync specs 或编写制品文件）之前，请确认项目已有根目录：运行 openspec list --json（如果已选择存储库，则传入 --store <id>，因为该存储库此时就是根目录），并读取 root。root 对象表示项目已完成设置。"root": null 表示项目尚未完成设置——此处没有 openspec/ 目录，执行 openspec new change 等写入操作会产生副作用并创建该目录。该命令也会以非零状态退出；这不是 CLI 故障，而是表明项目尚未完成设置，因此请读取 JSON，不要重试或尝试绕过。

一个 "root": null 并不总是表示项目尚未完成设置：当 status 的错误消息以 Declared in 或 Invalid store declaration in 开头，并指明了此项目的 openspec/config.yaml（或 config.yml）时，说明该项目确实通过其声明的存储库使用 OpenSpec，但这台机器无法解析该存储库（它尚未注册，或 store: 行格式错误）。不要将其视为尚未初始化，也不要继续执行下方的分支：停止写入，并向用户显示该错误的 message 和 fix。

否则，如果没有根目录，接下来如何处理取决于此工作流的触发方式：

• 自动选择： 这是你自行选择的工作流，用户没有提及 OpenSpec、此技能，也没有运行其斜杠命令。停止使用 OpenSpec，并像未安装 OpenSpec 一样正常响应用户请求。不要让用户进行设置，也不要提及 OpenSpec 设置。
• 明确请求使用 OpenSpec： 用户提及了 OpenSpec、此技能，或运行了其斜杠命令。停止写入并询问用户如何继续：设置此项目（openspec init）、指定他们已有的存储库（--store <id>），或在此请求中不使用 OpenSpec 继续。等待用户答复。

在这两个分支中，绝不要将创建根目录作为副作用：在用户要求之前，不要运行 openspec init；不要手动创建 openspec/ 文件；也不要让命令创建该目录。

输入： 用户的请求应包含变更名称（kebab-case），或描述他们想要构建的内容。

步骤

1. 如果没有提供明确的输入，询问用户想要构建什么

   开放式询问用户，不要提供预设选项：

   “你想处理什么变更？请描述你想要构建或修复的内容。”

   根据用户的描述，推导出 kebab-case 名称（例如，“add user authentication” → add-user-auth）。

   重要： 在了解用户想要构建什么之前，不要继续。

2. 确定工作流模式

   使用默认模式（省略 --schema），除非用户明确要求使用其他工作流。

   只有在用户提及时，才使用其他模式：

   • 指定了某个模式名称 → 使用 --schema <name>
   • 提到“show workflows”或“what workflows” → 运行 openspec schemas --json，让用户选择

   否则： 省略 --schema，使用默认模式。

3. 创建变更目录

   openspec new change "<name>"
   

   仅当用户指定了某个工作流时，才添加 --schema <name>。 这会在 CLI 解析出的规划目录中创建一个脚手架变更。

4. 显示产物状态

   openspec status --change "<name>" --json
   

   使用返回的 planningHome、changeRoot、artifactPaths 和 nextSteps，不要假设路径位于仓库本地。

5. 获取第一个产物的说明 第一个产物取决于所用的 schema（例如，规范驱动工作流会使用 proposal）。 检查状态输出，找到第一个状态为 "ready" 的产物。

   openspec instructions <first-artifact-id> --change "<name>"
   

   这会输出用于创建第一个产物的模板和上下文。

6. 停止并等待用户指示

输出

完成这些步骤后，请总结：

• 变更名称和位置
• 使用的 schema/工作流及其产物顺序
• 当前状态（已完成 0/N 个产物）
• 第一个产物的模板
• 提示："准备好创建第一个产物了吗？只需描述这项变更的内容，我就会起草；也可以让我继续。"

注意事项

• 不要创建任何产物——只显示说明
• 不要在展示第一个产物模板后继续操作
• 如果名称无效（不是 kebab-case），请要求用户提供有效名称
• 如果已存在同名变更，请建议继续该变更
• 如果使用非默认工作流，请传递 --schema