Handoff

Handoff: Move Context Between Agent Sessions

Compress the current session into a small markdown document another agent session can continue from. A handoff is a one-way, lossy carry: whatever the next session needs has to be written down explicitly, because everything else is gone.

The point is to keep each session focused and inside its high-attention context window instead of dragging one bloated thread forward.

Inspired by Matt Pocock's /handoff skill. The failure mode it exists to prevent is relitigation: the next session reopens a decision the current one had already settled, because the doc recorded what was decided but not why. Every locked decision carries its rationale for this reason.

When to use

• Switching roles across sessions: planner -> implementer, implementer -> reviewer
• Kicking off an AFK or unattended run from a clean context
• Fanning out to parallel sessions that each own one slice of the work
• Prototyping or spiking in a throwaway session without polluting the current one
• The current context window is full or degrading and you want a fresh start with only essentials
• User says "hand this off", "write a handoff", "continue this in a fresh session"

When NOT to use

• Capturing feature ideas or backlog items - use roadmap
• Running the full branch -> implement -> test -> PR -> merge workflow - use dev-cycle
• Choosing which skill should handle the current request - use skill-router
• Writing durable project documentation, READMEs, or changelogs - use update-docs
• Composing commit, PR, or MR text - use git
• A heavyweight, phase-coupled pause inside a GSD planning workflow - use GSD's pause-work. This skill is the lightweight, plugin-agnostic version: one disposable doc, no phase state

AI Self-Check

Before writing or returning a handoff doc, verify:

• Purpose stated: the next session's job is one or two clear sentences at the top
• Decisions carry rationale: every locked decision says why, not just what, so the next session does not relitigate it
• State is tagged: each current-state item is marked verified, assumed, or blocked so the next session knows what it can trust without rechecking
• Pointers, not paste: artifacts are referenced by path, file:line, PR, or branch - not copied in, which would bloat the carry and drift from the source
• No secrets: API keys, passwords, tokens, PII, and internal URLs are redacted
• Suggested skills listed: the next session is told which skills to invoke for its task
• Small enough to fit: the doc is short enough to sit in the next session's high-attention zone - if it is long, cut detail and lean harder on pointers
• Gitignored: .handoff/ is in .gitignore unless the user asked to commit the doc
• Spec claims verified: pointers (paths, line numbers, PR numbers, branches) are confirmed to exist at write time, not assumed
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

The handoff document

One purpose-driven markdown file. Sections in this order; omit a section only when it is genuinely empty.

# Handoff: {one-line purpose}

> Written: {date} | {Disposable working doc | Committed for review} | From: {short note on the source session}

## Purpose

{What the next session is for. One or two sentences. The single most important field -
if the next agent reads only this, it should still know what to do.}

## Locked decisions

Settled. Do NOT reopen these.

- {Decision} - because {rationale}
- {Decision} - because {rationale}

## Deferred

Deliberately not doing now. Recorded so the next session does not relitigate them. Omit if empty.

- {Ruled out for now} - because {rationale}; revisit when {trigger}

## Current state

- [verified] {Done and confirmed} - confirmed by {test, command, or observation}
- [assumed] {Believed true but unchecked} - verify by {command or check} before relying on it
- [blocked] {Stuck} - waiting on {what}

## Next steps

1. {Concrete action}
2. {Concrete action}

## Pointers

References, not copied content.

- `{file:line}` - {what is there}
- PR #{n} / branch `{name}` - {status}
- `{spec or doc path}` - {what it covers}

## Suggested skills

- **{skill}** - {why the next session needs it}

Keep it lossy on purpose. A handoff is not a transcript; it is the minimum the next session needs to act without re-deriving context. When in doubt, point at the artifact rather than pasting it.

Performance

• Favor pointers over pasted content; a handoff that reproduces files defeats its own purpose.
• Keep the doc short enough to land in the next session's high-attention window (degradation sets in well before a context window is technically full).
• Write one handoff per next-session purpose. Fanning out to three parallel sessions means three focused handoffs, not one doc the readers must filter.

Best Practices

• Lead with purpose. Everything else serves the one job the next session has to do.
• Pair every locked decision with its reason so the next session inherits the conclusion, not the debate.
• Tag confidence honestly: mark unverified beliefs as assumed so the next session does not build on sand.
• Redact before you write, not after. Secrets that reach the file have already leaked.

Workflow

Mode 1: Author a handoff (default)

Step 1: Name the next session's purpose

State, in one or two sentences, what the next session is for. If the user gave a purpose as the argument, use it. If not, infer it from the current work and confirm in the doc's Purpose section. Everything downstream is selected to serve this purpose - context irrelevant to it is dropped.

Step 2: Extract decisions and their rationale

Walk the current session for decisions that are settled: choices of approach, tradeoffs resolved, things ruled out. For each, record the decision and the reason it was made. The rationale is not optional - it is the specific thing that stops the next session relitigating.

Step 3: Capture state, tagged by confidence

Summarize where things stand. Tag each item:

• verified - done and confirmed, with how it was confirmed
• assumed - believed true but not checked; name the command or check that would verify it, so the next session can confirm before relying on it
• blocked - stuck, and on what

