get-shit-done-cc 1.9.2 → 1.9.4

package/agents/gsd-executor.md

@@ -347,6 +347,21 @@ Type "done" when authenticated.
 </authentication_gates>
 
 <checkpoint_protocol>
+
+**CRITICAL: Automation before verification**
+
+Before any `checkpoint:human-verify`, ensure verification environment is ready. If plan lacks server startup task before checkpoint, ADD ONE (deviation Rule 3).
+
+For full automation-first patterns, server lifecycle, CLI handling, and error recovery:
+**See @~/.claude/get-shit-done/references/checkpoints.md**
+
+**Quick reference:**
+- Users NEVER run CLI commands - Claude does all automation
+- Users ONLY visit URLs, click UI, evaluate visuals, provide secrets
+- Claude starts servers, seeds databases, configures env vars
+
+---
+
 When encountering `type="checkpoint:*"`:
 
 **STOP immediately.** Do not continue to next task.

package/bin/install.js

@@ -181,6 +181,9 @@ function cleanupOrphanedHooks(settings) {
   const orphanedHookPatterns = [
     'gsd-notify.sh',  // Removed in v1.6.x
     'hooks/statusline.js',  // Renamed to gsd-statusline.js in v1.9.0
+    'gsd-intel-index.js',  // Removed in v1.9.2
+    'gsd-intel-session.js',  // Removed in v1.9.2
+    'gsd-intel-prune.js',  // Removed in v1.9.2
   ];
 
   let cleaned = false;

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

@@ -2,6 +2,12 @@
 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.
+
+**Golden rules:**
+1. **If Claude can run it, Claude runs it** - Never ask user to execute CLI commands, start servers, or run builds
+2. **Claude sets up the verification environment** - Start dev servers, seed databases, configure env vars
+3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
+4. **Secrets come from user, automation comes from Claude** - Ask for API keys, then Claude uses them via CLI
 </overview>
 
 <checkpoint_types>
@@ -67,20 +73,28 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
   <done>Dashboard component builds without errors</done>
 </task>
 
+<task type="auto">
+  <name>Start dev server for verification</name>
+  <action>Run `npm run dev` in background, wait for "ready" message, capture port</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+  <done>Dev server running at http://localhost:3000</done>
+</task>
+
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Responsive dashboard layout at /dashboard</what-built>
+  <what-built>Responsive dashboard layout - dev server running at http://localhost:3000</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
+    Visit http://localhost:3000/dashboard and verify:
+    1. Desktop (>1024px): Sidebar left, content right, header top
+    2. Tablet (768px): Sidebar collapses to hamburger menu
+    3. Mobile (375px): Single column layout, bottom nav appears
+    4. No layout shift or horizontal scroll at any size
   </how-to-verify>
   <resume-signal>Type "approved" or describe layout issues</resume-signal>
 </task>
 ```
 
+**Key pattern:** Claude starts the dev server BEFORE the checkpoint. User only needs to visit the URL.
+
 **Example: Xcode Build**
 ```xml
 <task type="auto">
@@ -466,6 +480,8 @@ Task 3 complete. Continuing to task 4...
 
 **The rule:** If it has CLI/API, Claude does it. Never ask human to perform automatable work.
 
+## Service CLI Reference
+
 | Service | CLI/API | Key Commands | Auth Gate |
 |---------|---------|--------------|-----------|
 | Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |
@@ -476,13 +492,174 @@ Task 3 complete. Continuing to task 4...
 | 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 |
+| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A |
 | Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
-| Convex | `npx convex` | `dev`, `deploy`, `import` | `npx convex login` |
+| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` |
+
+## Environment Variable Automation
 
 **Env files:** Use Write/Edit tools. Never ask human to create .env manually.
 
-**Quick reference:**
+**Dashboard env vars via CLI:**
+
+| Platform | CLI Command | Example |
+|----------|-------------|---------|
+| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` |
+| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` |
+| Railway | `railway variables set` | `railway variables set API_KEY=value` |
+| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` |
+| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` |
+
+**Pattern for secret collection:**
+```xml
+<!-- WRONG: Asking user to add env vars in dashboard -->
+<task type="checkpoint:human-action">
+  <action>Add OPENAI_API_KEY to Convex dashboard</action>
+  <instructions>Go to dashboard.convex.dev → Settings → Environment Variables → Add</instructions>
+</task>
+
+<!-- RIGHT: Claude asks for value, then adds via CLI -->
+<task type="checkpoint:human-action">
+  <action>Provide your OpenAI API key</action>
+  <instructions>
+    I need your OpenAI API key to configure the Convex backend.
+    Get it from: https://platform.openai.com/api-keys
+    Paste the key (starts with sk-)
+  </instructions>
+  <verification>I'll add it via `npx convex env set` and verify it's configured</verification>
+  <resume-signal>Paste your API key</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Configure OpenAI key in Convex</name>
+  <action>Run `npx convex env set OPENAI_API_KEY {user-provided-key}`</action>
+  <verify>`npx convex env get OPENAI_API_KEY` returns the key (masked)</verify>
+</task>
+```
+
+## Dev Server Automation
+
+**Claude starts servers, user visits URLs:**
+
+| Framework | Start Command | Ready Signal | Default URL |
+|-----------|---------------|--------------|-------------|
+| Next.js | `npm run dev` | "Ready in" or "started server" | http://localhost:3000 |
+| Vite | `npm run dev` | "ready in" | http://localhost:5173 |
+| Convex | `npx convex dev` | "Convex functions ready" | N/A (backend only) |
+| Express | `npm start` | "listening on port" | http://localhost:3000 |
+| Django | `python manage.py runserver` | "Starting development server" | http://localhost:8000 |
+
+### Server Lifecycle Protocol
+
+**Starting servers:**
+```bash
+# Run in background, capture PID for cleanup
+npm run dev &
+DEV_SERVER_PID=$!
+
+# Wait for ready signal (max 30s)
+timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'
+```
+
+**Port conflicts:**
+If default port is in use, check what's running and either:
+1. Kill the existing process if it's stale: `lsof -ti:3000 | xargs kill`
+2. Use alternate port: `npm run dev -- --port 3001`
+
+**Server stays running** for the duration of the checkpoint. After user approves, server continues running for subsequent tasks. Only kill explicitly if:
+- Plan is complete and no more verification needed
+- Switching to production deployment
+- Port needed for different service
+
+**Pattern:**
+```xml
+<!-- Claude starts server before checkpoint -->
+<task type="auto">
+  <name>Start dev server</name>
+  <action>Run `npm run dev` in background, wait for ready signal</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+  <done>Dev server running</done>
+</task>
+
+<!-- User only visits URL -->
+<task type="checkpoint:human-verify">
+  <what-built>Feature X - dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    Visit http://localhost:3000/feature and verify:
+    1. [Visual check 1]
+    2. [Visual check 2]
+  </how-to-verify>
+</task>
+```
+
+## CLI Installation Handling
+
+**When a required CLI is not installed:**
+
+| CLI | Auto-install? | Command |
+|-----|---------------|---------|
+| npm/pnpm/yarn | No - ask user | User chooses package manager |
+| vercel | Yes | `npm i -g vercel` |
+| gh (GitHub) | Yes | `brew install gh` (macOS) or `apt install gh` (Linux) |
+| stripe | Yes | `npm i -g stripe` |
+| supabase | Yes | `npm i -g supabase` |
+| convex | No - use npx | `npx convex` (no install needed) |
+| fly | Yes | `brew install flyctl` or curl installer |
+| railway | Yes | `npm i -g @railway/cli` |
+
+**Protocol:**
+1. Try the command
+2. If "command not found", check if auto-installable
+3. If yes: install silently, retry command
+4. If no: create checkpoint asking user to install
+
+```xml
+<!-- Example: vercel not found -->
+<task type="auto">
+  <name>Install Vercel CLI</name>
+  <action>Run `npm i -g vercel`</action>
+  <verify>`vercel --version` succeeds</verify>
+  <done>Vercel CLI installed</done>
+</task>
+```
+
+## Pre-Checkpoint Automation Failures
+
+**When setup fails before checkpoint:**
+
+| Failure | Response |
+|---------|----------|
+| Server won't start | Check error output, fix issue, retry (don't proceed to checkpoint) |
+| Port in use | Kill stale process or use alternate port |
+| Missing dependency | Run `npm install`, retry |
+| Build error | Fix the error first (this is a bug, not a checkpoint issue) |
+| Auth error | Create auth gate checkpoint |
+| Network timeout | Retry with backoff, then checkpoint if persistent |
+
+**Key principle:** Never present a checkpoint with broken verification environment. If `curl localhost:3000` fails, don't ask user to "visit localhost:3000".
+
+```xml
+<!-- WRONG: Checkpoint with broken environment -->
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard (server failed to start)</what-built>
+  <how-to-verify>Visit http://localhost:3000...</how-to-verify>
+</task>
+
+<!-- RIGHT: Fix first, then checkpoint -->
+<task type="auto">
+  <name>Fix server startup issue</name>
+  <action>Investigate error, fix root cause, restart server</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+  <done>Server running correctly</done>
+</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard - server running at http://localhost:3000</what-built>
+  <how-to-verify>Visit http://localhost:3000/dashboard...</how-to-verify>
+</task>
+```
+
+## Quick Reference
 
 | Action | Automatable? | Claude does it? |
 |--------|--------------|-----------------|
@@ -491,9 +668,15 @@ Task 3 complete. Continuing to task 4...
 | Write .env file | Yes (Write tool) | YES |
 | Create Upstash DB | Yes (`upstash`) | YES |
 | Run tests | Yes (`npm test`) | YES |
+| Start dev server | Yes (`npm run dev`) | YES |
+| Add env vars to Convex | Yes (`npx convex env set`) | YES |
+| Add env vars to Vercel | Yes (`vercel env add`) | YES |
+| Seed database | Yes (CLI/API) | YES |
 | Click email verification link | No | NO |
 | Enter credit card with 3DS | No | NO |
 | Complete OAuth in browser | No | NO |
+| Visually verify UI looks correct | No | NO |
+| Test interactive user flows | No | NO |
 
 </automation_reference>
 
@@ -643,17 +826,23 @@ Task 3 complete. Continuing to task 4...
   <verify>npm run build succeeds</verify>
 </task>
 
-<!-- ONE checkpoint at end verifies the complete flow -->
+<task type="auto">
+  <name>Start dev server for auth testing</name>
+  <action>Run `npm run dev` in background, wait for ready signal</action>
+  <verify>curl http://localhost:3000 returns 200</verify>
+  <done>Dev server running at http://localhost:3000</done>
+</task>
+
+<!-- ONE checkpoint at end verifies the complete flow - Claude already started server -->
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Complete authentication flow (schema + API + UI)</what-built>
+  <what-built>Complete authentication flow - dev server running at http://localhost:3000</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
+    1. Visit: http://localhost:3000/login
+    2. Click "Sign in with GitHub"
+    3. Complete GitHub OAuth flow
+    4. Verify: Redirected to /dashboard, user name displayed
+    5. Refresh page: Session persists
+    6. Click logout: Session cleared
   </how-to-verify>
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
@@ -662,7 +851,77 @@ Task 3 complete. Continuing to task 4...
 
 <anti_patterns>
 
-### ❌ BAD: Asking human to automate
+### ❌ BAD: Asking user to start dev server
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dashboard component</what-built>
+  <how-to-verify>
+    1. Run: npm run dev
+    2. Visit: http://localhost:3000/dashboard
+    3. Check layout is correct
+  </how-to-verify>
+</task>
+```
+
+**Why bad:** Claude can run `npm run dev`. User should only visit URLs, not execute commands.
+
+### ✅ GOOD: Claude starts server, user visits
+
+```xml
+<task type="auto">
+  <name>Start dev server</name>
+  <action>Run `npm run dev` in background</action>
+  <verify>curl localhost:3000 returns 200</verify>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dashboard at http://localhost:3000/dashboard (server running)</what-built>
+  <how-to-verify>
+    Visit http://localhost:3000/dashboard and verify:
+    1. Layout matches design
+    2. No console errors
+  </how-to-verify>
+</task>
+```
+
+### ❌ BAD: Asking user to add env vars in dashboard
+
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Add environment variables to Convex</action>
+  <instructions>
+    1. Go to dashboard.convex.dev
+    2. Select your project
+    3. Navigate to Settings → Environment Variables
+    4. Add OPENAI_API_KEY with your key
+  </instructions>
+</task>
+```
+
+**Why bad:** Convex has `npx convex env set`. Claude should ask for the key value, then run the CLI command.
+
+### ✅ GOOD: Claude collects secret, adds via CLI
+
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Provide your OpenAI API key</action>
+  <instructions>
+    I need your OpenAI API key. Get it from: https://platform.openai.com/api-keys
+    Paste the key below (starts with sk-)
+  </instructions>
+  <verification>I'll configure it via CLI</verification>
+  <resume-signal>Paste your key</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Add OpenAI key to Convex</name>
+  <action>Run `npx convex env set OPENAI_API_KEY {key}`</action>
+  <verify>`npx convex env get` shows OPENAI_API_KEY configured</verify>
+</task>
+```
+
+### ❌ BAD: Asking human to deploy
 
 ```xml
 <task type="checkpoint:human-action" gate="blocking">
@@ -750,23 +1009,54 @@ Task 3 complete. Continuing to task 4...
 
 **Why bad:** No specifics. User doesn't know what to test or what "works" means.
 
-### ✅ GOOD: Specific verification steps
+### ✅ GOOD: Specific verification steps (server already running)
 
 ```xml
 <task type="checkpoint:human-verify">
-  <what-built>Responsive dashboard at /dashboard</what-built>
+  <what-built>Responsive dashboard - server running at http://localhost:3000</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
+    Visit http://localhost:3000/dashboard and verify:
+    1. Desktop (>1024px): Sidebar visible, content area fills remaining space
+    2. Tablet (768px): Sidebar collapses to icons
+    3. Mobile (375px): Sidebar hidden, hamburger menu in header
+    4. No horizontal scroll at any size
   </how-to-verify>
   <resume-signal>Type "approved" or describe layout issues</resume-signal>
 </task>
 ```
 
+### ❌ BAD: Asking user to run any CLI command
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Run database migrations</action>
+  <instructions>
+    1. Run: npx prisma migrate deploy
+    2. Run: npx prisma db seed
+    3. Verify tables exist
+  </instructions>
+</task>
+```
+
+**Why bad:** Claude can run these commands. User should never execute CLI commands.
+
+### ❌ BAD: Asking user to copy values between services
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Configure webhook URL in Stripe</action>
+  <instructions>
+    1. Copy the deployment URL from terminal
+    2. Go to Stripe Dashboard → Webhooks
+    3. Add endpoint with URL + /api/webhooks
+    4. Copy webhook signing secret
+    5. Add to .env file
+  </instructions>
+</task>
+```
+
+**Why bad:** Stripe has an API. Claude should create the webhook via API and write to .env directly.
+
 </anti_patterns>
 
 <summary>

package/get-shit-done/references/verification-patterns.md

@@ -593,3 +593,20 @@ Some things can't be verified programmatically. Flag these for human testing:
 ```
 
 </human_verification_triggers>
+
+<checkpoint_automation_reference>
+
+## Pre-Checkpoint Automation
+
+For automation-first checkpoint patterns, server lifecycle management, CLI installation handling, and error recovery protocols, see:
+
+**@~/.claude/get-shit-done/references/checkpoints.md** → `<automation_reference>` section
+
+Key principles:
+- Claude sets up verification environment BEFORE presenting checkpoints
+- Users never run CLI commands (visit URLs only)
+- Server lifecycle: start before checkpoint, handle port conflicts, keep running for duration
+- CLI installation: auto-install where safe, checkpoint for user choice otherwise
+- Error handling: fix broken environment before checkpoint, never present checkpoint with failed setup
+
+</checkpoint_automation_reference>

package/get-shit-done/templates/phase-prompt.md

@@ -75,33 +75,23 @@ Output: [What artifacts will be created]
   <done>[Acceptance criteria]</done>
 </task>
 
+<!-- For checkpoint task examples and patterns, see @~/.claude/get-shit-done/references/checkpoints.md -->
+<!-- Key rule: Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
+
 <task type="checkpoint:decision" gate="blocking">
   <decision>[What needs deciding]</decision>
   <context>[Why this decision matters]</context>
   <options>
-    <option id="option-a">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
-    <option id="option-b">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
+    <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>
   </options>
-  <resume-signal>[How to indicate choice - "Select: option-a or option-b"]</resume-signal>
+  <resume-signal>Select: option-a or option-b</resume-signal>
 </task>
 
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[What Claude just built that needs verification]</what-built>
-  <how-to-verify>
-    1. Run: [command to start dev server/app]
-    2. Visit: [URL to check]
-    3. Test: [Specific interactions]
-    4. Confirm: [Expected behaviors]
-  </how-to-verify>
-  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
+  <what-built>[What Claude built] - server running at [URL]</what-built>
+  <how-to-verify>Visit [URL] and verify: [visual checks only, NO CLI commands]</how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 
 </tasks>
@@ -403,15 +393,16 @@ Output: Working dashboard component.
   <done>Dashboard renders without errors</done>
 </task>
 
+<!-- Checkpoint pattern: Claude starts server, user visits URL. See checkpoints.md for full patterns. -->
+<task type="auto">
+  <name>Start dev server</name>
+  <action>Run `npm run dev` in background, wait for ready</action>
+  <verify>curl localhost:3000 returns 200</verify>
+</task>
+
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Responsive dashboard with user and product sections</what-built>
-  <how-to-verify>
-    1. Run: npm run dev
-    2. Visit: http://localhost:3000/dashboard
-    3. Desktop: Verify two-column grid
-    4. Mobile: Verify stacked layout
-    5. Check: No layout shift, no scroll issues
-  </how-to-verify>
+  <what-built>Dashboard - server at http://localhost:3000</what-built>
+  <how-to-verify>Visit localhost:3000/dashboard. Check: desktop grid, mobile stack, no scroll issues.</how-to-verify>
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 </tasks>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "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"