docs(stores): add multi-repo implementation flow

[alectimison-maker]

Summary

Add a concrete stores-beta walkthrough for a feature spanning one service repo and one frontend repo.

The guide now answers the two questions from #1257:

• Store-based planning sees store artifacts/configured context, not component source trees automatically; a workset can make local checkouts visible without creating routing or edit permissions.
• A store: pointer selects the same central root for every command and does not divide tasks by caller directory. Teams that need independent component apply/review cycles can keep shared requirements in the store while each repo retains a local OpenSpec root with a read-only references: entry.

The example follows that supported two-layer flow through central contract planning, local service/frontend changes, separate apply cycles, and independent review/archive.

Closes #1257.

Why this shape

The current root/action-context model scopes a workflow to its selected planning root, references expose store specs as read-only upstream context, and worksets only reopen folders together. Documenting those boundaries avoids implying repo-sliced apply behavior that OpenSpec does not currently implement.

Validation

• corepack pnpm run build — passed.
• Focused reference, pointer, workset, and capstone journey suites — 17/17 passed.
• Full suite — 3,472/3,474 passed. The two unrelated environment-sensitive failures were an initial telemetry notice in an exact stdout assertion and the locally installed Claude executable being launched instead of a deliberately broken test shim.
• git diff --check — passed.

Scope and risk

Documentation only. No CLI, schema, generated skill, or runtime behavior changes. Repo-sliced task routing remains explicitly deferred; the guide describes the currently supported pattern instead.

Summary by CodeRabbit

• Documentation
  • Added guidance for using shared planning stores across repositories and coordinating cross-repository contracts.
  • Documented worksets for opening store and component repositories together.
  • Clarified that stores do not automatically discover repositories or route tasks.
  • Explained component-local planning configuration using references rather than a store pointer.
  • Added examples for explicitly fetching shared specifications, tracking active changes, maintaining separate review and apply cycles, and linking related branches for review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8ebd7e33-e9fe-4415-8e00-7d8fa15b004b

📥 Commits

Reviewing files that changed from the base of the PR and between ae3051c and cb9b08c.

📒 Files selected for processing (1)

• docs/stores-beta/user-guide.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/stores-beta/user-guide.md

---

📝 Walkthrough

Walkthrough

The user guide adds a cross-repository workflow. It explains shared contract planning, store context boundaries, references configuration, explicit contract retrieval, and independent component implementation and review cycles.

Changes

Cross-repository store workflow

Layer / File(s)	Summary
Shared contract planning docs/stores-beta/user-guide.md	Adds a checkout-promotion example with a shared contract in team-plans and API/frontend boundary behavior.
Store context and worksets docs/stores-beta/user-guide.md	Explains store context boundaries and shows how a workset opens the planning store with both component repositories. It clarifies that a store pointer does not route tasks across repositories.
Independent component delivery docs/stores-beta/user-guide.md	Documents separate API and UI changes, explicit contract retrieval through references, independent review and archival, and branch linking for contract version tracking.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related issues

• Issue 1436 — The documentation clarifies references: usage and explains that stores do not discover or route consuming repositories.

Possibly related PRs

• Fission-AI/OpenSpec#1267 — Documents usage of the Stores beta feature introduced by this related change.

Suggested reviewers: clay-good

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the added multi-repository implementation flow in the stores documentation.
Linked Issues check	✅ Passed	The documentation addresses the cross-repository planning context, implementation flow, and per-repository scope requested in [#1257].
Out of Scope Changes check	✅ Passed	The changes are documentation-only and directly support the multi-component stores workflow requested in [#1257].
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In `@docs/stores-beta/user-guide.md`:
- Around line 218-221: Qualify the `store: team-plans` pointer description in
the user guide to state that it applies only when no higher-precedence explicit
`--store` option or nearest local `openspec/` root overrides it. Preserve the
existing clarification that OpenSpec does not split tasks by the directory where
`apply` was invoked or route tasks to repositories.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 880b9cab-aec9-4e83-8708-8ec8825b7d57

📥 Commits

Reviewing files that changed from the base of the PR and between 45cca5d and ae3051c.

📒 Files selected for processing (1)

• docs/stores-beta/user-guide.md

[alfred-openspec]

Please qualify the store: pointer paragraph before merge: an explicit --store and a nearer local planning root take precedence, so the pointer does not make every command target team-plans unconditionally. The rest of the two-layer flow matches current Stores behavior, and the focused pointer/reference/workset tests pass.

[alectimison-maker]

Thanks for the review. Addressed in cb9b08c: the paragraph now makes the store: pointer conditional on there being no explicit --store or nearer local openspec/ root, while retaining the clarification that OpenSpec does not route tasks to repositories. CodeRabbit's follow-up found no actionable comments. The CI and Security workflows are currently awaiting maintainer approval (�ction_required), with no executed check failure reported.

[alfred-openspec]

The pointer-precedence qualification now matches the actual root-selection behavior while preserving the important no-routing clarification. The rest of the two-repo flow remains coherent; approved at cb9b08c.