The Agent Handoff Document Template I Actually Use (11 Sections, One Machine-Checkable Line)

There are seven files named OPUS-HANDOFF.md sitting one directory deep in my home folder right now, one per active build. Each one commissions an autonomous agent to do a multi-day job I will not be supervising. They are the single highest-leverage artifact in my whole operation, and the reason is structural rather than clever: the agent's memory ends and the file does not.

I have written before about why handoff documents keep agents continuous. This post is the other half — the actual anatomy, section by section, from files that are running production work.

Why the file has to exist at all

This is not a preference. Anthropic's own documentation states it plainly: "Each Claude Code session begins with a fresh context window," and the two mechanisms that carry knowledge across sessions are files — CLAUDE.md instructions you write, and auto memory the model writes itself. The same page notes that instructions given only in conversation are the ones that go missing after compaction: "it was either given only in conversation or lives in a nested CLAUDE.md that hasn't reloaded yet." (Claude Code memory documentation.)

So there are exactly two categories of instruction: the kind that is written to a file, and the kind that evaporates. A handoff document is simply the decision to put the mission in the first category. Everything else here is detail.

Where public templates stop

The best public example I have found is the session-handoff skill in the softaworks agent-toolkit. Its template defines ten sections: metadata, current state summary, important context, decisions made, immediate next steps, pending work, critical files, key patterns discovered, potential gotchas, and a handoff chain linking each document to its predecessor. That is a genuinely good structure and I have borrowed from it.

But read the section names in order and the orientation is unmistakable: it is a retrospective. It is written at the end of a session, by the agent that just did the work, describing what happened so a successor can resume. That is the right shape for continuing a conversation you ran out of context in.

It is the wrong shape for what I mostly need, which is commissioning a job nobody has started. My handoffs are written before the work, by an orchestrating model, for an executor that will run unattended for days. That inverts three things: the state section becomes a set of verified findings rather than a summary, the "gotchas" section becomes enforceable rules rather than warnings, and there has to be a completion condition, because nobody is going to be in the room to say "that's enough."

The 11 sections

Here is the anatomy, with what each one is actually for.

1. Title and mission line. One sentence naming the systems in scope. The file I opened while writing this starts with a title naming three specific sites — no ambiguity about which repositories are in play.

2. Provenance header. Who wrote it, when, which model executes it, and under what autonomy level. Mine reads "Written: 2026-07-14 by orchestrator. Executor: Opus, fully autonomous." An agent reading a document with no author and no date cannot judge how stale it is.

3. Commercial context. What this work is worth and to whom. It sounds like a human concern and it is not: an agent that knows a deliverable is billed monthly makes different tradeoffs about scope than one that thinks it is a hobby project.

4. Anchor facts, with their source. Any date or number the plan is parameterized on, plus where it came from and what happens if it is wrong. Mine names a start date, states it was verified from a specific message thread, and says explicitly: if this date is corrected, it is one variable and everything below recomputes from it. That single clause is the difference between a correction being a five-second edit and a rewrite.

5. Verified baseline findings. The section I would keep if I could keep only one. It is a list of things already checked, with the timestamp of the check, and a header instructing the agent to trust these over its own assumptions. Real examples from my files: a blog that is already live under a name the agent must match instead of inventing a new one; two production sites that return HTTP 200 for every nonexistent URL, with the consequence spelled out — "curl 200 alone never proves a page is live here, always assert the returned title matches." Agents do not fail because they are stupid. They fail because they assume a reasonable thing that happens to be false on this specific system. This section is where you spend those assumptions in advance.

6. Mission, numbered. The deliverables as a countable list with quantities. Not "improve SEO." Instead: this many posts per site per day across this range, this specific infrastructure per site, a scheduled job that is armed and verified.

7. Hard rules. Prohibitions, not preferences. Mine include a standing ban on git checkout, merge, reset, and stash in any existing working tree — use a worktree or a copy — plus never fabricating a statistic or a client claim, and a language standard applied to every word published. These exist because each one is a mistake that already happened once. A rule with a scar behind it is worth ten rules from a style guide.

8. Per-target sections. One block per repository or property: paths, deploy commands, brand constraints, and the specific trap that target carries. One of mine opens with a warning that the working tree contains a preview-only overhaul that must not reach production, and then gives the exact alternative procedure. That is a paragraph that has saved a production site.

9. Reversibility notes. For any irreversible-looking step, the sentence that makes it reversible: the command to undo it, or the reason it is safe. My files carry these inline next to the risky instruction, not in an appendix.

10. Open decisions, explicitly suspended. Anything the agent must not decide. One of my files contains a policy block marked SUSPENDED — pending the human's call — with the reasoning for both options laid out and a middle path proposed. This is the section that separates a fleet from a liability. Autonomy means the agent executes without asking; it does not mean the agent gets to make the calls that are mine, and the only way to enforce that is to name them in writing before it starts.

