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. This adapts that pattern to be the Human Mediator Pattern. (20260312 - Ben P Kimball)

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 local storage schema. The client agent doesn't need to know the server's database 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 except via the handoff doc and the repo. It can be a shared repo clearly broken into server vs client(s), or separate repos that they need to be aware of, even if one agent only has read access to repos that do not belong to it's work scope. They seem really good at respecting repo boundaries - I've done all this with a single repo and have only had to call an agent out for boundary crossing once. (I'm actually surprised by that - of all the surprising things I've seen them do, this is a separation they seem to have no issue with.)

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. After months of running this pattern on a real project, I've found the document works best with these zones:

Zone 1 — Process Rules (the operating contract)

This section defines how the agents work, not what they build. It's where you encode the lessons you've learned about what goes wrong and the gates that prevent it. The critical insight after real usage: agents must be autonomous. They don't ask the moderator for context or permission. They pull main, read the handoff, and execute.

Here's what a battle-tested process rules section looks like:

## Process Rules

**Agent autonomy (CRITICAL):**
- Both agents work autonomously — they do NOT ask the moderator
  for context or permission during a task.
- Agents pull the latest `main`, read the Active Handoff section,
  and execute the work described there independently.
- All actionable items, blockers, and technical details go directly
  in this document (committed to `main`).
- Do not stall waiting for moderator approval mid-task. Complete
  the work, commit, push, and update this document. The moderator
  reviews between handoffs and will send work back if needed.

**Handoff management:**
- Put all technical findings, debugging conclusions, and next-step
  details in this document.
- Agent commits their findings and updates the Active Handoff section
  with actionable next steps for the other side.
- Agent pushes commits to `main`.

**Mandatory gates:**
- Untracked content rule: remove unexpected untracked files/directories
  before commit; only keep intentional tracked changes.
- Readiness gate: all executable tests must pass before marking
  a handoff as ready.
- Environment-gated tests may be skipped but must be explicitly identified
  with the required environment/runtime prerequisites documented.
- Runtime verification gate: before declaring a server-side blocker fixed,
  verify the running service is on current binaries (not stale publish output)
  and document the verification command/output in handoff notes.
- Secret handling rule: never commit raw bearer tokens or refresh tokens;
  share token acquisition steps and sanitized outputs only.

**Document maintenance:**
- Pre-commit archive rule: before committing this file, move all
  completed/older handoff tasks to an archive document.
- Keep only the single current task in Active Handoff (one active block only).
- If a task is completed, archive it first, then replace Active Handoff
  with the next task.

An important nuance: these rules are written for the agents. They tell the agent "don't stall waiting for me" — but that doesn't mean the moderator is hands-off. Between handoffs, the moderator is absolutely reviewing diffs, making high-level technical decisions (which phase to tackle next, whether to defer or prioritize), and deciding whether a handoff passes the gates or gets kicked back. The agent just doesn't need to know that. From the agent's perspective, it does its work autonomously and the moderator is a narrow relay channel. From the moderator's perspective, you're reviewing everything and steering the ship.

Some of these rules may look overly specific — "never commit raw bearer tokens," "verify the running service is on current binaries." They all come from real mistakes. The runtime verification gate exists because an agent once declared a server fix complete while the server was still running old binaries from a stale publish directory. The secret handling rule exists because a token got committed. The untracked content rule exists because leftover test artifacts got pushed to main. Every mandatory gate is a scar.

Zone 2 — Carry-Forward Contracts (the technical agreement)

Written once at the start, updated when contracts change. 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.

## Key Carry-Forward Contracts

- Auth: Bearer tokens on all protected endpoints via [Authorize].
- API envelope: middleware wraps responses; clients unwrap via envelope helpers.
- Sync flow: changes → tree → reconcile → chunk manifest → download → assembly.
- OAuth client ID: `my-app-desktop` (must match server registration exactly).

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.

