#1729·OpenSpec

Proposal: Multiple connected spec roots within a monorepo

Author: IlrilanCreated Aug 27, 2026Updated Sep 14, 2026
Labelsdesign-review

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:

  1. Specs for packages/block-a should live in packages/block-a/openspec/ next to the code, not in a shared root
  2. 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)
  3. Teams want /opsx:propose and 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:propose run inside packages/block-a/ can reference specs from the root openspec/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