An OpenSpec change is finished when its spec deltas have been folded into openspec/specs/, the change directory has moved to the archive, and its code is on your branch. SpecBuddy does all three from the Cockpit.

Sync

Sync merges the change’s deltas into the main specs: each specs/<capability>/spec.md in the change updates openspec/specs/<capability>/spec.md — adding, modifying or removing the requirements the delta lists, creating the capability if it is new. The change itself stays where it is.

Sync is available at any point, not only when every task is done. Syncing early keeps the main specs truthful while a long change is in progress, and lets other changes build on requirements this one introduced.

It is an agent run (/opsx:sync): it appears in the log, the Explorer row says Running: sync, and the Cockpit’s History tab records it with a diff of the main specs before and after.

Archive

Archive moves the change directory to openspec/changes/archive/<date>-<change-id>/. From then on it is listed under Archive in the Spec Explorer, with everything it had — documents, logs, run history — but without actions.

The two usually go together, so the Cockpit’s button is a split: Sync and archive runs both in one agent session, and its dropdown offers Sync or Archive alone.

Then merge

If the change ran in a worktree, the completion card of the Sync and archive run offers Commit & Merge, Commit and Merge — the same actions described in Worktrees and git. Take Commit & Merge for the usual case: the worktree is committed, its branch merged into the branch you have checked out, and the worktree removed.

If you press Merge before syncing, SpecBuddy points it out and offers to sync and archive first — it would rather not land code whose specs are still deltas.

If the change ran in your current branch, there is nothing to merge; commit as usual.

What survives archiving

Everything. The archived change’s row expands to its documents; Show Agent Log opens its logs; the Cockpit’s History tab lists every run — propose, each task, every refine, the sync and the archive — with before/after snapshots you can still diff. The run history is stored outside the repository (under ~/.specbuddy/), keyed by the change id, so the move into the archive folder does not detach it.

Checklist

  1. Every task done and reviewed — the Explorer badge reads 7/7 Tasks.
  2. Sync and archive in the Cockpit; read the log’s completion card (which main specs changed).
  3. Commit & Merge from that card; resolve a conflict if the agent reports one.
  4. Delete the feature/<change-id> branch when you no longer need it — SpecBuddy removes the worktree, not the branch.
  5. Commit the updated openspec/specs/ and the archived change together with the code, if the merge didn’t already — both are part of the change.