openspec-archiving

name	openspec-archiving
description	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", "finalize spec", "mark as done".

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:

Archive Progress:
- [ ] Step 1: Verify implementation is complete
- [ ] Step 2: Review spec deltas to merge
- [ ] Step 3: Create timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into living specs
- [ ] Step 5: Merge MODIFIED requirements into living specs
- [ ] Step 6: Merge REMOVED requirements into living specs
- [ ] Step 7: Move change folder to archive
- [ ] Step 8: Validate living spec structure

Step 1: Verify implementation is complete

Before archiving, confirm all work is done:

# Check for IMPLEMENTED marker
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"

# Review tasks
cat spec/changes/{change-id}/tasks.md

# Check git status for uncommitted work
git status

Ask the user:

Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?

Step 2: Review spec deltas to merge

Understand what will be merged:

# List all spec delta files
find spec/changes/{change-id}/specs -name "*.md" -type f

# Read each delta
for file in spec/changes/{change-id}/specs/**/*.md; do
    echo "=== $file ==="
    cat "$file"
done

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

# Create archive with today's date
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}

Example:

# For change "add-user-auth" archived on Oct 26, 2025
mkdir -p spec/archive/2025-10-26-add-user-auth

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):

## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session

Target (spec/specs/authentication/spec.md):

# Append to living spec
cat >> spec/specs/authentication/spec.md << 'EOF'

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session
EOF

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:

# Find and replace requirement block
# This is conceptual - actual implementation depends on structure

# First, identify the line range of the old requirement
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

# Find the end (next requirement or end of file)
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md | \
           grep -n "^### Requirement:" | head -1 | cut -d: -f1)

# Delete old requirement
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md

# Insert new requirement at same position
# (Extract from delta and insert)

Manual approach (recommended for safety):

1. Open living spec in editor
2. Find the requirement by name
3. Delete entire block (requirement + all scenarios)
4. Paste updated requirement from delta
5. Save

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:

# Option 1: Delete with comment
# Manually edit spec/specs/authentication/spec.md

# Add deprecation comment
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md

# Delete the requirement block manually or with sed

Pattern:

<!-- Removed 2025-10-26: User must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

Step 7: Move change folder to archive

After all deltas are merged:

# Move entire change folder to archive
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

Verify move succeeded:

# Check archive exists
ls -la spec/archive/${TIMESTAMP}-{change-id}

# Check changes directory is clean
ls spec/changes/ | grep "{change-id}"  # Should return nothing

Step 8: Validate living spec structure

After merging, validate the living specs are well-formed:

# Check requirement format
grep -n "### Requirement:" spec/specs/**/*.md

# Check scenario format
grep -n "#### Scenario:" spec/specs/**/*.md

# Count requirements per spec
for spec in spec/specs/**/spec.md; do
    count=$(grep -c "### Requirement:" "$spec")
    echo "$spec: $count requirements"
done

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

Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written

MODIFIED Operation

Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive

REMOVED Operation

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->

RENAMED Operation (uncommon)

Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead

Best Practices

Pattern 1: Verify Before Moving

Always verify delta merges before moving to archive:

# After merging, check diff
git diff spec/specs/

# Review changes
git diff spec/specs/authentication/spec.md

# If correct, commit
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth"

# Then archive
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

Pattern 2: Atomic Archiving

Archive entire changes, not individual files:

Good:

# Move complete change folder
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

Bad:

# Don't cherry-pick files
mv spec/changes/add-user-auth/proposal.md spec/archive/
# (leaves orphaned files)

Pattern 3: Archive Preservation

The archive is a historical record. Never modify archived files:

❌ Don't: Edit files in spec/archive/
✓ Do: Treat archive as read-only history

Pattern 4: Git Commit Strategy

Recommended commit workflow:

# Commit 1: Merge deltas
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth

- Added User Login requirement
- Modified Password Policy requirement
- Removed Legacy Auth requirement"

# Commit 2: Archive change
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"

Advanced Topics

For complex deltas: See 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

Change adds 1 new requirement → Append to spec → Archive

Pattern 2: Behavioral Change

Change modifies 1 requirement → Replace in spec → Archive

Pattern 3: Deprecation

Change removes 1 requirement → Delete from spec with comment → Archive

Pattern 4: Feature with Multiple Requirements

Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive

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:

1. If names match but content differs → Use MODIFIED pattern
2. If truly different requirements → Rename one
3. If duplicate by mistake → Use whichever is correct

Issue: Can't find requirement to modify/remove

Solution:

1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if already removed
3. Check if in different capability file

Issue: Living spec has formatting errors after merge

Solution:

1. Fix formatting manually
2. Re-run validation: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels

Reference Materials

• MERGE_LOGIC.md - Detailed merge operation rules

---

Token budget: This SKILL.md is approximately 480 lines, under the 500-line recommended limit.