start-vibing-stacks 2.3.0 → 2.4.0

package/templates/CLAUDE-nodejs.md

@@ -0,0 +1,323 @@
+# {{PROJECT_NAME}}
+
+> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
+
+## Last Change
+
+**Branch:** main
+**Date:** {{DATE}}
+**Summary:** Initial project setup with start-vibing-stacks (Node.js)
+
+## 30 Seconds Overview
+
+{{PROJECT_NAME}} is a TypeScript project using {{FRAMEWORK}}.
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | Bun / Node.js 20+ |
+| Language | TypeScript **strict mode** |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+| Validation | Zod |
+| Testing | Vitest + Playwright |
+| UI | React + Tailwind + shadcn |
+| Data | TanStack Query + Sonner |
+| Forms | react-hook-form + Zod |
+
+## Architecture
+
+```
+project/
+├── CLAUDE.md               # This file (40k char max)
+├── .claude/
+│   ├── agents/             # 6 active subagents
+│   ├── skills/             # Skill systems (auto-injected)
+│   ├── hooks/              # Validation hooks
+│   ├── config/             # Project configuration
+│   └── commands/           # Slash commands (/feature, /fix, /research, /validate)
+├── src/
+│   ├── app/                # Next.js App Router pages
+│   │   ├── (marketing)/    # Route group — public pages
+│   │   ├── (app)/          # Route group — authenticated
+│   │   │   └── dashboard/
+│   │   │       ├── page.tsx
+│   │   │       └── _components/  # Page-specific components
+│   │   ├── api/            # Route handlers (API endpoints)
+│   │   ├── layout.tsx      # Root layout with providers
+│   │   └── loading.tsx     # Global loading skeleton
+│   ├── components/
+│   │   ├── ui/             # shadcn primitives (Button, Input)
+│   │   ├── layout/         # Header, Sidebar, Footer
+│   │   ├── shared/         # Cross-feature components
+│   │   └── providers.tsx   # Context providers (client)
+│   ├── lib/
+│   │   ├── utils.ts        # cn utility (clsx + tailwind-merge)
+│   │   ├── api/            # API client instances
+│   │   └── validations/    # Zod schemas
+│   ├── hooks/              # Custom React hooks
+│   └── styles/             # Global styles, theme tokens
+├── types/                  # ALL TypeScript interfaces (MANDATORY)
+├── tests/
+│   ├── unit/               # Vitest unit tests
+│   └── e2e/                # Playwright E2E tests
+├── public/                 # Static assets
+├── tsconfig.json           # TypeScript config (strict: true)
+├── next.config.ts          # Framework config
+├── tailwind.config.ts      # TailwindCSS config
+├── vitest.config.ts        # Test config
+└── package.json            # Dependencies
+```
+
+## Workflow
+
+```
+0. TODO LIST      → Create detailed todo list from prompt
+1. BRANCH         → Create feature/ | fix/ | refactor/ | test/
+2. RESEARCH       → Run research-web agent for NEW features
+3. IMPLEMENT      → Follow project rules + strict types
+4. TEST           → Run tester agent (Vitest / Playwright)
+5. DOCUMENT       → Run documenter agent for modified files
+6. UPDATE         → Update THIS FILE (CLAUDE.md) with changes
+7. QUALITY        → bun run typecheck && lint && test
+8. COMMIT         → Conventional commits, merge to main
+```
+
+## CLAUDE.md Update Rules
+
+> After ANY implementation, update this file to reflect the current state.
+
+| Change Type | Sections to Update |
+|-------------|-------------------|
+| Any file change | Last Change (branch, date, summary) |
+| API/routes | Critical Rules, Architecture |
+| UI components | Architecture, Component Organization |
+| New feature | 30s Overview, Architecture |
+| New gotcha | FORBIDDEN or NRY |
+| New dependency | Stack |
+| Workflow change | Workflow section |
+
+1. **Last Change** documents WHAT was done
+2. **Other sections** document HOW things work NOW
+3. **Both must be current** — updating only Last Change is insufficient
+4. Keep only the LATEST Last Change entry (no stacking)
+
+## Agent System
+
+### Subagents (6)
+
+| Agent | Purpose |
+|-------|---------|
+| **research-web** | Researches best practices before new features |
+| **documenter** | Maps files to domains, creates/updates domain docs |
+| **domain-updater** | Records problems, solutions, learnings |
+| **commit-manager** | Manages git commits, conventional format |
+| **claude-md-compactor** | Compacts CLAUDE.md when > 40k chars |
+| **tester** | Creates tests with Vitest/Playwright |
+
+### Skills
+
+| Category | Skills |
+|----------|--------|
+| **Development** | typescript-strict, react-patterns, nextjs-app-router, zod-validation, shadcn-ui, tailwind-patterns |
+| **Quality** | quality-gate, security-scan, test-coverage, final-check |
+| **Infrastructure** | docker-patterns, git-workflow, performance-patterns, debugging-patterns |
+| **Documentation** | codebase-knowledge, docs-tracker, research-cache, ui-ux-audit |
+
+## Critical Rules
+
+- **TypeScript strict mode** — `strict: true` in tsconfig.json
+- **Bracket notation** for env vars: `process.env['VARIABLE']`
+- **Zod validation** for ALL external input (forms, API, env)
+- **Server Components by default** — push `'use client'` to leaf components
+- **Parallel data fetching** — `Promise.all()` over waterfall
+- **Type everything** — no `any`, use `unknown` for truly unknown data
+- **Loading states** — every data page must have `loading.tsx`
+- **Error boundaries** — every route should handle errors gracefully
+- **Conventional commits** — `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+
+### Environment Variables Security (MANDATORY)
+
+> **NEVER expose secrets to the browser.** `NEXT_PUBLIC_*` vars are embedded in the JS bundle and visible to anyone.
+
+| Prefix | Where it runs | Safe for |
+|--------|--------------|----------|
+| `NEXT_PUBLIC_*` | Browser + Server | Public URLs, analytics IDs, Stripe **publishable** key (`pk_`) |
+| No prefix | Server ONLY | API keys, secrets, tokens, database URLs, private keys |
+
+```typescript
+// .env.local
+OPENAI_KEY=sk-abc123                    // Server only — SAFE
+STRIPE_SECRET_KEY=sk_live_abc           // Server only — SAFE
+NEXT_PUBLIC_APP_URL=https://myapp.com   // Public — OK (no secret)
+NEXT_PUBLIC_STRIPE_KEY=pk_live_abc      // Public — OK (publishable key)
+
+// NEXT_PUBLIC_OPENAI_KEY=sk-abc123     // FORBIDDEN — exposed in browser bundle!
+```
+
+### API Proxy Pattern (MANDATORY for external APIs)
+
+> **ALL calls to external APIs with secrets MUST go through server-side Route Handlers or Server Actions. NEVER call external APIs directly from client components.**
+
+```typescript
+// app/api/chat/route.ts — Server-side proxy (token NEVER leaves server)
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { message } = await req.json();
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    headers: { Authorization: `Bearer ${process.env['OPENAI_KEY']}` },
+    method: 'POST',
+    body: JSON.stringify({ model: 'gpt-4', messages: [{ role: 'user', content: message }] }),
+  });
+  return NextResponse.json(await response.json());
+}
+
+// components/chat.tsx — Client calls YOUR API, not the external one
+'use client';
+const response = await fetch('/api/chat', {
+  method: 'POST',
+  body: JSON.stringify({ message }),
+});
+```
+
+### Types Location
+
+- **ALL** interfaces/types MUST be in `types/` folder
+- **NEVER** define types in `src/` files
+- **EXCEPTION:** Zod inferred types (`z.infer<typeof Schema>`)
+
+### TypeScript Strict
+
+```typescript
+process.env['VARIABLE'];    // CORRECT (bracket notation)
+source: 'listed' as const;  // CORRECT (literal type)
+```
+
+### Component Organization
+
+| Question | Location |
+|----------|----------|
+| Used in ONE page only? | `app/[page]/_components/` |
+| Used across 2+ features? | `components/shared/` |
+| UI primitive (Button, Input)? | `components/ui/` |
+| Layout element (Header)? | `components/layout/` |
+
+| Lines | Action |
+|-------|--------|
+| < 200 | Keep in single file |
+| 200-400 | Consider splitting |
+| > 400 | **MUST split** into smaller components |
+
+## FORBIDDEN
+
+### Security (CRITICAL)
+
+| Action | Reason |
+|--------|--------|
+| `NEXT_PUBLIC_` with API keys/secrets/tokens | Exposes credentials in browser JS bundle — use server-side proxy |
+| Call external APIs from client components | Leaks tokens — route through `app/api/` Route Handlers |
+| `process.env['SECRET']` in `'use client'` files | Only `NEXT_PUBLIC_*` vars reach the browser — use Server Actions |
+| Hardcode API keys in source code | Use `.env.local` + server-side access only |
+| Commit `.env.local` / `.env` to git | Add to `.gitignore` — use `.env.example` with empty values |
+
+### Code Quality
+
+| Action | Reason |
+|--------|--------|
+| `any` type | Defeats strict mode — use `unknown` |
+| Skip typecheck | TypeScript errors become runtime bugs |
+| Relative imports (shared) | Breaks when files move — use `@/` alias |
+| Define types in `src/` | Must be in `types/` folder |
+| `'use client'` at top-level layouts | Breaks server rendering, push to leaves |
+| Waterfall data fetching | Use `Promise.all()` for parallel |
+| Skip `loading.tsx` on data pages | Flash of empty content |
+| Files > 400 lines | MUST split into smaller components |
+| Wildcard icon imports | Use named: `import { X } from 'lucide-react'` |
+| `var` keyword | Use `const` or `let` |
+| Raw `console.log` in production | Use structured logging |
+
+### Workflow
+
+| Action | Reason |
+|--------|--------|
+| Commit directly to main | Create feature/fix branches |
+| Skip research for new features | Leads to outdated patterns |
+| Skip todo list creation | Loses track of tasks |
+| Skip documenter agent | Documentation is mandatory |
+| Skip domain documentation | MUST update domains/*.md |
+| Stack Last Change entries | Keep only the LATEST |
+| Use MUI/Chakra | Use shadcn/ui + Radix |
+| Skip CLAUDE.md update | MUST update after implementations |
+
+## UI Architecture
+
+> Web apps MUST have **separate UIs** for each platform, NOT just "responsive design".
+
+| Platform | Layout |
+|----------|--------|
+| Mobile (375px) | Full-screen modals, bottom nav, touch-first |
+| Tablet (768px) | Condensed dropdowns, hybrid nav |
+| Desktop (1280px+) | Sidebar left, top navbar with search |
+
+## Quality Gates
+
+```bash
+bun run typecheck   # MUST pass
+bun run lint        # MUST pass
+bun run test        # MUST pass
+bun run build       # MUST pass
+```
+
+## Domain Documentation
+
+> Domain docs prevent Claude from re-exploring the codebase every session.
+
+```
+.claude/skills/codebase-knowledge/domains/
+├── authentication.md
+├── api.md
+├── database.md
+├── ui-components.md
+└── [domain-name].md
+```
+
+Each domain file tracks: Files, Connections, Recent Commits, Attention Points, Problems & Solutions.
+
+## Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`
+
+## NRY (Never Repeat Yourself)
+
+- Multi-line bash with `\` continuations (breaks permissions)
+- Relative paths in permission patterns
+- Using bash for file operations (use Read/Write/Edit tools)
+- Ignoring context size (use `/compact`)
+
+## Configuration
+
+Project settings in `.claude/config/`:
+
+- `active-project.json` — Stack, framework, database, skills
+- `domain-mapping.json` — File-to-domain mapping
+- `quality-gates.json` — Quality check commands
+- `testing-config.json` — Test framework config
+- `security-rules.json` — Security audit rules
+- `standards-review.json` — Imported project standards
+
+## Setup by start-vibing-stacks
+
+This project was set up with `npx start-vibing-stacks`.
+For updates: `npx start-vibing-stacks --force`

package/templates/CLAUDE-php.md

@@ -1,5 +1,7 @@
 # {{PROJECT_NAME}}
 
+> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
+
 ## Last Change
 
 **Branch:** main
@@ -78,6 +80,24 @@ project/
 └── CLAUDE.md            # This file
 ```
 
