Openspec Archive Change

Check task completion status

Read the tasks file (typically tasks.md) to check for incomplete tasks.

Count tasks marked with - [ ] (incomplete) vs - [x] (complete).

If incomplete tasks found:

• Display warning showing count of incomplete tasks
• Use AskUserQuestion tool to confirm user wants to proceed
• Proceed if user confirms

If no tasks file exists: Proceed without task-related warning.

Assess delta spec sync state

Check for delta specs at openspec/changes/<name>/specs/. If none exist, proceed without sync prompt.

If delta specs exist:

• Compare each delta spec with its corresponding main spec at openspec/specs/<capability>/spec.md
• Determine what changes would be applied (adds, modifications, removals, renames)
• Show a combined summary before prompting

Prompt options:

• If changes needed: "Sync now (recommended)", "Archive without syncing"
• If already synced: "Archive now", "Sync anyway", "Cancel"

If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.

Commit and push all changes

Before archiving or switching branches, ALL work on the current branch MUST be committed and pushed.

a. Run git status --short to check for uncommitted changes (staged, unstaged, or untracked files related to this change).

b. If uncommitted changes exist:

• Stage and commit all relevant changes with a descriptive commit message.
• Push to the remote branch.
• Verify git status is clean before proceeding.

c. If the working tree is already clean: proceed.

CRITICAL: Do NOT move to step 6 (archive) or step 7 (branch switch) with uncommitted changes. Switching branches with a dirty working tree causes changes to follow you to the wrong branch or be lost entirely.

Perform the archive

Create the archive directory if it doesn't exist:

mkdir -p openspec/changes/archive

Generate target name using current date: YYYY-MM-DD-<change-name>

Check if target already exists:

• If yes: Fail with error, suggest renaming existing archive or using different date
• If no: Move the change directory to archive

mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>

Return to main branch

After the archive move completes, commit the archive:

git add openspec/changes/archive/
git commit -m "chore: archive openspec change <name>"
git push

Then switch branches:

git checkout main

The opsx/<name> branch still exists locally. Note in the summary that the developer can delete it manually with git branch -d opsx/<name> if desired.

Display summary

Show archive completion summary including:

• Change name
• Schema that was used
• Archive location
• Whether specs were synced (if applicable)
• Branch status (returned to main)
• Note about any warnings (incomplete artifacts/tasks)