Spec Archive

completed change -> gate -> archive -> specs updated -> commit -> PR.

The last link in spec-explore -> spec-propose -> spec-apply -> spec-verify -> spec-archive. /opsx:archive owns the OpenSpec mechanics and never branches, commits, or opens a PR. This skill owns that seam, plus the one gate the CLI declines to enforce. Never author spec content here.

Preconditions

openspec context --json

no_openspec_root -> stop, offer openspec init --tools claude, wait for the user. Never auto-init, never fall back to the current directory. Use the returned root.path as authoritative. User names a store -> openspec store list --json for ids, then --store <id> on every command that accepts one, sticky for the rest of the run.

Then two things must hold before anything is archived:

• The work is verified - spec-verify ran and its gate passed. Not verified -> send the user there and stop. Why -> archiving folds the delta into the specs, so doing it before the code is proven makes the spec the fiction rather than the record
• The tree is clean enough to commit the archive alone. Unrelated edits in flight -> commit or stash them first. Why -> the archive move and the spec fold are one commit, and a dirty tree drags someone else's work into it

The Gate

This is the point of this wrapper. Read the task progress before archiving, and never pass --yes without having read it:

openspec instructions apply --change "<name>" --json

state: "all_done", equivalently progress.remaining == 0 -> the gate passes. Anything else -> stop. Name every unticked task and send the user to spec-apply. Do not archive. Do not "just tick the boxes".

Do not gate on isComplete from openspec status --json. It reports that all four artifact FILES exist, not that any task is finished. Probed: a change with 1 of 3 tasks ticked reports isComplete: true while openspec instructions apply --json reports progress: {total: 3, complete: 1, remaining: 2}. Only the second one counts checkboxes.

Probed, on a change with 0 of 3 tasks complete, openspec archive <name> --yes printed exactly one line:

Warning: N incomplete task(s) found. Continuing due to --yes flag.

It then exited 0 and folded the spec delta into openspec/specs/ as though the feature had shipped. The warning is the only signal, nothing fails, and the exit code says success.

Why -> the archive is the moment a claim becomes the project's durable specification. An unearned archive leaves openspec/specs/ describing a feature nobody built, and every later change plans against that lie.

--yes suppresses the interactive prompt after the gate has passed. It is never the way past the warning.

Flow

1. Preflight per Preconditions. Resolve the change name - user named one -> use it; ambiguous -> openspec list --json and ask. Never guess which change is "the finished one"
2. Gate on progress.remaining per The Gate. Nonzero -> stop here and report the unticked tasks
3. Archive. .claude/commands/opsx/archive.md present -> invoke it; the OpenSpec-side mechanics are its job and this skill owns only the git seam. Absent -> drive the CLI directly:

   openspec archive "<name>"

4. Post-check:

   openspec validate --archived

   Catches an archived change whose tasks were never finished. It is a backstop, not a substitute for The Gate - by the time it fires the specs are already wrong and the fix is a revert, not an edit
5. Read what moved (see What The Archive Writes) and commit both halves as one commit via git-commit, scoped to the spec:

   docs(spec): archive <change-name>

   Why -> splitting them leaves a commit where openspec/specs/ claims a capability whose change record is still sitting open in openspec/changes/
6. git-pr-create on the branch spec-propose started. It derives the title, body, and label itself, and fills the template's Resolves: line from the branch-to-issue link spec-propose set (git config --get branch.<name>.issue). No link -> the line is dropped and the PR closes nothing. Say so; do not let it go missing quietly
7. Report: the archive path, the capability specs touched, the PR url, plus the missing-link note if step 6 hit one. Nothing else

What The Archive Writes

Two file moves, one commit:

• openspec/changes/<name>/ -> openspec/changes/archive/<YYYY-MM-DD>-<name>/
• Each spec delta folded into openspec/specs/<capability>/spec.md

git status after the archive shows both. Stage both.

Never hand-edit anything under openspec/specs/. The openspec CLI owns those files and the next archive overwrites the edit without a word. A spec that ended up wrong gets fixed by correcting the CHANGE - its specs/ delta, via spec-propose's flow - and letting the archive write it. This is the docs-autoupdate seam: the change is the source, the archived spec is the output.

Flags

• --skip-specs is for a change that genuinely has nothing to fold. Never reach for it to get past a validation complaint. Why -> the complaint says the delta is malformed; skipping the fold archives the change anyway and leaves the specs silent about work that shipped
• --no-validate is never used. Why -> validation is the only check that the delta about to become the project's spec is well-formed, and it runs on exactly the file nobody will re-read afterwards

Several Changes At Once

/opsx:bulk-archive where installed, then one commit per change - same message shape, same gate applied to each. Not installed -> it needs the custom profile, and the profile is GLOBAL state shared by every repo on the machine. Ask before changing it, never silently:

openspec config set profile custom

User declines -> loop this skill one change at a time. That is the correct fallback, not a degraded one.

When Not to Use This

• Tasks still unticked -> spec-apply
• Applied but not proven green -> spec-verify
• Just opening a PR, with no change to archive -> git-pr-create
• Retiring a whole capability rather than completing a change -> that is a new change, so spec-propose

Rules

• Never openspec archive --yes without reading progress.remaining first. isComplete is artifact existence, not task completion. See The Gate
• Never --no-validate
• Never hand-edit openspec/specs/ - correct the change and re-archive
• Never split the directory move and the spec fold across two commits
• Never gh pr merge. Why -> merging is the user's review gate, and an agent merging its own spec work removes the only human check between generated code and the base branch
• Never auto-run openspec init. Offer it and wait
• Never mutate the global openspec profile without asking
• Never --no-verify on the commit or the push