| name | handoff |
| description | Generate a minimal-sufficient handoff when another agent or session will take ownership of a task or continue unfinished work. Use for /handoff, "hand this to the next agent", "let another session continue", session transfer, task ownership transfer, or restarting in a fresh context when the current session has degraded (a handoff to your future self). Reuses durable artifacts by reference instead of copying them, and redacts secrets. |
| metadata | {"short-description":"Minimal-sufficient task handoff"} |
handoff
Compress the current task into a prompt the next agent can start from directly. Issues, context docs, PRs, commits, and diffs are the sources of truth; the handoff only provides entry points, current state, and the necessary not-yet-persisted delta.
The same compression works in three directions: transferring ownership to another agent or session; disciplining spawn contracts when a dispatcher delegates slices (see /fan-out); and restarting yourself — when the current context has degraded (noise from failed explorations polluting decisions), a handoff aimed at your own fresh session beats continuing in the noise. Compaction is just a handoff to your future self.
Language: mirror the user's language.
Core rules
- Reuse durable artifacts first; never copy an existing spec, issue, or checklist into a fourth source of truth.
- Return the handoff in the conversation by default; write a file only when the user asks.
- No fixed length. The standard is: the next agent can start working, and no fact is duplicated.
- Do not create or update issues, write to external systems, or send messages without explicit consent.
- A handoff request does not imply authorization to commit, push, open PRs, or change remote state.
Workflow
- Define the transfer: the next agent's goal, what is in and out of scope, and whether the task is not-yet-started or in progress.
- Discover durable artifacts (read-only): tracking issue, linked PR, authoritative context/ADR docs, current branch/worktree, commits, diff, latest verification results. Record each artifact's path or URL and status; do not restate its content.
- Issue consent gate: if no tracking issue exists, tell the user and ask whether to file one (per the target repo's workflow) or produce a self-contained handoff. Do not file silently. If an existing issue is stale, flag the difference as unpersisted delta instead of silently editing it.
- Compress by reference: for each piece of information — already in a durable artifact → give path/URL + status + anchor only; not persisted but required to continue → state it briefly, marked as unpersisted decision / blocker; irrelevant to the next step → omit. If artifacts conflict with observed state, name the conflict and say which evidence wins.
- In-progress tasks: include branch/worktree, base, dirty files, done/not-done, latest verification, failures or blockers, and the exact next step. Quote only actionable failure conclusions and commands, never whole terminal logs. Never claim unverified work as done.
- Safety pass: strip API keys, tokens, passwords, connection strings, credential-bearing URLs, and PII the task does not need. Keep variable names, replace values with
<redacted>. If a secret looks already-leaked, say it needs rotation without repeating the value.
- Output a copyable handoff prompt with the applicable sections (omit empty ones): Goal / Sources of truth / Current state / Unpersisted decisions & blockers / Next action / Suggested skills. Tell the next agent to read the sources of truth before acting. Suggest only the target repo's skills that the task actually needs; do not invent gates.
Boundaries
- Independent explorer/parallel subtasks whose spawn prompt already states goal, boundaries, and output do not need a handoff first.
- Handoff replaces neither issue filing, context writing, implementation, verification, nor PR workflows; it only compresses state and routes the next step.
