get-shit-done-cc 1.4.26 → 1.4.28

package/commands/gsd/execute-phase.md

@@ -64,10 +64,83 @@ Phase: $ARGUMENTS
    - Update ROADMAP.md
 
 6. **Offer next steps**
-   - More phases → `/gsd:plan-phase {next}`
-   - Milestone complete → `/gsd:complete-milestone`
+   - Route to next action (see `<offer_next>`)
 </process>
 
+<offer_next>
+**MANDATORY: Present copy/paste-ready next command.**
+
+After phase completes, determine what's next:
+
+**Step 1: Check milestone status**
+
+Read ROADMAP.md. Find current phase number and highest phase in milestone.
+
+| Condition | Action |
+|-----------|--------|
+| current < highest | More phases → Route A |
+| current = highest | Milestone complete → Route B |
+
+---
+
+**Route A: More phases remain in milestone**
+
+```
+## ✓ Phase {Z}: {Name} Complete
+
+All {Y} plans finished.
+
+---
+
+## ▶ Next Up
+
+**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
+
+`/gsd:plan-phase {Z+1}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:verify-work {Z}` — manual acceptance testing before continuing
+- `/gsd:discuss-phase {Z+1}` — gather context first
+- `/gsd:research-phase {Z+1}` — investigate unknowns
+
+---
+```
+
+---
+
+**Route B: Milestone complete**
+
+```
+🎉 MILESTONE COMPLETE!
+
+## ✓ Phase {Z}: {Name} Complete
+
+All {N} phases finished.
+
+---
+
+## ▶ Next Up
+
+**Complete Milestone** — archive and prepare for next
+
+`/gsd:complete-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:verify-work` — manual acceptance testing before completing milestone
+- `/gsd:add-phase <description>` — add another phase before completing
+
+---
+```
+</offer_next>
+
 <wave_execution>
 **Parallel spawning:**
 
@@ -85,11 +158,12 @@ All three run in parallel. Task tool blocks until all complete.
 </wave_execution>
 
 <checkpoint_handling>
-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
+Plans with `autonomous: false` have checkpoints. The execute-phase.md workflow handles the full checkpoint flow:
+- Subagent pauses at checkpoint, returns structured state
+- Orchestrator presents to user, collects response
+- Spawns fresh continuation agent (not resume)
+
+See `@~/.claude/get-shit-done/workflows/execute-phase.md` step `checkpoint_handling` for complete details.
 </checkpoint_handling>
 
 <deviation_rules>

package/commands/gsd/execute-plan.md

@@ -85,12 +85,111 @@ Plan path: $ARGUMENTS
    - If contains "## CHECKPOINT REACHED": Execute checkpoint_handling
    - If contains "## PLAN COMPLETE": Verify SUMMARY exists, report success
 
-7. **Report completion**
+7. **Report completion and offer next steps**
    - Show SUMMARY path
    - Show commits from subagent return
-   - Offer next steps
+   - Route to next action (see `<offer_next>`)
 </process>
 
+<offer_next>
+**MANDATORY: Present copy/paste-ready next command.**
+
+After plan completes, determine what's next:
+
+**Step 1: Count plans vs summaries in current phase**
+```bash
+ls -1 .planning/phases/[phase-dir]/*-PLAN.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
+```
+
+**Step 2: Route based on counts**
+
+| Condition | Action |
+|-----------|--------|
+| summaries < plans | More plans remain → Route A |
+| summaries = plans | Phase complete → Check milestone (Step 3) |
+
+---
+
+**Route A: More plans remain in phase**
+
+Find next PLAN.md without matching SUMMARY.md. Present:
+
+```
+Plan {phase}-{plan} complete.
+Summary: .planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md
+
+{Y} of {X} plans complete for Phase {Z}.
+
+---
+
+## ▶ Next Up
+
+**{phase}-{next-plan}: [Plan Name]** — [objective from PLAN.md]
+
+`/gsd:execute-plan .planning/phases/{phase-dir}/{phase}-{next-plan}-PLAN.md`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+---
+
+**Step 3: Check milestone status (only when phase complete)**
+
+Read ROADMAP.md. Find current phase number and highest phase in milestone.
+
+| Condition | Action |
+|-----------|--------|
+| current < highest | More phases → Route B |
+| current = highest | Milestone complete → Route C |
+
+---
+
+**Route B: Phase complete, more phases remain**
+
+```
+## ✓ Phase {Z}: {Name} Complete
+
+All {Y} plans finished.
+
+---
+
+## ▶ Next Up
+
+**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
+
+`/gsd:plan-phase {Z+1}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+---
+
+**Route C: Milestone complete**
+
+```
+🎉 MILESTONE COMPLETE!
+
+## ✓ Phase {Z}: {Name} Complete
+
+All {N} phases finished.
+
+---
+
+## ▶ Next Up
+
+`/gsd:complete-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+</offer_next>
+
 <checkpoint_handling>
 When subagent returns with checkpoint:
 
@@ -102,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] |
+
+### 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 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}
 
-**Awaiting:** [Resume signal]
+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
+════════════════════════════════════════
 
-**2. Present to user:**
-Display the checkpoint content exactly as returned by subagent.
+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:
@@ -116,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.
 </checkpoint_handling>
 
+<checkpoint_templates>
+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
+</checkpoint_templates>
+
 <success_criteria>
 - [ ] Plan executed (SUMMARY.md created)
 - [ ] All checkpoints handled

package/get-shit-done/references/checkpoints.md

@@ -1,110 +1,315 @@
 <overview>
-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.
 </overview>
 
 <checkpoint_types>
 
-## checkpoint:human-verify (90% of checkpoints)
+<type name="human-verify">
+## 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
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[What Claude automated]</what-built>
-  <how-to-verify>[Numbered steps - URLs, commands, expected behavior]</how-to-verify>
-  <resume-signal>[How to continue - "approved" or describe issues]</resume-signal>
+  <what-built>[What Claude automated and deployed/built]</what-built>
+  <how-to-verify>
+    [Exact steps to test - URLs, commands, expected behavior]
+  </how-to-verify>
+  <resume-signal>[How to continue - "approved", "yes", or describe issues]</resume-signal>
 </task>
 ```
 
