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

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 and implemented by the executor in 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:

---
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) 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) respects the autonomous flag during task iteration. When processing the task list, the executor checks each task's type:

# 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, 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 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.
• The autonomous flag in plan front-matter (templates/phase-prompt.md) distinguishes autonomous plans (true) from non-autonomous plans (false).
• The planner (agents/gsd-planner.md) automatically sets autonomous: false when checkpoint tasks are present.
• The executor (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) 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) 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.

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