Handoff

---
name: handoff
description: Prepares the session handoff (Claude Code, Codex, Cursor, Gemini, OpenCode...) before context rot - saves the state of the work so the next session can resume with /pickup. Use when the context is getting full, or when asked to "prepare the handoff", "write the handoff" or "give me a prompt to continue in another session".
---

# Handoff

Only prepares and saves. To resume, the next session uses `/pickup`.

## How to do it

Do not continue the task. Only record its state.

1. Identify only projects actually involved in the task from the session and verified workspace state. Distinguish the session working directory from each project and its actual checkout or worktree. For each relevant Git checkout, inspect branch, HEAD and uncommitted work without changing it; record unknown or unavailable facts as such. Never include secrets. Write the handoff in this format, with concrete facts (IDs, paths, values, commands), nothing generic:

```markdown
---
agent: <claude-code | codex | cursor | gemini | opencode | ...>
model: <exact model identifier if known, otherwise unknown>
folder: <absolute working directory>
branch: <current branch, if it is a git repository>
date: <YYYY-MM-DDTHH:MM, local time>
---

## <short task title>

### Goal
One sentence: what we are trying to deliver.

### Summary for whoever arrives
Two or three sentences so an agent with no context can get oriented at once.

### Projects involved
- For each project: name, absolute project path, role in the task, actual checkout or worktree path, and, if Git applies, branch, HEAD and uncommitted work. State explicitly when a fact could not be verified.

### Intent of the next step
Why the next step is the one it is: the hypothesis being tested, what we expect to see.

### Done
- What is already finished and verified.

### Facts discovered
- IDs, values, states, paths found in this session.

### Discarded
- Paths tried and abandoned, and why.

### Next steps (this task)
1. The first step to execute.
2. ...

### Pending decisions
- What only the user can decide, with the options.

### Other open items
- Subjects outside this task. The next session must NOT jump to them.
```

2. If the Cruise relay supplies an explicit handoff file path, save to that exact path. Otherwise save to `~/.local/state/handoffs/<folder-slug>/<YYYY-MM-DD-HHMM>.md`, where the slug is the working directory path with `/` replaced by `-`. If that name already exists, append a unique suffix; never overwrite an earlier handoff. Create the folder if it does not exist.
3. Optional ai-memory mirror. The file from step 2 is the handoff; this step only mirrors it. If this session has an ai-memory MCP server (any tool named like `memory_handoff_begin`, even if only its name is listed as a deferred tool), load that tool first (in Claude Code: `ToolSearch` with `select:mcp__ai-memory__memory_handoff_begin`) and register the same content there. If no ai-memory server is present, skip this step without comment. If loading or the call fails, say so and quote the error.
4. Reply with the harness and model, session working directory, every involved project and its absolute path and role, the objective, what is done and the next step, the absolute handoff file path, and whether it also went to ai-memory (yes, no server, or failed with the error). Include a short ready-to-copy continuation prompt containing those facts, pending decisions and the exact handoff path; tell the next agent to read that file, verify the projects and continue the next step. Use only verified model information; write `unknown` if unavailable. Say that `/pickup` can take the explicit file path, or can be run without a path after clearing or opening a session in the same working directory. Do not include secrets.

For immediate continuation in the same environment use `/go-around <exact handoff path>`; use `/pickup <exact handoff path>` for a checked resumption later.