Why cross-repo work breaks
Picture a feature that touches an API, its client library and the web app. Hand each repo to its own agent with the same loose description and each one does something reasonable. The API agent renames a field; the client agent keeps the old name; the web agent invents a third. Each agent is right in its own repo and wrong together.
Two things go wrong: the contract between the repos drifts, and the merge order matters. Merge the consumer before the producer and main is broken until the other PR lands.
Plan once, at the architecture level
Write one parent story that describes the whole change — the mission, the new contract, the order — and then one sub-issue per repository, each with its own acceptance criteria. Linear supports exactly this with parent and sub-issues. [4] The parent holds the architecture; each sub-issue is small enough for one agent run. How to write each one is covered in our guide to stories for coding agents.
Expand, migrate, contract
The safest way to change an interface that several repos depend on is an old one. Martin Fowler calls it parallel change:
"Parallel change, also known as expand and contract, is a pattern to implement backward-incompatible changes to an interface in a safe manner, by breaking the change into three distinct phases: expand, migrate, and contract." [1]
Expand
The producer accepts and returns both the old and the new shape.
Migrate
Each consumer moves to the new shape, one repo at a time.
Contract
Once every consumer has moved, remove the old shape.
Every step is deployable on its own. Google's book on large-scale changes makes the same point at a bigger scale: "the largest atomic change possible counterintuitively decreases" as a codebase grows, so big changes get broken into independent pieces. [2]
Encode the order as dependencies
Don't keep the order in your head. In Linear, mark the consumer sub-issue as blocked by the producer sub-issue — blocked issues show up with an orange flag under "Blocked by" in the issue sidebar. [5] The consumer slice doesn't start until the producer slice has merged.
Parent: Show customers' chosen display name everywhere
├─ API-1 Expand: accept + return display_name alongside customer_name
├─ SDK-1 Use display_name in the typed client (blocked by API-1)
├─ WEB-1 Render display_name in account pages (blocked by SDK-1)
└─ API-2 Contract: remove customer_name (blocked by WEB-1)Blocked-by means merged — so make sure merging the producer also deploys or publishes it (for an SDK, a released version) before the consumer slice depends on it. If your deploys don't happen on merge, add a release step to the producer's story.
Read top to bottom, that's both the plan and the merge order — and every line leaves main deployable. It's the same idea as merging parallel work one branch at a time, which we cover in our guide to parallel coding agents.
Pin the contract
A contract written only in a story can still drift. Pin it in code, so a mismatch fails in CI: a shared typed client generated from one source, an OpenAPI spec both sides validate against, or consumer-driven contract tests. Pact describes the idea: a contract is between a consumer — "a client that wants to receive some data" — and a provider — "an API on a server that provides the data the client needs." [3] The consumer's tests record what it expects; the provider's CI checks it still delivers that.
One agent across repos, or one per repo?
Cursor's Cloud Agents can run in multi-repo environments, where one agent changes several repositories in a single run and opens a pull request in each. [6] When is that the right tool?
One agent across repos
A small, tightly coupled change that's safe to ship together — the same people own every repo and you can deploy them at once.
One agent per repo
A bigger change, different owners, or anything that needs staged deploys. Separate slices with blocked-by order keep each step reviewable and deployable.
Where Aerunit fits
This guide asks for two things: one plan for the whole change, and an explicit order that keeps main deployable. Aerunit does both. Its story writer reads every repository the change touches and proposes a parent issue plus one sub-issue per affected repo, each with scope, acceptance criteria and non-goals.
Aerunit follows Linear's blocks / blocked-by relations, so when the producer slice's PR merges, the sub-issues it was blocking are queued to Cursor Cloud Agents automatically — the next slice starts on top of merged code, without you dispatching by hand.
One plan
A parent issue plus one sub-issue per repo, written from your actual code.
Explicit order
Blocked-by relations make the merge order visible in Linear.
One review per repo
Each slice is its own PR, reviewed against its own sub-issue.
Common questions
Should we move to a monorepo for agents?
Not just for agents. A monorepo lets one change land atomically, but even Google, with one of the largest monorepos, avoids sweeping atomic changes at scale and breaks them into smaller independent pieces. The habits in this guide — plan once, expand-migrate-contract, explicit order — work in either setup. [2]
How do I stop two repos' agents from inventing different field names?
Decide the contract before either agent starts, write it into the parent story, and pin it in code: a shared typed client, an OpenAPI spec, or consumer-driven contract tests. Then a mismatch fails in CI instead of in production. [3]
What if a downstream slice fails after the upstream one merged?
That's the point of expand-migrate-contract: the upstream change accepts both the old and new shape, so nothing is broken while the downstream slice is fixed or retried. Only remove the old shape after every consumer has moved. [1]
