Handoff

Handoff

Saves or loads a structured JSON snapshot of session state. Use the schema in references/schema.md for all fields.

Mode Selection

• User wants to save / pause / context is full → CREATE workflow
• User wants to resume / load / continue → RESUME workflow
• After 5+ file edits or a major decision → suggest: "We've made good progress — say 'create handoff' when you're ready to save state and start fresh."

CREATE Workflow

Step 1 — Determine Output File

Use the user's argument if provided (e.g. /handoff auth-work.json). Otherwise default to .claude/handoffs/YYYY-MM-DD-HHMMSS-<slug>.json in the project root, where <slug> is 2–4 words from the task goal (e.g. auth-refactor, payment-api). Create .claude/handoffs/ if it doesn't exist.

Step 2 — Analyse the Session

Review the full conversation and all modified files, then extract:

• The primary goal and what "done" looks like (acceptance criteria)
• All architectural and design decisions reached, with rationale
• What has been completed and can be verified
• What still needs to be done, in priority order
• Hard constraints and non-negotiables
• Known bugs, issues, or unresolved warnings
• Which files were changed and what was done to each

Step 3 — Write the Handoff File

Write the JSON using the schema in references/schema.md. Do not omit any top-level field — use [] if there is nothing to report.

Step 4 — Confirm and Guide the User

Handoff written to: <filename>

Summary:
- Task: <goal>
- Completed: <N> steps
- Pending: <N> steps
- Constraints: <N>
- Open issues: <N>
- Modified files: <N>

Next steps:
1. Run /clear to wipe the context window
2. Start a new session
3. Paste this prompt to resume:

"<resume_prompt value>"

Do not run /clear yourself — the user must do this manually.

RESUME Workflow

Step 1 — Locate the File

Use the user's argument if given. Otherwise read .claude/handoffs/ and pick the most recent file by filename timestamp. If the directory is empty or missing, tell the user.

Step 2 — Load and Orient

Read the file fully. Then report:

Loaded handoff: <filename>

- Task: <goal>
- Completed: <N> steps
- Pending: <N> steps
- First step: <pending_steps[0]>
- Open issues: <N>
- Constraints: <N>

Step 3 — Begin Work

Start immediately with pending_steps[0]. Keep constraints, discovered_issues, and decisions visible as you work — don't re-litigate choices already made.

Reference Files

• references/schema.md — full JSON schema, field rules, and a complete example