DEV Community: binith

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

binith — Sat, 31 Oct 2026 17:04:41 +0000

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:

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.
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:

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.
The Contract CI Hook: If a service PR modifies an API contract, require it to cite an active Story or ADR from team-meta.
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:

Sequence Locked: PAY-217 establishes that billing-service updates its API schema first with amount_cents.
Guardrails Active: ADR-0014 stops the agent from blocking checkout on settlement, queuing the refund asynchronously and showing a pending state instead.
Cross-Repo Visibility: Working from team-meta, the checkout agent reads billing's canonical schema instead of guessing.
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.

Why AI Coding Feels Faster (While Your Sprints Slow Down)

binith — Thu, 22 Oct 2026 21:11:16 +0000

If you work on a mature codebase, you have probably felt the weird disconnect around AI coding tools over the past year. In the moment, sitting in your IDE, you feel noticeably faster. You ask an agent for a new endpoint or a state machine refactor, and 200 lines of clean-looking TypeScript or Java appear in ten seconds.

Then you look at your team's sprint board on Friday. Cycle times haven't moved. Pull request review queues are backed up worse than before, and subtle regression bugs keep slipping into staging.

In a landmark randomized controlled trial conducted by METR (Model Evaluation & Threat Research), researchers put a stopwatch on experienced open-source developers working across mature codebases. Before starting, developers predicted that frontier AI tools would speed them up by 24%. Even after completing the tasks, they believed they had moved 20% faster.

When researchers checked the stopwatch, tasks done with AI took 19% longer than tasks done without it.

While tooling and base models have improved since that initial trial, newer industry data from DORA and developer productivity studies confirms that the core paradox has only intensified: teams are generating 30% to 40% more pull requests, but PR review turnaround times have doubled, and change failure rates remain elevated.

Writing syntax was never the real bottleneck in software engineering. When we prompt an LLM in an ungrounded chat window, we save twenty minutes of typing and spend the next two hours untangling hallucinated contracts, reviewing plausible-looking edge-case failures, and playing detective in integration tests.

To turn AI from a noisy typing assistant into a dependable team multiplier, we have to confront an uncomfortable truth about a rule most of us have treated as sacred for twenty-five years.

1. The 180-Degree Inversion: When Code Becomes a Cheap Commodity

For twenty-five years, software engineering culture has been anchored to one foundational line from the 2001 Agile Manifesto:

"Working software over comprehensive documentation."

Every developer, tech lead, and engineering manager has had this mantra drilled into their instincts: Code is reality. Writing documentation is waste. If it isn't running in production, it doesn't matter.

In 2001, that was pure economic sanity. Human keystrokes were the scarcest resource on a software team. Translating business requirements into working C++ or Java took weeks of manual labor, while 50-page Word documents rotted the afternoon the first production patch was deployed. The source code was the only truth you could afford to trust.

With AI agents, that economic reality has flipped 180 degrees.

Today, syntax generation is practically free. An agent will happily emit 500 lines of syntactically valid code in thirty seconds for pennies.

What is scarce and expensive now is unambiguous intent, domain invariants, and cross-service alignment. When an agent breaks a downstream service, it rarely fails because the model forgot how to write a loop. It fails because the edge cases, business rules, and contract boundaries lived inside someone's head, an informal Slack message, or a vague two-sentence Jira ticket.

Here is the radical shift most teams haven't internalized yet: application code is still something you commit and maintain, but it is no longer where primary intent lives. Code is now a generated artifact; the living specification is the actual source of truth.

Dimension	Traditional Agile	Spec-Driven AI Agile
Primary Asset	Application source code	Living specs, schemas, invariants
Application Code	Hand-crafted artifact	Verified compilation target
Team Bottleneck	Typing, syntax, boilerplate	Spec precision, contract boundaries
User Story	Advisory conversation starter	Authoritative contract (`Given/When/Then`)
When Code Fails	Patch code manually	Fix spec or harness rules and re-run