-**Example:**
+**Key elements:**
+- `<what-built>`: What Claude automated (deployed, built, configured)
+- `<how-to-verify>`: Exact steps to confirm it works (numbered, specific)
+- `<resume-signal>`: Clear indication of how to continue
+
+**Example: Vercel Deployment**
 ```xml
 <task type="auto">
   <name>Deploy to Vercel</name>
-  <action>Run `vercel --yes` to deploy. Capture URL.</action>
+  <files>.vercel/, vercel.json</files>
+  <action>Run `vercel --yes` to create project and deploy. Capture deployment URL from output.</action>
   <verify>vercel ls shows deployment, curl {url} returns 200</verify>
+  <done>App deployed, URL captured</done>
 </task>
 
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Deployed to https://myapp.vercel.app</what-built>
+  <what-built>Deployed to Vercel at https://myapp-abc123.vercel.app</what-built>
   <how-to-verify>
-    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
+  </how-to-verify>
+  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
+</task>
+```
+
+**Example: UI Component**
+```xml
+<task type="auto">
+  <name>Build responsive dashboard layout</name>
+  <files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
+  <action>Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile.</action>
+  <verify>npm run build succeeds, no TypeScript errors</verify>
+  <done>Dashboard component builds without errors</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Responsive dashboard layout at /dashboard</what-built>
+  <how-to-verify>
+    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
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe layout issues</resume-signal>
+</task>
+```
+
+**Example: Xcode Build**
+```xml
+<task type="auto">
+  <name>Build macOS app with Xcode</name>
+  <files>App.xcodeproj, Sources/</files>
+  <action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output.</action>
+  <verify>Build output contains "BUILD SUCCEEDED", no errors</verify>
+  <done>App builds successfully</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
+  <how-to-verify>
+    Open App.app and test:
+    - App launches without crashes
+    - Menu bar icon appears
+    - Preferences window opens correctly
+    - No visual glitches or layout issues
   </how-to-verify>
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 ```
+</type>
 
