How to Use AI Coding Agents Across Multiple Repositories (Without a Monorepo Migration)

In Part 1, we saw that code generation is cheap, while clear intent and contract boundaries are the scarce bottleneck. We concluded with a clean principle: store the living story spec in the repository alongside the code.

Then Monday morning arrives, and you pick up your next ticket: partial refunds.

It touches two repositories: web-checkout (React) and billing-service (Go). Real features often touch more, but two are enough to show the problem.

Which repository does the specification live in?

If you put the spec in web-checkout, the backend engineer in billing-service never sees it. If you put it in billing-service, the frontend agent in web-checkout invents its own expectations:

• The agent in web-checkout invents a JSON field named refund.partialAmount.
• An agent in billing-service names the incoming field amount_cents.
• Both developers run local tests. Both suites pass. Both PRs merge.
• Staging deploys, and checkout fails on an unhandled contract mismatch.

Both agents followed instructions inside their silos. Lacking cross-repo visibility, they compiled ambiguity into production bugs.

Nearly every tutorial on AGENTS.md and Spec-Driven Development assumes your company lives in a single monorepo. But if your team operates across multiple repositories, you need cross-service context without a multi-year migration.

The answer is the Sibling Meta-Repo.

---

1. Where Does the Context Lake Live? The team-meta Pattern

Create a lightweight Git repository checked out as a sibling directory alongside your squad's service repositories.

It acts as the squad's shared memory, holding cross-service feature specs and Architecture Decision Records (ADRs).

Before AI, the reasons behind past architectural choices—why checkout never calls the payment gateway synchronously, or why billing owns currency conversion—mostly lived inside a few senior developers' heads (and even the rest of the team rarely knew all of them). In AI-driven development, that same gap hits even harder because every agent session starts with a blank slate. ADRs are the alternative to relying on people's brains—capturing those decisions and trade-offs in a short, structured format that is far more reliable for humans and AI agents alike:

~/work/payments-squad/
├── team-meta/                         # <-- Squad Brain (Context Lake + Harness)
│   ├── AGENTS.md                      # Topology, blast radius, contract rules
│   ├── repos.yaml                     # Registry of sibling service repos
│   ├── decisions/                     # Cross-repo ADRs (Architecture Decision Records)
│   │   └── ADR-0014-async-partial-refunds.md
│   └── planning/
│       ├── pi-current/                # (Optional: SAFe / multi-squad objectives)
│       ├── epics/
│       │   ├── EPIC-104-partial-refunds/
│       │   │   ├── epic.md                         # Goal, scope & dataflow
│       │   │   ├── PAY-217-partial-refunds.md      # Story 1: Request & pending UI
│       │   │   └── PAY-218-refund-status-webhook.md # Story 2: Async settlement update
│       │   └── EPIC-105-saved-payment-methods/
│       │       ├── epic.md
│       │       ├── PAY-224-card-tokenization.md
│       │       └── PAY-225-one-click-checkout.md
│       └── archive/                   # Compacted prior completed epics
├── web-checkout/                      # Sibling 1 (React — has local AGENTS.md)
├── billing-service/                   # Sibling 2 (Go — has local AGENTS.md)
└── other-services/                    # More siblings, same layout

The Two Dimensions team-meta Solves

team-meta solves two problems that single-repo chat tools ignore:

1. The Spatial Dimension (The "Where"): Giving the Context Lake and Harness a physical home. Sibling repos hold the code, while team-meta holds cross-repo ADRs, blast-radius rules, and shared specs.
2. The Temporal Dimension (The "When"): Coordinating agents across time. Complex features are not built in 10-minute chat turns. team-meta connects the multi-week plan in planning/epics/ to 1-to-2 day slices like PAY-217, so an agent picking up frontend work on Tuesday respects the backend contract decided on Monday.

The sibling meta-repo lifts Part 1's three harness pillars to the cross-repo boundary:

Harness Pillar	Repo-Local (billing-service)	Cross-Repo (team-meta)
Context Lake	Local modules, stack dependencies, owned API schema	Squad topology map, service ownership, cross-repo ADRs
Way of Working	Local linting, test runners, code formatting	Multi-repo change sequence, contract-first rule
Verification Rig	Local unit and integration tests	Cross-repo contract checks across sibling checkouts

The Layering Rule

• Repo-level AGENTS.md defines how to build, lint, and test that specific stack.
• team-meta/AGENTS.md defines how services collaborate: service ownership, change sequence, and blast-radius rules.

A small registry, repos.yaml, lists the sibling repositories so developers and CI work from the same layout.

---

2. Where Do Cross-Repo Specs & ADRs Go?

A. Epics, Stories, and Contract Ownership

An Epic is a directory. Its epic.md holds the overall goal and system flow, and each story nested underneath is a 1-to-2 day slice that names the repositories it touches and the order they change in. (If your organization uses SAFe, planning/pi-current/ tracks cross-squad dependencies; under Scrum or Kanban, omit it.)

# PAY-217: Partial Refunds
Repos: `billing-service`, `web-checkout`

### Change Order
1. `billing-service`: Add `POST /v2/refunds` endpoint and update API schema.
2. `web-checkout`: Add the amount input; call the new endpoint.

### Acceptance Criteria
- [ ] Accepts `{ "order_id": string, "amount_cents": int }`.
- [ ] Returns an asynchronous pending status with a refund tracking ID.
- [ ] Checkout shows a pending state and never waits for settlement.

Keep Code and API Schemas in the Service Repos

Do not copy code or API schemas into team-meta. Maintaining duplicate schemas creates two sources of truth and guarantees drift.

Instead, each service repository stays the single source of truth for its own API definition. The story spec in team-meta simply states what is changing and which repository changes first, while the actual code and schema changes happen inside billing-service and web-checkout.

