handoffkit
handoffkit
Turn everything learned in this conversation into a single handoff document a fresh agent, with none of this context, can read and continue from. The point is transfer, not archival: capture the state and reasoning that only lives in this session, and point at the artifacts that already exist (specs, PRs, commits, diffs, issues) rather than copying them. By default, save it as a Markdown file under docs/handoffs/; print it as a copy-pastable block only when the user explicitly asks for inline or terminal output, or when no writable filesystem is available.
When this fires
The user wants continuity across a context boundary: "write a handoff", "hand this off", "summarize for the next session", "pass this to another agent", "compact this before we run out of context". If they give an argument (e.g. "handoff for finishing the migration"), treat it as the focus of the next session and slant the whole document toward it. Lead with what that goal needs and prune what it doesn't.
What goes in, and what stays out
A handoff earns its keep by carrying what a new agent can't reconstruct:
- Include: the goal and why it matters; what's done vs. still open; the immediate next action; decisions made and the reasoning behind them; dead ends already ruled out; gotchas, constraints, and how to run/verify.
- Exclude (reference instead): anything already written down, meaning specs, ADRs, plans, issues, commit messages, diffs, PR descriptions. Link them by path or URL; don't paste their contents. A handoff that restates the diff is noise.
- Redact: API keys, tokens, passwords, and personally identifiable information. Never carry secrets into the document. Refer to them by name ("the staging DB password in
.env"), not value.
Document shape
Write these sections; drop any that are genuinely empty rather than padding them.