experiment(stores): initiatives — plan above changes, in one repo or many

[clay-good]

What this is

An experiment for stores. This PR adds a thin layer that lets OpenSpec carry planning above a single change, for any workflow and any team. Everything is cheap to rename or delete; that is the point. All output below is from real runs.

Specs are what is true. Changes are what is in motion. Initiatives are where the work is going.

The whole idea in one output

Three teams, three different workflows, one folder convention, one command:

$ openspec list --initiatives
Evergreen: roadmap.md

checkout-revamp   0/1 changes complete
  stages: 00_product → 01_engineering
  · add-guest-checkout  here            1/2 tasks

data-platform   1/1 changes complete
  stages: 00_analysis → 01_product → 02_architecture → 03_design → 04_engineering
  ✓ add-ingestion-api  here            2/2 tasks
  all changes complete — sync the evergreen artifacts this initiative served

quick-wins   1/1 changes complete
  ✓ fix-login-copy  here            2/2 tasks
  all changes complete — sync the evergreen artifacts this initiative served

A two-stage product flow, a five-stage org flow, and a scratchpad with no stages at all. OpenSpec never learned any of these workflows. It only knows that lower-numbered folders are upstream, and that is enough to handle every chain the same way.

What is the structure of the folder?

Thing	What it is
unnumbered top-level files (roadmap.md)	evergreen truths, maintained forever like specs
a subfolder (checkout-revamp/)	one initiative: a finite piece of work; creating the folder is the whole ceremony
numbered folders inside it	your workflow, spelled out in folder names (optional)
initiative: <name> in a change's .openspec.yaml	one line pointing up; <store-id>/<name> for a store's initiative

Stage names are yours, and changing the workflow is just renaming folders. No settings, no manifest, no code:

00_product/ 01_engineering/                                          a two-person team
00_product/ 01_design/ 02_engineering/                               a product team
00_analysis/ 01_product/ 02_architecture/ 03_design/ 04_engineering/ a bigger org
00_idea/ 01_build/                                                   a solo dev switching hats

The documents inside can be any format — a PRD, an RFC, a one-pager, design notes. Drop in a doc you already have; it slots in as-is. Position carries the meaning, not the format.

Running it

One repo: nothing to set up. openspec init generates the skill; from there you just talk — /opsx:initiatives captures the plan into the folder, decomposes it into linked changes, and keeps the rollup live.

Many repos: three commands, and every piece of wiring is automatic and announced (real output):

$ openspec store setup team-plans          # once — no path to choose, defaults to ~/openspec/team-plans
Store ready: team-plans

$ openspec new change add-search --initiative team-plans/smoother-setup   # in any repo
Created change 'add-search' at openspec/changes/add-search/
Initiative: team-plans/smoother-setup  (rollup: openspec list --initiatives --store team-plans)
Referenced store 'team-plans' in openspec/config.yaml — agents here now see its context.

$ cd ~ && openspec list --initiatives      # from anywhere
team-plans
  smoother-setup   0/1 changes complete
    – add-search  my-app          no tasks

That middle command does everything: writes the one-line link, records the checkout so rollups find this repo (machine-local, nothing in the repo), and references the store so agents working here see the upstream context. No registration step, no config editing, nothing to remember.

How do people use it?

Handoffs are pull-based, with one rule: read everything lower-numbered, then produce what your stage owes the next one. Nothing pushes work downstream, and no role needs its own skill. An analyst, a PM, a designer, an engineer, or a solo dev switching hats all make the same move from different positions:

Where you stand	What you need	What happens
nothing exists yet	capture the intent	ask the agent: /opsx:initiatives turns the conversation into the first artifact, or drop in a doc you already have
a middle stage	add your piece	the skill reads everything upstream and drafts your stage
the last stage	turn plans into work	the skill decomposes it into changes born linked (openspec new change <name> --initiative <ref>), each tracing to something upstream
anywhere	know where it stands	openspec list --initiatives, live from task lists, no bookkeeping

The handoff from planning to building is the change itself: self-contained, worked with the normal change skills, with status flowing back automatically. And the intent travels with it — openspec instructions and instructions apply for a linked change open with the initiative it serves and the on-disk path to its upstream context, so the working agent reads the why/what without anyone pasting it:

<initiative ref="team-plans/smoother-setup">
This change serves initiative 'smoother-setup' in store 'team-plans'.
Upstream context: /…/team-plans/openspec/initiatives/smoother-setup
Before working, read the evergreen files beside that initiative and every lower-numbered stage inside it; this change should trace to something upstream.
Status rollup: openspec list --initiatives --store team-plans
</initiative>

The same loop, one level up

OpenSpec already had the bottom row. This PR adds the top one — the same pattern, one altitude up, so there is nothing new to learn.

Altitude	Standing truth	In motion
Planning	evergreen artifacts	initiatives
Code	specs	changes

The mechanics rhyme across both rows:

• Work flows down — an initiative decomposes into changes, the way a change decomposes into tasks.
• Truth flows up — finishing an initiative updates its evergreen artifacts, the way archiving a change updates specs.
• Status flows back live — always from facts on disk (a task checked off, a change archived), never from prose.

What this PR adds

Stores already provide the shared home, registry, references, context surfacing, and worksets. On top of that, this PR is only:

• the openspec/initiatives/ folder convention (evergreen files + initiatives + stages)
• the one initiative: metadata line and new change --initiative — linking does all the wiring: it records the checkout machine-locally so rollups scan it (nothing written into the repo for that), and it references the store in the repo's own config so agents there see the upstream context — announced in the output, with a conservative fallback to a printed one-liner when the config can't be edited safely
• the openspec list --initiatives [--store <id>] rollup (works outside any root, scans registered stores + linked repos, never clones or syncs) — and it nudges the evergreen sync when an initiative's changes are all complete
• the initiative block in instructions / instructions apply (shown above), so upstream intent reaches the agent working a linked change
• store setup <id> with no path decision (defaults to ~/openspec/<id>, the same visible location the interactive prompt suggests)
• the openspec-initiatives skill (/opsx:initiatives), in the core profile so openspec init generates it. Routed by what is on disk: nothing yet, capture the conversation; a portfolio, open with where everything stands; inside an initiative, advance the workflow and decompose. Every move ends in a short numbered menu of real next actions.

Put the folder in a store and the same command answers org-wide, across every registered repo, from any directory. Going from solo to team is moving one folder.

What a real dogfood found (and what it changed)

A full run against a real multi-repo product on this machine — four repos, one shared effort, an existing plan that lived only in commit-message prefixes — traced every phase: store setup, capture, cross-repo linking, rollup, and working a linked change. Verdict: the skeleton held (numbered stages were "the best part — zero config, renaming folders is reconfiguring"; the rollup was the only thing showing several repos under one heading), but the two load-bearing joints existed only halfway, and the trace caught both:

Finding	Fix (in this PR now)
Linked changes were silently invisible to the rollup until their code repo was registered as a store — a concept conflation, diagnosable only by reading source	linking is the registration: the checkout is recorded machine-locally at link time; the rollup scans it with no further setup
Upstream intent never reached the working agent — names surfaced (after manual config), content and membership never	instructions / instructions apply open with the initiative block above; stale refs stay visible instead of vanishing
The documented headline skill was not generated by openspec init (it was outside the default profile)	initiatives joins the core profile
Friction: no initiatives/ dir in a fresh store, link hints missing the store-qualified ref, a no-root error suggesting the wrong fix, help text naming a wrong path	all fixed; store setup seeds initiatives/, hints are store-qualified, openspec init leads the fix

Proof

• The three-workflow portfolio above ran end-to-end for real: three chains, three linked changes, one rollup, same code path for all of them, plus a stage-chain unit test pinning it.
• The dogfood scenario re-ran green after the fixes: a store, a plain unregistered code repo linking a change, the rollup finding it from inside the repo and from outside any root, and the initiative block appearing in the change's instructions. New unit tests pin linked-root discovery and link resolution.
• Round 2 ran against two more real repos that had never touched OpenSpec, under a harder bar: complete every phase using only what the CLI itself prints — no reading source or docs. The bar was met. All four round-1 findings verified fixed: identical rollup from inside either repo and from ~ with neither registered as anything; the initiative block leading every instructions output; the skill generated by plain init; hint-rich linking. The one cold-start gap it caught (nothing taught a first-timer the folder/stage layout) is fixed — both empty states now teach it.
• Round 3 put the skill in the driver's seat — every move through /opsx:initiatives and the change skills, nothing hand-made. All five moves passed: it read live state before speaking, opened with a standing table and a menu with exactly one recommended option, drafted a middle stage from upstream without re-interviewing (every decision row tracing to the intent doc), worked a linked change with the initiative context arriving automatically, and — when the rollup flipped to all-complete and printed its nudge — synced the evergreen file honestly, recording what actually shipped and what drifted rather than papering "complete" into "done." The full loop closed: work flowed down, truth flowed up, status stayed live. Its two instruction findings (a blocked-state hint naming a skill init may not generate; an ambiguous no-code-in-upstream rule) are fixed in this PR.
• This repo dogfoods it with a chain that fits no standard template (01_who → 02_decisions), grouping four real changes, 2/4 complete, live.
• The store path ran too: solo, then graduation into a store, a second repo joining, and the outside-any-root fallback. Commands are in the docs guide.
• CI green: full suite, and the change record validates --strict. Decisions and their whys are in add-initiatives.

Honest limits

