start-vibing 3.0.7 → 3.0.8

package/template/.claude/CLAUDE.md

@@ -1,125 +1,185 @@
 # Claude Development System - Agent Context
 
-This file provides context for all agents. For user-facing rules, see `/CLAUDE.md`.
+This file provides detailed context for the development system. For user-facing project rules, see `/CLAUDE.md`.
 
 ---
 
-## CLAUDE.md Validation (STOP HOOK ENFORCED)
+## System Architecture
+
+```
+.claude/
+├── agents/          # 6 active subagents (flat structure)
+│   └── _archive/    # 82+ archived agents (unused, kept for reference)
+├── skills/          # 20 skill systems with cache
+├── scripts/         # Utility scripts (validate-skills.sh)
+├── config/          # Project-specific configuration
+└── commands/        # Slash commands (feature, fix, research, validate)
+```
+
+---
+
+## Agents (6 Active Subagents)
+
+| Agent | Model | Color | Purpose |
+|-------|-------|-------|---------|
+| **research-web** | sonnet | cyan | Researches best practices (2024-2026) before implementing new features |
+| **documenter** | sonnet | blue | Maps files to domains, creates/updates domain documentation |
+| **domain-updater** | haiku | purple | Records problems, solutions, gotchas in existing domain files |
+| **commit-manager** | haiku | green | Manages git commits, conventional format, workflow completion |
+| **claude-md-compactor** | sonnet | orange | Compacts CLAUDE.md when it exceeds 40k chars |
+| **tester-unit** | sonnet | yellow | Creates unit tests with Vitest for new functions and utilities |
+
+### Agent -> Skill Mapping
 
-The stop hook validates `/CLAUDE.md` before allowing task completion:
+| Agent | Primary Skill | Secondary |
+|-------|---------------|-----------|
+| research-web | research-cache | codebase-knowledge |
+| documenter | docs-tracker | codebase-knowledge |
+| domain-updater | codebase-knowledge | docs-tracker |
+| commit-manager | workflow-state | docs-tracker |
+| claude-md-compactor | - | - |
+| tester-unit | test-coverage | - |
 
-| Check             | Requirement                                               |
-| ----------------- | --------------------------------------------------------- |
-| Character limit   | Max 40,000 chars                                          |
-| Required sections | Last Change, 30s Overview, Stack, Architecture            |
-| Last Change       | Must be updated with session info (branch, date, summary) |
-| Content depth     | Relevant rule/flow sections must also be updated          |
-| No stacking       | Only ONE Last Change section (latest only)                |
-| Branch            | Must be on main (PR merged)                               |
-| Git tree          | Must be clean (no uncommitted changes)                    |
+### Agent Workflow Order
 
-**If CLAUDE.md exceeds 40k chars:** Compact it by removing verbose explanations, keeping critical sections.
+```
+implement -> quality gates -> domain-updater -> commit-manager -> complete
+```
+
+---
+
+## Skills (20 Active)
+
+Skills are auto-injected into context when the task matches their description. All use the imperative pattern for 95%+ auto-invocation.
+
+### Development Skills
 
-**If not on main:** Complete PR workflow (commit, push, PR, merge, checkout main).
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **bun-runtime** | Bun scripts, packages, bundling | Runtime patterns and best practices |
+| **typescript-strict** | Writing/editing .ts/.tsx files | Strict mode: index access, null checks, generics |
+| **react-patterns** | React components, hooks, state | React 19 patterns and best practices |
+| **nextjs-app-router** | Next.js pages, layouts, server components | App Router patterns, data fetching |
+| **trpc-api** | tRPC routers, procedures, middleware | Type-safe API patterns |
+| **zod-validation** | User input, API params, form data | Zod schemas, type inference |
+| **shadcn-ui** | shadcn/ui components | Theming, accessibility, customization |
+| **tailwind-patterns** | Tailwind CSS classes | Responsive, dark mode, animations |
 
-### Content Depth Rule (CLAUDE_MD_SHALLOW_UPDATE)
+### Quality & Testing Skills
 
-> **"Last Change" = WHAT was done. Other sections = HOW things work NOW. Both MUST be current.**
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **quality-gate** | Before any commit | Runs typecheck, lint, test, build in sequence |
+| **security-scan** | API, auth, user data code | OWASP Top 10, Zod validation (HAS VETO POWER) |
+| **test-coverage** | After implementing features | Creates Vitest unit + Playwright E2E tests |
+| **final-check** | Before completing any task | Validates skills used, docs updated (HAS VETO POWER) |
 
-The stop-validator categorizes changed files and maps them to CLAUDE.md sections:
+### Infrastructure & DevOps Skills
 
-| Changed Files | Must Also Update |
-|---------------|-----------------|
-| API/CRUD routes | Critical Rules, HTTP Requests |
-| UI components | UI Architecture, Component Organization |
-| Pages/layouts | Architecture, Next.js App Router Patterns |
-| Styling/aesthetics | UI Architecture, Design System |
-| Auth/middleware | Critical Rules, Workflow |
-| Database/models | Architecture, Critical Rules |
-| Config files | Stack, Configuration |
-| Hooks/scripts | Workflow, Stop Hook Validations |
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **docker-patterns** | Dockerfile, docker-compose | Multi-stage builds, security patterns |
+| **git-workflow** | Git operations | Commit, branch, merge workflow rules |
+| **performance-patterns** | Slow app, optimization needed | React renders, bundle size, memory leaks |
+| **debugging-patterns** | Errors, stack traces, bugs | Runtime, build, and network error resolution |
 
