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-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：当前针对实施的建议性指导

   处理以下状态：

   • 如果 state: "blocked"（缺少制品）：显示提示，并建议使用 /openspec-continue-change（如果未安装该命令，请运行 openspec status --change "<name>" --json 查看下一个制品，并运行 openspec instructions <artifact-id> --change "<name>" --json 了解如何创建它）
   • 如果 state: "all_done"：表示祝贺，并建议归档
   • 否则：继续实施

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

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

4. 读取上下文文件 读取 apply 指令输出中 contextFiles 下列出的每个文件。 文件取决于所使用的 schema：

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

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

5. 显示当前进度

   显示：

   • 正在使用的 schema
   • 进度：“已完成 N/M 项任务”
   • 剩余任务概览
   • CLI 中的动态指令

6. 实施任务（循环执行，直至完成或受阻）

   对每项待处理任务：

   • 显示正在处理的任务
   • 按要求进行代码更改
   • 保持更改最小且聚焦
   • 在 tasks 文件中将任务标记为完成：- [ ] → - [x]
   • 继续下一项任务

   以下情况请暂停：

   • 任务不明确 → 请求澄清
   • 实施过程中发现设计问题 → 建议更新文档
   • 任务需要完成超出规范和 tasks 所描述的工作，或者你打算为了适应现状而放弃、缩小、推迟指定行为或接受例外 → 提出新增范围并询问；不要擅自处理
   • 遇到错误或阻碍 → 报告并等待指示
   • 用户中断

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 tasks complete! 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，不要假定特定文件名
• 不要以 context 或操作指南作为任务完成的依据
• 应用相关项目上下文；报告与具有约束力的工作流输入之间的冲突
• 考虑每条指导；说明任何不适用或相互冲突的建议
• 不要将运行时上下文或操作指南复制到实现文件或规划文档中
• 遵循 CLI 控制的受阻／就绪／全部完成状态及完成标准

灵活的工作流集成

此技能支持“针对变更采取行动”的模式：

• 可随时调用：所有文档完成之前（如果已有任务）、部分实施之后，也可与其他操作交替进行
• 允许更新文档：如果实施过程中发现设计问题，建议更新文档——不受阶段限制，灵活推进