-## checkpoint:decision (9% of checkpoints)
+<type name="decision">
+## 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
 <task type="checkpoint:decision" gate="blocking">
   <decision>[What's being decided]</decision>
-  <context>[Why this matters]</context>
+  <context>[Why this decision matters]</context>
   <options>
-    <option id="option-a"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
-    <option id="option-b"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
+    <option id="option-a">
+      <name>[Option name]</name>
+      <pros>[Benefits]</pros>
+      <cons>[Tradeoffs]</cons>
+    </option>
+    <option id="option-b">
+      <name>[Option name]</name>
+      <pros>[Benefits]</pros>
+      <cons>[Tradeoffs]</cons>
+    </option>
   </options>
   <resume-signal>[How to indicate choice]</resume-signal>
 </task>
 ```
 
-**Example:**
+**Key elements:**
+- `<decision>`: What's being decided
+- `<context>`: Why this matters
+- `<options>`: Each option with balanced pros/cons (not prescriptive)
+- `<resume-signal>`: How to indicate choice
+
+**Example: Auth Provider Selection**
 ```xml
 <task type="checkpoint:decision" gate="blocking">
   <decision>Select authentication provider</decision>
-  <context>Need user auth. Three options with different tradeoffs.</context>
+  <context>
+    Need user authentication for the app. Three solid options with different tradeoffs.
+  </context>
   <options>
-    <option id="supabase"><name>Supabase Auth</name><pros>Built-in with DB, free tier, RLS integration</pros><cons>Less customizable, ecosystem lock-in</cons></option>
-    <option id="clerk"><name>Clerk</name><pros>Beautiful UI, best DX</pros><cons>Paid after 10k MAU</cons></option>
-    <option id="nextauth"><name>NextAuth.js</name><pros>Free, self-hosted, max control</pros><cons>More setup, DIY security</cons></option>
+    <option id="supabase">
+      <name>Supabase Auth</name>
+      <pros>Built-in with Supabase DB we're using, generous free tier, row-level security integration</pros>
+      <cons>Less customizable UI, tied to Supabase ecosystem</cons>
+    </option>
+    <option id="clerk">
+      <name>Clerk</name>
+      <pros>Beautiful pre-built UI, best developer experience, excellent docs</pros>
+      <cons>Paid after 10k MAU, vendor lock-in</cons>
+    </option>
+    <option id="nextauth">
+      <name>NextAuth.js</name>
+      <pros>Free, self-hosted, maximum control, widely adopted</pros>
+      <cons>More setup work, you manage security updates, UI is DIY</cons>
+    </option>
   </options>
   <resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
 </task>
 ```
 
-## checkpoint:human-action (1% - rare)
+**Example: Database Selection**
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>Select database for user data</decision>
+  <context>
+    App needs persistent storage for users, sessions, and user-generated content.
+    Expected scale: 10k users, 1M records first year.
+  </context>
+  <options>
+    <option id="supabase">
+      <name>Supabase (Postgres)</name>
+      <pros>Full SQL, generous free tier, built-in auth, real-time subscriptions</pros>
+      <cons>Vendor lock-in for real-time features, less flexible than raw Postgres</cons>
+    </option>
+    <option id="planetscale">
+      <name>PlanetScale (MySQL)</name>
+      <pros>Serverless scaling, branching workflow, excellent DX</pros>
+      <cons>MySQL not Postgres, no foreign keys in free tier</cons>
+    </option>
+    <option id="convex">
+      <name>Convex</name>
+      <pros>Real-time by default, TypeScript-native, automatic caching</pros>
+      <cons>Newer platform, different mental model, less SQL flexibility</cons>
+    </option>
+  </options>
+  <resume-signal>Select: supabase, planetscale, or convex</resume-signal>
+</task>
+```
+</type>
 
-**When:** Action has NO CLI/API and requires human-only interaction.
+<type name="human-action">
+## 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
 <task type="checkpoint:human-action" gate="blocking">
-  <action>[Unavoidable manual step]</action>
-  <instructions>[What Claude automated] [ONE thing requiring human action]</instructions>
-  <verification>[What Claude checks afterward]</verification>
+  <action>[What human must do - Claude already did everything automatable]</action>
+  <instructions>
+    [What Claude already automated]
+    [The ONE thing requiring human action]
+  </instructions>
+  <verification>[What Claude can check afterward]</verification>
   <resume-signal>[How to continue]</resume-signal>
 </task>
 ```
 
-**Example (email verification):**
+**Key principle:** Claude automates EVERYTHING possible first, only asks human for the truly unavoidable manual step.
+
+**Example: Email Verification**
 ```xml
+<task type="auto">
+  <name>Create SendGrid account via API</name>
+  <action>Use SendGrid API to create subuser account with provided email. Request verification email.</action>
+  <verify>API returns 201, account created</verify>
+  <done>Account created, verification email sent</done>
+</task>
+
 <task type="checkpoint:human-action" gate="blocking">
   <action>Complete email verification for SendGrid account</action>
   <instructions>
     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.
   </instructions>
   <verification>SendGrid API key works: curl test succeeds</verification>
-  <resume-signal>Type "done" when verified</resume-signal>
+  <resume-signal>Type "done" when email verified</resume-signal>
+</task>
+```
+
+**Example: Credit Card 3D Secure**
+```xml
+<task type="auto">
+  <name>Create Stripe payment intent</name>
+  <action>Use Stripe API to create payment intent for $99. Generate checkout URL.</action>
+  <verify>Stripe API returns payment intent ID and URL</verify>
+  <done>Payment intent created</done>
+</task>
+
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Complete 3D Secure authentication</action>
+  <instructions>
+    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.
+  </instructions>
+  <verification>Stripe webhook receives payment_intent.succeeded event</verification>
+  <resume-signal>Type "done" when payment completes</resume-signal>
 </task>
 ```
 
+**Example: Authentication Gate (Dynamic Checkpoint)**
+```xml
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <files>.vercel/, vercel.json</files>
+  <action>Run `vercel --yes` to deploy</action>
+  <verify>vercel ls shows deployment, curl returns 200</verify>
+</task>
+
+<!-- If vercel returns "Error: Not authenticated", Claude creates checkpoint on the fly -->
+
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Authenticate Vercel CLI so I can continue deployment</action>
+  <instructions>
+    I tried to deploy but got authentication error.
+    Run: vercel login
+    This will open your browser - complete the authentication flow.
+  </instructions>
+  <verification>vercel whoami returns your account email</verification>
+  <resume-signal>Type "done" when authenticated</resume-signal>
+</task>
+
+<!-- After authentication, Claude retries the deployment -->
+
+<task type="auto">
+  <name>Retry Vercel deployment</name>
+  <action>Run `vercel --yes` (now authenticated)</action>
+  <verify>vercel ls shows deployment, curl returns 200</verify>
+</task>
+```
+
+**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.
+</type>
 </checkpoint_types>
 
 <execution_protocol>
@@ -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.
+════════════════════════════════════════
+```
 </execution_protocol>
 
 <authentication_gates>
@@ -148,30 +423,42 @@ Task [X] of [Y]: [Name]
 6. Retry the original task
 7. Continue normally
 
-**Example (Vercel auth gate):**
-```xml
-<!-- Claude tries to deploy -->
-<task type="auto">
-  <name>Deploy to Vercel</name>
-  <action>Run `vercel --yes` to deploy</action>
-</task>
+**Example execution flow (Vercel auth gate):**
 
-<!-- If vercel returns "Error: Not authenticated" -->
-<task type="checkpoint:human-action" gate="blocking">
-  <action>Authenticate Vercel CLI so I can continue</action>
-  <instructions>
-    I tried to deploy but got authentication error.
-    Run: vercel login (opens browser)
-  </instructions>
-  <verification>vercel whoami returns your account</verification>
-  <resume-signal>Type "done" when authenticated</resume-signal>
-</task>
+```
+Claude: Running `vercel --yes` to deploy...
 
-<!-- After auth, Claude retries automatically -->
-<task type="auto">
-  <name>Retry deployment</name>
-  <action>Run `vercel --yes` (now authenticated)</action>
-</task>
+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 |
 
 </automation_reference>
 
-<guidelines>
+<writing_guidelines>
 
 **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) ❌
