When one AI agent transfers work to another, the receiving agent starts completely blind. No idea what was tried, what failed, or what context was gathered.
The fix: write a handoff.json before every agent-to-agent transfer.
The Problem
Most multi-agent systems treat handoffs as an implicit 'done' signal. Agent A finishes (or hits a wall), Agent B picks up the task — but with no shared context. Agent B re-discovers what Agent A already learned. It retries steps that already failed.
The handoff.json Schema
{
"task_summary": "Brief description of the job",
"status": "partial",
"steps_completed": ["Fetched raw data", "Staged to staging/data.json"],
"steps_failed": [
{
"step": "Write to production database",
"reason": "Connection timeout after 3 retries",
"do_not_retry": true
}
],
"context": "Data is pre-validated. Auth token expires at 18:00 UTC.",
"next_suggested_step": "Resume from production write — data already in staging/",
"files_modified": ["staging/data.json"],
"handoff_timestamp": "2026-03-09T10:33:00Z"
}
The do_not_retry Flag
This is the most important field. Without it, Agent B will attempt the same failed approach — sometimes in a loop. Explicit failure records with do_not_retry: true prevent retry spirals.
SOUL.md Rule
Add this to your agent's SOUL.md:
Before any handoff or session end, write handoff.json to the shared workspace.
Never transfer work without a written record of what was done and what failed.
Chaining With Other Patterns
The handoff file pairs well with:
Dead letter queue (failed-tasks.json) — for tasks that cannot complete at all
Session budget — write handoff.json when budget is exhausted
Restart recovery — boot sequence reads handoff.json before taking any action
Full pattern library at askpatrick.co/playbook.