Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
**Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
## checkpoint:human-verify (90% of checkpoints)
**When:** Claude completed automated work, human confirms it works correctly.
**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing.
**Structure:**
```xml
[What Claude automated][Numbered steps - URLs, commands, expected behavior][How to continue - "approved" or describe issues]
```
**Example:**
```xml
Deploy to VercelRun `vercel --yes` to deploy. Capture URL.vercel ls shows deployment, curl {url} returns 200Deployed to https://myapp.vercel.app
Visit URL and confirm:
1. Homepage loads without errors
2. All images/assets load
3. No console errors
Type "approved" or describe issues
```
## checkpoint:decision (9% of checkpoints)
**When:** Human must make choice that affects implementation direction.
**Use for:** Technology selection, architecture decisions, design choices, feature prioritization.
**Structure:**
```xml
[What's being decided][Why this matters][How to indicate choice]
```
**Example:**
```xml
Select authentication providerNeed user auth. Three options with different tradeoffs.Select: supabase, clerk, or nextauth
```
## checkpoint:human-action (1% - rare)
**When:** Action has NO CLI/API and requires human-only interaction.
**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals.
**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use Bash), file operations (use Write/Edit).
**Structure:**
```xml
[Unavoidable manual step][What Claude automated] [ONE thing requiring human action][What Claude checks afterward][How to continue]
```
**Example (email verification):**
```xml
Complete email verification for SendGrid account
I created the account and requested verification email.
Check your inbox for verification link and click it.
SendGrid API key works: curl test succeedsType "done" when verified
```
When Claude encounters `type="checkpoint:*"`:
1. **Stop immediately** - do not proceed to next task
2. **Display checkpoint clearly:**
```
════════════════════════════════════════
CHECKPOINT: [Type]
════════════════════════════════════════
Task [X] of [Y]: [Name]
[Checkpoint-specific content]
[Resume signal instruction]
════════════════════════════════════════
```
3. **Wait for user response** - do not hallucinate completion
4. **Verify if possible** - check files, run tests
5. **Resume execution** - continue only after confirmation
**Critical:** When Claude tries CLI/API and gets auth error, this is NOT a failure - it's a gate requiring human input to unblock automation.
**Pattern:** Claude tries automation → auth error → creates checkpoint → you authenticate → Claude retries → continues
**Gate protocol:**
1. Recognize it's not a failure - missing auth is expected
2. Stop current task - don't retry repeatedly
3. Create checkpoint:human-action dynamically
4. Provide exact authentication steps
5. Verify authentication works
6. Retry the original task
7. Continue normally
**Example (Vercel auth gate):**
```xml
Deploy to VercelRun `vercel --yes` to deployAuthenticate Vercel CLI so I can continue
I tried to deploy but got authentication error.
Run: vercel login (opens browser)
vercel whoami returns your accountType "done" when authenticatedRetry deploymentRun `vercel --yes` (now authenticated)
```
**Key distinction:**
- Pre-planned checkpoint: "I need you to do X" (wrong - Claude should automate)
- Auth gate: "I tried to automate X but need credentials" (correct - unblocks automation)
**The rule:** If it has CLI/API, Claude does it. Never ask human to perform automatable work.
| Service | CLI/API | Key Commands | Auth Gate |
|---------|---------|--------------|-----------|
| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |
| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |
| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |
| Stripe | `stripe` + API | `listen`, `trigger`, API calls | API key in .env |
| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |
| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |
| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |
| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |
| Node | `npm`/`pnpm` | `install`, `run build`, `test` | N/A |
| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
**Env files:** Use Write/Edit tools. Never ask human to create .env manually.
**Quick reference:**
| Action | Automatable? | Claude does it? |
|--------|--------------|-----------------|
| Deploy to Vercel | Yes (`vercel`) | YES |
| Create Stripe webhook | Yes (API) | YES |
| Write .env file | Yes (Write tool) | YES |
| Create Upstash DB | Yes (`upstash`) | YES |
| Run tests | Yes (`npm test`) | YES |
| Click email verification link | No | NO |
| Enter credit card with 3DS | No | NO |
**DO:**
- Automate everything with CLI/API before checkpoint
- Be specific: "Visit https://myapp.vercel.app" not "check deployment"
- Number verification steps
- State expected outcomes
- Make verification executable
**DON'T:**
- Ask human to do work Claude can automate
- Assume knowledge: "Configure the usual settings"
- Mix multiple verifications in one checkpoint
- Use checkpoints too frequently (verification fatigue)
**Placement:**
- After automation completes (not before)
- After UI buildout
- Before dependent work (decisions)
- At integration points
**BAD: Asking human to automate**
```xml
Deploy to VercelVisit vercel.com/new, import repo, click Deploy
```
Why bad: Vercel has CLI. Use `vercel --yes`.
**BAD: Too many checkpoints**
```xml
Create schemaCheck schemaCreate APICheck API
```
Why bad: Verification fatigue. Combine into one checkpoint at end.
**GOOD: Claude automates, human verifies once**
```xml
Create schemaCreate APICreate UIComplete auth flowTest full flow: register, login, access protected page
```
**The golden rule:** If Claude CAN automate it, Claude MUST automate it.
**Checkpoint priority:**
1. **checkpoint:human-verify** (90%) - Claude automated, human confirms visual/functional correctness
2. **checkpoint:decision** (9%) - Human makes architectural/technology choices
3. **checkpoint:human-action** (1%) - Truly unavoidable manual steps with no API/CLI
**When NOT to use checkpoints:**
- Things Claude can verify programmatically (tests, builds)
- File operations (Claude can read/write)
- Anything with CLI/API available