Skip to content

fix(templates): make archive sync guidance profile-agnostic when sync skill is uninstalled (#913) #1443

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hsusul wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix(templates): make archive sync guidance profile-agnostic when sync skill is uninstalled (#913) #1443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f0221c5
fix(templates): make archive sync guidance profile-agnostic when sync…
hsusul Jul 26, 2026
52f6d7d
Merge branch 'main' into fix/profile-agnostic-archive-sync-guidance
clay-good Jul 27, 2026
8c632a8
fix(archive): make command and bulk archive paths root-aware, synchro…
hsusul Jul 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions skills/openspec-archive-change/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Archive a completed change in the experimental workflow.
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving

To sync, run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis from above, and wait for it to finish. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
To sync, run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge) for change '<name>' (if `openspec-sync-specs` is not installed, perform the spec sync directly by merging delta specs into main specs under `openspec/specs/`), passing the delta spec analysis from above, and wait for it to finish. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Use the store-aware main-spec root for direct sync.

  • skills/openspec-archive-change/SKILL.md#L75-L75: replace literal openspec/specs/ with the <planningHome.root>/openspec/specs/ location established earlier.
  • src/core/templates/workflows/archive-change.ts#L77-L77: update the source template accordingly, then regenerate the installed skill.
📍 Affects 2 files
  • skills/openspec-archive-change/SKILL.md#L75-L75 (this comment)
  • src/core/templates/workflows/archive-change.ts#L77-L77
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/openspec-archive-change/SKILL.md` at line 75, Update the direct
spec-sync instruction in skills/openspec-archive-change/SKILL.md to use the
store-aware <planningHome.root>/openspec/specs/ path instead of the literal
openspec/specs/ path. Apply the same change in the archive-change template at
src/core/templates/workflows/archive-change.ts, then regenerate the installed
skill from the updated template.


Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
Expand Down Expand Up @@ -127,6 +127,6 @@ Archive a completed change in the experimental workflow.
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven)
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven), or perform the spec sync directly if that workflow is not installed
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
29 changes: 20 additions & 9 deletions skills/openspec-bulk-archive-change/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,19 +122,28 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
so match what the user picked rather than the wording above:
- "Cancel" — stop, do not archive. Report that nothing was archived and skip the remaining steps.
- The archive-everything option — proceed with every selected change
- The ready-only option — proceed with only the changes the step 6 table marks `Ready` or `Ready*`, and record the rest as Skipped in step 8c. If a `Ready*` change's conflict partner is skipped, re-derive that conflict's resolution using only the changes being archived.
- The ready-only option — proceed with only the changes the step 6 table marks `Ready` or `Ready*`, and record the rest as Skipped in step 8d. If a `Ready*` change's conflict partner is skipped, re-derive that conflict's resolution using only the changes being archived.
- Anything else — ask again rather than archiving

8. **Execute archive for each confirmed change**

Process changes in the determined order (respecting conflict resolution):

a. **Sync specs** if delta specs exist:
- Use the openspec-sync-specs approach (agent-driven intelligent merge)
- For conflicts, apply in resolved order
- Track if sync was done
- Run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge, or merge delta specs directly into main specs at `<planningHome.root>/openspec/specs/<capability>/spec.md` if sync workflow is not installed) for each change, passing the delta spec analysis, and wait for it to finish.
- For conflicts, apply in resolved order.
- Do not delegate to a background task — step 8c would move `changeRoot` out from under a sync that is still reading it.

b. **Perform the archive**:
b. **Verify main specs before moving changeRoot**:
- Re-run the comparison against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` against main spec at `<planningHome.root>/openspec/specs/<capability>/spec.md` (use the store-aware `planningHome.root` from step 3 status JSON, not a hardcoded repo path).
- Verify that main specs are updated:
- ADDED requirements present
- MODIFIED requirements carrying scenario and description changes named in the delta, with their other scenarios intact
- REMOVED requirements gone
- RENAMED requirements present under the new name and absent under the old one
- If sync failed or any capability does not match verification, report what differs and fail/skip moving that change's `changeRoot` — do not archive that change. `changeRoot` remains intact.

c. **Perform the archive**:

Target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<name>` (same rule as `openspec archive`).

Expand All @@ -143,9 +152,9 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
```

c. **Track outcome** for each change:
d. **Track outcome** for each change:
- Success: archived successfully
- Failed: error during archive (record error)
- Failed: error during archive or spec verification (record error)
- Skipped: user chose not to archive (if applicable)

9. **Display summary**
Expand Down Expand Up @@ -178,7 +187,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig

Example 1: Only one implemented
```text
Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
Conflict: <planningHome.root>/openspec/specs/auth/spec.md touched by [add-oauth, add-jwt]

Checking add-oauth:
- Delta adds "OAuth Provider Integration" requirement
Expand All @@ -193,7 +202,7 @@ Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.

Example 2: Both implemented
```text
Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
Conflict: <planningHome.root>/openspec/specs/api/spec.md touched by [add-rest-api, add-graphql]

Checking add-rest-api (created 2026-01-10):
- Delta adds "REST Endpoints" requirement
Expand Down Expand Up @@ -257,3 +266,5 @@ No active changes found. Create a new change to get started.
- Preserve .openspec.yaml when moving to archive
- Archive directory target uses current date: YYYY-MM-DD-<name>; a name that already starts with a `YYYY-MM-DD-` prefix is used as-is (never stack a second date)
- If archive target exists, fail that change but continue with others
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven) for each change
- Never archive a change while a spec sync is still in flight — run the sync inline and verify main specs at `<planningHome.root>/openspec/specs/<capability>/spec.md` before moving `changeRoot`
8 changes: 4 additions & 4 deletions src/core/templates/workflows/archive-change.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ ${STORE_SELECTION_GUIDANCE}
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving

To sync, run the \`openspec-sync-specs\` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis from above, and wait for it to finish. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
To sync, run the \`openspec-sync-specs\` workflow inline (agent-driven intelligent merge) for change '<name>' (if \`openspec-sync-specs\` is not installed, perform the spec sync directly by merging delta specs into main specs under \`openspec/specs/\`), passing the delta spec analysis from above, and wait for it to finish. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.

Then re-run the comparison from the top of this step against every capability that has a delta spec in \`artifactPaths.specs.existingOutputPaths\` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
Expand Down Expand Up @@ -129,7 +129,7 @@ ${STORE_SELECTION_GUIDANCE}
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven)
- If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven), or perform the spec sync directly if that workflow is not installed
Comment thread
coderabbitai[bot] marked this conversation as resolved.
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving \`changeRoot\`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting`,
license: 'MIT',
Expand Down Expand Up @@ -207,7 +207,7 @@ ${STORE_SELECTION_GUIDANCE}
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving

To sync, run the \`openspec-sync-specs\` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis from above, and wait for it to finish. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
To sync, run the \`/opsx:sync\` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis from above, and wait for it to finish. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.

Then re-run the comparison from the top of this step against every capability that has a delta spec in \`artifactPaths.specs.existingOutputPaths\` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
Expand Down Expand Up @@ -309,7 +309,7 @@ Target archive directory already exists.
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven)
- If sync is requested, run the \`/opsx:sync\` workflow inline (agent-driven)
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving \`changeRoot\`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting`
};
Expand Down
Loading