mindsystem-cc 3.0.0

package/mindsystem/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.

package/mindsystem/templates/verification-report.md

@@ -0,0 +1,322 @@
+# Verification Report Template
+
+Template for `.planning/phases/XX-name/{phase}-VERIFICATION.md` — phase goal verification results.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M must-haves verified
+---
+
+# Phase {X}: {Name} Verification Report
+
+**Phase Goal:** {goal from ROADMAP.md}
+**Verified:** {timestamp}
+**Status:** {passed | gaps_found | human_needed}
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
+| 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
+| 3 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
+
+**Score:** {N}/{M} truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✓ EXISTS + SUBSTANTIVE | Exports ChatList, renders Message[], no stubs |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | File exists but POST returns placeholder |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Model defined with all fields |
+
+**Artifacts:** {N}/{M} verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat | fetch in useEffect | ✓ WIRED | Line 23: `fetch('/api/chat')` with response handling |
+| ChatInput | /api/chat POST | onSubmit handler | ✗ NOT WIRED | onSubmit only calls console.log |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns hardcoded response, no DB call |
+
+**Wiring:** {N}/{M} connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| {REQ-01}: {description} | ✓ SATISFIED | - |
+| {REQ-02}: {description} | ✗ BLOCKED | API route is stub |
+| {REQ-03}: {description} | ? NEEDS HUMAN | Can't verify WebSocket programmatically |
+
+**Coverage:** {N}/{M} requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ Warning | Indicates incomplete |
+| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 Blocker | Renders no content |
+| src/hooks/useChat.ts | - | File missing | 🛑 Blocker | Expected hook doesn't exist |
+
+**Anti-patterns:** {N} found ({blockers} blockers, {warnings} warnings)
+
+## Human Verification Required
+
+{If no human verification needed:}
+None — all verifiable items checked programmatically.
+
+{If human verification needed:}
+
+### 1. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+### 2. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+## Gaps Summary
+
+{If no gaps:}
+**No gaps found.** Phase goal achieved. Ready to proceed.
+
+{If gaps found:}
+
+### Critical Gaps (Block Progress)
+
+1. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+2. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+### Non-Critical Gaps (Can Defer)
+
+1. **{Gap name}**
+   - Issue: {what's wrong}
+   - Impact: {limited impact because...}
+   - Recommendation: {fix now or defer}
+
+## Recommended Fix Plans
+
+{If gaps found, generate fix plan recommendations:}
+
+### {phase}-{next}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task to fix gap 1}
+2. {Task to fix gap 2}
+3. {Verification task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+### {phase}-{next+1}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task}
+2. {Task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** {PLAN.md frontmatter | derived from ROADMAP.md goal}
+**Automated checks:** {N} passed, {M} failed
+**Human checks required:** {N}
+**Total verification time:** {duration}
+
+---
+*Verified: {timestamp}*
+*Verifier: Claude (subagent)*
+```
+
+---
+
+## Guidelines
+
+**Status values:**
+- `passed` — All must-haves verified, no blockers
+- `gaps_found` — One or more critical gaps found
+- `human_needed` — Automated checks pass but human verification required
+
+**Evidence types:**
+- For EXISTS: "File at path, exports X"
+- For SUBSTANTIVE: "N lines, has patterns X, Y, Z"
+- For WIRED: "Line N: code that connects A to B"
+- For FAILED: "Missing because X" or "Stub because Y"
+
+**Severity levels:**
+- 🛑 Blocker: Prevents goal achievement, must fix
+- ⚠️ Warning: Indicates incomplete but doesn't block
+- ℹ️ Info: Notable but not problematic
+
+**Fix plan generation:**
+- Only generate if gaps_found
+- Group related fixes into single plans
+- Keep to 2-3 tasks per plan
+- Include verification task in each plan
+
+---
+
+## Example
+
+```markdown
+---
+phase: 03-chat
+verified: 2025-01-15T14:30:00Z
+status: gaps_found
+score: 2/5 must-haves verified
+---
+
+# Phase 3: Chat Interface Verification Report
+
+**Phase Goal:** Working chat interface where users can send and receive messages
+**Verified:** 2025-01-15T14:30:00Z
+**Status:** gaps_found
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | User can see existing messages | ✗ FAILED | Component renders placeholder, not message data |
+| 2 | User can type a message | ✓ VERIFIED | Input field exists with onChange handler |
+| 3 | User can send a message | ✗ FAILED | onSubmit handler is console.log only |
+| 4 | Sent message appears in list | ✗ FAILED | No state update after send |
+| 5 | Messages persist across refresh | ? UNCERTAIN | Can't verify - send doesn't work |
+
+**Score:** 1/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✗ STUB | Returns `<div>Chat will be here</div>` |
+| `src/components/ChatInput.tsx` | Message input | ✓ EXISTS + SUBSTANTIVE | Form with input, submit button, handlers |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | GET returns [], POST returns { ok: true } |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Message model with id, content, userId, createdAt |
+
+**Artifacts:** 2/4 verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat GET | fetch | ✗ NOT WIRED | No fetch call in component |
+| ChatInput | /api/chat POST | onSubmit | ✗ NOT WIRED | Handler only logs, doesn't fetch |
+| /api/chat GET | database | prisma.message.findMany | ✗ NOT WIRED | Returns hardcoded [] |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns { ok: true }, no DB call |
+
+**Wiring:** 0/4 connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| CHAT-01: User can send message | ✗ BLOCKED | API POST is stub |
+| CHAT-02: User can view messages | ✗ BLOCKED | Component is placeholder |
+| CHAT-03: Messages persist | ✗ BLOCKED | No database integration |
+
+**Coverage:** 0/3 requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/components/Chat.tsx | 8 | `<div>Chat will be here</div>` | 🛑 Blocker | No actual content |
+| src/app/api/chat/route.ts | 5 | `return Response.json([])` | 🛑 Blocker | Hardcoded empty |
+| src/app/api/chat/route.ts | 12 | `// TODO: save to database` | ⚠️ Warning | Incomplete |
+
+**Anti-patterns:** 3 found (2 blockers, 1 warning)
+
+## Human Verification Required
+
+None needed until automated gaps are fixed.
+
+## Gaps Summary
+
+### Critical Gaps (Block Progress)
+
+1. **Chat component is placeholder**
+   - Missing: Actual message list rendering
+   - Impact: Users see "Chat will be here" instead of messages
+   - Fix: Implement Chat.tsx to fetch and render messages
+
+2. **API routes are stubs**
+   - Missing: Database integration in GET and POST
+   - Impact: No data persistence, no real functionality
+   - Fix: Wire prisma calls in route handlers
+
+3. **No wiring between frontend and backend**
+   - Missing: fetch calls in components
+   - Impact: Even if API worked, UI wouldn't call it
+   - Fix: Add useEffect fetch in Chat, onSubmit fetch in ChatInput
+
+## Recommended Fix Plans
+
+### 03-04-PLAN.md: Implement Chat API
+
+**Objective:** Wire API routes to database
+
+**Tasks:**
+1. Implement GET /api/chat with prisma.message.findMany
+2. Implement POST /api/chat with prisma.message.create
+3. Verify: API returns real data, POST creates records
+
+**Estimated scope:** Small
+
+---
+
+### 03-05-PLAN.md: Implement Chat UI
+
+**Objective:** Wire Chat component to API
+
+**Tasks:**
+1. Implement Chat.tsx with useEffect fetch and message rendering
+2. Wire ChatInput onSubmit to POST /api/chat
+3. Verify: Messages display, new messages appear after send
+
+**Estimated scope:** Small
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** 03-01-PLAN.md frontmatter
+**Automated checks:** 2 passed, 8 failed
+**Human checks required:** 0 (blocked by automated failures)
+**Total verification time:** 2 min
+
+---
+*Verified: 2025-01-15T14:30:00Z*
+*Verifier: Claude (subagent)*
+```