+## CLAUDE.md Update Rules
+
+> After ANY implementation, update this file to reflect the current state.
+
+| Change Type | Sections to Update |
+|-------------|-------------------|
+| Any file change | Last Change (branch, date, summary) |
+| API/routes | Critical Rules, Architecture |
+| New feature | 30s Overview, Architecture |
+| New gotcha | FORBIDDEN or NRY |
+| New dependency | Stack |
+| Workflow change | Workflow section |
+
+1. **Last Change** documents WHAT was done
+2. **Other sections** document HOW things work NOW
+3. **Both must be current** — updating only Last Change is insufficient
+4. Keep only the LATEST Last Change entry (no stacking)
+
 ## Critical Rules
 
 - **PHP >= 8.3** — readonly, enums, typed constants, match expressions
@@ -94,18 +114,80 @@ project/
 - **Config immutable** — never use `config()` to SET values at runtime
 - **Request object** — use `$request->input()`, never `$_GET`/`$_POST`/`$_SESSION`
 
+### Environment Variables & Secrets (MANDATORY)
+
+> **NEVER use `env()` outside config files.** After `config:cache`, `env()` returns null everywhere except config files.
+
+| Location | Access | Safe for |
+|----------|--------|----------|
+| `.env` | `env()` inside `config/*.php` only | API keys, DB credentials, secrets |
+| `config/*.php` | `config('services.stripe.key')` | Application code access |
+| Frontend (Inertia) | `InertiaShare` or controller props | Public data ONLY |
+
+```php
+// config/services.php — Bridge between .env and application
+return [
+    'openai' => [
+        'key' => env('OPENAI_KEY'),
+    ],
+    'stripe' => [
+        'key' => env('STRIPE_KEY'),          // Publishable (sent to frontend)
+        'secret' => env('STRIPE_SECRET'),    // NEVER send to frontend
+        'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
+    ],
+];
+
+// In code: ALWAYS use config()
+$apiKey = config('services.openai.key');
+
+// FORBIDDEN:
+$apiKey = env('OPENAI_KEY'); // Returns null when config is cached!
+```
+
+### Frontend Secret Isolation (MANDATORY)
+
+> **NEVER send API keys, secrets, or tokens to the frontend via Inertia props or JavaScript.**
+
+```php
+// WRONG — secret exposed in page source / DevTools
+return Inertia::render('Dashboard', [
+    'stripeSecret' => config('services.stripe.secret'),
+    'openaiKey' => config('services.openai.key'),
+]);
+
+// CORRECT — only public/publishable data to frontend
+return Inertia::render('Dashboard', [
+    'stripePublicKey' => config('services.stripe.key'), // pk_ only
+]);
+
+// For operations requiring secrets: use backend API routes
+// Frontend calls /api/payment → backend uses secret server-side
+```
+
 ## FORBIDDEN
 