+</writing_guidelines>
+
+<examples>
+
+### Example 1: Deployment Flow (Correct)
+
+```xml
+<!-- Claude automates everything -->
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <files>.vercel/, vercel.json, package.json</files>
+  <action>
+    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`
+  </action>
+  <verify>
+    - vercel ls shows deployment
+    - curl {url} returns 200
+    - Environment variables set correctly
+  </verify>
+  <done>App deployed to production, URL captured</done>
+</task>
+
+<!-- Human verifies visual/functional correctness -->
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Deployed to https://myapp.vercel.app</what-built>
+  <how-to-verify>
+    Visit https://myapp.vercel.app and confirm:
+    - Homepage loads correctly
+    - All images/assets load
+    - Navigation works
+    - No console errors
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+
+### Example 2: Database Setup (No Checkpoint Needed)
+
+```xml
+<!-- Claude automates everything -->
+<task type="auto">
+  <name>Create Upstash Redis database</name>
+  <files>.env</files>
+  <action>
+    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
+  </action>
+  <verify>
+    - upstash redis list shows database
+    - .env contains UPSTASH_REDIS_URL
+    - Test connection succeeds
+  </verify>
+  <done>Redis database created and configured</done>
+</task>
+
+<!-- NO CHECKPOINT NEEDED - Claude automated everything and verified programmatically -->
+```
+
+### Example 3: Stripe Webhooks (Correct)
+
+```xml
+<!-- Claude automates everything -->
+<task type="auto">
+  <name>Configure Stripe webhooks</name>
+  <files>.env, src/app/api/webhooks/route.ts</files>
+  <action>
+    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
+  </action>
+  <verify>
+    - Stripe API returns webhook endpoint ID
+    - .env contains STRIPE_WEBHOOK_SECRET
+    - curl webhook endpoint returns 200
+  </verify>
+  <done>Stripe webhooks configured and handler implemented</done>
+</task>
+
+<!-- Human verifies in Stripe dashboard -->
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Stripe webhook configured via API</what-built>
+  <how-to-verify>
+    Visit Stripe Dashboard > Developers > Webhooks
+    Confirm: Endpoint shows https://myapp.com/api/webhooks with correct events
+  </how-to-verify>
+  <resume-signal>Type "yes" if correct</resume-signal>
+</task>
+```
+
+### Example 4: Full Auth Flow Verification (Correct)
+
+```xml
+<task type="auto">
+  <name>Create user schema</name>
+  <files>src/db/schema.ts</files>
+  <action>Define User, Session, Account tables with Drizzle ORM</action>
+  <verify>npm run db:generate succeeds</verify>
+</task>
+
+<task type="auto">
+  <name>Create auth API routes</name>
+  <files>src/app/api/auth/[...nextauth]/route.ts</files>
+  <action>Set up NextAuth with GitHub provider, JWT strategy</action>
+  <verify>TypeScript compiles, no errors</verify>
+</task>
 
-</guidelines>
+<task type="auto">
+  <name>Create login UI</name>
+  <files>src/app/login/page.tsx, src/components/LoginButton.tsx</files>
+  <action>Create login page with GitHub OAuth button</action>
+  <verify>npm run build succeeds</verify>
+</task>
+
+<!-- ONE checkpoint at end verifies the complete flow -->
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Complete authentication flow (schema + API + UI)</what-built>
+  <how-to-verify>
+    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
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+</examples>
 
 <anti_patterns>
 
-**BAD: Asking human to automate**
+### ❌ BAD: Asking human to automate
+
 ```xml
