openspec-archive-change

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Archive a completed change in the experimental workflow.

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

If no change name provided, prompt for selection
Run
```
openspec list --json
```
to get available changes. Use the AskUserQuestion tool to let the user select.
Show only active changes (not already archived). Include the schema used for each change if available.

IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.
Check artifact completion status
Run
```
openspec status --change "<name>" --json
```
to check artifact completion.
Parse the JSON to understand:
- ```
schemaName
```
  : The workflow being used
- ```
artifacts
```
  : List of artifacts with their status (
```
done
```
  or other)
If any artifacts are not
done
:
- Display warning listing incomplete artifacts
- Use AskUserQuestion tool to confirm user wants 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
- Use AskUserQuestion tool to confirm user wants to proceed
- Proceed if user confirms
If no tasks file exists: Proceed without task-related warning.
Assess delta spec sync state
Check for delta specs at
```
openspec/changes/<name>/specs/
```
. If none exist, proceed without sync prompt.
If delta specs exist:
- Compare each delta spec with its corresponding main spec at
```
openspec/specs/<capability>/spec.md
```
- 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"
If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
Perform the archive

Create the archive directory if it doesn't exist:
bash
```
mkdir -p openspec/changes/archive
```
Generate target name using current date:
```
YYYY-MM-DD-<change-name>
```
Check if target already exists:
- If yes: Fail with error, suggest renaming existing archive or using different date
- If no: Move the change directory to archive
bash
```
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<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

undefined

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

输入：可选择性指定变更名称。如果未指定，检查是否可以从对话上下文推断。如果模糊或有歧义，必须提示用户选择可用的变更。

步骤

如果未提供变更名称，提示用户选择
Run
```
openspec list --json
```
获取可用变更。使用 AskUserQuestion tool 让用户选择。
仅显示活跃变更（尚未归档的）。如果可用，包含每个变更所使用的schema。

重要提示：请勿猜测或自动选择变更。务必让用户选择。
检查工件完成状态
Run
```
openspec status --change "<name>" --json
```
检查工件完成情况。
解析JSON以了解：
- ```
schemaName
```
  : 所使用的工作流
- ```
artifacts
```
  : 工件列表及其状态 (
```
done
```
  或其他)
如果存在未标记为
done
的工件：
- 显示列出未完成工件的警告
- 使用 AskUserQuestion tool 确认用户是否要继续
- 若用户确认则继续
检查任务完成状态
读取任务文件（通常为
```
tasks.md
```
）以检查是否存在未完成的任务。
统计标记为
```
- [ ]
```
（未完成）与
```
- [x]
```
（已完成）的任务数量。
如果发现未完成任务：
- 显示包含未完成任务数量的警告
- 使用 AskUserQuestion tool 确认用户是否要继续
- 若用户确认则继续
如果任务文件不存在：无需任务相关警告，直接继续。
评估delta spec同步状态
检查
```
openspec/changes/<name>/specs/
```
下是否存在delta spec。如果不存在，无需同步提示，直接继续。
如果存在delta spec：
- 将每个delta spec与其对应的主spec（位于
```
openspec/specs/<capability>/spec.md
```
  ）进行比较
- 确定将要应用的变更（添加、修改、删除、重命名）
- 在提示前显示合并后的摘要
提示选项：
- 如果需要变更："立即同步（推荐）"、"不同步直接归档"
- 如果已同步："立即归档"、"仍要同步"、"取消"
如果用户选择同步，使用Task工具（subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"）。无论选择如何，继续执行归档操作。
执行归档

如果归档目录不存在则创建：
bash
```
mkdir -p openspec/changes/archive
```
使用当前日期生成目标名称：
```
YYYY-MM-DD-<change-name>
```
检查目标是否已存在：
- 如果存在：报错失败，建议重命名现有归档或使用不同日期
- 如果不存在：将变更目录移动到归档目录
bash
```
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
```
显示摘要

显示归档完成摘要，包括：
- 变更名称
- 使用的schema
- 归档位置
- 规格是否已同步（如适用）
- 关于任何警告的说明（未完成的工件/任务）

成功时的输出

undefined

Archive Complete

归档完成

Change: <change-name> Schema: <schema-name> Archived to: openspec/changes/archive/YYYY-MM-DD-<name>/ Specs: ✓ Synced to main specs (or "No delta specs" or "Sync skipped")

All artifacts complete. All tasks complete.


**Guardrails**
- Always prompt for change selection if not provided
- 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, use openspec-sync-specs approach (agent-driven)
- If delta specs exist, always run the sync assessment and show the combined summary before prompting

变更： <change-name> Schema： <schema-name> 归档至： openspec/changes/archive/YYYY-MM-DD-<name>/ 规格： ✓ 已同步至主规格（或"无delta spec"或"已跳过同步"）

所有工件已完成。所有任务已完成。


**约束规则**
- 如果未提供变更名称，始终提示用户选择
- 使用工件图（openspec status --json）检查完成情况
- 不要因警告而阻止归档 - 仅告知用户并确认
- 移动到归档时保留.openspec.yaml（它会随目录一起移动）
- 清晰显示操作摘要
- 如果请求同步，使用openspec-sync-specs方法（由agent驱动）
- 如果存在delta spec，在提示前始终运行同步评估并显示合并后的摘要