Multi-Repo Agent Workflows: Moving Beyond Single-Project Agents

Most agent examples live inside a single repo. Most real work does not. A typical StudyLink change touches a Django backend, a Next.js frontend, an infra repo, a shared types repo, and a docs repo. Running agents across repos taught me patterns you cannot learn from demos.

The Shared Context Problem

An agent in repo A does not know what repo B expects. You either pass context manually or establish a shared contract. I landed on shared contracts.

The shared contract lives in a types repo that every other repo depends on. When the agent needs to know the shape of an API response, it reads from the types repo. The types repo is the source of truth. Agents edit it first, other repos second.

The Workflow I Use

Agent proposes a change in the types repo (the contract)
Human approves the contract change
Agents in the backend and frontend repos implement to the new contract in parallel
Integration tests in the infra repo verify end-to-end

plaintext

repo/shared-types    &lt;- contract
repo/backend         &lt;- implements contract
repo/frontend        &lt;- consumes contract
repo/infra           &lt;- verifies contract

Branch Naming Discipline

Every cross-repo change gets the same branch name across every repo: feature/auth-refactor-2026-03. This makes the change trivially traceable. Without this, you will lose track of which branches are coordinated by week two.

The Merge Order

Types first. Backend second. Frontend third. Infra fourth. Never merge a consumer before its producer. Agents violate this order constantly if you do not enforce it at the coordinator level.

The Hardest Lesson

Do not let an agent clone five repos and work on all of them in one session. Context bleed is brutal. Spawn one agent per repo with a clear scope. The coordinator holds the cross-repo view, not any individual agent.

Tooling

A small script that spawns parallel Claude Code sessions, one per repo, with pre-written CLAUDE.md for each. Git submodules are not the answer. Separate repos with a shared types package is.

Multi-repo agent work is an advanced skill. Learn it after you have mastered single-repo flows.