openspec-bulk-archive-change

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Archive multiple completed changes in a single operation.

This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.

Input: None required (prompts for selection)

Steps

Get active changes
Run
```
openspec list --json
```
to get all active changes.
If no active changes exist, inform user and stop.
Prompt for change selection

Use AskUserQuestion tool with multi-select to let user choose changes:
- Show each change with its schema
- Include an option for "All changes"
- Allow any number of selections (1+ works, 2+ is the typical use case)
IMPORTANT: Do NOT auto-select. Always let the user choose.
Batch validation - gather status for all selected changes

For each selected change, collect:
a. Artifact status - Run
```
openspec status --change "<name>" --json
```
- Parse
```
schemaName
```
  and
```
artifacts
```
  list
- Note which artifacts are
```
done
```
  vs other states
b. Task completion - Read
```
openspec/changes/<name>/tasks.md
```
- Count
```
- [ ]
```
  (incomplete) vs
```
- [x]
```
  (complete)
- If no tasks file exists, note as "No tasks"
c. Delta specs - Check
```
openspec/changes/<name>/specs/
```
directory
- List which capability specs exist
- For each, extract requirement names (lines matching
```
### Requirement: <name>
```
  )

Detect spec conflicts

Build a map of

capability -> [changes that touch it]

auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
api  -> [change-c]            <- OK (only 1 change)

A conflict exists when 2+ selected changes have delta specs for the same capability.

Resolve conflicts agentically

For each conflict, investigate the codebase:

a. Read the delta specs from each conflicting change to understand what each claims to add/modify

b. Search the codebase for implementation evidence:
- Look for code implementing requirements from each delta spec
- Check for related files, functions, or tests
c. Determine resolution:
- If only one change is actually implemented -> sync that one's specs
- If both implemented -> apply in chronological order (older first, newer overwrites)
- If neither implemented -> skip spec sync, warn user
d. Record resolution for each conflict:
- Which change's specs to apply
- In what order (if both)
- Rationale (what was found in codebase)

Show consolidated status table

Display a table summarizing all changes:

| Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
|---------------------|-----------|-------|---------|-----------|--------|
| schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
| project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
| add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
| add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |

For conflicts, show the resolution:

* Conflict resolution:
  - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)

For incomplete changes, show warnings:

Warnings:
- add-verify-skill: 1 incomplete artifact, 3 incomplete tasks

Confirm batch operation

Use AskUserQuestion tool with a single confirmation:
- "Archive N changes?" with options based on status
- Options might include:
  - "Archive all N changes"
  - "Archive only N ready changes (skip incomplete)"
  - "Cancel"
If there are incomplete changes, make clear they'll be archived with warnings.
Execute archive for each confirmed change

Process changes in the determined order (respecting conflict resolution):

a. Sync specs if delta specs exist:
- Use the openspec-sync-specs approach (agent-driven intelligent merge)
- For conflicts, apply in resolved order
- Track if sync was done
b. Perform the archive:
bash
```
mkdir -p openspec/changes/archive
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
```
c. Track outcome for each change:
- Success: archived successfully
- Failed: error during archive (record error)
- Skipped: user chose not to archive (if applicable)

Display summary

Show final results:

## Bulk Archive Complete

Archived 3 changes:
- schema-management-cli -> archive/2026-01-19-schema-management-cli/
- project-config -> archive/2026-01-19-project-config/
- add-oauth -> archive/2026-01-19-add-oauth/

Skipped 1 change:
- add-verify-skill (user chose not to archive incomplete)

Spec sync summary:
- 4 delta specs synced to main specs
- 1 conflict resolved (auth: applied both in chronological order)

If any failures:

Failed 1 change:
- some-change: Archive directory already exists

Conflict Resolution Examples

Example 1: Only one implemented

Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]

Checking add-oauth:
- Delta adds "OAuth Provider Integration" requirement
- Searching codebase... found src/auth/oauth.ts implementing OAuth flow

Checking add-jwt:
- Delta adds "JWT Token Handling" requirement
- Searching codebase... no JWT implementation found

Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.

