Handoff

handoff

Compact the current conversation into a single self-contained Markdown document that a fresh agent can read at the start of the next session and immediately know: what to do, what's already done, what's blocked, and which skills/files to touch. Save it to the OS temp directory (NOT the workspace) so it doesn't accidentally get committed.

The handoff doc is a briefing, not a transcript. It references — never duplicates — content that already lives in other artifacts (PRs, plans, design docs, commits, memory entries, ADRs, issue trackers).

See [README.md](README.md) for the credit (Matt Pocock's original handoff) and install / use instructions.

When to invoke

Fire on any of:

• User invokes /handoff (optionally with an argument describing the next session's focus).
• User says "create a handoff doc", "write a handoff document", "compact this", "pass off to another session", "checkpoint this conversation".
• User says "what will the next session focus on" or "I'll pick this up tomorrow".
• User signals an imminent context-window break and wants the work to survive.

When NOT to invoke

• Mid-task, when the user wants you to keep going. Handoff is a session-boundary ritual, not a status update mid-conversation.
• For one-off questions ("what's the status?") — answer directly; don't write a file.
• When the conversation is short ( --author "@me" --state open

gh pr view --json state,reviewDecision,mergeStateStatus,headRefOid # for each in-flight PR date -u +"%Y-%m-%dT%H:%M:%SZ" # timestamp

Also scan the recent conversation for:

- **In-flight PRs** + their status + any pending review comments.
- **Recently merged work** (last 1–2 PRs) and their merge commits.
- **Open questions / decisions** the user deferred or you couldn't resolve without them.
- **External dependencies** (waiting on Codex review, waiting on CI, waiting on user input).
- **Memory entries** that materially shaped recent decisions (cite them by filename — don't quote the body).

## Step 3 — Choose the output path

OS temp directory, NOT the workspace. On macOS the canonical user-facing temp is `/tmp/` (symlinked to `$TMPDIR` for the user's session). On Linux, `/tmp/` is standard. Filename pattern:

/tmp/handoff--.md

Where `` is 3–5 words summarising the next session's focus (e.g. `slice-3-and-skill`, `respond-codex-pr-364`, `bootstrap-rebuild`).

If `/tmp/` doesn't exist or isn't writable (rare), fall back to `$(mktemp -d)/handoff.md` and report that path.

**Never** write to:
- The repo workspace (`./`, `../`, anywhere under the current project).
- The user's home dir outside `~/.claude/`.
- `~/.claude/plans/` (that's for plan-mode artifacts; handoffs are not plans).

## Step 4 — Identify references (don't duplicate)

Before writing a single line of doc body, enumerate every artifact that *already* captures something you'd otherwise restate. Reference these by path or URL; don't paraphrase their content.

| Artifact type | Common locations | How to reference |
|---|---|---|
| Design docs | `docs/design/**/*-design.md`, `project-management/**/*-design.md`, `architecture/**/*.md`, ADR folders | Path + section anchor (e.g. `docs/design/foo-design.md §4.5`) |
| Implementation plans | `/**/*-plan.md` | Same |
| Peer-review threads (Codex, another Claude, human reviewer) | `/.dialogue/*-review-thread.md`, `/**/*-review-thread.md` | Path; note whether closed (Final ACK both sides) or open |
| Open PRs | GitHub / GitLab | URL + PR number; cite head SHA |
| Merged PRs | Same | URL + merge commit SHA |
| Recent commits worth flagging | git history | SHA + one-line subject |
| Auto-memory entries | `~/.claude/projects//memory/*.md` | Filename only (no body) — the next agent reads `MEMORY.md` on session start |
| Per-package / per-module specs | `packages//{SPEC,CLAUDE}.md`, `apps//CLAUDE.md`, `/SPEC.md` | Path; note "assume loaded" for the next session |
| Plan files from plan-mode | `~/.claude/plans/.md` | Path; note approval status |

If you find yourself wanting to write out a 10-bullet summary of a doc, **stop and reference the doc instead**. The next agent reads what they need; pre-digesting wastes context.

## Step 5 — Write the doc

Canonical structure — adapt section names but keep this order:

```markdown
# Handoff —  ()

**Repo**:  (one-line description)
**Branch at handoff**: `` (clean | dirty: )
**Working tree**: 

## Mission for next session

## Where we are

### Recent merge / open PR / pending work

### Canonical artifacts to read first

## Active work / context anchors

### Anticipated review push-back (when waiting on a peer review)

### Key memories worth recalling

## Suggested skills

## Open questions / decisions for the next session

## How to start the next session cleanly

 with .>

## Hand-off complete checklist

- [x] Branch state clean OR uncommitted changes documented above.
- [x] In-flight PR description has the full state-of-play; no comments need response from THIS session.
- [x] No secrets / PII in this doc.
- [x] References (not duplication): all canonical artifacts cited with paths/URLs/SHAs.

---

*Generated . Source conversation covered:
.*

Step 6 — Redact

Scan the draft for sensitive content before writing:

• API keys / tokens / secrets: any string matching sk-, whsec_, pk_, xoxb-, ghp_, eyJ, JWT-shaped tokens, anything from an .env example. Redact to ` or `.
• Passwords: any line near the word "password", "passphrase", "secret".
• PII: full names other than the user's already-public profile, personal email addresses (other than the user's own as published in repo metadata), phone numbers, addresses, birthdays from journal content. The user's GitHub handle from a PR URL is public and OK.
• Database connection strings with credentials: postgres://user:PASS@host/db → postgres://@host/db.
• Local file paths that include other usernames or sensitive directory names.

When in doubt, redact. Note redactions in a final line: *Redacted: credentials and PII items.*

Step 7 — Print the path

End the chat reply with:

Handoff doc written to .

Optionally add 2–3 sentences summarising the doc's structure (mission + the highest-value addition the doc makes vs. what's already on disk). Don't paste the doc body into chat — it's already in the file.

Doc-shape examples

The most recently written handoff (a worked example you can mimic) is at the path the user last invoked /handoff against. If that's not accessible:

• Two parallel tracks (most common): mission has two numbered items; structure has separate sub-sections per track.
• Single in-flight PR awaiting review: mission = "respond to review on #N"; the "Anticipated push-back" section becomes load-bearing.
• Mid-design pivot: mission = "decide between X and Y approach"; "Open questions / decisions" section is load-bearing.

Anti-patterns (do not do)

• Writing to the workspace. Handoff docs are ephemeral session bridges; they don't belong in git. If the user wants permanent docs, write to wherever the repo keeps them (docs/, project-management/, architecture/, alongside code).
• Paraphrasing the design doc / plan / PR body. Cite them. The next agent reads the artifact directly.
• Dumping the full memory index. Cite only the entries that shaped recent decisions; MEMORY.md loads automatically on session start.
• Mid-conversation handoff ("checkpoint and continue"). Handoff is a session-boundary ritual. If you want a status pin without ending the session, just summarise in chat.
• Asking the user to fill in details before writing. The whole point of handoff is the user is checking out. Mine the state yourself; the only acceptable question is one-line clarification of the mission when truly ambiguous.
• Skipping the "suggested skills" section. Even when no skill obviously applies, suggest the closest ones (grill-me for plans, pair-agent-harness for any peer review, the most-recently-used domain skill). This section is what makes handoffs re-bootable.
• Skipping redaction. Even if the conversation didn't visibly contain secrets, the next agent might widen access; scan systematically.

Validation checklist

Before reporting the path to the user, verify:

• [ ] File written to OS temp dir (path starts with /tmp/ or $TMPDIR), NOT the workspace.
• [ ] Filename matches handoff--.md.
• [ ] Frontmatter sections present in order: Mission, Where we are, Active work, Suggested skills, Open questions, How to start, Hand-off checklist.
• [ ] Mandatory "Suggested skills" section present with ≥2 entries.
• [ ] References use paths/URLs/SHAs; no duplicated content from cited artifacts.
• [ ] Redaction pass complete; sensitive content removed or replaced.
• [ ] Final timestamp + one-line topic summary at the bottom.
• [ ] Hand-off-complete checklist's items all checked (or unchecked items explicitly noted as known-incomplete).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Rijul1204
• Source: Rijul1204/rashedul-agentic-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.