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>
2026-01-14 13:38:20 -06:00
parent 9b8750ab53
commit 4da80d64a6
5 changed files with 513 additions and 0 deletions
--- a/get-shit-done/templates/phase-prompt.md
+++ b/get-shit-done/templates/phase-prompt.md
@@ -18,6 +18,7 @@ depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"]).
 files_modified: []          # Files this plan modifies.
 autonomous: true            # false if plan has checkpoints requiring user interaction
 domain: [optional - if domain skill loaded]
+user_setup: []              # Human-required setup Claude cannot automate (see below)
 ---

 <objective>
@@ -131,6 +132,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `files_modified` | Yes | Files this plan touches. |
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `domain` | No | Domain skill if loaded (e.g., `next-js`) |
+| `user_setup` | No | Array of human-required setup items (external services) |

 **Wave is pre-computed:** Wave numbers are assigned during `/gsd:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.

@@ -461,3 +463,37 @@ files_modified: [...]
 - Only reference prior SUMMARYs when genuinely needed
 - Group checkpoints with related auto tasks in same plan
 - 2-3 tasks per plan, ~50% context max
+
+---
+
+## User Setup (External Services)
+
+When a plan introduces external services requiring human configuration, declare in frontmatter:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "Payment processing requires API keys"
+    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"
+    dashboard_config:
+      - task: "Create webhook endpoint"
+        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
+        details: "URL: https://[your-domain]/api/webhooks/stripe"
+    local_dev:
+      - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+```
+
+**The automation-first rule:** `user_setup` contains ONLY what Claude literally cannot do:
+- Account creation (requires human signup)
+- Secret retrieval (requires dashboard access)
+- Dashboard configuration (requires human in browser)
+
+**NOT included:** Package installs, code changes, file creation, CLI commands Claude can run.
+
+**Result:** Execute-plan generates `{phase}-USER-SETUP.md` with checklist for the user.
+
+See `~/.claude/get-shit-done/templates/user-setup.md` for full schema and examples
--- a/get-shit-done/templates/summary.md
+++ b/get-shit-done/templates/summary.md
@@ -107,6 +107,17 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_

 [Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]

