openspec-apply-change

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement tasks from an OpenSpec change.

Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run

openspec store list --json

to discover registered store ids, then pass

--store <id>

on the commands that read or write specs and changes (

new change

status

instructions

list

show

validate

archive

doctor

context

schemas

view

). Once selected, treat

--store <id>

as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run

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

, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local

openspec/

root.

Input: Optionally specify a change name (e.g.,

/openspec-apply-change add-auth

). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

Select the change

If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run
```
openspec list --json
```
  to get available changes and ask the user to select one
Always announce: "Using change: <name>" and how to override (e.g.,
```
/openspec-apply-change <other>
```
).
Check status to understand the schema
bash
```
openspec status --change "<name>" --json
```
Parse the JSON to understand:
- ```
schemaName
```
  : The workflow being used (e.g., "spec-driven")
- ```
planningHome
```
  ,
```
changeRoot
```
  , and
```
actionContext
```
  : planning scope and edit constraints
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
Get apply instructions
bash
```
openspec instructions apply --change "<name>" --json
```
This returns:
- ```
contextFiles
```
  : artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
- Progress (total, complete, remaining)
- Task list with status
- Dynamic instruction based on current state
- Optional
```
context
```
  : current required project instruction input from the selected root
- Optional
```
operationGuidance
```
  : current advisory guidance for apply
Handle states:
- If
```
state: "blocked"
```
  (missing artifacts): show message, suggest using
```
/openspec-continue-change
```
  (if it is not installed, run
```
openspec status --change "<name>" --json
```
  to see the next artifact and
```
openspec instructions <artifact-id> --change "<name>" --json
```
  for how to create it)
- If
```
state: "all_done"
```
  : congratulate, suggest archive
- Otherwise: proceed to implementation
Treat
```
context
```
as a required prompt-level input. Read and consider it, and apply relevant project facts, conventions, and constraints while implementing. Treat
```
operationGuidance
```
as optional additive advice. Read and consider every entry, and follow entries that are applicable and compatible with the built-in workflow.
Keep both fields separate from CLI-returned state, missing artifacts, tasks, progress,
```
contextFiles
```
, and the built-in
```
instruction
```
. They are not evidence of task completion, do not replace the built-in instruction, and do not permit bypassing a blocked state. If context conflicts with the built-in instruction, an explicit user choice, or a CLI-controlled value, report the conflict and preserve the controlling value. If guidance is inapplicable or conflicts with those controlling inputs, do not follow it and explain why. These are prompt-level behavior contracts, not enforceable checks.
Read context files
Read every file path listed under
```
contextFiles
```
from the apply instructions output. The files depend on the schema being used:
- spec-driven: proposal, specs, design, tasks
- Other schemas: follow the contextFiles from CLI output
Do not copy
```
context
```
or
```
operationGuidance
```
verbatim into implementation files or planning artifacts unless the user separately asks for that content.
Show current progress

Display:
- Schema being used
- Progress: "N/M tasks complete"
- Remaining tasks overview
- Dynamic instruction from CLI
Implement tasks (loop until done or blocked)

For each pending task:
- Show which task is being worked on
- Make the code changes required
- Keep changes minimal and focused
- Mark task complete in the tasks file:
```
- [ ]
```
  →
```
- [x]
```
- Continue to next task
Pause if:
- Task is unclear → ask for clarification
- Implementation reveals a design issue → suggest updating artifacts
- A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
- Error or blocker encountered → report and wait for guidance
- User interrupts
On completion or pause, show status

Display:
- Tasks completed this session
- Overall progress: "N/M tasks complete"
- If all done: suggest archive
- If paused: explain why and wait for guidance

Output During Implementation

undefined

实施 OpenSpec 变更中的任务。

Store 选择： 如果用户指定了某个

store

（一个注册在此机器上的独立 OpenSpec repo），或者当前工作位于某个

store

中，请运行

openspec store list --json

发现已注册的 store id，然后在读取或写入 specs 和 changes 的命令（

new change

、

status

、

instructions

、

list

、

show

、

validate

、

archive

、

doctor

、

context

、

schemas

、

view

）上传入

--store <id>

。选定后，在余下整个工作流中持续使用

--store <id>

。下文所有未限定 store 的命令示例均为简写：运行前应追加该参数。例如，应运行

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

，而不是下文所示的未限定形式。其他命令不接受该参数。命令打印的提示已包含该参数；后续命令也应保留它。未指定 store 时，命令将作用于最近的本地

openspec/

root。

输入： 可以选择指定变更名称（例如

/openspec-apply-change add-auth

）。如果省略，检查是否能从对话上下文推断。如果表述含糊或存在歧义，必须提示用户并提供可用变更供选择。

步骤

选择变更

如果提供了名称，则使用该名称。否则：
- 如果用户在对话上下文中提到了某个变更，则据此推断
- 如果只有一个活跃变更，则自动选择
- 如果存在歧义，则运行
```
openspec list --json
```
  获取可用变更，并要求用户选择
始终宣告：“正在使用变更：<name>”，并说明如何覆盖（例如
```
/openspec-apply-change <other>
```
）。
检查状态以了解 schema
bash
```
openspec status --change "<name>" --json
```
解析 JSON，以了解：
- ```
schemaName
```
  ：正在使用的工作流（例如
```
"spec-driven"
```
  ）
- ```
planningHome
```
  、
```
changeRoot
```
  和
```
actionContext
```
  ：规划范围和编辑约束
- 哪个 artifact 包含任务（对于 spec-driven，通常是
```
"tasks"
```
  ；对于其他 schema，则检查状态）
获取 apply instructions
bash
```
openspec instructions apply --change "<name>" --json
```
该命令返回：
- ```
contextFiles
```
  ：artifact ID -> 具体文件路径数组（因 schema 而异，可能是 proposal/specs/design/tasks，或 spec/tests/implementation/docs）
