Handoff

Why this workflow exists

Handoff is information compression. The next session does not need the transcript; it needs the smallest complete set of facts required to continue safely. An eight-item checklist guarantees completeness, and an empty category must say “None” rather than quietly disappearing — because omission and absence look identical to whoever reads it next.

How it runs, stage by stage

Every rule below is taken from the workflow definition in the source repository — this is what the agent is actually told to do.

1. 01

   Gather current facts

   Re-read the real state instead of trusting memory.

   • Re-read version-control status and the relevant diff.
   • Read the authoritative requirement and design documents.
   • Check the latest verification output rather than relying on memory.
   • Identify blockers, unresolved decisions, and unrelated work that must be preserved.
2. 02

   Produce the handoff

   Eight items, every one explicit, empty categories written as “None”.

   • Objective and accepted behavior.
   • Current implementation state.
   • Key files and authoritative documents.
   • Decisions already made and their reasons.
   • Commands run and their latest results.
   • Remaining tasks in dependency order.
   • Known risks, blockers, and unverified areas.
   • Version-control state and unrelated changes to preserve.
   • References support the facts; they do not replace them. Summarize each decision and its reason even when linking the source, and reference documents, commits, diffs, and test output instead of copying their full contents.
   • Write to the requested path when one is provided; otherwise return the handoff in the response without silently creating a repository file.

Rules that cannot be bypassed

A real invocation

What the conversation actually looks like, from the token you send to the evidence you get back.

1. Agent

   Re-reads Git status and the diff, the authoritative requirement record, and the most recent test output.

2. Agent

   Organizes the facts into the eight items, writing “None” for blockers rather than dropping the category.

3. Agent

   Summarizes each decision with its reason, and references the requirement document and test results instead of pasting them.

4. Agent

   Returns the record in the response — no path was given, so no file is created.

When to use it

• The session is ending and work passes to another session or teammate.
• The context window is nearly full and state must be saved before compaction.
• You need an executable record of exactly where the task stands.
• Someone else will continue and must not repeat decisions you already made.

When to reach for something else

Questions