handoff-protocol

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.

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.

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.

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.

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.

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.