One Agent Per Repo: An Orchestration Pattern for Multi-Repo AI Coding

just_an_electron — Tue, 16 Jun 2026 08:19:02 +0000

Your AI coding assistant is brilliant inside a single repo. Drop it into a DevOps workspace of a dozen and watch it fall apart.

It skims half of one repo and half of another, forgets which ones are read-only, blends their conventions, and spends most of its context window just trying to remember the rules. You ask one cross-cutting question and get a confident, half-wrong answer stitched together from the wrong files. The harder problem isn't the model, it's that you handed one brain a dozen jobs at once.

There's a fix, and it mirrors how good teams already split the work: give each repository its own specialised agent, and let one orchestrator route the work and merge the answers.

That's it. The rest of this post is the why and the how: the one constraint that quietly dictates the whole design, copy-pasteable starter agents you can drop in today, and the failure modes to avoid. Examples use Claude Code subagents, but the idea ports to any agent runtime with per-agent prompts and tool scoping.

TL;DR

One AI agent per repo, each with a scoped prompt and scoped tools.

A single orchestrator (the main session) routes work and merges answers. It can't be a separate "router agent," because subagents can't spawn subagents.

Make read-only repos read-only by removing their write tools, not by asking nicely.

Cross-repo questions fan out to several agents in parallel, each in a clean context.

It's a few Markdown files. No framework required.

The problem

Picture a system that's grown into several independent repos, checked out side by side, a layout most DevOps and platform teams will recognise:

Repo	Role	Edit policy
`backend`	Application services you debug against, source of truth for behavior and stack traces	read only
`frontend`	Web client / UI you debug against	read only
`infrastructure`	Terraform / IaC you own	edit, confirm first
`deploy`	Kubernetes manifests / Helm charts you own	edit, confirm first
`docs`	Runbooks and documentation	edit via pull request

This is a DevOps view of the world: infrastructure and deploy are yours to change, but they touch production, so an agent should never apply a change without showing you the diff and getting a yes. backend and frontend belong to other teams; you read them to debug, never to edit. docs you change freely, but through a pull request. Three tiers, and each one becomes a different agent.

Point one AI session at all of it and you hit three walls.

Context dilution. Loading every repo's conventions, layout, and edit policy into one context window crowds out the actual problem, and the model starts leaking rules from one repo into another ("it's fine to edit here" bleeding into a read-only repo).

Serial investigation. A question like "is this a code bug or an environment misconfiguration?" spans two repos. One session reads the first, then the second, then struggles to hold both in mind at once.

Weak guardrails. When "this repo is read-only" lives only in a prose instructions file, it's a polite request the model can forget under load, not an enforced boundary. On a shared workspace, that's how the wrong repo gets edited.

The thesis: one specialised agent per repo, and a single orchestrator that routes work to the relevant ones, in parallel, and merges their findings.

The pattern has a name: orchestrator-worker

It mirrors how you'd run a team. You wouldn't make one engineer own the backend, the Helm charts, and the docs all at once, holding every rule in their head. You'd give each area an owner and put someone in charge of routing the work. That's the orchestrator-worker pattern (also called manager-worker, or conductor), and it's well-trodden ground. The recurring lessons:

One agent per repo means a focused context window per repo. The backend agent reads only backend conventions; the deploy agent only deploy conventions. The orchestrator coordinates but holds none of the detail.
A multi-repo layout is where this shines. Independent repos mean agents in different repos can't create file conflicts, unlike a monorepo where parallel edits collide.
Managers hold the plan; workers execute, one repo, one task.

None of this is new. There's already plenty written on multi-agent orchestration and the orchestrator-worker pattern, and a quick search will turn up more than enough. What follows is my take on making it actually work across a real multi-repo workspace.

The one constraint that shapes everything

Internalise this before drawing any boxes, because it kills the most intuitive design:

Subagents cannot spawn other subagents.

The tempting model is a three-tier pipeline: a router agent dispatches to repo agents, which report up to a separate answer agent. That's two levels of delegation, and the second level isn't allowed.

So the orchestrator can't be a subagent. It must be the main conversation itself. The session you talk to is the conductor: it reads your request, decides which repo agents to invoke (the one and only level of subagents), collects their reports, and synthesises the answer.

        YOU
         |  (your request)
         v
  +--------------------------------------------+
  |   ORCHESTRATOR  =  the main session         |
  |   - reads the request                       |
  |   - routes to the right repo workers        |
  |   - fans out in parallel when needed         |
  |   - merges their reports                     |
  |   - replies to you                           |
  +--------------------------------------------+
       |          |          |            |
       v          v          v            v
  [backend]   [deploy]   [infra]      [docs]     <- one worker per repo
   agent       agent      agent        agent        (cannot spawn more)

Every choice below lives inside this constraint.

The building block: one agent definition per repo

In Claude Code, each agent is a small Markdown file with YAML frontmatter, dropped in .claude/agents/:

---
name: backend-expert
description: >
  Application services you debug against: the source of truth for behavior and stack
  traces. Use when an issue involves a traceback, wrong output, or "where does X happen
  in the code". Read only.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are the expert for the backend repository.
- Scope: application services, the code paths behind a stack trace.
- Access: READ ONLY. Describe fixes precisely (file:line + the change); never apply them.
- Report back: a conclusion first, then file:line references and root cause. Findings,
  not raw file dumps.

Three frontmatter fields carry the design:

Field	Role	Note
`description`	Routing signal the orchestrator matches requests against	Write it as "use when ..."
`tools`	Hard guardrail: omit `Edit`/`Write` and the agent is physically read-only	The capability is absent, not discouraged
`model`	Cost/quality dial per agent	Heavy model for reasoning, cheap for lookups

