AI coding agents are getting incredibly good at working inside a single repository. They can inspect files, pick up on local conventions, write tests, and churn out solid code.
But let's be real: modern software products are rarely confined to a single repo.
When you're building a new feature, you're usually touching a backend API, a frontend UI, maybe a mobile app, infrastructure, and shared packages. Not to mention updating documentation and analytics events.
This brings up a fascinating new challenge for the era of AI-assisted development: How do we coordinate AI agents when each one is isolated in a different repository?
This article proposes a lightweight pattern to solve this: The Cross-Repo Handoff Protocol—a simple, file-based coordination layer for AI coding agents.
The Problem: Agents in Silos
Imagine you have two AI agents working on a feature. One is building the API, the other is putting together the UI. Without a coordination layer, each agent might solve its local part perfectly, but completely break the end-to-end product flow.
When these agents hit boundaries that depend on contracts, things get messy quickly. Who decides what endpoint the UI should call? What shape should the response take? Are there required fields, or specific error states to handle?
If we don't coordinate them, agents tend to duplicate assumptions, hallucinate API contracts, and miss crucial frontend/backend dependencies. They treat local success ("Hey, my tests passed!") as system success, leaving unresolved questions buried in their isolated conversation histories.
The core issue isn't code generation—it's cross-repo communication.
One option is to open your entire workspace and let a single "god agent" handle everything. For small tweaks, this works fine. But for larger features, the context window gets noisy, responsibilities blur, and the agent starts making wild assumptions across boundaries.
Alternatively, you can run one focused agent per repository. This gives them great focus, but now you're stuck manually playing telephone, copy-pasting context between their chat windows.
The Proposal: A File-Based Message Bus
We need a lightweight pattern. Instead of waiting for complex centralized agent runtimes or full agent-to-agent network protocols, we can use something every agent already understands: files.
The goal is simple: Use the filesystem as the message bus.
This keeps agents independent and repositories decoupled, while making their coordination visible, reviewable, and auditable by humans.
Why Files?
Files are dead simple. They are versionable, diffable, tool-agnostic, and compatible with Git. They're easy for us humans to inspect, and trivial for agents (like Claude Code, Cursor, or Goose) to read and write.
This isn't meant to replace future, sophisticated agent-to-agent protocols. It's a practical pattern that works today with the tools we already have.
The Workspace Layout
The protocol uses a neutral, shared directory outside the individual repositories. Let's look at an example:
platform-workspace/
.ai-workflow/
issues/
TICKET-123/
issue.md
shared-context.md
contract.md
decisions.md
status.md
messages/
handoff/
verification/
product-api/
product-ui/
In this setup:
product-api/is the domain of the API agent.
product-ui/is the domain of the UI agent.
.ai-workflow/is the shared coordination layer.
Agents don't need to touch each other's codebases to talk. The API agent stays in its lane, the UI agent stays in its, and both read/write structured markdown files in the .ai-workflow directory.
The Core Principle: Contracts over Conversations
Agents shouldn't communicate by injecting comments into each other's code. They should use an auditable workflow layer.
We need to enforce explicit boundaries:
Messages are temporary discussions.
Contracts are the source of truth.
Decisions are permanent records.
Handoffs are delivery summaries.
Verification proves the system works.
Why? Because a question isn't a contract. An implementation summary isn't an end-to-end test.
Key Files in the Workflow
issue.md: The original task. Includes acceptance criteria, product context, and affected repos.
shared-context.md: The overarching business goals, user flows, and domain constraints both agents need to know.
contract.md: The agreed-upon cross-repo behavior. Once agreed, this is the source of truth. This prevents an agent from implementing based on a stale assumption. For example:
# Contract: User Display Name
## Endpoint
`GET /api/users/{id}`
## Response shape
{
"id": "string",
"displayName": "string",
"firstName": "string"
}
## Rules
- `displayName` is required.
- If `displayName` is missing, the UI may fallback to `firstName + lastName`.
decisions.md: Permanent records of choices made ("The API will returndisplayNamedirectly").
status.md: Tracks overall progress and blockers.
We also use directories for specific lifecycle stages:
messages/: Asynchronous chat between agents (e.g.,001-api-to-ui-question.md).
handoff/: Summaries of what each agent built, changed files, and local tests run. For example, anapi-handoff.mdwould list exactly what controllers were touched, the tests run, and notes for the UI agent.
verification/: Records of validation (integration checklists, QA notes). It separates "I wrote the code" from "the system works."
The Message Lifecycle
Every message file needs structured metadata so agents know what to do with it. At a minimum, it should include sender, receiver, type, status, and any blocking info.
Example Question (from API to UI):
---
id: 001
issue: TICKET-123
from: api-agent
to: ui-agent
type: question
status: NEEDS_RESPONSE
created_at: 2026-04-30T13:00:00-06:00
blocks:
- api-implementation
---
## Question
Does the UI need this field as `displayName`, or should it compose it from `firstName` and `lastName`?
## Context
The API can support either option, but we need to avoid breaking existing consumers.
Example Answer (from UI to API):
---
id: 002
issue: TICKET-123
from: ui-agent
to: api-agent
type: answer
status: ANSWERED
responds_to: 001
created_at: 2026-04-30T13:15:00-06:00
---
## Answer
The UI prefers receiving `displayName` directly. The UI can keep a fallback using `firstName` and `lastName` for older responses during rollout.
By standardizing message types (hello, question, proposal, decision, blocker, handoff, close), we keep the workflow predictable. An issue cannot be considered complete while any message is still marked OPEN, NEEDS_RESPONSE, or BLOCKED.
Handshakes and Hangups
One of the biggest headaches in multi-agent coding is when one agent thinks the job is done, while the other is still waiting for an answer.
Start with a handshake:
When an agent spins up, it writes a hello message declaring its scope. The API agent explicitly states, "I will only modify product-api and I cannot modify frontend routes."
End with a hangup:
At the end, agents explicitly close their loop. The API agent writes a close message stating its implementation is done, tested, and it has no pending questions. The UI agent replies with a close_ack.
This explicit closure gives human reviewers confidence that both sides reached a natural, synchronized stopping point.
Verification: Trust, but Verify
Local tests aren't the same as cross-repo validation. Just because both repos passed their own tests doesn't mean the feature works.
The verification/ folder is where you ensure the integration checklist is checked off. Are the contracts respected? Do the error fallbacks trigger correctly? Did we actually run an end-to-end test?
Trade-offs: Nothing is Free
Let's be pragmatic—this pattern introduces overhead.
Token usage: If agents blindly read the entire workflow folder instead of just relevant files, token costs will spike.
Noise: Turning every minor clarification into an artifact can clutter the workspace.
Stale State: Ifcontract.mdorstatus.mdaren't updated, agents will hallucinate based on bad data.
False Confidence: Checking a box in a markdown checklist doesn't mean the code actually works.
This protocol is most useful when the cost of a wrong cross-repo assumption is much higher than the cost of writing the handoff files. For tiny, isolated tweaks, it's definitely overkill. A good rule of thumb is to only make agents read what they need (e.g., issue.md, contract.md, and unresolved messages/).
Final Thoughts
As AI coding agents become permanent fixtures in our engineering teams, the bottleneck will shift. It won't just be about generating code faster; it will be about coordinating these agents across repositories, contracts, and delivery phases.
In human teams, we solve this with Jira tickets, design docs, Slack threads, and PR reviews. AI agents need something similar—something explicit, readable by machines, and auditable by humans.
The Cross-Repo Handoff Protocol keeps agents independent and repos decoupled, while turning their coordination into a tangible artifact. Most importantly, it helps prevent local agent success from turning into a system-level failure.
What do you think? Have you run into the multi-agent coordination wall yet? Let's discuss in the comments!
SOCIAL SHARE CARD GENERATOR