11. Done =. One line, at the bottom, listing conditions that can be checked rather than felt. Mine reads like this: N posts live, HTTP 200 spot-checks on at least six URLs, sitemaps valid, JSON-LD validates, three scheduled jobs armed with one proven live run, a project report written, and every production page other than the intended additions verified untouched. Every clause is something a machine can test. That is the whole bar. If your Done section contains the words "high quality," you have not written a completion condition — you have written a hope, and an autonomous agent will meet it by declaring success.

The two failure modes this prevents

Drift, which is when the agent slowly optimizes for something adjacent to the goal. Sections 5, 7, and 11 fence it: the facts it may not re-derive, the actions it may not take, and the target it must hit. This is the same mechanism as written doctrine in CLAUDE.md and skills, scoped to one job instead of the whole system.

Amnesia, which is when a run ends — context exhausted, machine rebooted, session closed — and the next one starts from nothing. The file is the state. When I pick a project back up weeks later, I do not reconstruct anything; I open the handoff and read what past-me verified, with dates.

There is a third benefit I did not design for and now rely on: writing the handoff is where the plan actually gets made. A quarter of the plans I draft fall apart at the Done = line, because I cannot state a checkable completion condition, which means I do not yet know what I want. Better to discover that in a text editor than three days into an unattended run.

How to write one in twenty minutes

1. Name the mission in one sentence, then write Done = second. If you cannot make every clause machine-checkable, stop and fix the mission.
2. List everything you have already verified, each with a date. Add "trust these over assumptions" above the list.
3. Write the hard rules from memory — they are your existing scars, and you know them.
4. Add one block per target with paths, commands, and its specific trap.
5. Name anything the agent must not decide, and mark it suspended.
6. Fill in the rest only if it earns its place. A handoff nobody finishes reading is a handoff nobody follows.

Then keep it current. Mine get amended mid-run when a finding invalidates an assumption, which is exactly the behavior you want: the document is the system of record, and a run that discovers something true is supposed to write it down. That discipline is the same one behind staging every change safely before it ships — the artifact, not the conversation, is what survives.

The micro-lesson

The quality of an unattended agent run is set almost entirely before it starts, by the document that commissions it. Judge yours by one test: hand it to someone who has never seen the project, and ask whether they could tell you — without asking a single question — what to build, what never to touch, which calls are not theirs to make, and how they would know they were finished. If any of those four is missing, the agent will improvise it, and improvisation is precisely the thing you were not there to approve.

FAQ

What is an agent handoff document?

It is a written brief that carries a mission across the boundary where an AI agent's memory ends. Because each session starts with a fresh context window, anything stated only in conversation is lost when the session ends or the context compacts. A handoff document puts the mission, the verified facts, the prohibitions, and the completion condition into a file the next run reads at startup, so continuity comes from disk rather than recall.

What sections should an AI agent handoff document contain?

At minimum: provenance (who wrote it, when, which model executes it), verified findings with timestamps and an instruction to trust them over assumptions, a numbered mission with quantities, hard rules stating what must never be done, one block per target system with paths and traps, any decision the agent must not make, and a completion condition where every clause is machine-checkable. Public session-handoff templates add useful retrospective sections such as decisions made, critical files, and a chain link to the previous handoff.

How is a handoff document different from a CLAUDE.md file?

CLAUDE.md is standing doctrine: conventions, commands, and rules that apply to every session in a project, loaded automatically at startup. A handoff document is job-scoped and finite — it commissions one specific piece of work, carries findings verified for that work, and ends at a defined completion condition. Doctrine tells the agent how to behave; a handoff tells it what to build and when to stop. Most projects need both.

Why does my agent forget context between sessions?

Because each session begins with a fresh context window, and long sessions compact, which drops detail from the middle of the conversation. Anthropic's documentation is explicit that instructions given only in conversation do not survive, while project-root CLAUDE.md is re-read from disk and re-injected after compaction. The fix is not a longer prompt; it is moving anything that must persist out of the conversation and into a file the agent reads at the start of every run.

How do I write a completion condition an autonomous agent cannot fudge?

Write only clauses a machine could test: a specific count of artifacts existing, specific URLs returning HTTP 200, structured data that validates, a scheduled job appearing in the scheduler's own listing with at least one proven end-to-end run, a report file written. Remove every subjective word. If a clause cannot be checked without a human judging quality, either convert it into a test or move it out of the completion condition and into a review step you perform yourself.

— Italo Campilii. Every section above is drawn from handoff files currently in use on my own machine, read on 2026-08-02.