Strategies/best practices to integrate multiple changes into one spec for the same domain

[alesky78]

From the docs, OpenSpec keeps a source-of-truth per domain at openspec/specs/domain/spec.md,

During archive, those deltas are merged into the main spec.
I’m looking for official strategies/best practices to ensure multiple changes that affect the same area converge into a single domain spec.

this is a real case that happen to me:

First change — user-show
I created a feature to display users and ran it through the full flow:
/opsx:new "user-show" → /opsx:ff → /opsx:apply → /opsx:archive

Second change — user-detail
The next day I created a feature that adds extra details on the same page introduced by user-show:
/opsx:new "user-detail" → /opsx:ff → /opsx:apply → /opsx:archive

What I see now
OpenSpec correctly recognized some overlap and integrated parts of the second change into the source-of-truth spec created by the first change.
However, I currently have two specs in the repository:
openspec/specs/user-show/spec.md
openspec/specs/user-detail/spec.md

My intention was to end up with a single spec (I would have named it user-mangament) because, functionally, these two features are tightly connected. I split the work only for practical reasons: deliver the first piece, test/integrate, then proceed with the next piece, when the tester in parallel was verifying the first one

Imagine doing it as a CRUD and delivering it in stages. I would end up with four specifications instead of one, especially if we have to implement and deliver each functionality one by one for any valid reason

Questions

1 - How can I force both changes to land in the same domain spec?
Is there a recommended way to ensure that subsequent changes affecting the same functional area always converge into one existing domain (so that I don’t end up with multiple domain folders for closely related features)?

2 - Should I have used a broader domain name from the start?
For example, should I have created a domain like "user-management" (and reused it) both times:
/opsx:new "user-mangament" ..... /opsx:archive (phase 1)
/opsx:new "user-mangament" ..... /opsx:archive (phase 2)
so that both user-show and user-detail changes archive into the same openspec/specs/user-management/spec.md?
NOTE: this one i tested and in same way it works, but i see two interesting points:

• when you archive the second change, if the days are the same there is a conflict because openSpec try to recreate the same folder in the archive repository with the same name (dd-mm-yyy is part of the name) --> OpenSpec propose you to rename or delete the old one
• during the second change OpenSpec update directly the spec of the source of true during the creation (/opsx:new) then continuing whit the flow it anyway recreated correctly also the spec in the change folder and there was any issue during the final merge

3 - Best practices
Are there recommended strategies or best practices to:
choose and reuse the right across multiple related changes, and
avoid fragmenting the source-of-truth into multiple specs when features are tightly coupled but delivered in stages?

Thanks in advance to share your experience and strategies.

[LeonKraim]

bump

[tangrufus]

My workaround: Tell your AI to consolidate the main spec.

👨: /opsx:archive "user-show"


🤖: # Questions
Delta specs were found for this change under openspec/changes/user-show/specs/. 
The main specs directory is missing a corresponding capability, 
so syncing will add new specs to openspec/specs/. How would you like to proceed?

Then you specific the main spec name:

👨: Sync now and name the main spec "user"


🤖: Archive Complete

Change: user-show
Schema: spec-driven
Archived to: openspec/changes/archive/2026-04-02-user-show/
Specs: ✓ Synced to main specs (created openspec/specs/user/spec.md)
All artifacts complete. All tasks complete.

Repeat for user-detail

---

It would be great if the /opsx:archive command can accept <capability> as an argument.

[alesky78]

thanks @tangrufus to share your workaround

In the end after several spec created I diceide to apprach this problem in this way that look like the more approrpiate for my lifecycle

The spec can be controlled during the proposal creation.
when the proposal.md is generated, we have the capability section that identify the spec that will be created or added

## Capabilities

### New Capabilities
- `wo-questions-config-detail`: Drill-down view that displays the `WorkOrderQuestionsConfig` rows (id, questionName, dispatcherName, isUpdate) for a selected `woConfigId`, rendered as a separate table below the flow configuration table via AJAX.

### Modified Capabilities
- `wo-flow-config-page`: The `woConfigId` column in the results table changes from plain display text to a clickable link, and the page gains a second result section (`#displayWoQuestionsConfig`) below the existing `#displayWoFlowConfig` section.

it is enoght at this stage to modify this part of the proposal before to proceed

well in case of the new fast workflow i don't think it works, you will have all in one shot
and then the spec folder/files are already generated

/opsx:propose ──► /opsx:apply ──► /opsx:archive

but in my case i use alwasy the extended workflow

/opsx:new ──► /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

and in this case this approach fit well