One additional gate that earned its place the hard way: when auth is involved, verify that clientid, redirecturi, and requested scopes exactly match the server-registered values before requesting cross-machine retries. I've burned multiple debugging sessions on a scope mismatch that both agents were confident was correct on their side.

Zone 3 — 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

**Date:** 2026-03-07
**Owner:** Client agent
**Status:** IN PROGRESS 🔄

**What server implemented (commit `4570c16`):**
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 using the above endpoint.
Use channel-based buffering (not in-memory accumulation).

**Test suite baseline:** 847 passed / 0 failed / 0 skipped.

**Next action:**
- Implement upload pipeline, commit, push, update this section with results.

Notice there's no "Request Back" checklist in the active handoff itself. The agent knows what to report because the process rules already define the gates: commit hash, test count, build status. Redundancy in the document creates noise that agents struggle with over long sessions.

Zone 4 — The Archive (never delete, but move it out)

Completed tasks don't stay in the handoff document — they get moved to an archive file (HANDOFFARCHIVE.md). This is critical. The handoff document will grow, and once it gets large, agents start struggling to process it efficiently. A table of resolved issues in the archive gives you the audit trail without the cognitive overhead:

## Resolved Issues (Issues #1–#22)

| # | Issue | Root Cause | Fix | Side |
|---|-------|-----------|-----|------|
| 1 | `invalid_client` on authorize | OAuth client not registered | Added client registration seed | Server |
| 2 | `invalid_scope` on authorize | Scopes not registered | Added scope + permissions | Server |
| 8 | `UserId` empty after login | Access tokens encrypted | Changed token format, added claims | Server |
| 16 | Token refresh fails | Auth keys regenerated on restart | Persisted key material to disk | Server |
| 22 | Sync flattens directory tree | Used filename, ignored parent ID | Built parent-path map | Client |

New update available on main, pull latest and follow instructions in handoff doc.

When authentication is involved, verify that clientid, redirect_uri, and requested scopes exactly match the server-registered values before requesting cross-machine retries. I've seen multiple sessions burned debugging what turned out to be a simple scope mismatch — both agents were confident their side was correct and the other side was wrong. A quick contract check catches this before it costs you hours.

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.