• Stage order is a naming convention, not a gate. The skill just knows what is upstream.
• Rollup scans checkouts this machine knows — registered stores plus repos that have linked a change. It never clones or syncs; the initiative: line itself lives in git and travels with the repo, so any machine with the checkouts can answer.
• Discovery state is machine-local and rebuilds by linking: a fresh machine (or lost state) sees a repo again the moment it links any change there. Changes linked before this build stay invisible until then — a doctor check for "changes reference an initiative but their repo isn't scanned" is a natural follow-up, deliberately not this PR.
• Reactions fire when the skill looks. Reactive triggers (git hooks, CI) are a natural next experiment, deliberately not this one.
• Typed artifacts stay out: freeform is the point, and custom schemas already exist if a team ever wants types.

Where feedback would help most

1. Linking does all the wiring — one command records the checkout machine-locally AND auto-edits references: in the repo's config (announced, conservative fallback). Right call, or is the config edit too much magic?
2. Stale links — pre-fix or cross-machine links stay invisible until the repo links again. Acceptable for the experiment, or does doctor need an orphaned-initiative:-ref check first?
3. Completion semantics — at N/N complete the rollup nudges an evergreen sync. Should a finished initiative eventually archive (the planning analog of archiving a change), or stay a folder someone deletes?
4. Core profile — the skill now generates for everyone on openspec init. Worth the +1 default skill, or should it stay opt-in while experimental?

Naming note: the old beta's initiatives machinery (manifests, registration) stays deleted; its planning history moved intact to openspec/explorations/. This experiment is a folder convention, one metadata line, one rollup, one skill.

Try it

mkdir -p acme/openspec/changes acme/openspec/specs && cd acme

# three initiatives, three workflows; invent your own chain
mkdir -p openspec/initiatives/checkout-revamp/{00_product,01_engineering}
mkdir -p openspec/initiatives/data-platform/{00_analysis,01_product,02_architecture,03_design,04_engineering}
mkdir -p openspec/initiatives/quick-wins
echo '# Roadmap: what we ship next' > openspec/initiatives/roadmap.md
echo '# Product spec: guest checkout' > openspec/initiatives/checkout-revamp/00_product/product-spec.md

openspec new change add-guest-checkout --initiative checkout-revamp   # born linked
printf -- '- [x] 1 build\n- [ ] 2 test\n' > openspec/changes/add-guest-checkout/tasks.md
openspec list --initiatives          # the output shown above

# the team path is the three commands under "Running it" above; then:
openspec instructions apply --change add-search  # opens with the initiative block
# (full walkthrough: docs/stores-beta/initiatives.md)

🤖 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 main change: store-backed initiatives spanning one or more repos.

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

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Clarify the --store discovery contract.

The requirement says store discovery is "in addition to the current repo's own schemas," but the openspec schemas --store acme-plans scenario reads like a store-only listing. Please spell out whether --store merges local and store results or replaces the local view, otherwise implementations and tests can diverge here.

♻️ Proposed spec clarification

- The system SHALL discover schemas and artifact types from a store when the store
- is selected with `--store` or referenced by the current repo, in addition to the
- current repo's own schemas.
+ When a repo references a store, the system SHALL discover that store's schemas
+ and artifact types alongside the current repo's own schemas.
+ When `--store <id>` is used, the system SHALL list that store's schemas and
+ artifact types for the selected store.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	### Requirement: Store-aware schema discovery
	The system SHALL discover schemas and artifact types from a store when the store
	is selected with `--store` or referenced by the current repo, in addition to the
	current repo's own schemas.
	#### Scenario: Listing a store's schemas
	- **WHEN** a user runs `openspec schemas --store acme-plans`
	- **THEN** the system lists the schemas defined in the `acme-plans` store
	- **AND** each schema shows its name and description
	#### Scenario: Referenced store schemas are visible from a repo
	- **WHEN** a repo references the `acme-plans` store and the user runs
	`openspec context`
	- **THEN** the referenced store's custom artifact types are listed as read-only
	context
	- **AND** each entry includes a one-line summary and a fetch command
	### Requirement: Store-aware schema discovery
	When a repo references a store, the system SHALL discover that store's schemas
	and artifact types alongside the current repo's own schemas.
	When `--store <id>` is used, the system SHALL list that store's schemas and
	artifact types for the selected store.
	#### Scenario: Listing a store's schemas
	- **WHEN** a user runs `openspec schemas --store acme-plans`
	- **THEN** the system lists the schemas defined in the `acme-plans` store
	- **AND** each schema shows its name and description
	#### Scenario: Referenced store schemas are visible from a repo
	- **WHEN** a repo references the `acme-plans` store and the user runs
	`openspec context`
	- **THEN** the referenced store's custom artifact types are listed as read-only
	context
	- **AND** each entry includes a one-line summary and a fetch command

🤖 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/changes/initiatives-in-stores/specs/store-aware-artifacts/spec.md`
around lines 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.

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

[alfred-openspec]

Looks good to merge from my side now. The manifest integrity blocker I had is gone with the no-manifest initiatives shape, latest CI is green, and the focused initiatives/context/link tests pass locally.

[alfred-openspec]

Re-reviewed the latest pushes. The dogfood fixes address the prior concerns, CI is green, and the focused initiatives/link/config tests plus strict validation pass locally. Good to merge from my side.