thrivekit 2.0.0

package/.claude/commands/tour.md

@@ -0,0 +1,301 @@
+---
+description: Take an interactive tour of thrivekit - the system for going from idea to shipped code with AI.
+---
+
+# Vibe & Thrive Tour
+
+## Step 1: Check & Fix Setup
+
+Print this exactly:
+
+```
+  ╦  ╦╦╔╗ ╔═╗   ┬   ╔╦╗╦ ╦╦═╗╦╦  ╦╔═╗
+  ╚╗╔╝║╠╩╗║╣   ┌┼─   ║ ╠═╣╠╦╝║╚╗╔╝║╣
+   ╚╝ ╩╚═╝╚═╝  └┘    ╩ ╩ ╩╩╚═╩ ╚╝ ╚═╝
+
+  Checking setup...
+```
+
+**Check each item and FIX if missing:**
+
+1. **Check jq installed:**
+   ```bash
+   command -v jq
+   ```
+   - If missing: Say "⚠️ jq not found. Install it: `brew install jq` (macOS) or `apt install jq` (Linux)"
+   - If found: ✓ jq installed
+
+2. **Check slash commands:**
+   ```bash
+   test -d .claude/commands && ls .claude/commands/*.md 2>/dev/null | wc -l
+   ```
+   - If missing or count is 0: Copy from node_modules:
+     ```bash
+     mkdir -p .claude/commands && cp -r node_modules/thrivekit/.claude/commands/* .claude/commands/
+     ```
+   - Then: ✓ Slash commands installed
+
+3. **Check Ralph initialized:**
+   ```bash
+   test -f .ralph/config.json
+   ```
+   - If missing: Run `npx ralph init`
+   - Then: ✓ Ralph initialized
+
+4. **Check CLAUDE.md:**
+   ```bash
+   test -f CLAUDE.md
+   ```
+   - If missing: Create a basic one:
+     ```bash
+     echo "# Project Guide for Claude" > CLAUDE.md
+     ```
+   - Then: ✓ CLAUDE.md created
+
+5. **Check Claude Code hooks:**
+   ```bash
+   test -f .claude/settings.json && jq -e '.hooks' .claude/settings.json > /dev/null 2>&1
+   ```
+   - If missing: Install hooks:
+     ```bash
+     npx ralph hooks
+     ```
+   - Then: ✓ Claude Code hooks installed
+
+6. **Check Docker:**
+   ```bash
+   test -f docker-compose.yml || test -f docker-compose.yaml || test -f compose.yml
+   ```
+   - If found:
+     - Update config: `jq '.docker.enabled = true' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json`
+     - Say: "✓ Docker detected - Ralph will run commands inside containers"
+     - **Skip Playwright check** (browser verification uses curl in Docker mode)
+
+7. **Check & Install Playwright (if not Docker):**
+
+   Check BOTH the npm package AND browser binaries:
+   ```bash
+   # Check npm package
+   npm list playwright 2>/dev/null
+
+   # Check browser binaries exist (macOS or Linux path)
+   ls ~/Library/Caches/ms-playwright/chromium-* 2>/dev/null || ls ~/.cache/ms-playwright/chromium-* 2>/dev/null
+   ```
+
+   - If BOTH exist: Say "✓ Playwright available"
+   - If either is missing:
+     Say: "Installing Playwright for browser verification (~150MB)..."
+     ```bash
+     npm install playwright && npx playwright install chromium
+     ```
+     - If successful: Say "✓ Playwright installed"
+     - If failed: Say "⚠️ Playwright installation failed. Browser verification will use basic HTTP checks. You can try manually: `npm install playwright && npx playwright install chromium`"
+
+Say: "Setup verified! Let me configure Ralph for your project..."
+
+---
+
+## Step 2: Auto-Configure Ralph
+
+**Auto-detect and configure project settings:**
+
+### 2a. Detect Project Structure
+
+Check these directories and set `paths` in config:
+
+```bash
+# Check what exists
+test -d frontend && echo "frontend exists"
+test -d client && echo "client exists"
+test -d backend && echo "backend exists"
+test -d core && echo "core exists"
+test -d src && echo "src exists"
+```
+
+Based on results, update config:
+- `frontend/` exists → set `paths.frontend` to `"frontend"`
+- `client/` exists → set `paths.frontend` to `"client"`
+- `backend/` exists → set `paths.backend` to `"backend"`
+- `core/` exists → set `paths.backend` to `"core"`
+- Only `src/` exists → set `paths.frontend` to `"."`
+
+### 2b. Detect URLs
+
+Check `.env`, `.env.example`, or `docker-compose.yml` for port numbers:
+
+```bash
+grep -h "PORT\|URL\|localhost" .env .env.example docker-compose.yml 2>/dev/null | head -5
+```
+
+Also check `package.json` for port in dev script:
+```bash
+cat package.json 2>/dev/null | jq -r '.scripts.dev // empty'
+```
+
+Set URLs based on findings (defaults: frontend=3000, backend=8000):
+```bash
+jq '.urls.frontend = "http://localhost:3000" | .urls.backend = "http://localhost:8000"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+```
+
+### 2c. Detect Commands
+
+Read package.json scripts and update config:
+
+```bash
+# Get scripts from package.json (check root and frontend/)
+cat package.json 2>/dev/null | jq -r '.scripts | to_entries[] | "\(.key): \(.value)"' | head -10
+```
+
+Update config with detected commands:
+```bash
+# Example: if package.json has "dev": "next dev"
+jq '.commands.dev = "npm run dev"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+```
+
+For fullstack projects with separate frontend:
+```bash
+jq '.commands.dev = "cd frontend && npm run dev"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+```
+
+### 2d. Detect Build & Test
+
+Check for build script in package.json:
+```bash
+cat package.json 2>/dev/null | jq -r '.scripts.build // empty'
+cat frontend/package.json 2>/dev/null | jq -r '.scripts.build // empty'
+```
+
+Update config with build command:
+```bash
+# If build script exists in root
+jq '.checks.build = "npm run build"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+
+# If build script exists in frontend/
+jq '.checks.build = "cd frontend && npm run build"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+```
+
+Detect test framework:
+```bash
+test -f playwright.config.ts && echo "playwright"
+test -f vitest.config.ts && echo "vitest"
+test -f jest.config.js && echo "jest"
+test -f manage.py && echo "django"
+test -f pytest.ini && echo "pytest"
+test -f pyproject.toml && grep -q "pytest" pyproject.toml && echo "pytest"
+```
+
+Update config:
+```bash
+# If playwright found
+jq '.playwright.enabled = true' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+
+# If Django found (NO --parallel - it hides errors)
+jq '.checks.test = "python manage.py test --keepdb"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+
+# If Django + Docker
+jq '.checks.test = "docker compose exec -T web python manage.py test --keepdb"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+
+# If pytest found
+jq '.checks.test = "pytest"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+
+# If vitest/jest found
+jq '.checks.test = "npm test"' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+```
+
+### 2e. Show Results
+
+After updating, read the config and show user:
+
+```bash
+cat .ralph/config.json | jq '{paths, urls, commands, checks}'
+```
+
+Say: "I've auto-configured Ralph:
+
+[Show the detected settings in a nice format]
+
+Edit `.ralph/config.json` if anything needs adjusting."
+
+### 2f. Test Credentials (Optional)
+
+```bash
+cat .ralph/config.json | jq -r '.auth.testUser // empty'
+```
+
+**If empty**, use AskUserQuestion:
+- **Question:** "Add test credentials? Ralph needs these for authenticated endpoints."
+- **Header:** "Test auth"
+- **Options:**
+  - **Yes** - "I'll ask for email and password"
+  - **Skip** - "Edit .ralph/config.json later"
+
+If "Yes":
+- Ask for email, then password
+- Update config:
+  ```bash
+  jq --arg u "$EMAIL" --arg p "$PASSWORD" '.auth.testUser = $u | .auth.testPassword = $p' .ralph/config.json > .ralph/config.tmp && mv .ralph/config.tmp .ralph/config.json
+  ```
+- Say: "✓ Test credentials saved"
+
+If "Skip":
+- Say: "No problem! Add credentials to `.ralph/config.json` when needed."
+
+**If already set:**
+- Say: "✓ Test credentials configured"
+
+---
+
+## Step 3: Check for DNA
+
+Check if `~/.claude/DNA.md` exists.
+
+**If DNA.md does NOT exist:**
+
+Use AskUserQuestion:
+- **Question:** "Want to set up your personal preferences? This teaches me how you like to work."
+- **Header:** "DNA setup"
+- **Options:**
+  - **Yes, set up my DNA** - "Takes ~2 minutes, makes our collaboration better"
+  - **Skip for now** - "You can run /my-dna anytime"
+
+If user selects "Yes, set up my DNA":
+- Run the `/my-dna` command inline (execute its full flow)
+- After completing, continue to Step 4
+
+If user selects "Skip for now":
+- Say: "No problem! Run `/my-dna` anytime."
+- Continue to Step 4
+
+**If DNA.md EXISTS:**
+
+Skip this step entirely. Move to Step 4.
+
+---
+
+## Step 4: Quick Reference
+
+Print this:
+
+```
+Quick Reference
+───────────────
+
+Workflow:
+  /idea [feature]       Brainstorm → PRD
+  npx ralph run         Execute autonomously
+  npx ralph status      Check progress
+  npx ralph stop        Stop after current story
+
+Quality:
+  /vibe-check           Audit code quality
+  /review               Review changes
+  npx ralph check       Run verification
+
+Other:
+  /my-dna               Set preferences
+  /explain              Understand code
+  /styleguide           Generate design system
+  /vibe-help            Full cheatsheet
+```
+
+Say: "You're all set! Run `/idea [your next feature]` to get started."

