archive

Archive a Change

You are archiving a completed OpenSpec change. This moves the change from openspec/changes/ to the archive and merges its specs into the main openspec/specs/ directory.

Upstream source: Fission-AI/OpenSpec

About Archiving

Archiving a change does two things:

1. Merges specs: Delta specs in openspec/changes/<change-name>/specs/ are merged into the canonical specs at openspec/specs/
2. Archives the change: Moves the change directory to openspec/changes/archive/<date>-<change-name>/

After archiving, the change is preserved for reference but no longer appears as active work.

Workflow

Step 1: Identify the Change to Archive

• If the user specified a change name, locate it at openspec/changes/<change-name>/
• If not specified, list changes that appear to be complete (all tasks checked) and ask the user to choose
• A change is complete when all items in tasks.md are checked [x]

If incomplete tasks remain, warn the user:

⚠️ Warning: [change-name] has [N] uncompleted tasks:
  - [ ] 3.2 [task description]
  - [ ] 4.1 [task description]

Are you sure you want to archive with incomplete tasks? (yes/no)

Step 2: Merge Delta Specs into Main Specs

For each spec file in openspec/changes/<change-name>/specs/**/*.md:

Read the delta spec and identify the operation headers:

• ## ADDED Requirements → Add new requirements to the main spec
• ## MODIFIED Requirements → Update existing requirements in the main spec
• ## REMOVED Requirements → Remove requirements from the main spec (with migration note)
• ## RENAMED Requirements → Rename requirements in the main spec

For ADDED requirements:

• Check if openspec/specs/<capability>/spec.md exists
  • If not: create it as a new spec file with the added requirements
  • If yes: append the new requirements to the spec file

For MODIFIED requirements:

• Locate the ### Requirement: <name> section in openspec/specs/<capability>/spec.md
• Replace the entire requirement block (from ### Requirement: through all its scenarios) with the modified version
• Ensure header text matches exactly (whitespace-insensitive)

For REMOVED requirements:

• Remove the requirement block from openspec/specs/<capability>/spec.md
• Add a comment or migration note at the bottom of the spec (for audit trail):

  ## Removed Requirements
  
  ### [Requirement Name] (removed: [DATE])
  **Reason**: [from the delta spec]
  **Migration**: [from the delta spec]
  

For RENAMED requirements:

• Find the requirement using the FROM: name
• Update the header to use the TO: name

Report each merge operation:

Merging specs for: [capability]
  ✓ ADDED: Requirement: [name]
  ✓ MODIFIED: Requirement: [name]
  ✓ REMOVED: Requirement: [name]

Step 3: Archive the Change Directory

Move the change directory to the archive:

From: openspec/changes/<change-name>/
To:   openspec/changes/archive/[TODAY'S DATE]-<change-name>/

Preserve all files (proposal.md, specs/, design.md, tasks.md, .openspec.yaml).

Step 4: Output Summary

Change Archived: [change-name]

  Specs Updated:
    openspec/specs/[capability-1]/spec.md
      ✓ Added: [N] requirements
      ✓ Modified: [N] requirements
    openspec/specs/[capability-2]/spec.md (created)
      ✓ Added: [N] requirements

  Archived to:
    openspec/changes/archive/[DATE]-[change-name]/

  Active changes remaining: [N]

Next: Start a new change with /openspec:propose

Edge Cases

No specs in the change: If openspec/changes/<change-name>/specs/ is empty or doesn't exist, skip the merge step and just archive the directory.

Conflicting requirements: If a MODIFIED requirement doesn't exist in the main spec (possibly deleted by another change), report the conflict:

⚠️ Conflict: Requirement "[name]" not found in openspec/specs/[capability]/spec.md
   Options:
     1. Add it as a new ADDED requirement instead
     2. Skip this requirement
     3. View the delta spec and decide manually

Missing main spec: If a capability's main spec doesn't exist for MODIFIED/REMOVED operations, ask the user how to proceed.

Behavior Rules

• Never delete the original change directory without archiving it
• Always verify spec merges are correct before completing the archive
• Preserve the complete history in the archive directory
• Report every spec change made during the merge