Spec Archive Skill

Archive completed development specs with proper documentation and index maintenance.

Reference: See reference.md.

When to Use

Archive a spec when:

• All success criteria met
• Tests passing and code merged
• Ready to start new work
• Spec is "done enough" and blocking new work
• User explicitly requests archival

Don't archive when:

• Spec is actively in progress
• Blocking issues remain unresolved
• Branch has unmerged changes
• Critical checklist items incomplete (unless user confirms)

Workflow

Step 1: Validate Spec Argument

Parse spec name from command argument:

# User provides: add-temporal-joins
# Look for: ./specs/active/add-temporal-joins/

If not found, list available specs and ask which to archive.

Step 2: Verify Completion Status

Before archiving, check:

• Read spec.md - status should be "Complete"
• Read tasks.yaml - verify all tasks have status: completed
• If incomplete, ask: "This spec appears incomplete. Archive anyway? (y/n)"

Step 3: Pre-Archive Updates

Update documents before moving:

In spec.md:

• Set status to Complete
• Add **Completed**: [Today's date] after Started date
• Ensure all success criteria marked complete

In tasks.yaml:

• Update meta.progress to final count (e.g., "45/45")
• Update meta.last_updated to today
• Ensure all tasks have status: completed
• Mark any phase checkpoints as verified: true

In context.md:

• Update "Last Updated" to today
• Add Archive Notes section using templates/archive-notes.md

Step 4: Archive the Spec

mkdir -p ./specs/archive/
mv ./specs/active/{spec-name} ./specs/archive/{spec-name}

Step 5: Git Operations (Optional)

If spec has associated branch:

1. Check current branch
2. If on spec branch, ask: "Switch back to main? (y/n)"
3. Ask: "Delete spec branch {branch} (only if merged)? (y/n)"

Step 6: Create/Update Archive Index

Create ./specs/archive/README.md if doesn't exist using templates/archive-index.md.

Add entry at top of Archive Index section:

### [Spec Name] - [Today's Date]
- **Duration**: [Started] → [Completed]
- **Branch**: [branch-name if applicable]
- **Summary**: [One sentence from spec.md Overview]
- **Location**: `./specs/archive/{spec-name}/`

---

Step 7: Confirm Completion

Report to user:

Archived: {spec-name}

  From: ./specs/active/{spec-name}/
  To:   ./specs/archive/{spec-name}/

  Files archived:
  - spec.md (Complete)
  - context.md (Final notes added)
  - tasks.yaml (X/Y tasks complete)

  Archive index updated: ./specs/archive/README.md

  [If branch operations performed]:
  Git: Switched to main, deleted branch {branch}

Partial Completion Handling

If archiving incomplete spec (user confirmed):

• Mark status as Incomplete - [Reason] not Complete
• In Archive Notes, clearly document what was NOT completed
• Explain why spec was abandoned/deferred
• Consider creating new spec for remaining work

Archive Notes Template

See templates/archive-notes.md for full template including:

• Summary (2-3 sentences)
• Key Outcomes (deliverables)
• Technical Debt / Future Work
• Lessons Learned

Templates

• templates/archive-notes.md - Archive Notes section for context.md
• templates/archive-index.md - Archive README template

Success Criteria

• Spec moved from ./specs/active/ to ./specs/archive/
• All three documents updated with completion status
• Archive Notes added to context.md
• Archive index entry created
• User informed of next steps

Integration

Workflow:

• During task: Use /spec.update to sync status
• After task: Use this skill to archive
• Result: Clean ./specs/active/, historical record preserved

Related:

• Command: /spec.archive
• Skills: spec-create (creation), spec-update (reminder)

Reference

See reference.md for archive organization guidelines and troubleshooting.