handoff-protocol

Serialize and restore workflow state across Claude Code sessions using HANDOFF.json and HANDOFF.md.

Updated Mar 25, 2026

Search Tags:#debugging #resume #handoff #session-state #context-notes #workflow-serialization

Ready to run

npx skills add https://github.com/tuanldas/superteam --skill handoff-protocol-tuanldas

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: handoff-protocol
Source: https://github.com/tuanldas/superteam/tree/main/skills/handoff-protocol
Command: npx skills add https://github.com/tuanldas/superteam --skill handoff-protocol-tuanldas

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This handoff protocol solves the challenge of preserving complete workflow context across Claude Code sessions by standardizing how state is serialized and restored.

Core Features & Use Cases

HANDOFF.json and HANDOFF.md ensure structured machine-readable and human-readable state captures
Unified capture/restore protocol across all workflows (/st:execute, /st:phase-execute, /st:debug, /st:quick, /st:plan) and any active task
One-shot lifecycle: CREATE on pause → CONSUME on resume → DELETE after successful resume; files must be ignored by Git
Rich context: context_notes, blockers, decisions, and human_actions_pending surface during resume

Quick Start

Pause your session to generate HANDOFF.json and HANDOFF.md in the .superteam folder.

Frequently Asked Questions about handoff-protocol

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I preserve session state across Claude Code sessions?▼

To preserve session state across Claude Code sessions, serialize your workflow context into structured HANDOFF.json and HANDOFF.md files. This captures context notes, blockers, and pending human actions to prevent loss of context during pauses.

What is the best way to resume a paused debugging workflow without losing context?▼

The best way to resume a paused debugging workflow is to consume the generated HANDOFF.json state file, which restores the complete session context including blockers and decisions, and then deletes the file after a successful resume.

How does the handoff protocol lifecycle work for active workflows?▼

The handoff protocol lifecycle follows a one-shot rule: create state files when you pause a workflow, consume them upon resume to restore context, and delete the files immediately after a successful restoration to maintain a clean workspace.

Do I need to commit HANDOFF.json and HANDOFF.md to Git?▼

No, you should not commit HANDOFF.json and HANDOFF.md to Git. These files must be ignored by Git as they serve as temporary state captures for the one-shot lifecycle of serializing and restoring session context.

Can I use session state serialization for workflows beyond /st:execute?▼

Yes, you can use session state serialization across multiple active workflows including /st:phase-execute, /st:debug, /st:quick, and /st:plan. The unified capture and restore protocol applies to any active task requiring context preservation.

What context information is captured when serializing workflow state?▼

Serializing workflow state captures rich context including context_notes, blockers, decisions, and human_actions_pending. This ensures all critical session variables are surfaced and restored when you resume your Claude Code workflow.