package/.claude/commands/vibe-check.md

@@ -0,0 +1,116 @@
+---
+description: Run a comprehensive code quality check looking for common patterns that AI coding agents introduce.
+---
+
+# Vibe Check
+
+Run a comprehensive code quality check on the current codebase, looking for common patterns that AI coding agents introduce.
+
+## Instructions
+
+Analyze the codebase for the following issues. For each category, search the relevant file types and report what you find.
+
+### 1. Debug Statements
+Search for debug statements that shouldn't go to production:
+- Python: `print()`, `breakpoint()`, `pdb.set_trace()`, `ipdb`
+- JS/TS: `console.log()`, `console.debug()`, `console.info()`, `debugger`
+
+Ignore: `console.error()`, `console.warn()`, `logger.*` calls, and lines with `// noqa: debug` or `# noqa: debug`
+
+### 2. TODO/FIXME Comments
+Search for unfinished work markers:
+- `TODO`, `FIXME`, `XXX`, `HACK`, `BUG`
+
+Skip markdown files and dedicated TODO files.
+
+### 3. Empty Catch Blocks
+Search for error handling that silently swallows errors:
+- Python: `except: pass` or `except Exception: pass`
+- JS/TS: `catch (e) {}` or `.catch(() => {})`
+
+### 4. Hardcoded URLs
+Search for localhost/development URLs:
+- `http://localhost:`
+- `http://127.0.0.1:`
+
+Skip test files and config files.
+
+### 5. snake_case in TypeScript
+Search TypeScript interface/type definitions for snake_case property names that should be camelCase.
+
+### 6. Magic Numbers
+In Python files, look for hardcoded numbers > 10 that aren't in constants files.
+
+### 7. Potential Secrets
+Search for patterns that look like hardcoded secrets:
+- `AKIA` (AWS keys)
+- `sk-` followed by long strings (OpenAI/Stripe)
+- `ghp_` (GitHub tokens)
+- Connection strings with passwords
+
+Skip `.env.example` files.
+
+### 8. DRY Violations
+Look for obvious code duplication:
+- Very similar functions
+- Repeated string literals (same long string 3+ times)
+- Copy-pasted code blocks
+
+## Output Format
+
+Provide a summary report like this:
+
+```
+## Vibe Check Report
+
+### Summary
+- X issues found across Y files
+- Z high priority (secrets, hardcoded URLs)
+- W low priority (TODOs, debug statements)
+
+### High Priority (fix before committing)
+
+#### Potential Secrets
+- file.py:42 - Looks like an API key
+
+#### Hardcoded URLs
+- api.ts:15 - localhost URL should use env var
+
+### Medium Priority (fix soon)
+
+#### Empty Catch Blocks
+- service.py:88 - except: pass (silently swallows errors)
+
+#### snake_case in TypeScript
+- types.ts:12 - `user_id` should be `userId`
+
+### Low Priority (nice to fix)
+
+#### Debug Statements
+- utils.py:23 - print() statement
+- component.tsx:45 - console.log()
+
+#### TODO/FIXME
+- auth.py:67 - TODO: implement refresh token
+
+### Clean Areas
+- No magic numbers found
+- No DRY violations detected
+```
+
+If everything looks good:
+
+```
+## Vibe Check Report
+
+✨ Looking good! No issues found.
+
+Your code is clean and ready to ship.
+```
+
+## Notes
+
+- Focus on **actionable** findings, not nitpicks
+- Group by severity to help prioritize
+- If a file has many issues, summarize rather than listing every line
+- Be encouraging - the goal is to help, not shame

