docs(cli): propose multi-library command support

[runsonmypc]

Recursive list discovery exposes descendant work, but view, show, validate, and workflow/lifecycle commands still operate against one root. This proposal defines consistent support across library-aware CLI commands so users can inspect and act on that discovered work from the repository root.

Closes #2011. Follow-up to #2009.

• Aggregate dashboards, bulk validation, health/context, and inventories with relative ownership labels.
• Resolve named changes/specs to their unique owning library; duplicate names require explicit selection with actionable candidate paths.
• Add optional --library <project-path> targeting across library-aware commands while preserving selected-store scope and default discovery without configuration.
• Keep archive, creation, setup/update, and schema writes scoped to one project; retain artifact/edit-root ownership and command hints.
• Specify compatibility for single-library JSON, deprecated adapters, native Windows paths, and partial failures.

The design includes a command coverage matrix. The tasks include fixture tests, documentation, Windows CI, end-to-end sibling-artifact checks, and actual CLI screenshots using fictional data.

Proposal only: the diff contains only openspec/changes/support-multi-library-cli/. No runtime code or existing project artifacts are changed. Implementation waits for proposal approval as required by CONTRIBUTING.md. The existing listing PR remains separate.

Validation: openspec validate support-multi-library-cli --type change --strict --json passed with no issues; all four planning artifacts are complete; whitespace checks passed. Code tests are deferred to implementation because this PR changes only planning artifacts.

Summary by CodeRabbit

• Documentation
  • Added specifications for selecting and discovering multiple local libraries in the CLI, including --library targeting and ownership-aware item lookup.
  • Documented expected behavior for aggregate dashboards and validation, including per-library results and diagnostics when a library cannot be inspected.
  • Clarified how named workflows, archive operations, and setup commands should handle duplicate items and avoid ambiguous writes.
  • Recorded compatibility expectations for existing single-library behavior and store-selected projects.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: Fission-AI/OpenSpec/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: dd25d709-3d81-460a-bae2-3f4334ce156a

📥 Commits

Reviewing files that changed from the base of the PR and between 781c7f9 and ed8a8f7.

📒 Files selected for processing (11)

• openspec/changes/support-multi-library-cli/.openspec.yaml
• openspec/changes/support-multi-library-cli/design.md
• openspec/changes/support-multi-library-cli/proposal.md
• openspec/changes/support-multi-library-cli/specs/cli-archive/spec.md
• openspec/changes/support-multi-library-cli/specs/cli-artifact-workflow/spec.md
• openspec/changes/support-multi-library-cli/specs/cli-library-selection/spec.md
• openspec/changes/support-multi-library-cli/specs/cli-show/spec.md
• openspec/changes/support-multi-library-cli/specs/cli-update/spec.md
• openspec/changes/support-multi-library-cli/specs/cli-validate/spec.md
• openspec/changes/support-multi-library-cli/specs/cli-view/spec.md
• openspec/changes/support-multi-library-cli/tasks.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

This proposal defines local library discovery and selection across OpenSpec CLI commands. It specifies aggregate browsing and validation, owner-aware item lookup, ambiguity handling, and single-library scope for mutations. It also defines compatibility behavior for registered stores, JSON output, and existing project layouts.

Changes

Multi-library CLI

Layer / File(s)	Summary
Discovery and library selection openspec/changes/support-multi-library-cli/.openspec.yaml, openspec/changes/support-multi-library-cli/design.md, openspec/changes/support-multi-library-cli/proposal.md, openspec/changes/support-multi-library-cli/specs/cli-library-selection/spec.md, openspec/changes/support-multi-library-cli/tasks.md	Defines library discovery, --library selection, conflicts with store and positional project selection, store scope, path identity, and discovery-related tasks.
Aggregate reads and item lookup openspec/changes/support-multi-library-cli/specs/cli-library-selection/spec.md, openspec/changes/support-multi-library-cli/specs/cli-show/spec.md, openspec/changes/support-multi-library-cli/specs/cli-validate/spec.md, openspec/changes/support-multi-library-cli/specs/cli-view/spec.md, openspec/changes/support-multi-library-cli/tasks.md	Defines aggregate view and validation output, ownership metadata, partial-failure reporting, and unique or ambiguous item lookup and display.
Scoped workflows and writes openspec/changes/support-multi-library-cli/specs/cli-library-selection/spec.md, openspec/changes/support-multi-library-cli/specs/cli-archive/spec.md, openspec/changes/support-multi-library-cli/specs/cli-artifact-workflow/spec.md, openspec/changes/support-multi-library-cli/specs/cli-update/spec.md, openspec/changes/support-multi-library-cli/tasks.md	Defines target resolution before writes, owner-scoped archive and workflow behavior, library-specific update selection, and implementation and verification tasks.

Priority: ➖ Normal

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

Change: Other

Suggested reviewers: tabishb

Merge Risk: ⚪ Minimal · up to ed8a8

This is a proposal-only change with no runtime behavior impact. No actionable merge-blocking issues remain.

Architecture Summary

Architecture risk: 🔵 Low · up to ed8a8

The change affects 1 system.

Changed systems: openspec

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — openspec (service) was modified; 11 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in openspec/changes/support-multi-library-cli/.openspec.yaml: Added OpenSpec metadata specifying the spec-driven schema and creation date 2026-09-29.
• observed — Modified behavior in openspec/changes/support-multi-library-cli/design.md: Adds the complete multi-library CLI design: shared invocation-local discovery; target selection and ambiguity rules; command-family behavior and write boundaries; aggregation, validation, schema, context, and doctor handling; JSON compatibility and ownership metadata; unreadable-candidate safeguards; native path and terminal requirements; and risks, migration steps, and rollback.
• observed — Modified behavior in openspec/changes/support-multi-library-cli/proposal.md: The proposal adds local-library selection and owning-library resolution across CLI commands, combined dashboard and validation behavior, ambiguity handling, scoped writes and registered stores, compatibility requirements, documentation updates, and the cli-library-selection capability. It lists changes to six existing capabilities and specifies that duplicate item names across discovered libraries require selection, while product-local commands retain product-local scope.
• observed — Modified behavior in openspec/changes/support-multi-library-cli/specs/cli-archive/spec.md: Added archive requirements for selecting the owning library before checks or modifications, including outcomes for unique descendant matches, duplicate names, and unreadable candidates.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies a documentation proposal for multi-library CLI support, which matches the planning artifacts and PR objectives.
Linked Issues check	✅ Passed	The PR satisfies the proposal-only coding requirements in #2011. proposal.md defines local-library discovery, aggregate browsing and validation, owning-library lookup, --library selection, ambigui…
Out of Scope Changes check	✅ Passed	The diff adds only planning artifacts under openspec/changes/support-multi-library-cli/. The files define the requested multi-library CLI contract and its verification plan. No unrelated runtime cod…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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