-### Backend
+### Security (CRITICAL)
 
 | Action | Reason |
 |--------|--------|
+| `env()` outside config files | Returns null when config is cached — use `config()` |
+| Send API keys/secrets via Inertia props | Exposed in page source — keep secrets server-side |
+| `$guarded = []` on models | Allows mass assignment of any field — use `$fillable` |
+| `DB::raw()` with user input | SQL injection — use Eloquent or parameterized queries |
+| `{!! $userInput !!}` | XSS — use `{{ }}` (auto-escaped) |
 | Dynamic code execution functions | Remote code execution risk |
-| `DB::raw()` with user input | SQL injection risk |
-| `{!! $userInput !!}` | XSS — use `{{ }}` instead |
-| Mass assignment without `$fillable` | Uncontrolled field injection |
+| `md5()` / `sha1()` for passwords | Weak hashing — use `Hash::make()` |
+| `unserialize()` on user data | Object injection — use JSON with model casts |
+| CORS `allowed_origins: ['*']` | Open API — restrict to your domain |
+| `createToken('x', ['*'])` | Over-privileged — use specific abilities |
+| Trust `X-Forwarded-For` directly | Spoofable — use trusted proxies config |
+| `$_GET` / `$_POST` / `$_SESSION` | Stale in Octane — use `$request->input()` |
+
+### Backend
+
+| Action | Reason |
+|--------|--------|
 | Business logic in controllers | Move to Service classes |