-If ONLY "Last Change" was modified but **significant** categorized source files changed, `CLAUDE_MD_SHALLOW_UPDATE` blocks completion.
+### Documentation & Research Skills
 
-**Exempt (minor changes):** < 3 categorized files AND < 30 lines changed AND no new files = Last Change only is OK.
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **codebase-knowledge** | Before implementing features | Maps files by domain, tracks connections |
+| **docs-tracker** | After implementation | Detects modified files, creates/updates docs |
+| **research-cache** | Before web research | Checks cached findings to avoid redundant searches |
+| **ui-ux-audit** | Before UI features | Competitors, WCAG 2.1, responsiveness |
 
 ---
 
-## System Architecture
+## Plugins (5 via enabledPlugins)
 
-```
-.claude/
-├── agents/          # 6 active subagents (flat structure)
-│   └── _archive/    # 82+ archived agents (unused, kept for reference)
-├── skills/          # 23 skill systems with cache
-├── scripts/         # Validation scripts (validate-claude-md.ts)
-├── config/          # Project-specific configuration
-├── commands/        # Slash commands (feature, fix, research, validate)
-└── hooks/           # stop-validator.ts, user-prompt-submit.ts
-```
+Plugins are auto-installed via `enabledPlugins` in settings.json. They replaced archived agents.
+
+| Plugin | Mechanism | Purpose | Replaces |
+|--------|-----------|---------|----------|
+| **typescript-lsp** | LSP server (auto) | Type diagnostics, go-to-def | ts-strict-checker agent |
+| **security-guidance** | PreToolUse hook (auto) | OWASP, vulnerability scan | security-auditor agent |
+| **code-review** | `/code-review` command | Code quality, PR analysis | code-reviewer agent |
+| **commit-commands** | `/commit` command | Git commit, push, PR flows | commit-manager (PR part) |
+| **frontend-design** | `/frontend-design` command | Production-grade UI design | ui-ux-reviewer agent |
 
 ---
 
-## MCP Servers
+## UI/UX Development (Mandatory Review Process)
+
+Any task that touches UI code (`.tsx`, `.jsx`, components, pages, layouts) requires:
+
+### Required Tools
 
-Available MCP servers and their usage:
+| Tool | Purpose | When |
+|------|---------|------|
+| **`/frontend-design` plugin** | Production-grade UI design with high design quality | Before implementing ANY UI feature |
+| **ui-ux-audit skill** | Competitor research, WCAG 2.1 accessibility, responsive audit | Before UI implementation |
+| **Playwright MCP** | Visual verification across viewports (375px, 768px, 1280px+) | After UI implementation |
 
-| Server                | Purpose                            | Used By                                  |
-| --------------------- | ---------------------------------- | ---------------------------------------- |
-| `context7`            | Up-to-date library documentation   | research-web agent, direct use           |
-| `sequential-thinking` | Complex problem-solving            | Direct use for planning                  |
-| `memory`              | Persistent knowledge graph         | domain-updater agent, direct use         |
-| `playwright`          | Browser automation (`--user-data-dir` for persistent sessions) | Direct use for E2E testing  |
-| `nextjs-devtools`     | Next.js specific development tools | Direct use in Next.js projects           |
-| `mongodb`             | MongoDB database operations        | Direct use for DB queries                |
+### UI Review Workflow
+
+```
+1. Research competitors (ui-ux-audit skill)
+2. Design with /frontend-design plugin
+3. Implement separate layouts for mobile/tablet/desktop
+4. Verify with Playwright MCP (all 3 viewports)
+5. Validate WCAG 2.1 accessibility
+```
 
-### MCP Usage Rules
+### Platform-Specific UIs (NOT just responsive)
 
-- Use `context7` before implementing features with external libraries
-- Use `memory` to persist patterns across sessions
-- Use `playwright` for E2E testing (sessions persist via `--user-data-dir`)
-- Plugins handle security (security-guidance hook) and types (typescript-lsp) automatically
+| 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        |
+
+> Never use "responsive-only" design. Build separate UI layouts per platform.
 
 ---
 
-## Configuration Files
+## MCP Servers (Strict Usage Rules)
 
-Project-specific settings are in `.claude/config/`:
+### Required MCPs (ALWAYS use these)
 
