checkpoint-protocol

name	checkpoint-protocol
description	Use when human information, judgment, approval, testing, credentials, review, or external action is genuinely required before proceeding.

Checkpoint Protocol

Use a structured pause instead of an ad-hoc question. Announce that work requires input before proceeding.

When to Use

Choose exactly one type: needs_info, needs_decision, needs_confirmation, needs_testing, needs_credentials, needs_deployment_action, or needs_review. Use it only when safe progress cannot continue through research, repository conventions, reversible judgment, or available automation.

Route

• Select the trigger and copy the appropriate format from checkpoint types.
• After the user responds, follow resolution and resumption.
• Load only the first reference when pausing and only the second when resuming.

Invariants

• Present one checkpoint at a time; never batch unrelated gates.
• Provide context, the exact blocker, what was tried, the impact of the response, and a concrete resumption path.
• For choices, present meaningful options and lead with a reasoned recommendation.
• Record the checkpoint under STATE.md Blockers. After resolution, move durable choices to Decisions Made and continue from the exact prior position.
• Never ask the user to paste secrets in chat. Direct credentials to an approved local secret store such as .env and name only the variable or location.
• Do not use a checkpoint to transfer routine implementation judgment back to the user.

Red Flags

• A bare “what do you want?” without evidence or options.
• Stacked questions, excessive micro-approvals, or a checkpoint for variable names, test values, imports, or ordinary file placement.
• Performing a destructive or production-impacting action before confirmation.
• Re-reading completed work after the response instead of resuming cleanly.

Integration

Used by executing-plans, brainstorming, and systematic-debugging. Pairs with state-management for durable blockers, pause/status workflows for handoff, and verification-before-completion when manual testing is unavoidable.