Proposal: Multiple connected spec roots within a monorepo
Problem
OpenSpec supports two layouts:
- Single
openspec/root for the whole repository - Separate repos connected via Stores
Neither covers a common monorepo pattern: co-located specs per package with connected context across packages.
Use case
A monorepo with many independent blocks/packages where:
- Specs for
packages/block-ashould live inpackages/block-a/openspec/next to the code, not in a shared root - Architecture and shared specs live at the repo root; changes to shared specs cascade into block specs and vice versa
(50-75% of work happens at block level) - Teams want
/opsx:proposeand archive/merge to work across both levels without switching context
Current limitation
Running openspec init packages/block-a creates an independent instance with no awareness of the root openspec/.
Cross-references between root specs and block specs are not tracked by the CLI. Maintaining N separate openspec/ folders
with separate schemas and configs is high overhead.
Stores are designed for cross-repo scenarios, not intra-monorepo co-location.
What would help
A way to declare sub-roots that inherit from a parent root:
- Each
packages/block-a/openspec/inherits the root schema and context /opsx:proposerun insidepackages/block-a/can reference specs from the rootopenspec/specs/- Archive/merge works within the block scope but the agent has visibility into the full hierarchy
Workarounds considered
- Single root, blocks as domains: loses co-location
- Multiple independent instances: loses connected context, high maintenance overhead
- Stores: designed for cross-repo, overkill for intra-monorepo
If proposal looks not ugly, i can contribute this feature myself, just will need maintainers review later
Source: Fission-AI/OpenSpec