openspec-apply-change

实现 OpenSpec 变更中的任务。

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

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

步骤

1. 选择变更

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

   • 如果用户在对话上下文中提到了某个变更，则据此推断
   • 如果只有一个进行中的变更，则自动选择
   • 如果存在歧义，请运行 openspec list --json 获取可用变更，并让用户选择一个

   务必宣布：“使用变更：”，并说明如何更改选择（例如，$openspec-apply-change (Codex) or /openspec-apply-change (other agents) <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 (Codex) or /openspec-continue-change (other agents)（如果未安装，请运行 openspec status --change "<name>" --json 查看下一个工件，并运行 openspec instructions <artifact-id> --change "<name>" --json 了解如何创建该工件）
   • 如果 state: "all_done"：祝贺用户，并建议归档
   • 否则：继续实施

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

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

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

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

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

5. 显示当前进度

   显示：

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

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

   对于每个待处理任务：

   • 显示当前正在处理的任务
   • 完成所需的代码更改
   • 保持更改精简且聚焦
   • 在 tasks 文件中将任务标记为完成：- [ ] → - [x]
   • 继续下一个任务

   遇到以下情况时暂停：

   • 任务不明确 → 请求澄清
   • 实现过程中发现设计问题 → 建议更新文档
   • 遇到错误或阻碍 → 报告并等待指示
   • 用户中断

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 (Codex) or /openspec-archive-change (other agents)`.

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

## 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 instructions 的输出）
• 如果任务含糊不清，先暂停并询问，再开始实现
• 如果实现过程中发现问题，暂停并建议更新文档
• 代码更改应精简，并限定在各项任务的范围内
• 每完成一项任务，立即更新任务复选框
• 遇到错误、阻碍或不明确的要求时暂停，不要猜测
• 使用 CLI 输出中的 contextFiles，不要假设具体文件名
• 不要将上下文或操作指引作为任务已完成的证明
• 应用相关项目上下文；报告与起控制作用的工作流输入之间的冲突
• 考虑每条指引；说明任何不适用或相互冲突的建议
• 不要将运行时上下文或操作指引复制到实现文件或规划文档中
• 遵循 CLI 控制的阻塞／就绪／全部完成行为及完成标准

流畅工作流集成

此技能支持“针对变更执行操作”的模式：

• 可随时调用：所有文档尚未完成时（只要存在任务）、部分实现后，或与其他操作交错进行时
• 允许更新文档：如果实现过程中发现设计问题，建议更新文档；不受阶段限制，可灵活处理