experiment(stores): the plan folder

[clay-good]

What this is

An experiment for stores. OpenSpec and stores do the heavy lifting; this
PR adds the thinnest layer that lets them carry planning above a single
change. Everything is cheap to rename or delete — that is the point. All
output below is real.

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

The idea

The plan is a place, not a document type. It is one folder where
everything above a change lives — your PRD, roadmap, decisions, personas,
meeting notes — without needing to label or catalog any of it. No required
file names, no required shapes: whatever your team already writes is already
valid. A required format can be wrong for someone; a place can't.

Put in your destination. Point changes at it with one line. One command maps
the in-flight work against it, live:

openspec/plan/
  product.md              your destination — any artifact, any name

openspec/changes/
  add-search/
    .openspec.yaml        plan: local   ← one line points the change UP

$ openspec list --plan
Plan: openspec/plan
  product.md
Changes pointing here: 1/2 complete
  · add-search      here   1/2 tasks
  ✓ fix-onboarding  here   2/2 tasks

Want a visible workflow? Number the folders (00_goal/, 01_requirements/)
— your location then tells the agent what is upstream and what to produce
next ("what's your cwd?", not roles). Without numbers it all still works:
one file is a valid plan.

How it fits what OpenSpec already is

plan/      where the work is going    freeform — yours, unlabeled
changes/   what is in motion          one bounded piece each
specs/     what became true           strict, checked

Work flows down (the plan decomposes into changes), truth flows up (archiving
a change updates specs), and status flows back to the plan, live. Specs stay
strict because they hold facts; the plan stays freeform because it holds
intent — the two are opposites on purpose, and the change was already the
bridge between them.

OpenSpec already does the heavy lifting

You need	OpenSpec already had	This experiment adds
a home for the plan	the openspec/ root	the plan/ folder convention
a shared home for the org	stores — setup, register, registry	—
linking a change to the plan	change metadata (.openspec.yaml)	the one plan: line + --plan flag
live status	the task lists list --changes reads	the list --plan rollup view
running it from anywhere	--store root selection	—
finding work across repos	the store registry	the scan that groups by plan:
agents seeing the plan	references:, openspec context, the context: config field	the plan shown in those surfaces
plan + code open together	worksets	—
typed artifacts, if ever	custom schemas	—
a guide through it	the skill pipeline (optional workflows)	the openspec-plan skill

The "—" rows are the story: the store is what makes this work for an org.
The store is the parent; code repos are children pointing up; going solo → org
is moving one folder into a store.

The handoff

Whoever plans starts in /opsx:plan: talk the idea through and the skill
writes the destination artifact (it synthesizes — it doesn't re-interview
you), then decomposes into self-contained, end-to-end slices, each becoming a
change born linked. Whoever builds picks up any change and works it
normally — the plan travels along via config context: and store references.
The change is the handoff artifact; status flows back with no bookkeeping.
(The synthesize and slice disciplines are borrowed from
mattpocock/skills' to-prd / to-issues.)

Proved end-to-end

One continuous run (commands in the walkthrough below):

1  Solo: product.md in; one existing change mapped with one line; one new
   change born linked → list --plan shows both, live
2  Graduation: mv the plan folder into a store, register the repo —
   same command, same answer, now org-wide
3  A second repo joins: 2/3 complete ACROSS my-app + api-server;
   a referencing repo's agent context shows:  Plan: product.md
4  The skill installs like any workflow:
   .claude/skills/openspec-plan/SKILL.md + /opsx:plan

This repo dogfoods it too: openspec/plan/ groups
four real changes, and the repo's context: config points agents at the plan.
CI green; the change record add-plan-folder
validates --strict.

Honest limits

• Rollup scans repos registered on this machine — never clones, never syncs.
• Stage order is a naming convention, not a gate.

What we want a read on

1. The noun — "plan," one boring word everywhere.
2. Numbering — opt-in convention for order + cwd navigation. Right track?
3. The skill — explore-style, brevity-enforcing interpretation layer.
4. The store story — solo → org as a one-folder move into a store.

Test it out!

# ---- solo: destination in, work mapped against it ----
mkdir -p my-app/openspec/changes my-app/openspec/specs && cd my-app
mkdir -p openspec/plan
echo '# Product: smoother setup' > openspec/plan/product.md

openspec new change add-search --plan local                    # born linked
printf -- '- [x] 1 build\n- [ ] 2 test\n' > openspec/changes/add-search/tasks.md
openspec list --plan
cd ..

# ---- graduate: move ONE folder into a store ----
openspec store setup team-plans --path ./team-plans
mv my-app/openspec/plan team-plans/openspec/plan
sed -i '' 's/plan: local/plan: team-plans/' my-app/openspec/changes/*/.openspec.yaml
openspec store register ./my-app --id my-app --yes
openspec list --plan --store team-plans                        # same answer, org-wide

# ---- a second repo joins ----
openspec store setup api-server --path ./api-server
cd api-server && openspec new change add-payments-api --plan team-plans
printf -- '- [x] a\n- [x] b\n' > openspec/changes/add-payments-api/tasks.md
cd .. && openspec list --plan --store team-plans               # rollup across repos

# ---- the agent sees it ----
printf 'references:\n  - team-plans\n' > my-app/openspec/config.yaml
cd my-app && openspec context
#   Plan: product.md  (openspec list --plan --store team-plans)

One folder, one line, one command, one skill — and stores carry the rest.

[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 | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title hints at store-based planning, but it is too vague to clearly describe the initiative/store prototype changes.	Rename it to something specific, like "experiment(stores): add store-aware initiatives and schema discovery".

✅ Passed checks (4 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.

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