Handoff

Handoff — Move Context Between Agent Sessions

Overview

Mid-session, you notice something out of scope — a refactor opportunity, a prototype that needs a fresh 100k-token context window, a security issue, a parallel investigation. You don't want to dilute your current session by switching, and you don't want to lose the relevant context.

/handoff compresses the relevant slice of the current conversation into a markdown document saved to /tmp/. A fresh agent session (any tool — Claude Code, Codex CLI, Copilot CLI, Gemini CLI) can then pick it up and continue the work.

This is a locally-forked version of Matt Pocock's mattpocock/skills/handoff. The upstream is 6 directives, prompt-only, deliberately minimal. This fork adds ecosystem-aware behaviour for our forge/bob/alf/pa/evo/wiki workflow.

Companion skills:

• forge — invoke from the handoff if the work is MEDIUM/COMPLEX (design needed)
• pa — file the handoff as a tracked task if it needs persistent visibility
• cross-project-mail (cpmail) — alternative when the handoff target is another project on the same host (cross-project rather than cross-session)
• secret-scanning — defense-in-depth redaction layer for the handoff body
• exit-with-docs — sister skill that updates tasks.md/history.md at end-of-session (handoff is for mid-session, exit-with-docs is for end-of-session)

1. When to use vs alternatives

2. Output format

The handoff doc is markdown saved to /tmp/handoff-<topic>-<YYYY-MM-DD>-<short-uuid>.md (or %TEMP%\handoff-... on Windows). Structure:

# Handoff: <one-line topic>

**Source session:** <best-effort identifier — claude-code-session-id if available, else "current session 2026-MM-DD">
**Created:** 2026-MM-DD HH:MM:SS<tz>
**Complexity classification:** TRIVIAL | SIMPLE | MEDIUM | COMPLEX
**Suggested skills:** <comma-separated list of skills the next session should invoke>
**Target tool:** any (Claude Code | Codex | Gemini | Copilot) | <specific if appropriate>

---

## 1. Purpose

<one paragraph: what the next session needs to accomplish, expressed in terms of OUTCOME not steps>

## 2. Relevant context from this session

<pointer pack — NO duplication. Reference each artifact by absolute path with one-line "what's in it">

- **PROJECT.md** — `/path/to/PROJECT.md` (architecture map; read first if unfamiliar with project)
- **history.md** — `/path/to/history.md` (recent session entries 2026-MM-DD..)
- **tasks.md** — `/path/to/tasks.md` (task #N relevant; section "Active Tasks")
- **Design docs** — `/path/to/docs/plans/2026-MM-DD-<topic>-design.md` (if forge cycle ran)
- **Ledger entries** — `/path/to/.ledger/...` (if contract-driven work)
- **Bob checkpoint** — `/path/to/.bob-checkpoint.md` (if mid-execution)
- **Recent commits** — `git log --oneline -5` output (or specific SHA references)

## 3. What this session has already established

<2-5 bullets: facts that the next session shouldn't re-derive>

- Fact 1 with evidence pointer
- Fact 2 with evidence pointer
- ...

## 4. Open question(s) for the next session

<the actual work — what does the next session need to figure out / build / decide?>

## 5. Suggested approach

<2-4 sentences. Includes which skill to invoke first per the complexity classification.>

For MEDIUM/COMPLEX: "Invoke `forge` first."
For SIMPLE: "Invoke `<domain-skill-name>` directly."
For TRIVIAL: "Handle directly; no skill needed."

## 6. Constraints / non-goals

<bulleted list — what's OUT of scope for the next session>

## 7. How to verify success

<1-3 bullets — what the next session's done-condition looks like, with evidence>

---

_Generated by the `handoff` skill v1.0 (local fork). This doc is disposable; if the work merits permanent tracking, file `tasks.md` entry #N or commit the design doc._

3. Complexity classification (drives the Suggested skills section)

Inherit from CLAUDE.md routing rules:

Default if uncertain: MEDIUM (matches CLAUDE.md default).

4. Ecosystem-aware pointer pack

When generating the "Relevant context" section, check for each of these and include if present:

# Project context files
[ -f "$PWD/PROJECT.md" ]            && include
[ -f "$PWD/history.md" ]            && include   # head + tail if >400 lines
[ -f "$PWD/tasks.md" ]              && include   # specific task IDs if relevant
[ -f "$PWD/session_control.md" ]    && include
[ -f "$PWD/index.md" ]              && include

# Forge/bob state
[ -d "$PWD/.forge/" ]               && include   # forge-session-id, signed contract map sig
[ -f "$PWD/.bob-checkpoint.md" ]    && include   # mid-execution state
[ -d "$PWD/.ledger/" ]              && include   # contract-driven artifacts
[ -d "$PWD/.design-ledger/" ]       && include   # design skeletons
[ -d "$PWD/.process-observations/" ] && include   # observability friction signals

# Design docs
ls "$PWD/docs/plans/" | tail -3     && include   # most recent design docs

# Wiki bindings (if .wiki-link exists)
[ -f "$PWD/.wiki-link" ]            && include   # bound wiki(s) for prior knowledge

# Recent git history
git -C "$PWD" log --oneline -5      && include   # last 5 commits

NEVER copy file contents into the handoff doc. ALWAYS reference by absolute path + one-line "what's in it".

5. Secret-scanning integration (HARD-RULE 3 implementation)

Before writing the handoff doc:

1. Tier 1 (always): apply the regex catalog from scripts/secrets-scan.sh to the handoff body. Replace matches with [REDACTED-<type>] (e.g. [REDACTED-AWS-KEY], [REDACTED-JWT]).

2. Tier 2 (defense-in-depth, if installed): if gitleaks is on PATH (check ~/.claude/state/inventory.json), write to a temp staging file first, run gitleaks dir <staging-dir> --no-banner --redact --exit-code 1, abort write on findings. Same for trufflehog --only-verified.

3. Tier 3 (user trust check): explicit reminder in the doc body — <!-- This handoff doc lives in /tmp/ and is not encrypted. Treat as semi-public. -->

A handoff that fails Tier 2 scan must NOT be written until the user explicitly waives. Bare "I checked and there's no secret" assertions don't qualify — the scan log must be in the chat.

6. Anti-patterns

7. Selection Cheatsheet

• Spotted a security issue mid-bob-WP → emit /handoff to /tmp/, file tasks.md entry #N, continue WP (bob HARD-RULE)
• Need to prototype something with fresh 100k context → /handoff + dispatch Claude Code on the handoff path
• Mid-design, found a sub-design → /handoff for the sub-design; current forge keeps the parent design
• Want to ask Codex / Gemini about an out-of-scope question → /handoff + open the file in the other tool
• End of session, multiple tasks done → exit-with-docs, not /handoff
• Cross-project ping → cpmail, not /handoff
• Tracked work item → pa task entry + optional handoff doc for context

8. Update triggers (alf scans these)

• Pocock's upstream handoff skill releases an update (mattpocock/skills)
• A new ecosystem state file appears (e.g. .something-ledger/) and isn't yet in the pointer-pack inspection list
• Secret-scanning regex catalog updates (in-house, gitleaks, or trufflehog patterns)
• Annual review on 2027-05-25

9. See Also