start-vibing 3.0.10 → 4.0.0

package/template/.claude/CLAUDE.md

@@ -1,901 +1,367 @@
-# Claude Development System - Agent Context
-
-This file provides detailed context for the development system. For user-facing project rules, see `/CLAUDE.md`.
-
----
-
-## System Architecture
-
-```
-.claude/
-├── agents/          # 6 active subagents (flat structure)
-├── skills/          # 26 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
-
-| 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 | - |
-
-### Agent Workflow Order
-
-```
-implement -> quality gates -> domain-updater -> commit-manager -> complete
-```
-
----
-
-## Skills (26 Active)
-
-Skills are auto-injected into context when the task matches their description. All use the imperative pattern for 95%+ auto-invocation.
-
-### Development Skills
-
-| 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 |
-
-### Quality & Testing Skills
-
-| 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) |
-| **playwright-testing** | Playwright E2E tests | Page Objects, fixtures, multi-viewport patterns |
-| **test-infrastructure** | Test configs, data factories | Vitest config, MongoMemoryServer, cleanup |
-
-### Database Skills
-
-| Skill | Trigger | Description |
-|-------|---------|-------------|
-| **mongoose-patterns** | Mongoose models, queries, DB ops | Schema template, ESR indexes, aggregation, seeders |
-
-### Infrastructure & DevOps Skills
-
-| 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 |
-
-### Documentation & Research Skills
-
-| 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 |
-| **api-docs** | After API/function changes | API docs, JSDoc, changelog management |
-
-### Meta & SEO Skills
-
-| Skill | Trigger | Description |
-|-------|---------|-------------|
-| **skill-creator** | Creating/editing skills | Interview, draft, test, iterate loop (from anthropics/skills) |
-| **claude-seo** | SEO analysis, audits, sitemaps | Full SEO suite with health scoring (from AgriciDaniel/claude-seo) |
-
----
-
-## Plugins (5 via enabledPlugins)
-
-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 |
-
----
-
-## UI/UX Development (Mandatory Review Process)
-
-Any task that touches UI code (`.tsx`, `.jsx`, components, pages, layouts) requires:
-
-### Required Tools
-
-| 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 |
-
-### 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
-```
-
-### Platform-Specific UIs (NOT just responsive)
-
-| 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.
-
----
-
-## MCP Servers (Strict Usage Rules)
-
-### Required MCPs (ALWAYS use these)
-
-| 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. |
-
-> These 3 MCPs are **non-negotiable**. Skipping them leads to outdated code, poor planning, and untested UIs.
-
-### Standard MCPs
-
-| 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 |
-
----
-
-## Configuration Files
-
-Project-specific settings in `.claude/config/`:
-
-| 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.
-
----
-
-## Execution Protocol
-
-### Before ANY implementation:
-
-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)
-
-### 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
-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.
-
----
-
-## HTTP Requests (MANDATORY)
-
-All HTTP requests MUST use **axios** with proper configuration.
-
-### Base Setup
-
-```typescript
-// lib/api/axios.ts - Create a configured axios instance
-import axios from 'axios';
-
-export const api = axios.create({
-  baseURL: process.env.NEXT_PUBLIC_API_URL || '/api',
-  withCredentials: true, // ALWAYS for auth cookies/sessions
-  headers: {
-    'Content-Type': 'application/json',
-  },
-});
-
-// Request interceptor for auth tokens
-api.interceptors.request.use((config) => {
-  const token = localStorage.getItem('token');
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`;
-  }
-  return config;
-});
-
-// Response interceptor for error handling
-api.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      // Handle unauthorized
-    }
-    return Promise.reject(error);
-  }
-);
-```
-
-### Usage Rules
-
-| Rule | Description |
-|------|-------------|
-| ALWAYS use `api` instance | Never raw `axios.get()` or `fetch()` |
-| ALWAYS `withCredentials: true` | Required for cookies/sessions |
-| Extend for specific APIs | Create `api.auth`, `api.payments`, etc. |
-| Type responses | `api.get<UserResponse>('/users')` |
-| Handle errors centrally | Use interceptors, not try/catch everywhere |
-
----
-
-## Enforcement Mechanisms
-
-| 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 |
-
----
-
-## Quality Requirements
-
-All implementations MUST:
-
-- [ ] Pass typecheck (`bun run typecheck`)
-- [ ] Pass lint (`bun run lint`)
-- [ ] Pass unit tests (`bun run test`)
-- [ ] Pass build (`bun run build`)
-- [ ] Have documentation updated (documenter agent)
-- [ ] 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
-
----
-
-## Domain Documentation
-
-Domain docs prevent Claude from re-exploring the codebase every session.
-
-### Location
-
-```
-.claude/skills/codebase-knowledge/domains/
-├── claude-system.md    # This development system
-├── authentication.md
-├── api.md
-├── ui-components.md
-└── ...
-```
-
-### Domain Mapping
-
-Configured in `.claude/config/domain-mapping.json`:
-
-| Domain | File Patterns |
-|--------|---------------|
-| authentication | `**/auth/**`, `**/*auth*.ts` |
-| api | `**/api/**`, `**/routers/**` |
-| database | `**/models/**`, `**/*.model.ts` |
-| ui-components | `**/components/**/*.tsx` |
-| pages | `**/app/**/page.tsx` |
-
-### Documentation Agents
-
-| 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".
-
-| 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
-```
-
----
-
-## Design System Reference
-
-> **Full docs in**: `.claude/skills/research-cache/cache/` (12 detailed files)
-
-### Required Libraries
-
-```bash
-# Core utilities (MANDATORY)
-bun add clsx tailwind-merge class-variance-authority
-bun add -D tailwindcss-animate
-
-# Animation & feedback
-bun add @formkit/auto-animate framer-motion sonner
-
-# Skeleton loaders
-bun add react-loading-skeleton
-
-# Copy-paste from: magicui.design, ui.aceternity.com, hover.dev
-```
-
-### 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));
-```
-
----
-
-## Icon Libraries (MANDATORY)
-
-| 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'` |
-
-```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';
-```
-
----
-
-## 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 |
-
----
-
-## Component Organization (MANDATORY)
-
-### 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>;
-}
-```
-
-### 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()]);
-
-// AVOID: Waterfall (sequential)
-const user = await getUser();
-const posts = await getPosts();  // Waits for user
-```
-
----
-
-## 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 |
-
-> **Cache**: `list-design-patterns-web-apps.md`
-
----
-
-## Multi-Step Forms (MANDATORY for complex forms)
-
-| 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 |
-
-### Form Stack (MANDATORY)
-
-```typescript
-// 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',
-});
-
-// 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`
-
----
-
-## Optimistic UI (MANDATORY for mutations)
-
-> Show instant feedback, rollback on error.
-
-### Pattern 1: useOptimistic (React 19)
-
-```typescript
-const [optimisticItems, addOptimistic] = useOptimistic(
-  items,
-  (state, newItem) => [...state, { ...newItem, pending: true }]
-);
-
-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
-  }
-}
-```
-
-### 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`
-
----
-
-## 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`
-
----
-
-## 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
-```
-
----
-
-## Commit Format
-
-```
-[type]: [description]
-
-- Detail 1
-- Detail 2
-
-Generated with Claude Code
-```
-
-Types: `feat`, `fix`, `refactor`, `docs`, `chore`
-
----
-
-## 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
+# Claude Development System - Agent Context
+
+This file provides detailed context for the development system installed by `start-vibing v4`.
+For user-facing project rules, see `/CLAUDE.md`.
+
+---
+
+## What start-vibing v4 Installs
+
+start-vibing is a CLI (`npx start-vibing`) that sets up Claude Code with a complete development system in ~30 seconds:
+
+| Component | Count | Installation Method |
+|-----------|-------|-------------------|
+| **MCP Servers** | 8 | `claude mcp add` (parallel, ~20s) |
+| **Plugins** | 9 | `claude plugin install` (parallel, auto-accept, ~3s) |
+| **Community Skills** | 5 | Direct HTTPS download from GitHub (~0.3s) |
+| **Template Files** | ~30 | File copy (agents, skills, config, CLAUDE.md) |
+
+### Installation Architecture
+
+```
+npx start-vibing
+├── Phase 1: Copy template files (agents, skills, config)
+├── Phase 2: Verify/install Claude Code CLI
+├── Phase 3: Install 8 MCP servers (parallel via Promise.all)
+├── Phase 4: Install 9 plugins (parallel, stdin auto-accept 'y')
+├── Phase 5: Download 5 community skills (parallel HTTPS from GitHub)
+└── Phase 6: Launch Claude Code (resume last session or new)
+```
+
+All phases run best-effort. MCP and plugin failures are non-blocking — `settings.json` `enabledPlugins` is the fallback for plugins.
+
+### CLI Options
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Overwrite all files (including custom ones) |
+| `--new` | Start fresh Claude session (default: resume last) |
+| `--no-claude` | Skip Claude Code installation and launch |
+| `--no-mcp` | Skip MCP server installation |
+| `--no-skills` | Skip community skills installation |
+| `--no-update-check` | Skip version check |
+
+---
+
+## System Architecture
+
+```
+.claude/
+├── agents/          # 4 active subagents (flat structure)
+├── skills/          # Custom + 5 community skills (auto-injected by description match)
+├── scripts/         # Utility scripts
+├── config/          # Project-specific configuration (JSON files)
+└── commands/        # Slash commands (feature, fix, research, validate)
+```
+
+---
+
+## Agents (4 Active Subagents)
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| **research-web** | sonnet | Researches best practices (2024-2026) before implementing new features |
+| **commit-manager** | haiku | Manages git commits, conventional format, merge workflow |
+| **claude-md-compactor** | sonnet | Compacts CLAUDE.md when it exceeds 40k chars |
+| **tester-unit** | sonnet | Creates unit tests with Vitest for new functions and utilities |
+
+### Agent Workflow Order
+
+```
+implement -> quality gates -> ask user about docs -> commit-manager -> complete
+```
+
+Agents are dispatched via the `Agent` tool with `subagent_type` matching agent names. They run autonomously and return results to the orchestrator.
+
+---
+
+## Plugins (9 via enabledPlugins)
+
+Plugins are the primary extension mechanism. All 9 are installed in parallel with auto-accept (`stdin.write('y\n')` x3). If CLI install fails, `settings.json` `enabledPlugins` ensures they activate on next Claude session.
+
+### Core Workflow Plugins
+
+| Plugin | Mechanism | Purpose |
+|--------|-----------|---------|
+| **superpowers** | Skills + commands | TDD, brainstorming, debugging, planning, code review, git worktrees |
+| **ralph-loop** | Stop hook + command | Iterative autonomous development loop with checkpoints |
+| **context7** | Skill + agent + MCP | Auto library docs — replaces manual context7 MCP server |
+| **code-simplifier** | Skill + command | Refine code for clarity, reduce nesting, improve naming |
+
+### Development Plugins
+
+| Plugin | Mechanism | Purpose |
+|--------|-----------|---------|
+| **typescript-lsp** | LSP server (auto) | Type diagnostics, go-to-definition, hover info |
+| **security-guidance** | PreToolUse hook (auto) | OWASP Top 10, vulnerability scan, blocks unsafe patterns |
+| **code-review** | `/code-review` command | Code quality analysis, PR review |
+| **commit-commands** | `/commit` command | Git commit, push, PR flows with conventional format |
+| **frontend-design** | `/frontend-design` command | Production-grade UI design with competitor research |
+
+### Plugin Installation Details
+
+```typescript
+// How plugins are installed (src/plugins.ts):
+// 1. Check if already installed via `claude plugin list`
+// 2. Spawn `claude plugin install <name>@claude-plugins-official --scope user`
+// 3. Auto-accept all prompts via stdin: proc.stdin.write('y\n') x3
+// 4. All 9 run in parallel via Promise.all (completes in ~3s)
+// 5. Fallback: settings.json enabledPlugins activates them even if CLI install fails
+```
+
+### Using Superpowers (RECOMMENDED)
+
+Superpowers provides structured workflows for feature development:
+
+```
+/brainstorming                   → Before designing features (ALWAYS for creative work)
+/write-plan                      → Plan multi-step implementations into executable specs
+/execute-plan                    → Execute plans with TDD (red-green-refactor cycle)
+/systematic-debugging            → Debug with root-cause analysis (not guessing)
+/verification-before-completion  → Verify before claiming work is done
+/requesting-code-review          → Get review after major features
+/dispatching-parallel-agents     → Run 2+ independent tasks in parallel via subagents
+/using-git-worktrees             → Isolate feature work from current branch
+```
+
+### Using Ralph Loop (FOR BIG TASKS)
+
+Ralph Loop runs Claude autonomously in a continuous implementation loop:
+
+```
+/ralph-loop "implement full CRUD for users" --max-iterations 10
+/cancel-ralph   → Abort if needed
+```
+
+All file changes and git history persist between iterations. Best for multi-file features, complex refactors, or sustained autonomous work.
+
+### Using Code Simplifier (POST-IMPLEMENTATION)
+
+After implementing, run `/simplify` to:
+- Reduce nesting and redundancy
+- Improve naming and readability
+- Replace nested ternaries with early returns
+- Simplify without changing behavior
+
+---
+
+## MCP Servers (8 Installed)
+
+All 8 MCPs are installed in parallel via `claude mcp add -s user` (~20s total). Each runs as a subprocess spawned by Claude Code on demand.
+
+### Required MCPs (ALWAYS use these)
+
+| Server | Package | Purpose |
+|--------|---------|---------|
+| `sequential-thinking` | `@modelcontextprotocol/server-sequential-thinking` | Structured reasoning for multi-step tasks, architecture decisions, debugging |
+| `playwright` | `@playwright/mcp@latest` | Browser automation for UI verification, E2E tests, visual validation |
+
+> These 2 are **non-negotiable**. Skipping them leads to poor planning and untested UIs.
+
+> **Note**: `context7` is now a **plugin** with auto-invocation skill (not an MCP). Library docs are fetched automatically when you use any library.
+
+### Standard MCPs
+
+| Server | Package | Transport | Purpose |
+|--------|---------|-----------|---------|
+| `memory` | `@modelcontextprotocol/server-memory` | stdio (npx) | Persistent knowledge graph across sessions |
+| `nextjs-devtools` | `next-devtools-mcp@latest` | stdio (npx) | Next.js runtime errors, routes, cache inspection |
+| `mongodb` | `@mongodb-js/mongodb-mcp-server` | stdio (npx) | MongoDB queries, schema inspection, aggregation |
+| `jira` | `@aashari/mcp-server-atlassian-jira` | stdio (npx) | Issue tracking, task management |
+| `git` | `mcp-server-git` | stdio (uvx) | Git operations, repo search, history, diffs |
+| `fetch` | `mcp-server-fetch` | stdio (uvx) | Fetch web pages as markdown |
+
+### Optional MCPs (install manually)
+
+These are shown to the user after setup but not auto-installed:
+
+| Server | Install Command |
+|--------|----------------|
+| `github` | `claude mcp add --transport http -s user github https://api.githubcopilot.com/mcp/` |
+| `sentry` | `claude mcp add --transport http -s user sentry https://mcp.sentry.dev/mcp` |
+| `figma` | `claude mcp add --transport http -s user figma https://mcp.figma.com/mcp` |
+| `linear` | `claude mcp add --transport http -s user linear https://mcp.linear.app/sse` |
+| `stripe` | `claude mcp add --transport http -s user stripe https://mcp.stripe.com` |
+| `vercel` | `claude mcp add --transport http -s user vercel https://mcp.vercel.com` |
+
+---
+
+## Community Skills (5 from GitHub)
+
+Skills are SKILL.md files placed in `.claude/skills/<name>/SKILL.md`. They are auto-injected into Claude's context when the task matches their frontmatter `description`.
+
+### Installation Method
+
+Community skills are downloaded directly from GitHub raw URLs (the `skillsadd` npm package is deprecated — its backend `skills.ws` is down). Each skill is a single SKILL.md file.
+
+```typescript
+// How skills are installed (src/skills.ts):
+// 1. Check if .claude/skills/<name>/SKILL.md already exists (skip if so)
+// 2. HTTPS GET from raw.githubusercontent.com/<owner>/<repo>/main/skills/<name>/SKILL.md
+// 3. Write to .claude/skills/<name>/SKILL.md
+// 4. All 5 run in parallel via Promise.all (completes in ~0.3s)
+// 5. No external CLI dependency — just Node.js https module
+```
+
+### Installed Skills
+
+| Skill | Source Repo | Purpose |
+|-------|------------|---------|
+| **react-best-practices** | `vercel-labs/agent-skills` | React/Next.js performance optimization rules |
+| **web-design-guidelines** | `vercel-labs/agent-skills` | 100+ WCAG accessibility + UX audit rules |
+| **composition-patterns** | `vercel-labs/agent-skills` | Compound component and composition patterns |
+| **webapp-testing** | `anthropics/skills` | Real browser test execution with Playwright |
+| **mcp-builder** | `anthropics/skills` | Guide for building MCP servers |
+
+### Adding More Skills
+
+To install additional skills from [skills.sh](https://skills.sh), use the working CLI:
+
+```bash
+# List available skills in a repo
+npx skills add vercel-labs/agent-skills --list
+
+# Install a specific skill
+npx skills add vercel-labs/agent-skills --skill <name> --yes
+
+# Install from anthropics
+npx skills add anthropics/skills --skill <name> --yes
+
+# Manual fallback (if CLI fails)
+mkdir -p .claude/skills/<name>
+curl -o .claude/skills/<name>/SKILL.md \
+  https://raw.githubusercontent.com/<owner>/<repo>/main/skills/<name>/SKILL.md
+```
+
+---
+
+## Configuration Files
+
+Project-specific settings in `.claude/config/`:
+
+| File | Purpose |
+|------|---------|
+| `project-config.json` | Stack, structure, commands |
+| `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 — update the JSON files instead.
+
+---
+
+## settings.json (enabledPlugins)
+
+The `.claude/settings.json` file contains `enabledPlugins` which is the fallback mechanism for plugin activation. Even if `claude plugin install` fails, having the plugin listed in `enabledPlugins` ensures Claude prompts to install it on first use.
+
+```json
+{
+  "enabledPlugins": {
+    "typescript-lsp@claude-plugins-official": true,
+    "security-guidance@claude-plugins-official": true,
+    "code-review@claude-plugins-official": true,
+    "commit-commands@claude-plugins-official": true,
+    "frontend-design@claude-plugins-official": true,
+    "superpowers@claude-plugins-official": true,
+    "ralph-loop@claude-plugins-official": true,
+    "context7@claude-plugins-official": true,
+    "code-simplifier@claude-plugins-official": true
+  }
+}
+```
+
+---
+
+## Execution Protocol
+
+### Before Implementation
+
+1. Use `/brainstorming` for creative work or feature design
+2. Use `/write-plan` for multi-step tasks
+3. Use `context7` (auto via plugin) for library docs
+4. Research if needed (research-web agent or web search)
+
+### During Implementation
+
+1. Use superpowers TDD (red-green-refactor)
+2. Use `/ralph-loop` for autonomous big tasks
+3. Run quality gates as you go
+
+### After Implementation
+
+1. Run `/simplify` (code-simplifier) on changed files
+2. Run quality gates (`bun run typecheck && lint && test`)
+3. Ask user if they want documentation in `/docs`
+4. Commit via commit-manager agent (FINAL step)
+5. Update CLAUDE.md with architecture changes
+
+---
+
+## Documentation Policy
+
+> Documentation is NOT automatic. It lives in `/docs` and is created only when the user asks.
+
+### After Completing Work
+
+Always ask the user:
+```
+Done! Finished [task]. Want me to:
+1. Document this in /docs?
+2. Move on to something else?
+```
+
+### What NOT to Do
+
+- Do NOT auto-generate domain docs
+- Do NOT maintain `.claude/skills/codebase-knowledge/domains/`
+- Do NOT run documenter or domain-updater agents (they were removed in v4)
+- Do NOT create documentation without user consent
+
+---
+
+## Quality Requirements
+
+All implementations MUST:
+
+- [ ] Pass typecheck (`bun run typecheck`)
+- [ ] Pass lint (`bun run lint`)
+- [ ] Pass unit tests (`bun run test`)
+- [ ] Be committed with conventional commits
+- [ ] Have CLAUDE.md updated with architecture/rule changes
+
+---
+
+## FORBIDDEN Actions
+
+| Action                         | Reason                       |
+| ------------------------------ | ---------------------------- |
+| Write in non-English           | ALL code/docs MUST be in EN  |
+| Skip typecheck                 | Catches runtime errors       |
+| Use `any` type                 | Defeats strict mode          |
+| Define types in `src/`         | Must be in `types/`          |
+| Commit directly to main        | Create feature/fix branches  |
+| Auto-document without asking   | Always ask user first        |
+| Skip superpowers for features  | Use brainstorming + TDD      |
+| Skip code-simplifier           | Run /simplify post-implementation |
+| Use MUI/Chakra                 | Use shadcn/ui + Radix        |
+| Files > 400 lines              | MUST split into smaller      |
+| 'use client' at top level      | Push to leaf components only |
+| Waterfall data fetching        | Use Promise.all() for parallel |
+| Skip CLAUDE.md update          | MUST update after implementations |
+
+---
+
+## Updating start-vibing
+
+```bash
+# Update to latest version
+npx start-vibing@latest
+
+# Force overwrite all template files (preserves custom skills)
+npx start-vibing --force
+
+# Check current version
+npx start-vibing --version
+```
+
+Template files use smart copy: `.claude/settings.json`, `CLAUDE.md`, and custom skills in `.claude/skills/` are preserved by default. Use `--force` to overwrite everything.