openspec-sync-specs

name	openspec-sync-specs
description	Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
allowed-tools	Bash(openspec:*)
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.6.0"}

Sync delta specs from a change to main specs.

This is an agent-driven operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).

Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run openspec store list --json to discover registered store ids, then pass --store <id> on the commands that read or write specs and changes (new change, status, instructions, list, show, validate, archive, doctor, context). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local openspec/ root.

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

1. If no change name provided, prompt for selection

   Run openspec list --json --store "<store-id>" (omit the store option for repo-local work) to get available changes. Use the AskUserQuestion tool to let the user select.

   Show changes that have delta specs (under specs/ directory).

   IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.

2. Resolve change context

   Run:

   openspec status --change "<name>" --json --store "<store-id>"
   

3. Find delta specs

   Use artifactPaths.specs.existingOutputPaths from the status JSON as the list of delta spec files.

   Each delta spec file contains sections like:

   • ## ADDED Requirements - New requirements to add
   • ## MODIFIED Requirements - Changes to existing requirements
   • ## REMOVED Requirements - Requirements to remove
   • ## RENAMED Requirements - Requirements to rename (FROM:/TO: format)

   If no delta specs found, inform user and stop.

4. For each delta spec, apply changes to main specs

   For each concrete capability delta spec path returned by the selected store's status output:

   a. Read the delta spec to understand the intended changes

   b. Resolve and read the corresponding main spec from the selected OpenSpec root returned by the CLI (it may not exist yet). Never assume the current repository's openspec/specs directory when a store is active.

   c. Apply changes intelligently:

   ADDED Requirements:

   • If requirement doesn't exist in main spec → add it
   • If a requirement with the same normalized heading/identity already exists → merge only descriptions or scenarios explicitly changed by the delta; preserve all unmentioned content

   MODIFIED Requirements:

   • Find the requirement in main spec
   • Match scenarios by normalized scenario heading/identity
   • Add only scenarios that do not exist; update an existing scenario only when the delta explicitly changes that scenario

Delta Spec Format Reference

## ADDED Requirements

### Requirement: New Feature

The system SHALL do something new.

#### Scenario: Basic case

- **WHEN** user does X
- **THEN** system does Y

## MODIFIED Requirements

### Requirement: Existing Feature

#### Scenario: New scenario to add

- **WHEN** user does A
- **THEN** system does B

## REMOVED Requirements

### Requirement: Deprecated Feature

## RENAMED Requirements

- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`

Key Principle: Intelligent Merging

Unlike programmatic merging, you can apply partial updates:

• To add a scenario, include that scenario under MODIFIED; identity matching ensures an existing scenario is updated or skipped rather than duplicated
• The delta represents intent, not a wholesale replacement
• Use your judgment to merge changes sensibly

Output On Success

## Specs Synced: <change-name>

Updated main specs:

**<capability-1>**:
- Added requirement: "New Feature"
- Modified requirement: "Existing Feature" (added 1 scenario)

**<capability-2>**:
- Created new spec file
- Added requirement: "Another Feature"

Main specs are now updated. The change remains active - archive when implementation is complete.

Guardrails

• Read both delta and main specs before making changes
• Preserve existing content not mentioned in delta
• Match requirements and scenarios by stable heading identity and never replace unmentioned descriptions or scenarios
• Add only missing requirements/scenarios; rerunning the same sync must produce no diff
• If something is unclear, ask for clarification
• Show what you're changing as you go
• The operation should be idempotent - running twice should give same result