golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(04-01): merge cli-automation into checkpoints, compress plan-format

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2025-12-29 12:07:39 -06:00
parent d6913f3fd9
commit 5d16432887
4 changed files with 206 additions and 1311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
commands/gsd/plan-phase.md
View File

@@ -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
</execution_context>
<context>

607
get-shit-done/references/checkpoints.md
View File

@@ -1,286 +1,110 @@
<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.
</overview>
<checkpoint_types>
<type name="human-verify">
## 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
<task type="checkpoint:human-verify" gate="blocking">
<what-built>[What Claude automated and deployed/built]</what-built>
<how-to-verify>
[Exact steps to test - URLs, commands, expected behavior]
</how-to-verify>
<resume-signal>[How to continue - "approved", "yes", or describe issues]</resume-signal>
<what-built>[What Claude automated]</what-built>
<how-to-verify>[Numbered steps - URLs, commands, expected behavior]</how-to-verify>
<resume-signal>[How to continue - "approved" or describe issues]</resume-signal>
</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**
**Example:**
```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>
<action>Run `vercel --yes` to deploy. Capture URL.</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>
<what-built>Deployed to https://myapp.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**
```xml
<task type="auto">
<name>Build responsive dashboard layout</name>
<files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
<action>Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile.</action>
<verify>npm run build succeeds, no TypeScript errors</verify>
<done>Dashboard component builds without errors</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Responsive dashboard layout at /dashboard</what-built>
<how-to-verify>
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Desktop (>1024px): Verify sidebar left, content right, header top
4. Tablet (768px): Verify sidebar collapses to hamburger
5. Mobile (375px): Verify single column, bottom nav
6. Check: No layout shift, no horizontal scroll
</how-to-verify>
<resume-signal>Type "approved" or describe layout issues</resume-signal>
</task>
```
**Example: Xcode Build**
```xml
<task type="auto">
<name>Build macOS app with Xcode</name>
<files>App.xcodeproj, Sources/</files>
<action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output.</action>
<verify>Build output contains "BUILD SUCCEEDED", no errors</verify>
<done>App builds successfully</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
<how-to-verify>
Open App.app and test:
- App launches without crashes
- Menu bar icon appears
- Preferences window opens correctly
- No visual glitches or layout issues
Visit URL and confirm:
1. Homepage loads without errors
2. All images/assets load
3. No console errors
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
</type>
<type name="decision">
## 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
<task type="checkpoint:decision" gate="blocking">
<decision>[What's being decided]</decision>
<context>[Why this decision matters]</context>
<context>[Why this matters]</context>
<options>
<option id="option-a">
<name>[Option name]</name>
<pros>[Benefits]</pros>
<cons>[Tradeoffs]</cons>
</option>
<option id="option-b">
<name>[Option name]</name>
<pros>[Benefits]</pros>
<cons>[Tradeoffs]</cons>
</option>
<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]</resume-signal>
</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**
**Example:**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>Select authentication provider</decision>
<context>
Need user authentication for the app. Three solid options with different tradeoffs.
</context>
<context>Need user auth. Three options with different tradeoffs.</context>
<options>
<option id="supabase">
<name>Supabase Auth</name>
<pros>Built-in with Supabase DB we're using, generous free tier, row-level security integration</pros>
<cons>Less customizable UI, tied to Supabase ecosystem</cons>
</option>
<option id="clerk">
<name>Clerk</name>
<pros>Beautiful pre-built UI, best developer experience, excellent docs</pros>
<cons>Paid after 10k MAU, vendor lock-in</cons>
</option>
<option id="nextauth">
<name>NextAuth.js</name>
<pros>Free, self-hosted, maximum control, widely adopted</pros>
<cons>More setup work, you manage security updates, UI is DIY</cons>
</option>
<option id="supabase"><name>Supabase Auth</name><pros>Built-in with DB, free tier, RLS integration</pros><cons>Less customizable, ecosystem lock-in</cons></option>
<option id="clerk"><name>Clerk</name><pros>Beautiful UI, best DX</pros><cons>Paid after 10k MAU</cons></option>
<option id="nextauth"><name>NextAuth.js</name><pros>Free, self-hosted, max control</pros><cons>More setup, DIY security</cons></option>
</options>
<resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
</task>
```
</type>
<type name="human-action">
## 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
<task type="checkpoint:human-action" gate="blocking">
<action>[What human must do - Claude already did everything automatable]</action>
<instructions>
[What Claude already automated]
[The ONE thing requiring human action]
</instructions>
<verification>[What Claude can check afterward]</verification>
<action>[Unavoidable manual step]</action>
<instructions>[What Claude automated] [ONE thing requiring human action]</instructions>
<verification>[What Claude checks 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**
**Example (email verification):**
```xml
<task type="auto">
<name>Create SendGrid account via API</name>
<action>Use SendGrid API to create subuser account with provided email. Request verification email.</action>
<verify>API returns 201, account created</verify>
<done>Account created, verification email sent</done>
</task>
<task type="checkpoint:human-action" gate="blocking">
<action>Complete email verification for SendGrid account</action>
<instructions>
I created the account and requested verification email.
Check your inbox for SendGrid verification link and click it.
Check your inbox for verification link and click it.
</instructions>
<verification>SendGrid API key works: curl test succeeds</verification>
<resume-signal>Type "done" when email verified</resume-signal>
<resume-signal>Type "done" when verified</resume-signal>
</task>
```
**Example: Credit Card 3D Secure**
```xml
<task type="auto">
<name>Create Stripe payment intent</name>
<action>Use Stripe API to create payment intent for $99. Generate checkout URL.</action>
<verify>Stripe API returns payment intent ID and URL</verify>
<done>Payment intent created</done>
</task>
<task type="checkpoint:human-action" gate="blocking">
<action>Complete 3D Secure authentication</action>
<instructions>
I created the payment intent: https://checkout.stripe.com/pay/cs_test_abc123
Visit that URL and complete the 3D Secure verification flow with your test card.
</instructions>
<verification>Stripe webhook receives payment_intent.succeeded event</verification>
<resume-signal>Type "done" when payment completes</resume-signal>
</task>
```
**Example: Authentication Gate (Dynamic Checkpoint)**
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json</files>
<action>Run `vercel --yes` to deploy</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
<!-- If vercel returns "Error: Not authenticated", Claude creates checkpoint on the fly -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate Vercel CLI so I can continue deployment</action>
<instructions>
I tried to deploy but got authentication error.
Run: vercel login
This will open your browser - complete the authentication flow.
</instructions>
<verification>vercel whoami returns your account email</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<!-- After authentication, Claude retries the deployment -->
<task type="auto">
<name>Retry Vercel deployment</name>
<action>Run `vercel --yes` (now authenticated)</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
```
**Key distinction:** Authentication gates are created dynamically when Claude encounters auth errors during automation. They're NOT pre-planned - Claude tries to automate first, only asks for credentials when blocked.
</type>
</checkpoint_types>
<execution_protocol>
@@ -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
════════════════════════════════════════
```
</execution_protocol>
<writing_guidelines>
<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.
**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
<!-- Claude tries to deploy -->
<task type="auto">
<name>Deploy to Vercel</name>
<action>Run `vercel --yes` to deploy</action>
</task>
<!-- If vercel returns "Error: Not authenticated" -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate Vercel CLI so I can continue</action>
<instructions>
I tried to deploy but got authentication error.
Run: vercel login (opens browser)
</instructions>
<verification>vercel whoami returns your account</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<!-- After auth, Claude retries automatically -->
<task type="auto">
<name>Retry deployment</name>
<action>Run `vercel --yes` (now authenticated)</action>
</task>
```
**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)
</authentication_gates>
<automation_reference>
**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 |
</automation_reference>
<guidelines>
**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)
</writing_guidelines>
- 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)
<usage_guidelines>
**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
</usage_guidelines>
<placement_guidelines>
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) ❌
</placement_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 (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Create Upstash Redis database</name>
<files>.env</files>
<action>
1. Run `upstash redis create myapp-cache --region us-east-1`
2. Capture connection URL from output
3. Write to .env: UPSTASH_REDIS_URL={url}
4. Verify connection with test command
</action>
<verify>
- upstash redis list shows database
- .env contains UPSTASH_REDIS_URL
- Test connection succeeds
</verify>
<done>Redis database created and configured</done>
</task>
<!-- NO CHECKPOINT NEEDED - Claude automated everything and verified programmatically -->
```
### Example 3: Stripe Webhooks (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Configure Stripe webhooks</name>
<files>.env, src/app/api/webhooks/route.ts</files>
<action>
1. Use Stripe API to create webhook endpoint pointing to /api/webhooks
2. Subscribe to events: payment_intent.succeeded, customer.subscription.updated
3. Save webhook signing secret to .env
4. Implement webhook handler in route.ts
</action>
<verify>
- Stripe API returns webhook endpoint ID
- .env contains STRIPE_WEBHOOK_SECRET
- curl webhook endpoint returns 200
</verify>
<done>Stripe webhooks configured and handler implemented</done>
</task>
<!-- Human verifies in Stripe dashboard -->
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Stripe webhook configured via API</what-built>
<how-to-verify>
Visit Stripe Dashboard > Developers > Webhooks
Confirm: Endpoint shows https://myapp.com/api/webhooks with correct events
</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
</examples>
</guidelines>
<anti_patterns>
### ❌ BAD: Asking human to automate
**BAD: Asking human to automate**
```xml
<task type="checkpoint:human-action" gate="blocking">
<task type="checkpoint:human-action">
<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>
<instructions>Visit vercel.com/new, import repo, click Deploy</instructions>
</task>
```
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
<task type="auto">
<name>Deploy to Vercel</name>
<action>Run `vercel --yes`. Capture URL.</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Deployed to {url}</what-built>
<how-to-verify>Visit {url}, check homepage loads</how-to-verify>
<resume-signal>Type "approved"</resume-signal>
</task>
```
### ❌ BAD: Too many checkpoints
**BAD: Too many checkpoints**
```xml
<task type="auto">Create schema</task>
<task type="checkpoint:human-verify">Check schema</task>
<task type="auto">Create API route</task>
<task type="auto">Create API</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.
**Why bad:** Verification fatigue. Combine into one checkpoint at end.
### ✅ GOOD: Single verification checkpoint
**GOOD: Claude automates, human verifies once**
```xml
<task type="auto">Create schema</task>
<task type="auto">Create API route</task>
<task type="auto">Create UI form</task>
<task type="auto">Create API</task>
<task type="auto">Create UI</task>
<task type="checkpoint:human-verify">
<what-built>Complete auth flow (schema + API + UI)</what-built>
<what-built>Complete auth flow</what-built>
<how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
<resume-signal>Type "approved"</resume-signal>
</task>
```
### ❌ BAD: Asking for automatable file operations
```xml
<task type="checkpoint:human-action">
<action>Create .env file</action>
<instructions>
1. Create .env in project root
2. Add: DATABASE_URL=...
3. Add: STRIPE_KEY=...
</instructions>
</task>
```
**Why bad:** Claude has Write tool. This should be `type="auto"`.
</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.
**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
</summary>

527
get-shit-done/references/cli-automation.md
View File

@@ -1,527 +0,0 @@
<overview>
**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.
</overview>
<deployment_platforms>
<platform name="vercel">
**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
<task type="auto">
<name>Deploy to Vercel</name>
<action>Run `vercel --yes` to deploy. Capture deployment URL.</action>
<verify>vercel ls shows deployment, curl {url} returns 200</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Deployed to {url}</what-built>
<how-to-verify>Visit {url} - check homepage loads</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
</platform>
<platform name="railway">
**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`
</platform>
<platform name="fly">
**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`
</platform>
</deployment_platforms>
<payment_billing>
<service name="stripe">
**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
<task type="auto">
<name>Configure Stripe webhooks</name>
<action>Use Stripe API to create webhook endpoint at /api/webhooks. Save signing secret to .env.</action>
<verify>stripe webhooks list shows endpoint, .env contains STRIPE_WEBHOOK_SECRET</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Stripe webhook configured</what-built>
<how-to-verify>Check Stripe dashboard > Developers > Webhooks shows endpoint with correct URL</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
</service>
</payment_billing>
<databases_backend>
<service name="supabase">
**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.
</service>
<service name="upstash">
**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
<task type="auto">
<name>Create Upstash Redis database</name>
<action>Run `upstash redis create myapp-cache --region us-east-1`. Save URL to .env.</action>
<verify>.env contains UPSTASH_REDIS_URL, upstash redis list shows database</verify>
</task>
```
</service>
<service name="planetscale">
**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}`
</service>
</databases_backend>
<version_control>
<service name="github">
**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
</service>
</version_control>
<build_tools>
<tools name="node">
**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
</tools>
<tools name="xcode">
**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
<task type="auto">
<name>Build macOS app</name>
<action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check output for errors.</action>
<verify>Build succeeds with "BUILD SUCCEEDED" in output</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
<how-to-verify>Open App.app and check: login flow works, no visual glitches</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
</tools>
</build_tools>
<environment_config>
<config name="env-files">
**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
<task type="auto">
<name>Configure environment variables</name>
<action>Write .env file with: DATABASE_URL, STRIPE_KEY, JWT_SECRET (generated).</action>
<verify>Read .env confirms all variables present</verify>
</task>
```
</config>
</environment_config>
<email_communication>
<service name="resend">
**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
</service>
<service name="sendgrid">
**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.
</service>
</email_communication>
<authentication_gates>
**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**
<example name="vercel-auth">
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json</files>
<action>Run `vercel --yes` to deploy</action>
<verify>vercel ls shows deployment</verify>
</task>
<!-- If vercel returns "Error: Not authenticated" -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate Vercel CLI so I can continue deployment</action>
<instructions>
I tried to deploy but got authentication error.
Run: vercel login
This will open your browser - complete the authentication flow.
</instructions>
<verification>vercel whoami returns your account email</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<!-- After authentication, Claude retries automatically -->
<task type="auto">
<name>Retry Vercel deployment</name>
<action>Run `vercel --yes` (now authenticated)</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
```
</example>
<example name="stripe-auth">
```xml
<task type="auto">
<name>Create Stripe webhook endpoint</name>
<action>Use Stripe API to create webhook at /api/webhooks</action>
</task>
<!-- If API returns 401 Unauthorized -->
<task type="checkpoint:human-action" gate="blocking">
<action>Provide Stripe API key so I can continue webhook configuration</action>
<instructions>
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_...
</instructions>
<verification>Stripe API key works: curl test succeeds</verification>
<resume-signal>Type "done" or paste the key</resume-signal>
</task>
<!-- After key provided, Claude writes to .env and continues -->
<task type="auto">
<name>Save Stripe key and create webhook</name>
<action>
1. Write STRIPE_SECRET_KEY to .env
2. Create webhook endpoint via Stripe API
3. Save webhook secret to .env
</action>
<verify>.env contains both keys, webhook endpoint exists</verify>
</task>
```
</example>
<example name="github-auth">
```xml
<task type="auto">
<name>Create GitHub repository</name>
<action>Run `gh repo create myapp --public`</action>
</task>
<!-- If gh returns "Not logged in" -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate GitHub CLI so I can create repository</action>
<instructions>
I need GitHub authentication to create the repo.
Run: gh auth login
Follow the prompts to authenticate (browser or token).
</instructions>
<verification>gh auth status shows "Logged in"</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<task type="auto">
<name>Create repository (authenticated)</name>
<action>Run `gh repo create myapp --public`</action>
<verify>gh repo view shows repository exists</verify>
</task>
```
</example>
<example name="upstash-auth">
```xml
<task type="auto">
<name>Create Upstash Redis database</name>
<action>Run `upstash redis create myapp-cache --region us-east-1`</action>
</task>
<!-- If upstash returns auth error -->
<task type="checkpoint:human-action" gate="blocking">
<action>Configure Upstash CLI credentials so I can create database</action>
<instructions>
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
</instructions>
<verification>upstash auth status shows authenticated</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<task type="auto">
<name>Create Redis database (authenticated)</name>
<action>
1. Run `upstash redis create myapp-cache --region us-east-1`
2. Capture connection URL
3. Write to .env: UPSTASH_REDIS_URL={url}
</action>
<verify>upstash redis list shows database, .env contains URL</verify>
</task>
```
</example>
<gate_protocol>
**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
</gate_protocol>
</authentication_gates>
<required_cases>
**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
<task type="checkpoint:human-action" gate="blocking">
<action>Complete email verification for SendGrid account</action>
<instructions>
I created the account and requested verification email.
Check your inbox for verification link and click it.
</instructions>
<verification>SendGrid API key works: curl test succeeds</verification>
<resume-signal>Type "done" when verified</resume-signal>
</task>
```
**Key difference:** Claude does EVERYTHING possible first (account creation, API requests), only asks human for the one thing with no automation path.
</required_cases>
<quick_reference>
| 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.
</quick_reference>
<decision_tree>
```
┌─────────────────────────────────────┐
│ 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 │
└────────────────────────────────────────┘
```
</decision_tree>
<summary>
**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.**
</summary>