+## User Setup Required
+
+[If USER-SETUP.md was generated:]
+**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
+- Environment variables to add
+- Dashboard configuration steps
+- Verification commands
+
+[If no USER-SETUP.md:]
+None - no external service configuration required.
+
 ## Next Phase Readiness
 [What's ready for next phase]
 [Any blockers or concerns]
--- a/get-shit-done/templates/user-setup.md
+++ b/get-shit-done/templates/user-setup.md
@@ -0,0 +1,323 @@
+# User Setup Template
+
+Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required configuration that Claude cannot automate.
+
+**Purpose:** Document setup tasks that literally require human action - account creation, dashboard configuration, secret retrieval. Claude automates everything possible; this file captures only what remains.
+
+---
+
+## File Template
+
+```markdown
+# Phase {X}: User Setup Required
+
+**Generated:** [YYYY-MM-DD]
+**Phase:** {phase-name}
+**Status:** Incomplete
+
+Complete these items for the integration to function. Claude automated everything possible; these items require human access to external dashboards/accounts.
+
+## Environment Variables
+
+| Status | Variable | Source | Add to |
+|--------|----------|--------|--------|
+| [ ] | `ENV_VAR_NAME` | [Service Dashboard → Path → To → Value] | `.env.local` |
+| [ ] | `ANOTHER_VAR` | [Service Dashboard → Path → To → Value] | `.env.local` |
+
+## Account Setup
+
+[Only if new account creation is required]
+
+- [ ] **Create [Service] account**
+  - URL: [signup URL]
+  - Skip if: Already have account
+
+## Dashboard Configuration
+
+[Only if dashboard configuration is required]
+
+- [ ] **[Configuration task]**
+  - Location: [Service Dashboard → Path → To → Setting]
+  - Set to: [Required value or configuration]
+  - Notes: [Any important details]
+
+## Verification
+
+After completing setup, verify with:
+
+```bash
+# [Verification commands]
+```
+
+Expected results:
+- [What success looks like]
+
+---
+
+**Once all items complete:** Mark status as "Complete" at top of file.
+```
+
+---
+
+## When to Generate
+
+Generate `{phase}-USER-SETUP.md` when plan frontmatter contains `user_setup` field.
+
+**Trigger:** `user_setup` exists in PLAN.md frontmatter and has items.
+
+**Location:** Same directory as PLAN.md and SUMMARY.md.
+
+**Timing:** Generated during execute-plan.md after tasks complete, before SUMMARY.md creation.
+
+---
+
+## Frontmatter Schema
+
+In PLAN.md, `user_setup` declares human-required configuration:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "Payment processing requires API keys"
+    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"
+    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, customer.subscription.*"
+    local_dev:
+      - "Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+      - "Use the webhook secret from CLI output for local testing"
+```
+
+---
+
+## The Automation-First Rule
+
+**USER-SETUP.md contains ONLY what Claude literally cannot do.**
+
+| Claude CAN Do (not in USER-SETUP) | Claude CANNOT Do (→ USER-SETUP) |
+|-----------------------------------|--------------------------------|
+| `npm install stripe` | Create Stripe account |
+| Write webhook handler code | Get API keys from dashboard |
+| Create `.env.local` file structure | Copy actual secret values |
+| Run `stripe listen` | Authenticate Stripe CLI (browser OAuth) |
+| Configure package.json | Access external service dashboards |
+| Write any code | Retrieve secrets from third-party systems |
+
+**The test:** "Does this require a human in a browser, accessing an account Claude doesn't have credentials for?"
+- Yes → USER-SETUP.md
+- No → Claude does it automatically
+
+---
+
+## Service-Specific Examples
+
+<stripe_example>
+```markdown
+# Phase 10: User Setup Required
+
+**Generated:** 2025-01-14
+**Phase:** 10-monetization
+**Status:** Incomplete
+
+Complete these items for Stripe integration to function.
+
+## Environment Variables
+
+| Status | Variable | Source | Add to |
+|--------|----------|--------|--------|
+| [ ] | `STRIPE_SECRET_KEY` | Stripe Dashboard → Developers → API keys → Secret key | `.env.local` |
+| [ ] | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe Dashboard → Developers → API keys → Publishable key | `.env.local` |
+| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Developers → Webhooks → [endpoint] → Signing secret | `.env.local` |
+
+## Account Setup
+
+- [ ] **Create Stripe account** (if needed)
+  - URL: https://dashboard.stripe.com/register
+  - Skip if: Already have Stripe account
+
+## Dashboard Configuration
+
+- [ ] **Create webhook endpoint**
+  - Location: Stripe Dashboard → Developers → Webhooks → Add endpoint
+  - Endpoint URL: `https://[your-domain]/api/webhooks/stripe`
+  - Events to send:
+    - `checkout.session.completed`
+    - `customer.subscription.created`
+    - `customer.subscription.updated`
+    - `customer.subscription.deleted`
+
+- [ ] **Create products and prices** (if using subscription tiers)
+  - Location: Stripe Dashboard → Products → Add product
+  - Create each subscription tier
+  - Copy Price IDs to:
+    - `STRIPE_STARTER_PRICE_ID`
+    - `STRIPE_PRO_PRICE_ID`
+
+## Local Development
+
+For local webhook testing:
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+Use the webhook signing secret from CLI output (starts with `whsec_`).
+
+## Verification
+
+After completing setup:
+
+```bash
+# Check env vars are set
+grep STRIPE .env.local
+
+# Verify build passes
+npm run build
+
+# Test webhook endpoint (should return 400 bad signature, not 500 crash)
+curl -X POST http://localhost:3000/api/webhooks/stripe \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Expected: Build passes, webhook returns 400 (signature validation working).
+
+---
+
+**Once all items complete:** Mark status as "Complete" at top of file.
+```
+</stripe_example>
+
+<supabase_example>
+```markdown
+# Phase 2: User Setup Required
+
+**Generated:** 2025-01-14
+**Phase:** 02-authentication
+**Status:** Incomplete
+
+Complete these items for Supabase Auth to function.
+
+## Environment Variables
+
+| Status | Variable | Source | Add to |
+|--------|----------|--------|--------|
+| [ ] | `NEXT_PUBLIC_SUPABASE_URL` | Supabase Dashboard → Settings → API → Project URL | `.env.local` |
+| [ ] | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase Dashboard → Settings → API → anon public | `.env.local` |
+| [ ] | `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard → Settings → API → service_role | `.env.local` |
+
+## Account Setup
+
+- [ ] **Create Supabase project**
+  - URL: https://supabase.com/dashboard/new
+  - Skip if: Already have project for this app
+
+## Dashboard Configuration
+
+- [ ] **Enable Email Auth**
+  - Location: Supabase Dashboard → Authentication → Providers
+  - Enable: Email provider
+  - Configure: Confirm email (on/off based on preference)
+
+- [ ] **Configure OAuth providers** (if using social login)
+  - Location: Supabase Dashboard → Authentication → Providers
+  - For Google: Add Client ID and Secret from Google Cloud Console
+  - For GitHub: Add Client ID and Secret from GitHub OAuth Apps
+
+## Verification
+
+After completing setup:
+
+```bash
+# Check env vars
+grep SUPABASE .env.local
+
+# Verify connection (run in project directory)
+npx supabase status
+```
+
+---
+
+**Once all items complete:** Mark status as "Complete" at top of file.
+```
+</supabase_example>
+
+<sendgrid_example>
+```markdown
+# Phase 5: User Setup Required
+
+**Generated:** 2025-01-14
+**Phase:** 05-notifications
+**Status:** Incomplete
+
+Complete these items for SendGrid email to function.
+
+## Environment Variables
+
+| Status | Variable | Source | Add to |
+|--------|----------|--------|--------|
+| [ ] | `SENDGRID_API_KEY` | SendGrid Dashboard → Settings → API Keys → Create API Key | `.env.local` |
+| [ ] | `SENDGRID_FROM_EMAIL` | Your verified sender email address | `.env.local` |
+
+## Account Setup
+
+- [ ] **Create SendGrid account**
+  - URL: https://signup.sendgrid.com/
+  - Skip if: Already have account
+
+## Dashboard Configuration
+
+- [ ] **Verify sender identity**
+  - Location: SendGrid Dashboard → Settings → Sender Authentication
+  - Option 1: Single Sender Verification (quick, for dev)
+  - Option 2: Domain Authentication (production)
+
+- [ ] **Create API Key**
+  - Location: SendGrid Dashboard → Settings → API Keys → Create API Key
+  - Permission: Restricted Access → Mail Send (Full Access)
+  - Copy key immediately (shown only once)
+
+## Verification
+
+After completing setup:
+
+```bash
+# Check env var
+grep SENDGRID .env.local
+
+# Test email sending (replace with your test email)
+curl -X POST http://localhost:3000/api/test-email \
+  -H "Content-Type: application/json" \
+  -d '{"to": "your@email.com"}'
+```
+
+---
+
+**Once all items complete:** Mark status as "Complete" at top of file.
+```
+</sendgrid_example>
+
+---
+
+## Guidelines
+
+**Include in USER-SETUP.md:**
+- Environment variable names and where to find values
+- Account creation URLs (if new service)
+- Dashboard configuration steps
+- Verification commands to confirm setup works
+- Local development alternatives (e.g., `stripe listen`)
+
+**Do NOT include:**
+- Actual secret values (never)
+- Steps Claude can automate (package installs, code changes, file creation)
+- Generic instructions ("set up your environment")
+
+**Naming:** `{phase}-USER-SETUP.md` matches the phase number pattern.
+
+**Status tracking:** User marks checkboxes and updates status line when complete.
+
+**Searchability:** `grep -r "USER-SETUP" .planning/` finds all phases with user requirements.
--- a/get-shit-done/workflows/execute-plan.md
+++ b/get-shit-done/workflows/execute-plan.md
@@ -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>
--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -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