/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.

Carry the next session's assigned activity and scope, the source and limits of delegated choices, retained decisions, and any accepted artifact/version. Preserve current withdrawals and wait conditions with the route to resume. The handoff grants no more authority than its caller holds; a proposal for later work remains a proposal.

Carry the current acceptance claims, hard requirements and working revision freedom, plus material review dispositions with their evidence and what would reopen them. Include unfinished mandatory work and evidence that needs refreshing, not just a prior verdict.

Prefer references to the correct artifact/version when the receiving session can access them. When it cannot, carry the essential contract and continuation state in the payload, naming the unavailable source and any evidence limit. A local path alone is not a cross-host handoff; avoid copying unrelated history or duplicating content the receiver can already read.

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}-{id}.md` (create the dir; `~` = `$HOME` / `%USERPROFILE%`) where `{timestamp}` is `YYYYMMDD-HHMMSS` in UTC and `{id}` is four random hex characters, creating the file only where that path is free and drawing a new `{id}` otherwise, so two handoffs written in the same second never overwrite each other — 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.