The Human Mediator: Coordinating Two AI Coding Agents Without Chaos

The Core Problem in Plain Terms

When you split a project between two AI coding agents — say, one handling the server and one handling the client — you immediately hit a wall: they cannot talk to each other. They have no shared memory. They cannot read each other's context. If you just let them both run and hope they stay in sync, they will diverge. One will assume the API looks one way; the other will assume something different. By the time you try to integrate, you're reconciling hours of contradictory work.

The naive fix is to paste context from one agent into the other. That works for small things, but it doesn't scale — you forget to relay something, you paraphrase wrong, or one agent's session gets too long and loses track of what the other side agreed to.

There's a better way, borrowed from software design: the Mediator Pattern.

What the Mediator Pattern Is (The Short Version)

In software, the mediator pattern solves the problem of objects that all need to communicate with each other. Instead of every object talking directly to every other object (chaotic), you route all communication through one central coordinator — the mediator. Nobody talks to each other directly. Everyone just talks to the mediator.

Applied to two AI agents, it maps perfectly:

The agents don't know about each other. They only know you. You are the communication channel, the memory, and the gatekeeper.

This isn't a limitation — it's the design. It's what makes the whole thing work.

Why This Is Worth Doing

Here's what you get from running this pattern seriously:

No context drift. Each agent stays laser-focused on its own codebase. The server agent doesn't need to understand the client's SQLite schema. The client agent doesn't need to know the server's EF Core migration strategy. Confusion only happens when agents are asked to reason about things outside their lane.

Built-in code review. Every time work crosses from one agent to the other, you — the mediator — review it first. Because each task is small and bounded, reviews take minutes rather than hours. You catch bad assumptions before they become load-bearing.

A permanent audit trail. The shared handoff document records every decision, every commit hash, every test count. Weeks later when something breaks, you can find exactly which task introduced it and why the decision was made.

Real verification, not vibes. Neither agent can say "it's done" with a vague reassurance. The commit hash either exists or it doesn't. The tests either pass or they don't. You can verify in seconds.

The Three Things You Need

1. Two Separate Agent Sessions

These should be genuinely isolated — different terminal windows, different chat sessions, different machines if possible. The whole point is that they don't share context.

Important: At the start, tell each agent which machine it is. If you don't, it won't know which role to adopt and the process will stall before it begins.

"You are the server agent (Machine A). I am the human mediator. You will receive tasks via a handoff document and report back to me when complete."

2. A Shared Handoff Document

This is a markdown file committed to your shared Git repository. It's the only thing both agents can "see" — not simultaneously, but sequentially. It has three zones:

Zone 1 — Architecture Decisions (never changes)

Written once at the start. Contains everything both sides must agree on: API contract shape, auth strategy, endpoint URL patterns, envelope formats. Any agent starting fresh reads this section first.

## Architecture Decisions (Carry Forward)

- Auth: Bearer tokens on all sync endpoints via [Authorize]
- API contract: All endpoints use GetAuthenticatedCaller().
  All responses wrapped by ResponseEnvelopeMiddleware.
  Client unwraps via ReadEnvelopeDataAsync().
- Sync flow: changes → tree → reconcile → chunk manifest → download → assembly

These are not suggestions — they're the contract. When one side needs to change something here, it updates this section first, and you relay the change to the other agent before any new work starts.

Zone 2 — Active Handoff (one task at a time)

One open task at a time. Contains: what was just built (in enough detail to verify), what the receiving agent needs to do, and what it must report back.

## Active Handoff

### Issue #12: Streaming Upload Pipeline — Client only

**Server status:** ✅ COMPLETE — commit `4570c16`
**Client status:** 🔲 IN PROGRESS

**What server implemented:**
Bounded-channel producer/consumer pipeline. Chunks uploaded in 512KB segments.
Endpoint: POST /api/sync/upload-chunk. Returns { success: true, chunkId }.

**What client needs to do:**
Implement the upload side of the pipeline using the above endpoint.
Use channel-based buffering (not in-memory accumulation).

**Request back from client:**
- Commit hash
- Build: 0 errors
- Test count (was 66, should increase by ≥2)
- Confirm: channel-based buffering in use (not MemoryStream accumulation)

**Mediator review notes:**

Zone 3 — Resolved Issues (never delete)

Completed tasks stay here forever. They form your audit trail. When a bug appears weeks later, this section tells you exactly which commit introduced what, what the test count was, and any review notes from the time.

3. Your Relay Discipline

This is the hardest part, because it requires you to resist the urge to be helpful in ways that break the system.

Your Job as Mediator (And What It Is Not)

Your job is relay, review, and gate-keep. That's it.

Relay means forwarding the completing agent's output to the waiting agent, accurately and completely. Not summarized. Not improved. If the server agent says "build: 0 errors, 304 tests, commit 4570c16" — that exact string goes to the client agent's context.

