/handoff

name: handoff
description: 'Produce a self-contained context payload that lets a fresh agent continue without re-deriving what this session established. Use for cross-boundary transfer such as switching tools, starting a clean session, or handing off to another agent, and for DIY delegation flows where a focused side-session returns context to the parent.'
argument-hint: '<what the next session is for>'
user-invocable: true

Produce a self-contained context payload that lets a fresh agent continue this work without re-deriving or re-learning what this session already established. The argument is what the next session is for — use it to shape what's captured and what's left out.

Capture what's hard-won — anything the new session would have to re-do otherwise. For each item that travels, carry the grounding with it, so the receiver inherits the working state rather than just the conclusion. *Examples (illustrative, not required):* a settled decision travels with the alternatives considered and why this won; a verified fact travels with how it was verified (file:line, command output, doc URL); an open thread travels with what would close it. If a particular handoff isn't structured around decisions, facts, or threads, capture whatever the goal requires — with its grounding.

Reference other artifacts (PRDs, manifests, ADRs, issues, PRs, commits, diffs) by path or URL — don't restate their content.

Name the skills the next agent should invoke when the work ahead maps to them — the receiver may not know the toolbox it's inheriting.

Redact credentials, tokens, and personal data — the payload outlives this session and may become another agent's prompt verbatim. Point at where a secret lives (an env var name, a vault path) instead of its value.

Shape is the agent's call. Section names, headings, prose-vs-lists, ordering — driven by the intent, not a template.

Output to `~/.manifest-dev/handoffs/handoff-{timestamp}.md` (create the dir; `~` = `$HOME` / `%USERPROFILE%`) where `{timestamp}` is `YYYYMMDD-HHMMSS` in UTC — a durable home so handoffs survive OS temp cleanup between sessions. Fall back to a writable temp path only when the home directory isn't writable. If the argument is a path to a prior handoff, read it first and write a fresh doc reflecting the current state — pure rewrite, not append.