Example 2: Both implemented

Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]

Checking add-rest-api (created 2026-01-10):
- Delta adds "REST Endpoints" requirement
- Searching codebase... found src/api/rest.ts

Checking add-graphql (created 2026-01-15):
- Delta adds "GraphQL Schema" requirement
- Searching codebase... found src/api/graphql.ts

Resolution: Both implemented. Will apply add-rest-api specs first,
then add-graphql specs (chronological order, newer takes precedence).

Output On Success

undefined

在一次操作中归档多个已完成的变更。

该Skill允许你批量归档变更，通过检查代码库来智能处理规格冲突，以确定实际已实现的内容。

输入：无需提供（会提示进行选择）

步骤

获取活跃变更

运行

openspec list --json

获取所有活跃变更。

如果不存在活跃变更，告知用户并停止操作。

提示选择变更

使用AskUserQuestion工具的多选功能让用户选择变更：

显示每个变更及其 schema
包含“所有变更”选项
允许选择任意数量的变更（1个及以上均可，2个及以上为典型使用场景）

重要提示：请勿自动选择。务必让用户自行选择。

批量验证 - 收集所有选中变更的状态

针对每个选中的变更，收集以下信息：

a. 工件状态 - 运行

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

解析
```
schemaName
```
和
```
artifacts
```
列表
记录哪些工件处于
```
done
```
状态，哪些处于其他状态

b. 任务完成情况 - 读取

openspec/changes/<name>/tasks.md

统计
```
- [ ]
```
（未完成）与
```
- [x]
```
（已完成）的数量
如果不存在任务文件，记录为“无任务”

c. Delta规格 - 检查

openspec/changes/<name>/specs/

列出存在的所有能力规格
针对每个规格，提取需求名称（匹配
```
### Requirement: <name>
```
的行）

检测规格冲突

构建一个

能力 -> [涉及该能力的变更]

的映射：

auth -> [change-a, change-b]  <- 冲突（2个及以上变更）
api  -> [change-c]            <- 正常（仅1个变更）

当2个及以上选中的变更针对同一能力拥有delta规格时，即存在冲突。

智能解决冲突

针对每个冲突，检查代码库：

a. 读取delta规格：从每个冲突变更中读取delta规格，以了解各自声称要添加/修改的内容

b. 搜索代码库以寻找实现证据：

查找实现每个delta规格中需求的代码
检查相关文件、函数或测试

c. 确定解决方案：

如果仅一个变更已实际实现 -> 同步该变更的规格
如果两个变更均已实现 -> 按时间顺序应用（先旧后新，新的覆盖旧的）
如果两个变更均未实现 -> 跳过规格同步，向用户发出警告

d. 记录每个冲突的解决方案：

要应用哪个变更的规格
应用顺序（如果两者都要应用）
理由（在代码库中发现的内容）

显示合并后的状态表格

显示汇总所有变更的表格：

| Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
|---------------------|-----------|-------|---------|-----------|--------|
| schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
| project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
| add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
| add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |

针对冲突，显示解决方案：

* Conflict resolution:
 - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)

针对未完成的变更，显示警告：

Warnings:
- add-verify-skill: 1 incomplete artifact, 3 incomplete tasks

确认批量操作

使用AskUserQuestion工具进行单次确认：

询问“归档N个变更？”，选项基于状态而定
选项可能包括：
- “归档所有N个变更”
- “仅归档N个已就绪的变更（跳过未完成的）”
- “取消”

如果存在未完成的变更，需明确告知用户归档这些变更时会附带警告。

执行每个已确认变更的归档操作

按照确定的顺序处理变更（遵循冲突解决方案中的顺序）：

a. 同步规格（如果存在delta规格）：

使用openspec-sync-specs方法（由Agent驱动的智能合并）
针对冲突，按已解决的顺序应用
记录是否已完成同步

b. 执行归档：

bash

mkdir -p openspec/changes/archive
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>

c. 跟踪每个变更的结果：

成功：已成功归档
失败：归档过程中出错（记录错误信息）
跳过：用户选择不归档（如适用）

