From 5d16432887957ed510809617e0dc18fcf3bb691b Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Mon, 29 Dec 2025 12:07:39 -0600 Subject: [PATCH] feat(04-01): merge cli-automation into checkpoints, compress plan-format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Consolidated checkpoints.md with automation reference (287 lines from 1,121) - Compressed plan-format.md to reference card (127 lines from 397) - Deleted cli-automation.md (merged into checkpoints.md) - Updated plan-phase.md to remove stale reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- commands/gsd/plan-phase.md | 1 - get-shit-done/references/checkpoints.md | 607 +++++---------------- get-shit-done/references/cli-automation.md | 527 ------------------ get-shit-done/references/plan-format.md | 382 ++----------- 4 files changed, 206 insertions(+), 1311 deletions(-) delete mode 100644 get-shit-done/references/cli-automation.md diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 0c5dddaf4..493d6fdb0 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -25,7 +25,6 @@ Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-na @~/.claude/get-shit-done/references/plan-format.md @~/.claude/get-shit-done/references/scope-estimation.md @~/.claude/get-shit-done/references/checkpoints.md -@~/.claude/get-shit-done/references/cli-automation.md diff --git a/get-shit-done/references/checkpoints.md b/get-shit-done/references/checkpoints.md index 50625233d..7cc7b8308 100644 --- a/get-shit-done/references/checkpoints.md +++ b/get-shit-done/references/checkpoints.md @@ -1,286 +1,110 @@ -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. - -## checkpoint:human-verify (Most Common) +## checkpoint:human-verify (90% of checkpoints) **When:** Claude completed automated work, human confirms it works correctly. -**Use for:** -- Visual UI checks (layout, styling, responsiveness) -- Interactive flows (click through wizard, test user flows) -- Functional verification (feature works as expected) -- Audio/video playback quality -- Animation smoothness -- Accessibility testing +**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing. **Structure:** ```xml - [What Claude automated and deployed/built] - - [Exact steps to test - URLs, commands, expected behavior] - - [How to continue - "approved", "yes", or describe issues] + [What Claude automated] + [Numbered steps - URLs, commands, expected behavior] + [How to continue - "approved" or describe issues] ``` -**Key elements:** -- ``: What Claude automated (deployed, built, configured) -- ``: Exact steps to confirm it works (numbered, specific) -- ``: Clear indication of how to continue - -**Example: Vercel Deployment** +**Example:** ```xml Deploy to Vercel - .vercel/, vercel.json - Run `vercel --yes` to create project and deploy. Capture deployment URL from output. + Run `vercel --yes` to deploy. Capture URL. vercel ls shows deployment, curl {url} returns 200 - App deployed, URL captured - Deployed to Vercel at https://myapp-abc123.vercel.app + Deployed to https://myapp.vercel.app - Visit https://myapp-abc123.vercel.app and confirm: - - Homepage loads without errors - - Login form is visible - - No console errors in browser DevTools - - Type "approved" to continue, or describe issues to fix - -``` - -**Example: UI Component** -```xml - - Build responsive dashboard layout - src/components/Dashboard.tsx, src/app/dashboard/page.tsx - Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile. - npm run build succeeds, no TypeScript errors - Dashboard component builds without errors - - - - Responsive dashboard layout at /dashboard - - 1. Run: npm run dev - 2. Visit: http://localhost:3000/dashboard - 3. Desktop (>1024px): Verify sidebar left, content right, header top - 4. Tablet (768px): Verify sidebar collapses to hamburger - 5. Mobile (375px): Verify single column, bottom nav - 6. Check: No layout shift, no horizontal scroll - - Type "approved" or describe layout issues - -``` - -**Example: Xcode Build** -```xml - - Build macOS app with Xcode - App.xcodeproj, Sources/ - Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output. - Build output contains "BUILD SUCCEEDED", no errors - App builds successfully - - - - Built macOS app at DerivedData/Build/Products/Debug/App.app - - Open App.app and test: - - App launches without crashes - - Menu bar icon appears - - Preferences window opens correctly - - No visual glitches or layout issues + Visit URL and confirm: + 1. Homepage loads without errors + 2. All images/assets load + 3. No console errors Type "approved" or describe issues ``` - - -## checkpoint:decision +## checkpoint:decision (9% of checkpoints) **When:** Human must make choice that affects implementation direction. -**Use for:** -- Technology selection (which auth provider, which database) -- Architecture decisions (monorepo vs separate repos) -- Design choices (color scheme, layout approach) -- Feature prioritization (which variant to build) -- Data model decisions (schema structure) +**Use for:** Technology selection, architecture decisions, design choices, feature prioritization. **Structure:** ```xml [What's being decided] - [Why this decision matters] + [Why this matters] - - + + [How to indicate choice] ``` -**Key elements:** -- ``: What's being decided -- ``: Why this matters -- ``: Each option with balanced pros/cons (not prescriptive) -- ``: How to indicate choice - -**Example: Auth Provider Selection** +**Example:** ```xml Select authentication provider - - Need user authentication for the app. Three solid options with different tradeoffs. - + Need user auth. Three options with different tradeoffs. - - - + + + Select: supabase, clerk, or nextauth ``` - - -## checkpoint:human-action (Rare) +## 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. -**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) +**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals. -**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) +**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use Bash), file operations (use Write/Edit). **Structure:** ```xml - [What human must do - Claude already did everything automatable] - - [What Claude already automated] - [The ONE thing requiring human action] - - [What Claude can check afterward] + [Unavoidable manual step] + [What Claude automated] [ONE thing requiring human action] + [What Claude checks afterward] [How to continue] ``` -**Key principle:** Claude automates EVERYTHING possible first, only asks human for the truly unavoidable manual step. - -**Example: Email Verification** +**Example (email verification):** ```xml - - Create SendGrid account via API - Use SendGrid API to create subuser account with provided email. Request verification email. - API returns 201, account created - Account created, verification email sent - - Complete email verification for SendGrid account I created the account and requested verification email. - Check your inbox for SendGrid verification link and click it. + Check your inbox for verification link and click it. SendGrid API key works: curl test succeeds - Type "done" when email verified + Type "done" when verified ``` -**Example: Credit Card 3D Secure** -```xml - - Create Stripe payment intent - Use Stripe API to create payment intent for $99. Generate checkout URL. - Stripe API returns payment intent ID and URL - Payment intent created - - - - Complete 3D Secure authentication - - I created the payment intent: https://checkout.stripe.com/pay/cs_test_abc123 - Visit that URL and complete the 3D Secure verification flow with your test card. - - Stripe webhook receives payment_intent.succeeded event - Type "done" when payment completes - -``` - -**Example: Authentication Gate (Dynamic Checkpoint)** -```xml - - Deploy to Vercel - .vercel/, vercel.json - Run `vercel --yes` to deploy - vercel ls shows deployment, curl returns 200 - - - - - - Authenticate Vercel CLI so I can continue deployment - - I tried to deploy but got authentication error. - Run: vercel login - This will open your browser - complete the authentication flow. - - vercel whoami returns your account email - Type "done" when authenticated - - - - - - Retry Vercel deployment - Run `vercel --yes` (now authenticated) - vercel ls shows deployment, curl returns 200 - -``` - -**Key distinction:** Authentication gates are created dynamically when Claude encounters auth errors during automation. They're NOT pre-planned - Claude tries to automate first, only asks for credentials when blocked. - @@ -297,298 +121,167 @@ CHECKPOINT: [Type] Task [X] of [Y]: [Name] -[Display checkpoint-specific content] +[Checkpoint-specific content] [Resume signal instruction] ════════════════════════════════════════ ``` 3. **Wait for user response** - do not hallucinate completion -4. **Verify if possible** - check files, run tests, whatever is specified -5. **Resume execution** - continue to next task only after confirmation +4. **Verify if possible** - check files, run tests +5. **Resume execution** - continue only after confirmation -**For checkpoint:human-verify:** -``` -════════════════════════════════════════ -CHECKPOINT: Verification Required -════════════════════════════════════════ - -Task 5 of 8: Responsive dashboard layout - -I built: Responsive dashboard at /dashboard - -How to verify: -1. Run: npm run dev -2. Visit: http://localhost:3000/dashboard -3. Test: Resize browser window to mobile/tablet/desktop -4. Confirm: No layout shift, proper responsive behavior - -Type "approved" to continue, or describe issues. -════════════════════════════════════════ -``` - -**For checkpoint:decision:** -``` -════════════════════════════════════════ -CHECKPOINT: Decision Required -════════════════════════════════════════ - -Task 2 of 6: Select authentication provider - -Decision: Which auth provider should we use? - -Context: Need user authentication. Three options with different tradeoffs. - -Options: -1. supabase - Built-in with our DB, free tier -2. clerk - Best DX, paid after 10k users -3. nextauth - Self-hosted, maximum control - -Select: supabase, clerk, or nextauth -════════════════════════════════════════ -``` - + + +**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. + +**Pattern:** Claude tries automation → auth error → creates checkpoint → you authenticate → Claude retries → continues + +**Gate protocol:** +1. Recognize it's not a failure - missing auth is expected +2. Stop current task - don't retry repeatedly +3. Create checkpoint:human-action dynamically +4. Provide exact authentication steps +5. Verify authentication works +6. Retry the original task +7. Continue normally + +**Example (Vercel auth gate):** +```xml + + + Deploy to Vercel + Run `vercel --yes` to deploy + + + + + Authenticate Vercel CLI so I can continue + + I tried to deploy but got authentication error. + Run: vercel login (opens browser) + + vercel whoami returns your account + Type "done" when authenticated + + + + + Retry deployment + Run `vercel --yes` (now authenticated) + +``` + +**Key distinction:** +- Pre-planned checkpoint: "I need you to do X" (wrong - Claude should automate) +- Auth gate: "I tried to automate X but need credentials" (correct - unblocks automation) + + + + + +**The rule:** If it has CLI/API, Claude does it. Never ask human to perform automatable work. + +| Service | CLI/API | Key Commands | Auth Gate | +|---------|---------|--------------|-----------| +| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` | +| Railway | `railway` | `init`, `up`, `variables set` | `railway login` | +| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` | +| Stripe | `stripe` + API | `listen`, `trigger`, API calls | API key in .env | +| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` | +| 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 | +| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A | + +**Env files:** Use Write/Edit tools. Never ask human to create .env manually. + +**Quick reference:** + +| Action | Automatable? | Claude 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 | +| Click email verification link | No | NO | +| Enter credit card with 3DS | No | NO | + + + + **DO:** - Automate everything with CLI/API before checkpoint - Be specific: "Visit https://myapp.vercel.app" not "check deployment" -- Number verification steps: easier to follow -- State expected outcomes: "You should see X" -- Provide context: why this checkpoint exists -- Make verification executable: clear, testable steps +- Number verification steps +- State expected outcomes +- Make verification executable **DON'T:** -- Ask human to do work Claude can automate (deploy, create resources, run builds) -- Assume knowledge: "Configure the usual settings" ❌ -- Skip steps: "Set up database" ❌ (too vague) -- Mix multiple verifications in one checkpoint (split them) -- Make verification impossible (Claude can't check visual appearance without user confirmation) - +- 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) - +**Placement:** +- After automation completes (not before) +- After UI buildout +- Before dependent work (decisions) +- At integration points -**Use checkpoint:human-verify for:** -- Visual verification (UI, layouts, animations) -- Interactive testing (click flows, user journeys) -- Quality checks (audio/video playback, animation smoothness) -- Confirming deployed apps are accessible - -**Use checkpoint:decision for:** -- Technology selection (auth providers, databases, frameworks) -- Architecture choices (monorepo, deployment strategy) -- Design decisions (color schemes, layout approaches) -- Feature prioritization - -**Use checkpoint:human-action for:** -- Email verification links (no API) -- SMS 2FA codes (no API) -- Manual approvals with no automation -- 3D Secure payment flows - -**Don't use checkpoints for:** -- Things Claude can verify programmatically (tests pass, build succeeds) -- File operations (Claude can read files to verify) -- Code correctness (use tests and static analysis) -- Anything automatable via CLI/API - - - - -Place checkpoints: -- **After automation completes** - not before Claude does the work -- **After UI buildout** - before declaring phase complete -- **Before dependent work** - decisions before implementation -- **At integration points** - after configuring external services - -Bad placement: -- Before Claude automates (asking human to do automatable work) ❌ -- Too frequent (every other task is a checkpoint) ❌ -- Too late (checkpoint is last task, but earlier tasks needed its result) ❌ - - - - -### Example 1: Deployment Flow (Correct) - -```xml - - - Deploy to Vercel - .vercel/, vercel.json, package.json - - 1. Run `vercel --yes` to create project and deploy - 2. Capture deployment URL from output - 3. Set environment variables with `vercel env add` - 4. Trigger production deployment with `vercel --prod` - - - - vercel ls shows deployment - - curl {url} returns 200 - - Environment variables set correctly - - App deployed to production, URL captured - - - - - Deployed to https://myapp.vercel.app - - Visit https://myapp.vercel.app and confirm: - - Homepage loads correctly - - All images/assets load - - Navigation works - - No console errors - - Type "approved" or describe issues - -``` - -### Example 2: Database Setup (Correct) - -```xml - - - Create Upstash Redis database - .env - - 1. Run `upstash redis create myapp-cache --region us-east-1` - 2. Capture connection URL from output - 3. Write to .env: UPSTASH_REDIS_URL={url} - 4. Verify connection with test command - - - - upstash redis list shows database - - .env contains UPSTASH_REDIS_URL - - Test connection succeeds - - Redis database created and configured - - - -``` - -### Example 3: Stripe Webhooks (Correct) - -```xml - - - Configure Stripe webhooks - .env, src/app/api/webhooks/route.ts - - 1. Use Stripe API to create webhook endpoint pointing to /api/webhooks - 2. Subscribe to events: payment_intent.succeeded, customer.subscription.updated - 3. Save webhook signing secret to .env - 4. Implement webhook handler in route.ts - - - - Stripe API returns webhook endpoint ID - - .env contains STRIPE_WEBHOOK_SECRET - - curl webhook endpoint returns 200 - - Stripe webhooks configured and handler implemented - - - - - Stripe webhook configured via API - - Visit Stripe Dashboard > Developers > Webhooks - Confirm: Endpoint shows https://myapp.com/api/webhooks with correct events - - Type "yes" if correct - -``` - + -### ❌ BAD: Asking human to automate - +**BAD: Asking human to automate** ```xml - + Deploy to Vercel - - 1. Visit vercel.com/new - 2. Import Git repository - 3. Click Deploy - 4. Copy deployment URL - - Deployment exists - Paste URL + Visit vercel.com/new, import repo, click Deploy ``` +Why bad: Vercel has CLI. Use `vercel --yes`. -**Why bad:** Vercel has a CLI. Claude should run `vercel --yes`. - -### ✅ GOOD: Claude automates, human verifies - -```xml - - Deploy to Vercel - Run `vercel --yes`. Capture URL. - vercel ls shows deployment, curl returns 200 - - - - Deployed to {url} - Visit {url}, check homepage loads - Type "approved" - -``` - -### ❌ BAD: Too many checkpoints - +**BAD: Too many checkpoints** ```xml Create schema Check schema -Create API route +Create API Check API -Create UI form -Check form ``` +Why bad: Verification fatigue. Combine into one checkpoint at end. -**Why bad:** Verification fatigue. Combine into one checkpoint at end. - -### ✅ GOOD: Single verification checkpoint - +**GOOD: Claude automates, human verifies once** ```xml Create schema -Create API route -Create UI form +Create API +Create UI - Complete auth flow (schema + API + UI) + Complete auth flow Test full flow: register, login, access protected page - Type "approved" ``` -### ❌ BAD: Asking for automatable file operations - -```xml - - Create .env file - - 1. Create .env in project root - 2. Add: DATABASE_URL=... - 3. Add: STRIPE_KEY=... - - -``` - -**Why bad:** Claude has Write tool. This should be `type="auto"`. -Checkpoints formalize human-in-the-loop points. Use them when Claude cannot complete a task autonomously OR when human verification is required for correctness. - **The golden rule:** If Claude CAN automate it, Claude MUST automate it. **Checkpoint priority:** -1. **checkpoint:human-verify** (90% of checkpoints) - Claude automated everything, human confirms visual/functional correctness -2. **checkpoint:decision** (9% of checkpoints) - Human makes architectural/technology choices -3. **checkpoint:human-action** (1% of checkpoints) - Truly unavoidable manual steps with no API/CLI +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 + +**When NOT to use checkpoints:** +- Things Claude can verify programmatically (tests, builds) +- File operations (Claude can read/write) +- Anything with CLI/API available + diff --git a/get-shit-done/references/cli-automation.md b/get-shit-done/references/cli-automation.md deleted file mode 100644 index 9a2e54f85..000000000 --- a/get-shit-done/references/cli-automation.md +++ /dev/null @@ -1,527 +0,0 @@ - -**Core principle:** If it has a CLI or API, Claude does it. Never ask the human to perform manual steps that Claude can automate. - -This reference documents what Claude CAN and SHOULD automate during plan execution. - - - - - -**CLI:** `vercel` - -**What Claude automates:** -- Create and deploy projects: `vercel --yes` -- Set environment variables: `vercel env add KEY production` -- Link to git repo: `vercel link` -- Trigger deployments: `vercel --prod` -- Get deployment URLs: `vercel ls` -- Manage domains: `vercel domains add example.com` - -**Never ask human to:** -- Visit vercel.com/new to create project -- Click through dashboard to add env vars -- Manually link repository - -**Checkpoint pattern:** -```xml - - Deploy to Vercel - Run `vercel --yes` to deploy. Capture deployment URL. - vercel ls shows deployment, curl {url} returns 200 - - - - Deployed to {url} - Visit {url} - check homepage loads - Type "yes" if correct - -``` - - - -**CLI:** `railway` - -**What Claude automates:** -- Initialize project: `railway init` -- Link to repo: `railway link` -- Deploy: `railway up` -- Set variables: `railway variables set KEY=value` -- Get deployment URL: `railway domain` - - - -**CLI:** `fly` - -**What Claude automates:** -- Launch app: `fly launch --no-deploy` -- Deploy: `fly deploy` -- Set secrets: `fly secrets set KEY=value` -- Scale: `fly scale count 2` - - - - - - -**CLI:** `stripe` - -**What Claude automates:** -- Create webhook endpoints: `stripe listen --forward-to localhost:3000/api/webhooks` -- Trigger test events: `stripe trigger payment_intent.succeeded` -- Create products/prices: Stripe API via curl/fetch -- Manage customers: Stripe API via curl/fetch -- Check webhook logs: `stripe webhooks list` - -**Never ask human to:** -- Visit dashboard.stripe.com to create webhook -- Click through UI to create products -- Manually copy webhook signing secret - -**Checkpoint pattern:** -```xml - - Configure Stripe webhooks - Use Stripe API to create webhook endpoint at /api/webhooks. Save signing secret to .env. - stripe webhooks list shows endpoint, .env contains STRIPE_WEBHOOK_SECRET - - - - Stripe webhook configured - Check Stripe dashboard > Developers > Webhooks shows endpoint with correct URL - Type "yes" if correct - -``` - - - - - - -**CLI:** `supabase` - -**What Claude automates:** -- Initialize project: `supabase init` -- Link to remote: `supabase link --project-ref {ref}` -- Create migrations: `supabase migration new {name}` -- Push migrations: `supabase db push` -- Generate types: `supabase gen types typescript` -- Deploy functions: `supabase functions deploy {name}` - -**Never ask human to:** -- Visit supabase.com to create project manually -- Click through dashboard to run migrations -- Copy/paste connection strings - -**Note:** Project creation may require web dashboard initially (no CLI for initial project creation), but all subsequent work (migrations, functions, etc.) is CLI-automated. - - - -**CLI:** `upstash` - -**What Claude automates:** -- Create Redis database: `upstash redis create {name} --region {region}` -- Get connection details: `upstash redis get {id}` -- Create Kafka cluster: `upstash kafka create {name} --region {region}` - -**Never ask human to:** -- Visit console.upstash.com -- Click through UI to create database -- Copy/paste connection URLs manually - -**Checkpoint pattern:** -```xml - - Create Upstash Redis database - Run `upstash redis create myapp-cache --region us-east-1`. Save URL to .env. - .env contains UPSTASH_REDIS_URL, upstash redis list shows database - -``` - - - -**CLI:** `pscale` - -**What Claude automates:** -- Create database: `pscale database create {name} --region {region}` -- Create branch: `pscale branch create {db} {branch}` -- Deploy request: `pscale deploy-request create {db} {branch}` -- Connection string: `pscale connect {db} {branch}` - - - - - - -**CLI:** `gh` - -**What Claude automates:** -- Create repo: `gh repo create {name} --public/--private` -- Create issues: `gh issue create --title "{title}" --body "{body}"` -- Create PR: `gh pr create --title "{title}" --body "{body}"` -- Manage secrets: `gh secret set {KEY}` -- Trigger workflows: `gh workflow run {name}` -- Check status: `gh run list` - -**Never ask human to:** -- Visit github.com to create repo -- Click through UI to add secrets -- Manually create issues/PRs - - - - - - -**What Claude automates:** -- Install dependencies: `npm install`, `pnpm install`, `bun install` -- Run builds: `npm run build` -- Run tests: `npm test`, `npm run test:e2e` -- Type checking: `tsc --noEmit` - -**Never ask human to:** Run these commands manually - - - -**CLI:** `xcodebuild` - -**What Claude automates:** -- Build project: `xcodebuild -project App.xcodeproj -scheme App build` -- Run tests: `xcodebuild test -project App.xcodeproj -scheme App` -- Archive: `xcodebuild archive -project App.xcodeproj -scheme App` -- Check compilation: Parse xcodebuild output for errors - -**Never ask human to:** -- Open Xcode and click Product > Build -- Click Product > Test manually -- Check for errors by looking at Xcode UI - -**Checkpoint pattern:** -```xml - - Build macOS app - Run `xcodebuild -project App.xcodeproj -scheme App build`. Check output for errors. - Build succeeds with "BUILD SUCCEEDED" in output - - - - Built macOS app at DerivedData/Build/Products/Debug/App.app - Open App.app and check: login flow works, no visual glitches - Type "approved" or describe issues - -``` - - - - - - -**Tool:** Write tool - -**What Claude automates:** -- Create .env files: Use Write tool -- Append variables: Use Edit tool -- Read current values: Use Read tool - -**Never ask human to:** -- Manually create .env file -- Copy/paste values into .env -- Edit .env in text editor - -**Pattern:** -```xml - - Configure environment variables - Write .env file with: DATABASE_URL, STRIPE_KEY, JWT_SECRET (generated). - Read .env confirms all variables present - -``` - - - - - - -**API:** Resend API via HTTP - -**What Claude automates:** -- Create API keys via dashboard API (if available) or instructions for one-time setup -- Send emails: Resend API -- Configure domains: Resend API - - - -**API:** SendGrid API via HTTP - -**What Claude automates:** -- Create API keys via API -- Send emails: SendGrid API -- Configure webhooks: SendGrid API - -**Note:** Initial account setup may require email verification (checkpoint:human-action), but all subsequent work is API-automated. - - - - - -**Critical distinction:** When Claude tries to use a CLI/API and gets an authentication error, this is NOT a failure - it's a gate that requires human input to unblock automation. - -**Pattern: Claude encounters auth error → creates checkpoint → you authenticate → Claude continues** - - - -```xml - - Deploy to Vercel - .vercel/, vercel.json - Run `vercel --yes` to deploy - vercel ls shows deployment - - - - - - Authenticate Vercel CLI so I can continue deployment - - I tried to deploy but got authentication error. - Run: vercel login - This will open your browser - complete the authentication flow. - - vercel whoami returns your account email - Type "done" when authenticated - - - - - - Retry Vercel deployment - Run `vercel --yes` (now authenticated) - vercel ls shows deployment, curl returns 200 - -``` - - - - -```xml - - Create Stripe webhook endpoint - Use Stripe API to create webhook at /api/webhooks - - - - - - Provide Stripe API key so I can continue webhook configuration - - I need your Stripe API key to create webhooks. - 1. Visit dashboard.stripe.com/apikeys - 2. Copy your "Secret key" (starts with sk_test_ or sk_live_) - 3. Paste it here or run: export STRIPE_SECRET_KEY=sk_... - - Stripe API key works: curl test succeeds - Type "done" or paste the key - - - - - - Save Stripe key and create webhook - - 1. Write STRIPE_SECRET_KEY to .env - 2. Create webhook endpoint via Stripe API - 3. Save webhook secret to .env - - .env contains both keys, webhook endpoint exists - -``` - - - - -```xml - - Create GitHub repository - Run `gh repo create myapp --public` - - - - - - Authenticate GitHub CLI so I can create repository - - I need GitHub authentication to create the repo. - Run: gh auth login - Follow the prompts to authenticate (browser or token). - - gh auth status shows "Logged in" - Type "done" when authenticated - - - - Create repository (authenticated) - Run `gh repo create myapp --public` - gh repo view shows repository exists - -``` - - - - -```xml - - Create Upstash Redis database - Run `upstash redis create myapp-cache --region us-east-1` - - - - - - Configure Upstash CLI credentials so I can create database - - I need Upstash authentication to create Redis database. - 1. Visit console.upstash.com/account/api - 2. Copy your API key - 3. Run: upstash auth login - 4. Paste your API key when prompted - - upstash auth status shows authenticated - Type "done" when authenticated - - - - Create Redis database (authenticated) - - 1. Run `upstash redis create myapp-cache --region us-east-1` - 2. Capture connection URL - 3. Write to .env: UPSTASH_REDIS_URL={url} - - upstash redis list shows database, .env contains URL - -``` - - - - -**When Claude encounters authentication error during execution:** - -1. **Recognize it's not a failure** - Missing auth is expected, not a bug -2. **Stop current task** - Don't retry repeatedly -3. **Create checkpoint:human-action on the fly** - Dynamic checkpoint, not pre-planned -4. **Provide exact authentication steps** - CLI commands, where to get keys -5. **Verify authentication** - Test that auth works before continuing -6. **Retry the original task** - Resume automation where it left off -7. **Continue normally** - One auth gate doesn't break the flow - -**Key difference from pre-planned checkpoints:** -- Pre-planned: "I need you to do X" (wrong - Claude should automate) -- Auth gate: "I tried to automate X but need credentials to continue" (correct - unblocks automation) - -**This preserves agentic flow:** -- Claude tries automation first -- Only asks for help when blocked by credentials -- Continues automating after unblocked -- You never manually deploy/create resources - just provide keys - - - - - -**Truly rare cases where no CLI/API exists:** - -1. **Email verification links** - Account signup requires clicking verification email -2. **SMS verification codes** - 2FA requiring phone -3. **Manual account approvals** - Platform requires human review before API access -4. **Domain DNS records at registrar** - Some registrars have no API -5. **Credit card input** - Payment methods requiring 3D Secure web flow -6. **OAuth app approval** - Some platforms require web-based app approval flow - -**For these rare cases:** -```xml - - Complete email verification for SendGrid account - - I created the account and requested verification email. - Check your inbox for verification link and click it. - - SendGrid API key works: curl test succeeds - Type "done" when verified - -``` - -**Key difference:** Claude does EVERYTHING possible first (account creation, API requests), only asks human for the one thing with no automation path. - - - - -| Action | CLI/API? | Claude does it? | -|--------|----------|-----------------| -| Deploy to Vercel | ✅ `vercel` | YES | -| Create Stripe webhook | ✅ Stripe API | YES | -| Run xcodebuild | ✅ `xcodebuild` | YES | -| Write .env file | ✅ Write tool | YES | -| Create Upstash DB | ✅ `upstash` CLI | YES | -| Install npm packages | ✅ `npm` | YES | -| Create GitHub repo | ✅ `gh` | YES | -| Run tests | ✅ `npm test` | YES | -| Create Supabase project | ⚠️ Web dashboard | NO (then CLI for everything else) | -| Click email verification link | ❌ No API | NO | -| Enter credit card with 3DS | ❌ No API | NO | - -**Default answer: YES.** Unless explicitly in the "NO" category, Claude automates it. - - - - -``` -┌─────────────────────────────────────┐ -│ Task requires external resource? │ -└──────────────┬──────────────────────┘ - │ - ▼ -┌─────────────────────────────────────┐ -│ Does it have CLI/API/tool access? │ -└──────────────┬──────────────────────┘ - │ - ┌─────┴─────┐ - │ │ - ▼ ▼ - YES NO - │ │ - │ ▼ - │ ┌──────────────────────────────┐ - │ │ checkpoint:human-action │ - │ │ (email links, 2FA, etc.) │ - │ └──────────────────────────────┘ - │ - ▼ - ┌────────────────────────────────────────┐ - │ task type="auto" │ - │ Claude automates via CLI/API │ - └────────────┬───────────────────────────┘ - │ - ▼ - ┌────────────────────────────────────────┐ - │ checkpoint:human-verify │ - │ Human confirms visual/functional │ - └────────────────────────────────────────┘ -``` - - - - -**The rule:** If Claude CAN do it, Claude MUST do it. - -Checkpoints are for: -- **Verification** - Confirming Claude's automated work looks/behaves correctly -- **Decisions** - Choosing between valid approaches -- **True blockers** - Rare actions with literally no API/CLI (email links, 2FA) - -Checkpoints are NOT for: -- Deploying (use CLI) -- Creating resources (use CLI/API) -- Running builds (use Bash) -- Writing files (use Write tool) -- Anything with automation available - -**This keeps the agentic coding workflow intact - Claude does the work, you verify results.** - diff --git a/get-shit-done/references/plan-format.md b/get-shit-done/references/plan-format.md index 91d058344..89c18eb2b 100644 --- a/get-shit-done/references/plan-format.md +++ b/get-shit-done/references/plan-format.md @@ -1,397 +1,127 @@ -Claude-executable plans have a specific format that enables Claude to implement without interpretation. This reference defines what makes a plan executable vs. vague. +Claude-executable plans have a specific format. This reference defines what makes a plan executable vs. vague. -**Key insight:** PLAN.md IS the executable prompt. It contains everything Claude needs to execute the phase, including objective, context references, tasks, verification, success criteria, and output specification. +**Core principle:** A plan is Claude-executable when Claude can read PLAN.md and immediately start implementing without clarifying questions. If Claude has to guess or interpret - the task is too vague. - -A plan is Claude-executable when Claude can read the PLAN.md and immediately start implementing without asking clarifying questions. - -If Claude has to guess, interpret, or make assumptions - the task is too vague. - - - -Every PLAN.md follows this XML structure: - -```markdown ---- -phase: XX-name -type: execute -domain: [optional] ---- - - -[What and why] -Purpose: [...] -Output: [...] - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@relevant/source/files.ts - - - - - Task N: [Name] - [paths] - [what to do, what to avoid and WHY] - [command/check] - [criteria] - - - - [what Claude automated] - [numbered verification steps] - [how to continue - "approved" or describe issues] - - - - [what needs deciding] - [why this matters] - - - - - [how to indicate choice] - - - - -[Overall phase checks] - - - -[Measurable completion] - - - -[SUMMARY.md specification] - -``` - - - + Every task has four required fields: - -**What it is**: Exact file paths that will be created or modified. +**files** - Exact paths created/modified +- Good: `src/app/api/auth/login/route.ts` +- Bad: "the auth files" -**Good**: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma` -**Bad**: "the auth files", "relevant components" +**action** - Specific implementation with pitfalls to avoid +- Good: "POST endpoint accepting {email, password}. Query User by email, compare with bcrypt. Return JWT in httpOnly cookie (15-min expiry). Use jose (not jsonwebtoken - CommonJS issues with Edge)." +- Bad: "Add authentication" -Be specific. If you don't know the file path, figure it out first. - +**verify** - Executable proof of completion +- Good: `curl -X POST /api/auth/login` returns 200 with Set-Cookie header +- Bad: "It works" - -**What it is**: Specific implementation instructions, including what to avoid and WHY. +**done** - Measurable acceptance criteria +- Good: "Valid credentials → 200 + cookie. Invalid → 401." +- Bad: "Authentication complete" -**Good**: "Create POST endpoint that accepts {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Next.js Edge runtime)." - -**Bad**: "Add authentication", "Make login work" - -Include: technology choices, data structures, behavior details, pitfalls to avoid. - - - -**What it is**: How to prove the task is complete. - -**Good**: - -- `npm test` passes -- `curl -X POST /api/auth/login` returns 200 with Set-Cookie header -- Build completes without errors - -**Bad**: "It works", "Looks good", "User can log in" - -Must be executable - a command, a test, an observable behavior. - - - -**What it is**: Acceptance criteria - the measurable state of completion. - -**Good**: "Valid credentials return 200 + JWT cookie, invalid credentials return 401" - -**Bad**: "Authentication is complete" - -Should be testable without subjective judgment. - -Tasks have a `type` attribute that determines how they execute: - - -**Default task type** - Claude executes autonomously. - -**Structure:** +**type="auto"** (default) - Claude executes autonomously ```xml - Task 3: Create login endpoint with JWT + Task 1: Create login endpoint src/app/api/auth/login/route.ts - POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401. - curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header - Valid credentials → 200 + cookie. Invalid → 401. + POST accepting {email, password}. bcrypt compare, JWT via jose, httpOnly cookie. + curl returns 200 with Set-Cookie + Valid → 200 + cookie. Invalid → 401. ``` -Use for: Everything Claude can do independently (code, tests, builds, file operations). - - - -**RARELY USED** - Only for actions with NO CLI/API. Claude automates everything possible first. - -**Structure:** - -```xml - - [Unavoidable manual step - email link, 2FA code] - - [What Claude already automated] - [The ONE thing requiring human action] - - [What Claude can check afterward] - [How to continue] - -``` - -Use ONLY for: Email verification links, SMS 2FA codes, manual approvals with no API, 3D Secure payment flows. - -Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub), builds, tests, file creation, deployments. - -**Execution:** Claude automates everything with CLI/API, stops only for truly unavoidable manual steps. - - - -**Human must verify Claude's work** - Visual checks, UX testing. - -**Structure:** - +**type="checkpoint:human-verify"** - Human confirms Claude's work ```xml - Responsive dashboard layout - - 1. Run: npm run dev - 2. Visit: http://localhost:3000/dashboard - 3. Desktop (>1024px): Verify sidebar left, content right - 4. Tablet (768px): Verify sidebar collapses to hamburger - 5. Mobile (375px): Verify single column, bottom nav - 6. Check: No layout shift, no horizontal scroll - + Responsive dashboard at /dashboard + 1. npm run dev 2. Visit localhost:3000/dashboard 3. Test mobile/tablet/desktop Type "approved" or describe issues ``` -Use for: UI/UX verification, visual design checks, animation smoothness, accessibility testing. - -**Execution:** Claude builds the feature, stops, provides testing instructions, waits for approval/feedback. - - - -**Human must make implementation choice** - Direction-setting decisions. - -**Structure:** - +**type="checkpoint:decision"** - Human makes implementation choice ```xml - Select authentication provider - We need user authentication. Three approaches with different tradeoffs: + Select auth provider + Need user auth with different tradeoffs. - - - + + - Select: supabase, clerk, or nextauth + Select: supabase or clerk ``` -Use for: Technology selection, architecture decisions, design choices, feature prioritization. - -**Execution:** Claude presents options with balanced pros/cons, waits for decision, proceeds with chosen direction. - - -**When to use checkpoints:** - -- Visual/UX verification (after Claude builds) → `checkpoint:human-verify` -- Implementation direction choice → `checkpoint:decision` -- Truly unavoidable manual actions (email links, 2FA) → `checkpoint:human-action` (rare) - -**When NOT to use checkpoints:** - -- Anything with CLI/API (Claude automates it) → `type="auto"` -- Deployments (Vercel, Railway, Fly) → `type="auto"` with CLI -- Creating resources (Upstash, Stripe, GitHub) → `type="auto"` with CLI/API -- File operations, tests, builds → `type="auto"` +**type="checkpoint:human-action"** - Rare, only for NO API/CLI actions (email links, 2FA) **Golden rule:** If Claude CAN automate it, Claude MUST automate it. See `./checkpoints.md` for comprehensive checkpoint guidance. + - -Use @file references to load context for the prompt: - -```markdown - -@.planning/PROJECT.md # Project vision -@.planning/ROADMAP.md # Phase structure -@.planning/phases/02-auth/DISCOVERY.md # Discovery results -@src/lib/db.ts # Existing database setup -@src/types/user.ts # Existing type definitions - -``` - -Reference files that Claude needs to understand before implementing. - - - -Overall phase verification (beyond individual task verification): - -```markdown - -Before declaring phase complete: -- [ ] `npm run build` succeeds without errors -- [ ] `npm test` passes all tests -- [ ] No TypeScript errors -- [ ] Feature works end-to-end manually - -``` - - - - -Measurable criteria for phase completion: - -```markdown - - -- All tasks completed -- All verification checks pass -- No errors or warnings introduced -- JWT auth flow works end-to-end -- Protected routes redirect unauthenticated users - -``` - - - - -Specify the SUMMARY.md structure: - -```markdown - -After completion, create `.planning/phases/XX-name/SUMMARY.md`: - -# Phase X: Name Summary - -**[Substantive one-liner]** - -## Accomplishments - -## Files Created/Modified - -## Decisions Made - -## Issues Encountered - -## Next Phase Readiness - - -``` - - - - +**Too vague:** ```xml - Task 1: Add authentication + Add authentication ??? Implement auth ??? Users can authenticate ``` - Claude: "How? What type? What library? Where?" - - - +**Just right:** ```xml - Task 1: Create login endpoint with JWT + Create login endpoint with JWT src/app/api/auth/login/route.ts - POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401. Use jose instead of jsonwebtoken (CommonJS issues with Edge). - curl -X POST localhost:3000/api/auth/login -H "Content-Type: application/json" -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie header containing JWT - Valid credentials → 200 + cookie. Invalid → 401. Missing fields → 400. + POST accepting {email, password}. Query User by email, bcrypt compare. On match: JWT via jose, httpOnly cookie (15-min). Return 200. Mismatch: 401. Use jose not jsonwebtoken (Edge compatibility). + curl -X POST localhost:3000/api/auth/login -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie + Valid → 200 + cookie. Invalid → 401. Missing fields → 400. ``` -Claude can implement this immediately. - - - -Writing the actual code in the plan. Trust Claude to implement from clear instructions. - - -- "Set up the infrastructure" -- "Handle edge cases" -- "Make it production-ready" -- "Add proper error handling" +**Vague actions:** +- "Set up infrastructure" - what infrastructure? +- "Handle edge cases" - which ones? +- "Add proper error handling" - what's proper? -These require Claude to decide WHAT to do. Specify it. - +**Unverifiable completion:** +- "It works correctly" - how to test? +- "Code is clean" - subjective +- "Tests pass" - which tests? do they exist? - +**Missing context:** +- "Use standard approach" - which standard? +- "Like the other endpoints" - Claude doesn't know your patterns -- "It works correctly" -- "User experience is good" -- "Code is clean" -- "Tests pass" (which tests? do they exist?) - -These require subjective judgment. Make it objective. - - - - -- "Use the standard approach" -- "Follow best practices" -- "Like the other endpoints" - -Claude doesn't know your standards. Be explicit. - - + + Good task size: 15-60 minutes of Claude work. -**Too small**: "Add import statement for bcrypt" (combine with related task) -**Just right**: "Create login endpoint with JWT validation" (focused, specific) -**Too big**: "Implement full authentication system" (split into multiple plans) +- Too small: "Add import for bcrypt" → combine with related task +- Just right: "Create login endpoint with JWT" → focused, specific +- Too big: "Implement full auth system" → split into multiple plans -If a task takes multiple sessions, break it down. -If a task is trivial, combine with related tasks. +If phase has >3 tasks or spans multiple subsystems, split into multiple plans: `{phase}-{plan}-PLAN.md` -**Note on scope:** If a phase has >3 tasks or spans multiple subsystems, split into multiple plans using the naming convention `{phase}-{plan}-PLAN.md`. See `./scope-estimation.md` for guidance. - +