1---2name: openspec-sync-specs3description: 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.4license: MIT5compatibility: Requires openspec CLI.6metadata:7 author: openspec8 version: "1.0"9 generatedBy: "1.4.1"10---1112Sync delta specs from a change to main specs.1314This 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).1516**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.1718**Steps**19201. **If no change name provided, prompt for selection**2122 Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.2324 Show changes that have delta specs (under `specs/` directory).2526 **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.27282. **Resolve change context**2930 Run:31 ```bash32 openspec status --change "<name>" --json33 ```3435 If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.36373. **Find delta specs**3839 Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.4041 Each delta spec file contains sections like:42 - `## ADDED Requirements` - New requirements to add43 - `## MODIFIED Requirements` - Changes to existing requirements44 - `## REMOVED Requirements` - Requirements to remove45 - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)4647 If no delta specs found, inform user and stop.48494. **For each delta spec, apply changes to main specs**5051 For each repo-local capability delta spec path returned by the CLI:5253 a. **Read the delta spec** to understand the intended changes5455 b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)5657 c. **Apply changes intelligently**:5859 **ADDED Requirements:**60 - If requirement doesn't exist in main spec → add it61 - If requirement already exists → update it to match (treat as implicit MODIFIED)6263 **MODIFIED Requirements:**64 - Find the requirement in main spec65 - Apply the changes - this can be:66 - Adding new scenarios (don't need to copy existing ones)67 - Modifying existing scenarios68 - Changing the requirement description69 - Preserve scenarios/content not mentioned in the delta7071 **REMOVED Requirements:**72 - Remove the entire requirement block from main spec7374 **RENAMED Requirements:**75 - Find the FROM requirement, rename to TO7677 d. **Create new main spec** if capability doesn't exist yet:78 - Create `openspec/specs/<capability>/spec.md`79 - Add Purpose section (can be brief, mark as TBD)80 - Add Requirements section with the ADDED requirements81825. **Show summary**8384 After applying all changes, summarize:85 - Which capabilities were updated86 - What changes were made (requirements added/modified/removed/renamed)8788**Delta Spec Format Reference**8990```markdown91## ADDED Requirements9293### Requirement: New Feature94The system SHALL do something new.9596#### Scenario: Basic case97- **WHEN** user does X98- **THEN** system does Y99100## MODIFIED Requirements101102### Requirement: Existing Feature103#### Scenario: New scenario to add104- **WHEN** user does A105- **THEN** system does B106107## REMOVED Requirements108109### Requirement: Deprecated Feature110111## RENAMED Requirements112113- FROM: `### Requirement: Old Name`114- TO: `### Requirement: New Name`115```116117**Key Principle: Intelligent Merging**118119Unlike programmatic merging, you can apply **partial updates**:120- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios121- The delta represents *intent*, not a wholesale replacement122- Use your judgment to merge changes sensibly123124**Output On Success**125126```127## Specs Synced: <change-name>128129Updated main specs:130131**<capability-1>**:132- Added requirement: "New Feature"133- Modified requirement: "Existing Feature" (added 1 scenario)134135**<capability-2>**:136- Created new spec file137- Added requirement: "Another Feature"138139Main specs are now updated. The change remains active - archive when implementation is complete.140```141142**Guardrails**143- Read both delta and main specs before making changes144- Preserve existing content not mentioned in delta145- If something is unclear, ask for clarification146- Show what you're changing as you go147- The operation should be idempotent - running twice should give same result