openspec-sync-specs · diff
v1.0 to v1.0
47 added, 29 removed. Audit A to A.
---
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.
license: MIT
compatibility: Requires openspec CLI.
metadata:
- author: openspec
- version: "1.0"
- generatedBy: "1.4.1"
+ author: openspec
+ version: "1.0"
+ generatedBy: "1.4.1"
---
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).
+ 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).
- **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.
+ **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` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+ Run `openspec list --json` 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.
+ **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user
+ choose.
2. **Resolve change context**
Run:
```bash
openspec status --change "<name>" --json
```
- 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.
+ 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.
3. **Find delta specs**
- Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+ 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 repo-local capability delta spec path returned by the CLI:
a. **Read the delta spec** to understand the intended changes
- b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+ b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not
+ exist yet)
c. **Apply changes intelligently**:
- **ADDED Requirements:**
- - If requirement doesn't exist in main spec → add it
- - If requirement already exists → update it to match (treat as implicit MODIFIED)
+ **ADDED Requirements:**
+ - If requirement doesn't exist in main spec → add it
+ - If requirement already exists → update it to match (treat as implicit
+ MODIFIED)
- **MODIFIED Requirements:**
- - Find the requirement in main spec
- - Apply the changes - this can be:
- - Adding new scenarios (don't need to copy existing ones)
- - Modifying existing scenarios
- - Changing the requirement description
- - Preserve scenarios/content not mentioned in the delta
+ **MODIFIED Requirements:**
+ - Find the requirement in main spec
+ - Apply the changes - this can be:
+ - Adding new scenarios (don't need to copy existing ones)
+ - Modifying existing scenarios
+ - Changing the requirement description
+ - Preserve scenarios/content not mentioned in the delta
- **REMOVED Requirements:**
- - Remove the entire requirement block from main spec
+ **REMOVED Requirements:**
+ - Remove the entire requirement block from main spec
- **RENAMED Requirements:**
- - Find the FROM requirement, rename to TO
+ **RENAMED Requirements:**
+ - Find the FROM requirement, rename to TO
d. **Create new main spec** if capability doesn't exist yet:
- - Create `openspec/specs/<capability>/spec.md`
- - Add Purpose section (can be brief, mark as TBD)
- - Add Requirements section with the ADDED requirements
+ - Create `openspec/specs/<capability>/spec.md`
+ - Add Purpose section (can be brief, mark as TBD)
+ - Add Requirements section with the ADDED requirements
5. **Show summary**
After applying all changes, summarize:
- Which capabilities were updated
- What changes were made (requirements added/modified/removed/renamed)
**Delta Spec Format Reference**
```markdown
## 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, just include that scenario under MODIFIED - don't copy existing scenarios
- - The delta represents *intent*, not a wholesale replacement
+
+ - To add a scenario, just include that scenario under MODIFIED - don't copy
+ existing scenarios
+ - 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
- 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