Handoff

handoff

Move in-progress work from one agent to the next — a different session, a different machine, a different day — through a structured document committed to the repo. Two directions, one skill: write a handoff, or resume one.

The document is the whole product. It is written for a reader who has none of the writer's session — no scrollback, no open files, no memory of what was already tried. A handoff that only makes sense to the agent that wrote it has failed at the one job it has.

Workflow

1. Route

2. Make the work reachable — before writing anything

A handoff is committed so another machine can pick it up. That promise is only kept if the work travels too, not just the note about it.

• Uncommitted work is unreachable. Commit it (via atomic-commit) and push the branch. Work in progress that is not yet coherent goes in one honest wip commit — the resumer needs the code more than it needs a tidy history.
• Nothing to commit is a fine answer — say so in the document (Progress records "nothing uncommitted").
• Cannot push (no remote, offline, work that must not leave the machine) → still write the handoff, but state it plainly under Progress and drop the branch field. A handoff describing work that exists nowhere but this disk is a local note, and must not claim otherwise.

3. Allocate the id

Handoffs live in .agents/handoffs/, named NNNN-lower-kebab-case.md (0001-refactor-auth-layer.md).

The next id is one above the highest ever used — read from git history, not the folder. Handoffs are deleted when their work completes, so the folder is a poor witness; history is the only one that remembers 0003 existed. Ids are never reused, renumbered or gap-filled. Recipe: REFERENCE.md.

4. Write the document

Copy templates/handoff.md and fill every section. Frontmatter carries the machine-readable fields (title, status, created, updated, branch, issue); the body carries the prose, in fixed H2s: Goal, Context, Progress, Next steps, Open questions. Full contract: REFERENCE.md.

Write it self-contained:

• No deixis. No "the file we looked at", "as discussed", "the failing test from earlier". Name paths, symbols, commands, issue numbers and commit shas outright.
• Dead ends are the most valuable content. What was tried and did not work saves the resumer from spending the same hours. Record it under Context, with the reason it failed.
• Next steps are actionable and ordered — the next thing to type, not a topic to consider.
• No secrets. The file is committed. Never paste tokens, keys, credentials or .env values into it; reference where they live instead.
• No attribution. No agent or model name, no session url, no "handed off by". The document says what the work is, never who typed it — see Guardrails.

5. Commit the handoff

Commit the new file via atomic-commit and push. Until it is pushed, the handoff has not happened. Report the id, the path and the branch.

atomic-commit is optional — at every commit this skill makes: the work at step 2, the handoff here, and the deletion at step 8. Not installed, commit directly in the repo's own Conventional Commits conventions and push as usual. A handoff that never lands — or never clears — because a helper skill is absent is the one failure these steps cannot afford.

6. Find the handoff to resume

Never resolve a handoff by recency. "The latest" is a guess with a plausible-looking answer, and picking the wrong thread of work is the one failure a handoff cannot recover from. Two files sharing an id (a real race) → report the ambiguity, do not pick.

7. Restore the ground, then work

Read the document fully before touching anything. Then git fetch, check out the branch it names, and confirm the tree matches what Progress describes — if it does not, say so before working; the document is the writer's snapshot, and the branch may have moved since.

Then do the work: Goal is the target, Next steps is the running order, Context is what you do not need to rediscover. Open questions are for the human — put them to the user rather than answering them by fiat.

Do not delete the handoff now. Reading it is not consuming it.

8. Delete the handoff when the work is done

The file is deleted in the same commit that finishes the work — not on read, not on resume, not on the first green test.

A handoff deleted on read exists nowhere the moment the resuming session crashes — which is precisely the situation it was written to survive. Its lifetime is the work's lifetime: it lives while the work is unfinished and disappears with the last commit that finishes it. Nothing else in the repo records that it ever existed, and nothing needs to.

9. Unfinished? Update in place

Resumed work that is being parked again updates the existing document — same id, same file. Refresh Progress, Next steps, updated, and branch if it changed; fold what you learned into Context. Never open a second handoff for the same thread of work: one thread, one id, until it is done.

Guardrails

• Reachable or honest. Never write a handoff that implies work is available elsewhere when it was never pushed (step 2).
• atomic-commit is optional, never a precondition. It is the preferred way to commit the work, the handoff and the deletion that closes it, but if it is not installed, commit in the repo's own conventions and push anyway — a missing helper must not be why the handoff fails to land or fails to clear.
• Self-contained or worthless. The reader has none of your session. Every reference is resolvable from the document alone.
• Delete on done, never on read (step 8). The file survives every intermediate failure, by design.
• Never guess which handoff (step 6). Explicit id, or the single unambiguous one, or ask.
• Ids are permanent and never reused — even though the files are not (REFERENCE.md).
• Attribution-free. No agent or model name, no Generated with/🤖 line, no session url, in the document, the commit, or anything this skill writes. The frontmatter has no author field on purpose — a handoff is a note to the next worker, not a signed artifact, and the next worker gains nothing from knowing which tool typed it.
• Secret-free. The document is committed. Scan what you paste into Context — logs, env dumps and config excerpts are where secrets get in.
• A handoff is not an ADR. Same NNNN-title.md shape, opposite lifecycle — an ADR (write-docs) is a permanent record that must never be deleted; a handoff is working state that is consumed and removed. Never file a decision as a handoff, and never let a handoff's deletion take a decision's record with it — if the work settled something architectural, that belongs in an ADR before the handoff goes (REFERENCE.md).

Reference

Two branches, and step 1 settles which. Writing one — open it at step 3 for the folder and file schema and how an id is allocated (and what happens when two runs allocate the same one), then at step 4 for the document contract and status vocabulary, since a document that quietly assumes the writer's session is the failure this skill exists to prevent. Resuming one — open it at step 6 for the resume rules and the lifecycle that puts the delete at the end of the work rather than at the read. And when the note looks like it should be something else — an ADR, a tracker issue, a commit — the same file draws that line: REFERENCE.md.