- 进度（总数、已完成、剩余）
- 带状态的任务列表
- 基于当前状态生成的动态 instruction
- 可选的
```
context
```
  ：从选定 root 获取的、当前所需的项目 instruction 输入
- 可选的
```
operationGuidance
```
  ：当前针对 apply 的建议性指导
处理各种状态：
- 如果
```
state: "blocked"
```
  （缺少 artifact）：显示消息，建议使用
```
/openspec-continue-change
```
  （如果尚未安装，则运行
```
openspec status --change "<name>" --json
```
  查看下一个 artifact，并运行
```
openspec instructions <artifact-id> --change "<name>" --json
```
  了解如何创建）
- 如果
```
state: "all_done"
```
  ：表示祝贺，并建议归档
- 否则：继续实施
将
```
context
```
视为必需的 prompt-level 输入。读取并考虑其内容，并在实施时应用相关项目事实、约定和约束。将
```
operationGuidance
```
视为可选的附加建议。读取并考虑每一条建议，并遵循其中适用且与内置工作流兼容的条目。
将这两个字段与 CLI 返回的 state、缺失的 artifact、任务、进度、
```
contextFiles
```
和内置
```
instruction
```
明确区分。它们不是任务完成的证据，不能替代内置 instruction，也不允许绕过 blocked 状态。如果 context 与内置 instruction、用户的明确选择或 CLI 控制值发生冲突，应报告冲突并保留起控制作用的值。如果 guidance 不适用，或与这些控制输入冲突，则不要遵循，并说明原因。这些是 prompt-level 行为契约，而不是可强制执行的检查。
读取 context 文件 读取 apply instructions 输出中
```
contextFiles
```
下列出的每个文件路径。文件取决于所使用的 schema：
- spec-driven：proposal、specs、design、tasks
- 其他 schema：遵循 CLI 输出中的 contextFiles
除非用户另行要求，否则不要将
```
context
```
或
```
operationGuidance
```
逐字复制到 implementation files 或 planning artifacts 中。
显示当前进度 显示：
- 正在使用的 schema
- 进度：“N/M 个任务已完成”
- 剩余任务概览
- CLI 返回的动态 instruction
实施任务（循环执行，直到完成或被阻塞） 对于每个待处理任务：
- 显示当前正在处理的任务
- 做出任务所需的代码变更
- 保持变更最小且聚焦
- 在 tasks 文件中将任务标记为完成：
```
- [ ]
```
  →
```
- [x]
```
- 继续下一个任务
遇到以下情况时暂停：
- 任务不清楚 → 请求澄清
- 实施过程中发现设计问题 → 建议更新 artifact
- 任务需要完成 spec 和 tasks 未描述的工作，或者为了使其契合而想要丢弃、缩减、推迟指定行为或接受例外 → 指出新增范围并询问；不要默默吸收
- 遇到错误或阻塞 → 报告并等待指导
- 用户中断
完成或暂停时显示状态 显示：
- 本次会话完成的任务
- 总体进度：“N/M 个任务已完成”
- 如果全部完成：建议归档
- 如果暂停：说明原因并等待指导

实施期间的输出

undefined

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


**Output On Completion**

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

Task 1
Task 2 ...

All tasks complete! You can archive this change with

/openspec-archive-change


**Output On Pause (Issue Encountered)**

Task 1
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

Options:

<option 1>
<option 2>
Other approach

What would you like to do?


**Guardrails**
- Keep going through tasks until done or blocked
- Always read context files before starting (from the apply instructions output)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess
- When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
- Only mark a task `- [x]` when its specified behavior is fully implemented, not when it is partially done or deferred
- Use contextFiles from CLI output, don't assume specific file names
- Do not use context or operation guidance as proof that a task is complete
- Apply relevant project context; report conflicts with controlling workflow inputs
- Consider every guidance entry; explain any inapplicable or conflicting advice
- Do not copy runtime context or operation guidance into implementation files or planning artifacts
- Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria

**Fluid Workflow Integration**

This skill supports the "actions on a change" model:

- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

Options:

<option 1>
<option 2>
Other approach

What would you like to do?


**防护规则**
- 持续处理任务，直到完成或被阻塞
- 开始实施前，始终读取 apply instructions 输出中的 context 文件
- 如果任务存在歧义，暂停并询问后再实施
- 如果实施过程中发现问题，暂停并建议更新 artifact
- 保持代码变更最小，并限定在当前任务范围内
- 每完成一个任务，立即更新任务复选框
- 遇到错误、阻塞或不明确的要求时暂停，不要猜测
- 如果任务需要完成 spec 未描述的工作，应指出新增范围并暂停——绝不能默默缩减、推迟或简化指定的 behavior
- 仅在指定 behavior 已完整实现时，才将任务标记为 `- [x]`，不能标记为部分完成或已推迟
- 使用 CLI 输出中的 contextFiles，不要假设具体文件名
- 不要将 context 或 operation guidance 作为任务已完成的证据
- 应用相关项目 context；报告其与工作流控制输入之间的冲突
- 考虑每一条 guidance；说明任何不适用或存在冲突的建议
- 不要将 runtime context 或 operation guidance 复制到 implementation files 或 planning artifacts 中
- 保留 CLI 控制的 blocked/ready/all-done behavior 和完成标准

**灵活工作流集成**
此 skill 支持“对变更执行操作”的模型：
- **可随时调用**：在所有 artifact 完成之前（如果存在 tasks）、部分实施之后，或与其他操作交错执行时
- **允许更新 artifact**：如果实施揭示设计问题，建议更新 artifact——不受阶段锁定，可以灵活推进