openspec-apply-change

实施 OpenSpec 变更中的任务。

存储选择： 如果用户指定了某个存储库（存储库是此机器上注册的独立 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/ 文件；也不要让命令创建它。

输入： 可选地指定变更名称（例如，/openspec-apply-change add-auth）。如果未指定，请检查能否从对话上下文中推断。如果含糊不清或存在歧义，必须提示用户从可用变更中选择。

步骤

1. 选择变更

   如果提供了名称，请使用该名称。否则：

   • 根据对话上下文推断用户是否提到过某项变更
   • 如果只有一项活跃变更，则自动选择
   • 如果存在歧义，运行 openspec list --json 获取可用变更，并请用户选择一项

   始终告知用户：“使用变更：”，并说明如何更换（例如，/openspec-apply-change <other>）。

2. 检查状态以了解方案

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

   解析 JSON 以了解：

   • schemaName：所用工作流（例如，“spec-driven”）
   • planningHome、changeRoot 和 actionContext：规划范围和编辑约束
   • 哪个产物包含任务（通常是 spec-driven 工作流中的 “tasks”；其他工作流请检查状态）

3. 获取实施说明

   openspec instructions apply --change "<name>" --json
   

   这将返回：

   • contextFiles：制品 ID → 具体文件路径数组（因架构而异，可能是 proposal/specs/design/tasks，也可能是 spec/tests/implementation/docs）
   • 进度（总数、已完成数、剩余数）
   • 任务列表，包含状态、源路径和源行号
   • 根据当前状态生成的动态指令
   • 可选的 context：来自所选根目录的当前必需项目指令输入
   • 可选的 operationGuidance：适用于 apply 的当前建议
   • missingArtifacts（如有）：没有输出的必需制品 ID

   处理状态：

   • 如果 state: "blocked"：显示消息并暂停实现。
     • 如果 missingArtifacts 不为空：建议使用 /openspec-continue-change 创建这些制品。
     • 否则，按照 CLI 指令，根据现有规划制品创建或修复由架构配置的跟踪文件。不要假设其他制品已就绪，也不要在受阻时开始实现。
   • 如果 state: "all_done"：报告所有已跟踪任务均已完成，并建议在归档前进行适当的审查或验证
   • 否则：继续实现

   将 context 视为提示词级别的必需输入。阅读并考虑它，在实现时应用相关的项目事实、约定和限制。 将 operationGuidance 视为可选的补充建议。阅读并考虑每一项，并遵循适用且与内置工作流兼容的建议。

   将这两个字段与 CLI 返回的状态、缺失制品、任务、进度、contextFiles 和内置 instruction 分开处理。它们不能作为任务完成的证据，不能替代内置指令，也不能允许绕过受阻状态。如果 context 与内置指令、用户明确选择或由 CLI 控制的值冲突，请报告冲突并保留控制方指定的值。如果建议不适用或与这些控制输入冲突，请勿遵循，并说明原因。 这些是提示词级别的行为约定，不是可强制执行的检查。

4. 读取上下文文件

   读取 apply 指令输出中 contextFiles 下列出的每个文件路径。 文件取决于所使用的架构：

   • spec-driven：proposal、specs、design、tasks
   • 其他架构：遵循 CLI 输出中的 contextFiles

   除非用户另行要求，否则不要将 context 或 operationGuidance 原文复制到实现文件或规划制品中。

5. 显示当前进度

   显示：

   • 使用的架构
   • 进度：“已完成 N/M 项任务”
   • 剩余任务概述
   • CLI 的动态指令

6. 实现任务（循环直到完成或受阻）

   对于每项待处理任务：

   • 显示正在处理的任务
   • 按要求进行代码更改
   • 保持更改精简且聚焦
   • 编辑前，确认返回的 sourcePath 和 line 处的复选框仍与任务描述一致；如果不一致，重新运行 apply 指令并使用刷新后的位置
   • 在返回的 sourcePath 和 line 处将任务标记为完成：- [ ] → - [x]
   • 重新运行 apply 指令，确认该任务现已完成且进度有所变化
   • 继续下一项任务

   在以下情况下暂停：

   • 任务不明确 → 请求澄清
   • 实现暴露设计问题 → 建议更新制品
   • 任务所需工作超出规范和任务描述，或者你为了使其适配而打算丢弃、缩小范围、推迟或接受对指定行为的例外 → 提出新增范围并询问；不要擅自处理
   • 遇到错误或阻塞因素 → 报告并等待指示
   • 用户中断

7. 完成或暂停时，显示状态 显示：

   • 本次会话已完成的任务
   • 总体进度："N/M 项任务已完成"
   • 如果全部完成：报告已跟踪的任务均已完成，并建议在归档前视情况进行审查或验证
   • 如果已暂停：说明原因并等待指示

实现过程中的输出

## Implementing: <change-name> (schema: <schema-name>)

Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete

Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete

完成时的输出

## Implementation Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓

### Completed This Session
- [x] Task 1
- [x] Task 2
...

All tracked tasks are complete. Review or verify the change as appropriate
before archiving. You can archive this change with `/openspec-archive-change`.

暂停时的输出（遇到问题）

## Implementation Paused

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete

### Issue Encountered
<description of the issue>

**Options:**
1. <option 1>
2. <option 2>
3. Other approach

What would you like to do?

护栏规则

• 持续推进任务，直到完成或被阻塞
• 开始前始终阅读上下文文件（来自 apply 指令的输出）
• 如果任务含义不明确，先暂停并在实现前询问
• 如果实现过程中发现问题，暂停并建议更新工件
• 保持代码变更最小化，并限定在每项任务的范围内
• 完成每项任务后立即更新任务复选框
• 遇到错误、阻塞或不清楚的情况时暂停，不要猜测
• 当某项任务所需的工作超出规范描述的范围时，说明新增范围并暂停——绝不静默收窄、推迟或简化规范中已明确的行为
• 只有当某项任务的指定行为被完整实现时，才将其标记为 - [x]，而不是在部分完成或推迟时标记
• 使用 CLI 输出中的 contextFiles，不要假设具体文件名
• 使用每项任务的 sourcePath 和行号来更新其确切的复选框
• 不要将上下文或操作指引作为任务已完成的证明
• 应用相关项目上下文；报告与控制工作流输入之间的冲突
• 考虑每一条指引条目；解释任何不适用或冲突的建议
• 不要将运行时上下文或操作指引复制到实现文件或规划工件中
• 保留 CLI 控制的 blocked/ready/all-done 行为及完成标准

流式工作流集成

此技能支持"变更时执行操作"模型：

• 可随时调用：在所有工件完成之前（如果任务已存在）、部分实现之后，或与其他操作交错进行
• 允许更新工件：如果实现过程中发现设计问题，建议更新工件——不受阶段锁定，灵活推进