[Still, I find things work best staying sequential. Just let things happen one at a time for best results.]

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)
• Commit hash (verifiable with git show)
• 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 845 tests when the validated count was 847, that discrepancy gets flagged before anything moves forward. (Watch everything they say, they aren't evil, but they can be tricky/sneaky!)

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 carry-forward contracts
• Completely Bizarre interpretations - agent did exactly what you said, but in the most unexpected way

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. [Still best to call them on it early]

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 Complete Starting Template

Here's the template I've refined through months of actual use. Copy this into a file called HANDOFF.md in your repo (or wherever your coordination docs live) and commit it before you start:

# Client/Server Mediation Handoff

Last updated: 

Purpose: shared handoff between client-side and server-side agents, mediated by user.

Archived context:
- Historical completed updates are in `HANDOFF_ARCHIVE.md`.
- Additional history remains available in git.

## Process Rules

**Agent autonomy (CRITICAL):**
- Both client and server agents work autonomously — they do NOT ask the
  moderator for context or permission during a task.
- Agents pull the latest `main`, read the Active Handoff section, and execute
  the work described there independently.
- All actionable items, blockers, and technical details go directly in this
  document (committed to `main`).
- Do not stall waiting for moderator approval mid-task. Complete the work,
  commit, push, and update this document. The moderator reviews between
  handoffs and will send work back if needed.

**Handoff management:**
- Put all technical findings, debugging conclusions, and next-step details
  in this document.
- Agent commits their findings/work and updates the Active Handoff section
  with actionable next steps for the other agent.
- Agent pushes commits to `main`.
- Untracked content rule (MANDATORY): remove unexpected untracked
  files/directories before commit; only keep intentional tracked changes.
- Readiness gate (MANDATORY): all executable tests must pass before marking
  a handoff as ready. Environment-gated tests may be skipped but must be
  explicitly identified with prerequisites documented.
- Runtime verification gate (MANDATORY): before declaring a server-side blocker
  fixed, verify the running service is on current binaries (not stale publish
  output) and document the verification command/output.
- Secret handling rule (MANDATORY): never commit raw bearer tokens/refresh
  tokens; share token acquisition steps and sanitized outputs only.
- Moderator relays a short "check for updates" message to the other machine.
- Other agent pulls latest, reads the handoff, and takes action without
  asking questions.

**Document maintenance:**
- Pre-commit archive rule (MANDATORY): before committing this file, move all
  completed/older handoff tasks to `HANDOFF_ARCHIVE.md`.
- Keep only the single current task in Active Handoff (one active block only).
- If a task is completed, archive it first, then replace Active Handoff
  with the next task.

## Moderator Communication (Minimal)

**When handoff passes review, moderator relays ONE of these — nothing more:**

- `New handoff update. Pull main and resume from 'Active Handoff' section.`
- ` — New handoff update. Pull and check HANDOFF.md.`

**Ultra-short format (for clipboard relay between machines):**

`New update available on main, pull latest and follow instructions in handoff doc.`

**When handoff fails review:** Moderator talks to the *completing* agent
in plain English about what needs to change. The relay to the other machine
does NOT happen until the issues are resolved and a clean commit is pushed.

**No moderator context in relay:** The one-sentence relay provides zero
context and zero explanation. The handoff document has everything the
receiving agent needs.

## Environment

| Role | Machine | Detail |
|---|---|---|
| Server (Agent A) | `` | `https://:/` |
| Client (Agent B) | `` | Working dir: `` |

## Key Carry-Forward Contracts

- Auth: 
- API format: 
- 

## Active Handoff

###  — 

**Date:** 
**Owner:** 
**Status:** IN PROGRESS 🔄 | COMPLETE ✅

**What was implemented (commit ``):**


**What  needs to do:**


**Test suite baseline:**  passed /  failed /  skipped.

**Next action:**


## Relay Template

### Send to [Server|Client] Agent


### Request Back
- commit hash
- build result (0 errors)
- test count (was X, should be ≥ Y)
- 

And the companion archive template:

# Handoff — Archived Context

Archived: . Full git history preserved.

This file contains historical reference from completed mediation sessions.
Only consult when investigating a regression or reviewing a past decision.

## Resolved Issues

| # | Issue | Root Cause | Fix | Side |
|---|-------|-----------|-----|------|
| 1 |  |  |  | Server/Client |

## Verified State at Milestone Completion

### Server (, commit ``)
- Build: 0 errors, 0 warnings
- Tests:  passed

### Client (, commit ``)
- Build: 0 errors, 0 warnings
- Tests:  passed

### End-to-End Flow Verified

Using AI to Generate Your Initial Handoff

The hardest part of the handoff document isn't the template — it's filling in the Carry-Forward Contracts 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 Carry-Forward Contracts section for a handoff document. 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 contracts 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 contracts 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 the handoff document and that becomes the single source of truth both agents orient from.

Model Selection: Save the Big Guns for When You Need Them

You don't need top-tier models for every task. In practice, a mid-tier model (something in the Claude Sonnet class) handles the vast majority of the work just fine — straightforward feature implementation, test writing, documentation, routine debugging. The handoff structure helps here: because tasks are small and well-scoped with clear contracts, the agent doesn't need to be brilliant. It just needs to be competent and follow instructions.

Where you want a top-tier model (Claude Opus or equivalent) is when things start going sideways. The symptoms are recognizable: the agent keeps circling without making progress, it's passing work back and forth with the other side but nothing actually gets resolved, or it's making changes that break something else every time it fixes the original problem. When you see that pattern, swap in the stronger model for that specific task. It will usually cut through the problem in one session.

This is a real cost optimization. Top-tier tokens are expensive. If 90% of your tasks complete cleanly with a mid-tier model, you save significantly by reserving the heavy hitter for the 10% that actually need it. And the escalation path gives you somewhere to go when things get stuck — which is better than the alternative of running the same model at the same problem repeatedly and hoping for a different result. If even the best available model can't solve it, that's your signal that the problem is structural, not computational, and you need to rethink the approach rather than throw more tokens at it.

There's a related trick for the planning phase: use the top-tier model to create your initial architecture and implementation planning documents — the carry-forward contracts, the phased task breakdown, the handoff document itself. But tell it explicitly that the actual implementation will be done by a mid-tier model. The top-tier model will adjust its output accordingly: more explicit instructions, less assumed context, clearer decision rationale. You get the architectural thinking of the strongest model, written at a level that a competent but less capable model can follow without ambiguity. It's a one-time cost that pays off across every task that follows.

Real-World Usage Example

To make this concrete, here's a condensed example drawn from real experience running dozens of issues through the mediator pattern over several weeks on a client/server project:

The setup: Two machines. A Linux server running the API, and a Windows machine running the desktop/mobile client. Each machine has its own AI agent session. The developer sits in the middle.

A typical auth debugging issue — UserId empty after OAuth login:

The client agent completed the OAuth flow and received tokens, but every API call returned a 403 because the user ID extracted from the token was empty. The client agent reported the symptom and committed its findings to the handoff document:

## Active Handoff

### Issue #8: UserId extracted as empty string — Server

**Client status:** ✅ Auth flow working, tokens received
**Server status:** 🔄 IN PROGRESS

**What client found:**
Access token appears encrypted. No `sub` claim visible after decode.
Server's userinfo endpoint returns 404.

**What server needs to do:**
- Fix token format so claims are readable by the client.
- Implement the userinfo endpoint.
- Ensure `sub` claim contains the user's ID.

The server agent pulled main, read the handoff, diagnosed the issue (encrypted tokens hiding claims from the client), fixed it (changed token format, added the user ID claim, registered the userinfo endpoint), and updated the handoff:

**Server status:** ✅ COMPLETE — commit `a3f9c12`
- Changed token format so claims are visible to clients.
- Added `sub` claim populated from database user lookup.
- Registered userinfo endpoint with proper claims.
- Tests: 304 → 312 (8 new auth tests).

The moderator's message to the client machine: a3f9c12 UserId fix — token format changed, sub claim added. Pull main. Verify token decode shows sub.

The client agent pulled, verified sub was present in the decoded token, and the 403s stopped. Issue moved to archive.

The resolved issues table after 22 issues looked like the audit trail shown in the archive template above — every root cause, every fix, every side. When a later issue caused tokens to break again (auth signing keys regenerating on restart), the agents could see the full history of auth-related fixes without re-investigating from scratch. That's the audit trail paying for itself.

Starting Your First Session

1. Create and commit HANDOFF.md with your carry-forward contracts 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 carry-forward contracts. Your first task is [Task 1]."
3. Agent A works. When done, it commits, pushes, and updates the Active Handoff section.
4. You review the diff. This is where you catch scope creep, contract drift, and missing tests.
5. Relay to Agent B's machine:
   . Pull main. .
6. Agent B pulls, reads the handoff, works, commits, pushes, updates.
7. Move the completed issue to the archive. Write the next Active Handoff entry. 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, mandatory verification gates before every handoff, and an archive that preserves every decision and root cause.

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

What makes this version of the pattern different from the theoretical version is the gates. The mandatory rules about test readiness, runtime verification, untracked content, secret handling, and auth contract checks aren't process theater — they're the specific failure modes that actually happen during real dual-agent development. Every rule is a scar from a real debugging session.

Your role is not to write code or make architectural decisions mid-stream. Your role is to route information with precision — ideally in a single clipboard-pasteable line — 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 the handoff document deliberately tells them.