Plans execute autonomously. Checkpoints formalize the 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 (Most Common) **When:** Claude completed automated work, human confirms it works correctly. **Use for:** - Visual UI checks (layout, styling, responsiveness) - Interactive flows (click through wizard, test user flows) - Functional verification (feature works as expected) - Audio/video playback quality - Animation smoothness - Accessibility testing **Structure:** ```xml [What Claude automated and deployed/built] [Exact steps to test - URLs, commands, expected behavior] [How to continue - "approved", "yes", or describe issues] ``` **Key elements:** - ``: What Claude automated (deployed, built, configured) - ``: Exact steps to confirm it works (numbered, specific) - ``: Clear indication of how to continue **Example: Vercel Deployment** ```xml Deploy to Vercel .vercel/, vercel.json Run `vercel --yes` to create project and deploy. Capture deployment URL from output. vercel ls shows deployment, curl {url} returns 200 App deployed, URL captured Deployed to Vercel at https://myapp-abc123.vercel.app Visit https://myapp-abc123.vercel.app and confirm: - Homepage loads without errors - Login form is visible - No console errors in browser DevTools Type "approved" to continue, or describe issues to fix ``` **Example: UI Component** ```xml Build responsive dashboard layout src/components/Dashboard.tsx, src/app/dashboard/page.tsx Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile. npm run build succeeds, no TypeScript errors Dashboard component builds without errors Responsive dashboard layout at /dashboard 1. Run: npm run dev 2. Visit: http://localhost:3000/dashboard 3. Desktop (>1024px): Verify sidebar left, content right, header top 4. Tablet (768px): Verify sidebar collapses to hamburger 5. Mobile (375px): Verify single column, bottom nav 6. Check: No layout shift, no horizontal scroll Type "approved" or describe layout issues ``` **Example: Xcode Build** ```xml Build macOS app with Xcode App.xcodeproj, Sources/ Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output. Build output contains "BUILD SUCCEEDED", no errors App builds successfully Built macOS app at DerivedData/Build/Products/Debug/App.app Open App.app and test: - App launches without crashes - Menu bar icon appears - Preferences window opens correctly - No visual glitches or layout issues Type "approved" or describe issues ``` ## checkpoint:decision **When:** Human must make choice that affects implementation direction. **Use for:** - Technology selection (which auth provider, which database) - Architecture decisions (monorepo vs separate repos) - Design choices (color scheme, layout approach) - Feature prioritization (which variant to build) - Data model decisions (schema structure) **Structure:** ```xml [What's being decided] [Why this decision matters] [Option name] [Benefits] [Tradeoffs] [Option name] [Benefits] [Tradeoffs] [How to indicate choice] ``` **Key elements:** - ``: What's being decided - ``: Why this matters - ``: Each option with balanced pros/cons (not prescriptive) - ``: How to indicate choice **Example: Auth Provider Selection** ```xml Select authentication provider Need user authentication for the app. Three solid options with different tradeoffs. Supabase Auth Built-in with Supabase DB we're using, generous free tier, row-level security integration Less customizable UI, tied to Supabase ecosystem Clerk Beautiful pre-built UI, best developer experience, excellent docs Paid after 10k MAU, vendor lock-in NextAuth.js Free, self-hosted, maximum control, widely adopted More setup work, you manage security updates, UI is DIY Select: supabase, clerk, or nextauth ``` ## checkpoint:human-action (Rare) **When:** Action has NO CLI/API and requires human-only interaction, OR Claude hit an authentication gate during automation. **Use ONLY for:** - **Authentication gates** - Claude tried to use CLI/API but needs credentials to continue (this is NOT a failure) - Email verification links (account creation requires clicking email) - SMS 2FA codes (phone verification) - Manual account approvals (platform requires human review before API access) - Credit card 3D Secure flows (web-based payment authorization) - OAuth app approvals (some platforms require web-based approval) **Do NOT use for pre-planned manual work:** - Manually deploying to Vercel (use `vercel` CLI - auth gate if needed) - Manually creating Stripe webhooks (use Stripe API - auth gate if needed) - Manually creating databases (use provider CLI - auth gate if needed) - Running builds/tests manually (use Bash tool) - Creating files manually (use Write tool) **Structure:** ```xml [What human must do - Claude already did everything automatable] [What Claude already automated] [The ONE thing requiring human action] [What Claude can check afterward] [How to continue] ``` **Key principle:** Claude automates EVERYTHING possible first, only asks human for the truly unavoidable manual step. **Example: Email Verification** ```xml Create SendGrid account via API Use SendGrid API to create subuser account with provided email. Request verification email. API returns 201, account created Account created, verification email sent Complete email verification for SendGrid account I created the account and requested verification email. Check your inbox for SendGrid verification link and click it. SendGrid API key works: curl test succeeds Type "done" when email verified ``` **Example: Credit Card 3D Secure** ```xml Create Stripe payment intent Use Stripe API to create payment intent for $99. Generate checkout URL. Stripe API returns payment intent ID and URL Payment intent created Complete 3D Secure authentication I created the payment intent: https://checkout.stripe.com/pay/cs_test_abc123 Visit that URL and complete the 3D Secure verification flow with your test card. Stripe webhook receives payment_intent.succeeded event Type "done" when payment completes ``` **Example: Authentication Gate (Dynamic Checkpoint)** ```xml Deploy to Vercel .vercel/, vercel.json Run `vercel --yes` to deploy vercel ls shows deployment, curl returns 200 Authenticate Vercel CLI so I can continue deployment I tried to deploy but got authentication error. Run: vercel login This will open your browser - complete the authentication flow. vercel whoami returns your account email Type "done" when authenticated Retry Vercel deployment Run `vercel --yes` (now authenticated) vercel ls shows deployment, curl returns 200 ``` **Key distinction:** Authentication gates are created dynamically when Claude encounters auth errors during automation. They're NOT pre-planned - Claude tries to automate first, only asks for credentials when blocked. 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] [Display checkpoint-specific content] [Resume signal instruction] ════════════════════════════════════════ ``` 3. **Wait for user response** - do not hallucinate completion 4. **Verify if possible** - check files, run tests, whatever is specified 5. **Resume execution** - continue to next task only after confirmation **For checkpoint:human-verify:** ``` ════════════════════════════════════════ CHECKPOINT: Verification Required ════════════════════════════════════════ Task 5 of 8: Responsive dashboard layout I built: Responsive dashboard at /dashboard How to verify: 1. Run: npm run dev 2. Visit: http://localhost:3000/dashboard 3. Test: Resize browser window to mobile/tablet/desktop 4. Confirm: No layout shift, proper responsive behavior Type "approved" to continue, or describe issues. ════════════════════════════════════════ ``` **For checkpoint:decision:** ``` ════════════════════════════════════════ CHECKPOINT: Decision Required ════════════════════════════════════════ Task 2 of 6: Select authentication provider Decision: Which auth provider should we use? Context: Need user authentication. Three options with different tradeoffs. Options: 1. supabase - Built-in with our DB, free tier 2. clerk - Best DX, paid after 10k users 3. nextauth - Self-hosted, maximum control Select: supabase, clerk, or nextauth ════════════════════════════════════════ ``` **DO:** - Automate everything with CLI/API before checkpoint - Be specific: "Visit https://myapp.vercel.app" not "check deployment" - Number verification steps: easier to follow - State expected outcomes: "You should see X" - Provide context: why this checkpoint exists - Make verification executable: clear, testable steps **DON'T:** - Ask human to do work Claude can automate (deploy, create resources, run builds) - Assume knowledge: "Configure the usual settings" ❌ - Skip steps: "Set up database" ❌ (too vague) - Mix multiple verifications in one checkpoint (split them) - Make verification impossible (Claude can't check visual appearance without user confirmation) **Use checkpoint:human-verify for:** - Visual verification (UI, layouts, animations) - Interactive testing (click flows, user journeys) - Quality checks (audio/video playback, animation smoothness) - Confirming deployed apps are accessible **Use checkpoint:decision for:** - Technology selection (auth providers, databases, frameworks) - Architecture choices (monorepo, deployment strategy) - Design decisions (color schemes, layout approaches) - Feature prioritization **Use checkpoint:human-action for:** - Email verification links (no API) - SMS 2FA codes (no API) - Manual approvals with no automation - 3D Secure payment flows **Don't use checkpoints for:** - Things Claude can verify programmatically (tests pass, build succeeds) - File operations (Claude can read files to verify) - Code correctness (use tests and static analysis) - Anything automatable via CLI/API Place checkpoints: - **After automation completes** - not before Claude does the work - **After UI buildout** - before declaring phase complete - **Before dependent work** - decisions before implementation - **At integration points** - after configuring external services Bad placement: - Before Claude automates (asking human to do automatable work) ❌ - Too frequent (every other task is a checkpoint) ❌ - Too late (checkpoint is last task, but earlier tasks needed its result) ❌ ### Example 1: Deployment Flow (Correct) ```xml Deploy to Vercel .vercel/, vercel.json, package.json 1. Run `vercel --yes` to create project and deploy 2. Capture deployment URL from output 3. Set environment variables with `vercel env add` 4. Trigger production deployment with `vercel --prod` - vercel ls shows deployment - curl {url} returns 200 - Environment variables set correctly App deployed to production, URL captured Deployed to https://myapp.vercel.app Visit https://myapp.vercel.app and confirm: - Homepage loads correctly - All images/assets load - Navigation works - No console errors Type "approved" or describe issues ``` ### Example 2: Database Setup (Correct) ```xml Create Upstash Redis database .env 1. Run `upstash redis create myapp-cache --region us-east-1` 2. Capture connection URL from output 3. Write to .env: UPSTASH_REDIS_URL={url} 4. Verify connection with test command - upstash redis list shows database - .env contains UPSTASH_REDIS_URL - Test connection succeeds Redis database created and configured ``` ### Example 3: Stripe Webhooks (Correct) ```xml Configure Stripe webhooks .env, src/app/api/webhooks/route.ts 1. Use Stripe API to create webhook endpoint pointing to /api/webhooks 2. Subscribe to events: payment_intent.succeeded, customer.subscription.updated 3. Save webhook signing secret to .env 4. Implement webhook handler in route.ts - Stripe API returns webhook endpoint ID - .env contains STRIPE_WEBHOOK_SECRET - curl webhook endpoint returns 200 Stripe webhooks configured and handler implemented Stripe webhook configured via API Visit Stripe Dashboard > Developers > Webhooks Confirm: Endpoint shows https://myapp.com/api/webhooks with correct events Type "yes" if correct ``` ### ❌ BAD: Asking human to automate ```xml Deploy to Vercel 1. Visit vercel.com/new 2. Import Git repository 3. Click Deploy 4. Copy deployment URL Deployment exists Paste URL ``` **Why bad:** Vercel has a CLI. Claude should run `vercel --yes`. ### ✅ GOOD: Claude automates, human verifies ```xml Deploy to Vercel Run `vercel --yes`. Capture URL. vercel ls shows deployment, curl returns 200 Deployed to {url} Visit {url}, check homepage loads Type "approved" ``` ### ❌ BAD: Too many checkpoints ```xml Create schema Check schema Create API route Check API Create UI form Check form ``` **Why bad:** Verification fatigue. Combine into one checkpoint at end. ### ✅ GOOD: Single verification checkpoint ```xml Create schema Create API route Create UI form Complete auth flow (schema + API + UI) Test full flow: register, login, access protected page Type "approved" ``` ### ❌ BAD: Asking for automatable file operations ```xml Create .env file 1. Create .env in project root 2. Add: DATABASE_URL=... 3. Add: STRIPE_KEY=... ``` **Why bad:** Claude has Write tool. This should be `type="auto"`.

Checkpoints formalize human-in-the-loop points. Use them when Claude cannot complete a task autonomously OR when human verification is required for correctness. **The golden rule:** If Claude CAN automate it, Claude MUST automate it. **Checkpoint priority:** 1. **checkpoint:human-verify** (90% of checkpoints) - Claude automated everything, human confirms visual/functional correctness 2. **checkpoint:decision** (9% of checkpoints) - Human makes architectural/technology choices 3. **checkpoint:human-action** (1% of checkpoints) - Truly unavoidable manual steps with no API/CLI