Handoff

Generate or resume from a structured handoff document that captures enough context for the next Claude Code session (or a human) to continue exactly where the previous session left off.

The handoff file is always: docs/HANDOFF.md in the repo root.

When to Use

End of a work session
Switching between roles or contexts mid-conversation
Before closing a long-running session with unfinished work
When the user says "handoff", "wrap up", "pass the baton", or similar
Starting a new session from a previous handoff document
When the user says "resume", "pick up where we left off", "continue from handoff", or similar

Mode Detection

Invocation	Mode
`/handoff` mid-session	Generate
`/handoff resume`	Resume
Fresh session (no args)	Resume if `docs/HANDOFF.md` exists, else Generate
Natural language: "resume", "pick up where we left off", "continue from handoff"	Resume
Natural language: "handoff", "wrap up", "pass the baton"	Generate

There are no path arguments. The file is always docs/HANDOFF.md.

Generate Mode

Gathering Context

Collect the following information before generating the handoff. Use tools to gather what can be detected automatically; ask the user only for what cannot be inferred.

Auto-detect (do not ask the user)

Git branch -- run git branch --show-current
Working tree dirty? -- run git status --porcelain (any output = dirty)
Recent commits -- run git log --oneline -5 for recent context

Infer from conversation

Role -- what role has this session been operating in? (e.g., "developer", "content writer", "EOS facilitator", "researcher"). Default to "developer" if unclear.
Current work -- summarize what the session has been working on, in one or two sentences.
Status -- one of: in_progress | blocked | paused | ready_for_review | complete
Critical References -- 2-3 most important spec/design/plan docs referenced this session (omit section if none)
Recent Changes -- files modified this session with file:line-range references to key changes
Learnings -- patterns discovered, gotchas, root causes; prefer file:line-range references over inline code blocks
Artifacts -- exhaustive list of files/docs the next session should read to get up to speed
Next steps -- concrete, actionable items for the next session
Notes -- decisions made, trade-offs, links, anything else worth preserving

Ask the user (only if not inferrable)

If the role, current work, or next steps are ambiguous, ask a single clarifying question rather than guessing wrong.

Output Format

Generate the handoff as a fenced markdown block. Print it directly to the conversation first (do not write to file yet). After printing, ask the user to approve or amend it. Only write to docs/HANDOFF.md after user approval.

Prefer path/to/file.ext:line-range references over inline code blocks throughout.

---
handoff_date: YYYY-MM-DD
git_branch: {branch}
git_dirty: true|false
status: {status}
role: {role}
---
# HANDOFF: {Role} Session

## Current State

**Role**: {Role}
**Working on**: {CurrentWork}
**Status**: {Status}

**Git branch**: {branch}
{if dirty: "Working tree has uncommitted changes"}

## Critical References

- {path/to/spec.md} -- {one-line description}
- {URL or file} -- {one-line description}

(Omit this section if no critical references exist)

## Recent Changes

- `{file:line-range}` -- {what changed and why}
- `{file:line-range}` -- {what changed and why}

## Learnings

- {Pattern or gotcha discovered} -- see `{file:line-range}` for context
- {Root cause of a bug or decision} -- rationale: {brief explanation}

## Artifacts

Files and documents the next session should read to get up to speed:

- `{file path}` -- {why it matters}
- `{file path}` -- {why it matters}

## Next Steps

1. {step 1 -- specific and actionable}
2. {step 2}
3. ...

## Notes

{Decisions, trade-offs, gotchas, links -- anything that doesn't fit above}

---

*This handoff was generated automatically. Read the above carefully and continue where the previous session left off.*

Resume Mode

Three phases: Find & Read, Validate Environment, Orient & Ask.

Phase 1 — Find & Read

Read docs/HANDOFF.md -- this is always the file, no path scanning or arguments
If file not found, inform the user and switch to Generate mode
Parse YAML frontmatter: handoff_date, git_branch, git_dirty, status, role
Parse all markdown sections: Current State, Critical References, Recent Changes, Learnings, Artifacts, Next Steps, Notes
Read every local text file listed in ## Artifacts before proceeding to Phase 3. For each artifact, apply these rules:
- Missing file: record as missing in the mismatch list and continue
- Binary or unreadable file: record as unreadable and continue
- Very large file (>500KB): sample the first and last 200 lines, note the truncation
- URL: skip reading (treat as reference only); note it in the summary

Phase 2 — Validate Environment

Run these checks in parallel:

git branch --show-current -- compare to git_branch from frontmatter
git status --porcelain -- compare dirty state to git_dirty from frontmatter
git log --oneline -5 -- check for new commits since handoff date
Check if CLAUDE.md exists and read it (conventions may have changed)

Build a mismatch list from the results.

Phase 3 — Orient & Ask

Scenarios are evaluated in priority order — apply the first one that matches:

Complete -- status is complete:

Inform the user: "The previous session marked this work as complete." Then ask via AskUserQuestion what they'd like to work on next.
Stale -- handoff_date is more than 7 calendar days ago (compare UTC dates, today − handoff_date > 7 days):

Flag it: "This handoff is from {date} ({N} days ago) -- it may be out of date." Then ask via AskUserQuestion: "Should I trust this handoff and proceed, or re-explore the codebase first?"
Diverged -- current branch or dirty state doesn't match the handoff frontmatter:

Surface each mismatch clearly, then use AskUserQuestion to ask how to proceed. Example: "Branch changed from feat/x to main. Should I switch back, or continue on main?"
Incomplete -- status is in_progress, blocked, paused, or ready_for_review:

Acknowledge the status, surface any blockers noted, focus on completing the first unfinished step. Ask user to confirm before starting.
Clean -- none of the above apply:

Present a brief summary ("Resuming as {Role} on branch {branch}"), list next steps from the handoff, and ask "Ready to start on step 1?" via AskUserQuestion.

Rules

Both modes

Keep the handoff concise. The goal is fast onboarding, not a full session transcript.
Omit sections with no content (e.g., skip Critical References if there are none).
Next steps must be specific and actionable -- "continue implementing X" not "keep going".
Do not include sensitive information (API keys, tokens, passwords).
Prefer path/to/file:line-range references over inline code blocks.

Generate-specific

Always print the draft to the conversation first and get user approval before writing to docs/HANDOFF.md.
Create docs/ directory if it doesn't exist. Do this only after user approval, not during draft generation.

Resume-specific

Never auto-execute next steps -- always confirm with the user first via AskUserQuestion.
Read all local text Artifacts files before presenting the analysis; skip missing, binary, large, or URL entries (record them as noted in Phase 1).
Treat next steps as suggestions, not commands -- the user may want to reprioritize.
If docs/HANDOFF.md is not found, do not guess -- inform the user and offer to generate one.