openspec-sync

OpenSpec Sync

Context and documentation synchronization for OpenSpec changes. Keeps CONTEXT-llm.md and docs in sync with implementation state.

Workflow: Check → Gather → Write

flowchart LR
    A["Get status via CLI"] --> B["Read current state"]
    B --> C["Gather context"]
    C --> D["Write updates"]
    D --> E["Verify idempotent"]

    classDef action fill:#C8E6C9,stroke:#388E3C,color:#000
    class A,B,C,D,E action

Critical: Use openspec status for change state, never parse files directly.

Guardrails

Autonomous (no confirmation needed):

• CONTEXT-llm.md updates
• Doc content refresh
• Status queries via CLI

Ask-first (pause and confirm):

• Creating new doc files not mentioned in proposal
• Deleting outdated docs
• Major restructuring of existing docs

CLI Delegation

Always use CLI for status:

openspec status {change-id}

Never:

• Parse proposal.md for status manually
• Infer status from file existence
• Maintain separate status tracking

The CLI is the single source of truth for change status.

Commands

sync

Full synchronization: updates CONTEXT-llm.md and refreshes docs in one command.

Input: $ARGUMENTS = change-id

Workflow:

1. Run openspec status {change-id} for current state
2. Read git state: git status --short, git log -1 --oneline
3. Read openspec/changes/{change-id}/tasks.md for progress
4. Update CONTEXT-llm.md with gathered state
5. Identify docs affected by implementation (Glob for modified files)
6. Refresh affected docs if out of sync

Output:

✅ Sync complete for {change-id}
- CONTEXT-llm.md: updated
- Docs refreshed: {count} files
- Change status: {status from CLI}

docs

Refresh documentation files only (no CONTEXT-llm.md update).

Input: $ARGUMENTS = change-id

Workflow:

1. Run openspec status {change-id} for affected files
2. Read openspec/changes/{change-id}/proposal.md → Affected Files
3. Glob for modified files since change started
4. Identify docs that reference changed files
5. Update those docs to reflect current implementation