Handoff
Compress the current session into a disposable markdown file so a fresh agent can continue without inheriting a bloated context window.
When to use handoff vs compact
| Situation |
Prefer |
| Same session, same goal — context is huge but work continues in place |
Harness compact (summarize in-place) |
| Side task, refactor, bug, or prototype out of scope for this session |
Handoff to a new session |
| Different agent or tool for the next step |
Handoff (markdown is portable) |
| Prototype or spike, then return learnings to the planner session |
Handoff out and handoff back (see patterns.md) |
Handoff keeps the current session pure; compact keeps one long session going.
Before writing
The user (or skill arguments) should state why you are handing off and what the next session will do. Without that focus, the document will be vague. If missing, ask briefly or infer from the latest user message.
Instructions
- Write a handoff document summarizing only what the next session needs.
- Save outside the workspace — use the OS temporary directory (e.g.
mktemp / $TMPDIR), not the project repo. Handoffs are disposable, not documentation.
- Tell the user the full path to the file when done.
- Include a Suggested skills section listing skills the next agent should invoke (by name), with one line each on why.
- Do not duplicate content already in PRDs, plans, ADRs, issues, commits, or diffs — reference by path or URL.
- Redact API keys, passwords, tokens, and PII.
- If the user passed arguments (or a slash-command argument), treat them as the next session's focus and tailor the document accordingly.
Document template
Use this structure (omit empty sections):
# Handoff: [short title]
## Purpose
Why we are handing off and what the next session must accomplish.
## Context
Decisions, constraints, and background the next agent needs (compressed).
## Current state
What is done, in progress, or blocked in this session.
## Artifacts
Pointers only — paths, URLs, issue numbers, branch names.
## Open questions
Unresolved items for the next session to answer or validate.
## Suggested skills
- `skill-name` — why to invoke it
## Out of scope
What this handoff explicitly does **not** include (keeps the next session focused).
Quality bar
- Slice, don't dump — only context relevant to the stated next-session purpose.
- Actionable — the next agent should know the first concrete step.
- Portable — readable without this chat; no "as discussed above."
- Short — prefer pointers over pasted prose.
Common patterns
For parallel side tasks and cross-agent review, see references/patterns.md.
1---2name: handoff3description: Compact the current conversation into a handoff markdown document for another agent or session to pick up. Use when handing off a side task, spawning a prototype session, passing work to a different agent (Cursor, Codex, GitHub Copilot CLI, Claude Code), or keeping the current session focused while continuing work elsewhere. Also use when the user says handoff, hand off, or wants a handoff document.4---56# Handoff78Compress the current session into a **disposable** markdown file so a fresh agent can continue without inheriting a bloated context window.910## When to use handoff vs compact1112| Situation | Prefer |13| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |14| Same session, same goal — context is huge but work continues in place | Harness **compact** (summarize in-place) |15| Side task, refactor, bug, or prototype **out of scope** for this session | **Handoff** to a new session |16| Different agent or tool for the next step | **Handoff** (markdown is portable) |17| Prototype or spike, then return learnings to the planner session | **Handoff** out and **handoff** back (see [patterns.md](references/patterns.md)) |1819Handoff keeps the **current** session pure; compact keeps one **long** session going.2021## Before writing2223The user (or skill arguments) should state **why** you are handing off and **what the next session will do**. Without that focus, the document will be vague. If missing, ask briefly or infer from the latest user message.2425## Instructions26271. Write a handoff document summarizing only what the **next** session needs.282. **Save outside the workspace** — use the OS temporary directory (e.g. `mktemp` / `$TMPDIR`), **not** the project repo. Handoffs are disposable, not documentation.293. Tell the user the full path to the file when done.304. Include a **Suggested skills** section listing skills the next agent should invoke (by name), with one line each on why.315. **Do not duplicate** content already in PRDs, plans, ADRs, issues, commits, or diffs — **reference by path or URL**.326. **Redact** API keys, passwords, tokens, and PII.337. If the user passed arguments (or a slash-command argument), treat them as the next session's focus and tailor the document accordingly.3435## Document template3637Use this structure (omit empty sections):3839```markdown40# Handoff: [short title]4142## Purpose4344Why we are handing off and what the next session must accomplish.4546## Context4748Decisions, constraints, and background the next agent needs (compressed).4950## Current state5152What is done, in progress, or blocked in this session.5354## Artifacts5556Pointers only — paths, URLs, issue numbers, branch names.5758## Open questions5960Unresolved items for the next session to answer or validate.6162## Suggested skills6364- `skill-name` — why to invoke it6566## Out of scope6768What this handoff explicitly does **not** include (keeps the next session focused).69```7071## Quality bar7273- **Slice, don't dump** — only context relevant to the stated next-session purpose.74- **Actionable** — the next agent should know the first concrete step.75- **Portable** — readable without this chat; no "as discussed above."76- **Short** — prefer pointers over pasted prose.7778## Common patterns7980For parallel side tasks and cross-agent review, see [references/patterns.md](references/patterns.md).
nearform