用途
openspec-apply-change 用于实现某个 OpenSpec 变更(change)中的任务。当用户想要开始实现、继续实现,或逐项推进任务时使用该技能。
主要能力
- 选择要处理的变更:可显式指定变更名称(如 $openspec-apply-change (Codex) 或 /openspec-apply-change (other agents) add-auth),也可从对话上下文推断;若只有一个活动变更则自动选择;若含糊或存在歧义,则运行 openspec list --json 获取可用变更并让用户选择。选定后会提示“Using change: ”以及如何覆盖。
- 检查状态以了解 schema:运行 openspec status --change "<name>" --json,解析 JSON 以了解 schemaName(如 "spec-driven")、planningHome、changeRoot、actionContext,以及哪个工件包含任务(spec-driven 通常为 "tasks")。
- 获取 apply 指令:运行 openspec instructions apply --change "<name>" --json,返回 contextFiles(工件 ID 到具体文件路径的映射)、进度(总数、已完成、剩余)、带状态的任务列表、基于当前状态的动态指令,以及可选的 context(来自所选根目录的当前必需项目指令输入)和 operationGuidance(apply 的当前建议性指导)。
- 处理状态:若 state 为 "blocked"(缺少工件),显示消息并建议使用 $openspec-continue-change (Codex) 或 /openspec-continue-change (other agents)(若未安装,则运行 openspec status --change "<name>" --json 查看下一个工件,并用 openspec instructions <artifact-id> --change "<name>" --json 了解如何创建);若 state 为 "all_done",则祝贺并建议归档;否则进入实现。
- 读取上下文文件:读取 apply 指令输出中 contextFiles 下列出的每个文件路径。文件取决于所用 schema:spec-driven 为 proposal、specs、design、tasks;其他 schema 遵循 CLI 输出中的 contextFiles。
- 展示当前进度:显示所用 schema、进度(“N/M tasks complete”)、剩余任务概览、来自 CLI 的动态指令。
- 实现任务(循环直到完成或阻塞):对每个待处理任务,显示正在处理的任务、进行所需代码修改、保持改动最小且聚焦、在任务文件中将 - [ ] 标记为 - [x],然后继续下一个任务。
使用方式
- 存储选择:若用户指定了 store(本机注册的独立 OpenSpec 仓库)或工作位于某个 store 中,运行 openspec store list --json 发现已注册的 store id,然后在读写 specs 和 changes 的命令(new change、status、instructions、list、show、validate、archive、doctor、context、view)上传递 --store <id>。选定后,--store <id> 在后续工作流中保持粘性。下文所有未限定范围的示例均为简写:运行前需追加该标志,例如运行 openspec status --change "<name>" --json --store "<id>"。其他命令不接受该标志。命令打印的提示已带有该标志,后续操作应保留。未指定 store 时,命令作用于最近的本地 openspec/ 根目录。
- 输入:可选指定变更名称。若省略,检查是否可从对话上下文推断。若含糊或歧义,必须提示可用变更。
- 暂停条件:任务不明确时请求澄清;实现中发现设计问题时建议更新工件;遇到错误或阻塞时报告并等待指导;用户中断。
- 完成或暂停时展示状态:本次会话完成的任务、总体进度(“N/M tasks complete”);若全部完成则建议归档;若暂停则解释原因并等待指导。
适用场景
- 用户希望开始、继续或逐项完成某个 OpenSpec 变更中的任务。
- 该技能支持“对变更执行操作”的模型:可在所有工件完成前(若任务已存在)、部分实现后、与其他操作交错时随时调用;允许更新工件——若实现中发现设计问题,建议更新工件,不锁定阶段,灵活工作。
限制与约束
- 将 context 视为必需的提示级输入,阅读并考虑,在实现时应用相关项目事实、约定和约束。
- 将 operationGuidance 视为可选的附加建议,阅读并考虑每一条,遵循适用且与内置工作流兼容的条目。
- 将这两个字段与 CLI 返回的状态、缺失工件、任务、进度、contextFiles 和内置指令分开。它们不是任务完成的证据,不替代内置指令,也不允许绕过阻塞状态。若 context 与内置指令、明确的用户选择或 CLI 控制的值冲突,报告冲突并保留控制值。若 guidance 不适用或与这些控制输入冲突,不遵循并解释原因。这些是提示级行为契约,不是可强制执行的检查。
- 不要将 context 或 operationGuidance 逐字复制到实现文件或规划工件中,除非用户另行要求。
- 护栏:持续处理任务直到完成或阻塞;开始前始终读取上下文文件(来自 apply 指令输出);任务含糊时暂停并询问;实现中发现问题时暂停并建议更新工件;保持代码改动最小且限定于每个任务;完成每个任务后立即更新任务复选框;遇到错误、阻塞或需求不清时暂停,不要猜测;使用 CLI 输出中的 contextFiles,不要假设具体文件名;不要用 context 或操作指导作为任务完成的证明;应用相关项目上下文,报告与控制性工作流输入的冲突;考虑每一条指导条目,解释不适用或冲突的建议;不要将运行时上下文或操作指导复制到实现文件或规划工件中;保留 CLI 控制的 blocked/ready/all-done 行为与完成标准。