-| File                  | Purpose                        |
-| --------------------- | ------------------------------ |
-| `project-config.json` | Stack, structure, commands     |
-| `domain-mapping.json` | File patterns to domains       |
-| `quality-gates.json`  | Quality check commands         |
-| `testing-config.json` | Test framework and conventions |
-| `security-rules.json` | Security audit rules           |
+| Server | Purpose | When to Use |
+|--------|---------|-------------|
+| `context7` | Up-to-date library documentation | **ALWAYS** before implementing with ANY library. Never assume docs -- always query. |
+| `sequential-thinking` | Structured reasoning and planning | **ALWAYS** for multi-step tasks, architecture decisions, debugging complex issues, and planning implementations. Use before writing code for non-trivial features. |
+| `playwright` | Browser automation and E2E testing | **ALWAYS** for UI verification, E2E tests, and visual validation. Uses `--user-data-dir` for persistent sessions. Every UI change must be tested in browser. |
 
-**RULE:** Agents MUST read config files before acting. Do NOT hardcode project specifics.
+> These 3 MCPs are **non-negotiable**. Skipping them leads to outdated code, poor planning, and untested UIs.
 
----
+### Standard MCPs
 
-## Agent → Skill Mapping
+| Server | Purpose | When to Use |
+|--------|---------|-------------|
+| `memory` | Persistent knowledge graph | Store/recall project patterns across sessions |
+| `nextjs-devtools` | Next.js development tools | Next.js projects (runtime errors, routes, cache) |
+| `mongodb` | MongoDB database operations | DB queries, schema inspection |
+| `jira` | Issue tracking | Pull tasks, create issues, update status |
+| `git` | Git operations | Repo search, history, diffs |
+| `fetch` | Web page reading | Fetch URLs as markdown |
 
-### Active Subagents (6)
+---
 
-| Agent              | Primary Skill      | Secondary          |
-| ------------------ | ------------------ | ------------------ |
-| research-web       | research-cache     | codebase-knowledge |
-| documenter         | docs-tracker       | codebase-knowledge |
-| domain-updater     | codebase-knowledge | docs-tracker       |
-| commit-manager     | workflow-state     | docs-tracker       |
-| claude-md-compactor| -                  | -                  |
-| tester-unit        | test-coverage      | -                  |
+## Configuration Files
 
-### Plugins (replace archived agents)
+Project-specific settings in `.claude/config/`:
 
-| Plugin             | Replaces Old Agent  | Mechanism         |
-| ------------------ | ------------------- | ----------------- |
-| security-guidance  | security-auditor    | PreToolUse hook   |
-| typescript-lsp     | ts-strict-checker   | LSP server        |
-| code-review        | code-reviewer       | /code-review cmd  |
-| frontend-design    | ui-ux-reviewer      | /frontend-design  |
-| commit-commands    | commit-manager (PR) | /commit cmd       |
+| File | Purpose |
+|------|---------|
+| `project-config.json` | Stack, structure, commands |
+| `domain-mapping.json` | File patterns to domains |
+| `quality-gates.json` | Quality check commands |
+| `testing-config.json` | Test framework and conventions |
+| `security-rules.json` | Security audit rules |
+
+Agents read config files before acting. Do NOT hardcode project specifics.
 
 ---
 
@@ -127,7 +187,7 @@ Project-specific settings are in `.claude/config/`:
 
 ### Before ANY implementation:
 
-1. **Read config** from `.claude/config/` for project specifics
+1. Read config from `.claude/config/` for project specifics
 2. Read relevant skill SKILL.md file
 3. Check skill cache for existing data
 4. Research if needed (research-web agent or web search)
@@ -135,10 +195,32 @@ Project-specific settings are in `.claude/config/`:
 ### After implementation:
 
 1. Update skill cache with changes
-2. Run quality gates (bun run typecheck && lint && test)
-3. Security handled automatically by security-guidance plugin (PreToolUse hook)
-4. **Update domains** via domain-updater agent (BEFORE commit, keeps git clean)
-5. **Commit** via commit-manager agent (FINAL step)
+2. Run quality gates (`bun run typecheck && lint && test`)
+3. Security handled automatically by security-guidance plugin
+4. Update domains via domain-updater agent
+5. **Update CLAUDE.md** with architecture/rule changes (see rule below)
+6. Commit via commit-manager agent (FINAL step)
+
+---
+
+## CLAUDE.md Update Rule (POST-IMPLEMENTATION)
+
+After completing any implementation or change that modifies architecture, rules, or conventions:
+
+1. **Update `/CLAUDE.md`** -- The root project CLAUDE.md must reflect current state
+2. **What to update:**
+   - `Last Change` section with branch, date, summary
+   - Any section affected by the changes (Architecture, Rules, Stack, etc.)
+   - New patterns, gotchas, or conventions discovered
+3. **What counts as "architecture change":**
+   - New files/folders added to the project structure
+   - New dependencies or tools added
+   - Workflow changes
+   - New API routes, pages, or components
+   - Configuration changes
+   - Any change that a future Claude session would need to know about
+4. **Format:** Keep it concise. Tables and bullet points over prose.
+5. **Character limit:** Max 40,000 chars. If exceeded, invoke claude-md-compactor agent.
 
 ---
 
