openspec-archive-change
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseArchive 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 to discover registered store ids, then pass on the commands that read or write specs and changes (, , , , , , , , , , ). Once selected, treat 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 , 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 root.
openspec store list --json--store <id>new changestatusinstructionslistshowvalidatearchivedoctorcontextschemasview--store <id>openspec status --change "<name>" --json --store "<id>"openspec/<capability-path>specs/user-authidentity/user-authInput: 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 changeIf 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 to get available changes and ask the user to select one
openspec list --json
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 <other>Load current archive inputs before the existing archive checks:After resolving the selected change and planning root, run:bashopenspec instructions archive --change "<name>" --jsonKeep 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. Treatas a required prompt-level input: read and consider it, and apply relevant project facts, conventions, and constraints. Treatcontextas optional additive advice: read and consider every entry, and follow entries that are applicable and compatible with the built-in archive workflow.operationGuidanceKeep 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 statusRunto check artifact completion.
openspec status --change "<name>" --jsonParse the JSON to understand:- : The workflow being used
schemaName - ,
planningHome,changeRoot, andartifactPaths: path and scope contextactionContext - : List of artifacts with their status (
artifacts,done, or other)skipped
If any artifacts are neithernordone(skipped artifacts satisfy the requirement - the change declares skip_specs):skipped- Display warning listing incomplete artifacts
- Ask the user to confirm they want to proceed
- Proceed if user confirms
-
Check task completion statusRead the tasks file (typically) to check for incomplete tasks.
tasks.mdCount tasks marked with(incomplete) vs- [ ](complete).- [x]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 stateUsefrom status JSON as the only delta-spec source. If the
artifactPaths.specs.existingOutputPathsentry is missing orspecsis empty, proceed without a sync prompt and do not infer delta specs from other artifacts.existingOutputPathsIf delta specs exist:- Compare each delta spec with its corresponding main spec at (use the store-aware
<planningHome.root>/openspec/specs/<capability-path>/spec.mdfrom step 2, not a hardcoded repo path)planningHome.root - 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, runonce 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 omittedopenspec instructions specs --change "<name>" --jsonis the no-rules case. Apply returnedrulesonly 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.rulesThen run theworkflow 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 fetchingopenspec-sync-specsinstructions again. Do not delegate it to a background task — step 5 would movespecsout 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.changeRootThen re-run the comparison from the top of this step against every capability that has a delta spec in— 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:artifactPaths.specs.existingOutputPaths- 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 empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
## Requirements - 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 andis intact, so the user can fix the mismatch or re-run the sync and start the archive again.changeRoot - Compare each delta spec with its corresponding main spec at
-
Perform the archiveCreate andirectory under
archiveif it doesn't exist:planningHome.changesDirbashmkdir -p "<planningHome.changesDir>/archive"Generate the target name: use the change name as-is when it already starts with aprefix; otherwise prepend the current date asYYYY-MM-DD-. Never stack a second date (same rule asYYYY-MM-DD-<change-name>).openspec archiveCheck if target already exists:- If yes: Fail with error, suggest renaming existing archive or using different date
- If no: Move to the archive directory
changeRoot
bashmv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>" -
Display summaryShow 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 仓库),或者工作项位于某个 store 中,请运行 以发现已注册的 store id,然后在所有读取或写入 spec 与变更的命令中传入 (、、、、、、、、、、)。选定后,在该工作流余下步骤中始终沿用 。下文每个未指定作用域的命令示例都采用这一简写:运行前必须追加该标志。例如,应运行 ,而不是下文所示的未指定作用域形式。其他命令不接受此标志。命令输出的提示已带有该标志;后续命令应继续保留。没有 store 时,命令作用于最近的本地 根目录。
openspec store list --json--store <id>new changestatusinstructionslistshowvalidatearchivedoctorcontextschemasview--store <id>openspec status --change "<name>" --json --store "<id>"openspec/<capability-path>specs/user-authidentity/user-auth输入: 可以选择指定变更名称。如果省略,则检查能否从对话上下文推断。如果描述模糊或不明确,必须提示用户选择可用变更。
步骤
-
选择变更如果提供了名称,则使用该名称。否则:
- 如果用户在对话中提到了某个变更,则从上下文推断
- 如果仅存在一个活跃变更,则自动选择
- 如果存在歧义,运行 获取可用变更,并要求用户选择
openspec list --json
提示选择时,仅显示活跃变更(不包括已归档的变更)。 如果可以获取,请包含每个变更所使用的 schema。始终声明:“Using change: <name>”,并说明如何覆盖(例如)。/openspec-archive-change <other>在执行现有归档检查之前加载当前归档输入:确定所选变更和规划根目录后,运行:bashopenspec instructions archive --change "<name>" --json在此命令上保留相同的根目录选择标志。此查询仅供参考且为可选操作:它只提供额外的提示输入,因此绝不能阻塞归档。 如果它以非零状态退出或返回无效 JSON——例如旧版 CLI 尚不支持此命令——则在没有上下文和操作指导的情况下继续归档工作流。不要报告错误,也不要停止。成功响应可能省略两个可选字段。将视为必需的提示级输入:读取并考虑它,并应用相关项目事实、约定和约束。将context视为可选的补充建议:读取并考虑每一条,并遵循适用且与内置归档工作流兼容的条目。operationGuidance将这两个字段与内置步骤、用户明确选择、已解析路径、CLI 检查和命令契约彼此分离。如果与其中任一控制性输入冲突,请报告冲突并保留控制性值。如果指导不适用或与控制性输入冲突,则不要遵循该指导,并说明原因。不要从任一字段推断替代路径、跳过的提示或标志,也不要将其文本逐字复制到 spec、变更 artifact 或归档摘要中,除非用户另行要求。这些是提示级行为契约,而不是可强制执行的检查。context -
检查 artifact 完成状态运行以检查 artifact 完成情况。
openspec status --change "<name>" --json解析 JSON 以了解:- :使用的工作流
schemaName - 、
planningHome、changeRoot和artifactPaths:路径与作用域上下文actionContext - :artifact 列表及其状态(
artifacts、done或其他状态)skipped
如果任何 artifact 既不是也不是done(skipped artifact 满足要求——该变更声明了skipped):skip_specs- 显示警告并列出未完成的 artifact
- 要求用户确认是否继续
- 如果用户确认,则继续
-
检查任务完成状态读取任务文件(通常是),检查是否有未完成的任务。
tasks.md统计标记为(未完成)与- [ ](已完成)的任务数量。- [x]如果发现未完成任务:- 显示警告并说明未完成任务的数量
- 要求用户确认是否继续
- 如果用户确认,则继续
如果不存在任务文件: 直接继续,不显示任务相关警告。 -
评估增量 spec 同步状态仅使用状态 JSON 中的作为增量 spec 来源。如果
artifactPaths.specs.existingOutputPaths条目缺失或specs为空,则继续执行,不显示同步提示,也不要从其他 artifact 推断增量 spec。existingOutputPaths如果存在增量 spec:- 将每个增量 spec 与 中对应的主 spec 进行比较(使用第 2 步中支持 store 的
<planningHome.root>/openspec/specs/<capability-path>/spec.md,不要使用硬编码的仓库路径)planningHome.root - 确定将应用哪些变更(新增、修改、删除、重命名)
- 在提示前显示合并摘要
提示选项:- 如果需要变更:“立即同步(推荐)”、“不同步直接归档”
- 如果已经同步:“立即归档”、“仍然同步”、“取消”
根据回答执行对应操作:- “取消”——停止,不执行归档
- “不同步直接归档”或“立即归档”——继续归档
- “立即同步”或“仍然同步”——执行同步,然后进行验证(见下文)
- 其他回答——再次询问,不要归档
在选定的同步操作写入任何主 spec 之前,使用相同的根目录选择标志运行一次:。必须以零退出状态返回有效的 artifact 指令 JSON。如果查询失败或返回无效 JSON,请报告错误,并在写入任何主 spec 或移动变更之前停止。有效响应中省略openspec instructions specs --change "<name>" --json表示无规则情形。仅将返回的rules应用于此次合并所生成主 spec 的内容和形式;不要将其用作归档指导或变更 CLI 行为,也不要将规则文本复制到任何输出文件中。rules然后为变更内联运行<name>工作流(由 agent 驱动的智能合并),传入增量 spec 分析结果以及上面获取的 specs 规则快照,并等待其完成。内联同步必须复用该快照,不得再次获取openspec-sync-specs指令。不要将其委派给后台任务——第 5 步会在同步仍在读取时移动specs,导致变更已被归档而主 spec 从未更新。如果 agent 只能通过委派方式运行,则同步委派并等待结果。changeRoot然后从本步骤开头重新执行比较,涵盖中具有增量 spec 的每个 capability,而不只检查同步报告已触及的 capability。成功同步后,不应再有内容需要应用,因此每个 capability 现在都必须显示为已同步:artifactPaths.specs.existingOutputPaths- 存在 ADDED requirements
- 存在 MODIFIED requirements,并包含增量 spec 中指明的场景和描述变更,同时保留其他场景
- REMOVED requirements 已消失——并且,如果此次同步淘汰了某个 capability(删除其最后一个 requirement,导致 为空),则其主 spec 应被删除,而不是保留为空;同步明确保留并报告的 spec 也视为匹配
## Requirements - RENAMED requirements 以新名称存在,并且旧名称下不存在
如果同步失败,或任何 capability 不匹配,请报告差异并停止——不要归档。没有任何内容被移动,且保持完好,因此用户可以修复不匹配问题、重新运行同步,然后再次开始归档。changeRoot - 将每个增量 spec 与
-
执行归档如果下不存在
planningHome.changesDir目录,则创建它:archivebashmkdir -p "<planningHome.changesDir>/archive"生成目标名称:如果变更名称已经以开头,则原样使用;否则在前面添加当前日期,格式为YYYY-MM-DD-。绝不叠加第二个日期(规则与YYYY-MM-DD-<change-name>相同)。openspec archive检查目标是否已存在:- 如果存在:失败并报错,建议重命名现有归档或使用不同日期
- 如果不存在:将 移动到归档目录
changeRoot
bashmv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>" -
显示摘要显示归档完成摘要,包括:
- 变更名称
- 使用的 Schema
- 归档位置
- spec 是否已同步(如适用)
- 任何警告的说明(未完成的 artifact/任务)
成功时的输出
markdown
undefinedArchive Complete
归档完成
Change: <change-name>
Schema: <schema-name>
Archived to: the archive path derived from /<target-name>/
Specs: <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">
planningHome.changesDir<"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-name>
Schema: <schema-name>
归档至: 根据 推导出的 <target-name>/ 归档路径
Specs: <仅当第 4 步验证通过时使用“✓ 已同步到主 spec”;否则使用“无增量 spec”或“已跳过同步”>
planningHome.changesDir<“所有 artifact 均已完成。所有任务均已完成。”——如果归档时存在警告,则改为列出这些警告,例如“已归档,但有 2 个未完成任务”>
**防护措施**
- 声明所选变更;有歧义时提示用户选择
- 使用 artifact 图(`openspec status --json`)检查完成情况
- 不要因警告阻塞归档——只需告知并确认
- 移动到归档时保留 `.openspec.yaml`(它会随目录一起移动)
- 清晰展示所发生的情况
- 如果请求同步,则内联运行 `openspec-sync-specs` 工作流(由 agent 驱动)
- spec 同步仍在进行时绝不归档——内联运行同步,并在移动 `changeRoot` 前验证主 spec
- 如果存在增量 spec,始终运行同步评估,并在提示前显示合并摘要
- 应用相关运行时上下文并报告冲突;操作指导仅供参考
- 考虑每一条指导,并解释任何不适用或冲突的建议
- 现有 CLI 检查、已解析路径、提示和命令契约保持不变
- artifact 规则仅约束正在写入的 spec,绝不作为操作指导
- 绝不将运行时上下文、操作指导或 artifact 规则文本逐字复制到输出文件