---
name: handoff
description: Use when context is getting full, a session needs to continue elsewhere, or plan execution must be resumed later without losing state.
---

# Handoff - Session Transfer

Create a compact, actionable transfer note so a new session can continue without rediscovering decisions, files, blockers, or plan progress.

## When to Use

- Context is getting heavy or compaction is likely.
- You need to stop but want the next session to continue.
- Work is mid-plan and task status matters.
- A different person or agent will pick up the work.

## The Rule

The next session needs operational state, not a diary. Capture what changed, what is true now, what remains, and the exact first next action.

## What to Capture

1. **Objective** - the user's end goal, not just the last task.
2. **Working directory** - absolute path and target repo/project.
3. **Active plan** - path to the plan/spec if one exists, plus completed and remaining tasks.
4. **Git state** - branch, latest relevant commit, uncommitted files, and whether changes are user-owned or agent-owned.
5. **Verification state** - commands run, results, failures, and what was not verified.
6. **Decisions and gotchas** - constraints, rejected approaches, auth/tool limitations, known fragile points.
7. **Files touched or important references** - absolute paths.
8. **Next step** - one concrete action the new session should perform first.

## Summary Format

```markdown
# Handoff Summary

> **Instructions for new session:**
> - This work was handed off from a previous session.
> - Read this summary before acting.
> - Give the user a brief status recap.
> - Ask for approval before continuing if the next action mutates files, pushes, deploys, deletes, or depends on an unresolved choice.

## Objective
[User's end goal]

## Working Directory
[Absolute path]

## Current State
- Completed:
- In progress:
- Remaining:

## Active Plan / Task Progress
- Plan/spec path:
- Completed tasks:
- Next task:

## Git State
- Branch/worktree:
- Latest relevant commit:
- Uncommitted changes:
- Files changed by user that must not be overwritten:

## Verification
- Ran:
- Result:
- Not verified:

## Decisions / Constraints / Gotchas
- [Decision and reason]
- [Known issue or blocker]

## Important Files
- [Absolute path] - [why it matters]

## Exact Next Step
[Specific first action for the next session]
```

## Guidelines

- Be concise but specific enough to resume without rereading the whole transcript.
- Prefer exact file paths, commands, commit hashes, and task names over prose.
- Include failed attempts only when they prevent repeated work.
- Never claim tests passed unless the command and result are recorded.
- If there is no active plan, say so explicitly.