The Limits of the Compiler Analogy (Why Prompts Aren't Deterministic)

It is tempting to look at this table and say: "Great, so the LLM is just a C compiler."

Every experienced engineer knows the catch: compilers are deterministic, but AI models roll dice. If you feed the exact same C source into gcc twice, you get the exact same binary. But if you give an AI agent the exact same prompt twice, you might get a clean, idiomatic implementation at 10 AM, and an unhandled null pointer or hallucinated dependency at 2 PM.

You cannot treat code as disposable bytecode when you still have to wake up and support it in production at 3 AM.

This non-determinism is precisely why you cannot rely on casual chat prompting. Because the model is probabilistic, you must bound it on both sides. The living specification locks down the intent before the model acts, and deterministic automated verification bounds what is acceptable after it acts.

Tight specifications narrow the model's solution space, while automated verification enforces correctness. That combination is what finally earns trust from the skeptics on your team.

2. Beyond Chat: Demystifying the Harness Rig

When teams first encounter problems with AI code quality, the initial reaction is usually to tweak the prompt: "Be careful with error handling," or "Write production-grade clean code." When that fails, people dump whole folders into massive context windows, only to discover that flooding a model with hundreds of files causes severe distraction and makes the agent miss subtle constraints.

The solution is not more clever chat prompting. It is understanding the core systems formula formalized by Thoughtworks Distinguished Engineer Birgitta Böckeler:

Agent = Model + Harness

The model is the reasoning engine you rent from an AI lab. The Harness Rig is the operational environment your team builds around that model.

In practice, a harness is not just a test runner. A complete harness rig consists of three distinct pillars working together:

The Context Lake (What the agent knows): Despite the grand name, a team Context Lake does not require an enterprise vector database. It is simply your Git-tracked repository of truth (repo map, API schemas, and active feature specs) fed to the model just-in-time rather than dumped in a prompt.
The Way of Working (How the agent behaves): The team's conventions, tool access, allowed libraries, and operational boundaries (what the agent can do autonomously vs. when it must ask a human).
The Verification Rig (How the agent proves correctness): The deterministic compiler checks, linters, and test suites that inspect the output and feed errors back to the model for self-correction.

flowchart TD
    A["Context Lake<br/>AGENTS.md, schemas, living story spec"] -->|"just-in-time context"| B["Coding Agent"]
    B -->|"proposed diff"| C{"Harness Rig: verify.sh<br/>tests, linters, boundary checks"}
    C -->|"fail: stderr fed back"| B
    C -->|"pass"| D["Human review<br/>PR + spec"]

The Two Levels of Intent You Actually Need

Most developers reading about harnesses think: "We don't have custom harness infrastructure. We barely have a generic AGENTS.md file that Cursor or Claude Code generated for us."

You don't need complex internal platforms to start. To get dependable, repeatable output from an agent, you only need to provide two living files:

Repo-Level Intent (AGENTS.md): This is your team's Way of Working. It doesn't need to be a 1,000-page manual. It simply defines your stack conventions, architectural boundaries (which services can talk to which databases), forbidden dependencies, and how to run tests. It acts as the agent's institutional memory.
Feature-Level Intent (The Story Spec): This is the contract for the task. It lives in the repository alongside the code, capturing exact endpoints, request/response payloads, and acceptance criteria in unambiguous Given/When/Then terms.

Without written repo intent, every agent session starts like an intern who was hired five minutes ago and never read your codebase. Without written feature intent, the agent is forced to guess your business logic. Providing both is the absolute minimum requirement for consistent AI delivery.

3. Shift-Left Refinement Without Falling Into Waterfall

Whenever you tell experienced engineers that specifications must become the primary source artifact, a red flag immediately goes up:

"Wait. Isn't writing detailed specifications before coding just 1990s Big Design Up Front (Waterfall) dressed up in Markdown?"

This is a valid danger. If a team tries to write 50-page markdown documents for an entire quarter upfront, the LLM will miss half the requirements, and engineers will spend their lives maintaining stale prose.

The difference between modern Spec-Driven Agile and 1990s Waterfall comes down to batch size and collaborative refinement:

Tiny Batch Size: Waterfall attempted to freeze six months of requirements across an entire release. Spec-Driven Agile bounds the batch size to a single vertical user story (one or two days of execution), demanding crisp completeness on that slice alone before implementation begins.
The "Four Amigos": In traditional Scrum, refinement often rushes through tickets, slapping points on a two-sentence Jira description because "we'll figure out the details when we start coding." But feeding a two-sentence ticket to an AI agent guarantees hallucinated code. High-leverage squads bring the agent into backlog refinement as the 4th Amigo alongside Product, Dev, and QA.

In refinement, the agent is strictly forbidden from writing implementation code. Instead, it inspects the draft ticket against the Context Lake to surface missing contracts and hidden assumptions:

"This ticket introduces a partial refund, but billing-service OpenAPI v2 only defines full-void webhooks. Which service versions its schema first?"
"What is the fallback behavior if the payment gateway times out after 5,000ms?"

The Pragmatic Jira Bridge

Pushing detailed specifications into Git introduces an immediate cultural challenge: Product Managers and Scrum Masters live in Jira, and they will not review Git pull requests.

Expecting non-engineers to maintain Markdown in Git causes process deadlock. Leaving specifications solely in unstructured Jira descriptions blinds your agents. Practical squads bridge this with a clear split:

Developers maintain the technical spec in Git: During refinement or upon starting a ticket, the developer pairs with the agent to produce the authoritative technical story specification in Git (covering touched repos, contract changes, edge cases, and verification commands).
Sync a crisp summary to Jira: Once the spec is committed in Git, a short, readable summary is synced back into the Jira ticket (linked directly to the Git spec file). Product managers and stakeholders track status and acceptance criteria on their familiar boards, while the agent executes against the version-controlled specification.

4. Monorepo Assumption vs. Multi-Repo Reality

Flipping our focus from raw chat prompting to a Git-backed Context Lake, a deterministic Harness Rig, and shift-left story specs provides a predictable foundation for AI development.

Until you try to implement it across your real architecture.

Nearly every tutorial, benchmark, and demo on AGENTS.md and Spec-Driven Development quietly assumes your entire company lives inside a single monorepo. They show an agent running in one root folder, inspecting one directory tree, and executing one test command.

In practice, a vast majority of enterprise teams operate across multi-repo (polyrepo) architectures. A single business feature frequently cuts across a frontend repo, multiple backend microservices, and shared infrastructure definitions—each with its own repository, permissions, and CI pipeline.

When your system spans multiple repositories, where does your Context Lake live? Where do you store cross-repo story specs? And how do you give an agent coherent context across repositories without embarking on a painful monorepo migration?

In Part 2, we will break down the lightweight architecture that solves this: the Sibling Meta-Repo (../team-meta) paired with multi-directory workspace mounting (/add-dir).