openspec-archive-change

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Archive a completed change in the experimental workflow.

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.

<capability-path>

is the spec directory relative to

specs/

(for example,

user-auth

identity/user-auth

). Preserve the full path from each delta spec when resolving its main spec.

Input: Optionally specify a change name. 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
When prompting, show only active changes (not already archived). Include the schema used for each change if available.
Always announce: "Using change: <name>" and how to override (e.g.,
```
$openspec-archive-change (Codex) or /openspec-archive-change (other agents) <other>
```
).
Load current archive inputs before the existing archive checks:

After resolving the selected change and planning root, run:
bash
```
openspec instructions archive --change "<name>" --json
```
Keep the same selected-root flags on this command. This lookup is advisory and optional: it only supplies extra prompt inputs, so it must never block archiving. If it exits non-zero or returns invalid JSON — for example on an older CLI that does not support this command yet — continue the archive workflow with no context and no operation guidance. Do not report an error and do not stop.
A successful response may omit both optional fields. Treat
```
context
```
as a required prompt-level input: read and consider it, and apply relevant project facts, conventions, and constraints. Treat
```
operationGuidance
```
as optional additive advice: read and consider every entry, and follow entries that are applicable and compatible with the built-in archive workflow.
Keep both fields separate from built-in steps, explicit user choices, resolved paths, CLI checks, and command contracts. If context conflicts with one of those controlling inputs, report the conflict and preserve the controlling value. If guidance is inapplicable or conflicts with a controlling input, do not follow it and explain why. Do not infer replacement paths, skipped prompts, or flags from either field, and do not copy their text verbatim into specs, change artifacts, or archive summaries unless the user separately asks for it. These are prompt-level behavior contracts, not enforceable checks.
Check artifact completion status
Run
```
openspec status --change "<name>" --json
```
to check artifact completion.
Parse the JSON to understand:
- ```
schemaName
```
  : The workflow being used
- ```
planningHome
```
  ,
```
changeRoot
```
  ,
```
artifactPaths
```
  , and
```
actionContext
```
  : path and scope context
- ```
artifacts
```
  : List of artifacts with their status (
```
done
```
  ,
```
skipped
```
  , or other)
If any artifacts are neither
done
nor
skipped
(skipped artifacts satisfy the requirement - the change declares skip_specs):
- Display warning listing incomplete artifacts
- Ask the user to confirm they want to proceed
- Proceed if user confirms
Check task completion status
Read the tasks file (typically
```
tasks.md
```
) to check for incomplete tasks.
Count tasks marked with
```
- [ ]
```
(incomplete) vs
```
- [x]
```
(complete).
If incomplete tasks found:
- Display warning showing count of incomplete tasks
- Ask the user to confirm they want to proceed
- Proceed if user confirms
If no tasks file exists: Proceed without task-related warning.
Assess delta spec sync state
Use
```
artifactPaths.specs.existingOutputPaths
```
from status JSON as the only delta-spec source. If the
```
specs
```
entry is missing or
```
existingOutputPaths
```
is empty, proceed without a sync prompt and do not infer delta specs from other artifacts.
If delta specs exist:
- Compare each delta spec with its corresponding main spec at
```
<planningHome.root>/openspec/specs/<capability-path>/spec.md
```
  (use the store-aware
```
planningHome.root
```
  from step 2, not a hardcoded repo path)
- Determine what changes would be applied (adds, modifications, removals, renames)
- Show a combined summary before prompting
Prompt options:
- If changes needed: "Sync now (recommended)", "Archive without syncing"
- If already synced: "Archive now", "Sync anyway", "Cancel"
Route on the answer:
- "Cancel" — stop, do not archive
- "Archive without syncing" or "Archive now" — proceed to archive
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving
Before a selected sync writes any main spec, run
```
openspec instructions specs --change "<name>" --json
```
once with the same selected-root flags. Require a zero exit status and valid artifact-instruction JSON. If the lookup fails or returns invalid JSON, report the error and stop before writing any main spec or moving the change. A valid response with omitted
```
rules
```
is the no-rules case. Apply returned
```
rules
```
only to the content and form of main specs produced by this merge; do not use them as archive guidance, change CLI behavior, or copy the rule text into any output file.
Then run the
```
openspec-sync-specs
```
workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching
```
specs
```
instructions again. Do not delegate it to a background task — step 5 would move
```
changeRoot
```
out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
Then re-run the comparison from the top of this step against every capability that has a delta spec in
```
artifactPaths.specs.existingOutputPaths
```
— not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving
```
## Requirements
```
  empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
- RENAMED requirements present under the new name and absent under the old one
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and
```
changeRoot
```
is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
Perform the archive
Create an
```
archive
```
directory under
```
planningHome.changesDir
```
if it doesn't exist:
bash
```
mkdir -p "<planningHome.changesDir>/archive"
```
Generate the target name: use the change name as-is when it already starts with a
```
YYYY-MM-DD-
```
prefix; otherwise prepend the current date as
```
YYYY-MM-DD-<change-name>
```
. Never stack a second date (same rule as
```
openspec archive
```
).
Check if target already exists:
- If yes: Fail with error, suggest renaming existing archive or using different date
- If no: Move
```
changeRoot
```
  to the archive directory
