sync

Sync — Merge Delta Specs into Main Specs (Expanded Workflow)

You are merging the delta specs from an active change into the canonical openspec/specs/ directory. Unlike /openspec:archive, this does NOT archive the change — it only updates the main specs.

Note: This is part of the expanded workflow. Use when you want to apply spec updates to the main spec directory before archiving the change.

Upstream source: Fission-AI/OpenSpec

When to Use This

Use /openspec:sync when:

• You want the main openspec/specs/ to reflect the latest changes while keeping the change active
• You're working on a long-running change and want to share spec updates with others
• You need the canonical specs updated before archiving (e.g., for other teams or changes that depend on these specs)

For normal workflow, /openspec:archive handles both sync and archiving in one step.

Workflow

Step 1: Identify the Change

• If the user specified a change name, use that
• Otherwise, list active changes in openspec/changes/ (those without archive status)
• Ask if multiple changes are active

Step 2: Preview the Sync

Before making any changes, show what will be merged:

Sync Preview for: [change-name]

Will merge:
  openspec/changes/[change-name]/specs/[capability-1]/spec.md
    → ADDED: Requirement: [name]
    → MODIFIED: Requirement: [name]
    
  openspec/changes/[change-name]/specs/[capability-2]/spec.md (new capability)
    → Will create: openspec/specs/[capability-2]/spec.md

Files that will be created or modified:
  openspec/specs/[capability-1]/spec.md  (modified)
  openspec/specs/[capability-2]/spec.md  (created)

Proceed? (yes/no)

Step 3: Merge Delta Specs

For each spec file in openspec/changes/<change-name>/specs/**/*.md, apply the delta operations to the corresponding file in openspec/specs/:

ADDED Requirements:

• If openspec/specs/<capability>/spec.md exists: append new requirements
• If it doesn't exist: create the file with the new requirements

MODIFIED Requirements:

• Locate ### Requirement: <name> in the main spec
• Replace the complete requirement block with the modified version
• Match header text exactly (whitespace-insensitive)

REMOVED Requirements:

• Remove the requirement block from the main spec
• Add a removal record at the bottom:

  ## Removed Requirements
  
  ### [Requirement Name] (removed: [DATE], change: [change-name])
  **Reason**: [from delta spec]
  **Migration**: [from delta spec]
  

RENAMED Requirements:

• Find the requirement using the FROM: name and update to the TO: name

Report each operation as it completes:

✓ Synced openspec/specs/[capability]/spec.md
  + ADDED: Requirement: [name]
  ~ MODIFIED: Requirement: [name]

Step 4: Output Summary

Sync Complete: [change-name]

  Main specs updated:
    openspec/specs/[capability-1]/spec.md — modified (2 requirements updated)
    openspec/specs/[capability-2]/spec.md — created (3 requirements added)

  Change remains active: openspec/changes/[change-name]/
  (Use /openspec:archive when the change is fully complete)

Notes

• Unlike /openspec:archive, sync does not move the change to the archive directory
• The change remains fully active and editable after sync
• You can sync multiple times for a long-running change
• Running sync and then archive will result in a no-op merge during archive (since specs are already merged)
• Conflicts are handled the same way as in /openspec:archive