feat(gsd): add USER-SETUP.md for external service configuration

Problem: Phases introducing external services (Stripe, SendGrid, etc.) complete
successfully but user doesn't know about required env vars and dashboard config
until runtime failures occur.

Solution: Explicit declaration at planning time, enforced at execution time.

Changes:
- New template: user-setup.md - defines USER-SETUP.md structure
- phase-prompt.md: add user_setup frontmatter field
- plan-phase.md: add user setup detection guidance in break_into_tasks step
- execute-plan.md: add generate_user_setup step, surface in offer_next
- summary.md: add "User Setup Required" section

Flow:
1. Planning: Claude identifies external services, declares in user_setup frontmatter
2. Execution: After tasks complete, generates {phase}-USER-SETUP.md
3. Completion: Warning block prominently shows required setup before next steps

Automation-first rule: USER-SETUP.md contains ONLY what Claude cannot automate
(account creation, secret retrieval, dashboard config). Everything else Claude does.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-14 13:38:20 -06:00
parent 9b8750ab53
commit 4da80d64a6
5 changed files with 513 additions and 0 deletions

View File

@@ -288,6 +288,22 @@ See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
**Critical:** If external resource has CLI/API (Vercel, Stripe, etc.), use type="auto" to automate. Only checkpoint for verification AFTER automation.
See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure.
**User setup detection:** For tasks involving external services, identify human-required configuration:
External service indicators:
- New SDK: `stripe`, `@sendgrid/mail`, `twilio`, `openai`, `@supabase/supabase-js`
- Webhook handlers: Files in `**/webhooks/**` or `**/webhook*`
- OAuth integration: Social login, third-party auth
- API keys: Code referencing `process.env.SERVICE_*` patterns
For each external service, determine:
1. **Env vars needed** - What secrets must be retrieved from dashboards?
2. **Account setup** - Does user need to create an account?
3. **Dashboard config** - What must be configured in external UI?
4. **Local dev** - Any CLI tools for local testing?
Record in `user_setup` frontmatter (see write_phase_prompt step).
</step>
<step name="build_dependency_graph">
@@ -557,9 +573,39 @@ depends_on: [] # Plan IDs this plan requires.
files_modified: [] # Files this plan touches.
autonomous: true # false if plan has checkpoints requiring user interaction
domain: [optional]
user_setup: [] # Human-required setup (omit if empty)
---
```
**User setup frontmatter (when external services involved):**
```yaml
user_setup:
- service: stripe
why: "Payment processing"
env_vars:
- name: STRIPE_SECRET_KEY
source: "Stripe Dashboard → Developers → API keys → Secret key"
- name: STRIPE_WEBHOOK_SECRET
source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
account_setup:
- url: "https://dashboard.stripe.com/register"
skip_if: "Already have Stripe account"
dashboard_config:
- task: "Create webhook endpoint"
location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed"
local_dev:
- "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
```
**Automation-first rule:** Only include setup Claude literally cannot do:
- Account creation (requires human signup)
- Secret retrieval (requires dashboard access)
- Dashboard configuration (requires human in browser)
Do NOT include: npm install, code changes, file creation, CLI commands Claude can run.
**Wave is pre-computed:** Wave numbers are assigned during planning (see `assign_waves` step). `/gsd:execute-phase` reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
**Context section - parallel-aware:**
@@ -691,6 +737,7 @@ Phase planning complete when:
- [ ] Tasks grouped into plans by wave, not by sequence
- [ ] PLAN file(s) exist with XML structure
- [ ] Each plan: depends_on, files_modified, autonomous in frontmatter
- [ ] Each plan: user_setup declared if external services involved
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
- [ ] Each plan: 2-3 tasks (~50% context)
- [ ] Each task: Type, Files (if auto), Action, Verify, Done