bash
```
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
```
Display summary

Show archive completion summary including:
- Change name
- Schema that was used
- Archive location
- Whether specs were synced (if applicable)
- Note about any warnings (incomplete artifacts/tasks)

Output On Success

markdown

undefined

在实验性工作流中归档已完成的变更。

Store 选择： 如果用户指定了某个 store（store 是注册在此机器上的独立 OpenSpec repo），或者工作内容位于某个 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/

根目录。

<capability-path>

是相对于

specs/

的 spec 目录（例如

user-auth

或

identity/user-auth

）。解析每个 delta spec 对应的 main spec 时，请保留从该 delta spec 获得的完整路径。

输入： 可以选择指定 change 名称。如果省略此项，请检查是否可以从对话上下文推断。如果表述模糊或不明确，必须提示用户选择可用 change。

步骤

选择 change

如果提供了名称，则使用该名称。否则：
- 如果用户在对话中提到某个 change，则从对话上下文中推断
- 如果只有一个活跃 change，则自动选择
- 如果存在歧义，运行
```
openspec list --json
```
  获取可用 change，并要求用户选择一个
提示用户时，只显示活跃 change（不显示已经归档的 change）。如果可用，请包含每个 change 使用的 schema。
始终声明：“正在使用 change: <name>”，并说明如何覆盖它（例如
```
$openspec-archive-change (Codex) or /openspec-archive-change (other agents) <other>
```
）。
在执行现有归档检查之前加载当前归档输入：

确定所选 change 和规划根目录后，运行：
bash
```
openspec instructions archive --change "<name>" --json
```
在此命令上保留相同的选定根目录标志。该查询仅供参考且是可选的：它只提供额外的提示输入，因此绝不能阻塞归档。如果它以非零状态退出或返回无效 JSON——例如旧版 CLI 尚不支持此命令——则继续归档工作流，不带 context，也不带 operation guidance。不要报告错误，也不要停止。
成功响应可能省略两个可选字段。将
```
context
```
视为必需的提示层面输入：读取并考虑它，并应用相关项目事实、约定和约束。将
```
operationGuidance
```
视为可选的补充建议：读取并考虑每一条，并遵循适用且与内置归档工作流兼容的条目。
将这两个字段与内置步骤、明确的用户选择、已解析路径、CLI 检查和命令契约分开。如果 context 与其中某个控制性输入冲突，请报告冲突并保留控制性值。如果 guidance 不适用或与控制性输入冲突，则不要遵循它，并解释原因。不要从任一字段推断替代路径、跳过的提示或标志，也不要将其文本逐字复制到 specs、change artifacts 或归档摘要中，除非用户另行要求。这些是提示层面的行为契约，而不是可执行的检查。
检查 artifact 完成状态
运行
```
openspec status --change "<name>" --json
```
检查 artifact 完成情况。
解析 JSON 以了解：
- ```
schemaName
```
  ：使用中的工作流
- ```
planningHome
```
  、
```
changeRoot
```
  、
```
artifactPaths
```
  和
```
actionContext
```
  ：路径和范围上下文
- ```
artifacts
```
  ：artifact 列表及其状态（
```
done
```
  、
```
skipped
```
  或其他）
如果任何 artifact 既不是
done
也不是
skipped
（skipped artifact 满足要求——该 change 声明了 skip_specs）：
- 显示警告并列出未完成的 artifact
- 要求用户确认是否要继续
- 如果用户确认，则继续
检查 task 完成状态
读取 tasks 文件（通常是
```
tasks.md
```
），检查未完成的任务。
统计标记为
```
- [ ]
```
（未完成）和
```
- [x]
```
（已完成）的任务。
如果发现未完成的任务：
- 显示警告并显示未完成任务的数量
- 要求用户确认是否要继续
- 如果用户确认，则继续
如果不存在 tasks 文件： 直接继续，不显示与任务相关的警告。
评估 delta spec 同步状态
仅使用 status JSON 中的
```
artifactPaths.specs.existingOutputPaths
```
作为 delta spec 来源。如果缺少
```
specs
```
条目或
```
existingOutputPaths
```
为空，则不显示同步提示并继续，且不要从其他 artifact 推断 delta spec。
如果存在 delta spec：
- 将每个 delta spec 与
```
<planningHome.root>/openspec/specs/<capability-path>/spec.md
```
  处对应的 main spec 进行比较（使用第 2 步中支持 store 的
```
planningHome.root
```
  ，不要使用硬编码的 repo 路径）
