openspec/work/simplify-context-and-workspace-model/slices/store-root-selection/spec.md
Normal OpenSpec commands can act on a registered standalone OpenSpec root selected by name:
openspec new change add-billing --store team-context
Selecting a store resolves to an ordinary OpenSpec root. Everything downstream
behaves exactly as if the command had been run from inside that root: the same
openspec/specs/, openspec/changes/, and openspec/changes/archive/ files,
the same schema, the same lifecycle.
This slice also retires initiative-link creation from normal change flows
(Phase 2.1 pulled forward), so --store has exactly one meaning: which
OpenSpec root should this command use.
--store means root selection, and only that. The old initiative
meaning of --store / --store-path on new change and set change is
removed in this slice. New changes do not create initiative links.
Initiative linking was set change's only behavior, so openspec set change is removed rather than kept as a deprecated stub or empty shell.--store <id> (registry lookup) is the only selector. --store-path
is deferred. Registering a clone is the answer for path access; the path
form can be added later if someone actually hits the wall.A human stays in the project repo they are working on and tells their agent where the work lives. The agent discovers registered stores and selects one by name:
openspec context-store list --json
openspec new change add-billing --store team-context
openspec status --change add-billing --store team-context
openspec instructions proposal --change add-billing --store team-context
openspec archive add-billing --store team-context
When a store is selected, every supported command emits a human-visible verification signal so the human can verify the work landed in the right repo without watching the CLI run. In human mode, this signal is written to stderr so commands whose stdout is raw Markdown or agent-consumed instructions keep their normal stdout payload:
Using OpenSpec root: team-context (/Users/alice/src/team-context)
Without --store, commands keep using the nearest OpenSpec root when one
exists, including when the user is working inside the standalone repo itself.
The flag is never required; it is how you reach a root you are not standing in.
This slice intentionally changes only two legacy no-flag cases: leftover
workspace view state no longer wins root resolution, and a no-root directory
with registered stores errors with a store-selection hint instead of silently
scaffolding a new local root.
In scope:
--store <id> on new change, status, instructions, list, show,
validate, and archive, with identical semantics on each.cwd + openspec/changes path joins.--json on archive (it has none today), so the shared root block is
uniform across the command set.list --specs --json support so specs listing also participates in
the shared root reporting contract.--store-path rejection that points to
context-store register; a generic unknown-option error is not enough.context-store doctor.--store / --store-path) from new change.openspec set change from the CLI, help, completions metadata,
workflow exports if unused, and command tests/docs references. No deprecation
stub is kept because initiative linking was its only behavior.new change options: --goal remains ordinary
optional change metadata and never affects root selection, while --areas is
rejected because affected workspace links only made sense for workspace-scoped
planning.context-store setup and register that shows
--store usage (depends on slice 1.1, store-root-parity, being merged).--store consistently.Out of scope:
--store-path or any path-addressed selection (deferred).--store (tracked
separately; do not forget it).openspec change show, openspec spec show, and similar): they keep their current cwd-based behavior and do not
gain --store.context-store terminology renaming (L7).--store <id> resolves the id through the local registry to the store's
OpenSpec root and runs the command against that root.
team-context with a healthy OpenSpec
rootopenspec/
rootopenspec new change add-billing --store team-contextopenspec/changes/add-billing/ inside the
team-context store rootteam-context store contains the change add-billinglist, show, status, validate, and archive
with --store team-contextopenspec/changes/ and
openspec/specs/archive moves the change into the store's
openspec/changes/archive/openspec/ root--store team-contextteam-context store rootteam-context is the only registered store--store team-contxt--store for that idcontext-store doctor.openspec-store/store.yaml id does not
match its registry id--store for that idcontext-store doctor--store-path to a supported commandcontext-store register plus --store <id>Without --store, commands resolve the nearest OpenSpec root exactly as a
user standing in that directory would expect.
openspec/ root--storeopenspec/ root, unchanged from today--storeopenspec/ rootnew change treats the
current directory as an implicit root, while list and archive fail and
point to openspec init)openspec/ root--store--store <id> or openspec initLeftover workspace view state does not decide where these commands act.
.openspec-workspace-view.yaml stateopenspec/ root--storeopenspec/ root--store team-contextteam-context store rootopenspec/ root--storeopenspec new change add-billing --areas api--areasopenspec new change add-billing --goal "Improve billing"--goal--goal may write the existing change goal metadataPhase 2.1, pulled forward: normal change creation stops attaching work to initiatives.
new change completes, with or without --store--initiative to new change--store is documented as root selection onlyopenspec set change or openspec set change --helpThe human's verification signal is the output, not the command line.
--store in human modeshow and agent-consumed text from instructions are not prefixed or
injected with the root banner--store, human output is unchanged from today--json{
"root": {
"path": "/abs/path",
"source": "store",
"store_id": "team-context"
}
}
source is one of store, nearest, or implicitstore_id is present only when a store was selectedimplicit is used only for preserved no-store behavior where a
command is allowed to treat the current directory as an implicit OpenSpec rootlist --specs --json emits JSON rather than human text so it can
include the shared root blockarchive --json--storenew change, status, instructions,
list, show, validate, archive) receives --storevalidate --all, item pickers, and
similar) discover and operate on items within the resolved rootcontext-store setup or context-store register succeeds--store <id>