显示汇总结果

展示最终结果：

undefined

Bulk Archive Complete

Archived N changes:

<change-1> -> archive/YYYY-MM-DD-<change-1>/
<change-2> -> archive/YYYY-MM-DD-<change-2>/

Spec sync summary:

N delta specs synced to main specs
No conflicts (or: M conflicts resolved)


**Output On Partial Success**

Archived 3 changes:

schema-management-cli -> archive/2026-01-19-schema-management-cli/
project-config -> archive/2026-01-19-project-config/
add-oauth -> archive/2026-01-19-add-oauth/

Skipped 1 change:

add-verify-skill (user chose not to archive incomplete)

Spec sync summary:

4 delta specs synced to main specs
1 conflict resolved (auth: applied both in chronological order)


如果存在失败的情况：

Failed 1 change:

some-change: Archive directory already exists


**冲突解决示例**

示例1：仅一个变更已实现

Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]

Checking add-oauth:

Delta adds "OAuth Provider Integration" requirement
Searching codebase... found src/auth/oauth.ts implementing OAuth flow

Checking add-jwt:

Delta adds "JWT Token Handling" requirement
Searching codebase... no JWT implementation found

Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.


示例2：两个变更均已实现

Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]

Checking add-rest-api (created 2026-01-10):

Delta adds "REST Endpoints" requirement
Searching codebase... found src/api/rest.ts

Checking add-graphql (created 2026-01-15):

Delta adds "GraphQL Schema" requirement
Searching codebase... found src/api/graphql.ts

Resolution: Both implemented. Will apply add-rest-api specs first, then add-graphql specs (chronological order, newer takes precedence).


**成功时的输出**

Bulk Archive Complete (partial)

Bulk Archive Complete

Archived N changes:

<change-1> -> archive/YYYY-MM-DD-<change-1>/

Skipped M changes:

<change-2> (user chose not to archive incomplete)

Failed K changes:

<change-3>: Archive directory already exists


**Output When No Changes**

Archived N changes:

<change-1> -> archive/YYYY-MM-DD-<change-1>/
<change-2> -> archive/YYYY-MM-DD-<change-2>/

Spec sync summary:

N delta specs synced to main specs
No conflicts (or: M conflicts resolved)


**部分成功时的输出**

No Changes to Archive

Bulk Archive Complete (partial)

No active changes found. Use

/opsx:new

to create a new change.


**Guardrails**

- Allow any number of changes (1+ is fine, 2+ is the typical use case)
- Always prompt for selection, never auto-select
- Detect spec conflicts early and resolve by checking codebase
- When both changes are implemented, apply specs in chronological order
- Skip spec sync only when implementation is missing (warn user)
- Show clear per-change status before confirming
- Use single confirmation for entire batch
- Track and report all outcomes (success/skip/fail)
- Preserve .openspec.yaml when moving to archive
- Archive directory target uses current date: YYYY-MM-DD-<name>
- If archive target exists, fail that change but continue with others

Archived N changes:

<change-1> -> archive/YYYY-MM-DD-<change-1>/

Skipped M changes:

<change-2> (user chose not to archive incomplete)

Failed K changes:

<change-3>: Archive directory already exists


**无变更时的输出**

—

No Changes to Archive

—

No active changes found. Use

/opsx:new

to create a new change.


**约束规则**

- 允许选择任意数量的变更（1个及以上均可，2个及以上为典型使用场景）
- 始终提示用户选择，绝不自动选择
- 尽早检测规格冲突，并通过检查代码库解决
- 当两个变更均已实现时，按时间顺序应用规格
- 仅当实现缺失时跳过规格同步（并向用户发出警告）
- 在确认前清晰显示每个变更的状态
- 对整个批量操作进行单次确认
- 跟踪并报告所有结果（成功/跳过/失败）
- 移动到归档目录时保留.openspec.yaml文件
- 归档目录目标使用当前日期：YYYY-MM-DD-<name>
- 如果归档目标已存在，该变更归档失败，但继续处理其他变更