- 确定将应用哪些变更（新增、修改、移除、重命名）
- 在提示前显示综合摘要
提示选项：
- 如果需要变更：“立即同步（推荐）”、“不同步直接归档”
- 如果已经同步：“立即归档”、“仍然同步”、“取消”
根据回答进行分流：
- “取消”——停止，不要归档
- “不同步直接归档”或“立即归档”——继续归档
- “立即同步”或“仍然同步”——执行同步，然后验证（如下）
- 其他任何回答——再次询问，而不是归档
在所选同步操作写入任何 main spec 之前，使用相同的选定根目录标志运行一次
```
openspec instructions specs --change "<name>" --json
```
。要求退出状态为零，并返回有效的 artifact-instruction JSON。如果查询失败或返回无效 JSON，请报告错误，并在写入任何 main spec 或移动 change 之前停止。有效响应中省略
```
rules
```
表示无规则情况。仅将返回的
```
rules
```
应用于此次合并生成的主 specs 的内容和形式；不要将其用作归档指导、改变 CLI 行为，或将规则文本复制到任何输出文件。
然后，为 change
```
<name>
```
内联运行
```
openspec-sync-specs
```
工作流（由 agent 驱动的 intelligent merge），传入 delta spec 分析结果以及上面获取的 specs-rule 快照，并等待其完成。内联同步必须复用该快照，不要再次获取
```
specs
```
instructions。不要将其委托给后台任务——第 5 步会在同步仍在读取
```
changeRoot
```
时将其移走，最终导致 change 已被归档而主 specs 从未更新。如果 agent 只能通过委托运行，则同步委托并等待结果。
然后，从本步骤开头重新对每个具有 delta spec 的 capability 执行比较——不要只比较同步报告已触及的 capability。成功的同步不会留下任何待应用的内容，因此每个 capability 现在都应呈现为已同步状态：
- ADDED requirements 已存在
- MODIFIED requirements 包含 delta 中指明的 scenario 和 description 变更，同时保留其他 scenarios
- REMOVED requirements 已消失——如果此次同步使某个 capability 退役（移除了其最后一个 requirement，导致
```
## Requirements
```
  为空），则应删除其 main spec，而不是将其留空；同步明确保留并报告的 spec 也视为匹配
- RENAMED requirements 在新名称下存在，且旧名称下不存在
如果同步失败，或任何 capability 不匹配，请报告差异并停止——不要归档。此时没有移动任何内容，
```
changeRoot
```
仍然完整，因此用户可以修复不匹配问题，或重新运行同步并再次开始归档。
执行归档
如果
```
planningHome.changesDir
```
下不存在
```
archive
```
目录，则创建：
bash
```
mkdir -p "<planningHome.changesDir>/archive"
```
生成目标名称：如果 change 名称已经以
```
YYYY-MM-DD-
```
开头，则原样使用；否则，将当前日期作为
```
YYYY-MM-DD-<change-name>
```
添加到前面。绝不叠加第二个日期（与
```
openspec archive
```
的规则相同）。
检查目标是否已存在：
- 如果存在：失败并报错，建议重命名现有归档或使用其他日期
- 如果不存在：将
```
changeRoot
```
  移动到归档目录
bash
```
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
```
显示摘要

显示归档完成摘要，其中包括：
- change 名称
- 使用的 schema
- 归档位置
- specs 是否已同步（如适用）
- 关于警告的说明（未完成的 artifacts/tasks）

成功时的输出

markdown

undefined

Archive Complete

Change: <change-name> Schema: <schema-name> Archived to: the archive path derived from

planningHome.changesDir

/<target-name>/ Specs: <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">

<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")>


**Guardrails**
- Announce the selected change; prompt for selection when it is ambiguous
- Use artifact graph (openspec status --json) for completion checking
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven)
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
- Apply relevant runtime context and report conflicts; operation guidance remains advisory
- Consider every guidance entry and explain any inapplicable or conflicting advice
- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged
- Artifact rules constrain only the specs being written and are never operation guidance
- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files

Change: <change-name> Schema: <schema-name> Archived to: the archive path derived from

planningHome.changesDir

/<target-name>/ Specs: <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">

<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")>


**防护措施**
- 声明所选 change；在存在歧义时提示用户选择
- 使用 artifact graph（`openspec status --json`）检查完成情况
- 不要因警告阻塞归档——只需告知用户并请求确认
- 移动到归档时保留 `.openspec.yaml`（它会随目录一起移动）
- 清晰显示发生了什么
- 如果请求同步，内联运行 `openspec-sync-specs` 工作流（由 agent 驱动）
- 在 spec 同步仍在进行时绝不归档——先内联运行同步，并在移动 `changeRoot` 前验证主 specs
- 如果存在 delta specs，始终运行同步评估，并在提示前显示综合摘要
- 应用相关 runtime context 并报告冲突；operation guidance 仍仅作为参考
- 考虑每一条 guidance，并解释任何不适用或冲突的建议
- 现有 CLI 检查、已解析路径、提示和命令契约保持不变
- Artifact 规则仅约束正在写入的 specs，绝不作为操作指导
- 绝不将 runtime context、operation guidance 或 artifact-rule 文本逐字复制到输出文件