openspec-sync-specs

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).

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.

AskUserQuestion is ATTENDED-SESSIONS-ONLY (#2666). Every prompt below assumes a human is watching.
In an unattended session (a worker/supervisor run) AskUserQuestion is FORBIDDEN — the session hangs
until the log-tail watchdog pages it. Unattended, park instead: post ONE structured question comment
on the issue (options + recommendation + default), add the needs-decision label, write a blocked
marker with reason: needs-decision (or reason: seam1-approval at Seam 1), and EXIT, releasing the
machine. Resume only on a strictly-newer owner reply (a durable resume-dont-ask label is a standing
Seam-1 seal that stands in for the answer).

Steps

1. If no change name provided, prompt for selection

   Run openspec list --json to get available changes. Use the AskUserQuestion tool (attended only — unattended, PARK per the note above) 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

   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.

   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)

   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)

   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

   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

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

## 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
• 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