@undeemed/get-shit-done-codex 1.6.12 → 1.20.3

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

@@ -1,7 +1,13 @@
 <overview>
-Plans execute autonomously. Checkpoints formalize the interaction points where human verification or decisions are needed.
+Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
 
-**Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
+**Core principle:** Codex automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
+
+**Golden rules:**
+1. **If Codex can run it, Codex runs it** - Never ask user to execute CLI commands, start servers, or run builds
+2. **Codex 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 Codex** - Ask for API keys, then Codex uses them via CLI
 </overview>
 
 <checkpoint_types>
@@ -9,7 +15,7 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 <type name="human-verify">
 ## checkpoint:human-verify (Most Common - 90%)
 
-**When:** Claude completed automated work, human confirms it works correctly.
+**When:** Codex completed automated work, human confirms it works correctly.
 
 **Use for:**
 - Visual UI checks (layout, styling, responsiveness)
@@ -22,7 +28,7 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 **Structure:**
 ```xml
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[What Claude automated and deployed/built]</what-built>
+  <what-built>[What Codex automated and deployed/built]</what-built>
   <how-to-verify>
     [Exact steps to test - URLs, commands, expected behavior]
   </how-to-verify>
@@ -30,34 +36,7 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 </task>
 ```
 
-**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>
-  <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 Vercel at https://myapp-abc123.vercel.app</what-built>
-  <how-to-verify>
-    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**
+**Example: UI Component (shows key pattern: Codex starts server BEFORE checkpoint)**
 ```xml
 <task type="auto">
   <name>Build responsive dashboard layout</name>
@@ -67,15 +46,21 @@ 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>
@@ -138,12 +123,6 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 </task>
 ```
 
-**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">
@@ -205,38 +184,35 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 <type name="human-action">
 ## checkpoint:human-action (1% - Rare)
 
-**When:** Action has NO CLI/API and requires human-only interaction, OR Claude hit an authentication gate during automation.
+**When:** Action has NO CLI/API and requires human-only interaction, OR Codex 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)
+- **Authentication gates** - Codex tried CLI/API but needs credentials (this is NOT a failure)
+- Email verification links (clicking email)
 - SMS 2FA codes (phone verification)
-- Manual account approvals (platform requires human review before API access)
+- Manual account approvals (platform requires human review)
 - Credit card 3D Secure flows (web-based payment authorization)
-- OAuth app approvals (some platforms require web-based approval)
+- OAuth app approvals (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)
+- Deploying (use CLI - auth gate if needed)
+- Creating webhooks/databases (use API/CLI - auth gate if needed)
+- Running builds/tests (use Bash tool)
+- Creating files (use Write tool)
 
 **Structure:**
 ```xml
 <task type="checkpoint:human-action" gate="blocking">
-  <action>[What human must do - Claude already did everything automatable]</action>
+  <action>[What human must do - Codex already did everything automatable]</action>
   <instructions>
-    [What Claude already automated]
+    [What Codex already automated]
     [The ONE thing requiring human action]
   </instructions>
-  <verification>[What Claude can check afterward]</verification>
+  <verification>[What Codex can check afterward]</verification>
   <resume-signal>[How to continue]</resume-signal>
 </task>
 ```
 