Do not present assumptions as facts. A mistagged assumption is how the next session inherits a bug as a foundation.

Step 4: Collect pointers, redact secrets

Reference the artifacts the next session needs: file:line, spec and doc paths, PR numbers, branch names. Confirm each pointer resolves at write time - check that the file and line exist rather than trusting a remembered location, because a stale line number sends the next session to the wrong place. Do not paste file contents.

While collecting, strip any secrets: API keys, passwords, tokens, PII, internal URLs, connection strings. This includes secrets that surfaced in the session itself - a value the user pasted into the chat or that printed to a log is just as sensitive as one read from a file. Redact by reference, not by partial value - point at where the secret lives so the next session can resolve it, and never write a fragment that is itself sensitive (a host, a port, half a token):

• REDIS_URL env var
• credentials loaded from .env.local
• {REDACTED} when there is nowhere to point

If the secret's only source is volatile - shell history, a pasted chat message, console output - there is no durable place to point at. Tell the next session to re-provision it from the real secret store, not to recover the leaked value.

Step 5: Suggest skills and next steps

List the concrete next actions, and the skills the next session should invoke for its task - pick the smallest set that covers the work, the way skill-router would (e.g., a "implement and test a Redis denylist" next step suggests testing for the tests, plus whichever domain skill fits the implementation). This primes the fresh session to start with the right tool instead of rediscovering it.

Step 6: Write the file

Disposable (default). Write to .handoff/YYYY-MM-DD-{slug}.md in the working directory and keep it out of version control:

1. Ensure .handoff/ is gitignored. If .handoff/ (or a covering entry) is not in .gitignore, add it:

   # Disposable agent handoff docs
   .handoff/
   

   Inform the user: "Added .handoff/ to .gitignore. Tell me if you want this handoff committed instead."
2. Set the header's middle field to Disposable working doc.
3. Write the doc and report the path so the user can pass it to the next session.

Committed (when the user wants it tracked - e.g. visible in a PR). Do not write into the gitignored .handoff/; that only forces a git add -f fight. Instead:

1. Write to a tracked path. Default to docs/handoffs/YYYY-MM-DD-{slug}.md; use the location the user named if they gave one, or follow an existing repo handoff convention if there is one.
2. Set the header's middle field to Committed for review.
3. Write the doc, then commit it via git. Report the path.

Mode 2: Resume from a handoff

Trigger: user points at an existing handoff doc ("resume ", "continue from this handoff").

1. Read the handoff doc.
2. Treat Locked decisions as settled - do not reopen them. If one looks wrong, flag it to the user rather than silently relitigating.
3. Verify pointers still resolve (files, line numbers, branches, PRs). Note any that have moved or gone stale before relying on them.
4. Re-check anything tagged assumed before building on it.
5. Invoke the suggested skills and start on the next steps.

A disposable handoff has served its purpose once the next session is underway and can be deleted; a committed one stays in the repo as a record of the PR it shipped with.

Output Contract

See references/output-contract.md for the full contract.

• Skill name: HANDOFF
• Deliverable bucket: deliverables
• Mode: conditional. When invoked to author or resume a handoff (its primary mode), respond freely without the contract; the handoff doc is written to .handoff/ in the working directory, not to docs/local/. When invoked to review or audit existing handoff docs (e.g., "check whether these handoffs are leaking secrets or relitigating"), emit the full contract - monospace inline header, severity-grouped inline summary, linked Markdown deliverable, and concise monospace conclusion - and write the deliverable to docs/local/deliverables/handoff/<YYYY-MM-DD>-<slug>.md.
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

• skill-router - reason the same way when filling the Suggested skills section: pick the smallest useful skill set for the next session's purpose.
• dev-cycle - runs the full development workflow in one session; handoff carries context between sessions when that workflow spans more than one.
• roadmap - captures what to build over time; handoff carries the live state of one piece of work to the next session. Ideas there, in-flight context here.
• git - use it to commit a handoff when the user wants it durable instead of disposable, or to resolve branch and PR pointers when authoring one.
• update-docs - writes durable project documentation; a handoff is a throwaway working doc, not documentation.

Rules

1. Purpose first. Every handoff opens with the next session's job in one or two sentences. No purpose, no handoff.
2. Every decision carries its why. A locked decision without a rationale invites relitigation. Record the reason or do not lock it.
3. Pointers, not paste. Reference artifacts; never copy file contents into the handoff.
4. Tag confidence. Mark state verified, assumed, or blocked. Never present an assumption as a fact.
5. Redact secrets. Strip API keys, passwords, tokens, PII, and internal URLs before writing.
6. Gitignore by default. Ensure .handoff/ is gitignored unless the user asks to commit the doc.
7. Keep it small. The handoff must fit the next session's high-attention window. Cut detail and lean on pointers before it grows large.
8. Do not relitigate on resume. Treat a handoff's locked decisions as settled; flag a wrong one to the user instead of silently reopening it.
9. Headless mode. In non-interactive contexts (--bare, Cursor Automations, Codex exec): write to .handoff/, add the gitignore entry without prompting, and report the path.