B. Cross-Repo ADRs in Practice: Negative Constraints

Consider a rule that usually lives in team folklore:

"Never make checkout wait for a refund to finish processing. External payment gateways can be slow under peak load, so refunds must run asynchronously."

Without that context, an AI agent asked to add partial refunds will write the obvious synchronous version: checkout calls billing, billing calls the gateway, and checkout waits for the answer. Local mocks respond instantly, so tests pass. In production, a slow gateway stalls the storefront.

This is why ADRs belong in team-meta/decisions/.

Alongside the usual context and decision, include the section that matters most for AI agents, Rejected Alternatives:

# ADR-0014: Asynchronous Partial Refunds
Status: Accepted

Context: External payment gateways can respond slowly during peak sales events.
Decision: `billing-service` queues the refund and returns a pending status
at once. `web-checkout` shows a pending state.
Consequences: Refunds settle asynchronously; customers see the result later.

Rejected Alternatives:
- Waiting synchronously for settlement inside the checkout request was
  EXPLICITLY REJECTED, as slow gateway responses block the checkout flow.

ADR-0014 gives the agent an explicit negative constraint: it knows what not to build before it writes code.

---

3. Coherent Agent Context Without a Monorepo

There are two ways to work with team-meta, depending on the task.

Cross-Repo Work: Start in team-meta

When planning or building a feature that spans multiple services, start in team-meta with the sibling checkouts attached to your workspace. The agent reads the shared story spec and ADRs first, then follows team-meta/AGENTS.md to inspect the local rules of each repository listed on the story.

Single-Repo Work: Attach team-meta on Demand

Most daily work in a service repo—bug fixes, local refactors, UI tweaks—is standalone and needs no cross-repo context. Preloading team-meta on every session wastes context window space.

When a single-repo task touches a shared API boundary, stay in your service repository and attach ../team-meta on demand (for example, by adding the folder to your IDE workspace or running /add-dir ../team-meta in a CLI agent). Then point the agent at the specific spec or ADR it should read.

---

4. "Why Not Just...?" The Alternatives Table

Approach	Setup Cost	Reversibility	Agent Sees Cross-Repo Intent?	Drift Risk
Monorepo Migration	Very High (months/years)	Low (hard to reverse)	Yes	Low
Git Submodules	Medium (complex UX)	Medium	Partially (code yes, intent no)	High (detached HEADs)
Custom MCP Server Mesh	Medium to High	High	Only what MCP tools expose	Medium
Sibling Meta-Repo (team-meta)	Low (single git init)	High (non-invasive)	Yes (ADRs, specs, and sibling paths)	Low (once the contract gate runs in CI)

Steelmanning the Monorepo Migration

If your organization can migrate to a unified monorepo, evaluate it. Teams at Google and Meta benefit from atomic commits and single-root navigation. But most enterprise teams cannot migrate this quarter. team-meta delivers cross-repo context today without touching build systems.

MCP earns its place for external systems like Jira and Sentry. For files already on disk, a local checkout is faster, with no network hop and no extra tool schemas.

Most importantly, unlike the other alternatives in the table, this pattern requires zero permission to try. Because team-meta sits outside your service repositories, any developer on the team can create it locally, experiment on a single cross-repo ticket without altering a single file or CI pipeline in the existing project repos, and onboard the rest of the squad once the results speak for themselves.

---

5. Keeping the Meta-Repo Alive (Anti-Rot)

Three practices prevent team-meta from decaying:

1. Documentation as Post-Mortem: When an agent produces hallucinated code, commit a 5-line PR to team-meta/decisions/ or team-meta/AGENTS.md so future agents do not repeat it.
2. The Contract CI Hook: If a service PR modifies an API contract, require it to cite an active Story or ADR from team-meta.
3. Sprint Compaction: Archive completed stories at iteration boundaries.

---

6. Full Circle: How the Partial Refund Lands

Revisit the opening failure: two agents inventing conflicting fields (refund.partialAmount vs. amount_cents), passing local tests, and breaking staging.

With team-meta, that failure disappears:

1. Sequence Locked: PAY-217 establishes that billing-service updates its API schema first with amount_cents.
2. Guardrails Active: ADR-0014 stops the agent from blocking checkout on settlement, queuing the refund asynchronously and showing a pending state instead.
3. Cross-Repo Visibility: Working from team-meta, the checkout agent reads billing's canonical schema instead of guessing.
4. Pre-PR Gating: Cross-repo contract checks catch breaking changes before a pull request opens.

Ambiguity was resolved in team-meta before the model generated a single line of code.

---

7. The Bottom Line: Moving Beyond the Autocomplete Era

This way of working is not free. Crisp specs, cross-repo ADRs, and a curated meta-repo take real discipline.

If your team only uses AI as a micro-level typing assistant for a regex or test boilerplate, your existing workflow is fine. You do not need a meta-repo for autocomplete.

The danger is the middle ground: attempting to use AI agents on multi-repo features while keeping your old, casual workflow.

Without a version-controlled Context Lake and verification harness, teams feel faster while cycle times degrade: models generate plausible architectural debt, and senior engineers spend their afternoons untangling broken contracts in review queues.

Teams face a bimodal choice: keep AI as an individual micro-helper, or make the structural investment to work AI-native at the system level. Half-measures accelerate code generation while crippling delivery.

For the vast majority of enterprise teams working across multiple repositories without a Big Tech monorepo, a lightweight cross-repo layer like team-meta is not just useful—it is essential once you move beyond autocomplete. And because it sits entirely outside your existing repositories, any developer can try it out on their next feature without disturbing the existing way of working in other repos.

By anchoring your squad's context, ADRs, and contracts in a sibling meta-repo, you give AI agents the one thing they cannot hallucinate on their own: the collective architectural memory of your team.