skills.rest
aguachis
aguachisCOMMUNITY
Explore all skills by this author →
GitHub

openspec-sync-specs

Merge delta spec changes into main OpenSpec capability specifications.

Updated Jun 24, 2026
Search Tags:#requirements#cli#merge#spec-driven development#openspec#spec sync#delta specs
One-click install
npx skills add https://github.com/aguachis/Nicole-DB --skill openspec-sync-specs-aguachis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openspec-sync-specs
Source: https://github.com/aguachis/Nicole-DB/tree/main/.agents/skills/openspec-sync-specs
Command: npx skills add https://github.com/aguachis/Nicole-DB --skill openspec-sync-specs-aguachis

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 delta specs (ADDED, MODIFIED, REMOVED, RENAMED requirements) from an OpenSpec change directly into the main specs, performing intelligent merging instead of blind overwriting. ## Core Features & Use Cases - Intelligent Requirement Merging: Adds new requirements, updates modified ones, removes deprecated ones, and renames requirements while preserving untouched content and ordering. - Store-Aware Operation: Supports OpenSpec stores via --store <id> flags so specs in registered standalone repos can be synced, not just the local repository. - Safe Capability Retirement: Deletes a spec.md only when strict conditions hold (empty requirements, valid Purpose, retire_capabilities: true marker), preventing accidental spec loss. - Use Case: After finishing a change that adds two requirements and modifies one in the billing/invoices capability, run the sync to update the main spec, validate it with openspec validate --specs, and keep the change active for later archiving. ## Quick Start Ask the agent to sync the delta specs from change "add-billing-invoices" into the main specs without archiving the change.

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?▼

Select the change, run openspec status to get artifactPaths.specs.existingOutputPaths, then apply each delta's ADDED, MODIFIED, REMOVED, and RENAMED sections to the matching main spec. Finish by running openspec validate --specs to confirm the merged specs are valid.

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 and moves the change, so sync is used when implementation is still in progress.

Can I sync only some delta specs instead of all of them?▼

Yes. A caller can narrow the sync by naming explicit entries from existingOutputPaths, and only those paths are merged. The selection is never widened back, and unknown paths are reported rather than silently dropped.

Does openspec-sync-specs work with OpenSpec stores?▼

Yes. Run openspec store list --json to discover registered store ids, then pass --store <id> on commands like status, list, show, and validate. The flag stays sticky for the whole workflow and targets the store instead of the local repo.

When is a main spec file deleted during a sync?▼

A spec.md is deleted only when all retirement conditions hold: no requirement blocks remain, the spec is well-formed with a Purpose, it was not already empty, the change declares retire_capabilities: true, and the path resolves inside the real specs root.

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

The sync stops if the openspec instructions specs command exits non-zero or returns invalid JSON, since artifact rules could not be confirmed. It also stops when no delta specs exist in existingOutputPaths or a named path is not in that list.

Related Skills

Explore More Software Engineering Skills→
MetaCubeXMetaCubeX
4.1k

openspec-sync-specs

Merge delta specifications into main specs under openspec/specs.

Official
Intermediate
captaincontratcaptaincontrat

openspec-archive-change

Archives completed OpenSpec changes with metadata preservation using the openspec CLI.

Official
Advanced
AlmogMaayanAlmogMaayan

ptp-archive-force

Force-archives OpenSpec changes while bypassing task, review, and validation gates.

Community
Advanced
moltbook-experimentsmoltbook-experiments
3

openspec-sync-specs

Merge delta specs into main specs using ADDED, MODIFIED, REMOVED, and RENAMED rules.

Official
Advanced