From ec99091b7a513c9a73f07e1a3ab51bd28a8298dc Mon Sep 17 00:00:00 2001 From: Howard Date: Thu, 7 May 2026 10:58:36 +0800 Subject: [PATCH 1/2] docs(opsx): fix /opsx:sync description and add detailed documentation - Changed description from 'Sync delta specs to main' to 'Merge delta specs into main specs' - Added detailed Usage section for /opsx:sync command - Now consistent with commands.md and migration-guide.md - Improves documentation completeness and clarity --- docs/opsx.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/opsx.md b/docs/opsx.md index 095f159d27..0fb59e98b1 100644 --- a/docs/opsx.md +++ b/docs/opsx.md @@ -165,7 +165,7 @@ rules: | `/opsx:apply` | Implement tasks, updating artifacts as needed | | `/opsx:update` | Revise a change's planning artifacts and keep them coherent | | `/opsx:verify` | Validate implementation against artifacts (expanded workflow) | -| `/opsx:sync` | Sync delta specs to main (default workflow, optional) | +| `/opsx:sync` | Merge delta specs into main specs (optional) | | `/opsx:archive` | Archive when done | | `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) | | `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) | @@ -215,6 +215,22 @@ Works through tasks, checking them off as you go. If you're juggling multiple ch ``` Revises the change's existing planning artifacts and keeps them coherent - in any direction (a design edit may ripple back to the proposal). Planning artifacts only: it never edits code, and it never creates missing artifacts (that's `/opsx:continue`). Every edit is confirmed with you first. If the change was already implemented, it recommends `/opsx:apply` so the code catches up with the revised plan. If your revision changes the change's *intent*, start fresh instead - see [When to Update vs. Start Fresh](#when-to-update-vs-start-fresh). +### Sync delta specs +```text +/opsx:sync +``` +Merges delta specs from the current change into main specs. Optional—archive will prompt to sync if needed. + +**What it does:** +- Reads delta specs from change folder +- Merges changes into main `openspec/specs/` directory +- Does not archive the change (remains active) + +**When to use:** +- You want to update main specs before archiving +- Multiple changes need to see each other's specs +- You're iterating on specs and want to test integration + ### Finish up ``` /opsx:archive # Move to archive when done (prompts to sync specs if needed) From 02c5938f97e6b6b0614e0ee51b251bafd85c6c05 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Fri, 7 Aug 2026 16:22:50 -0500 Subject: [PATCH 2/2] docs(opsx): harden Sync delta specs section for accuracy and house style Fold the /opsx:sync usage entry into a single prose paragraph to match the six sibling Usage sections (heading -> fence -> paragraph), and fix two accuracy issues found against src/core/templates/workflows/sync-specs.ts: - Drop the invented "changes see each other's specs" and "test integration" use cases (no cross-change propagation or test step exists). - State that sync applies the whole delta -- a REMOVED requirement is deleted from the main spec and a RENAMED one retitled -- so the section no longer reads as additive-only. - Use the file's spaced em-dash convention. Docs-site build verified: sync-docs + fumadocs next build compile and render /docs/opsx end-to-end. Co-Authored-By: Claude Opus 4.8 --- docs/opsx.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/opsx.md b/docs/opsx.md index 0fb59e98b1..c1b2dba37f 100644 --- a/docs/opsx.md +++ b/docs/opsx.md @@ -219,17 +219,7 @@ Revises the change's existing planning artifacts and keeps them coherent - in an ```text /opsx:sync ``` -Merges delta specs from the current change into main specs. Optional—archive will prompt to sync if needed. - -**What it does:** -- Reads delta specs from change folder -- Merges changes into main `openspec/specs/` directory -- Does not archive the change (remains active) - -**When to use:** -- You want to update main specs before archiving -- Multiple changes need to see each other's specs -- You're iterating on specs and want to test integration +Merges the current change's delta specs into your main `openspec/specs/` without archiving — the change stays active. It applies the whole delta: a requirement under `## REMOVED` is deleted from the main spec and a renamed one is retitled in place, while content the delta doesn't mention is left untouched. Syncing is optional — archive prompts you to sync first if you haven't. Reach for it when you want main specs updated before archiving, when a parallel change needs to build on specs this one just added, or when you want to review the merged main spec before archiving. ### Finish up ```