-<task type="checkpoint:human-action">
+<task type="checkpoint:human-action" gate="blocking">
   <action>Deploy to Vercel</action>
-  <instructions>Visit vercel.com/new, import repo, click Deploy</instructions>
+  <instructions>
+    1. Visit vercel.com/new
+    2. Import Git repository
+    3. Click Deploy
+    4. Copy deployment URL
+  </instructions>
+  <verification>Deployment exists</verification>
+  <resume-signal>Paste URL</resume-signal>
+</task>
+```
+
+**Why bad:** Vercel has a CLI. Claude should run `vercel --yes`.
+
+### ✅ GOOD: Claude automates, human verifies
+
+```xml
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <action>Run `vercel --yes`. Capture URL.</action>
+  <verify>vercel ls shows deployment, curl returns 200</verify>
+</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Deployed to {url}</what-built>
+  <how-to-verify>Visit {url}, check homepage loads</how-to-verify>
+  <resume-signal>Type "approved"</resume-signal>
 </task>
 ```
-Why bad: Vercel has CLI. Use `vercel --yes`.
 
-**BAD: Too many checkpoints**
+### ❌ BAD: Too many checkpoints
+
 ```xml
 <task type="auto">Create schema</task>
 <task type="checkpoint:human-verify">Check schema</task>
-<task type="auto">Create API</task>
+<task type="auto">Create API route</task>
 <task type="checkpoint:human-verify">Check API</task>
+<task type="auto">Create UI form</task>
+<task type="checkpoint:human-verify">Check form</task>
 ```
-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
 <task type="auto">Create schema</task>
-<task type="auto">Create API</task>
-<task type="auto">Create UI</task>
+<task type="auto">Create API route</task>
+<task type="auto">Create UI form</task>
 
 <task type="checkpoint:human-verify">
-  <what-built>Complete auth flow</what-built>
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
   <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+  <resume-signal>Type "approved"</resume-signal>
+</task>
+```
+
+### ❌ BAD: Asking for automatable file operations
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Create .env file</action>
+  <instructions>
+    1. Create .env in project root
+    2. Add: DATABASE_URL=...
+    3. Add: STRIPE_KEY=...
+  </instructions>
+</task>
+```
+
+**Why bad:** Claude has Write tool. This should be `type="auto"`.
+
+### ❌ BAD: Vague verification steps
+
+```xml
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard</what-built>
+  <how-to-verify>Check it works</how-to-verify>
+  <resume-signal>Continue</resume-signal>
+</task>
+```
+
+**Why bad:** No specifics. User doesn't know what to test or what "works" means.
+
+### ✅ GOOD: Specific verification steps
+
+```xml
+<task type="checkpoint:human-verify">
+  <what-built>Responsive dashboard at /dashboard</what-built>
+  <how-to-verify>
+    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
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe layout issues</resume-signal>
 </task>
 ```
 
@@ -272,16 +776,18 @@ Why bad: Verification fatigue. Combine into one checkpoint at end.
 
 <summary>
 
+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
 </summary>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.4.26",
+  "version": "1.4.28",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"