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-.json in the project root, where ` 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: 

Summary:
- Task: 
- Completed:  steps
- Pending:  steps
- Constraints: 
- Open issues: 
- Modified files: 

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

""

> 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: 

- Task: 
- Completed:  steps
- Pending:  steps
- First step: 
- Open issues: 
- Constraints: 

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: psenger
• Source: psenger/ai-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.