version: "1.0.1" name: create-handoff description: "Write a handoff file at .turbo/handoff/<YYYY-MM-DD>-<slug>.md capturing current session state — task, status, open decisions, in-flight changes, next step — so a fresh session can continue without re-deriving context. Use when the user asks to \"create a handoff\", \"create handoff\", \"save handoff\", \"handoff before compact\", \"save session state\", \"handoff for next session\", or \"capture session state\"."

Create Handoff

Write a session handoff file at .turbo/handoff/<YYYY-MM-DD>-<slug>.md so a fresh session can pick up where this one left off.

Step 1: Resolve the Target Path

Get today's date: date +%Y-%m-%d.

Pick a slug for the current task:

• Lowercase
• Replace non-alphanumeric characters with hyphens
• Collapse consecutive hyphens
• Trim leading and trailing hyphens
• Truncate to 40 characters at a word boundary

If the work is anchored to an existing artifact (a plan at .turbo/plans/<slug>.md, a shell at .turbo/shells/<slug>.md, or a spec at .turbo/specs/<slug>.md), reuse that artifact's slug verbatim.

The user may pass an explicit slug or path; honor it.

The target path is .turbo/handoff/<YYYY-MM-DD>-<slug>.md. If the path already exists, append -2, -3, etc. until the path is free.

State the chosen path before continuing.

Step 2: Gather Session State

Run git status --short to see uncommitted changes in the working tree.

Survey the conversation context for:

• Current task: what is being worked on, in one or two sentences
• Workflow status: where in the workflow this session is (drafting, refining iteration N, applying findings, implementing step M of K, investigating, blocked on Q, etc.)
• Active artifact: path to the plan, shell, spec, or other file at the center of the work, if one exists
• Open decisions: questions raised but not resolved, choices the user is still weighing, escalations awaiting input
• In-flight changes: staged or unstaged edits that are not yet committed; what each change is doing and what is missing
• Closed avenues: approaches that were built or tested and then abandoned, with the observed evidence that ruled them out
• Next step: the first concrete action the new session should take

When something is genuinely unclear and would leave a gap in the handoff, use request_user_input to resolve it. Default to inferring quietly when the conversation makes the answer clear.

Step 3: Write the Handoff File

Create .turbo/handoff/ if it does not exist. Write the file at the path picked in Step 1.

Lead with # Handoff: <Task Title>. Cover the items gathered in Step 2 in whatever structure fits the session — drafting, refining, implementing, and investigating sessions each have different shapes and don't all map to the same headings. Close with a clear statement of the next concrete action so the new session knows exactly what to do first.

Keep it dense. Omit anything that has no real content.

Step 4: Confirm

Tell the user where the handoff was written and quote the next-step statement so the path forward is visible at a glance.

Then call update_plan to mark this step completed and continue with the next step of the active workflow.