handoff

Write a handoff document that lets a fresh agent continue this work without re-deriving any context. Save it to a path produced by f=$(mktemp "${TMPDIR:-/tmp}handoff-XXXXXXXX") && mv "$f" "$f.md" && echo "$f.md" (read the file before you write to it).

If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

What to capture

The goal is compression, not transcription. A good handoff is under 200 lines and gives the next agent everything it needs to start working immediately.

Include these sections (skip any that don't apply):

Goal — What the user is trying to accomplish, in one or two sentences. Include the "why" if it's not obvious from the task itself.

Current state — Where things stand right now: branch name, what's been built/changed, what works, what doesn't. Be specific — file paths, function names, test results.

Decisions made — Choices that were made during this session and their rationale. The next agent shouldn't re-litigate settled questions.

What failed / dead ends — Approaches that were tried and abandoned, and why. This prevents the next agent from repeating mistakes.

Open questions / blockers — Anything unresolved that needs the user's input or further investigation.

Next steps — Concrete actions for the next session, ordered by priority.

Suggested skills — Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.

What NOT to include

Do not duplicate content already captured in other artifacts — PRDs, plans, ADRs, issues, commits, diffs. Reference them by path or URL instead. The handoff supplements the commit history; it doesn't replace it.

Do not include verbatim code blocks unless they're critical context that isn't committed anywhere (e.g., a snippet the user pasted that informed a design choice).

Do not rehash the full conversation. Distill it.