sw-handoff

sw-handoff — resume anywhere

No AI tool can read another's transcript. The portable thing is a ≤1-page document built from durable state: the ledger, the spec ACs, the decisions, and the exact uncommitted diff. This skill writes that document.

Run specweave --version: exit 0 → CLI path. Not found → manual path. Both emit the same sections and the same Doc format v2 footer marker, so a doc from either path is resumable by either.

Before you write

Release your claims so nothing is stuck behind a dead session: specweave task release --all-mine (manual: append one release line per task you hold — see sw-task).

CLI path

specweave handoff [<inc>] [--reason "out of tokens"] [--summary "..."] \
  [--next "..."] [--gotcha "..."] [--decision "..."] [--inline]

Writes .specweave/increments/<inc>/handoff.md + handoff.diff, points .specweave/state/handoff-latest.txt at it, and prints the doc path, the diff path and a copy-paste resume prompt. Surface that output verbatim, in order. --inline embeds the whole body in the prompt (use when moving machines). No workspace or no active increment → a git + notes handoff is still written.

Manual path

1. Capture git state (free):

git rev-parse --abbrev-ref HEAD; git rev-parse --short HEAD
git status --porcelain; git diff --stat
{ git diff HEAD; git diff --cached; } > handoff.diff

PowerShell — { … } > file writes the scriptblock text in UTF-16, not a diff:

git rev-parse --abbrev-ref HEAD; git rev-parse --short HEAD
git status --porcelain; git diff --stat
$d = (git diff HEAD | Out-String) + (git diff --cached | Out-String)
[IO.File]::WriteAllText('handoff.diff', $d, [Text.UTF8Encoding]::new($false))

1. Ask the user only what the files cannot know: why you are stopping, where things stand in one line, the exact next step, any gotcha, key decisions.
2. Scrub secrets in the free text AND the diff before writing: replace sk-…, gh[pos]_…, AKIA…/ASIA…, vsk_…, xox[bap]-…, Bearer …, password=…, api_key=…, -----BEGIN … with [REDACTED-<type>] and count them. Heuristic — say so; an empty list is not a guarantee.
3. Write the document below to .specweave/increments/<inc>/handoff.md (SpecWeave workspace without an active increment → .specweave/state/handoff-latest.md; outside a workspace → ./HANDOFF.md, or .handoff/HANDOFF.md with .handoff/.gitignore = * when a foreign HANDOFF.md is in the way). UTF-8 without BOM; on PowerShell write with [IO.File]::WriteAllText($p, $body, [Text.UTF8Encoding]::new($false)), never >. If a file is already there without the Doc format v2 (or v1) marker it is somebody else's — do not overwrite it.
4. Print the absolute doc path first, then the diff path, then the paste prompt.