382
get-shit-done/references/plan-format.md
View File

@@ -1,397 +1,127 @@
<overview>
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.
</overview>
<core_principle>
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.
</core_principle>
<prompt_structure>
Every PLAN.md follows this XML structure:
```markdown
---
phase: XX-name
type: execute
domain: [optional]
---
<objective>
[What and why]
Purpose: [...]
Output: [...]
</objective>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@relevant/source/files.ts
</context>
<tasks>
<task type="auto">
<name>Task N: [Name]</name>
<files>[paths]</files>
<action>[what to do, what to avoid and WHY]</action>
<verify>[command/check]</verify>
<done>[criteria]</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>[what Claude automated]</what-built>
<how-to-verify>[numbered verification steps]</how-to-verify>
<resume-signal>[how to continue - "approved" or describe issues]</resume-signal>
</task>
<task type="checkpoint:decision" gate="blocking">
<decision>[what needs deciding]</decision>
<context>[why this matters]</context>
<options>
<option id="option-a"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
<option id="option-b"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
</options>
<resume-signal>[how to indicate choice]</resume-signal>
</task>
</tasks>
<verification>
[Overall phase checks]
</verification>
<success_criteria>
[Measurable completion]
</success_criteria>
<output>
[SUMMARY.md specification]
</output>
```
</prompt_structure>
<task_anatomy>
Every task has four required fields:
<field name="files">
**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.
</field>
**verify** - Executable proof of completion
- Good: `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
- Bad: "It works"
<field name="action">
**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.
</field>
<field name="verify">
**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.
</field>
<field name="done">
**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.
</field>
</task_anatomy>
<task_types>
Tasks have a `type` attribute that determines how they execute:
<type name="auto">
**Default task type** - Claude executes autonomously.
**Structure:**
**type="auto"** (default) - Claude executes autonomously
```xml
<task type="auto">
<name>Task 3: Create login endpoint with JWT</name>
<name>Task 1: Create login endpoint</name>
<files>src/app/api/auth/login/route.ts</files>
<action>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.</action>
<verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>
<done>Valid credentials → 200 + cookie. Invalid → 401.</done>
<action>POST accepting {email, password}. bcrypt compare, JWT via jose, httpOnly cookie.</action>
<verify>curl returns 200 with Set-Cookie</verify>
<done>Valid → 200 + cookie. Invalid → 401.</done>
</task>
```
Use for: Everything Claude can do independently (code, tests, builds, file operations).
</type>
<type name="checkpoint:human-action">
**RARELY USED** - Only for actions with NO CLI/API. Claude automates everything possible first.
**Structure:**
```xml
<task type="checkpoint:human-action" gate="blocking">
<action>[Unavoidable manual step - email link, 2FA code]</action>
<instructions>
[What Claude already automated]
[The ONE thing requiring human action]
</instructions>
<verification>[What Claude can check afterward]</verification>
<resume-signal>[How to continue]</resume-signal>
</task>
```
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.
</type>
<type name="checkpoint:human-verify">
**Human must verify Claude's work** - Visual checks, UX testing.
**Structure:**
**type="checkpoint:human-verify"** - Human confirms Claude's work
```xml
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Responsive dashboard layout</what-built>
<how-to-verify>
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
</how-to-verify>
<what-built>Responsive dashboard at /dashboard</what-built>
<how-to-verify>1. npm run dev 2. Visit localhost:3000/dashboard 3. Test mobile/tablet/desktop</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
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.
</type>
<type name="checkpoint:decision">
**Human must make implementation choice** - Direction-setting decisions.
**Structure:**
**type="checkpoint:decision"** - Human makes implementation choice
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>Select authentication provider</decision>
<context>We need user authentication. Three approaches with different tradeoffs:</context>
<decision>Select auth provider</decision>
<context>Need user auth with different tradeoffs.</context>
<options>
<option id="supabase">
<name>Supabase Auth</name>
<pros>Built-in with Supabase, generous free tier</pros>
<cons>Less customizable UI, tied to ecosystem</cons>
</option>
<option id="clerk">
<name>Clerk</name>
<pros>Beautiful pre-built UI, best DX</pros>
<cons>Paid after 10k MAU</cons>
</option>
<option id="nextauth">
<name>NextAuth.js</name>
<pros>Free, self-hosted, maximum control</pros>
<cons>More setup, you manage security</cons>
</option>
<option id="supabase"><name>Supabase</name><pros>Built-in, free</pros><cons>Ecosystem lock-in</cons></option>
<option id="clerk"><name>Clerk</name><pros>Best DX</pros><cons>Paid after 10k</cons></option>
</options>
<resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
<resume-signal>Select: supabase or clerk</resume-signal>
</task>
```
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.
</type>
**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.
</task_types>
<context_references>
Use @file references to load context for the prompt:
```markdown
<context>
@.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
</context>
```
Reference files that Claude needs to understand before implementing.
</context_references>
<verification_section>
Overall phase verification (beyond individual task verification):
```markdown
<verification>
Before declaring phase complete:
- [ ] `npm run build` succeeds without errors
- [ ] `npm test` passes all tests
- [ ] No TypeScript errors
- [ ] Feature works end-to-end manually
</verification>
```
</verification_section>
<success_criteria_section>
Measurable criteria for phase completion:
```markdown
<success_criteria>
- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- JWT auth flow works end-to-end
- Protected routes redirect unauthenticated users
</success_criteria>
```
</success_criteria_section>
<output_section>
Specify the SUMMARY.md structure:
```markdown
<output>
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
</output>
```
</output_section>
<specificity_levels>
<too_vague>
**Too vague:**
```xml
<task type="auto">
<name>Task 1: Add authentication</name>
<name>Add authentication</name>
<files>???</files>
<action>Implement auth</action>
<verify>???</verify>
<done>Users can authenticate</done>
</task>
```
Claude: "How? What type? What library? Where?"
</too_vague>
<just_right>
**Just right:**
```xml
<task type="auto">
<name>Task 1: Create login endpoint with JWT</name>
<name>Create login endpoint with JWT</name>
<files>src/app/api/auth/login/route.ts</files>
<action>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).</action>
<verify>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</verify>
<done>Valid credentials → 200 + cookie. Invalid → 401. Missing fields → 400.</done>
<action>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).</action>
<verify>curl -X POST localhost:3000/api/auth/login -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie</verify>
<done>Valid → 200 + cookie. Invalid → 401. Missing fields → 400.</done>
</task>
```
Claude can implement this immediately.
</just_right>
<too_detailed>
Writing the actual code in the plan. Trust Claude to implement from clear instructions.
</too_detailed>
</specificity_levels>
<anti_patterns>
<vague_actions>
- "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.
</vague_actions>
**Unverifiable completion:**
- "It works correctly" - how to test?
- "Code is clean" - subjective
- "Tests pass" - which tests? do they exist?
<unverifiable_completion>
**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.
</unverifiable_completion>
<missing_context>
- "Use the standard approach"
- "Follow best practices"
- "Like the other endpoints"
Claude doesn't know your standards. Be explicit.
</missing_context>
</anti_patterns>
<sizing_tasks>
<sizing>
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.
</sizing_tasks>
</sizing>