openspec-bulk-archive-change

name	openspec-bulk-archive-change
description	Archive multiple completed changes at once. Use when archiving several parallel changes.
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.3.1"}

Project context preflight before workflow actions: before this skill takes a workflow action, follow the project-constitution skill. Read root CONSTITUTION.md when present, enforce relevant project rules, stop on material conflicts, and follow the strict missing-constitution bootstrap/diagnostic policy. For architecture-sensitive work, also read ARCHITECTURE.md, adr/README.md, and relevant in-force adr/*.md. Read .secrets.local.env only when the current workflow actually needs a listed external system, and never reveal secret values.

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

1. Get active changes

   Run openspec list --json to get all active changes.

   If no active changes exist, inform user and stop.

2. Prompt for change selection

   Use Codex interactive user question tool when available, otherwise a concise Markdown question 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.

3. 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>)

4. 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.

5. 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

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

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

## Bulk Archive Complete (partial)

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

## No Changes to Archive

No active changes found. Create a new change to get started.

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-
• If archive target exists, fail that change but continue with others