diff --git a/commands/gsd/execute-phase.md b/commands/gsd/execute-phase.md
index 086714ac3..c3009ace0 100644
--- a/commands/gsd/execute-phase.md
+++ b/commands/gsd/execute-phase.md
@@ -160,9 +160,23 @@ All three run in parallel. Task tool blocks until all complete.
Plans with `autonomous: false` in frontmatter have checkpoints:
- Run in their assigned wave (can be parallel with other plans)
-- Pause at checkpoint, return to orchestrator
-- Orchestrator presents checkpoint to user
-- User responds, orchestrator resumes agent
+- Pause at checkpoint, return structured state to orchestrator
+- Orchestrator presents checkpoint to user (see execute-plan.md for presentation formats)
+- User responds, orchestrator spawns fresh continuation agent
+
+**Checkpoint flow:**
+1. Subagent returns `## CHECKPOINT REACHED` with Completed Tasks table
+2. Orchestrator parses return and presents rich formatted checkpoint
+3. User responds (approved/done/option selection)
+4. Orchestrator fills continuation-prompt.md template with state
+5. Spawns fresh agent: `Task(prompt=filled_continuation_template, subagent_type="general-purpose")`
+
+**Why fresh agent, not resume:**
+Task tool resume fails after multiple tool calls. Fresh agent with state handoff is the correct pattern.
+
+**Templates:**
+- `@~/.claude/get-shit-done/templates/checkpoint-return.md` - Subagent return format
+- `@~/.claude/get-shit-done/templates/continuation-prompt.md` - Fresh agent spawn template
diff --git a/commands/gsd/execute-plan.md b/commands/gsd/execute-plan.md
index 19a58079a..5391622cf 100644
--- a/commands/gsd/execute-plan.md
+++ b/commands/gsd/execute-plan.md
@@ -201,13 +201,88 @@ When subagent returns with checkpoint:
**Plan:** {phase}-{plan}
**Progress:** {completed}/{total} tasks complete
-[Checkpoint content]
+### Completed Tasks
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | [task name] | [hash] | [files] |
-**Awaiting:** [Resume signal]
+### Current Task
+**Task {N}:** [name]
+**Status:** [blocked | awaiting verification | awaiting decision]
+**Blocked by:** [specific blocker]
+
+### Checkpoint Details
+[Type-specific content for user]
+
+### Awaiting
+[What user needs to provide]
```
-**2. Present to user:**
-Display the checkpoint content exactly as returned by subagent.
+**2. Present checkpoint to user:**
+
+Display rich formatted checkpoint based on type:
+
+**For human-verify:**
+```
+════════════════════════════════════════
+CHECKPOINT: Verification Required
+════════════════════════════════════════
+
+Task {X} of {Y}: {task name}
+
+I built: {what-built from checkpoint details}
+
+How to verify:
+{numbered verification steps}
+
+Type "approved" to continue, or describe issues.
+════════════════════════════════════════
+```
+
+**For human-action (auth gate):**
+```
+════════════════════════════════════════
+CHECKPOINT: Authentication Required
+════════════════════════════════════════
+
+Task {X} of {Y}: {task name}
+
+I tried: {automation attempted}
+Error: {error encountered}
+
+What you need to do:
+{numbered instructions}
+
+I'll verify after: {verification}
+
+Type "done" when complete.
+════════════════════════════════════════
+```
+
+**For decision:**
+```
+════════════════════════════════════════
+CHECKPOINT: Decision Required
+════════════════════════════════════════
+
+Task {X} of {Y}: {task name}
+
+Decision: {what's being decided}
+
+Context: {why this matters}
+
+Options:
+1. {option-a}: {name}
+ Pros: {benefits}
+ Cons: {tradeoffs}
+
+2. {option-b}: {name}
+ Pros: {benefits}
+ Cons: {tradeoffs}
+
+Select: {option-a | option-b | ...}
+════════════════════════════════════════
+```
**3. Collect response:**
Wait for user input:
@@ -215,15 +290,34 @@ Wait for user input:
- decision: option selection
- human-action: "done" when complete
-**4. Resume subagent:**
+**4. Spawn fresh continuation agent:**
+
+Fill continuation-prompt template with:
+- completed_tasks_table: From checkpoint return
+- resume_task_number: Current task number
+- resume_task_name: Current task name
+- resume_status: Derived from checkpoint type and user response
+- user_response: What user provided
+- resume_instructions: Type-specific guidance (see template)
+
```
-Task(resume="{agent_id}", prompt="User response: {user_input}")
+Task(prompt=filled_continuation_template, subagent_type="general-purpose")
```
+**Why fresh agent, not resume:**
+Task tool resume fails after multiple tool calls (presenting to user, waiting for response). Fresh agent with state handoff via continuation-prompt.md is the correct pattern.
+
**5. Repeat:**
Continue handling returns until "## PLAN COMPLETE" or user stops.
+
+Templates for checkpoint handling:
+
+- `@~/.claude/get-shit-done/templates/checkpoint-return.md` - Subagent return format
+- `@~/.claude/get-shit-done/templates/continuation-prompt.md` - Fresh agent spawn template
+
+
- [ ] Plan executed (SUMMARY.md created)
- [ ] All checkpoints handled
diff --git a/get-shit-done/references/checkpoints.md b/get-shit-done/references/checkpoints.md
index 7cc7b8308..7a6188c5d 100644
--- a/get-shit-done/references/checkpoints.md
+++ b/get-shit-done/references/checkpoints.md
@@ -1,110 +1,315 @@
-Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
+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 (90% of checkpoints)
+
+## checkpoint:human-verify (Most Common - 90%)
**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.
+**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]
- [Numbered steps - URLs, commands, expected behavior]
- [How to continue - "approved" or describe issues]
+ [What Claude automated and deployed/built]
+
+ [Exact steps to test - URLs, commands, expected behavior]
+
+ [How to continue - "approved", "yes", or describe issues]
```
-**Example:**
+**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
- Run `vercel --yes` to deploy. Capture URL.
+ .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 https://myapp.vercel.app
+ Deployed to Vercel at https://myapp-abc123.vercel.app
- Visit URL and confirm:
- 1. Homepage loads without errors
- 2. All images/assets load
- 3. No console errors
+ 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 (9% of checkpoints)
+
+## checkpoint:decision (9%)
**When:** Human must make choice that affects implementation direction.
-**Use for:** Technology selection, architecture decisions, design choices, feature prioritization.
+**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 matters]
+ [Why this decision matters]
-
-
+
+
[How to indicate choice]
```
-**Example:**
+**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 auth. Three options with different tradeoffs.
+
+ Need user authentication for the app. Three solid options with different tradeoffs.
+
-
-
-
+
+
+
Select: supabase, clerk, or nextauth
```
-## checkpoint:human-action (1% - rare)
+**Example: Database Selection**
+```xml
+
+ Select database for user data
+
+ App needs persistent storage for users, sessions, and user-generated content.
+ Expected scale: 10k users, 1M records first year.
+
+
+
+
+
+
+ Select: supabase, planetscale, or convex
+
+```
+
-**When:** Action has NO CLI/API and requires human-only interaction.
+
+## checkpoint:human-action (1% - Rare)
-**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals.
+**When:** Action has NO CLI/API and requires human-only interaction, OR Claude hit an authentication gate during automation.
-**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use Bash), file operations (use Write/Edit).
+**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
- [Unavoidable manual step]
- [What Claude automated] [ONE thing requiring human action]
- [What Claude checks afterward]
+ [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]
```
-**Example (email verification):**
+**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 verification link and click it.
+ Check your inbox for SendGrid verification link and click it.
SendGrid API key works: curl test succeeds
- Type "done" when verified
+ 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.
+
@@ -121,16 +326,86 @@ CHECKPOINT: [Type]
Task [X] of [Y]: [Name]
-[Checkpoint-specific content]
+[Display task-specific content based on type]
[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
+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
+ Pros: Row-level security integration, generous free tier
+ Cons: Less customizable UI, ecosystem lock-in
+
+2. clerk - Best DX, paid after 10k users
+ Pros: Beautiful pre-built UI, excellent documentation
+ Cons: Vendor lock-in, pricing at scale
+
+3. nextauth - Self-hosted, maximum control
+ Pros: Free, no vendor lock-in, widely adopted
+ Cons: More setup work, DIY security updates
+
+Select: supabase, clerk, or nextauth
+════════════════════════════════════════
+```
+
+**For checkpoint:human-action:**
+```
+════════════════════════════════════════
+CHECKPOINT: Authentication Required
+════════════════════════════════════════
+
+Task 3 of 8: Deploy to Vercel
+
+I tried: vercel --yes
+Error: Not authenticated. Please run 'vercel login'
+
+What you need to do:
+1. Run: vercel login
+2. Complete browser authentication when it opens
+3. Return here when done
+
+I'll verify after: vercel whoami returns your account
+
+Type "done" when authenticated.
+════════════════════════════════════════
+```
@@ -148,30 +423,42 @@ Task [X] of [Y]: [Name]
6. Retry the original task
7. Continue normally
-**Example (Vercel auth gate):**
-```xml
-
-
- Deploy to Vercel
- Run `vercel --yes` to deploy
-
+**Example execution flow (Vercel auth gate):**
-
-
- Authenticate Vercel CLI so I can continue
-
- I tried to deploy but got authentication error.
- Run: vercel login (opens browser)
-
- vercel whoami returns your account
- Type "done" when authenticated
-
+```
+Claude: Running `vercel --yes` to deploy...
-
-
- Retry deployment
- Run `vercel --yes` (now authenticated)
-
+Error: Not authenticated. Please run 'vercel login'
+
+════════════════════════════════════════
+CHECKPOINT: Authentication Required
+════════════════════════════════════════
+
+Task 3 of 8: Deploy to Vercel
+
+I tried: vercel --yes
+Error: Not authenticated
+
+What you need to do:
+1. Run: vercel login
+2. Complete browser authentication
+
+I'll verify after: vercel whoami returns your account
+
+Type "done" when authenticated.
+════════════════════════════════════════
+
+User: done
+
+Claude: Verifying authentication...
+Running: vercel whoami
+✓ Authenticated as: user@example.com
+
+Retrying deployment...
+Running: vercel --yes
+✓ Deployed to: https://myapp-abc123.vercel.app
+
+Task 3 complete. Continuing to task 4...
```
**Key distinction:**
@@ -196,6 +483,7 @@ Task [X] of [Y]: [Name]
| 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 |
+| Convex | `npx convex` | `dev`, `deploy`, `import` | `npx convex login` |
**Env files:** Use Write/Edit tools. Never ask human to create .env manually.
@@ -210,61 +498,277 @@ Task [X] of [Y]: [Name]
| Run tests | Yes (`npm test`) | YES |
| Click email verification link | No | NO |
| Enter credit card with 3DS | No | NO |
+| Complete OAuth in browser | 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
+- 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
-- Assume knowledge: "Configure the usual settings"
-- Mix multiple verifications in one checkpoint
-- Use checkpoints too frequently (verification fatigue)
+- 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)
**Placement:**
-- After automation completes (not before)
-- After UI buildout
-- Before dependent work (decisions)
-- At integration points
+- **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 (No Checkpoint Needed)
+
+```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
+
+```
+
+### Example 4: Full Auth Flow Verification (Correct)
+
+```xml
+
+ Create user schema
+ src/db/schema.ts
+ Define User, Session, Account tables with Drizzle ORM
+ npm run db:generate succeeds
+
+
+
+ Create auth API routes
+ src/app/api/auth/[...nextauth]/route.ts
+ Set up NextAuth with GitHub provider, JWT strategy
+ TypeScript compiles, no errors
+
+
+
+ Create login UI
+ src/app/login/page.tsx, src/components/LoginButton.tsx
+ Create login page with GitHub OAuth button
+ npm run build succeeds
+
+
+
+
+ Complete authentication flow (schema + API + UI)
+
+ 1. Run: npm run dev
+ 2. Visit: http://localhost:3000/login
+ 3. Click "Sign in with GitHub"
+ 4. Complete GitHub OAuth flow
+ 5. Verify: Redirected to /dashboard, user name displayed
+ 6. Refresh page: Session persists
+ 7. Click logout: Session cleared
+
+ Type "approved" or describe issues
+
+```
+
-**BAD: Asking human to automate**
+### ❌ BAD: Asking human to automate
+
```xml
-
+
Deploy to Vercel
- Visit vercel.com/new, import repo, click Deploy
+
+ 1. Visit vercel.com/new
+ 2. Import Git repository
+ 3. Click Deploy
+ 4. Copy deployment URL
+
+ Deployment exists
+ Paste URL
```
-Why bad: Vercel has CLI. Use `vercel --yes`.
-**BAD: Too many checkpoints**
+**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
+Create API route
Check API
+Create UI form
+Check form
```
-Why bad: Verification fatigue. Combine into one checkpoint at end.
-**GOOD: Claude automates, human verifies once**
+**Why bad:** Verification fatigue. Combine into one checkpoint at end.
+
+### ✅ GOOD: Single verification checkpoint
+
```xml
Create schema
-Create API
-Create UI
+Create API route
+Create UI form
- Complete auth flow
+ 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"`.
+
+### ❌ BAD: Vague verification steps
+
+```xml
+
+ Dashboard
+ Check it works
+ Continue
+
+```
+
+**Why bad:** No specifics. User doesn't know what to test or what "works" means.
+
+### ✅ GOOD: Specific verification steps
+
+```xml
+
+ Responsive dashboard at /dashboard
+
+ 1. Run: npm run dev
+ 2. Visit: http://localhost:3000/dashboard
+ 3. Desktop (>1024px): Sidebar visible, content area fills remaining space
+ 4. Tablet (768px): Sidebar collapses to icons
+ 5. Mobile (375px): Sidebar hidden, hamburger menu in header
+ 6. Check: No horizontal scroll at any size
+
+ Type "approved" or describe layout issues
```
@@ -272,16 +776,18 @@ Why bad: Verification fatigue. Combine into one checkpoint at end.
+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%) - 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
+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
**When NOT to use checkpoints:**
-- Things Claude can verify programmatically (tests, builds)
-- File operations (Claude can read/write)
-- Anything with CLI/API available
-
+- 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