The orchestrator itself has no file; it's the main loop. Its routing comes from each agent's description plus a short triage guide in your top-level instructions file (CLAUDE.md) mapping issue types to repos. Match one agent and delegate. Spans repos, and it fans out in parallel and reconciles.

Copy-pasteable starter agents

The read-only example above (backend-expert) is one tier: it simply has no write tools. As a DevOps engineer you also own a couple of repos, so here are the two editable tiers. The key difference from a read-only agent is in tools and in the policy line of the prompt.

deploy-expert.md (edit, confirm first)

---
name: deploy-expert
description: >
  Kubernetes manifests and Helm charts you own: env config, resource limits, what's set
  per environment. Use for deployment questions and to make deployment changes.
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
---

You are the expert for the deploy repository. You may edit it, but it touches production.
NEVER apply a change without first showing the human the exact diff and getting an explicit
yes. Propose first; edit only on confirmation; never push, apply, or roll out on your own.
Report conclusion-first with file:line references.

(The infrastructure repo gets the same shape: edit allowed, but confirm-before-apply,
because Terraform changes touch production too.)

docs-editor.md (edit via PR)

---
name: docs-editor
description: >
  Runbooks and customer-facing docs. Use to find an existing runbook/known fix, or to
  draft/edit docs. EDITS ALLOWED but only via pull request: never push to the default
  branch directly.
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
---

You are the expert for the docs repository. Edits are allowed, but ALL changes go through
a pull request, never a push to the default branch. Prefer drafting; let the orchestrator
handle branch/PR creation. Follow existing structure and tone. Report conclusion-first.

Turning edit policies into real boundaries

This is the part teams under-appreciate. A single monolithic agent holds write capability everywhere and relies entirely on remembering which directories are off-limits. In the per-repo model the boundary is structural, and it comes in three tiers:

Read-only (hard wall). The repos you only debug against, like backend and frontend, get an agent with no Edit/Write tools at all. It can't modify them even if you ask, because the capability is absent. No memory required.
Edit, confirm first (production repos). The repos you own that touch production, like infrastructure and deploy, get write tools, but the prompt forbids applying anything without showing you the diff and getting a yes, and forbids pushing or rolling out unattended.
Edit via PR (low-risk repos). Repos like docs: write freely, but land changes through a pull request rather than a direct push.

Belt and suspenders. The most dangerous failure mode of AI on a shared workspace, quietly editing or deploying the wrong thing, is designed out: a read-only agent can't, and a production agent won't without a yes.

A worked example, end to end

Request: "A service crashes on startup in production. Is it the application code or the deployment config?"

1. The orchestrator routes. The request matches two agents, so it fans out in parallel:

orchestrator
   |--> backend-expert : "trace the startup crash; is the code actually broken?"
   `--> deploy-expert  : "could the deployment config cause this? what's set in prod?"

2. Workers investigate independently, each in a clean context.

backend-expert traces startup and finds the service reads a required env var and exits cleanly if it's missing. The code is correct; it's failing fast by design.
deploy-expert finds the prod Helm values never set that env var (it's only in the staging values). Root cause: a deployment-config gap, not the code.

3. The orchestrator merges and answers you:

It's a deployment-config gap, not a code bug. The service requires env var X at startup (backend, file:line), but the prod Helm values don't set it; only staging does (deploy, file:line). I can add it to the prod values for you, here's the one-line diff. Apply it?

And there's the payoff of the tiers. backend was read-only, so it could only explain. deploy is yours to edit, so the same agent that found the gap can fix it, but it stops and shows you the diff first because that repo touches production. You get the fix in one motion, without ever handing an agent unattended write access to prod.

A single session would have read both repos serially and juggled both rule sets at once. The split keeps each worker sharp and runs the investigations concurrently.

Everyday flows: single-repo lookups go to one agent; "write this up" goes to the docs agent (which lands it as a PR); and you can always force a route: "ask the deploy-expert what env vars the prod values set for service Y."

Operating, tuning, and pitfalls

A few things that make or break it:

Routing lives in description. Misrouting means a vague description; sharpen it, and keep them from overlapping or routing turns into a coin flip.
Each agent describes its own repo, not the whole system, and you dial model per agent (strong for reasoning, cheap for lookups).
Don't grant write tools "just in case". That quietly throws away the biggest safety win. Default to read-only.
Workers don't share memory. They don't see each other's state, so the orchestrator passes along anything that needs to cross over.

Limitations, and the heavier alternative

No deep nesting. One level of workers only; restructure "a worker needs workers" as orchestrator phases.
No shared memory between workers. Reconciliation is the orchestrator's job.
Routing is heuristic, not a hard dispatch table.

For deterministic, large-scale fan-out, like "audit every repo for X" or a migration across all of them, reach for a scripted workflow: code that orchestrates agents with explicit loops, parallel stages, and structured outputs. Rule of thumb: interactive subagents for debugging and exploration; a scripted workflow when you need repeatable, massively parallel passes.

Adopt it in five minutes

Create .claude/agents/ in your workspace root.
Add one agent file per repo (start from the snippets above). Repos you only debug: omit Edit/Write. Repos you own that touch production: add them, plus a confirm-before-apply policy. Low-risk repos like docs: add them, plus a land-via-PR policy.
Add a short triage guide to your top-level CLAUDE.md mapping issue types to repos.
Write each description as "use when ...", keeping them disjoint.
Ask a cross-repo question and watch the orchestrator delegate.

I've been running this across a multi-repo workspace and it's changed how I debug. One generalist drowning in every repo loses to a small team of specialists with a coordinator. True of people, true of agents. Give each repo an owner, put one session in charge, and make the agent that touches production ask before it acts.

How are you structuring this? One agent per repo, one per domain, or something else? Drop it in the comments. 👇

DEV Community: just_an_electron