Guide · Cross-repo changes

One change, many repos, no broken main

Most real features cross service boundaries. A single agent sees one slice; the hard part is planning the whole change and merging the slices in an order where every repo stays deployable at every step.

Mio Nilsson, creator of AerunitBy · Last updated

A single beam of cyan light passing through a row of glowing crystal towers
The problem

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

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.

Stay deployable

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]

Make it explicit

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.

Example: rename customer_name → display_name
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.

Catch it in CI

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.

A choice

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 we come in

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.

Quick answers

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]

Aerunit

Keep the agents busy. You do the thinking.

Sign-up is open — create an account and start with pay-as-you-go credits. No subscriptions, and teams share one credit pool at no extra cost.

Create account