Question: Best practices for scaling OpenSpec in a large monorepo?

[orbiri-ns]

Hi everyone,

I've had a great experience with OpenSpec on standalone full-stack web projects and I'm now starting to introduce it into a much different environment: a massive, low-level systems programming monorepo with ~100 developers.

I'm keen to hear from others who might have experience integrating OpenSpec into large-scale repositories. What are your experiences or best practices for managing a large and growing number of specs, especially in an environment with many concurrent changes (e.g., numerous open pull requests)?

More specifically, I'm curious about the context-awareness of the coding agents. In a repository of this scale, how does OpenSpec effectively identify and scope the right context for a given task? My main concern is that without an overarching architecture document or a similar guide for the agent, it might struggle to navigate the vast codebase efficiently.

I guess this is a question for both the maintainers of OpenSpec and for the community :)

Thanks!

[TabishB]

Hey @orbiri-ns monorepo's and cross repos are a bit of a challenge not just for a lightweight framework like openspec (which to be fair is honestly just instructions for agents to follow + structure) but for the agents and LLM tools themselves especially in terms of context management.

Getting an agent to plan effectively across larger repos and multiple repos is tricky, this is where the accuracy falls of with size of the relevant monorepo. Which is what you've also mentioned towards the end. Large codebase traversal is a limitation of the coding agent/tools themselves.

I've seen some people mention ways around it through use of subagents that have their own context windows, but cant really say i've used it or tried that in practice. Others have mentioned the use of codebase indexing tools that apparently help with this, but again unsure in their practical effectiveness.

---

best practices for managing a large and growing number of specs, especially in an environment with many concurrent changes (e.g., numerous open pull requests)?

This is a little tricky. In terms of the volume of specs the intuition there would be to initialize openspec multiple times per app. But this makes cross app changes a bit harder.

The parallel dev experience also for change deltas that are generated are not super great to be honest at the moment as someone who usually works on multiple changes in parallel, but I'm working to improve this soon.

That being said I think at the root of this is I think storing and managing specs through .md files is probably only managable up till a certain size of a project. Maybe storing specs in a db or some other store would be more scalable and easier to manage but that introduces its own set of challenges and stops this from being just a lightweight easy to use framework.

TLDR; I have no experience using OpenSpec in a larger setting yet so can't really say for certain what works and dosen't 😛 I'll let others chime in too though.

---

Additional similar previous questions:

Discord message on monorepos: https://discord.com/channels/1411657095639601154/1411658069368377405/1425578802376872086

Reddit thread on monorepos:
https://www.reddit.com/r/cursor/comments/1nomd8t/comment/ng2vy92/?context=3&share_id=7d3kYsr_itvnNfLaatLzF&utm_content=1&utm_medium=ios_app&utm_name=ioscss&utm_source=share&utm_term=1

[TabishB]

It's a super interesting topic though, if you have thoughts on it and ways to overcome this would love to talk about this more. Feel free to hit me up anytime :)

[orbiri-ns]

Hey @TabishB, thanks for the detailed and honest reply. It's great to know I'm not alone in thinking about these challenges. You've really hit on the key issue, which is the agent's context management and codebase traversal.

My current thinking is leaning towards what you might call a "guided context" approach. What if we could instruct the agent to follow the breadcrumbs of a hierarchy of specs?

Essentially, we'd create a top-level spec that acts as a software architecture document, outlining the major components and their interactions. This "meta-spec" would then link to more granular specs for each sub-component, which in turn could link to even more specific ones.

This process is no different from what a human developer does when onboarding to a new project. They don't read the entire codebase at once; they start with the architecture diagrams, understand the main flows, and then dive into the specific area they need to change. The hierarchy of specs would serve as that map for the agent.
• For proposing broad changes, the agent would start at the top, gathering the necessary architectural context before suggesting modifications to the specs and then acting on them.
• For localized tasks, as I mentioned, we could still direct the agent to a specific sub-spec, bypassing the top-down discovery when we already know the exact point of impact.

I wonder if this approach could provide the necessary guardrails and context for an agent to navigate the vast codebase effectively, making it a more powerful partner in a large monorepo.

It's just an idea, but it feels like a promising direction to explore. Would love to hear what you and others think!

[orbiri-ns]

Hey @TabishB,
Thank you again for the thoughtful discussion. It really helped me crystallize my thinking on how to tackle this.

My previous comment floated the high-level idea of an agent following the "breadcrumbs of a hierarchy of specs." I've spent some time thinking about how that would work in practice, especially considering OpenSpec's existing project.md convention.

