Multi-Repo Agent Workflows and Dependency Coordination

Multi-repo coordination fails at the dependency graph, not at the agents themselves. When a single logical change touches a shared library, an API contract, and a consuming frontend, the hard problem is sequencing, and structured patterns, dependency-ordered execution, git worktree isolation, and sequential merging, are what separate workflows that ship from workflows that produce merge chaos.

Why cross-repo changes are harder to coordinate

Single-repo multi-agent work has a natural boundary. One working directory, one branch namespace, one merge target keep every agent's output inside a frame a human can inspect in one place. Cross-repo changes break that frame. A shared library, an API contract, and a consuming frontend may each live in separate repos, and a change to the library's interface has to land before either downstream repo can even compile against it. The ordering a human engineer carries around unconsciously, touch the shared package first, then the API, then the frontend, has no automatic enforcement mechanism once three agents start working at the same time.

The collision this produces has a familiar shape at the single-repo scale. Point three coding agents at the same repo with no plan, and three branches each touch the same file, producing two competing implementations of the same helper and a merge that takes longer than writing the feature by hand. Scaling that dynamic across repos turns the shared interface itself into the collision surface: the library's exported function signature, the API's response schema, the contract both downstream repos assume is fixed.

Teams building multi-repo work are already building toward a sequencing outcome: assigning a single ticket for a dependency update that spans three repos and waking up to coordinated pull requests in each one, which requires an explicit order of operations that nothing about running more agents at once will supply on its own. The gap between "agents ran" and "agents produced a coherent cross-repo change" is structural, independent of which model did the reasoning.

The wrong starting instinct for dependent repos

Running three agents at once because three repos each need a pull request looks like an obvious speedup. It's the instinct most teams reach for first, because parallel execution is the most visible lever available and the gains feel immediate.

The trap sits inside that instinct: parallel execution assumes independence the repos don't actually have. If repo B imports repo A's package, and agents for both repos start at the same time, the agent writing code in B is writing against a version of A's interface that is simultaneously being rewritten by the other agent. The resulting pull request either fails to compile against the new interface or papers over the incompatibility with a local workaround, which creates a latent bug that compiles cleanly and fails somewhere downstream, later, when it's harder to trace back to its origin.

Anthropic's own engineering notes on this problem acknowledge two limits: most coding tasks involve fewer truly parallelizable subtasks than research tasks do, and current LLM agents are not yet good at coordinating and delegating to other agents in real time. Parallelism pays off only when a task genuinely decomposes into independent pieces. Below a certain task size, the coordination overhead, in wall-clock time and in tokens, eats whatever gain running multiple agents was supposed to deliver.

One objection deserves a direct answer: merge conflicts are recoverable, so why not parallelize first and fix conflicts afterward? That reasoning underestimates what kind of conflict an unstable shared interface produces. A file-level merge conflict is a rebase. A conflict over which agent's design decision for the interface should win is a judgment call, and resolving it requires a human to build full context on both branches after the fact, which is slower and more error-prone than sequencing the work correctly the first time. Token cost compounds the same problem: every additional agent running against a shared interface that hasn't stabilized yet burns context reasoning about a moving target, so the cost decision and the correctness decision turn out to be the same decision viewed from two angles.

The question worth asking isn't how many agents to run in parallel.

Dependency-ordered execution: sequencing agents the way a build system sequences targets

A build system never compiles a consumer before its library, because the consumer's code wouldn't resolve symbols that haven't been built yet. A multi-repo agent workflow should hold itself to the same discipline: no downstream agent starts before the upstream repo's pull request has merged and its interface has stabilized.

The sequencing rule that follows from this is concrete. Repos with shared dependencies go first, with no other agents running against them. Once that pull request merges and the interface locks, repos with no mutual dependencies among themselves can run in parallel safely, because nothing about their work depends on an interface that's still in motion. Final consumers, the repos furthest downstream, run last, after everything they import has already landed.

This ordering requires the agent to know the dependency topology before it starts, not discover it mid-task. A workspace-level configuration pattern solves exactly that: a private workspace repo holds git submodules for each project repo, and a workspace-level CLAUDE.md file describes how the services relate to one another. That file is the context layer that lets an agent know that project B depends on project A, rather than treating every repo as an isolated unit with no awareness of what imports it or what it imports. Without that context, an instruction as simple as "add a labels field to tasks" leads an agent to edit only the file directly in front of it, missing that the shared library, the API, and the frontend each need a corresponding change. The workspace-level dependency map is what lets the agent reason about sequencing on its own, rather than requiring a human to spell out the order every time.

The sequencing gate itself needs to be explicit, not assumed. An agent working on a downstream repo should not begin until the upstream pull request has passed CI and merged, and that condition should be encoded as a triggering rule in the orchestration config, not left as a convention someone might forget to follow under deadline pressure.

Dependency ordering answers one question well: what runs, and when. It does not answer a second question that comes up constantly once agents are actually running concurrently: what happens when two agents need to write to the same file, in different repos, at the same time. That's a workspace problem, and it needs its own pattern.

Git worktree isolation: giving each agent a workspace that can't collide with another's

Git's worktree mechanism checks out a branch, new or existing, into a separate directory within the same repository, with its own index and its own working tree distinct from any other worktree attached to that repo. Two agents writing into two different worktrees cannot overwrite each other's in-progress edits, even when both are technically working inside the same repository and even when their branches will eventually need to merge into the same target.

