Openspec Sync Change Docs

Load the change context

Prefer the OpenSpec CLI:

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

If the CLI is unavailable or errors, fall back to direct filesystem discovery under openspec/changes/<name>/ and read whichever of these files exist:

• proposal.md
• design.md
• tasks.md
• delta specs in openspec/changes/<name>/specs/*/spec.md

For each capability touched by the change, read the base-branch main spec from the base branch itself, not from the working tree:

git show <base>:openspec/specs/<capability>/spec.md

If that path does not exist on the base branch, treat the capability as new. The change docs are deltas against the base branch, not standalone full specs.

Measure implementation drift

Inspect the branch against the selected base branch before editing docs:

git diff --name-only <base>...HEAD
git diff --stat <base>...HEAD

Use the full branch diff only as a discovery aid. Then narrow the evidence set to files that clearly implement the selected change based on:

• capability names from the delta specs
• tasks and design references
• imports, symbols, tests, and entrypoints tied to the selected change

Read the changed code, tests, and configuration files that explain the actual behavior. Prefer implementation evidence over earlier artifact wording.

Pay special attention to:

• Behaviors added after the initial /opsx:apply
• Review-driven or user-requested tweaks
• Renamed or removed capabilities
• Test cases that describe the real acceptance behavior better than the stale spec text

If the branch contains unrelated work and you cannot confidently isolate the selected change, stop and ask instead of folding the whole branch into one change's docs.

Rewrite the change artifacts to match the code

Update only the active change artifacts unless the user explicitly asks for more:

• Rewrite proposal.md when the change scope, capability list, or impact statement materially shifted
• Rewrite design.md when the implemented architecture, data flow, API shape, or tradeoffs differ from the draft
• Rewrite tasks.md so completed work is checked off, obsolete tasks are removed or reworded, and remaining follow-ups reflect reality
• Rewrite each delta spec so it describes the actual diff from main

For delta specs:

• Use ## ADDED Requirements for behavior that exists on this branch but not in main
• Use ## MODIFIED Requirements when branch behavior changes an existing requirement from main
• Use ## REMOVED Requirements when the branch intentionally removes behavior present in main
• Use ## RENAMED Requirements only for genuine renames

Keep delta specs minimal and capability-scoped. Do not copy an entire main spec into the change unless the whole requirement actually changed.

Decide whether the change should still be the same change

Stop and recommend a new change instead of force-fitting the docs when:

• The branch now implements a different intent from the original proposal
• The work spans unrelated capabilities that should be reviewed independently
• The old change can still be completed or archived on its own without rewriting history

Small scope adjustments, clarified requirements, and design corrections should stay in the same change.

Validate the rewritten docs

Re-read the updated artifacts against both:

• the changed code on the current branch
• the relevant base-branch specs read via git show <base>:openspec/specs/*/spec.md

Confirm:

• the docs describe what is actually implemented
• the delta specs still read as diffs, not full copies
• tasks.md status matches reality
• no edits leaked into unrelated change folders or main specs

Report the outcome

Summarize:

• which change was updated
• which artifact files changed
• the main implementation differences captured
• any remaining ambiguity or intentional drift that still needs a human decision