Here is a more concrete proposal that builds on that idea to support deeply nested sub-architectures.

Proposal: Hierarchical Specs with Component-Level Architecture

The goal is to allow the openspec/ directory to mirror the nested structure of a complex codebase. We can achieve this by establishing a convention for specs to link to other specs, creating a navigable tree of requirements.

1. The Core Convention: From a Flat List to a Nested Tree

Instead of a single project.md linking to a flat list of component specs, we'll allow any spec to link to more granular specs. We can introduce a convention, perhaps using a filename like component.md or index.spec.md, to signify a sub-architecture document that groups related specs.

Example Nested File Structure:

This structure allows us to represent a complex domain like "Authentication" with its own internal architecture.

openspec/
└── specs/
    ├── project.md            # Top-level architecture, links to major domains like auth/
    └── auth/
        ├── component.md      # Sub-architecture for the Auth domain
        │                     # Links to jwt/, mfa/, and oauth/
        ├── jwt/
        │   └── spec.md       # Granular spec for JWT handling
        ├── mfa/
        │   ├── component.md  # Even deeper sub-architecture for MFA
        │   │                 # Links to totp/spec.md and sms/spec.md
        │   ├── totp/
        │   │   └── spec.md   # Spec for TOTP logic
        │   └── sms/
        │       └── spec.md   # Spec for SMS-based MFA
        └── oauth/
            └── spec.md       # Spec for OAuth flows

specs/project.md might contain:

# System Architecture
- **[Authentication Domain](./auth/component.md):** Manages all user authentication, sessions, and multi-factor auth.
- **[Profile Domain](./profile/component.md):** Manages user data.

specs/auth/component.md would then contain:

# Auth Domain Architecture
This component is responsible for authenticating users.
- **[JWT Handling](./jwt/spec.md):** Issues and validates JSON Web Tokens.
- **[Multi-Factor Auth](./mfa/component.md):** Manages second-factor verification.
- **[OAuth Providers](./oauth/spec.md):** Handles logins via third-party services.

2. The "Breadcrumb" Traversal Logic for Agents

This is the key change. We update the agent's instructions to perform a recursive, context-gathering traversal.

"To understand a task, start at openspec/specs/project.md. Follow the markdown links that are most relevant to the request, collecting context from each component.md or spec.md file you traverse. Continue until you reach the most specific spec file related to the task. This path of breadcrumbs forms the complete context needed to generate the change."

Workflow Example:

User: /openspec:proposal Add support for hardware keys in MFA

Agent's Path of Discovery:

• Starts at project.md, sees the link [Authentication Domain](./auth/component.md).
• Reads auth/component.md, follows the link to [Multi-Factor Auth](./mfa/component.md).
• Reads mfa/component.md to understand the existing MFA architecture (TOTP, SMS).
• Now, with the full context (project -> auth -> mfa), it can propose a change.

Generated Change:

• The agent creates a new spec: openspec/changes/add-hw-key-mfa/specs/auth/mfa/hw-keys/spec.md.
• It also creates a delta for the parent architecture: openspec/changes/add-hw-key-mfa/specs/auth/mfa/component.md to add a link to the new spec.

Benefits of This Deeply Nested Approach

• Precision at Scale: The agent gets exactly the context it needs—no more, no less. It understands both the high-level system design and the low-level details of the specific component it's modifying. 🎯
• Mirrors Code Structure: The spec hierarchy can directly reflect the monorepo's directory structure, making it intuitive for developers.
• Decentralized Ownership: Teams can own and manage their component.md files without creating merge conflicts at the top-level project.md.
• Avoids "God Specs": Prevents individual spec files from becoming massive and unmanageable by encouraging logical decomposition.

This feels like the right direction to make OpenSpec truly powerful in a large, complex monorepo with many developers. It's a natural evolution of the existing spec-driven philosophy.

Would love to hear your thoughts on this more refined take!

[TabishB]

@orbiri-ns Thanks for the detailed response and taking the time to think through the proposal. I'll need to spend some time to take a deeper look on whats being proposed here and see if it does solve some of the issues for the project.

I think the tricky part here is making a project that works for smaller as well as bigger repos. Currently the instructions for the agent are relatively simple and we can say things like "when doing planning look at these files". If we start having to add in another branching condition here we would need to include multiple search paths. I feel like instructions for monorepos need to be inherently different and can't be shared with the current instruction set. The scaffolding for this would also have to look very different.

It's something I have to think about deeper here, but just wanted to comment to say I haven't missed the response just doing a bit of thinking :)