openspec-archive-change

Archive a completed change in the experimental workflow.

Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run openspec store list --json to discover registered store ids, then pass --store <id> on the commands that read or write specs and changes (new change, status, instructions, list, show, validate, archive, doctor, context). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local openspec/ root.

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

1. If no change name provided, prompt for selection

   Run openspec list --json --store "<store-id>" (omit the store option for repo-local work) to get available changes. Use the AskUserQuestion tool to let the user select.

   Show only active changes (not already archived). Include the schema used for each change if available.

   IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.

2. Check artifact completion status

   Run openspec status --change "<name>" --json --store "<store-id>" to check artifact completion.

   Parse the JSON to understand:

   • schemaName: The workflow being used
   • planningHome, changeRoot, artifactPaths, and actionContext: path and scope context
   • artifacts: List of artifacts with their status (done or other)

   If any artifacts are not done:

   • Display warning listing incomplete artifacts
   • Use AskUserQuestion tool to confirm user wants to proceed
   • Proceed if user confirms

3. Check schema-resolved task completion status

   Run openspec instructions apply --change "<name>" --json --store "<store-id>" and use its progress and tasks fields. Do not assume a tasks.md path or Markdown checkbox syntax; the active schema controls the task artifact and representation.

   If the apply instructions report incomplete tasks:

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

   If the schema exposes no tasks: Proceed without a task-related warning.

4. Assess delta spec sync state

   Use artifactPaths.specs.existingOutputPaths from status JSON to check for delta specs. If none exist, proceed without sync prompt. Resolve every delta and main-spec path from the selected store's status/root metadata; never substitute a repository-local openspec/specs path when a store is active.

   If delta specs exist:

   • Compare each concrete delta path with its corresponding main spec under the selected OpenSpec root returned by the CLI
   • 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 the user chooses sync, invoke openspec-sync-specs for the same change and store. Archive only after that sync succeeds and its result has been verified. If the user chooses "Archive without syncing", ask for explicit confirmation and archive only after confirmation. If the user chooses "Cancel", or synchronization fails, stop immediately without moving the change.

5. Perform the archive

   Create an archive directory under planningHome.changesDir if it doesn't exist:

   mkdir -p "<planningHome.changesDir>/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 changeRoot to the archive directory