handoff

handoff — write a cold-startable transition file

You are running the HANDOFF step of the workflow. Your job is to freeze the current session's state into a single Markdown file that lives in the shared .workspace/transitions/ tree so any future session on either host can resume without re-deriving context.

This step is host-neutral: same contract on Claude and Codex. The shared .workspace/ directory is the host-swap primitive (see backlog #8) — there is no "execute as the other host" verb because the durable state is what makes the swap work, not orchestration.

When to use

• Approaching context limit (Claude: ~80%+; Codex: when reasoning quality starts to degrade).
• Switching hosts mid-feature (Claude → Codex or vice versa).
• End of day / wrapping a session before a break.
• After a milestone ships, before starting the next one.
• Before any operation that may lose state (/clear, /compact, host restart).

Arguments

Parse these from the user's invocation (any order):

Arg	Required	Default	Meaning
--out <path>	no	.workspace/transitions/$(date -u +%Y-%m-%d)/$(date -u +%H%M%S).md	Where to write
--why <reason>	no	"session boundary"	Short label appearing in TL;DR
--title <text>	no	inferred from recent commits and tasks	H1 title
--dry-run	no	false (write)	Print the file to stdout instead of writing

Always write under .workspace/transitions/ — never under .claude/ or .codex/. The shared path is load-bearing for cross-host continuation.

File structure (mandatory)

The file MUST have these sections, in this order. The structure is what /continue reads — deviating breaks the contract.

# Handoff: YYYY-MM-DD HH:MM UTC — <one-line summary>

## ⚡ TL;DR

<2-4 sentences. What was shipped this session. What is queued. Why the
session is ending now (`--why`).>

## Working directory for the next session

<absolute path that is the right cwd to resume from>

Verification snapshot (cold-start commands the next agent can paste):

```bash
<verifiable command 1>
<verifiable command 2>
…

The commands MUST be safe to run blindly (read-only) and MUST produce output the next agent can compare against the expected values listed inline (as comments) so drift is detectable. Example:

cd ~/agents/coding/coding-agent-toolkit
git log --oneline -3                       # most recent: <sha>
ls skills/                                 # expect: align next-issue plan-issues ship handoff continue

Beyond those durable artifacts, the snapshot MUST include a fixed staleness floor — current branch, uncommitted tree, open issue, and last-test-at-<sha>. See "Mandatory snapshot floor" below.

Current state (cold-read map)

What shipped this session

• — <one-line per file/commit>

Toolkit verbs status (or "Active project state" for non-toolkit

work)

Verb	Status	Notes
...	...	...

Open backlog items / known frictions

1. . .

Suggested next steps (pick one, ordered by leverage)

1. . <2 sentences of why this has the most leverage right now>. <expected scope, e.g. "~30 min" or "~1 day">.
2. . . .
3. . . .

Order matters: leverage first. The next agent should be able to pick #1 and act without re-deriving the ranking.

Important context for the next agent

<3-5 numbered points. Things the cold-reader CANNOT see from the code alone:>

1. . <one-paragraph explanation of the gotcha, decision, anti-pattern, or invariant that is not obvious from the code.>
2. . …

Files touched this session

<repo>/                                                  (commit <sha>)
  <relative path>                                        # what changed
  <relative path>                                        # what changed

List EVERY file written this session, grouped by repo + commit (or "uncommitted" for working-tree changes that did not land in a commit). This is the audit trail.

Continuation

continue from <relative path to this file>

Use the path the user would type. If the file is at .workspace/transitions/2026-06-16/234043.md, write exactly:

continue from .workspace/transitions/2026-06-16/234043.md