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

fix(checkpoints): restore rich documentation and fix continuation pattern

Browse Source 
- execute-plan.md: Replace broken Task(resume=...) with fresh continuation agent
- execute-phase.md: Expand checkpoint handling with full continuation flow
- checkpoints.md: Restore ~500 lines of detailed examples and anti-patterns

Checkpoint presentation formats now documented for all three types.
Templates referenced: checkpoint-return.md, continuation-prompt.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-14 16:26:08 -06:00
parent ac31b89526
commit e98bebfeeb
3 changed files with 712 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
commands/gsd/execute-phase.md
View File

@@ -160,9 +160,23 @@ All three run in parallel. Task tool blocks until all complete.
<checkpoint_handling> <checkpoint_handling>
Plans with `autonomous: false` in frontmatter have checkpoints: Plans with `autonomous: false` in frontmatter have checkpoints:
- Run in their assigned wave (can be parallel with other plans) - Run in their assigned wave (can be parallel with other plans)
- Pause at checkpoint, return to orchestrator - Pause at checkpoint, return structured state to orchestrator
- Orchestrator presents checkpoint to user - Orchestrator presents checkpoint to user (see execute-plan.md for presentation formats)
- User responds, orchestrator resumes agent - User responds, orchestrator spawns fresh continuation agent
**Checkpoint flow:**
1. Subagent returns `## CHECKPOINT REACHED` with Completed Tasks table
2. Orchestrator parses return and presents rich formatted checkpoint
3. User responds (approved/done/option selection)
4. Orchestrator fills continuation-prompt.md template with state
5. Spawns fresh agent: `Task(prompt=filled_continuation_template, subagent_type="general-purpose")`
**Why fresh agent, not resume:**
Task tool resume fails after multiple tool calls. Fresh agent with state handoff is the correct pattern.
**Templates:**
- `@~/.claude/get-shit-done/templates/checkpoint-return.md` - Subagent return format
- `@~/.claude/get-shit-done/templates/continuation-prompt.md` - Fresh agent spawn template
</checkpoint_handling> </checkpoint_handling>
<deviation_rules> <deviation_rules>

106
commands/gsd/execute-plan.md
View File

@@ -201,13 +201,88 @@ When subagent returns with checkpoint:
**Plan:** {phase}-{plan} **Plan:** {phase}-{plan}
**Progress:** {completed}/{total} tasks complete **Progress:** {completed}/{total} tasks complete
[Checkpoint content] ### Completed Tasks
| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | [task name] | [hash] | [files] |
**Awaiting:** [Resume signal] ### Current Task
**Task {N}:** [name]
**Status:** [blocked | awaiting verification | awaiting decision]
**Blocked by:** [specific blocker]
### Checkpoint Details
[Type-specific content for user]
### Awaiting
[What user needs to provide]
``` ```
**2. Present to user:** **2. Present checkpoint to user:**
Display the checkpoint content exactly as returned by subagent.
Display rich formatted checkpoint based on type:
**For human-verify:**
```
════════════════════════════════════════
CHECKPOINT: Verification Required
════════════════════════════════════════
Task {X} of {Y}: {task name}
I built: {what-built from checkpoint details}
How to verify:
{numbered verification steps}
Type "approved" to continue, or describe issues.
════════════════════════════════════════
```
**For human-action (auth gate):**
```
════════════════════════════════════════
CHECKPOINT: Authentication Required
════════════════════════════════════════
Task {X} of {Y}: {task name}
I tried: {automation attempted}
Error: {error encountered}
What you need to do:
{numbered instructions}
I'll verify after: {verification}
Type "done" when complete.
════════════════════════════════════════
```
**For decision:**
```
════════════════════════════════════════
CHECKPOINT: Decision Required
════════════════════════════════════════
Task {X} of {Y}: {task name}
Decision: {what's being decided}
Context: {why this matters}
Options:
1. {option-a}: {name}
Pros: {benefits}
Cons: {tradeoffs}
2. {option-b}: {name}
Pros: {benefits}
Cons: {tradeoffs}
Select: {option-a | option-b | ...}
════════════════════════════════════════
```
**3. Collect response:** **3. Collect response:**
Wait for user input: Wait for user input:
@@ -215,15 +290,34 @@ Wait for user input:
- decision: option selection - decision: option selection
- human-action: "done" when complete - human-action: "done" when complete
**4. Resume subagent:** **4. Spawn fresh continuation agent:**
Fill continuation-prompt template with:
- completed_tasks_table: From checkpoint return
- resume_task_number: Current task number
- resume_task_name: Current task name
- resume_status: Derived from checkpoint type and user response
- user_response: What user provided
- resume_instructions: Type-specific guidance (see template)
``` ```
Task(resume="{agent_id}", prompt="User response: {user_input}") Task(prompt=filled_continuation_template, subagent_type="general-purpose")
``` ```
**Why fresh agent, not resume:**
Task tool resume fails after multiple tool calls (presenting to user, waiting for response). Fresh agent with state handoff via continuation-prompt.md is the correct pattern.
**5. Repeat:** **5. Repeat:**
Continue handling returns until "## PLAN COMPLETE" or user stops. Continue handling returns until "## PLAN COMPLETE" or user stops.
</checkpoint_handling> </checkpoint_handling>
<checkpoint_templates>
Templates for checkpoint handling:
- `@~/.claude/get-shit-done/templates/checkpoint-return.md` - Subagent return format
- `@~/.claude/get-shit-done/templates/continuation-prompt.md` - Fresh agent spawn template
</checkpoint_templates>
<success_criteria> <success_criteria>
- [ ] Plan executed (SUMMARY.md created) - [ ] Plan executed (SUMMARY.md created)
- [ ] All checkpoints handled - [ ] All checkpoints handled

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