package/.claude/commands/vibe-help.md

@@ -0,0 +1,47 @@
+---
+description: Quick reference cheatsheet for all thrivekit commands including Ralph.
+---
+
+# Vibe & Thrive Cheatsheet
+
+Print this cheatsheet for the user. Do not add any commentary or explanation.
+
+---
+
+## The Loop
+
+```
+/idea [feature]          brainstorm & generate PRD
+npx ralph run            autonomous coding loop
+npx ralph status         check progress
+npx ralph stop           stop after current story
+```
+
+---
+
+Run `/vibe-list` to see all commands.
+
+---
+
+## Quality
+
+```
+/vibe-check              audit code quality
+/review                  security-focused review
+npx ralph check          run verification only
+```
+
+---
+
+## Setup & Learning
+
+```
+/tour                    guided setup
+/my-dna                  set preferences
+/sign                    teach Ralph a pattern
+npx ralph signs          view learned patterns
+```
+
+---
+
+*https://github.com/allthriveai/thrivekit*

package/.claude/commands/vibe-list.md

@@ -0,0 +1,203 @@
+---
+description: Show complete reference for all thrivekit commands (slash commands, Ralph CLI, vibe CLI).
+---
+
+# Vibe & Thrive - Complete Reference
+
+Print this complete reference for the user. Do not add any commentary.
+
+---
+
+## Slash Commands (in Claude Code)
+
+| Command | Description |
+|---------|-------------|
+| `/idea [feature]` | Brainstorm in plan mode, generate PRD for Ralph |
+| `/sign` | Add a learned pattern for Ralph to remember |
+| `/my-dna` | Set up your personal style preferences |
+| `/vibe-check` | Audit code quality before shipping |
+| `/review` | Code review with OWASP security checks |
+| `/explain` | Explain code line by line |
+| `/styleguide` | Generate UI component design system |
+| `/tour` | Interactive walkthrough of thrivekit |
+| `/vibe-help` | Quick reference cheatsheet |
+| `/vibe-list` | This complete reference |
+
+---
+
+## Ralph CLI (in terminal)
+
+### Setup & Status
+| Command | Description |
+|---------|-------------|
+| `npx ralph init` | Initialize `.ralph/` in current directory |
+| `npx ralph status` | Show feature, stories, pass/fail counts |
+| `npx ralph progress` | Show last 50 lines of progress log |
+| `npx ralph version` | Show version info |
+| `npx ralph help` | Show built-in help |
+
+### PRD Generation
+| Command | Description |
+|---------|-------------|
+| `npx ralph prd "notes"` | Generate PRD interactively from description |
+| `npx ralph prd --file spec.md` | Generate PRD from a file |
+| `npx ralph prd --accept` | Save generated PRD to `.ralph/prd.json` |
+
+### Autonomous Loop
+| Command | Description |
+|---------|-------------|
+| `npx ralph run` | Run loop until all stories pass |
+| `npx ralph run --max 10` | Limit to N iterations (default: 20) |
+| `npx ralph run --story TASK-001` | Run for specific task only |
+| `npx ralph stop` | Stop after current story completes |
+
+### Verification
+| Command | Description |
+|---------|-------------|
+| `npx ralph check` | Run all configured checks |
+| `npx ralph verify TASK-001` | Verify a specific task |
+
+### Signs (Learned Patterns)
+| Command | Description |
+|---------|-------------|
+| `npx ralph signs` | List all learned patterns |
+| `npx ralph sign "pattern" [cat]` | Add pattern with optional category |
+| `npx ralph unsign <id or text>` | Remove a sign by ID or text match |
+
+---
+
+## Vibe CLI (in terminal)
+
+| Command | Description |
+|---------|-------------|
+| `vibe help` | Show terminal quick reference |
+
+---
+
+## The Loop
+
+```
+/idea [feature]          Brainstorm → PRD
+npx ralph run            Autonomous coding
+npx ralph status         Check progress
+npx ralph stop           Stop after current story
+```
+
+---
+
+## Slash Command Details
+
+### /idea [feature description]
+Brainstorm in plan mode, explore codebase, ask clarifying questions.
+- Writes idea to `docs/ideas/{feature}.md`
+- On approval, splits into PRD stories
+- Writes to `.ralph/prd.json`
+
+### /review [file or selection]
+Code review with security focus (OWASP Top 10):
+- **Quick review** - Critical/high issues only
+- **Full review** - Everything
+- **Security review** - Deep dive on vulnerabilities
+- **Performance review** - Focus on speed
+
+### /explain [file or code]
+Line-by-line explanation:
+- High-level overview
+- Walk through each section
+- Highlight key concepts
+- Summarize takeaways
+
+### /styleguide
+Generate design system page at `/styleguide`:
+- Discovers your tech stack
+- Asks about vibe (minimal, bold, dark, etc.)
+- Asks about colors, border radius, components
+- Generates tokens, buttons, forms, cards, feedback
+
+### /vibe-check
+Audit code for AI-introduced patterns:
+- Debug statements
+- TODO/FIXME comments
+- Empty catch blocks
+- Hardcoded URLs
+- Potential secrets
+- DRY violations
+
+### /my-dna
+Interactive wizard to set up your personal style:
+- Core values (simplicity, speed, correctness, etc.)
+- Communication preferences (brief vs detailed, tone)
+- Working style (ask first vs try solutions)
+- Learning preferences (show alternatives, explain why)
+
+Creates `~/.claude/DNA.md` - applies to all your projects.
+
+---
+
+## Signs Examples
+
+```bash
+# Add patterns Ralph should follow
+npx ralph sign "Always use camelCase in WebSocket responses" frontend
+npx ralph sign "Run migrations before seeding" backend
+npx ralph sign "Check for null before accessing nested props" general
+
+# List learned patterns
+npx ralph signs
+
+# Remove a sign
+npx ralph unsign sign-001
+npx ralph unsign "camelCase"
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RALPH_DIR` | `.ralph` | Override ralph directory |
+| `PROMPT_FILE` | `PROMPT.md` | Override prompt file |
+
+---
+
+## Config (.ralph/config.json)
+
+```json
+{
+  "checks": {
+    "lint": "npm run lint",
+    "test": "npm test",
+    "build": "npm run build"
+  },
+  "testUrlBase": "http://localhost:3000",
+  "maxSessionSeconds": 600
+}
+```
+
+---
+
+## File Structure
+
+```
+# Project files
+.ralph/
+├── config.json      # Verification checks, settings
+├── prd.json         # Current feature PRD
+├── signs.json       # Learned patterns
+├── progress.txt     # Activity log
+├── archive/         # Completed PRDs
+└── screenshots/     # Browser verification captures
+
+CLAUDE.md            # Project standards (shared with team)
+PROMPT.md            # Base prompt for Ralph sessions
+docs/ideas/          # Brainstorm outputs from /idea
+
+# Global files (your home directory)
+~/.claude/
+└── DNA.md           # Your DNA - personal preferences (from /my-dna)
+```
+
+---
+
+*https://github.com/allthriveai/thrivekit*