# What Is Checkpointing in gsd-build? Managing Non-Autonomous Plans

> Understand checkpointing in gsd-build. Learn how this structured hand-off mechanism pauses execution for human verification and decision-making in non-autonomous plans.

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

---

**Checkpointing in gsd-build is a structured hand-off mechanism where Claude deliberately pauses execution to return control to a human for verification, decision-making, or manual actions that cannot be automated.**

In the `gsd-build/get-shit-done` repository, checkpointing serves as the boundary between autonomous AI execution and human-in-the-loop workflows. By explicitly defining where Claude stops and waits for input, the system ensures that critical verification steps, architectural decisions, and unavoidable manual tasks are never skipped or automated incorrectly.

## What Is Checkpointing in gsd-build?

A **checkpoint** is a deliberately placed pause in an execution plan where Claude hands control back to a human. The purpose is human verification or decision-making, not to offload work that Claude could automate. Checkpoints are defined in [`get-shit-done/references/checkpoints.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/references/checkpoints.md) and implemented by the executor in [`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md).

### The Three Types of Checkpoints

The repository formalizes three distinct checkpoint types, each serving a specific purpose in the workflow:

- **`checkpoint:human-verify`** – Appears after Claude completes automated tasks. The human visually inspects the UI, runs a URL, or confirms expected behavior before continuing.
- **`checkpoint:decision`** – Appears when an architectural or technology choice is required. The human chooses among presented options (e.g., selecting an authentication provider).
- **`checkpoint:human-action`** – Appears for rare, truly manual steps with no API or CLI equivalent (e.g., email verification). The human performs the action, then signals Claude to continue.

## How Checkpointing Controls Non-Autonomous Plans

Checkpointing is the primary mechanism for managing **non-autonomous plans**—execution workflows that require human interaction at specific points. The system uses an `autonomous` flag in plan metadata to distinguish between fully automated and human-in-the-loop workflows.

### The Autonomous Flag in Plan Metadata

Every plan's front-matter contains an `autonomous` boolean flag defined in [`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md):

```yaml
---
phase: 1
plan: 02
type: feature
autonomous: false   # checkpoint present, requires human interaction

wave: 1
depends_on: []
files_modified: ["src/components/Dashboard.tsx"]
---

```

- **`autonomous: true`** – The plan contains no checkpoints; Claude can run everything without human interruption.
- **`autonomous: false`** – The plan contains at least one checkpoint; execution pauses at each checkpoint, awaits user response, and resumes from the exact stopping point.

### Planner Logic: Setting the Autonomous Flag

The planner ([`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md)) automatically sets the `autonomous` flag based on the presence of `<task type="checkpoint:*">` entries. Around line 350 in the planner logic, the system scans the generated task list; if any checkpoint tasks are detected, it sets `autonomous: false` in the plan's front-matter.

### Executor Behavior: Stopping at Checkpoints

The executor ([`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md)) respects the autonomous flag during task iteration. When processing the task list, the executor checks each task's type:

```bash

# Inside agents/gsd-executor.md

if [[ "$task_type" == checkpoint:* ]]; then
  # STOP immediately – return structured checkpoint message

  return_checkpoint_message
fi

```

As shown in lines 74-76 of [`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md), when the executor encounters a task whose type matches `checkpoint:*`, it **immediately stops** and returns a structured checkpoint message using the `<checkpoint_return_format>` template. The user's reply (e.g., "approved" or a selected option) is fed back into the next execution cycle, allowing the plan to continue from the exact point where it stopped.

## Authentication Gates: Dynamic Checkpoints

Authentication gates are treated as a special, dynamically generated `checkpoint:human-action`. When Claude encounters an authentication error (e.g., `vercel login` required), the executor creates a checkpoint dynamically, prompts the user for credentials, verifies the outcome, and automatically retries the original task.

This behavior is documented in [`get-shit-done/references/checkpoints.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/references/checkpoints.md) under the *Authentication Gates* section. The dynamic checkpoint follows the same protocol as static checkpoints: it blocks execution, requests specific human action, and resumes only after verification.

## Summary

- **Checkpointing** in gsd-build is a structured hand-off where Claude pauses execution to return control to humans for verification, decisions, or manual actions.
- Three checkpoint types exist: `checkpoint:human-verify`, `checkpoint:decision`, and `checkpoint:human-action`, 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).
- The `autonomous` flag in plan front-matter ([`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md)) distinguishes autonomous plans (`true`) from non-autonomous plans (`false`).
- The planner ([`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md)) automatically sets `autonomous: false` when checkpoint tasks are present.
- The executor ([`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md)) stops immediately at checkpoint tasks, returns a structured message, and resumes only after receiving human input.
- Authentication gates trigger dynamic `checkpoint:human-action` checkpoints when CLI tools require login.

## Frequently Asked Questions

### What happens when Claude encounters a checkpoint during execution?

When Claude encounters a checkpoint, the executor ([`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md)) immediately halts processing and returns a structured checkpoint message to the user. This message includes details about what was built, how to verify it, or what decision is required. The system waits for the user's response before resuming execution from the exact stopping point.

### How does the planner determine if a plan is autonomous?

The planner ([`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md)) scans the generated task list for any entries with `type="checkpoint:*"`. If checkpoint tasks are detected, the planner automatically sets `autonomous: false` in the plan's front-matter. If no checkpoints are present, it sets `autonomous: true`, indicating Claude can execute the entire plan without human interruption.

### Can checkpoints be used for authentication failures?

Yes. Authentication gates are handled as dynamic `checkpoint:human-action` checkpoints. When Claude encounters an authentication error (such as requiring `vercel login`), the system generates a checkpoint dynamically, instructs the user to complete the authentication, verifies the result, and then automatically retries the original failed task.

### What is the difference between checkpoint:human-verify and checkpoint:human-action?

`checkpoint:human-verify` is used when Claude has completed automated work and requires the human to visually confirm the results, such as checking a UI or testing a URL. `checkpoint:human-action` is reserved for rare scenarios where no API or CLI exists to automate the task, requiring the human to perform a manual action (like clicking an email verification link) before Claude can continue.