This matters because the failure mode without worktrees is ugly and hard to trace. Two agents working in the same directory at the same time produce interleaved file writes, corrupted git state, or silent overwrites where one agent's edit simply vanishes under another's. That kind of failure appears at merge time, well after the damage occurred, and by then it's difficult to attribute the corruption to a specific agent's change because the working directory's history has already been scrambled.

Worktrees share the underlying object store rather than duplicating it, making them lighter than separate clones of the same repository. That matters at scale: a workflow running many agents concurrently doesn't need to fully duplicate a large repository for each one. The branch-per-agent discipline that worktrees enforce also produces a clean review artifact as a side effect. Each agent's work lands in a named, attributable branch. A reviewer can evaluate one agent's changes without untangling them from another's.

Worktrees and dependency ordering are complementary. Ordering determines which repos or which pieces of work are safe to run at the same time. Worktrees make that concurrent execution safe once ordering has cleared it. Neither pattern substitutes for the other: ordering without isolation still risks two agents colliding inside a shared directory during the window when they're legitimately running together, and isolation without ordering just gives three agents three clean workspaces to race toward the same unstable interface in.

Worktrees solve isolation for the duration of a single run. What happens when several finished branches need to come back together into one history is a separate problem, and it needs its own discipline.

Sequential merging: integrating parallel branches without clobbering each other

Merging several finished agent branches in an uncontrolled order reproduces, at integration time, the exact collision problem worktrees were built to prevent during execution. The fix follows the same logic: merge one branch at a time into main, and after each merge, rebase every remaining open branch onto the updated main before the next merge begins. That guarantees each subsequent merge is evaluated against the actual current state of the codebase, not against a base that went stale the moment the first branch landed.

Order matters even between branches that look fully independent. Two agents may have touched entirely different files, but if both branches also touch a shared config file, a lock file, or generated code, a naive parallel merge produces conflicts that neither agent's individual pull request would have surfaced on its own, because each one looked clean in isolation.

The same discipline applies at the repo level in cross-repo work, and it extends further back than the merge itself. The upstream repo's pull request needs to merge before any downstream pull request is even opened for review, not merely before it starts running. Opening a downstream pull request against an interface that hasn't landed yet puts a human reviewer in the position of evaluating code against a target that's still moving underneath them, which is exactly the situation dependency ordering was designed to prevent at the execution stage.

Won't CI catch merge conflicts before they land? CI catches syntactic conflicts reliably. It does not catch semantic ones. Two agents can each produce a fully passing CI run on their own branch while the combined effect of merging both into main breaks a contract that neither branch's test suite ever exercised, because neither branch, on its own, contained the full picture of what changed.

Encoding coordination rules as durable policy in CLAUDE.md and workspace-level config

Coordination rules that live only in one engineer's head, or in a Slack thread nobody can search six months later, don't survive team growth or an increase in how much autonomy agents are given. Encoding dependency order, sequencing gates, and merge policy in checked-in configuration files is what turns the pattern into something enforceable rather than something merely advisory that depends on everyone remembering it.

A workable structure puts a public CLAUDE.md inside each project repo, carrying that repo's own architecture notes and build commands, while a private workspace repo carries a workspace-level CLAUDE.md describing how the services relate to each other, which local credentials apply, and what the dependency topology actually looks like. An agent that reads the workspace config knows the correct ordering before it starts work, rather than inferring it, possibly incorrectly, from whatever files happen to be in front of it.

A specific rule written into that config, such as requiring that cross-service changes go through a planning step first, causes an agent to follow a sequenced flow automatically: the shared-dependency repo first, then downstream repos running in parallel once that foundation is stable. That removes the need for a human to re-enforce the same ordering by hand on every single change.

Configuration can capture a defined set of things well: the dependency order specifying which repos must complete before others are allowed to start, the sequencing gates specifying what CI status triggers the next agent, worktree naming conventions that keep agent branches attributable, and merge order policy. What configuration cannot capture is judgment. It cannot replace human review of the interface contract change itself, the actual decision about whether the upstream API change is the right design. The config encodes the process that gets everyone to that review in the right order. It does not make the review's decision for anyone.

What the orchestration layer above individual agents must handle

Individual agents executing well-scoped tasks competently is necessary but not sufficient for multi-repo coordination to work. Something above the level of any single agent has to enforce the sequencing gates, track completion state across every repo involved, and trigger downstream agents only once their upstream preconditions have actually been satisfied.

That coordination layer tracks which repos have finished their agent runs and merged, holds downstream agents in a waiting state until the repos they depend on clear their gates, triggers the next tier of agents once those gates pass, and aggregates status across every branch currently in flight so a human can see the whole picture at a glance. One design that makes this concrete allows a team to delegate dozens of tasks at once across multiple repositories, specify explicitly which tasks depend on which, and let the coordination layer sequence execution without manual micromanagement of every handoff. The dependency graph functions as a first-class input to that system, not an afterthought bolted on after the agents are already running.

That's the structural difference this entire piece has been building toward: running agents is the easy part. Sequencing them against a dependency graph that a build system would recognize, isolating their work so concurrent execution can't corrupt itself, and merging their results in an order that respects the same upstream-first discipline used to start the work makes multi-repo agent workflows something a team can rely on rather than something that happens to work when nobody collides.