Review means reading the diff before you forward anything. With small, bounded tasks this takes minutes. You're checking: does what the agent says it did match what it actually did? Do the test counts add up? Did it drift from the architecture decisions?

Gate-keep means not moving forward until outputs are verified. If the test count dropped, you don't forward the handoff — you send the finding back to the completing agent and ask for a fix.

What you do NOT do:

• Generate code yourself (relay the agent's instruction intact; don't paraphrase it)
• Resolve disagreements between agents (surface the conflict, relay both positions, let them reach explicit consensus recorded in the document)
• Hold important state in your head (if it matters beyond this session, it goes in the document)
• Pass complex messages verbally — any complex information must go into the handoff document, not into your chat message to the agent. Your messages to agents should be short: "There's a new handoff ready for you to pull."

Keeping the Agents on Track: The Moderator Problem

Here's something you'll encounter early and often: agents will try to make you do more than you should.

An agent may ask you to describe something complex, make a decision, or pass detailed information verbally. Gently redirect them every time.

Prompts that work when an agent starts treating you as more than a moderator:

"As moderator, I only pass short messages between agents — like 'there's a new handoff ready for you.' Complex messages go in the handoff document. I don't pass complex messages verbally."

"I'm only the moderator. You do what you need to do and then tell me what action I should take."

This isn't just about keeping your workload manageable — it's structurally important. If you start relaying complex information verbally, you introduce the same drift and loss problems the pattern exists to prevent.

They will figure it out. Once an agent has been corrected once or twice, it usually adapts and starts treating you as the narrow relay channel you're supposed to be. Be consistent about it early.

Practical Tips From Real Usage

Start a fresh session (or /COMPACT) after each handoff.
Context windows accumulate noise. After a task completes and the handoff is forwarded, either start a new chat session with the receiving agent or use /COMPACT before continuing. This keeps each agent's context clean and prevents old information from creating confusion.

Watch the size of your handoff document.
The handoff doc will grow. Once it gets large, agents start struggling to process it efficiently. Have the agent create an archive document and move completed resolved issues there. The archive can be referenced by name when needed (e.g., "see HANDOFF_ARCHIVE.md for prior decisions on the auth flow").

A good practice: instruct each agent to check the document size and archive completed tasks at the beginning of each new handoff. Make this an explicit step in your process rules section.

## Process Rules
- At the start of each handoff, check document length.
  If Resolved Issues section exceeds ~50 entries, archive oldest entries to HANDOFF_ARCHIVE.md.
- All technical findings go in this document, pushed to main before any handoff.
- Mediator is relay-only. Complex messages go in the document, not in chat.
- Blocking review findings must be resolved before the next task starts.

Tell the agents which machine they are at the start.
Agents don't have inherent identity. If you open a fresh session and just start describing the project, the agent won't know whether it's Agent A or Agent B. The first thing you say to a new session should establish its role:

"You are the client agent (Machine B) on this project. Pull the handoff document from the repo and read it to orient yourself. I'll let you know when you have an active task."

Task Sequencing: Parallel vs. Sequential

Not every task needs to wait for the other side. Being clear about dependencies saves a lot of unnecessary blocking:

Sequential (one agent must finish first): When Agent B needs something Agent A produces — an API endpoint, a data format, a contract update — Agent A goes first, you review and verify, then Agent B starts. The handoff document is the gate.

Independent (either agent can work freely): When a task is entirely within one side's codebase and doesn't touch the integration boundary, it can be labeled "Server only" or "Client only" and completed without involving the other agent at all. You still log it as complete in the document, but you don't relay anything.

Batched (natural checkpoints): Group related tasks into numbered batches. All of Batch 1 completes before Batch 2 starts. This gives you predictable review points and prevents one agent from racing so far ahead that the other can't integrate.

Validation: No Vague "It Works"

Before any task is considered complete, the agent must provide specific, verifiable outputs defined before the work starts — not after:

• Build result (exact error count, not "it compiled")
• Test count before and after (the delta confirms new tests were actually added)
• Specific test names for the new functionality
• Environment confirmation (which machine ran the tests)

The mediator's job at validation time: do the numbers match what was pre-agreed? If the agent reports 64 tests when the validated count was 66, that discrepancy gets flagged before anything moves forward.

What to Look For During Handoff Review

When a task completes, you have four things in front of you simultaneously:

1. The pre-agreed spec (what the task said to do)
2. The agent's completion report (what it says it did)
3. The actual diff (git show or a Git client)
4. The test results

The review question is simple: do these four things agree?

Common things to catch:

• Scope creep — agent modified files outside the listed scope
• Missing tests — delta is lower than expected, or test names don't match the feature
• Hardcoded assumptions — specific values that should be configurable, or assumptions about the other agent's interface that were never agreed
• New dependencies — a package added that wasn't discussed and might conflict
• Architecture drift — agent used a different auth pattern, envelope format, or URL structure than what's in the Architecture Decisions section

