openspec-sync-specs

Merge delta spec changes into main OpenSpec capability specifications.

1|Updated Jul 14, 2026
One-click install
npx skills add https://github.com/pablof7z/pod0 --skill openspec-sync-specs-pablof7z
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openspec-sync-specs
Source: https://github.com/pablof7z/pod0/tree/main/.agents/skills/openspec-sync-specs
Command: npx skills add https://github.com/pablof7z/pod0 --skill openspec-sync-specs-pablof7z

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping main capability specifications in sync with change proposals is tedious and error-prone when done by hand. This Skill applies the ADDED, MODIFIED, REMOVED, and RENAMED requirement blocks from a change's delta specs directly into the main specs, performing an intelligent merge instead of a blind overwrite. ## Core Features & Use Cases - Intelligent requirement merging: Adds new requirements, updates existing ones, removes deprecated ones, and applies renames while preserving content the delta does not mention. - Store-aware operation: Discovers registered OpenSpec stores and applies the correct --store flag so specs are synced in the right repository. - Safe capability retirement: Deletes a spec file only when strict conditions hold, including the retire_capabilities: true marker, and reports blockers otherwise. - Validation and summary: Runs openspec validate --specs after syncing and reports exactly which requirements were added, modified, removed, or renamed. - Use Case: After finishing a change that adds scenarios to the billing capability, ask the agent to sync the change's delta specs so the main billing spec reflects the new behavior without archiving the change. ## Quick Start Ask the agent to sync the delta specs from change "add-billing-invoices" into the main specs.

Frequently Asked Questions about openspec-sync-specs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I sync delta specs to main specs in OpenSpec?▼

Invoke the sync workflow with a change name, or let it infer the change from context. It reads the delta specs listed in the status JSON, merges each requirement into the matching main spec, then runs openspec validate --specs to confirm the result.

What is the difference between syncing specs and archiving a change?▼

Syncing updates the main specs while leaving the change active for further work. Archiving performs the same merge but also closes out the change, so sync is the right choice when implementation is still in progress.

Does openspec sync-specs work with registered stores?▼

Yes. It runs openspec store list --json to discover registered store ids and passes --store <id> on every spec-reading and spec-writing command, so delta and main specs resolve inside the selected store rather than the local repository.

When does syncing delete a main spec file?▼

A spec file is deleted only when removing requirements leaves no requirement blocks, the spec is otherwise well-formed, the change declares retire_capabilities: true, and the file resolves inside the real specs root. Otherwise the sync stops and reports the blocking condition.

Why does spec sync fail before writing any main spec?▼

The sync stops if the specs-instruction lookup exits non-zero or returns invalid JSON, if no delta specs exist in existingOutputPaths, or if a caller-named path is not in that list. It never infers delta specs from unrelated artifacts.