Understanding the Checkpoint System in gsd-build for Autonomous:false Plans

The checkpoint system in gsd-build inserts controlled human-in-the-loop moments into non-autonomous execution plans, pausing automation to require user verification before proceeding past designated tasks.

The gsd-build/get-shit-done repository implements a sophisticated execution framework that balances automation with human oversight. When working with plans where the autonomous flag is set to false, the checkpoint system becomes the primary mechanism for ensuring critical validation points, authentication gates, and design decisions receive necessary human attention.

How the Checkpoint System Works in gsd-build

When executing a plan with autonomous: false, the system parses the plan file and identifies any task whose type matches the checkpoint:* pattern. Upon encountering these markers, the executor switches from autonomous mode to the checkpoint protocol defined in ~/.claude/get-shit-done/workflows/execute-plan.md.

The Checkpoint Protocol

The protocol enforces a strict five-step execution order defined in the <step name="checkpoint_protocol"> section of execute-plan.md:

1. Stop the current sub-agent immediately when a checkpoint is encountered
2. Display a formatted checkpoint box showing progress and verification instructions
3. Wait for the user's response with no further automation running
4. Verify the user's signal (e.g., running curl for visual checks or vercel whoami for auth)
5. Resume the original plan only after successful verification

This protocol ensures that "false plans" (plans that appear autonomous but actually require human input) are safely managed without accidental automation past critical gates.

Checkpoint Types and Their Implementation

The system classifies checkpoints into three distinct types, each defined in get-shit-done/references/checkpoints.md with specific XML schemas and visual templates.

checkpoint:human-verify

This type appears after Claude has automated a feature and needs visual or functional confirmation from a human.

The user must visit a URL or run a command and type "approved" (or describe issues). The executor validates the reply, marks the checkpoint as passed, and resumes the plan.

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Responsive dashboard – dev server at http://localhost:3000</what-built>
  <how-to-verify>
    Visit http://localhost:3000/dashboard and verify:
    1. Desktop layout matches design
    2. Mobile view collapses correctly
    3. No horizontal scroll
  </how-to-verify>
  <resume-signal>Type "approved" or describe issues</resume-signal>
</task>

checkpoint:decision

This type appears when a design or architectural choice must be made that requires human judgment, such as selecting an authentication provider.

The user reviews options and replies with the selected option ID. The chosen option is recorded, any consequent plan modifications are applied, and execution proceeds.

checkpoint:human-action

This type appears when an unavoidable manual step is required, usually an authentication gate that cannot be automated.

The user performs the exact action (e.g., vercel login) and signals completion. After verification (e.g., vercel whoami succeeds), the original task is retried automatically.

<task type="checkpoint:human-action" gate="blocking">
  <action>Authenticate Vercel CLI so I can continue deployment</action>
  <instructions>
    I tried to deploy but got "Not authenticated".
    Run: vercel login
    Follow the browser flow and finish authentication.
  </instructions>
  <verification>vercel whoami returns your account email</verification>
  <resume-signal>Type "done" when authenticated</resume-signal>
</task>

Technical Implementation in the Codebase

The checkpoint system spans multiple files in the gsd-build/get-shit-done repository:

• get-shit-done/references/checkpoints.md – Central definition of checkpoint types, XML schema, and display format templates
• get-shit-done/workflows/execute-plan.md – Implements the checkpoint protocol, routing logic, and authentication-gate handling under the <step name="checkpoint_protocol"> section
• get-shit-done/templates/phase-prompt.md – Shows how to declare checkpoints inside plan files using the XML task format
• get-shit-done/workflows/verify-phase.md – Uses must_haves together with checkpoint outcomes to decide phase completion
• agents/gsd-executor.md – Runs sub-agents that pause at checkpoints and return structured state to the orchestrator

Authentication Gates and Dynamic Checkpoints

While most checkpoints are pre-declared in plan files, the system supports dynamic checkpoint generation for authentication failures. If a CLI or API call fails with an authentication error, the executor automatically generates a checkpoint:human-action task on the fly.

This behavior is documented in the Authentication Gates section of execute-plan.md. The dynamic checkpoint includes verification commands (like vercel whoami) to ensure the human action succeeded before the original task is retried automatically.

Summary

• The checkpoint system in gsd-build creates controlled pause points in autonomous:false plans, requiring human verification before proceeding
• Three checkpoint types handle different scenarios: human-verify for visual confirmation, decision for architectural choices, and human-action for manual steps like authentication
• The protocol enforces a strict five-step process: stop, display, wait, verify, and resume
• Checkpoints can be pre-declared in plan XML or generated dynamically for authentication failures
• Implementation spans execute-plan.md, checkpoints.md, and phase-prompt.md in the gsd-build/get-shit-done repository

Frequently Asked Questions

What happens when a plan has autonomous:false?

When a plan's front-matter contains autonomous: false, the executor switches to segmented execution mode (Pattern B) and activates the checkpoint protocol. The system parses the plan file for any tasks with type="checkpoint:*" and pauses execution at each one, waiting for human input before continuing.

How does the checkpoint system handle parallel execution?

In parallel execution waves, a checkpoint pauses only the specific sub-agent that reached it. Other agents continue processing until they also encounter checkpoints. The orchestrator aggregates results from all paused agents and presents each checkpoint sequentially to the user, ensuring no automation proceeds past any gate without verification.

Can checkpoints be created dynamically during execution?

Yes, while most checkpoints are pre-declared in plan files, the system generates checkpoint:human-action tasks dynamically when CLI or API calls fail with authentication errors. This is documented in the Authentication Gates section of execute-plan.md. The dynamic checkpoint includes verification commands to confirm the manual action succeeded before automatically retrying the original task.

Where is the checkpoint protocol defined in the source code?

The checkpoint protocol is defined in ~/.claude/get-shit-done/workflows/execute-plan.md under the <step name="checkpoint_protocol"> section. This file specifies the five-step execution order: stop, display, wait, verify, and resume. The XML schemas for checkpoint types are documented in get-shit-done/references/checkpoints.md, while declaration templates appear in get-shit-done/templates/phase-prompt.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}