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

Reduce manual verification in checkpoint system (#220)

Browse Source 
* docs: enforce automation-first checkpoint verification

Checkpoints should never ask users to run CLI commands that Claude Code
can execute. This update reinforces the automation-first principle:

Key changes:
- Add golden rules: Claude runs CLI, users only visit URLs
- Add dev server automation patterns (start before checkpoint)
- Add environment variable CLI patterns (Convex, Vercel, etc.)
- Add anti-patterns: asking user to run npm, add dashboard env vars
- Update all examples to show Claude starting servers
- Add comprehensive "Never Ask Users To" and "Users Only Do" lists
- Update gsd-executor with pre-checkpoint automation requirements

The core principle: if Claude CAN automate it, Claude MUST automate it.
Users only do what requires human judgment (visual verification, UX).

* refactor: DRY checkpoint automation with server lifecycle and error handling

Changes:
- checkpoints.md is now single source of truth for automation-first patterns
- Added server lifecycle protocol (start, port conflicts, cleanup)
- Added CLI installation handling (auto-install matrix)
- Added pre-checkpoint failure handling (fix before checkpoint)
- Removed ~93 lines of duplication from verification-patterns.md
- Replaced inline examples in phase-prompt.md with references
- Slimmed gsd-executor.md checkpoint section to reference checkpoints.md

Net effect: -23 lines while adding 3 new capabilities (server lifecycle,
CLI install, error handling). Single place to update automation patterns.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
TÂCHES
2026-01-21 10:52:30 -06:00
committed by GitHub
parent d58ae52b54
commit 67b064d534
4 changed files with 368 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
agents/gsd-executor.md
View File

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

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

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

17
get-shit-done/references/verification-patterns.md
View File

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

45
get-shit-done/templates/phase-prompt.md
View File

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