openspec/work/simplify-context-and-workspace-model/slices/store-rename-and-guidance/spec.md
The product noun for a registered standalone OpenSpec repo is store, everywhere: the command group, the machine tokens, the help text, the completions metadata, the generated workflow skills, the checked-in agent guidance, and the docs. The same pass makes stores discoverable to agents — a fresh agent session in a project repo with a registered store completes a store-scoped change from a single prompt, without the human spelling out flags — and stops the same guidance surfaces from advertising initiatives and workspaces as normal workflow.
This is one regeneration pass, not two: teaching guidance that stores exist and removing initiative/workspace advertising touch the same files, so they land together. The rename lands first, before any guidance prose is written, so no guidance bakes in a name that is about to change.
context-store → store. Subcommand names
(setup, register, unregister, remove, list/ls, doctor) are
unchanged. The --store flag stays. The rejected runner-up
(using the repo noun) is not revisited.context_store-bearing
diagnostic codes and JSON keys → store forms, and the machine-local
data directory context-stores/ → stores/..openspec-store/ metadata
directory name, the store.yaml file name and shape, and the registry
file shape are unchanged. A store created before this slice is still a
valid store after it.--store: workspace open --store <id> and workspace open --store-path <path> (initiative
selectors) are removed from registration and from the completions
metadata this slice regenerates.store group for the
inevitable openspec store new change <id> mistake, pointing at
openspec new change <id> --store <id>.schemas/workspace-planning/templates/ (Phase 5 decides its fate), and
any command behavior changes beyond the rename and the two riders.The reviews of the first draft converged on one principle, adopted here:
The token rename is total and mechanical. The prose rewrite is surgical.
target values,
completions, generated guidance, checked-in guidance, docs — emits or
contains the tokens context-store, context_store, contextStore,
or the phrase "context store". This includes the initiative and
workspace groups: their machine tokens, flag descriptions, hint
strings, and JSON keys rename mechanically even though both groups are
deleted in the next slice, because a hint a user pastes must work
verbatim and an acceptance grep must not need a carve-out list.
Whitelist (the only survivors): the committed format literals
(.openspec-store/ directory name, store.yaml filename) and the
openspec/ planning-history tree (work/, changes/,
initiatives/, explorations/), which sits outside the sweep roots
entirely.initiative and workspace
groups the rename substitutes tokens and nothing else: no restructuring,
no new prose, because that code dies in the next slice.context-store
command group disappears entirely — no hidden alias — and the old
context-stores/ data directory is neither read nor migrated. The
feature has zero users (everything since slice 1.1 is unmerged), and
Phase 5's criteria are already locked as delete-don't-hide.src/core/context-store/ →
src/core/store/, src/commands/context-store.ts →
src/commands/store.ts, ContextStore* symbols → Store*, and test
and helper files follow (test/commands/context-store*.test.ts,
test/core/context-store/, test/helpers/context-store-git.ts). One
concept, one token applies to the codebase, not just user-facing
strings; the rename is compiler-checked and free while there are no
users.initiative and
workspace groups are deleted in the next slice (the Phase 5
command-group deletion), so this slice renames their tokens (per the
rename rule above) and their group one-liners, and changes how
completions present them — but does not restructure their prose,
behavior, or tests beyond what the rename forces. Their --store
selectors (for example initiative create --store, a store-id
selector, and initiative's live --store-path) keep their behavior
under reworded descriptions and die with the groups next slice; the
spec names this as an accepted, expiring inconsistency rather than
pretending --store has exactly one meaning while the legacy groups
still breathe.actionContext.mode: "workspace-planning", still reachable until 4.1 rebuilds opening) and
they refuse workspace flows rather than advertise them. Ground truth
correction to the roadmap's surface inventory: five templates carry
the guard (apply-change, archive-change, bulk-archive-change,
sync-specs, verify-change), twice each (two profile variants); zero
templates reference initiatives. Three further mentions sit outside
guards — continue-change.ts:72,192 and onboard.ts:281 ("workspace
planning context") — and are reworded to schema-instruction language.context-store commands, so every doc
that instructs running them is updated mechanically: docs/cli.md
(store section renamed and reworded to the locked vocabulary; the
workspace open --store/--store-path rows deleted per rider 1; the
stale default-XDG-path line corrected — 1.3 already made --path
required; initiative rows token-renamed and legacy-labeled),
docs/concepts.md (token renames), and the docs/workspaces-beta/
files (agent-cli-playbook.md, user-guide.md), which get token
renames plus correctness fixes where a documented invocation already
fails against the current CLI (setup examples missing the --path
that 1.3 made required; pre-1.3 prompt-flow prose). Deleting the beta
docs outright belongs to the Phase 5 remainder; the public
concept-docs rewrite (L1) stays deferred..codex/skills/use-openspec/references/shared-context-beta.md
advertises initiative/workspace flows that the next slice deletes; per
the locked 5.1 sequencing ("guidance surfaces die in slice 1.4"), the
reference file is deleted, SKILL.md is rewritten around store
discovery instead of routing to it, and
references/artifact-placement.md loses its beta context-store flow
section and workspace-inspection routing (placement guidance itself
stays). Ground truth discovered during implementation: .codex/ is
git-ignored (.gitignore:158) — this guidance is the L8
ignored-local-skill, not checked-in source, so its rewrite lands on
disk for local agents but cannot appear in a commit; L8 still owns
its final disposition.getDefaultContextStoreRoot (foundation.ts:67) lost its last
production caller when 1.3 made --path required; the rename pass
deletes it (and its tests) per the locked delete-don't-hide criteria
rather than carrying a dead export under a new name.src/core/context-store/operations.ts (~1077 lines) and
src/commands/context-store.ts (~751 lines), both over the ~600-line
bar. No split in this slice: the changes are mechanical token
substitution, and the upcoming Phase 5 deletions and 4.1 rebuild will
shrink or restructure these modules; splitting mid-rename would create
review noise for structure that is about to change again.openspec store setup team-context --path ~/src/team-context
openspec store list
openspec store doctor
Top-level help describes the group as the standalone OpenSpec repo feature, in the locked vocabulary:
store Create and manage stores - standalone OpenSpec repos you register on this machine
The --store flag on lifecycle commands reads "Store id to use as the
OpenSpec root (a store is a standalone OpenSpec repo you've registered)".
Nothing in help, errors, JSON, completions, or docs says "context store"
anymore.
A human in an app repo says: "create a change for the billing rework in
our team store." The agent's generated workflow skill tells it how stores
work: discover with openspec store list --json, then carry
--store <id> on every lifecycle command. The agent runs:
openspec store list --json # finds id: team-context
openspec new change billing-rework --store team-context
and every hint the CLI prints keeps --store team-context in the loop, so
the agent never falls back to the wrong root. No initiative or workspace
command appears anywhere in the skill's instructions.
$ openspec store new change billing-rework
Error: unknown command 'new' for 'openspec store'.
Store subcommands manage store registration: setup, register, unregister,
remove, list (ls), doctor.
To create or work on a change in a store, use the normal command with
--store, for example:
openspec new change billing-rework --store <id>
workspace open --store and --store-path no longer exist. The
workspace and initiative group one-liners say they are legacy beta
surfaces, completions metadata stops presenting their flows as normal
steps, and the hints they still print name commands that actually exist.
(Both groups are deleted outright in the next slice; this slice only
stops the advertising and keeps every printed hint pasteable.)
In scope:
context-store → store in command registration
(src/commands/context-store.ts:691-751, src/cli/index.ts:22,349),
with subcommand names, arguments, and behavior unchanged. Telemetry
command paths follow mechanically (store:setup etc. via the generic
command-path tracker at src/cli/index.ts:100-101).context_store (the 37 context_store_*-prefixed
codes plus invalid_context_store_id, invalid_context_store_metadata,
invalid_context_store_path, invalid_context_store_registry,
no_context_store_registry, context_stores_unreadable,
context_stores_partially_unreadable, and
workspace_context_store_unavailable — 45 total today, pinned by
sweep, not by this count); every dotted diagnostic target value in
the context_store.* family (foundation, operations, git, registry,
root-selection, openspec-root); every JSON output key
(context_store/context_stores → store/stores), including the
initiative command output shapes (src/commands/initiative.ts:50-71)
and workspace-open JSON (src/commands/workspace/open-view.ts:61); the
XDG data dir context-stores/ → stores/
(foundation.ts:14,59-65), registry filename registry.yaml
unchanged.context-store command renames so it stays pasteable, including
initiative resolution (src/core/collections/initiatives/resolution.ts:551,565,625,
and its --store/--store-path advertising at :192,234, which
renames to name surviving selectors only), workspace surfaces
(src/commands/workspace/context-status.ts:48, open-view.ts:211,
open-target-selection.ts:142), and stray core strings
(src/core/change-metadata/schema.ts:14,
src/core/collections/runtime.ts:282,
src/core/workspace/open-surface.ts:21,120-138 — token substitution
only on the legacy generated workspace guidance).getDefaultContextStoreRoot export (decision 7)..openspec-store/ directory
name, store.yaml filename and shape, registry shape.--store/--store-path from workspace open
(src/commands/workspace/registration.ts:138-139, completions
command-registry.ts:383-392). workspace open --initiative <id> keeps
resolving through the existing cross-store search, the qualified
<store>/<initiative> form, and the interactive picker
(open-target-selection.ts:195-240).store group naming
the real subcommands (including the ls alias) and pointing
lifecycle-shaped mistakes at openspec <command> --store <id>. The
hint prints on stderr in both human and JSON invocations, consistent
with existing Commander unknown-command behavior; no new JSON envelope.store group and subcommand one-liners,
STORE_OPTION_DESCRIPTION (src/cli/index.ts:41), the hidden
--store-path rejection message (src/cli/index.ts:47-53), and the
workspace and initiative group one-liners (legacy-beta labeling).shared-flags.ts:29-33 store-flag
description; command-registry.ts store group entries renamed and
reworded; initiative/workspace entries token-renamed and labeled
legacy; the workspace open store selectors removed.src/core/templates/workflows/, 12
templates): add store teaching — when the user names a store or the
work lives in a registered store, discover ids with
openspec store list --json and carry --store <id> on every
openspec command the skill issues; note that printed hints carry the
flag. Workspace guards stay in the five templates that carry them; the
three out-of-guard workspace-planning prose mentions
(continue-change.ts:72,192, onboard.ts:281) reword to
schema-instruction language; no initiative or workspace flow is
presented as a normal step..codex/skills/use-openspec/SKILL.md
rewritten around store discovery (openspec store list --json as the
inspection command; --store as root selection);
references/shared-context-beta.md deleted;
references/artifact-placement.md updated per decision 6.docs/cli.md,
docs/concepts.md, and docs/workspaces-beta/agent-cli-playbook.md,
user-guide.md.openspec init in the scratch repo), with isolated XDG state and a
registered store, completes a store-scoped change from a single plain
prompt that names the team store but no ids or flags.Out of scope:
workspace and initiative command groups (the next
slice in the queue) or restructuring their internals beyond token
substitution and one-liners.schemas/workspace-planning/templates/ content, the
workspace-planning schema name, and the actionContext.mode: "workspace-planning" contract value (alive until 4.1).context-stores/ data directory..openspec-store/store.yaml or registry content shapes.view/opening
(Phase 4).docs/workspaces-beta/ (Phase 5 remainder) and the public
concept-docs rewrite (L1) beyond the accuracy pass above.openspec store setup|register|unregister|remove|list|ls|doctorcontext-store counterpart did
before this sliceopenspec context-store <anything> fails as an unknown command
with no alias or redirectopenspec --help lists store with a one-liner using the
locked definition and lists no context-store groupinitiative and workspace groupsstore forms (for example
store_not_found, invalid_store_id, no_store_registry,
workspace_store_unavailable), dotted target values use the
store.* family, and payload keys are store/storescontext_storecontext-store, context_store,
contextStore, and the phrase "context store" (case-insensitive)
across src/, test/, docs/, .codex/, scripts, and completions.openspec-store/, store.yaml where it names that file), the
openspec/work/ planning-history folder, and archived/changelog
history<data-dir>/stores/registry.yaml.openspec-store/store.yaml with
the same schema as before this slicecontext-stores/ directory.openspec-store and store.yaml as
on-disk literals, so a future rename pass cannot silently break cloned
storesstore: form (for example
store:setup), with no other telemetry changesopenspec workspace open --store x or
--store-path /tmp/xworkspace open --help and completions metadata list neither
optionworkspace open --initiative <id> still resolves initiatives
through registered stores, including the qualified
<store>/<initiative> form and the interactive picker--store appears in the help or completions of any command
outside the legacy initiative groupinitiative group's --store/--store-path
selectors keep their behavior under store-vocabulary descriptions
(an accepted inconsistency that the next slice deletes with the group)openspec store new change add-x (or another
unknown store subcommand)ls alias--store, for example
openspec new change add-x --store <id><id> placeholder--json
invocationsinitiative and workspace groups still exist this
sliceopenspec command (for example initiative resolution's
registry-missing fix, workspace context status, workspace open
failures)openspec
commandsopenspec store list --json and carrying --store <id> on every
command when the work selects a storeinitiative or presents workspace
flows as normal steps.codex/skills/use-openspec/openspec store list --jsoninitiative list and workspace list no longer appear as
inspection or workflow steps anywhere in the directoryopenspec --help or completions metadataworkspace and initiative one-liners identify them as
legacy beta surfacesdocs/cli.md or docs/workspaces-beta/docs/cli.md store section uses the store group name and
the locked vocabulary, and no longer documents the removed
workspace open store selectors or the pre-1.3 default-XDG-path setup
behavioropenspec init (so the
generated workflow skills are present), isolated XDG state, and a
registered store--store