@@ -1,110 +1,315 @@
<overview> <overview>
Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed. Plans execute autonomously. Checkpoints formalize the interaction points where human verification or decisions are needed.
**Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work. **Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
</overview> </overview>
<checkpoint_types> <checkpoint_types>
## checkpoint:human-verify (90% of checkpoints) <type name="human-verify">
## checkpoint:human-verify (Most Common - 90%)
**When:** Claude completed automated work, human confirms it works correctly. **When:** Claude completed automated work, human confirms it works correctly.
**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing. **Use for:**
- Visual UI checks (layout, styling, responsiveness)
- Interactive flows (click through wizard, test user flows)
- Functional verification (feature works as expected)
- Audio/video playback quality
- Animation smoothness
- Accessibility testing
**Structure:** **Structure:**
```xml ```xml
<task type="checkpoint:human-verify" gate="blocking"> <task type="checkpoint:human-verify" gate="blocking">
<what-built>[What Claude automated]</what-built> <what-built>[What Claude automated and deployed/built]</what-built>
<how-to-verify>[Numbered steps - URLs, commands, expected behavior]</how-to-verify> <how-to-verify>
<resume-signal>[How to continue - "approved" or describe issues]</resume-signal> [Exact steps to test - URLs, commands, expected behavior]
</how-to-verify>
<resume-signal>[How to continue - "approved", "yes", or describe issues]</resume-signal>
</task> </task>
``` ```
**Example:** **Key elements:**
- `<what-built>`: What Claude automated (deployed, built, configured)
- `<how-to-verify>`: Exact steps to confirm it works (numbered, specific)
- `<resume-signal>`: Clear indication of how to continue
**Example: Vercel Deployment**
```xml ```xml
<task type="auto"> <task type="auto">
<name>Deploy to Vercel</name> <name>Deploy to Vercel</name>
<action>Run `vercel --yes` to deploy. Capture URL.</action> <files>.vercel/, vercel.json</files>
<action>Run `vercel --yes` to create project and deploy. Capture deployment URL from output.</action>
<verify>vercel ls shows deployment, curl {url} returns 200</verify> <verify>vercel ls shows deployment, curl {url} returns 200</verify>
<done>App deployed, URL captured</done>
</task> </task>
<task type="checkpoint:human-verify" gate="blocking"> <task type="checkpoint:human-verify" gate="blocking">
<what-built>Deployed to https://myapp.vercel.app</what-built> <what-built>Deployed to Vercel at https://myapp-abc123.vercel.app</what-built>
<how-to-verify> <how-to-verify>
Visit URL and confirm: Visit https://myapp-abc123.vercel.app and confirm:
1. Homepage loads without errors - Homepage loads without errors
2. All images/assets load - Login form is visible
3. No console errors - No console errors in browser DevTools
</how-to-verify>
<resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>
```
**Example: UI Component**
```xml
<task type="auto">
<name>Build responsive dashboard layout</name>
<files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
<action>Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile.</action>
<verify>npm run build succeeds, no TypeScript errors</verify>
<done>Dashboard component builds without errors</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Responsive dashboard layout at /dashboard</what-built>
<how-to-verify>
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Desktop (>1024px): Verify sidebar left, content right, header top
4. Tablet (768px): Verify sidebar collapses to hamburger
5. Mobile (375px): Verify single column, bottom nav
6. Check: No layout shift, no horizontal scroll
</how-to-verify>
<resume-signal>Type "approved" or describe layout issues</resume-signal>
</task>
```
**Example: Xcode Build**
```xml
<task type="auto">
<name>Build macOS app with Xcode</name>
<files>App.xcodeproj, Sources/</files>
<action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output.</action>
<verify>Build output contains "BUILD SUCCEEDED", no errors</verify>
<done>App builds successfully</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
<how-to-verify>
Open App.app and test:
- App launches without crashes
- Menu bar icon appears
- Preferences window opens correctly
- No visual glitches or layout issues
</how-to-verify> </how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal> <resume-signal>Type "approved" or describe issues</resume-signal>
</task> </task>
``` ```
</type>
## checkpoint:decision (9% of checkpoints) <type name="decision">
## checkpoint:decision (9%)
**When:** Human must make choice that affects implementation direction. **When:** Human must make choice that affects implementation direction.
**Use for:** Technology selection, architecture decisions, design choices, feature prioritization. **Use for:**
- Technology selection (which auth provider, which database)
- Architecture decisions (monorepo vs separate repos)
- Design choices (color scheme, layout approach)
- Feature prioritization (which variant to build)
- Data model decisions (schema structure)
**Structure:** **Structure:**
```xml ```xml
<task type="checkpoint:decision" gate="blocking"> <task type="checkpoint:decision" gate="blocking">
<decision>[What's being decided]</decision> <decision>[What's being decided]</decision>
<context>[Why this matters]</context> <context>[Why this decision matters]</context>
<options> <options>
<option id="option-a"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option> <option id="option-a">
<option id="option-b"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option> <name>[Option name]</name>
<pros>[Benefits]</pros>
<cons>[Tradeoffs]</cons>
</option>
<option id="option-b">
<name>[Option name]</name>
<pros>[Benefits]</pros>
<cons>[Tradeoffs]</cons>
</option>
</options> </options>
<resume-signal>[How to indicate choice]</resume-signal> <resume-signal>[How to indicate choice]</resume-signal>
</task> </task>
``` ```
**Example:** **Key elements:**
- `<decision>`: What's being decided
- `<context>`: Why this matters
- `<options>`: Each option with balanced pros/cons (not prescriptive)
- `<resume-signal>`: How to indicate choice
**Example: Auth Provider Selection**
```xml ```xml
<task type="checkpoint:decision" gate="blocking"> <task type="checkpoint:decision" gate="blocking">
<decision>Select authentication provider</decision> <decision>Select authentication provider</decision>
<context>Need user auth. Three options with different tradeoffs.</context> <context>
Need user authentication for the app. Three solid options with different tradeoffs.
</context>
<options> <options>
<option id="supabase"><name>Supabase Auth</name><pros>Built-in with DB, free tier, RLS integration</pros><cons>Less customizable, ecosystem lock-in</cons></option> <option id="supabase">
<option id="clerk"><name>Clerk</name><pros>Beautiful UI, best DX</pros><cons>Paid after 10k MAU</cons></option> <name>Supabase Auth</name>
<option id="nextauth"><name>NextAuth.js</name><pros>Free, self-hosted, max control</pros><cons>More setup, DIY security</cons></option> <pros>Built-in with Supabase DB we're using, generous free tier, row-level security integration</pros>
<cons>Less customizable UI, tied to Supabase ecosystem</cons>
</option>
<option id="clerk">
<name>Clerk</name>
<pros>Beautiful pre-built UI, best developer experience, excellent docs</pros>
<cons>Paid after 10k MAU, vendor lock-in</cons>
</option>
<option id="nextauth">
<name>NextAuth.js</name>
<pros>Free, self-hosted, maximum control, widely adopted</pros>
<cons>More setup work, you manage security updates, UI is DIY</cons>
</option>
</options> </options>
<resume-signal>Select: supabase, clerk, or nextauth</resume-signal> <resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
</task> </task>
``` ```
## checkpoint:human-action (1% - rare) **Example: Database Selection**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>Select database for user data</decision>
<context>
App needs persistent storage for users, sessions, and user-generated content.
Expected scale: 10k users, 1M records first year.
</context>
<options>
<option id="supabase">
<name>Supabase (Postgres)</name>
<pros>Full SQL, generous free tier, built-in auth, real-time subscriptions</pros>
<cons>Vendor lock-in for real-time features, less flexible than raw Postgres</cons>
</option>
<option id="planetscale">
<name>PlanetScale (MySQL)</name>
<pros>Serverless scaling, branching workflow, excellent DX</pros>
<cons>MySQL not Postgres, no foreign keys in free tier</cons>
</option>
<option id="convex">
<name>Convex</name>
<pros>Real-time by default, TypeScript-native, automatic caching</pros>
<cons>Newer platform, different mental model, less SQL flexibility</cons>
</option>
</options>
<resume-signal>Select: supabase, planetscale, or convex</resume-signal>
</task>
```
</type>
**When:** Action has NO CLI/API and requires human-only interaction. <type name="human-action">
## checkpoint:human-action (1% - Rare)
**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals. **When:** Action has NO CLI/API and requires human-only interaction, OR Claude hit an authentication gate during automation.
**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use Bash), file operations (use Write/Edit). **Use ONLY for:**
- **Authentication gates** - Claude tried to use CLI/API but needs credentials to continue (this is NOT a failure)
- Email verification links (account creation requires clicking email)
- SMS 2FA codes (phone verification)
- Manual account approvals (platform requires human review before API access)
- Credit card 3D Secure flows (web-based payment authorization)
- OAuth app approvals (some platforms require web-based approval)
**Do NOT use for pre-planned manual work:**
- Manually deploying to Vercel (use `vercel` CLI - auth gate if needed)
- Manually creating Stripe webhooks (use Stripe API - auth gate if needed)
- Manually creating databases (use provider CLI - auth gate if needed)
- Running builds/tests manually (use Bash tool)
- Creating files manually (use Write tool)
**Structure:** **Structure:**
```xml ```xml
<task type="checkpoint:human-action" gate="blocking"> <task type="checkpoint:human-action" gate="blocking">
<action>[Unavoidable manual step]</action> <action>[What human must do - Claude already did everything automatable]</action>
<instructions>[What Claude automated] [ONE thing requiring human action]</instructions> <instructions>
<verification>[What Claude checks afterward]</verification> [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> <resume-signal>[How to continue]</resume-signal>
</task> </task>
``` ```
**Example (email verification):** **Key principle:** Claude automates EVERYTHING possible first, only asks human for the truly unavoidable manual step.
**Example: Email Verification**
```xml ```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"> <task type="checkpoint:human-action" gate="blocking">
<action>Complete email verification for SendGrid account</action> <action>Complete email verification for SendGrid account</action>
<instructions> <instructions>
I created the account and requested verification email. I created the account and requested verification email.
Check your inbox for verification link and click it. Check your inbox for SendGrid verification link and click it.
</instructions> </instructions>
<verification>SendGrid API key works: curl test succeeds</verification> <verification>SendGrid API key works: curl test succeeds</verification>
<resume-signal>Type "done" when verified</resume-signal> <resume-signal>Type "done" when email verified</resume-signal>
</task> </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> </checkpoint_types>
<execution_protocol> <execution_protocol>
@@ -121,16 +326,86 @@ CHECKPOINT: [Type]
Task [X] of [Y]: [Name] Task [X] of [Y]: [Name]
[Checkpoint-specific content] [Display task-specific content based on type]
[Resume signal instruction] [Resume signal instruction]
════════════════════════════════════════ ════════════════════════════════════════
``` ```
3. **Wait for user response** - do not hallucinate completion 3. **Wait for user response** - do not hallucinate completion
4. **Verify if possible** - check files, run tests 4. **Verify if possible** - check files, run tests, whatever is specified
5. **Resume execution** - continue only after confirmation 5. **Resume execution** - continue to next task only after confirmation
**For checkpoint:human-verify:**
```
════════════════════════════════════════
CHECKPOINT: Verification Required
════════════════════════════════════════
Task 5 of 8: Responsive dashboard layout
I built: Responsive dashboard at /dashboard
How to verify:
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Test: Resize browser window to mobile/tablet/desktop
4. Confirm: No layout shift, proper responsive behavior
Type "approved" to continue, or describe issues.
════════════════════════════════════════
```
**For checkpoint:decision:**
```
════════════════════════════════════════
CHECKPOINT: Decision Required
════════════════════════════════════════
Task 2 of 6: Select authentication provider
Decision: Which auth provider should we use?
Context: Need user authentication. Three options with different tradeoffs.
Options:
1. supabase - Built-in with our DB, free tier
Pros: Row-level security integration, generous free tier
Cons: Less customizable UI, ecosystem lock-in
2. clerk - Best DX, paid after 10k users
Pros: Beautiful pre-built UI, excellent documentation
Cons: Vendor lock-in, pricing at scale
3. nextauth - Self-hosted, maximum control
Pros: Free, no vendor lock-in, widely adopted
Cons: More setup work, DIY security updates
Select: supabase, clerk, or nextauth
════════════════════════════════════════
```
**For checkpoint:human-action:**
```
════════════════════════════════════════
CHECKPOINT: Authentication Required
════════════════════════════════════════
Task 3 of 8: Deploy to Vercel
I tried: vercel --yes
Error: Not authenticated. Please run 'vercel login'
What you need to do:
1. Run: vercel login
2. Complete browser authentication when it opens
3. Return here when done
I'll verify after: vercel whoami returns your account
Type "done" when authenticated.
════════════════════════════════════════
```
</execution_protocol> </execution_protocol>
<authentication_gates> <authentication_gates>
@@ -148,30 +423,42 @@ Task [X] of [Y]: [Name]
6. Retry the original task 6. Retry the original task
7. Continue normally 7. Continue normally
**Example (Vercel auth gate):** **Example execution flow (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"> Claude: Running `vercel --yes` to deploy...
<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 --> Error: Not authenticated. Please run 'vercel login'
<task type="auto">
<name>Retry deployment</name> ════════════════════════════════════════
<action>Run `vercel --yes` (now authenticated)</action> CHECKPOINT: Authentication Required
</task> ════════════════════════════════════════
Task 3 of 8: Deploy to Vercel
I tried: vercel --yes
Error: Not authenticated
What you need to do:
1. Run: vercel login
2. Complete browser authentication
I'll verify after: vercel whoami returns your account
Type "done" when authenticated.
════════════════════════════════════════
User: done
Claude: Verifying authentication...
Running: vercel whoami
✓ Authenticated as: user@example.com
Retrying deployment...
Running: vercel --yes
✓ Deployed to: https://myapp-abc123.vercel.app
Task 3 complete. Continuing to task 4...
``` ```
**Key distinction:** **Key distinction:**
@@ -196,6 +483,7 @@ Task [X] of [Y]: [Name]
| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` | | GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |
| Node | `npm`/`pnpm` | `install`, `run build`, `test` | N/A | | Node | `npm`/`pnpm` | `install`, `run build`, `test` | N/A |
| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A | | Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
| Convex | `npx convex` | `dev`, `deploy`, `import` | `npx convex login` |
**Env files:** Use Write/Edit tools. Never ask human to create .env manually. **Env files:** Use Write/Edit tools. Never ask human to create .env manually.
@@ -210,61 +498,277 @@ Task [X] of [Y]: [Name]
| Run tests | Yes (`npm test`) | YES | | Run tests | Yes (`npm test`) | YES |
| Click email verification link | No | NO | | Click email verification link | No | NO |
| Enter credit card with 3DS | No | NO | | Enter credit card with 3DS | No | NO |
| Complete OAuth in browser | No | NO |
</automation_reference> </automation_reference>
<guidelines> <writing_guidelines>
**DO:** **DO:**
- Automate everything with CLI/API before checkpoint - Automate everything with CLI/API before checkpoint
- Be specific: "Visit https://myapp.vercel.app" not "check deployment" - Be specific: "Visit https://myapp.vercel.app" not "check deployment"
- Number verification steps - Number verification steps: easier to follow
- State expected outcomes - State expected outcomes: "You should see X"
- Make verification executable - Provide context: why this checkpoint exists
- Make verification executable: clear, testable steps
**DON'T:** **DON'T:**
- Ask human to do work Claude can automate - Ask human to do work Claude can automate (deploy, create resources, run builds)
- Assume knowledge: "Configure the usual settings" - Assume knowledge: "Configure the usual settings" ❌
- Mix multiple verifications in one checkpoint - Skip steps: "Set up database" ❌ (too vague)
- Use checkpoints too frequently (verification fatigue) - Mix multiple verifications in one checkpoint (split them)
- Make verification impossible (Claude can't check visual appearance without user confirmation)
**Placement:** **Placement:**
- After automation completes (not before) - **After automation completes** - not before Claude does the work
- After UI buildout - **After UI buildout** - before declaring phase complete
- Before dependent work (decisions) - **Before dependent work** - decisions before implementation
- At integration points - **At integration points** - after configuring external services
</guidelines> **Bad placement:**
- Before Claude automates (asking human to do automatable work) ❌
- Too frequent (every other task is a checkpoint) ❌
- Too late (checkpoint is last task, but earlier tasks needed its result) ❌
</writing_guidelines>
<examples>
### Example 1: Deployment Flow (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json, package.json</files>
<action>
1. Run `vercel --yes` to create project and deploy
2. Capture deployment URL from output
3. Set environment variables with `vercel env add`
4. Trigger production deployment with `vercel --prod`
</action>
<verify>
- vercel ls shows deployment
- curl {url} returns 200
- Environment variables set correctly
</verify>
<done>App deployed to production, URL captured</done>
</task>
<!-- Human verifies visual/functional correctness -->
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Deployed to https://myapp.vercel.app</what-built>
<how-to-verify>
Visit https://myapp.vercel.app and confirm:
- Homepage loads correctly
- All images/assets load
- Navigation works
- No console errors
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
### Example 2: Database Setup (No Checkpoint Needed)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Create Upstash Redis database</name>
<files>.env</files>
<action>
1. Run `upstash redis create myapp-cache --region us-east-1`
2. Capture connection URL from output
3. Write to .env: UPSTASH_REDIS_URL={url}
4. Verify connection with test command
</action>
<verify>
- upstash redis list shows database
- .env contains UPSTASH_REDIS_URL
- Test connection succeeds
</verify>
<done>Redis database created and configured</done>
</task>
<!-- NO CHECKPOINT NEEDED - Claude automated everything and verified programmatically -->
```
### Example 3: Stripe Webhooks (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Configure Stripe webhooks</name>
<files>.env, src/app/api/webhooks/route.ts</files>
<action>
1. Use Stripe API to create webhook endpoint pointing to /api/webhooks
2. Subscribe to events: payment_intent.succeeded, customer.subscription.updated
3. Save webhook signing secret to .env
4. Implement webhook handler in route.ts
</action>
<verify>
- Stripe API returns webhook endpoint ID
- .env contains STRIPE_WEBHOOK_SECRET
- curl webhook endpoint returns 200
</verify>
<done>Stripe webhooks configured and handler implemented</done>
</task>
<!-- Human verifies in Stripe dashboard -->
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Stripe webhook configured via API</what-built>
<how-to-verify>
Visit Stripe Dashboard > Developers > Webhooks
Confirm: Endpoint shows https://myapp.com/api/webhooks with correct events
</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
### Example 4: Full Auth Flow Verification (Correct)
```xml
<task type="auto">
<name>Create user schema</name>
<files>src/db/schema.ts</files>
<action>Define User, Session, Account tables with Drizzle ORM</action>
<verify>npm run db:generate succeeds</verify>
</task>
<task type="auto">
<name>Create auth API routes</name>
<files>src/app/api/auth/[...nextauth]/route.ts</files>
<action>Set up NextAuth with GitHub provider, JWT strategy</action>
<verify>TypeScript compiles, no errors</verify>
</task>
<task type="auto">
<name>Create login UI</name>
<files>src/app/login/page.tsx, src/components/LoginButton.tsx</files>
<action>Create login page with GitHub OAuth button</action>
<verify>npm run build succeeds</verify>
</task>
<!-- ONE checkpoint at end verifies the complete flow -->
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Complete authentication flow (schema + API + UI)</what-built>
<how-to-verify>
1. Run: npm run dev
2. Visit: http://localhost:3000/login
3. Click "Sign in with GitHub"
4. Complete GitHub OAuth flow
5. Verify: Redirected to /dashboard, user name displayed
6. Refresh page: Session persists
7. Click logout: Session cleared
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
</examples>
<anti_patterns> <anti_patterns>
**BAD: Asking human to automate** ### ❌ BAD: Asking human to automate
```xml ```xml
<task type="checkpoint:human-action"> <task type="checkpoint:human-action" gate="blocking">
<action>Deploy to Vercel</action> <action>Deploy to Vercel</action>
<instructions>Visit vercel.com/new, import repo, click Deploy</instructions> <instructions>
1. Visit vercel.com/new
2. Import Git repository
3. Click Deploy
4. Copy deployment URL
</instructions>
<verification>Deployment exists</verification>
<resume-signal>Paste URL</resume-signal>
</task> </task>
``` ```
Why bad: Vercel has CLI. Use `vercel --yes`.
**BAD: Too many checkpoints** **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
```xml ```xml
<task type="auto">Create schema</task> <task type="auto">Create schema</task>
<task type="checkpoint:human-verify">Check schema</task> <task type="checkpoint:human-verify">Check schema</task>
<task type="auto">Create API</task> <task type="auto">Create API route</task>
<task type="checkpoint:human-verify">Check API</task> <task type="checkpoint:human-verify">Check API</task>
<task type="auto">Create UI form</task>
<task type="checkpoint:human-verify">Check form</task>
``` ```
Why bad: Verification fatigue. Combine into one checkpoint at end.
**GOOD: Claude automates, human verifies once** **Why bad:** Verification fatigue. Combine into one checkpoint at end.
### ✅ GOOD: Single verification checkpoint
```xml ```xml
<task type="auto">Create schema</task> <task type="auto">Create schema</task>
<task type="auto">Create API</task> <task type="auto">Create API route</task>
<task type="auto">Create UI</task> <task type="auto">Create UI form</task>
<task type="checkpoint:human-verify"> <task type="checkpoint:human-verify">
<what-built>Complete auth flow</what-built> <what-built>Complete auth flow (schema + API + UI)</what-built>
<how-to-verify>Test full flow: register, login, access protected page</how-to-verify> <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
<resume-signal>Type "approved"</resume-signal>
</task>
```
### ❌ BAD: Asking for automatable file operations
```xml
<task type="checkpoint:human-action">
<action>Create .env file</action>
<instructions>
1. Create .env in project root
2. Add: DATABASE_URL=...
3. Add: STRIPE_KEY=...
</instructions>
</task>
```
**Why bad:** Claude has Write tool. This should be `type="auto"`.
### ❌ BAD: Vague verification steps
```xml
<task type="checkpoint:human-verify">
<what-built>Dashboard</what-built>
<how-to-verify>Check it works</how-to-verify>
<resume-signal>Continue</resume-signal>
</task>
```
**Why bad:** No specifics. User doesn't know what to test or what "works" means.
### ✅ GOOD: Specific verification steps
```xml
<task type="checkpoint:human-verify">
<what-built>Responsive dashboard at /dashboard</what-built>
<how-to-verify>
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Desktop (>1024px): Sidebar visible, content area fills remaining space
4. Tablet (768px): Sidebar collapses to icons
5. Mobile (375px): Sidebar hidden, hamburger menu in header
6. Check: No horizontal scroll at any size
</how-to-verify>
<resume-signal>Type "approved" or describe layout issues</resume-signal>
</task> </task>
``` ```
@@ -272,16 +776,18 @@ Why bad: Verification fatigue. Combine into one checkpoint at end.
<summary> <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. **The golden rule:** If Claude CAN automate it, Claude MUST automate it.
**Checkpoint priority:** **Checkpoint priority:**
1. **checkpoint:human-verify** (90%) - Claude automated, human confirms visual/functional correctness 1. **checkpoint:human-verify** (90% of checkpoints) - Claude automated everything, human confirms visual/functional correctness
2. **checkpoint:decision** (9%) - Human makes architectural/technology choices 2. **checkpoint:decision** (9% of checkpoints) - Human makes architectural/technology choices
3. **checkpoint:human-action** (1%) - Truly unavoidable manual steps with no API/CLI 3. **checkpoint:human-action** (1% of checkpoints) - Truly unavoidable manual steps with no API/CLI
**When NOT to use checkpoints:** **When NOT to use checkpoints:**
- Things Claude can verify programmatically (tests, builds) - Things Claude can verify programmatically (tests pass, build succeeds)
- File operations (Claude can read/write) - File operations (Claude can read files to verify)
- Anything with CLI/API available - Code correctness (use tests and static analysis)
- Anything automatable via CLI/API
</summary> </summary>