handoff

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.

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.