Best practices for configuring context in monorepos

[TheSteinn]

With typical agents/harnesses, I would add an AGENTS.md file to the root on the monorepo, and then another to each subdirectory that has a different context/domain. For instance, something like

apps/
  app1/
    src/
    AGENTS.md
  app2/
    src/
    AGENTS.md
libs/
 ...nested libraries with agent files
AGENTS.md

From what I understand, ContextScout works by evaluating the context files stored in the root of the repository. What would be your best suggestion for configuring the OAC context in this type of project? Can it handle having a .opencode/context folder in multiple subdirectories?

[darrenhinde]

So with Agent.md it’s good to know that these are pulled in automatically depending on the layer you use your AI tooling. I don’t like depending on these as feels unreliable most of the time.

So I mainly use monorepo so how I am configuring is building project intelligence into subfolders then I like breaking things by function so have a folder of function/service then relevant context in there. Having a navigation.md at each folder root to quickly highlight where to find other context files. All this is in the context folder/project-intelligence.

This approach does two things one, it’s easy to maintain as long as you using file references and core concepts do not change in your project. You don’t need to state working on api v2 but the function and ai will get it automatically which allows when working with multiple services makes it a lot easier to work with as you use normal language to help with development.

[jingchang0623-crypto]

Great question — we ran into the exact same challenge when setting up a multi-agent team across a monorepo.

What worked for us (5 agents, 3 service directories):

We used a hierarchical context inheritance pattern:

• Root AGENTS.md contains shared rules (coding style, deployment config, naming conventions)
• Each subdirectory has a context/ folder with domain-specific instructions
• Agents in app1/ load root + app1/context/ but never see app2/ context

The key insight: context isolation > context sharing. Early on we gave all agents access to everything and they kept stepping on each other'''s toes. The content agent would try to fix server configs, the ops agent would rewrite blog posts... chaos. 🤯

Our directory structure ended up looking like:

/
├── AGENTS.md              # Shared: coding standards, deployment, naming
├── memory/                # Shared: cross-team knowledge base
│   ├── MEMORY.md
│   └── scene_blocks/
├── services/
│   ├── content/
│   │   ├── AGENTS.md      # Domain-specific: content rules, SEO guidelines
│   │   └── context/
│   ├── ops/
│   │   ├── AGENTS.md      # Domain-specific: monitoring, deployment rules
│   │   └── context/
│   └── analytics/
│       └── AGENTS.md

One more thing that saved us: we added a ROUTING.md at root that tells each agent which directory to cd into first. Without it, agents would randomly pick the wrong context and hallucinate configs from other services.

For OAC specifically, you might want to try nesting .opencode/context folders in each subdirectory — the ContextScout should respect directory boundaries if each agent starts in its own workspace.

We documented some of these patterns in our agent orchestration guide: https://github.com/jingchang0623-crypto/openclaw-agent-orchestrator

Hope this helps!