-**Key principle:** Claude automates EVERYTHING possible first, only asks human for the truly unavoidable manual step.
-
 **Example: Email Verification**
 ```xml
 <task type="auto">
@@ -257,26 +233,6 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 </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">
@@ -286,7 +242,7 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
   <verify>vercel ls shows deployment, curl returns 200</verify>
 </task>
 
-<!-- If vercel returns "Error: Not authenticated", Claude creates checkpoint on the fly -->
+<!-- If vercel returns "Error: Not authenticated", Codex creates checkpoint on the fly -->
 
 <task type="checkpoint:human-action" gate="blocking">
   <action>Authenticate Vercel CLI so I can continue deployment</action>
@@ -299,7 +255,7 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
   <resume-signal>Type "done" when authenticated</resume-signal>
 </task>
 
-<!-- After authentication, Claude retries the deployment -->
+<!-- After authentication, Codex retries the deployment -->
 
 <task type="auto">
   <name>Retry Vercel deployment</name>
@@ -308,13 +264,13 @@ Plans execute autonomously. Checkpoints formalize the interaction points where h
 </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.
+**Key distinction:** Auth gates are created dynamically when Codex encounters auth errors. NOT pre-planned — Codex automates first, asks for credentials only when blocked.
 </type>
 </checkpoint_types>
 
 <execution_protocol>
 
-When Claude encounters `type="checkpoint:*"`:
+When Codex encounters `type="checkpoint:*"`:
 
 1. **Stop immediately** - do not proceed to next task
 2. **Display checkpoint clearly** using the format below
@@ -334,11 +290,10 @@ Task: Responsive dashboard layout
 Built: Responsive dashboard at /dashboard
 
 How to verify:
-  1. Run: npm run dev
-  2. Visit: http://localhost:3000/dashboard
-  3. Desktop (>1024px): Sidebar visible, content fills remaining space
-  4. Tablet (768px): Sidebar collapses to icons
-  5. Mobile (375px): Sidebar hidden, hamburger menu appears
+  1. Visit: http://localhost:3000/dashboard
+  2. Desktop (>1024px): Sidebar visible, content fills remaining space
+  3. Tablet (768px): Sidebar collapses to icons
+  4. Mobile (375px): Sidebar hidden, hamburger menu appears
 
 ────────────────────────────────────────────────────────
 → YOUR ACTION: Type "approved" or describe issues
@@ -403,9 +358,9 @@ I'll verify: vercel whoami returns your account
 
 <authentication_gates>
 
-**Critical:** When Claude tries CLI/API and gets auth error, this is NOT a failure - it's a gate requiring human input to unblock automation.
+**Auth gate = Codex tried CLI/API, got auth error.** Not a failure — a gate requiring human input to unblock.
 
-**Pattern:** Claude tries automation → auth error → creates checkpoint → you authenticate → Claude retries → continues
+**Pattern:** Codex tries automation → auth error → creates checkpoint:human-action → user authenticates → Codex retries → continues
 
 **Gate protocol:**
 1. Recognize it's not a failure - missing auth is expected
@@ -416,55 +371,17 @@ I'll verify: vercel whoami returns your account
 6. Retry the original task
 7. Continue normally
 
-**Example execution flow (Vercel auth gate):**
-
-```
-Claude: Running `vercel --yes` to deploy...
-
-Error: Not authenticated. Please run 'vercel login'
-
-╔═══════════════════════════════════════════════════════╗
-║  CHECKPOINT: Action Required                          ║
-╚═══════════════════════════════════════════════════════╝
-
-Progress: 2/8 tasks complete
-Task: Deploy to Vercel
-
-Attempted: vercel --yes
-Error: Not authenticated
-
-What you need to do:
-  1. Run: vercel login
-  2. Complete browser authentication
-
-I'll verify: vercel whoami returns your account
-
-────────────────────────────────────────────────────────
-→ YOUR ACTION: 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:**
-- Pre-planned checkpoint: "I need you to do X" (wrong - Claude should automate)
+- Pre-planned checkpoint: "I need you to do X" (wrong - Codex should automate)
 - Auth gate: "I tried to automate X but need credentials" (correct - unblocks automation)
 
 </authentication_gates>
 
 <automation_reference>
 
-**The rule:** If it has CLI/API, Claude does it. Never ask human to perform automatable work.
+**The rule:** If it has CLI/API, Codex does it. Never ask human to perform automatable work.
+
+## Service CLI Reference
 
 | Service | CLI/API | Key Commands | Auth Gate |
 |---------|---------|--------------|-----------|
@@ -476,24 +393,141 @@ 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` |
+
+**Secret collection pattern:**
+```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: Codex 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 for 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</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
+
+| 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:**
+```bash
+# Run in background, capture PID
+npm run dev &
+DEV_SERVER_PID=$!
+
+# Wait for ready (max 30s)
+timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'
+```
+
+**Port conflicts:** Kill stale process (`lsof -ti:3000 | xargs kill`) or use alternate port (`--port 3001`).
+
+**Server stays running** through checkpoints. Only kill when plan complete, switching to production, or port needed for different service.
+
+## CLI Installation Handling
+
+| 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:** Try command → "command not found" → auto-installable? → yes: install silently, retry → no: checkpoint asking user to install.
+
+## Pre-Checkpoint Automation Failures
+
+| Failure | Response |
+|---------|----------|
+| Server won't start | Check error, 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 (bug, not checkpoint issue) |
+| Auth error | Create auth gate checkpoint |
+| Network timeout | Retry with backoff, then checkpoint if persistent |
+
+**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>
+</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>
+```
+
+## Automatable Quick Reference
 
-| Action | Automatable? | Claude does it? |
+| Action | Automatable? | Codex does it? |
 |--------|--------------|-----------------|
 | Deploy to Vercel | Yes (`vercel`) | YES |
 | Create Stripe webhook | Yes (API) | YES |
 | Write .env file | Yes (Write tool) | YES |
 | Create Upstash DB | Yes (`upstash`) | YES |
 | Run tests | Yes (`npm test`) | YES |
+| 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>
 
@@ -502,71 +536,30 @@ Task 3 complete. Continuing to task 4...
 **DO:**
 - Automate everything with CLI/API before checkpoint
 - Be specific: "Visit https://myapp.vercel.app" not "check deployment"
-- Number verification steps: easier to follow
+- Number verification steps
 - 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)
+- Ask human to do work Codex can automate ❌
 - 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)
+- Skip steps: "Set up database" (too vague) ❌
+- Mix multiple verifications in one checkpoint ❌
 
 **Placement:**
-- **After automation completes** - not before Claude does the work
+- **After automation completes** - not before Codex 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) ❌
+**Bad placement:** Before automation ❌ | Too frequent ❌ | Too late (dependent tasks already needed the 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)
+### Example 1: Database Setup (No Checkpoint Needed)
 
 ```xml
