This repository (Asymmetric-al/core)
These repo-owned sections sit above the official OpenSpec skill. Reconcile this
overlay after upstream refreshes before running bun run skills:sync.
Use the locally pinned CLI only: bun run openspec -- <command>. Do not invoke
@latest. Core does not use Stores. Pass an explicit change ID before any
mutating OpenSpec operation. Follow AGENTS.md and docs/ai/rules/openspec.md.
Do not bypass TDD, exact base-maia, data-access boundaries, security, or
repository checks. Do not archive unmerged or incomplete work. Do not run
openspec update against the live customized repository. Do not treat product
runtime Eve as a coding agent.
Allowed-tools metadata includes Bash(bun:*) so the local wrapper can run.
Triggers
- The matching OpenSpec workflow is requested: Explore, Propose, Update, Apply,
Verify, Sync, or Archive.
- Numbered commands
/1-start-project through /4-close-project wrap these
workflows.
Workflow
- Read
openspec/config.yaml, openspec/project.md, and the relevant specs
or active change.
- Invoke
bun run openspec -- with the explicit change ID for mutating work.
- Keep Core TDD, UI, data-boundary, and Guardian rules in force.
- Leave the change active until implementation has merged.
Checklist
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).
Project check: Before writing, run bun run openspec -- list --json and confirm the root is the Core checkout containing its local openspec/ tree. A missing root, Store declaration, or external root is a configuration error: stop before writing and report it. Do not initialize a root or select an external Store.
<capability-path> is the spec directory relative to specs/ (for example, user-auth or identity/user-auth). Preserve the full path from each delta spec when resolving its main spec.
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
Select the change
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run
openspec list --json to get available changes and ask the user to select one
When prompting, show changes that have delta specs (under specs/ directory).
Always announce: "Using change: " and how to override (e.g., /openspec-sync-specs <other>).
Resolve change context
Run:
openspec status --change "<name>" --json
The JSON includes planningHome.root. Main specs live under <planningHome.root>/openspec/specs/ — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
Find delta specs
Use artifactPaths.specs.existingOutputPaths from the status JSON as the
only source of delta spec paths. If the specs entry is missing or
existingOutputPaths is empty, report that there are no delta specs to sync,
do not infer them from other artifacts, and stop without requesting artifact
instructions or writing a main spec.
Sync every path in existingOutputPaths unless the caller narrowed the set.
A caller narrows it by naming an explicit list of complete entries from
existingOutputPaths — copy those absolute values verbatim. Archive does
this inline, and a user can too (for example, by selecting the entry ending
in /specs/billing/invoices/spec.md).
Then sync only the named paths and leave the remaining delta specs untouched:
bulk archive excludes a delta whose implementation it could not find, and
syncing it anyway would write a main spec the caller deliberately withheld.
Carry that narrowed selection through step 4; never widen it back to the full
list. If a named path is not in existingOutputPaths, do not sync it —
report it and stop, rather than dropping it silently. If the named list is
empty, report that there is nothing to sync and stop without writing a main
spec.
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.
For each delta spec, apply changes to main specs
Before the first main-spec write, obtain one current specs-rule snapshot:
- If archive invoked this workflow inline and supplied a valid snapshot from
openspec instructions specs --change "<name>" --json, reuse it and do not
fetch the same instructions again.
- Otherwise run that command once now with the same selected-root flags.
- If the direct lookup exits non-zero or returns invalid artifact-instruction
JSON, report the error and stop before writing any main spec. Do not treat the
failure as an absent rule set.
- A valid response with omitted
rules means no artifact rules are configured
and the existing semantic merge continues.
Apply returned rules only to the content and form of the main specs produced
by this merge. Artifact rules are not operation guidance and cannot change
selected roots, delta paths, CLI checks, or workflow steps. Use their text as
constraints without copying it verbatim into a main spec or summary.
For each capability delta spec path selected in step 3 — the full existingOutputPaths list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
a. Read the delta spec to understand the intended changes
b. Read the main spec at <planningHome.root>/openspec/specs/<capability-path>/spec.md (may not exist yet)
If it does not exist yet (a new capability), match what openspec archive does:
only ADDED requirements may be applied - step d creates the spec from them.
MODIFIED and RENAMED have no requirement to act on, so stop the sync for that
capability and report that its main spec does not exist and only ADDED is allowed
for a new spec; never invent the missing requirement. REMOVED has nothing to
remove - skip it and warn.
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 the main spec does not have yet
- 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
- Retiring the capability. Delete the whole
spec.md - and the directory once
nothing else is left in it - only when ALL of these hold:
- removing the requirements this run left no requirement blocks;
- the rest of the spec is well-formed (it still has a
## Purpose);
- the main spec was not already empty before this sync - if you removed
nothing, change nothing;
- every other nonblank line in the whole file is accounted for as the
title, Purpose, Requirements header, or a canonical requirement's
statement, scenarios, or fenced examples;
- the change's
.openspec.yaml declares retire_capabilities: true;
- the
spec.md resolves inside the real specs root (do not follow a
capability-directory symlink to delete an external file).
If removing the selected requirements would leave no requirement blocks and
any retirement condition is not satisfied, do not modify the main spec. Stop
the sync for that capability, report the blocking condition, and tell the user
how to resolve it. Never write or leave an empty ## Requirements section.
When only the marker is missing, say that too - it is the one thing the user
can add to make the retirement go through.
- Deleting the file also deletes its
## Purpose; any other section blocks
retirement. Name Purpose when you report the retirement. Include a pasteable
git checkout only when the spec lived in the caller's checkout;
otherwise give checkout-scoped recovery guidance.
RENAMED Requirements:
- Find the FROM requirement, rename to TO
## Purpose in the delta:
- The main spec already has one and it is authoritative - leave it alone
(this is what
openspec archive does; it warns and moves on)
d. Create new main spec if capability doesn't exist yet:
- Only when the delta has ADDED requirements to put in it and no MODIFIED or
RENAMED requirements blocked this capability in step b. Otherwise create nothing
and leave the specs directory untouched. For a REMOVED-only delta, if the change's
.openspec.yaml declares retire_capabilities: true, report it as already retired
and continue without recreating the spec. Without that marker, report the sync as blocked:
openspec archive rejects it with Spec must have at least one requirement.
An empty delta has no operations to sync; report it as blocked too.
Never write an empty ## Requirements section.
- Create
<planningHome.root>/openspec/specs/<capability-path>/spec.md
- Add Purpose section: copy the delta's
## Purpose body verbatim when it has one
(this is what openspec archive does); only write a brief TBD placeholder when it does not
- Add Requirements section with the ADDED requirements
- Follow the Main Spec Format Reference below
Validate updated main specs
Run openspec validate --specs with the same selected-root flags used earlier.
If validation fails, report the problems and do not claim the sync succeeded.
Show summary
After applying all changes, summarize:
- Which capabilities were updated
- What changes were made (requirements added/modified/removed/renamed)
- Any new main spec left with a TBD Purpose placeholder, so it gets written
now rather than lingering
- Any capability retired, naming the deleted
spec.md, its Purpose, and
either a pasteable git checkout or checkout-scoped recovery guidance
Delta Spec Format Reference
# Spec Delta
## Purpose
Only on a delta that introduces a brand-new capability. Seeds the new main spec.
## 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
The system SHALL keep doing the existing thing, now also handling A.
#### Scenario: Scenario the main spec already has
- **WHEN** user does X
- **THEN** system does Y
#### 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`
Main Spec Format Reference
Main specs are what the delta merges INTO. They must never contain delta operation headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) - after syncing, every requirement lives under a single ## Requirements section:
# <capability> Specification
## Purpose
Short description of what this capability does and why it exists.
## Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
Key Principle: Intelligent Merging
Unlike programmatic merging, you merge rather than overwrite:
- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change.
openspec validate and openspec archive both reject one that drops a scenario the main spec still has.
- Keep anything the delta does not mention, in the main spec's existing order
- 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
- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
- 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
- Use only
artifactPaths.specs.existingOutputPaths; never infer delta specs from unrelated artifacts
- Honor a caller-supplied subset of
existingOutputPaths; never widen it back to the full list
- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
- Artifact rules constrain only the specs being written and are never copied into output files
1---2name: openspec-sync-specs3description: Sync delta specs from an OpenSpec change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change. Also use when the user says "openspec sync" or "opsx sync".4allowed-tools: Bash(openspec:*), Bash(bun:*)5license: MIT6compatibility: Requires openspec CLI.7metadata:8 source: https://skillmd.com/skills/asymmetric-al/openspec-sync-specs9 author: openspec10 version: "1.0"11---1213<!-- CORE-OVERLAY-START -->1415## This repository (Asymmetric-al/core)1617These repo-owned sections sit above the official OpenSpec skill. Reconcile this18overlay after upstream refreshes before running `bun run skills:sync`.1920Use the locally pinned CLI only: `bun run openspec -- <command>`. Do not invoke21`@latest`. Core does not use Stores. Pass an explicit change ID before any22mutating OpenSpec operation. Follow `AGENTS.md` and `docs/ai/rules/openspec.md`.23Do not bypass TDD, exact `base-maia`, data-access boundaries, security, or24repository checks. Do not archive unmerged or incomplete work. Do not run25`openspec update` against the live customized repository. Do not treat product26runtime Eve as a coding agent.2728Allowed-tools metadata includes `Bash(bun:*)` so the local wrapper can run.2930### Triggers3132- The matching OpenSpec workflow is requested: Explore, Propose, Update, Apply,33 Verify, Sync, or Archive.34- Numbered commands `/1-start-project` through `/4-close-project` wrap these35 workflows.3637### Workflow38391. Read `openspec/config.yaml`, `openspec/project.md`, and the relevant specs40 or active change.412. Invoke `bun run openspec --` with the explicit change ID for mutating work.423. Keep Core TDD, UI, data-boundary, and Guardian rules in force.434. Leave the change active until implementation has merged.4445### Checklist4647- [ ] Local pinned CLI used via `bun run openspec --`48- [ ] Explicit change ID used for mutating operations49- [ ] Stores were not introduced50- [ ] Incomplete or unmerged work was not archived51- [ ] `openspec update` was not run against the live repo52- [ ] Product Eve was not treated as a coding agent5354<!-- CORE-OVERLAY-END -->5556Sync delta specs from a change to main specs.5758This 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).5960**Project check:** Before writing, run `bun run openspec -- list --json` and confirm the root is the Core checkout containing its local `openspec/` tree. A missing root, Store declaration, or external root is a configuration error: stop before writing and report it. Do not initialize a root or select an external Store.6162`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.6364**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.6566**Steps**67681. **Select the change**6970 If a name is provided, use it. Otherwise:71 - Infer from conversation context if the user mentioned a change72 - Auto-select if only one active change exists73 - If ambiguous, run `openspec list --json` to get available changes and ask the user to select one7475 When prompting, show changes that have delta specs (under `specs/` directory).7677 Always announce: "Using change: <name>" and how to override (e.g., `/openspec-sync-specs <other>`).78792. **Resolve change context**8081 Run:8283 ```bash84 openspec status --change "<name>" --json85 ```8687 The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.88893. **Find delta specs**9091 Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the92 only source of delta spec paths. If the `specs` entry is missing or93 `existingOutputPaths` is empty, report that there are no delta specs to sync,94 do not infer them from other artifacts, and stop without requesting artifact95 instructions or writing a main spec.9697 Sync every path in `existingOutputPaths` unless the caller narrowed the set.98 A caller narrows it by naming an explicit list of complete entries from99 `existingOutputPaths` — copy those absolute values verbatim. Archive does100 this inline, and a user can too (for example, by selecting the entry ending101 in `/specs/billing/invoices/spec.md`).102 Then sync only the named paths and leave the remaining delta specs untouched:103 bulk archive excludes a delta whose implementation it could not find, and104 syncing it anyway would write a main spec the caller deliberately withheld.105 Carry that narrowed selection through step 4; never widen it back to the full106 list. If a named path is not in `existingOutputPaths`, do not sync it —107 report it and stop, rather than dropping it silently. If the named list is108 empty, report that there is nothing to sync and stop without writing a main109 spec.110111 Each delta spec file contains sections like:112 - `## ADDED Requirements` - New requirements to add113 - `## MODIFIED Requirements` - Changes to existing requirements114 - `## REMOVED Requirements` - Requirements to remove115 - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)116117 If no delta specs found, inform user and stop.1181194. **For each delta spec, apply changes to main specs**120121 Before the first main-spec write, obtain one current specs-rule snapshot:122 - If archive invoked this workflow inline and supplied a valid snapshot from123 `openspec instructions specs --change "<name>" --json`, reuse it and do not124 fetch the same instructions again.125 - Otherwise run that command once now with the same selected-root flags.126 - If the direct lookup exits non-zero or returns invalid artifact-instruction127 JSON, report the error and stop before writing any main spec. Do not treat the128 failure as an absent rule set.129 - A valid response with omitted `rules` means no artifact rules are configured130 and the existing semantic merge continues.131132 Apply returned `rules` only to the content and form of the main specs produced133 by this merge. Artifact rules are not operation guidance and cannot change134 selected roots, delta paths, CLI checks, or workflow steps. Use their text as135 constraints without copying it verbatim into a main spec or summary.136137 For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):138139 a. **Read the delta spec** to understand the intended changes140141 b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)142143 **If it does not exist yet** (a new capability), match what `openspec archive` does:144 only ADDED requirements may be applied - step d creates the spec from them.145 MODIFIED and RENAMED have no requirement to act on, so stop the sync for that146 capability and report that its main spec does not exist and only ADDED is allowed147 for a new spec; never invent the missing requirement. REMOVED has nothing to148 remove - skip it and warn.149150 c. **Apply changes intelligently**:151152 **ADDED Requirements:**153 - If requirement doesn't exist in main spec → add it154 - If requirement already exists → update it to match (treat as implicit MODIFIED)155156 **MODIFIED Requirements:**157 - Find the requirement in main spec158 - Apply the changes - this can be:159 - Adding new scenarios the main spec does not have yet160 - Modifying existing scenarios161 - Changing the requirement description162 - Preserve scenarios/content not mentioned in the delta163164 **REMOVED Requirements:**165 - Remove the entire requirement block from main spec166 - Retiring the capability. Delete the whole `spec.md` - and the directory once167 nothing else is left in it - only when ALL of these hold:168 1. removing the requirements _this run_ left no requirement blocks;169 2. the rest of the spec is well-formed (it still has a `## Purpose`);170 3. the main spec was not already empty before this sync - if you removed171 nothing, change nothing;172 4. every other nonblank line in the whole file is accounted for as the173 title, Purpose, Requirements header, or a canonical requirement's174 statement, scenarios, or fenced examples;175 5. the change's `.openspec.yaml` declares `retire_capabilities: true`;176 6. the `spec.md` resolves inside the real specs root (do not follow a177 capability-directory symlink to delete an external file).178 If removing the selected requirements would leave no requirement blocks and179 any retirement condition is not satisfied, do not modify the main spec. Stop180 the sync for that capability, report the blocking condition, and tell the user181 how to resolve it. Never write or leave an empty `## Requirements` section.182 When only the marker is missing, say that too - it is the one thing the user183 can add to make the retirement go through.184 - Deleting the file also deletes its `## Purpose`; any other section blocks185 retirement. Name Purpose when you report the retirement. Include a pasteable186 `git checkout` only when the spec lived in the caller's checkout;187 otherwise give checkout-scoped recovery guidance.188189 **RENAMED Requirements:**190 - Find the FROM requirement, rename to TO191192 **`## Purpose` in the delta:**193 - The main spec already has one and it is authoritative - leave it alone194 (this is what `openspec archive` does; it warns and moves on)195196 d. **Create new main spec** if capability doesn't exist yet:197 - Only when the delta has ADDED requirements to put in it and no MODIFIED or198 RENAMED requirements blocked this capability in step b. Otherwise create nothing199 and leave the specs directory untouched. For a REMOVED-only delta, if the change's200 `.openspec.yaml` declares `retire_capabilities: true`, report it as already retired201 and continue without recreating the spec. Without that marker, report the sync as blocked:202 `openspec archive` rejects it with `Spec must have at least one requirement`.203 An empty delta has no operations to sync; report it as blocked too.204 Never write an empty `## Requirements` section.205 - Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`206 - Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one207 (this is what `openspec archive` does); only write a brief TBD placeholder when it does not208 - Add Requirements section with the ADDED requirements209 - Follow the **Main Spec Format Reference** below2102115. **Validate updated main specs**212213 Run `openspec validate --specs` with the same selected-root flags used earlier.214 If validation fails, report the problems and do not claim the sync succeeded.2152166. **Show summary**217218 After applying all changes, summarize:219 - Which capabilities were updated220 - What changes were made (requirements added/modified/removed/renamed)221 - Any new main spec left with a TBD Purpose placeholder, so it gets written222 now rather than lingering223 - Any capability retired, naming the deleted `spec.md`, its Purpose, and224 either a pasteable `git checkout` or checkout-scoped recovery guidance225226**Delta Spec Format Reference**227228```markdown229# Spec Delta230231## Purpose232233Only on a delta that introduces a brand-new capability. Seeds the new main spec.234235## ADDED Requirements236237### Requirement: New Feature238239The system SHALL do something new.240241#### Scenario: Basic case242243- **WHEN** user does X244- **THEN** system does Y245246## MODIFIED Requirements247248### Requirement: Existing Feature249250The system SHALL keep doing the existing thing, now also handling A.251252#### Scenario: Scenario the main spec already has253254- **WHEN** user does X255- **THEN** system does Y256257#### Scenario: New scenario to add258259- **WHEN** user does A260- **THEN** system does B261262## REMOVED Requirements263264### Requirement: Deprecated Feature265266## RENAMED Requirements267268- FROM: `### Requirement: Old Name`269- TO: `### Requirement: New Name`270```271272**Main Spec Format Reference**273274Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:275276```markdown277# <capability> Specification278279## Purpose280281Short description of what this capability does and why it exists.282283## Requirements284285### Requirement: New Feature286287The system SHALL do something new.288289#### Scenario: Basic case290291- **WHEN** user does X292- **THEN** system does Y293```294295**Key Principle: Intelligent Merging**296297Unlike programmatic merging, you merge rather than overwrite:298299- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate` and `openspec archive` both reject one that drops a scenario the main spec still has.300- Keep anything the delta does not mention, in the main spec's existing order301- Use your judgment to merge changes sensibly302303**Output On Success**304305```markdown306## Specs Synced: <change-name>307308Updated main specs:309310**<capability-1>**:311312- Added requirement: "New Feature"313- Modified requirement: "Existing Feature" (added 1 scenario)314315**<capability-2>**:316317- Created new spec file318- Added requirement: "Another Feature"319320Main specs are now updated. The change remains active - archive when implementation is complete.321```322323**Guardrails**324325- Read both delta and main specs before making changes326- Preserve existing content not mentioned in delta327- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers328- If something is unclear, ask for clarification329- Show what you're changing as you go330- The operation should be idempotent - running twice should give same result331- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts332- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list333- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline334- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response335- Artifact rules constrain only the specs being written and are never copied into output files