From 4da80d64a61ccf0b441884cf0f596f2c533d419c Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 14 Jan 2026 13:38:20 -0600 Subject: [PATCH] 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 --- get-shit-done/templates/phase-prompt.md | 36 +++ get-shit-done/templates/summary.md | 11 + get-shit-done/templates/user-setup.md | 323 ++++++++++++++++++++++++ get-shit-done/workflows/execute-plan.md | 96 +++++++ get-shit-done/workflows/plan-phase.md | 47 ++++ 5 files changed, 513 insertions(+) create mode 100644 get-shit-done/templates/user-setup.md diff --git a/get-shit-done/templates/phase-prompt.md b/get-shit-done/templates/phase-prompt.md index bbcc70f45..af364da80 100644 --- 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) --- @@ -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 diff --git a/get-shit-done/templates/summary.md b/get-shit-done/templates/summary.md index 7511bfcb9..3c699b100 100644 --- 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] diff --git a/get-shit-done/templates/user-setup.md b/get-shit-done/templates/user-setup.md new file mode 100644 index 000000000..8d0475909 --- /dev/null +++ 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 + + +```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. +``` + + + +```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. +``` + + + +```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. +``` + + +--- + +## 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. diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index 9b94b531f..f6171d6c8 100644 --- 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. + +**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. + + Create `{phase}-{plan}-SUMMARY.md` as specified in the prompt's `` 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 diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index f15eb4b87..4b7a2bd4b 100644 --- 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). @@ -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