Archives completed changes and merges specification deltas into living documentation. Use when changes are deployed, ready to archive, or specs need updating after implementation. Triggers include "openspec archive", "archive change", "merge specs", "complete proposal", "update documentation", "fina

Specification Archiving Archives completed change proposals and merges their spec deltas into the living specification documentation. Quick Start Archiving involves two main operations: 1. Move change folder to archive with timestamp 2. Merge spec deltas into living specs (ADDED/MODIFIED/REMOVED operations) Critical rule : Verify all tasks are complete before archiving. Archiving signifies deployment and completion. Workflow Copy this checklist and track progress: Step 1: Verify implementation is complete Before archiving, confirm all work is done: Ask the user : Step 2: Review spec deltas to merge Understand what will be merged: Identify : Which capabilities are affected How many requirements are ADDED/MODIFIED/REMOVED Where in living specs these changes belong Step 3: Create timestamped archive directory Example : Step 4: Merge ADDED requirements into living specs For each ADDED Requirements section: Process : 1. Locate the target living spec file 2. Append the new requirements to the end of the file 3. Maintain proper markdown formatting Example : Source ( spec/changes/add user auth/specs/authentication/spec delta.md ): Target ( spec/specs/authentication/spec.md ): Step 5: Merge MODIFIED requirements into living specs For each MODIFIED Requirements section: Process : 1. Locate the existing requirement in the living spec 2. Replace the ENTIRE requirement block (including all scenarios) 3. Use the complete updated text from the delta Example using sed : Manual approach (recommended for safety): Step 6: Merge REMOVED requirements into living specs For each REMOVED Requirements section: Process : 1. Locate the requirement in the living spec 2. Delete the entire requirement block 3. Add a comment documenting the removal Example : Pattern : Step 7: Move change folder to archive After all deltas are merged: Verify move succeeded : Step 8: Validate living spec structure After merging, validate the living specs are well formed: Manual review : Open each modified spec file Verify markdown formatting is correct Check requirements flow logically Ensure no duplicate requirements exist Merge Logic Reference ADDED Operation MODIFIED Operation REMOVED Operation RENAMED Operation (uncommon) Best Practices Pattern 1: Verify Before Moving Always verify delta merges before moving to archive: Pattern 2: Atomic Archiving Archive entire changes, not individual files: Good : Bad : Pattern 3: Archive Preservation The archive is a historical record. Never modify archived files: Pattern 4: Git Commit Strategy Recommended commit workflow: Advanced Topics For complex deltas : See [reference/MERGE LOGIC.md](reference/MERGE LOGIC.md) Conflict resolution : If multiple changes modified the same requirement, manual merge is required. Rollback strategy : To rollback an archive, reverse the process (move from archive back to changes, remove merged content from living specs). Common Patterns Pattern 1: Simple Addition Pattern 2: Behavioral Change Pattern 3: Deprecation Pattern 4: Feature with Multiple Requirements Anti Patterns to Avoid Don't : Archive incomplete implementations Merge deltas before deployment Modify archived files Skip validation after merging Forget to git commit merged specs Do : Verify all tasks complete before archiving Merge deltas carefully and completely Treat archive as immutable history Validate merged specs structure Commit merged specs before archiving move Troubleshooting Issue: Merge conflict (requirement exists in living spec) Solution : Issue: Can't find requirement to modify/remove Solution : Issue: Living spec has formatting errors after merge Solution : Reference Materials [MERGE LOGIC.md](reference/MERGE LOGIC.md) Detailed merge operation rules Token budget : This SKILL.md is approximately 480 lines, under the 500 line recommended limit.

openspec-archiving