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

> Master the gsd-build checkpoint system for autonomous:false plans. Learn how to insert human-in-the-loop moments and ensure user verification for critical tasks in your automation.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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.

```xml
<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.

```xml
<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`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/references/checkpoints.md)** – Central definition of checkpoint types, XML schema, and display format templates
- **[`get-shit-done/workflows/execute-plan.md`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/verify-phase.md)** – Uses `must_haves` together with checkpoint outcomes to decide phase completion
- **[`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/execute-plan.md), [`checkpoints.md`](https://github.com/gsd-build/get-shit-done/blob/main/checkpoints.md), and [`phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/references/checkpoints.md), while declaration templates appear in [`get-shit-done/templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/templates/phase-prompt.md).