experiment(stores): upstream work end to end — one door, workflows as data, serves links, live rollups

[clay-good]

One door

Type one thing, then just talk:

/opsx:store

That's the whole user experience this PR builds toward. The skill (generated by plain openspec init, part of the core profile) reads your machine's actual state, figures out the one thing that makes sense right now — set up, draft, link, check status, or archive — runs the commands itself, and ends every reply with a few numbered next moves, one recommended. You never learn the commands unless you want to. And because the skill carries zero logic of its own — everything underneath is a deterministic CLI call — the agent can't drift, and everything it does, you or CI can run directly.

Here's what it's driving.

What the door does for you

Teams decide what to build before code exists. This PR gives that work a home and a loop: a shared store (a git repo of decisions — what's agreed lives in specs/, what's being decided lives in changes/), and one thread connecting every code change to the decision it implements.

        store  (the team's shared upstream repo)
        ┌─────────────────────────────────┐
        │  changes/   what's being decided │ ◄─ serves: ─  a change in repo A
        │  specs/     what's been agreed   │ ◄─ serves: ─  a change in repo B
        └─────────────────────────────────┘
          status rolls up live · archiving a change turns it into specs

Every output below is from a real run.

1. Set up once — it's ready immediately. A fresh store comes with a working requirements workflow and teaches its own loop:

$ openspec store setup product-team
Store ready: product-team

Next:
  openspec new change <name> --store product-team     # draft requirements here
  openspec new change <name> --serves product-team/<change>   # in any repo: link work to them
  openspec list --downstream --store product-team     # where everything stands

2. Draft with gates. Requirements are an ordinary change — each stage guided, reviewed, and unlocked in order:

$ openspec status --change onboarding-revamp --store product-team
[x] proposal
[ ] specs

3. Link work with one flag. The link wires everything — the repo sees the store's context, agents get the upstream requirements in their instructions automatically (with a standing rule: if implementation shows a requirement is wrong, flag it upstream instead of silently diverging), and status knows where to look:

$ openspec new change add-welcome-tour --serves product-team/onboarding-revamp
Serves: product-team/onboarding-revamp
Referenced store 'product-team' in openspec/config.yaml — agents here now see its context.

4. Status computes itself. Progress comes from the work — task checkboxes and artifacts actually present, never a report someone wrote. A ✓ means genuinely done:

$ openspec list --downstream --store product-team

onboarding-revamp   2/2 serving changes complete
  ✓ add-invite-endpoint  api             2/2 tasks
  ✓ add-welcome-tour     web-app         2/2 tasks
  all serving changes complete — archive it to sync its specs

(--scan <dir> gives a stateless CI machine the same rollup from a folder of clones.)

5. Close the loop. Archive the decision and it becomes standing truth — a spec every future change traces against, with every existing link still resolving:

onboarding-revamp   (archived — its requirements now live in specs/)

The store, as an SDK

Everything a team can define about its store is plain files in git — one config and one folder per workflow. Declare it, and the CLI makes it real, enforces it, and teaches it to every agent in every repo that references the store:

your-store/
└── openspec/
    ├── config.yaml                  ← the store's definition, one file
    │     schema: product-flow          which workflow new decisions use
    │     structure:                     any folders/files — setup creates them,
    │       research/: raw inputs        doctor checks them, agents see them
    │       decisions/adr-template.md: the shape of a decision record
    │     context: |                     background every agent receives
    │       We ship weekly. Compliance reviews all customer-facing copy.
    │
    ├── schemas/product-flow/        ← the workflow, as editable files
    │     schema.yaml                   the stages, in your order
    │     instructions/<stage>.md       what agents are told, per stage
    │     templates/<stage>.md          the shape of each stage's output
    │
    ├── changes/                     ← decisions in motion (the loop above)
    └── specs/                       ← decisions that stuck (written by archive)

Nothing else exists — no server, no hidden state, no registration beyond your machine's store list. openspec schema init <name> --artifacts <your,stage,names> --store <id> scaffolds the workflow folder so nobody starts from blank YAML; repos that reference the store inherit its workflows automatically; and versioning is git — pull the store, and every repo follows.

Proven, not just demoed

• The full loop ran on a real four-repo product with pre-existing state — drafting, linking from two repos, the nudge, a real archive into standing specs.
• A cold-start session (an agent given only --help and the guides) completed every step on the first attempt.
• A hand-built three-stage workflow with names the tool had never seen ran through every gate and archived cleanly.
• The CI rollup ran for real: bare git remotes, a zero-state machine, four commands to a team-wide view.
• The layout loop ran end to end: declare → doctor flags drift → setup materializes → doctor clean.

The rounds surfaced real defects — old metadata failing to load, tasks-done counting as done with no approved proposal, the scaffolder rejecting custom stage names — every one fixed here with a regression test.

Choices made, each reversible in one line

Choice	Default	To change it
the entry point	/opsx:store, generated in the core profile	every command underneath works directly
what a fresh store's changes are	the built-in requirements workflow	schema: in the store's config
how a team defines a workflow	a folder — yaml + instructions + templates	inline instruction: still works
a store's layout	structure: map, materialized by setup, checked by doctor	edit the map
how status is gathered	discovered from serves: lines — no manifest	remove the line

🤖 Generated with Claude Code

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds initiatives documentation and example materials, introduces store-aware initiative discovery proposals, and wires list --initiatives plus schemas --store through the CLI, core logic, docs, and tests.

Changes

Initiatives documentation and examples

Layer / File(s)	Summary
Initiatives guides and overview docs/README.md, docs/stores-beta/initiatives.md, openspec/initiatives/smoother-setup/brief.md, openspec/initiatives/smoother-setup/personas/*	Adds the initiatives link, the store-hosted initiatives guide, and the smoother-setup brief and persona documents.
Example schema and templates openspec/initiatives/smoother-setup/example-schema/schema.yaml, .../templates/*, .../decisions/*	Adds the smoother-setup schema, matching templates, and decision documents.
Store-aware proposal set openspec/changes/initiatives-in-stores/design.md, proposal.md, specs/store-aware-artifacts/spec.md, tasks.md	Adds the design, proposal, specification, and task documents for store-aware initiative discovery and rollup behavior.

Store-aware CLI and initiative listing

Layer / File(s)	Summary
Initiative listing core src/core/initiatives.ts, test/core/initiatives.test.ts, docs/agent-contract.md	Adds the initiative listing module, including manifest reading, referenced-store shadow lookup, and rolled-up progress counts.
CLI list and schemas wiring src/cli/index.ts, src/commands/workflow/schemas.ts, src/core/completions/command-registry.ts, src/core/templates/workflows/store-selection.ts	Wires list --initiatives and store-scoped schemas into the CLI and command registry.
Schemas contract docs docs/agent-contract.md, docs/stores-beta/user-guide.md	Updates the agent contract and store-selection guidance to describe schemas --store and the related JSON shape changes.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1190: Overlaps with src/cli/index.ts list-command plumbing and root-selection behavior, which this PR extends with --initiatives and store-scoped schemas.

Suggested reviewers: alfred-openspec, TabishB

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is related to the PR’s store-aware initiative/schema work and live rollups, though it is wordy and uses jargon.

✨ 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]

🧹 Nitpick comments (5)

docs/stores-beta/initiatives.md (2)

25-31: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add language specifiers to fenced code blocks for syntax highlighting and accessibility.

Twenty code blocks lack language identifiers, triggering MD040 warnings. This hurts readability (no syntax highlighting) and accessibility (screen readers can't announce the code type).

Add these specifiers:

• File trees → text
• Shell commands → bash
• YAML config → yaml
• Command output → text

📝 Suggested fixes (excerpt)

- ```
+ ```text
  openspec/
    initiatives/
      smoother-setup/
        README.md      the shared plan: what this is and why these changes go together
        inventory.md   the list of changes, and where each one stands

```diff
- ```
+ ```bash
  openspec list --changes

```diff
- ```
+ ```yaml
  references:
    - team-plans

```diff
- ```
+ ```bash
  openspec validate example-first-run --type change --strict

</details>





Also applies to: 43-55, 59-61, 72-78, 99-101, 103-107, 111-114, 118-129, 134-141, 145-147, 169-184, 189-191, 194-200, 206-208, 210-220, 222-224, 226-228

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/stores-beta/initiatives.md around lines 25 - 31, Add language
identifiers to all fenced code blocks in the initiatives docs so Markdown lint
MD040 stops flagging them. Update the existing fences in the relevant sections
of docs/stores-beta/initiatives.md to use the right specifier based on content:
file trees with text, shell commands with bash, YAML snippets with yaml, and
command output with text. Make sure the repeated examples in the affected
sections are updated consistently so the markdown stays readable and accessible.

</details>

<!-- cr-comment:v1:fefae1bd15fd32332c3150a2 -->

---

`243-243`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _💤 Low value_

**Strong accuracy claim requires verification.**

The statement "Every command and its output above came from a normal OpenSpec install" is a strong claim. If any output was manually edited for clarity or reconstructed from memory, this could become inaccurate as the CLI evolves. Consider softening to "Command output shown is representative of a normal OpenSpec install" or adding a version note, unless you have high confidence every snippet was captured verbatim from a real run.

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/stores-beta/initiatives.md at line 243, The wording in the OpenSpec
install note is making an overly strong provenance claim; update the affected
text in the initiatives documentation to either soften it to representative
output or qualify it with a specific version/capture note. Use the surrounding
install narrative in the same section to locate the sentence, and ensure the
revised phrasing avoids asserting that every command and output was captured
verbatim unless that can be verified.

</details>

<!-- cr-comment:v1:d943cc4f4728404a2355a2f1 -->

</blockquote></details>
<details>
<summary>openspec/initiatives/smoother-setup/decisions/0002-tool-native-paths.md (1)</summary><blockquote>

`1-3`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _💤 Low value_

**Minor format inconsistency with ADR 0001.**

ADR 0001 includes an introductory quote block explaining what an ADR is; ADR 0002 omits it. For consistency across the initiative's decision records, consider adding the same intro to 0002, or removing it from 0001 if you prefer brevity.

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @openspec/initiatives/smoother-setup/decisions/0002-tool-native-paths.md
around lines 1 - 3, ADR 0002 is missing the same introductory quote block used
in ADR 0001, creating a format inconsistency between decision records. Update
the ADR 0002 document to either add the shared intro near the top or remove the
intro from ADR 0001 for consistency; use the ADR headings and title in 0002 to
place the change cleanly.

</details>

<!-- cr-comment:v1:e80d3fe6e806ee5a304cd9b2 -->

</blockquote></details>
<details>
<summary>openspec/initiatives/smoother-setup/inventory.md (1)</summary><blockquote>

`13-23`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _⚡ Quick win_

**Add language specifiers to fenced code blocks.**

The two command examples lack language tags, which hurts syntax highlighting and accessibility.

```diff
 See live status any time:
 
-```
+```shell
 openspec list --changes

Open any change to see its full plan:

- +shell
openspec show simplify-skill-installation

🤖 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 `@openspec/initiatives/smoother-setup/inventory.md` around lines 13 - 23, Add
the missing language specifiers to the fenced examples in inventory.md so the
command snippets render correctly. Update the two markdown code fences around
the openspec list and openspec show examples to use a shell language tag,
keeping the content unchanged. Use the existing fenced examples in the setup
instructions section as the target location.

openspec/initiatives/smoother-setup/example-schema/finished-example/.openspec.yaml (1)

1-2: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding version field to match schema declaration.

The schema.yaml declares version: 1, but the metadata file only includes schema: initiative without a corresponding version. If the metadata validation expects a version field or if future schema versions are anticipated, include it here for consistency.

 schema: initiative
+version: 1
 created: 2026-06-30

🤖 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
`@openspec/initiatives/smoother-setup/example-schema/finished-example/.openspec.yaml`
around lines 1 - 2, Add the missing version metadata to the initiative
definition so it matches the schema declaration. Update the .openspec YAML for
the example initiative by including a version field alongside schema:
initiative, keeping the metadata consistent with the versioned schema used
elsewhere. Use the existing initiative metadata structure in the .openspec file
as the place to add it.

🤖 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.

Nitpick comments:
In `@docs/stores-beta/initiatives.md`:
- Around line 25-31: Add language identifiers to all fenced code blocks in the
initiatives docs so Markdown lint MD040 stops flagging them. Update the existing
fences in the relevant sections of docs/stores-beta/initiatives.md to use the
right specifier based on content: file trees with text, shell commands with
bash, YAML snippets with yaml, and command output with text. Make sure the
repeated examples in the affected sections are updated consistently so the
markdown stays readable and accessible.
- Line 243: The wording in the OpenSpec install note is making an overly strong
provenance claim; update the affected text in the initiatives documentation to
either soften it to representative output or qualify it with a specific
version/capture note. Use the surrounding install narrative in the same section
to locate the sentence, and ensure the revised phrasing avoids asserting that
every command and output was captured verbatim unless that can be verified.

In `@openspec/initiatives/smoother-setup/decisions/0002-tool-native-paths.md`:
- Around line 1-3: ADR 0002 is missing the same introductory quote block used in
ADR 0001, creating a format inconsistency between decision records. Update the
ADR 0002 document to either add the shared intro near the top or remove the
intro from ADR 0001 for consistency; use the ADR headings and title in 0002 to
place the change cleanly.

In
`@openspec/initiatives/smoother-setup/example-schema/finished-example/.openspec.yaml`:
- Around line 1-2: Add the missing version metadata to the initiative definition
so it matches the schema declaration. Update the .openspec YAML for the example
initiative by including a version field alongside schema: initiative, keeping
the metadata consistent with the versioned schema used elsewhere. Use the
existing initiative metadata structure in the .openspec file as the place to add
it.

In `@openspec/initiatives/smoother-setup/inventory.md`:
- Around line 13-23: Add the missing language specifiers to the fenced examples
in inventory.md so the command snippets render correctly. Update the two
markdown code fences around the openspec list and openspec show examples to use
a shell language tag, keeping the content unchanged. Use the existing fenced
examples in the setup instructions section as the target location.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 93189cf8-0118-48b8-a5b4-2db11986357e

📥 Commits

Reviewing files that changed from the base of the PR and between 546224e and 8825ed2.

📒 Files selected for processing (21)

• docs/README.md
• docs/stores-beta/initiatives.md
• openspec/initiatives/smoother-setup/README.md
• openspec/initiatives/smoother-setup/decisions/0001-aliases-over-rename.md
• openspec/initiatives/smoother-setup/decisions/0002-tool-native-paths.md
• openspec/initiatives/smoother-setup/example-schema/finished-example/.openspec.yaml
• openspec/initiatives/smoother-setup/example-schema/finished-example/adr.md
• openspec/initiatives/smoother-setup/example-schema/finished-example/one-pager.md
• openspec/initiatives/smoother-setup/example-schema/finished-example/persona.md
• openspec/initiatives/smoother-setup/example-schema/finished-example/specs/first-run-skills/spec.md
• openspec/initiatives/smoother-setup/example-schema/finished-example/tasks.md
• openspec/initiatives/smoother-setup/example-schema/schema.yaml
• openspec/initiatives/smoother-setup/example-schema/templates/adr.md
• openspec/initiatives/smoother-setup/example-schema/templates/one-pager.md
• openspec/initiatives/smoother-setup/example-schema/templates/persona.md
• openspec/initiatives/smoother-setup/example-schema/templates/spec.md
• openspec/initiatives/smoother-setup/example-schema/templates/tasks.md
• openspec/initiatives/smoother-setup/inventory.md
• openspec/initiatives/smoother-setup/personas/coding-agent.md
• openspec/initiatives/smoother-setup/personas/new-user.md
• openspec/initiatives/smoother-setup/personas/team-lead.md

[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 `@openspec/changes/initiatives-in-stores/specs/store-aware-artifacts/spec.md`:
- Around line 3-22: Clarify the `--store` discovery behavior in the store-aware
schema discovery requirement by explicitly stating whether `openspec schemas
--store acme-plans` should merge store schemas with the current repo’s own
schemas or show only the selected store’s schemas. Update the requirement text
and the “Listing a store’s schemas” scenario so the contract is unambiguous, and
align the “Referenced store schemas are visible from a repo” scenario with the
same discovery rules using the store-aware schema discovery language.

🪄 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

Run ID: ef8289f3-2a22-46c2-a341-18f2e8ae8c33

📥 Commits

Reviewing files that changed from the base of the PR and between 4aa2ebe and 9288424.

📒 Files selected for processing (10)

• docs/README.md
• docs/stores-beta/initiatives.md
• openspec/changes/initiatives-in-stores/design.md
• openspec/changes/initiatives-in-stores/proposal.md
• openspec/changes/initiatives-in-stores/specs/store-aware-artifacts/spec.md
• openspec/changes/initiatives-in-stores/tasks.md
• openspec/initiatives/smoother-setup/brief.md
• openspec/initiatives/smoother-setup/example-schema/schema.yaml
• openspec/initiatives/smoother-setup/example-schema/templates/brief.md
• openspec/initiatives/smoother-setup/example-schema/templates/decision.md

✅ Files skipped from review due to trivial changes (7)

• openspec/initiatives/smoother-setup/example-schema/templates/brief.md
• openspec/initiatives/smoother-setup/brief.md
• openspec/changes/initiatives-in-stores/proposal.md
• openspec/changes/initiatives-in-stores/tasks.md
• openspec/initiatives/smoother-setup/example-schema/templates/decision.md
• docs/README.md
• docs/stores-beta/initiatives.md

[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 `@src/core/initiatives.ts`:
- Around line 59-75: The readManifest function currently only type-asserts
parseYaml output and silently falls back to {}, so invalid initiative.yaml
shapes (especially changes not being an array) can corrupt listInitiatives
counts without any warning. Add structural validation inside readManifest for
the parsed InitiativeManifest fields, especially changes, and treat invalid
shapes as a parse failure instead of returning a misleading object. Also emit a
warning or diagnostic on parse/validation failure, consistent with
readProjectConfig behavior, so callers can detect bad manifests before
listInitiatives iterates over changeId values.

🪄 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

Run ID: 4ce4cc06-f780-4f1b-a61c-d5f8c9950f3f

📥 Commits

Reviewing files that changed from the base of the PR and between 2e1ce30 and 7324d11.

📒 Files selected for processing (12)

• docs/agent-contract.md
• docs/stores-beta/initiatives.md
• docs/stores-beta/user-guide.md
• openspec/changes/initiatives-in-stores/tasks.md
• openspec/initiatives/smoother-setup/initiative.yaml
• src/cli/index.ts
• src/commands/workflow/schemas.ts
• src/core/completions/command-registry.ts
• src/core/initiatives.ts
• src/core/templates/workflows/store-selection.ts
• test/core/completions/command-registry.test.ts
• test/core/initiatives.test.ts

✅ Files skipped from review due to trivial changes (3)

• src/core/templates/workflows/store-selection.ts
• docs/stores-beta/initiatives.md
• openspec/changes/initiatives-in-stores/tasks.md

[alfred-openspec]

Strong direction and the main store/initiative shape looks right, but I found one manifest-integrity blocker before this should merge. new initiative --title 'API: v2' writes invalid YAML, then list --initiatives silently falls back to the id because manifest parse errors are swallowed, so the scaffold needs YAML-safe serialization and/or a visible malformed-manifest diagnostic.