@@ -191,40 +273,15 @@ api.interceptors.response.use(
 | Type responses | `api.get<UserResponse>('/users')` |
 | Handle errors centrally | Use interceptors, not try/catch everywhere |
 
-### When to Create API Wrapper
-
-```typescript
-// If you call the same endpoint multiple times, create a wrapper:
-// lib/api/users.ts
-export const usersApi = {
-  getAll: () => api.get<User[]>('/users'),
-  getById: (id: string) => api.get<User>(`/users/${id}`),
-  create: (data: CreateUser) => api.post<User>('/users', data),
-  update: (id: string, data: UpdateUser) => api.patch<User>(`/users/${id}`, data),
-  delete: (id: string) => api.delete(`/users/${id}`),
-};
-```
-
-### FORBIDDEN
-
-| Don't | Do Instead |
-|-------|------------|
-| `fetch('/api/...')` | `api.get('/...')` |
-| `axios.get(...)` | `api.get(...)` |
-| `withCredentials: false` | Always `true` |
-| Inline error handling | Use interceptors |
-
 ---
 
 ## Enforcement Mechanisms
 
-What blocks the flow if rules are violated:
-
-| Mechanism                   | Type           | Blocks When                                         |
-| --------------------------- | -------------- | --------------------------------------------------- |
-| **security-guidance plugin** | PreToolUse hook | Sensitive data exposure, missing validation, OWASP   |
-| **stop-validator hook**      | Stop hook       | Branch not main, uncommitted changes, docs missing   |
-| **quality gates**            | Manual / CI     | Typecheck, lint, or test failures                    |
+| Mechanism | Type | Blocks When |
+|-----------|------|-------------|
+| **security-guidance plugin** | PreToolUse hook (auto) | Sensitive data exposure, missing validation, OWASP |
+| **quality gates** | Manual / CI | Typecheck, lint, or test failures |
+| **final-check skill** | Skill (manual) | Any rule violated, tests failing, docs missing |
 
 ---
 
@@ -236,178 +293,594 @@ All implementations MUST:
 - [ ] Pass lint (`bun run lint`)
 - [ ] Pass unit tests (`bun run test`)
 - [ ] Pass build (`bun run build`)
-- [ ] Use Playwright MCP for browser testing when needed
 - [ ] Have documentation updated (documenter agent)
-- [ ] Security validated by security-guidance plugin (automatic via hook)
+- [ ] Security validated by security-guidance plugin (automatic)
 - [ ] Be committed with conventional commits
 - [ ] Have domains updated with session learnings (domain-updater agent)
+- [ ] Have CLAUDE.md updated with architecture/rule changes
 
 ---
 
-## Claude 4.6 Best Practices
+## Domain Documentation
 
-> **Source:** [Anthropic Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+Domain docs prevent Claude from re-exploring the codebase every session.
 
-### Model Selection
+### Location
 
-| Model | API ID | Cost (In/Out) | Best For |
-|-------|--------|---------------|----------|
-| **Opus 4.6** | `claude-opus-4-6` | $5/$25 MTok | Orchestrators, long-horizon tasks, 128K output |
-| **Sonnet 4.6** | `claude-sonnet-4-6` | $3/$15 MTok | Daily coding, teammates (5x cheaper) |
-| **Haiku 4.5** | `claude-haiku-4-5-20251001` | $1/$5 MTok | Classification, simple tasks |
+```
+.claude/skills/codebase-knowledge/domains/
+├── claude-system.md    # This development system
+├── authentication.md
+├── api.md
+├── ui-components.md
+└── ...
+```
 
-### Effort Levels
+### Domain Mapping
 
-| Level | Behavior | Use Case |
-|-------|----------|----------|
-| `max` | Always thinks, no limits | Complex architecture (**Opus ONLY**) |
-| `high` | Deep thinking (DEFAULT) | Agentic tasks, complex coding |
-| `medium` | Moderate, may skip simple | Most workloads |
-| `low` | Minimal thinking | Subagents, teammates, high-volume |
+Configured in `.claude/config/domain-mapping.json`:
 
-**CLI:** `/model` then arrow keys to adjust effort.
+| Domain | File Patterns |
+|--------|---------------|
+| authentication | `**/auth/**`, `**/*auth*.ts` |
+| api | `**/api/**`, `**/routers/**` |
+| database | `**/models/**`, `**/*.model.ts` |
+| ui-components | `**/components/**/*.tsx` |
+| pages | `**/app/**/page.tsx` |
 
-### Adaptive Thinking (Replaces budget_tokens)
+### Documentation Agents
 
-```typescript
-// CORRECT for 4.6 models
-thinking: { type: "adaptive" },
-output_config: { effort: "medium" }
+| Agent | Role | When |
+|-------|------|------|
+| **documenter** | Maps files to domains, creates/updates domain files | AFTER implementation |
+| **domain-updater** | Records problems, solutions, gotchas | BEFORE commit |
+
+---
+
+## FORBIDDEN Actions
+
+| Action                         | Reason                       |
+| ------------------------------ | ---------------------------- |
+| Write in non-English           | ALL code/docs MUST be in EN  |
+| Skip typecheck                 | Catches runtime errors       |
+| Relative imports (shared)      | Breaks when files move       |
+| Use `@types/` alias            | Reserved by TypeScript       |
+| Use `any` type                 | Defeats strict mode          |
+| Skip docker build test         | May fail in production       |
+| Define types in `src/`         | Must be in `types/`          |
+| Skip research for new features | Leads to outdated patterns   |
+| Skip todo list creation        | Loses track of tasks         |
+| Make responsive UI only        | Must be separate UIs         |
+| Commit directly to main        | Create feature/fix branches  |
+| Skip documenter agent          | Documentation is mandatory   |
+| Leave files undocumented       | Domain docs prevent re-exploration |
+| Stack Last Change entries      | Keep only the LATEST         |
+| Use Cards on mobile            | Waste space in flex-col      |
+| Edit JSX without UI review     | Use frontend-design plugin or research competitors |
+| Skip planning for features     | Use EnterPlanMode first      |
+| Skip domain documentation      | MUST update domains/*.md     |
+| Only update CLAUDE.md          | Domains are detail, CLAUDE.md is summary |
+| Skip flow documentation        | Document architecture changes in CLAUDE.md |
+| Use MUI/Chakra                 | Use shadcn/ui + Radix for personality control |
+| Neumorphism on forms           | Accessibility issues, use Glassmorphism |
+| Scroll animations on dashboard | Use only on landing/marketing pages |
+| 3D elements on mobile          | Performance issues, use sparingly |
+| Masonry grid on mobile         | Use vertical lists instead |
+| Mix animation libraries        | Pick one primary (Framer or GSAP) |
+| Wildcard icon imports          | Use named imports (`import { X } from 'lucide-react'`) |
+| React Icons in production      | Use Lucide + Simple Icons directly |
+| Files > 400 lines              | MUST split into smaller components |
+| Page components in /components | Use `app/[page]/_components/` |
+| Skip cn utility                | MUST use clsx + tailwind-merge |
+| 'use client' at top level      | Push to leaf components only |
+| Waterfall data fetching        | Use Promise.all() for parallel |
+| Skip loading.tsx               | Add skeleton loaders for data pages |
+| Skip CLAUDE.md update          | MUST update after implementations |
+
+---
+
+## UI Architecture (MANDATORY)
+
+> Web apps MUST have **separate UIs** for each platform, NOT just "responsive design".
 
-// DEPRECATED (will be removed)
-thinking: { type: "enabled", budget_tokens: 10000 }
+| 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        |
+
+### JSX Editing = UI Review (MANDATORY)
+
+ANY task that edits `.tsx` or `.jsx` files MUST consider all 3 viewports:
+
+- Use `/frontend-design` plugin for production-grade UI
+- Design separate layouts for mobile (375px), tablet (768px), desktop (1280px+)
+- Research competitor UIs before implementing new features
+
+---
+
+## UI/UX Design Rules
+
+### Mobile FORBIDDEN Patterns
+
+| Pattern | Problem | Use Instead |
+|---------|---------|-------------|
+| Cards in flex-col | Waste vertical space, poor scanning | Compact lists with dividers |
+| Card grids | Too cramped, hard to tap | Full-width list items |
+| Nested cards | Confusing hierarchy | Flat structure |
+| Multiple CTAs per card | Touch confusion | Single primary action |
+
+### Design Principles
+
+| Platform | Density | Navigation | Actions |
+|----------|---------|------------|---------|
+| Mobile | LOW - space for touch | Bottom tab bar | Bottom sheet |
+| Tablet | MEDIUM - hybrid | Side + top | Context menus |
+| Desktop | HIGH - data dense | Fixed sidebar | Inline + hover |
+
+### Component Choices
+
+```
+Mobile:   Lists > Cards, Sheets > Modals, Tabs > Dropdowns
+Tablet:   Collapsible cards, Split views, Floating actions
+Desktop:  Data tables, Multi-column forms, Keyboard shortcuts
 ```
 
-Adaptive thinking enables **interleaved thinking** — Claude reasons BETWEEN tool calls.
+---
 
-### Prompting Rules (CRITICAL)
+## Design System Reference
 
-**AVOID (causes overtriggering):**
-- "CRITICAL: You MUST use..."
-- "be thorough", "think carefully", "do not be lazy"
-- "use the think tool to plan your approach"
+> **Full docs in**: `.claude/skills/research-cache/cache/` (12 detailed files)
 
-**USE INSTEAD:**
-- "Use this tool when..." (softer language)
-- Remove anti-laziness prompts entirely
-- Lower effort level instead of adding constraints
+### Required Libraries
 
-**Why:** Opus 4.6 does MORE upfront exploration than older models. Anti-laziness prompts cause runaway thinking.
+```bash
+# Core utilities (MANDATORY)
+bun add clsx tailwind-merge class-variance-authority
+bun add -D tailwindcss-animate
 
-### Tool Use Patterns
+# Animation & feedback
+bun add @formkit/auto-animate framer-motion sonner
 
-```text
-# Claude will only SUGGEST:
-"Can you suggest some changes?"
+# Skeleton loaders
+bun add react-loading-skeleton
 
-# Claude will IMPLEMENT:
-"Change this function to improve performance."
+# Copy-paste from: magicui.design, ui.aceternity.com, hover.dev
 ```
 
-For proactive action by default, add to system prompt:
-```text
-By default, implement changes rather than only suggesting them.
+### The `cn` Utility (MANDATORY)
+
+```typescript
+// lib/utils.ts - MUST HAVE in every project
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));
 ```
 
-### Subagent Control
+---
 
-Opus 4.6 has a **strong predilection for subagents** — may spawn them when direct grep/read is faster.
+## Icon Libraries (MANDATORY)
 
-**Use subagents when:** Parallel tasks, isolated context, independent workstreams
-**Work directly when:** Sequential operations, single-file edits, shared state needed
+| Library | Use For | Icons | Import |
+|---------|---------|-------|--------|
+| **Lucide React** | UI icons (shadcn default) | 1,600+ | `import { Camera } from 'lucide-react'` |
+| **Simple Icons** | Brand logos ONLY | 3,150+ | `import { SiReact } from '@icons-pack/react-simple-icons'` |
 
-```text
-# Add if seeing excessive subagent use:
-For simple tasks, sequential operations, or single-file edits, work directly.
+```typescript
+// CORRECT: Named imports (tree-shakable, ~1KB per icon)
+import { Camera, User, Settings } from 'lucide-react';
+
+// FORBIDDEN: Wildcard imports (bundles ALL icons, +30KB)
+import * as Icons from 'lucide-react';
 ```
 
