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