ad-handoff

name	ad-handoff
description	Compact the current session into a handoff document a fresh agent can pick up from. Saves to the OS temp dir (never the repo). Captures live state — current branch, open artifacts, unresolved decisions, in-progress diff, recent errors — references existing artifacts (PRD / spec / task / ADR) by path instead of duplicating them, and lists suggested next skills. Redacts secrets before writing. Triggers on "handoff", "hand off this session", "compact this conversation", "save context for next session", "pass to another agent", "wrap up the session", "context exhausted", "/clear", "/ad-handoff".
summary	Compact current session into a handoff doc in the OS temp dir. Rebuilds the work as a done/open roadmap checklist, sweeps for asks that never landed, reports repo hygiene without acting on it, binds the next agent to ad-philosophy, references artifacts by path, redacts secrets. Never commits.
allowed-tools	Read, Write, Glob, Grep, Bash

/ad-handoff

Process scaffold for compacting a long or near-exhausted session into a handoff document. Output is a single markdown file in the OS temp directory; the next session reads it and continues. Helper, not blocker — the senior engineer keeps decision authority over what survives the compaction.

The skill exists because long sessions accumulate inherited bias (WORKFLOW §12 — "almost right" failures compound) and because session-window pressure forces ad-hoc summarisation that loses the parts the next agent actually needs. Handoffs replace ad-hoc summarisation with a structured artifact.

Step 0 — Confirm regime

Run when at least one holds:

• The user says "handoff", "hand off", "wrap up", "compact this", "save context", "pass to another agent", "I need to /clear".
• The session has run long enough that context-window pressure is imminent or stated.
• The user is about to switch agents (e.g. Claude Code → Codex, or back) and wants the work to continue.

Route elsewhere when:

• The work is finishable in the current turn → finish it; do not pre-emptively hand off.
• The handoff target is a specific artifact (a PRD / spec / task / ADR) → write that artifact via the matching /ad-* skill instead. Handoffs do not replace persistent decision records.
• The user wants to commit work-in-progress → /ad-commit (with wip: if your project allows it) or finish the change first.

Step 1 — Collect live state

Read the session into a structured snapshot. Do not duplicate content that already lives in repo artifacts — reference those by path.

Capture:

• Working tree — git status --short, current branch (git branch --show-current), divergence (git log --oneline @{upstream}..HEAD if a remote is set).

• In-progress diff — git diff + git diff --staged. If the combined diff is >300 lines, summarise per-file instead and tell the next agent to re-read it with git diff.

• Open artifacts — list of files touched but not yet committed; the task file under doc/tasks/ driving the work (if any); the spec under doc/specs/ it implements (if any); any ADR being drafted under doc/adr/.

• Unresolved decisions — questions the user posed that you have not answered; questions you posed that the user has not answered. One bullet per open question, with the recommended-answer line where you have one.

• Recent errors / hook failures — verbatim, last error message + which command produced it.

• Repo hygiene — git worktree list, git branch --merged <default>, git branch --no-merged <default>, stray untracked files at the repo root.

  Delete the merged branches. git branch -d <name> refuses any branch not fully merged, so git itself is the guard, and a merged branch's commits survive on the default branch and in the reflog — the blast radius WORKFLOW §7 asks you to match is near zero. Run it, and report what was deleted.

  Everything else is reported with its command, never run. Unmerged branches (including squash-merged ones, which git cannot tell from genuinely unmerged), worktrees, and stray files get git branch -D <name> / git worktree remove <path> written next to them for the user to run. Those are the destructive cases: -D discards commits, and a squash-merged branch looks identical to work nobody landed.

  Known limit, tested rather than assumed: squash-merged branches cannot be detected. git branch --merged misses them, and so do git cherry and a three-dot diff — squashing rewrites the patch-id, so a branch that genuinely shipped is indistinguishable from one that never did. Report it as ambiguous and let the human decide; a heuristic that guesses here would authorise deleting real work.

References, not copies. Spec: doc/specs/0007-foo.md beats pasting the spec. Task: doc/tasks/0042-bar.md beats pasting the task. The next agent will read those files fresh.

Step 2 — Reconstruct the roadmap

State is not a plan. A snapshot tells the next agent where the files are; it does not tell them what arc they are in the middle of, and an agent that cannot see the arc re-derives it — badly, and at cost.