-<!-- Claude automates everything -->
 <task type="auto">
   <name>Create Upstash Redis database</name>
   <files>.env</files>
@@ -584,42 +577,10 @@ Task 3 complete. Continuing to task 4...
   <done>Redis database created and configured</done>
 </task>
 
-<!-- NO CHECKPOINT NEEDED - Claude automated everything and verified programmatically -->
+<!-- NO CHECKPOINT NEEDED - Codex 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)
+### Example 2: Full Auth Flow (Single checkpoint at end)
 
 ```xml
 <task type="auto">
@@ -643,17 +604,23 @@ Task 3 complete. Continuing to task 4...
   <verify>npm run build succeeds</verify>
 </task>
 
+<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 -->
 <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,27 +629,50 @@ 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-action" gate="blocking">
-  <action>Deploy to Vercel</action>
-  <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 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:** Vercel has a CLI. Claude should run `vercel --yes`.
+**Why bad:** Codex can run `npm run dev`. User should only visit URLs, not execute commands.
+
+### ✅ GOOD: Codex 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>
+```
 
-### ✅ GOOD: Claude automates, human verifies
+### ❌ BAD: Asking human to deploy / ✅ GOOD: Codex automates
 
 ```xml
+<!-- BAD: Asking user to deploy via dashboard -->
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com/new → Import repo → Click Deploy → Copy URL</instructions>
+</task>
+
+<!-- GOOD: Codex deploys, user verifies -->
 <task type="auto">
   <name>Deploy to Vercel</name>
   <action>Run `vercel --yes`. Capture URL.</action>
@@ -696,22 +686,18 @@ Task 3 complete. Continuing to task 4...
 </task>
 ```
 
-### ❌ BAD: Too many checkpoints
+### ❌ BAD: Too many checkpoints / ✅ GOOD: Single checkpoint
 
 ```xml
+<!-- BAD: Checkpoint after every task -->
 <task type="auto">Create schema</task>
 <task type="checkpoint:human-verify">Check schema</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: Single verification checkpoint
 
-```xml
+<!-- GOOD: One checkpoint at end -->
 <task type="auto">Create schema</task>
 <task type="auto">Create API route</task>
 <task type="auto">Create UI form</task>
@@ -723,66 +709,67 @@ Task 3 complete. Continuing to task 4...
 </task>
 ```
 
-### ❌ BAD: Asking for automatable file operations
+### ❌ BAD: Vague verification / ✅ GOOD: Specific steps
 
 ```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>
+<!-- BAD -->
+<task type="checkpoint:human-verify">
+  <what-built>Dashboard</what-built>
+  <how-to-verify>Check it works</how-to-verify>
 </task>
-```
 
-**Why bad:** Claude has Write tool. This should be `type="auto"`.
+<!-- GOOD -->
+<task type="checkpoint:human-verify">
+  <what-built>Responsive dashboard - server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    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: Vague verification steps
+### ❌ BAD: Asking user to run CLI commands
 
 ```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 type="checkpoint:human-action">
+  <action>Run database migrations</action>
+  <instructions>Run: npx prisma migrate deploy && npx prisma db seed</instructions>
 </task>
 ```
 
-**Why bad:** No specifics. User doesn't know what to test or what "works" means.
+**Why bad:** Codex can run these commands. User should never execute CLI commands.
 
-### ✅ GOOD: Specific verification steps
+### ❌ BAD: Asking user to copy values between services
 
 ```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 type="checkpoint:human-action">
+  <action>Configure webhook URL in Stripe</action>
+  <instructions>Copy deployment URL → Stripe Dashboard → Webhooks → Add endpoint → Copy secret → Add to .env</instructions>
 </task>
 ```
 
+**Why bad:** Stripe has an API. Codex should create the webhook via API and write to .env directly.
+
 </anti_patterns>
 
 <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.
+Checkpoints formalize human-in-the-loop points for verification and decisions, not manual work.
 
-**The golden rule:** If Claude CAN automate it, Claude MUST automate it.
+**The golden rule:** If Codex CAN automate it, Codex 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
+1. **checkpoint:human-verify** (90%) - Codex automated everything, human confirms visual/functional correctness
+2. **checkpoint:decision** (9%) - Human makes architectural/technology choices
+3. **checkpoint:human-action** (1%) - Truly unavoidable manual steps with no API/CLI
 
 **When NOT to use checkpoints:**
-- Things Claude can verify programmatically (tests pass, build succeeds)
-- File operations (Claude can read files to verify)
-- Code correctness (use tests and static analysis)
+- Things Codex can verify programmatically (tests, builds)
+- File operations (Codex can read files)
+- Code correctness (tests and static analysis)
 - Anything automatable via CLI/API
 </summary>