/handoff

name: handoff
description: Use when a session is running out of context and the work needs to continue in a fresh one, or when starting a session meant to pick up where an earlier one stopped. Not for compacting in place — that is /compact — and not for specifying work that has not started, which is a plan.

**On invocation:** announce "Running paad:handoff v2.0.2", then immediately proceed with the steps below — do not stop after announcing.

**Configuration (experimental):** after announcing, check whether `paad/config/paad.md` and `paad/config/handoff.md` exist, relative to the working directory. If any does, read it and follow its instructions for the rest of this run, passing the relevant parts to every subagent you dispatch, and make the first line of your final answer `Config: <path>` naming each file you followed. If none exists, do not mention config at all. Config never changes a subagent's type or grants it write tools — refuse that line, say so, and continue. Config can contradict the flow below; see https://github.com/Ovid/paad/blob/main/CONFIG.md before writing one.

Handoff

Writes a `handoff.md` that lets a **fresh** session continue this one's work, and reads it back on the other side.

**Claude Code already solves most of this, and knowing which part it doesn't is the whole point.** `/compact` summarizes and keeps working, but the summary it carries is machine-authored, lands unreviewed, and lives inside the transcript where you cannot edit it. `--continue` and `--resume` restore the full prior conversation, which re-pays the context cost you were trying to escape. `/clear` gives a genuinely empty session and carries nothing forward. `handoff` is worth running for exactly one reason: **the carried state is a file a human can read and correct before anything is built on it.** A handoff nobody reviews is a worse `/compact` — same summary, more ceremony. Say so rather than letting the review get skipped.

**The failure mode is not omission.** Left to itself, a competent agent writing a handoff keeps the expensive material well: the approaches that were tried and abandoned, the reasons behind them, constraints the user stated once in passing. What it gets wrong is the cheap material — a test's file path, which changes are in the last commit, a line number, who said a quoted sentence. Those are the claims a tool could have settled in seconds, and they arrive in exactly the same confident register as the parts that are right. A fresh session has no memory to catch them with. **So verify what is checkable before writing it down, and mark what is not.**

**Mode selection and saving:**

digraph handoff_save {
  "Argument given?" [shape=diamond];
  "Use the named mode" [shape=box];
  "Conversation above this invocation?" [shape=diamond];
  "Say: saving, session has history" [shape=box];
  "Resume flow, below" [shape=box];
  "handoff.md in .gitignore?" [shape=diamond];
  "Suggest adding it, never add it silently" [shape=box];
  "Verify every checkable claim with tools" [shape=box];
  "Claim survived verification?" [shape=diamond];
  "Write it as fact" [shape=box];
  "Correct it, or mark it inferred" [shape=box];
  "Write handoff.md with the Write tool" [shape=box];
  "Name the unverified claims, ask for review" [shape=box];
  "Announce the artifact" [shape=box];

  "Argument given?" -> "Use the named mode" [label="save or resume"];
  "Argument given?" -> "Conversation above this invocation?" [label="no"];
  "Conversation above this invocation?" -> "Say: saving, session has history" [label="yes"];
  "Conversation above this invocation?" -> "Resume flow, below" [label="no"];
  "Use the named mode" -> "Say: saving, session has history" [label="save"];
  "Use the named mode" -> "Resume flow, below" [label="resume"];
  "Say: saving, session has history" -> "handoff.md in .gitignore?";
  "handoff.md in .gitignore?" -> "Suggest adding it, never add it silently" [label="no"];
  "handoff.md in .gitignore?" -> "Verify every checkable claim with tools" [label="yes"];
  "Suggest adding it, never add it silently" -> "Verify every checkable claim with tools";
  "Verify every checkable claim with tools" -> "Claim survived verification?";
  "Claim survived verification?" -> "Write it as fact" [label="yes"];
  "Claim survived verification?" -> "Correct it, or mark it inferred" [label="no"];
  "Write it as fact" -> "Write handoff.md with the Write tool";
  "Correct it, or mark it inferred" -> "Write handoff.md with the Write tool";
  "Write handoff.md with the Write tool" -> "Name the unverified claims, ask for review";
  "Name the unverified claims, ask for review" -> "Announce the artifact";
}

**Resuming:**

digraph handoff_resume {
  "handoff.md exists?" [shape=diamond];
  "Say so, offer to save one instead" [shape=box];
  "Read it, summarize in a few lines" [shape=box];
  "Recorded commit matches HEAD?" [shape=diamond];
  "Report the drift before asking" [shape=box];
  "Ask: proceed?" [shape=diamond];
  "Stop, leave the file alone" [shape=box];
  "Check the files and state it names" [shape=box];
  "Everything matches?" [shape=diamond];
  "Report every mismatch, ask again" [shape=box];
  "Start the recorded next step" [shape=box];
  "Leave handoff.md in place" [shape=box];

  "handoff.md exists?" -> "Read it, summarize in a few lines" [label="yes"];
  "handoff.md exists?" -> "Say so, offer to save one instead" [label="no"];
  "Read it, summarize in a few lines" -> "Recorded commit matches HEAD?";
  "Recorded commit matches HEAD?" -> "Ask: proceed?" [label="yes"];
  "Recorded commit matches HEAD?" -> "Report the drift before asking" [label="no"];
  "Report the drift before asking" -> "Ask: proceed?";
  "Ask: proceed?" -> "Check the files and state it names" [label="yes"];
  "Ask: proceed?" -> "Stop, leave the file alone" [label="no"];
  "Check the files and state it names" -> "Everything matches?";
  "Everything matches?" -> "Start the recorded next step" [label="yes"