Copy-paste HANDOFF.md template

Paste this into a new file, or ask your agent to fill it in at the end of a session.

# HANDOFF: <task name>

## Goal
What "done" means, in one or two sentences. What must not change.

## Current state
Where the work stands right now. Branch, last commit, what runs and what does not.

## What changed
- ...

## Decisions and why
- Chose X over Y because ...

## Next steps
1. ...
2. ...

## Open questions / blockers
- ...

## How to verify
```
npm test
```

## Files touched
- path/one.ts (new)
- path/two.ts (modified)

Where do you put HANDOFF.md and how do agents use it?

• Repo root for one stream of work. The next session finds it without being told.
• Per task (for example tasks/login-fix/HANDOFF.md) when several agents or branches run in parallel.

Agents such as Claude Code, Cursor or Codex can read any file in the repo, so the simplest setup is a line in your instructions: "At the end of a session, update HANDOFF.md. At the start, read it first." Nothing here depends on a built-in feature; it is an ordinary file and an ordinary instruction.

HANDOFF.md vs AGENTS.md, CLAUDE.md and README

HANDOFF.md holds session state: what happened and what comes next. It changes every session and is retired when the work ends. AGENTS.md and CLAUDE.md hold standing instructions for agents: build commands, code style, rules. README holds project docs for humans. Do not put session notes in the standing files; they go stale and mislead later runs.

Why does an agent handoff need a document at all?

Context windows end, sessions get closed, and the assistant that started the work is not the one that finishes it. What survives is whatever was written down. A handoff document is a compact, honest account of the state of a task: what was done, what was verified, what is still broken, and what to do next. It is not a transcript, and it deliberately does not carry repository access, credentials, or the previous conversation — only text.

What should an agent handoff document contain?

The template above is the short form. This longer nine-section version suits larger tasks and adds the commit and the commands already run.

# Agent handoff: <task name>

## Objective
One paragraph: what "done" means, and what must not change.

## Repository and branch
- Repo:
- Branch:
- Base:

## Relevant commit
<hash> — <subject>. Everything below describes the tree at this commit.

## Completed changes
- ...

## Files affected
```
path/one.ts   (new | modified)
```

## Commands run and results
```
npm test  → 14 passed
```

## Unresolved problems
1. ...

## Decisions and constraints
- ...

## Next steps
1. ...

Two of these do most of the work. Commands run and results saves the next agent from re-running a ten-minute test suite to learn what you already know. Relevant commit lets it check git log -1 and see immediately whether the summary still matches the branch.

What does a filled-in handoff look like?

A fictional but realistic one: an agent moved session storage to Redis behind a feature flag, ran the tests, and stopped before the CI and staging work. Everything the next agent needs is in the document, including the pre-existing lint warning it should not waste time on.

lib/session/redis-store.ts      (new)
lib/session/index.ts            (modified)
lib/session/memory-store.ts     (unchanged, still default)
docker-compose.yml              (modified)
.env.example                    (modified)
tests/session/redis-store.test.ts (new)

npm test -- session         → 14 passed, 0 failed
npm run type-check          → clean
npm run lint                → 1 warning (unused import in memory-store.ts, pre-existing)
docker compose up redis     → healthy on :6379
SESSION_STORE=redis npm run dev → login/logout works; cart persists across a server restart

How do I publish the handoff and pass the link on?

From Claude Code or Cursor with the Docs MD MCP server connected, at the end of the session:

Write an agent-handoff.md for the work in this session using the nine-section
template, then share it with a 7-day expiry and give me both links.

You get a rendered URL and a raw URL. Paste the raw URL into the next session's first message, or into the issue the teammate will pick up. Without MCP, the same thing from a shell:

curl -s -X POST https://docs-md.com/api/share \
  -H "Content-Type: application/json" \
  --data-binary @<(jq -Rs '{content: ., filename: "agent-handoff.md", expiry: "7d"}' agent-handoff.md) \
  | jq -r '.rawUrl'

How does the next agent or person read it?

• A person opens the rendered link: headings, the file list as a code block, the results table, and a table of contents in the sidebar.
• An assistant with an HTTP tool fetches https://docs-md.com/raw/<id> and gets the markdown as text/markdown. A first message such as "Read https://docs-md.com/raw/… and continue from its next steps" is enough.

Before acting on the summary, the next agent should compare the commit in the document with the branch head. If they differ, someone worked after the handoff was written, and the document is a starting point rather than the truth.

What are the limits?

• 120,000 characters per share; a handoff should be far shorter than that.
• The link is public to anyone who has it. Never include tokens, keys, or customer data.
• Expiry removes the page at its URL; it does not recall copies already fetched.
• The next agent needs its own repository access. The handoff carries a summary, not permissions.

To build the file from a form instead of by hand, use the HANDOFF.md generator: it emits the same sections with a live preview, a download, and a share link.

See also: share an implementation plan for review and the REST API.

FAQ