Classify findings as blocking or non-blocking:

Non-blocking: Record in the handoff doc under the completed issue. Don't stop the next task. Examples: unclear variable name, log message at wrong severity.

Blocking: The completing agent must fix before the handoff proceeds. Examples: test that passes for wrong reasons, endpoint that ignores the integration contract. Resolve blocking findings in the same session where they're found. Carrying them forward means the other agent builds on a broken foundation.

The Minimal Starting Template

Copy this into a file called HANDOFF.md in your repo root and commit it before you start:

# Handoff Document

## Architecture Decisions (Carry Forward)



## Process Rules
- At the start of each handoff, check document length.
  If Resolved Issues exceeds ~50 entries, archive oldest to HANDOFF_ARCHIVE.md.
- All findings go in this document, pushed to main before any handoff.
- Mediator is relay-only. Complex messages go in the document, not in chat.
- Mediator reviews each task diff before forwarding.
- Blocking findings must be resolved before the next task starts.

## Relay Template
### Send to [Agent A | Agent B]


### Request Back
- [ ] Commit hash
- [ ] Build: 0 errors
- [ ] Test count (was X, should be ≥ Y)
- [ ] [Any specific verification for this task]

## Active Handoff
### Issue #N: [Task Name] — [Agent A | Agent B | Both]

**Agent A status:** [not applicable | 🔲 IN PROGRESS | ✅ COMPLETE — commit `abc1234`]
**Agent B status:** [not applicable | 🔲 IN PROGRESS | ✅ COMPLETE — commit `def5678`]

**What was implemented:**


**What [Agent A | B] needs to do:**


**Request back:**
- Commit hash
- Build: 0 errors
- Test count (was X)
- [Task-specific verification]

**Mediator review notes:**


## Resolved Issues

Using AI to Generate Your Initial HANDOFF.md

The hardest part of the handoff document isn't the template — it's filling in the Architecture Decisions section correctly. That section needs to capture everything both agents must agree on before a single line of code is written: the API contract shape, auth strategy, envelope formats, URL conventions, and anything else that crosses the boundary between the two sides.

You don't have to write this from scratch. Use a third AI session — separate from both agents — as a planning assistant to draft it.

What to give it:

• A description of the project and what you're building
• Which parts belong to which agent (server vs. client, or whatever your split is)
• Any existing documentation, architecture notes, or planning docs you already have
• The template from this article

Then ask it something like:

"Based on this project description, draft the Architecture Decisions section for a HANDOFF.md file. Focus on everything that crosses the boundary between the server and client agents — API contracts, auth strategy, data formats, URL patterns, and any conventions both sides must follow. Also draft an initial task list broken into batches, with each task labeled as 'Server only', 'Client only', or 'Both'."

What you get back:

A draft Architecture Decisions section grounded in your actual project, and an initial task sequence you can load directly into the Active Handoff section. You'll likely need to edit it — the AI won't know every constraint — but it's far faster than writing it cold, and the process of reviewing and correcting the draft forces you to think through the integration boundary before the agents start working.

Validate it before you commit it. Read through the generated architecture decisions and ask yourself: if both agents followed these rules exactly, would their outputs be compatible? Look specifically for anything that would require one side to assume something the other side hasn't agreed to.

Once you're satisfied, commit HANDOFF.md and that becomes the single source of truth both agents orient from.

Starting Your First Session

1. Create and commit HANDOFF.md with your architecture decisions filled in.
2. Open Agent A's session. Tell it: "You are the server agent (Agent A). Pull HANDOFF.md from the repo and read the architecture decisions. Your first task is [Task 1]."
3. Agent A works. When done, it reports back to you with commit hash, build result, test count.
4. You review the diff. You fill in Mediator review notes in the document and commit it.
5. Open Agent B's session. Tell it: "You are the client agent (Agent B). Pull HANDOFF.md and read it. There's an active handoff for you."
6. Agent B works. Reports back. You review.
7. Move the completed issue to Resolved. Write the next Active Handoff entry. Commit. Repeat.

Start with one sequential task. Add parallel tracks only after you've run through the relay protocol two or three times and it's working cleanly.

Summary

The Human Mediator pattern gives two AI agents a way to collaborate on a shared codebase without ever directly communicating — because they can't. You become the communication channel, but a structured one: relay-only, with a shared document as persistent memory, validation gates before every handoff, and code review baked into the process at every boundary crossing.

The result is a codebase that gets reviewed and understood incrementally — one small, bounded task at a time — rather than a pile of integrated work that nobody fully reviewed until the end.

Your role is not to write code or make architectural decisions mid-stream. Your role is to route information with precision, catch problems while they're still cheap to fix, and keep the two agents from ever having to know anything about each other beyond what you deliberately choose to tell them.