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
@@ -1235,6 +1235,76 @@ fi
|
||||
Pass timing data to SUMMARY.md creation.
|
||||
</step>
|
||||
|
||||
<step name="generate_user_setup">
|
||||
**Generate USER-SETUP.md if plan has user_setup in frontmatter.**
|
||||
|
||||
Check PLAN.md frontmatter for `user_setup` field:
|
||||
|
||||
```bash
|
||||
grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50
|
||||
```
|
||||
|
||||
**If user_setup exists and is not empty:**
|
||||
|
||||
Create `.planning/phases/XX-name/{phase}-USER-SETUP.md` using template from `~/.claude/get-shit-done/templates/user-setup.md`.
|
||||
|
||||
**Content generation:**
|
||||
|
||||
1. Parse each service in `user_setup` array
|
||||
2. For each service, generate sections:
|
||||
- Environment Variables table (from `env_vars`)
|
||||
- Account Setup checklist (from `account_setup`, if present)
|
||||
- Dashboard Configuration steps (from `dashboard_config`, if present)
|
||||
- Local Development notes (from `local_dev`, if present)
|
||||
3. Add verification section with commands to confirm setup works
|
||||
4. Set status to "Incomplete"
|
||||
|
||||
**Example output:**
|
||||
|
||||
```markdown
|
||||
# Phase 10: User Setup Required
|
||||
|
||||
**Generated:** 2025-01-14
|
||||
**Phase:** 10-monetization
|
||||
**Status:** Incomplete
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Status | Variable | Source | Add to |
|
||||
|--------|----------|--------|--------|
|
||||
| [ ] | `STRIPE_SECRET_KEY` | Stripe Dashboard → Developers → API keys → Secret key | `.env.local` |
|
||||
| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Developers → Webhooks → Signing secret | `.env.local` |
|
||||
|
||||
## Dashboard Configuration
|
||||
|
||||
- [ ] **Create webhook endpoint**
|
||||
- Location: Stripe Dashboard → Developers → Webhooks → Add endpoint
|
||||
- Details: URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed
|
||||
|
||||
## Local Development
|
||||
|
||||
For local testing:
|
||||
\`\`\`bash
|
||||
stripe listen --forward-to localhost:3000/api/webhooks/stripe
|
||||
\`\`\`
|
||||
|
||||
## Verification
|
||||
|
||||
[Verification commands based on service]
|
||||
|
||||
---
|
||||
**Once all items complete:** Mark status as "Complete"
|
||||
```
|
||||
|
||||
**If user_setup is empty or missing:**
|
||||
|
||||
Skip this step - no USER-SETUP.md needed.
|
||||
|
||||
**Track for offer_next:**
|
||||
|
||||
Set `USER_SETUP_CREATED=true` if file was generated, for use in completion messaging.
|
||||
</step>
|
||||
|
||||
<step name="create_summary">
|
||||
Create `{phase}-{plan}-SUMMARY.md` as specified in the prompt's `<output>` section.
|
||||
Use ~/.claude/get-shit-done/templates/summary.md for structure.
|
||||
@@ -1541,6 +1611,30 @@ Skip this step.
|
||||
|
||||
Do NOT skip this verification. Do NOT assume phase or milestone completion without checking.
|
||||
|
||||
**Step 0: Check for USER-SETUP.md**
|
||||
|
||||
If `USER_SETUP_CREATED=true` (from generate_user_setup step), always include this warning block at the TOP of completion output:
|
||||
|
||||
```
|
||||
⚠️ USER SETUP REQUIRED
|
||||
|
||||
This phase introduced external services requiring manual configuration:
|
||||
|
||||
📋 .planning/phases/{phase-dir}/{phase}-USER-SETUP.md
|
||||
|
||||
Quick view:
|
||||
- [ ] {ENV_VAR_1}
|
||||
- [ ] {ENV_VAR_2}
|
||||
- [ ] {Dashboard config task}
|
||||
|
||||
Complete this setup for the integration to function.
|
||||
Run `cat .planning/phases/{phase-dir}/{phase}-USER-SETUP.md` for full details.
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
This warning appears BEFORE "Plan complete" messaging. User sees setup requirements prominently.
|
||||
|
||||
**Step 1: Count plans and summaries in current phase**
|
||||
|
||||
List files in the phase directory:
|
||||
@@ -1718,8 +1812,10 @@ Milestone is 100% done.
|
||||
|
||||
- All tasks from PLAN.md completed
|
||||
- All verifications pass
|
||||
- USER-SETUP.md generated if user_setup in frontmatter
|
||||
- SUMMARY.md created with substantive content
|
||||
- STATE.md updated (position, decisions, issues, session)
|
||||
- ROADMAP.md updated
|
||||
- If codebase map exists: map updated with execution changes (or skipped if no significant changes)
|
||||
- If USER-SETUP.md created: prominently surfaced in completion output
|
||||
</success_criteria>
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user