Walk the session start to finish and rebuild the work as a checklist, done and not-done in one list, in dependency order. Every line carries enough context to stand alone: a reader who has never seen this session must understand what the item is and why it exists without opening another file.

• - [x] for landed work — name the artifact that proves it (a commit subject, a test name, a published version), not just the claim.
• - [ ] for open work — name the blocking condition if there is one, and who owns it (you or the user).

Then check the roadmap against the session's stated priorities. If the user corrected course, ranked items, or rejected an approach, the roadmap must reflect the corrected order — a handoff that replays the original plan re-introduces the mistake the correction fixed. State the alignment explicitly; if some open item no longer matches a stated priority, say so rather than carrying it silently.

Step 3 — Sweep for asks that never landed

Re-read the session for requests the user made that did not turn into work, an artifact, or an explicit decision to skip. These are the highest-loss items in any handoff: they were important enough to say out loud and are invisible in git status.

Look for asks that were deferred mid-turn ("park that", "later"), superseded by a more urgent thread, answered partially, or acknowledged and then buried under subsequent work. For each, record the ask in the user's own framing and its current disposition — not started, partially done and where it stopped, or dropped deliberately with the reason.

An empty result is a real outcome; write "none" rather than manufacturing entries.

Step 4 — Redact

Before writing, scrub anything that should not land in $TMPDIR:

• API keys, tokens, JWTs, OAuth client secrets — replace with <REDACTED:type>.
• Environment variable values (.env, process.env.X payloads, anything that looks like a credential).
• Personally identifiable information beyond what is in the repo's git config.
• Absolute paths containing user home directory content that is not part of this repo (the repo's own absolute path may stay).

If a value is needed by the next session but is sensitive, write a placeholder + a one-line note on where to fetch it (pull from 1Password vault "X", re-export from env).

Step 5 — Resolve handoff path

Compute the target path:

TMP="${TMPDIR:-/tmp}"
DIR="$TMP/agentic-handoffs"
mkdir -p "$DIR"
ISO=$(date -u +%Y%m%dT%H%M%SZ)
SLUG=<from-arg-or-branch>
PATH_OUT="$DIR/$ISO-$SLUG.md"

Slug derivation, in priority order:

1. The argument the user passed (/ad-handoff merge-cleanup → merge-cleanup).
2. Current branch name with non-alphanumeric chars replaced by -.
3. session as the fallback.

Never write inside the repo. Never add .agentic/handoffs/ to the repo's .gitignore. Handoffs are per-session OS artifacts, not per-repo audit trail.

Step 6 — Write the handoff

The handoff's file shape lives in references/handoff-template.md — fill each <placeholder> from the state you collected; omit any section that does not apply, except Roadmap and Asks that never landed, which are never omitted (an empty sweep is written as "none").

The ## Working rules section is copied into the handoff verbatim — this block, restated below, is deliberately not referenced:

These are restated, not referenced, and that is deliberate. A handoff is an ephemeral $TMPDIR artifact read once by an agent with no history; a pointer it may not follow is worth less than four lines it cannot miss. The anti-duplication rule protects versioned documents from drifting copies — this file is deleted after it is read.

Reporting to the engineer. They are the boss, not the co-pilot, and they did not read the files you read. Lead with the conclusion — what happened, what it means, what comes next — in plain terms first, technical detail after. Write so they grasp it in about thirty seconds; that is a target for how the report lands, not a length limit, and clarity beats compression when the two pull apart. Translate artifacts into what they mean and what to do — a pasted diff or metric is not a report.

Deciding vs asking. Default is decide. A grounded happy path, a single-criterion winner, an established pattern, a green deterministic gate: take it, do not ask. Ask only for design and taste, irreversible or high-blast-radius actions, genuine ties, insufficient evidence, or a fuzzy spec — and when you ask, bring one question with the recommended answer first and why the alternatives are weaker. Never a survey.

Grounding before building. Non-trivial change gets /ad-ground first — official docs, validated implementation references, in-repo patterns, git history — then a stated happy path. Deviating from it needs an irrefutable reason, stated.

Hypotheses before fixes. A bug gets 3–5 ranked falsifiable hypotheses before any of them is tested, each naming the prediction that would kill it. Single-hypothesis debugging anchors on the first plausible idea and is the most common failure mode after having no feedback loop. /ad-diagnose carries the loop.

Validate before correcting. Never fix on a claim you have not reproduced — including a claim from a reviewer, a prior session, or this handoff. Re-run it and state what you observed, or say UNVERIFIED. An "N of M" claim needs the command that reproduces the enumeration and the false positives in its output named — or a statement that none were found and how that was checked.

Tests before the fix is trusted. When the behaviour is expressible as a test, write the failing test first and let it drive the change — one test at a time, verifying behaviour through public interfaces, never bulk-writing tests after the fact. Every bug that gets fixed gets a regression test that fails without the fix.

Spike when the technique is the unknown. If the uncertainty is how rather than what — several plausible approaches and no way to pick from reading — prove it with a staged spike and a golden fixture (/ad-spike) before correcting anything. Only when that is genuinely the situation; a spike for a problem whose technique is already settled is wasted motion.

Review before landing. /ad-review on the range before anything merges, two axes, fresh context. The agent that wrote the code is biased about it.

Suggested-skills picks from the installed ad-* set. Common patterns:

• Mid-implementation, behavior expressible as test → /ad-tdd.
• Stuck on a bug → /ad-diagnose.
• Spec unclear → /ad-grill-me.
• About to land work → /ad-commit → /ad-pr → /ad-merge.
• Ready for fresh-context review → /ad-review main..HEAD.

Write the file with Write. Print the absolute path to the user so they can paste it into the next session.

Step 7 — Hand off

Tell the user:

1. The handoff path.
2. The roadmap, rendered inline in the reply — the user reads the plan here, not by opening a file. Conclusion first, no preamble: done and open in one list, graspable in about thirty seconds without opening the file.
3. What hygiene deleted (merged branches only) and what it left for them, each with its command.
4. Any ask the sweep found unlanded — surface these even when they are inconvenient; a handoff that quietly drops a request is worse than no handoff, because it looks complete.
5. The single recommended first action, and the suggested-skills list verbatim.

When the host exposes a background-task chip primitive — a tool that renders a suggested task as a one-click chip spawning a fresh session (e.g. spawn_task in the Claude Code desktop app) — also offer the handoff as a chip. The chip's prompt must stand alone: the absolute handoff path with the instruction to read it first, the instruction to invoke /ad-philosophy explicitly before any work, the recommended first action, and the instruction to ground in the repo's binding docs (AGENTS.md and the artifacts the handoff references) before acting. Prefer the chip over a pasted prompt where the host offers one — it survives the clipboard and carries the path verbatim. Title: short imperative naming the work. The chip complements the file — the file stays the durable artifact; on hosts without the primitive (terminal CLI, IDE extensions, Codex) the printed path is the handoff, as above.

Do not auto-execute /clear or anything destructive. The user decides when to discard the current session.

Output contract

• A single markdown file at ${TMPDIR:-/tmp}/agentic-handoffs/<ISO>-<slug>.md.
• File contains only the sections above, in that order. Omitted sections are removed entirely (not left as ## Heading\n\nN/A). Roadmap and Asks that never landed are never omitted — an empty sweep is written as "none", because silence and emptiness are indistinguishable to the next agent.
• The roadmap is a single checklist covering done and open work in dependency order, each line self-sufficient, with an explicit priority-alignment line.
• Repo hygiene deletes fully-merged branches with git branch -d and reports them; everything destructive (-D, worktree removal, file deletion) is reported with its command and never run. Confirmation is matched to blast radius (WORKFLOW §7), not waived and not inflated.
• The Working rules section states the rules outright rather than pointing at them; /ad-philosophy binds posture and is never presented as covering grounding, hypothesis, test or review discipline.
• References artifacts by path; never duplicates their content.
• Secrets are replaced with <REDACTED:type> placeholders.
• Suggested skills are drawn from the installed ad-* set and each line carries a one-clause rationale.
• The user receives the absolute path of the file and the recommended first action; on hosts exposing a background-task chip primitive, a one-click resume chip is also offered. No destructive session ops are performed.

Next

• Paste the handoff path into the next session: cat /tmp/agentic-handoffs/<file>.md (or the host-specific opener).
• On Claude Code: /clear then Read <path> as the first turn.
• On Codex: /clear then paste the file contents, or explicitly spawn a Codex subagent with the handoff path as its context packet.
• If the handoff surfaced an unresolved decision worth recording: open an ADR with /ad-adr before the next agent picks the work up.
• If the handoff surfaced a vocabulary drift (a term you kept paraphrasing): /ad-domain to land it in CONTEXT.md so the next agent inherits the canonical noun.