Handoff Protocol

handoffs/ is a chronological log of project state. Each file is a complete, self-contained snapshot of where the project stands. The latest file is the only file the next agent reads. Older files are version history for the human — the agent must not read them.

File naming

handoffs/YYYY-MM-DDTHHMM.md

Examples:

handoffs/2026-05-13T1430.md
handoffs/2026-05-13T1645.md   ← supersedes the one above
handoffs/2026-05-14T0900.md   ← this becomes the new latest

Use the current UTC time when writing. The lexicographic sort order of the filenames is their chronological order — the last file alphabetically is always the latest.

Make sure handoffs/ is gitignored, or commit it as part of the human-readable project log — whichever your team prefers. This skill takes no position on that.

Writing a handoff

Write a new handoff file whenever:

• A unit of work is finished and reviewed.
• A session ends mid-task (partial progress, stopping for now).
• The user explicitly asks for a handoff (/handoff).

Every handoff must be fully self-contained. Do not reference or say "see previous handoff". The agent reading it will not look at any other file unless the handoff explicitly tells it to.

Use this template. Where the template links to per-task artifacts (plans, PRs, issue trackers, per-feature directories), use whatever convention this project follows. If the project has none, just describe the work inline.

# Handoff — YYYY-MM-DD HH:MM UTC

## Project state

<One paragraph. What is this project, what is its current overall status, and
what is the highest-priority thing the next session should focus on?>

## Completed this session

<What was finished. Link to a plan file, PR, issue, or per-task directory if
this project uses one. Otherwise just describe inline.
If nothing was completed, write "Nothing completed this session.">

- <task or feature name> — <one-line summary of what was done>

## In progress

<Work that was started but not finished. Be specific about exactly how far
along each one is and what remains.>

- <task or feature name> — <current state, what's done, what's next>

If none: "Nothing in progress."

## Next steps

Ordered list of what the next agent or developer should do first:

1. <Most important next action — be specific enough that someone can act on it immediately>
2. <Second action>
3. ...

## Context and gotchas

Things the next agent needs to know that are not obvious from the code:

- <gotcha / environment note / known issue / external dependency status>
- ...

If none: "No special context."

## Reading list

Files the next agent should read (beyond this handoff and UML.md):

- `<path>` — <why it's relevant>
- ...

If none: "No additional files needed."

Reading a handoff

When resuming a project that has a handoffs/ directory:

1. List all files in handoffs/.
2. Sort them lexicographically — the last file is the latest.
3. Read only that file. Do not read any other file in handoffs/.
4. Follow any "Reading list" entries the handoff specifies.
5. Treat the handoff as the primary source of "what's happening now". UML.md (if present) is the architectural reference; the handoff is the operational state.

Relation to other files

The handoff describes operational state; UML.md describes architectural structure. Together they let the next session get oriented without reading every source file. If your project keeps per-task artifacts (plans, PRs, feature directories, issues), link to them from the handoff so the next agent can drill down.