-| `env()` outside config files | Returns null when config is cached |
 | `static` properties on services | Memory leaks in Octane workers |
 | Global variables / superglobals | Stale state in Octane |
 | `die()` / `exit()` | Kills the Octane worker process |
@@ -113,11 +195,13 @@ project/
 | `migrate:fresh` / `db:wipe` / `db:reset` | Destroys production data |
 | `app()` / `resolve()` in constructors | Use constructor DI instead |
 | `Inertia::render()` after POST/PUT/DELETE | Use `redirect()->route()` instead |
+| `dd()` / `dump()` in production code | Use structured `Log::info()` |
 
 ### Frontend (React)
 
 | Action | Reason |
 |--------|--------|
+| Call external APIs with secrets from JS | Exposes tokens — route through Laravel API |
 | `__()` inside JSX / render | Hook violation — define as CONST before hooks |
 | `fetch()` / `axios` for page data | Bypasses Inertia — use props from controller |
 | `<a href>` for internal links | Full page reload — use `<Link>` |
@@ -160,8 +244,45 @@ $results = DB::select('SELECT * FROM users WHERE id = ?', [$id]);
 
 ## Workflow
 
-1. Create feature branch
-2. Implement with types, strict mode, Octane-safe patterns
-3. Run PHPStan + PHPUnit
-4. Update domains & CLAUDE.md
-5. Commit → merge to main
+```
+0. TODO LIST      → Create detailed todo list from prompt
+1. BRANCH         → Create feature/ | fix/ | refactor/ | test/
+2. RESEARCH       → Run research-web agent for NEW features
+3. IMPLEMENT      → Types, strict mode, Octane-safe, DI
+4. TEST           → Run PHPStan + PHPUnit
+5. DOCUMENT       → Run documenter agent for modified files
+6. UPDATE         → Update THIS FILE (CLAUDE.md) with changes
+7. QUALITY        → PHPStan + PHPUnit + PHP-CS-Fixer
+8. COMMIT         → Conventional commits, merge to main
+```
+
+## Domain Documentation
+
+> Domain docs prevent Claude from re-exploring the codebase every session.
+
+```
+.claude/skills/codebase-knowledge/domains/
+├── authentication.md
+├── api.md
+├── database.md
+├── ui-components.md
+└── [domain-name].md
+```
+
+Each domain file tracks: Files, Connections, Recent Commits, Attention Points, Problems & Solutions.
+
+## Configuration
+
+Project settings in `.claude/config/` (generated by start-vibing-stacks):
+
+- `active-project.json` — Stack, framework, database, skills
+- `domain-mapping.json` — File-to-domain mapping
+- `quality-gates.json` — Quality check commands
+- `testing-config.json` — Test framework config
+- `security-rules.json` — Security audit rules
+- `standards-review.json` — Imported project standards
+
+## Setup by start-vibing-stacks
+
+This project was set up with `npx start-vibing-stacks`.
+For updates: `npx start-vibing-stacks --force`