-### Avoid Over-Engineering
+---
+
+## Aesthetic Libraries
+
+| Library | Purpose | When |
+|---------|---------|------|
+| **clsx + tailwind-merge** | className management | ALWAYS |
+| **class-variance-authority** | Component variants | Reusable components |
+| **tailwindcss-animate** | Micro-interactions | Animations |
+| **react-loading-skeleton** | Loading states | Data fetching |
+
+---
 
-Opus 4.6 tends to create extra files and unnecessary abstractions.
+## Component Organization (MANDATORY)
 
-```text
-# Add to prompt:
-Avoid over-engineering. Only make changes directly requested.
-Don't add features, docstrings, or error handling beyond what's asked.
+### Component Location Rules
+
+| 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, Footer)? | `components/layout/` |
+
+### File Size Rules
+
+| Lines | Action |
+|-------|--------|
+| < 200 | Keep in single file |
+| 200-400 | Consider splitting |
+| > 400 | **MUST split** into smaller components |
+
+---
+
+## Next.js App Router Patterns (MANDATORY)
+
+### Server vs Client Components
+
+```tsx
+// DEFAULT: Server Component (no directive needed)
+export default async function Page({ params }) {
+  const data = await fetch('...');
+  return <ClientButton data={data} />;
+}
+
+// Client Component (push to leaves)
+'use client';
+export function ClientButton({ data }) {
+  const [state, setState] = useState();
+  return <button onClick={() => setState(!state)}>{data}</button>;
+}
 ```
 
-### Parallel Tool Calls
+### Layout Context Pattern
+
+```tsx
+// app/layout.tsx - Root layout with providers
+import { Providers } from '@/components/providers';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+
+// components/providers.tsx - Client-side providers
+'use client';
+export function Providers({ children }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider>
+        {children}
+        <Toaster />
+      </ThemeProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### Parallel Data Fetching
+
+```tsx
+// CORRECT: Parallel fetches
+const [user, posts] = await Promise.all([getUser(), getPosts()]);
 
-```text
-# Add for maximum efficiency:
-If calling multiple tools with no dependencies, make all calls in parallel.
+// AVOID: Waterfall (sequential)
+const user = await getUser();
+const posts = await getPosts();  // Waits for user
 ```
 
-### Cost Control
+---
+
+## Grid Layouts (Choose by Context)
+
+| Grid Type | Use For | Mobile |
+|-----------|---------|--------|
+| **Bento Grid** | Landing, features, portfolios | Stacks vertically |
+| **12-Column** | Dashboards, admin panels | Collapse to 1-2 cols |
+| **Masonry** | Galleries, Pinterest-style | Use vertical list |
+| **Card Grid** | Products, team, blog archive | Stack to single col |
+| **Split Grid** | Hero sections, auth pages | Stack vertically |
+| **Kanban** | Project management, tasks | Horizontal scroll |
+
+> **Cache**: `grid-layout-patterns-2025.md`
+
+---
+
+## Modal/Dialog Patterns (Choose by Action)
+
+| Modal Type | Use For | Mobile |
+|------------|---------|--------|
+| **Centered Dialog** | Confirmations, short forms | Full-screen |
+| **Slide-over/Drawer** | Filters, settings, details | Bottom sheet |
+| **Bottom Sheet** | Actions, sharing, quick forms | Native feel |
+| **Command Palette** | CMD+K, power users | Full-screen |
+| **Wizard/Stepper** | Multi-step forms, onboarding | Full-screen |
+| **Lightbox** | Images, videos | Full-screen |
+
+> **Cache**: `modal-dialog-design-patterns-2024-2025.md`
+
+---
+
+## List Patterns (Choose by Data)
+
+| List Type | Use For | Key Feature |
+|-----------|---------|-------------|
+| **Simple List** | Basic items, settings | Dividers |
+| **Avatar List** | Users, contacts | Profile images |
+| **Expandable/Accordion** | FAQs, nested content | Collapse/expand |
+| **Swipeable List** | Mobile actions | Left/right swipe |
+| **Drag & Drop** | Reordering | dnd-kit (NOT react-beautiful-dnd) |
+| **Virtualized** | 1000+ items | react-window or react-virtuoso |
+| **Timeline** | Activity feed, history | Vertical line |
+| **Chat/Messages** | Conversations | Bubbles left/right |
 
-| Issue | Solution |
-|-------|----------|
-| Runaway thinking | Lower effort (not prompt constraints) |
-| `stop_reason: "max_tokens"` | Increase `max_tokens` to 64K+ |
-| High costs | Use `low` effort for subagents |
-| Billing confusion | Billed for FULL thinking, not visible summary |
+> **Cache**: `list-design-patterns-web-apps.md`
 
-### Common Pitfalls
+---
+
+## Multi-Step Forms (MANDATORY for complex forms)
 
-| Pitfall | Fix |
-|---------|-----|
-| `max` effort on Sonnet/Haiku | Error — Opus only |
-| Prefilled responses | Deprecated in 4.6 |
-| Multiple agents editing same file | Isolate files per agent |
-| Aggressive prompts from older models | Remove "MUST", "CRITICAL" |
+| Pattern | Use For | Progress |
+|---------|---------|----------|
+| **Horizontal Stepper** | Onboarding, checkout | Numbers at top |
+| **Card-based Steps** | Settings, profiles | Expandable cards |
+| **Slide Animation** | Typeform-style | Left/right slide |
+| **Accordion Steps** | Long forms | Collapsible sections |
 
-### API Examples
+### Form Stack (MANDATORY)
 
 ```typescript
-// Standard agentic call
-await client.messages.create({
-  model: "claude-opus-4-6",
-  max_tokens: 64000,
-  thinking: { type: "adaptive" },
-  output_config: { effort: "high" },
-  messages: [...]
+// react-hook-form + Zod + per-step validation
+const { trigger } = useForm<FormData>({ resolver: zodResolver(schema) });
+
+const nextStep = async () => {
+  const isValid = await trigger(currentStepFields);
+  if (!isValid) return;
+  setStep(step + 1);
+};
+```
+
+> **Cache**: `multi-step-form-patterns.md`
+
+---
+
+## Toast Notifications (MANDATORY: Sonner)
+
+```typescript
+// Install: pnpm dlx shadcn@latest add sonner
+import { toast } from "sonner";
+
+// Promise-based (loading -> success/error)
+toast.promise(saveData(), {
+  loading: 'Saving...',
+  success: 'Saved!',
+  error: 'Failed to save',
 });
 
-// Cost-optimized subagent
-await client.messages.create({
-  model: "claude-sonnet-4-6",
-  max_tokens: 16000,
-  thinking: { type: "adaptive" },
-  output_config: { effort: "low" },
-  messages: [...]
+// With action button
+toast('File deleted', {
+  action: { label: 'Undo', onClick: () => restoreFile() },
 });
 ```
 
+> **Duration**: 4s info, 7s+ errors. Max 3-5 visible toasts.
+
+> **Cache**: `react-toast-notifications.md`
+
 ---
 
-## Domain Updater Agent
+## Optimistic UI (MANDATORY for mutations)
 
-The **domain-updater** runs BEFORE commit-manager to ensure git stays clean.
+> Show instant feedback, rollback on error.
 
-### Purpose
+### Pattern 1: useOptimistic (React 19)
 
-- Document **problems encountered** during the session
-- Record **solutions** applied to fix issues
-- Add **prevention tips** for future sessions
-- Update **attention points** with new learnings
-- Keep domain knowledge **current and accurate**
+```typescript
+const [optimisticItems, addOptimistic] = useOptimistic(
+  items,
+  (state, newItem) => [...state, { ...newItem, pending: true }]
+);
 
-### Trigger
+async function addItem(data: ItemData) {
+  addOptimistic(data);  // Instant UI update
+  try {
+    await api.post('/items', data);
+  } catch {
+    toast.error('Failed to add');
+    // State auto-reverts
+  }
+}
+```
 
-Runs in the workflow:
+### Pattern 2: TanStack Query
+
+```typescript
+useMutation({
+  mutationFn: updateItem,
+  onMutate: async (newData) => {
+    await queryClient.cancelQueries({ queryKey: ['items'] });
+    const previous = queryClient.getQueryData(['items']);
+    queryClient.setQueryData(['items'], (old) =>
+      old.map(item => item.id === newData.id ? { ...item, ...newData } : item)
+    );
+    return { previous };
+  },
+  onError: (err, vars, context) => {
+    queryClient.setQueryData(['items'], context.previous); // Rollback
+    toast.error('Update failed');
+  },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
+});
+```
+
+> **Cache**: `optimistic-ui-patterns-react.md`
+
+---
 
-1. AFTER implementation and quality gates pass
-2. BEFORE commit-manager (so changes are included in commit)
-3. Stop hook blocks session end until domains are updated (if source files were modified)
+## Data Display Patterns
+
+### Tables
+
+| Style | Use For |
+|-------|---------|
+| **Striped rows** | Long lists, scanning |
+| **Sticky header** | Scrollable data |
+| **Expandable rows** | Details on demand |
+| **Sortable columns** | Data comparison |
+| **Virtualized** | 1000+ rows (TanStack Virtual) |
+
+### Cards
+
+| Style | Use For |
+|-------|---------|
+| **Stats/KPI Card** | Metrics with trends |
+| **Product Card** | E-commerce listings |
+| **Profile Card** | User information |
+| **Interactive Card** | Hover effects, animations |
+
+> **Cache**: `data-display-patterns-2024-2025.md`
+
+---
+
+## Navigation Patterns
+
+| Type | Desktop | Mobile |
+|------|---------|--------|
+| **Header** | Fixed top navbar | Hamburger menu |
+| **Sidebar** | Fixed left, collapsible | Overlay drawer |
+| **Tabs** | Horizontal tabs | Bottom tab bar |
+| **Breadcrumbs** | Path navigation | Simplified |
+
+> **Cache**: `navigation-header-design-patterns-2025.md`
+
+---
 
-### Workflow Order
+## Animation Libraries
 
+| Library | Use When | Bundle |
+|---------|----------|--------|
+| **AutoAnimate** | 90% of UI (lists, tabs, dropdowns) | Minimal |
+| **Framer Motion** | Page transitions, gestures, layouts | 32KB |
+| **GSAP** | Scroll-driven, complex timelines | 23KB |
+| **Magic UI** | Landing pages, marketing | Copy-paste |
+| **Aceternity UI** | Portfolios, 3D effects | Copy-paste |
+
+---
+
+## Design Trends (2025)
+
+| Trend | Use For | Avoid |
+|-------|---------|-------|
+| **Glassmorphism** | Modals, overlays, dark mode | Light backgrounds |
+| **Minimalism** | Mobile, SaaS, accessibility | Marketing sites |
+| **Bold Typography** | Landing hero, brands | Data dashboards |
+
+---
+
+## Mandatory Planning
+
+> Use `EnterPlanMode` for non-trivial tasks BEFORE implementing.
+
+| Task Type | Plan Required |
+|-----------|---------------|
+| New feature | YES |
+| UI changes (any JSX) | YES |
+| Multi-file changes | YES |
+| Bug fix (simple) | NO |
+| Single-line fix | NO |
+
+### Plan Format
+
+```
+1. Analyze current state
+2. Identify affected files
+3. Design approach (with alternatives)
+4. Get user approval
+5. THEN implement
+```
+
+---
+
+## Critical Rules
+
+### Path Aliases (MANDATORY)
+
+| Alias      | Maps To             | Use For       |
+| ---------- | ------------------- | ------------- |
+| `$types/*` | `./types/*`         | Type defs     |
+| `@common`  | `./common/index.ts` | Logger, utils |
+| `@db`      | `./common/db/`      | DB connection |
+
+> **NEVER** use `@types/` (reserved by TypeScript)
+
+### Types Location
+
+- **ALL** interfaces/types MUST be in `types/` folder
+- **NEVER** define types in `src/` files
+- **EXCEPTION:** Zod inferred types and Mongoose Documents
+
+### TypeScript Strict
+
+```typescript
+process.env['VARIABLE']; // CORRECT (bracket notation)
+source: 'listed' as const; // CORRECT (literal type)
+```
+
+---
+
+## Quality Gates
+
+```bash
+bun run typecheck     # MUST pass
+bun run lint          # MUST pass
+bun run test          # MUST pass
+docker compose build  # MUST pass
+bash .claude/scripts/validate-skills.sh  # Skills activation check
 ```
-implement → quality gates → domain-updater → commit-manager → complete-task
-                                  ↑                  ↑
-                         (updates domains)  (commits all changes)
+
+---
+
+## Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
 ```
 
-### Configuration
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`
+
+---
 
-Reads domain patterns from `.claude/config/domain-mapping.json`
+## NRY (Never Repeat Yourself)
+
+Common Claude mistakes to avoid:
+
+- Multi-line bash with `\` continuations (breaks permissions)
+- Relative paths in permission patterns
+- Executing agent logic manually (use Task tool)
+- Using bash for file operations (use Read/Write/Edit)
+- Ignoring context size (use `/compact`)
+
+---
+
+## Claude 4.6 Best Practices
+
+### Model Selection
+
+| Model | API ID | Best For |
+|-------|--------|----------|
+| **Opus 4.6** | `claude-opus-4-6` | Orchestrators, long-horizon tasks |
+| **Sonnet 4.6** | `claude-sonnet-4-6` | Daily coding (5x cheaper) |
+| **Haiku 4.5** | `claude-haiku-4-5-20251001` | Simple tasks |
+
+### Key Rules
+
+- Use adaptive thinking (`thinking: { type: "adaptive" }`)
+- Avoid aggressive prompts ("MUST", "CRITICAL") -- causes overtriggering
+- Lower effort level instead of adding constraints
+- Use subagents for parallel tasks, work directly for sequential
+- Avoid over-engineering -- only make requested changes