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

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 (Codex) or /openspec-apply-change (other agents) 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 (Codex) or /openspec-apply-change (other agents) <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 (Codex) or /openspec-continue-change (other agents)
```
  (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
- 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（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>

。以下所有未指定 store 的命令示例均为简写：运行前应追加该 flag。例如，应运行

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

，而不是下面所示的未指定形式。其他命令不接受该 flag。命令输出的提示已携带该 flag；后续操作也应保留它。如果没有 store，命令将作用于最近的本地

openspec/

根目录。

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

$openspec-apply-change (Codex) or /openspec-apply-change (other agents) add-auth

）。如果省略，则检查能否从对话上下文推断。如果表述含糊或不明确，必须提示用户选择可用变更。

步骤

选择变更

如果提供了名称，使用该名称。否则：
- 如果对话上下文中提到某个变更，则据此推断
- 如果只有一个活跃变更，自动选择
- 如果存在歧义，运行
```
openspec list --json
```
  获取可用变更并要求用户选择
始终声明："使用变更：<name>"，并说明如何覆盖（例如，
```
$openspec-apply-change (Codex) or /openspec-apply-change (other agents) <other>
```
）。
检查状态以了解 schema
bash
```
openspec status --change "<name>" --json
```
解析 JSON 以了解：
- ```
schemaName
```
  ：正在使用的工作流（例如 "spec-driven"）
- ```
planningHome
```
  、
```
changeRoot
```
  和
```
actionContext
```
  ：规划范围和编辑约束
- 哪个 artifact 包含 tasks（对于 spec-driven，通常为 "tasks"；对于其他 schema，请检查状态）
获取 apply 指令
bash
```
openspec instructions apply --change "<name>" --json
```
该命令返回：
- ```
contextFiles
```
  ：artifact ID -> 具体文件路径数组（因 schema 而异，可能是 proposal/specs/design/tasks，也可能是 spec/tests/implementation/docs）
- 进度（总数、已完成数、剩余数）
- 带有状态的任务列表
- 根据当前状态生成的动态指令
- 可选的
```
context
```
  ：从选定根目录获取的当前必需项目指令输入
- 可选的
```
operationGuidance
```
  ：当前针对 apply 操作的建议性指导
处理各种状态：
- 如果
```
state: "blocked"
```
  （缺少 artifacts）：显示消息，并建议使用
```
$openspec-continue-change (Codex) or /openspec-continue-change (other agents)
```
  （如果尚未安装，则运行
```
openspec status --change "<name>" --json
```
  查看下一个 artifact，并运行
```
openspec instructions <artifact-id> --change "<name>" --json
```
  了解如何创建它）
- 如果
```
state: "all_done"
```
  ：表示祝贺，并建议归档
- 否则：继续实施
将
```
context
```
视为必需的 prompt-level 输入。读取并考虑它，并在实施时应用相关项目事实、约定和约束。将
```
operationGuidance
```
视为可选的附加建议。读取并考虑每一条内容，并遵循适用于当前工作流且与内置工作流兼容的条目。
将这两个字段与 CLI 返回的状态、缺失的 artifacts、tasks、进度、
```
contextFiles
```
和内置
```
instruction
```
明确区分。它们不是任务完成的证据，不能替代内置
```
instruction
```
，也不允许绕过 blocked 状态。如果
```
context
```
与内置
```
instruction
```
、用户的明确选择或 CLI 控制值发生冲突，请报告冲突并保留控制值。如果 guidance 不适用或与这些控制输入冲突，则不要遵循，并解释原因。这些是 prompt-level 行为契约，而不是可强制执行的检查。
读取 context files
读取 apply 指令输出中
```
contextFiles
```
下列出的每个文件路径。具体文件取决于所使用的 schema：
- spec-driven：proposal、specs、design、tasks
- 其他 schema：遵循 CLI 输出中的 contextFiles
除非用户另行要求，否则不要将
```
context
```
或
```
operationGuidance
```
逐字复制到 implementation files 或 planning artifacts 中。
显示当前进度

展示：
- 正在使用的 schema
- 进度："N/M 个任务已完成"
- 剩余任务概览
- CLI 生成的动态 instruction
实施任务（循环执行，直到完成或被阻塞）

对于每个待处理任务：
- 显示当前正在处理的任务
- 完成所需的代码更改
- 保持更改最小且聚焦
- 在 tasks 文件中将任务标记为完成：
```
- [ ]
```
  →
```
- [x]
```
- 继续处理下一个任务
出现以下情况时暂停：
- 任务不明确 → 请求澄清
- 实施过程中发现设计问题 → 建议更新 artifacts
- 遇到错误或阻塞 → 报告并等待指导
- 用户中断
完成或暂停时显示状态

展示：
- 本次会话完成的任务
- 总体进度："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 (Codex) or /openspec-archive-change (other agents)


**Output On Pause (Issue Encountered)**

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

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
- 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?


**防护规则**
- 持续处理任务，直到完成或被阻塞
- 开始前始终读取 context files（来自 apply 指令输出）
- 如果任务存在歧义，暂停并在实施前询问
- 如果实施过程中发现问题，暂停并建议更新 artifacts
- 保持代码更改最小，并限定在各个任务范围内
- 每完成一个任务，立即更新任务复选框
- 遇到错误、阻塞或要求不明确时暂停，不要猜测
- 使用 CLI 输出中的 contextFiles，不要假定具体文件名
- 不要将 context 或 operation guidance 作为任务已完成的证据
- 应用相关项目上下文；报告其与控制工作流输入之间的冲突
- 考虑每条 guidance；解释任何不适用或存在冲突的建议
- 不要将 runtime context 或 operation guidance 复制到 implementation files 或 planning artifacts 中
- 保留由 CLI 控制的 blocked/ready/all-done 行为和完成标准

**灵活工作流集成**

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