AI Blueprint

This section is for teams that use AI coding assistants. It is not required to run the boilerplate. New developers can safely start with Quick Start, Environment Setup, and Deployment, then return here when they want Claude Code, Cursor, Codex, OpenCode, or Gemini to follow the project rules automatically.

What matters first

.claude/rules/ is the canonical rule source.
AGENTS.md is the main entry point for Codex, Copilot, and generic coding agents.
scripts/sync-ai-rules.sh mirrors canonical rules to .codex/rules/, .gemini/rules/, .opencode/rules/, and regenerates .agents/skills/.
Do not hand-edit generated rule or skill mirrors; edit the canonical source first.

The project ships first-class instructions for Claude Code (.claude/), Cursor (.cursorrules + .cursor/rules/), OpenAI Codex / Copilot (AGENTS.md + .codex/), OpenCode (.opencode/), and Google Gemini (.gemini/).

Directory Structure

# Claude Code
.claude/
├── CLAUDE.md                     # Lean main instructions
├── CLAUDE.local.md.example       # Personal-preferences template (gitignored)
├── settings.local.json           # Permissions & hook wiring
├── rules/                        # 22 rule files (domain + cross-cutting)
│   ├── domain-map.md             # ⭐ START HERE — one-page orientation table
│   ├── code-writing-mandate.md   # ⭐ Non-negotiable Security/Architecture/Performance checklist
│   ├── anti-patterns.md          # ⭐ Grep-detectable regression catalog (shipped-to-main bugs)
│   ├── architecture.md           # Account-centric model, core/ layering, config-driven values
│   ├── authentication.md         # Magic links, OAuth, sessions, admin auto-promote
│   ├── database.md               # RLS, N+1, credit RPCs, security definer functions
│   ├── billing.md                # Stripe 21+ events, B2B flow, Zod metadata, multi-currency
│   ├── licensing.md              # One-shot payments, expiration, unified access check
│   ├── referrals.md              # Account-centric referrals, triggers, admin audit
│   ├── affiliates.md             # Partner program: tier commissions, 12 SECURITY DEFINER RPCs
│   ├── error-logs.md             # Server-side error monitoring, feature gate, redaction, retention
│   ├── api.md                    # apiSecurity, withSecurity, rate limiting, CSRF
│   ├── frontend.md               # React 19, i18n, components, PWA, useChat hook
│   ├── security.md               # OWASP, CSRF, SSRF, Turnstile, GDPR
│   ├── ai.md                     # 1 credit = 1 token, SSE types, prompt caching, RAG
│   ├── cms.md                    # Multi-locale JSONB, blog, shortcodes, media
│   ├── jobs.md                   # Dual auth, pg_cron, GDPR deletion, email backoff
│   ├── notifications.md          # Push (VAPID), quiet hours, email queue
│   ├── caching.md                # unstable_cache, React.cache, ISR, tag revalidation
│   ├── testing.md                # Vitest, Playwright WCAG 2.2 AA, Lighthouse CI
│   ├── design-skills.md          # 45-skill orchestration: tiers, mutual exclusivity
│   └── documentation.md          # Four-surface doc-update matrix (rules / AI-config / mirrors / user docs)
├── skills/                       # 45 skills across 4 tiers (invoke with /skill-name)
│   ├── supabase/                 # Supabase product/client/auth/CLI/MCP guidance
│   ├── supabase-postgres-best-practices/ # Postgres query/RLS/schema/index guidance
│   ├── create-api-endpoint/      # Secure API endpoints
│   ├── stripe-webhook/           # Stripe webhook handlers
│   ├── add-translation/          # i18n translations (FR/EN)
│   ├── create-component/         # React components (Server/Client)
│   ├── database-query/           # Optimized Supabase queries
│   ├── create-job-handler/       # Background job handlers
│   ├── create-ai-agent/          # AI agent definitions
│   ├── create-admin-page/        # Admin dashboard pages
│   └── (35 more skills across design / workflow / refinement tiers)
├── agents/                       # 11 specialized subagents
│   ├── code-quality-gate.md      # ⭐ Unified pre-merge gate (security + arch + perf)
│   ├── architecture-reviewer.md  # Account-centric drift, core/ layering, config values
│   ├── security-reviewer.md      # OWASP, RLS, CSRF, SSRF review
│   ├── performance-reviewer.md   # Bundle, CWV, rendering optimization
│   ├── db-architect.md           # Query optimization, schema design, RLS
│   ├── stripe-expert.md          # Payment flows, webhooks, multi-currency
│   ├── i18n-reviewer.md          # Hardcoded strings, missing translations
│   ├── ai-engineer.md            # LLM integration, prompt caching
│   ├── jobs-engineer.md          # Job handlers, GDPR deletion
│   ├── testing-engineer.md       # Test coverage, E2E, a11y
│   └── accessibility-reviewer.md # WCAG 2.2 AA compliance
└── hooks/                        # 6 automation hooks
    ├── inject-mandates.js        # ⭐ UserPromptSubmit — injects mandatory checklist
    ├── pre-write-guard.js        # ⭐ PreToolUse — blocks 15 anti-patterns at write time
    ├── protect-sensitive-files.js # PreToolUse — blocks .env, lock files, migrations
    ├── lint-on-edit.js           # PostToolUse — auto-runs ESLint
    ├── typecheck-on-edit.js      # PostToolUse — type-check (optional)
    └── stop-review.js            # Stop — review gate at session end

# Cursor
.cursorrules                      # Global rules (architecture, 10 critical rules)
.cursor/rules/                    # 17 scoped domain rules (.mdc format, glob-based loading)
│   ├── anti-patterns.mdc         # alwaysApply — regression catalog
│   ├── architecture.mdc          # alwaysApply — account-centric invariants
│   ├── database.mdc              # Supabase, credits, RLS, caching
│   ├── api-security.mdc          # apiSecurity, Zod, CSRF, rate limiting
│   ├── security.mdc              # Sanitization, CSRF, timingSafeEqual, SSRF
│   ├── stripe-billing.mdc        # Plans in config, webhooks, multi-currency
│   ├── licensing.mdc             # One-shot payments, expiration, unified access
│   ├── referrals.mdc             # Referral domain invariants
│   ├── error-logs.mdc            # Server-side error monitoring (fire-and-forget, feature-gated)
│   ├── ai-integration.mdc        # 1:1 token credits, SSE, caching
│   ├── react-components.mdc      # Server/Client, Tailwind v4, forms, a11y
│   ├── i18n.mdc                  # Translations, forbidden patterns, formatting
│   ├── cms.mdc                   # Multi-locale JSONB, blog, shortcodes
│   ├── jobs.mdc                  # Dual auth, handlers, pg_cron
│   ├── caching.mdc               # unstable_cache, revalidation tags
│   ├── notifications.mdc         # Push, email queue, quiet hours
│   └── testing.mdc               # Vitest, Playwright, Lighthouse thresholds
└── .cursor/skills/               # 4 reference skills (shared)

# OpenAI Codex + GitHub Copilot
AGENTS.md                         # Root-level instructions (+ top anti-patterns section)
.codex/instructions.md            # Compact 12 critical rules (incl. anti-patterns + referrals + error logs)
└── .codex/skills/                # 4 reference skills (shared)

# Google Gemini
.gemini/GEMINI.md                 # Gemini instructions (checklist + pre-PR smoke test)
└── .gemini/skills/               # 4 reference skills (shared)

Skills System (45 Skills)

The boilerplate includes 45 skills organized into 4 tiers. Invoke with /skill-name in Claude Code. Codex-facing copies live in .agents/skills/ and are regenerated from .claude/skills/. Skills are sourced from Supabase Agent Skills, Impeccable, Emil Kowalski, Taste Skill, Motion.dev, and custom project skills.

Tier 1: Foundation Skills (auto-invoked)

These are invoked proactively by Claude Code before writing any code:

Skill	Purpose
`/supabase`	Supabase product/client/auth/CLI/MCP guidance, current docs lookup, Data API/RLS/security traps
`/supabase-postgres-best-practices`	Postgres query planning, indexes, RLS performance, schema design, locking, and monitoring
`/vercel-react-best-practices`	Server/Client decisions, React 19 patterns, App Router, bundle optimization
`/tailwind-v4-shadcn`	Tailwind v4 `@theme inline` pattern, shadcn/ui best practices, avoids 8 error patterns
`/ui-ux-pro-max`	50+ UI styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, 25 chart types, design system generation

Tier 2: Aesthetic Direction (pick ONE per project)

These define the visual identity. They are mutually exclusive — only use one per project. Run /impeccable teach first to establish design context.

Skill	Aesthetic	Best For
`/impeccable`	Distinctive, anti-AI-slop, bold creative direction	Recommended default — most versatile. From Impeccable
`/taste-skill`	Premium agency feel, motion-heavy, spring physics	SaaS dashboards, feature-rich apps
`/soft-skill`	High-end agency ($150k+), haptic depth, cinematic rhythm	Marketing sites, luxury brands
`/minimalist-skill`	Clean editorial, warm monochrome, bento grids, muted pastels	Content platforms, productivity tools
`/brutalist-skill`	Raw mechanical, Swiss typography, military terminal	Data-heavy dashboards, portfolios

Tier 3: Refinement Skills (stackable)

Use alongside any Tier 2 choice to refine specific aspects:

Skill	Purpose	Source
`/typeset`	Fix typography hierarchy, font choices, readability	Impeccable
`/colorize`	Add strategic color to monochromatic designs	Impeccable
`/arrange`	Fix layout, spacing, and visual rhythm	Impeccable
`/animate`	Add purposeful motion and micro-interactions	Impeccable
`/motion-dev`	Motion.dev library usage — fetches docs from motion.dev and implements animations with `motion/react`	Motion.dev
`/emil-design-eng`	Polish animation quality (Emil Kowalski's philosophy: easing, springs, interaction patterns)	Emil Kowalski
`/adapt`	Responsive design across devices	Impeccable
`/clarify`	Improve UX copy, error messages, labels	Impeccable
`/onboard`	Design onboarding flows and empty states	Impeccable
`/harden`	Handle edge cases, i18n, text overflow	Impeccable
`/extract`	Consolidate reusable design patterns	Impeccable
`/normalize`	Realign UI to design system standards	Impeccable
`/delight`	Add moments of joy and personality	Impeccable
`/optimize`	Fix UI performance (loading, rendering, bundle)	Impeccable
`/overdrive`	Technically ambitious effects (shaders, physics, 60fps)	Impeccable
`/bolder`	Amplify bland designs (opposite of `/quieter`)	Impeccable
`/quieter`	Tone down aggressive designs (opposite of `/bolder`)	Impeccable
`/distill`	Strip unnecessary complexity	Impeccable

Tier 4: Workflow & Task Skills

Skill	Purpose	Example
`/shape`	Pre-implementation UX/UI planning with structured discovery	`/shape checkout flow`
`/critique`	Design review with Nielsen heuristic scoring, persona testing, anti-pattern detection	`/critique dashboard`
`/audit`	Technical quality check (a11y, performance, theming, anti-patterns)	`/audit landing page`
`/polish`	Final pre-ship quality pass (alignment, spacing, consistency)	`/polish settings page`
`/redesign-skill`	Audit and upgrade existing pages to premium quality	`/redesign-skill pricing page`
`/output-skill`	Enforce complete code generation (no truncation or placeholders)	`/output-skill` then describe task
`/stitch-skill`	Generate semantic DESIGN.md for Google Stitch	`/stitch-skill`
`/create-api-endpoint`	Create secure API endpoints with security middleware, validation	`/create-api-endpoint POST /api/users/export`
`/stripe-webhook`	Implement Stripe webhook handlers with signature verification	`/stripe-webhook invoice.payment_failed`
`/add-translation`	Add translations to both FR and EN locale files	`/add-translation billing.upgradeButton`
`/create-component`	Create React components following project patterns	`/create-component UserAvatar`
`/database-query`	Create optimized Supabase queries with RLS handling	`/database-query get account with members`
`/create-job-handler`	Create background job handlers with error handling	`/create-job-handler cleanup old notifications`
`/create-ai-agent`	Define AI agents with model restrictions and system prompts	`/create-ai-agent code review assistant`
`/create-admin-page`	Create admin dashboard pages with auth, layout, data fetching	`/create-admin-page license management`

Recommended Pipeline

Planning:    /shape → /impeccable teach
Building:    /impeccable craft  (or chosen Tier 2 aesthetic skill)
Refining:    /typeset, /colorize, /arrange, /animate, /motion-dev  (as needed)
Reviewing:   /critique → fix issues → /normalize
Shipping:    /polish → /audit

Design Skill Rules

Colors: Always oklch() via CSS variables in globals.css + Tailwind @theme inline. Never raw hex in components.
Fonts: Inter, Roboto, Arial, Syne are banned. Use distinctive fonts checked against package.json.
Animation: Cubic-bezier ease-out for UI feedback. Springs only for drag/gesture and decorative micro-interactions.
Security: No inline scripts/styles violating CSP. No dangerouslySetInnerHTML without sanitization.
See .claude/rules/design-skills.md for the complete orchestration guide.

UI/UX Pro Max Design Intelligence

Integrated UI/UX Pro Max as a design intelligence skill. Auto-activates when building, designing, or improving UI/UX. Powered by a BM25 search engine across curated design databases.

Asset	Count	Description
UI Styles	67	Glassmorphism, Brutalism, Minimalism, Neumorphism, Bento Grid, Dark Mode, Flat Design, and more with CSS keywords, performance ratings, and accessibility grades
Color Palettes	161	Industry-specific palettes (SaaS, e-commerce, fintech, healthcare...) with semantic tokens: Primary, Secondary, CTA, Background, Text, Muted, Destructive
Font Pairings	57	Curated Google Fonts heading/body combinations with mood keywords, CSS imports, and Tailwind config snippets
Chart Types	25	Data visualization recommendations with accessibility notes, library suggestions, and color guidance
UX Guidelines	99	Accessibility (WCAG), touch targets (44px min), performance, animation (150-300ms), forms, navigation across 10 priority categories
Reasoning Rules	161	AI engine analyzing product type to generate complete design system: pattern, style, colors, typography, effects, anti-patterns
Stack Guides	13	Next.js, React, shadcn/ui, Tailwind, Vue, Svelte, Flutter, React Native, Astro, Nuxt, Angular, Laravel, Three.js

Design System Generation:

# Search a specific domain
py .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS" --domain style

# Generate complete design system
py .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system -p "MyProject"

# Persist design system (Master + page overrides)
py .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system --persist -p "MyProject" --page "dashboard"

# Mobile stack guidelines (react-native is the only discrete --stack in v2.5.0)
py .claude/skills/ui-ux-pro-max/scripts/search.py "list performance" --stack react-native

# Web stacks (React/Next/Vue/shadcn) are consolidated into the core data — query by domain
py .claude/skills/ui-ux-pro-max/scripts/search.py "navigation" --domain ux

Pre-Delivery Checklist

Every design system output includes a mandatory checklist: no emoji icons (use SVG), cursor-pointer on clickables, hover transitions (150-300ms), 4.5:1 contrast ratio, visible focus states, prefers-reduced-motion support, and responsive breakpoints (375/768/1024/1440px).

Specialized Subagents

Use subagents for specialized reviews and complex tasks:

Agent	Specialization	Usage
code-quality-gate	Unified pre-merge gate — synthesizes security + architecture + performance lenses, runs the anti-patterns smoke test, returns a single PASS / CHANGES / BLOCKED verdict	"Run the code-quality-gate on this branch before merge"
architecture-reviewer	Account-centric drift, `core/` layering violations, config-driven values, migration↔schema.sql parity	"Use the architecture-reviewer on the new routes"
security-reviewer	RLS policies, authentication, API security, OWASP compliance	"Use the security-reviewer to audit the auth routes"
db-architect	Query optimization, N+1 detection, index suggestions	"Have the db-architect review these queries"
stripe-expert	Payment flows, webhook handlers, subscription logic	"Ask the stripe-expert to implement the webhook"
i18n-reviewer	Hardcoded strings, translation validation, locale patterns, currency formatting	"Run i18n-reviewer on components/dashboard/"
ai-engineer	LLM integration, prompt caching optimization, agent architecture, cost tracking	"Use the ai-engineer to review prompt caching strategy"
performance-reviewer	Bundle optimization, Core Web Vitals, Server/Client split, rendering	"Have the performance-reviewer analyze the landing page"
jobs-engineer	Background job handlers, cron scheduling, GDPR deletion, webhook security	"Ask the jobs-engineer to review the deletion handler"
testing-engineer	Test coverage gaps, E2E strategy, unit/a11y/responsive test design	"Run the testing-engineer to identify coverage gaps"
accessibility-reviewer	WCAG 2.2 AA compliance, semantic HTML, keyboard navigation, ARIA	"Use the accessibility-reviewer on the pricing page"

Automation Hooks

Six hooks enforce the Security / Architecture / Performance contract automatically at the key moments in every Claude Code turn — checklist injection before reasoning, anti-pattern blocking before write, lint + typecheck after write, review gate on session end.

Hook Type	Hook	Purpose
UserPromptSubmit	`inject-mandates.js`	Injects the mandatory Security / Architecture / Performance checklist into every non-trivial prompt so Claude must address each lens before writing code. Skipped for empty / pure-slash-command prompts.
PreToolUse	`pre-write-guard.js`	Grep-scans the about-to-be-written content for 15 anti-patterns (`getSession()`, direct `credits_balance` writes, `dangerouslySetInnerHTML` without sanitize, secret-shaped `NEXT_PUBLIC_`, hardcoded currencies/locales, locale conditionals, `createClient()` inside `unstable_cache`, raw `<img>`, raw hex colors, `.select('')`, `count:exact head:false`, raw `NEXT_PUBLIC_APP_URL` reads, direct `auth.getUser()`, locale-keyed JSONB literals). Bypass a specific finding with `// allow: <rule-id>`.
PreToolUse	`protect-sensitive-files.js`	Blocks editing `.env`, lock files, migration files, and other sensitive paths.
PostToolUse	`lint-on-edit.js`	Auto-runs ESLint on edited TypeScript / JavaScript files.
PostToolUse	`typecheck-on-edit.js`	Type-check after editing TypeScript files (optional).
Stop	`stop-review.js`	Review gate at session end — verifies no regressions before completion.

Modular Rules System

Rules are split into 22 focused files for better context management. A fresh AI agent should read domain-map.md first (one-page orientation), then code-writing-mandate.md (non-negotiable checklist), then the specific domain file for whatever it's about to touch.

Rule File	Topics Covered
`domain-map.md` ⭐	START HERE. One-page table mapping every domain to its tables, `core/` module, API routes, config source, RLS scope, and rule file. Includes cross-cutting layers registry and "where to start" debug flowchart.
`code-writing-mandate.md` ⭐	Non-negotiable pre-code checklist — three lenses (Security / Architecture / Performance), each with 16-20 numbered rows listing the requirement and its grep-detectable red flag. Enforced at every turn by the `inject-mandates.js` hook.
`anti-patterns.md` ⭐	Grep-detectable catalog of regressions that shipped to `main` more than once — organized into 5 categories (Architectural drift, Config+i18n, Performance foot-guns, Security tightening, Process invariants). 25+ patterns with symptom → past-regression citation → grep command → fix. Includes a 4-line pre-PR smoke test.
`architecture.md`	Account-centric model enforcement, `core/<domain>/` layering contract, config-driven values, route-handler thinness, anti-abstractions policy.
`referrals.md`	Account-centric referral program: feature gate, trigger semantics (`on_signup` / `on_first_purchase` / `on_first_subscription`), `SECURITY DEFINER` RPCs, cookie-based attribution, admin audit trail.
`affiliates.md`	Account-centric partner program: tier-based commissions (recurring vs one-time-upfront), 8 tables + 12 SECURITY DEFINER RPCs, conversion idempotency via `stripe_event_id UNIQUE`, billing webhook hooks try/catch-isolated so affiliate failures NEVER break billing, hold-period auto-approve job. Phase 1 (workflow + tracking) and Phase 2 (conversions + admin reverse) shipped; Phase 3 Stripe Connect deferred.
`authentication.md`	Magic link flow (token_hash), OAuth, sessions, admin auto-fix, onboarding
`database.md`	RLS policies, credit/license RPCs, N+1, security definer functions, 25+ tables
`billing.md`	Stripe 21+ events, B2B org creation, Zod metadata validation, multi-currency
`licensing.md`	One-shot payments, LicenseWebhookMetadata, expiration jobs, unified access check
`api.md`	apiSecurity + withSecurity, rate limiting, CSRF, data export, chat pagination
`frontend.md`	React 19, i18n, components, PWA, useChat hook, landing components, account context
`security.md`	OWASP, CSRF, SSRF prevention, timingSafeEqual, CMS validation, GDPR, Turnstile
`ai.md`	1 credit = 1 LLM token accounting, SSE event types, prompt caching, multi-agent architecture
`cms.md`	Multi-locale JSONB, blog system, shortcodes, media (10MB), content validation (500KB)
`jobs.md`	Dual auth (Bearer/admin), pg_cron, 12+ handlers, GDPR deletion, email backoff
`notifications.md`	Push (VAPID), quiet hours, device tracking, email queue, notification types
`caching.md`	unstable_cache, React.cache, ISR, tag-based revalidation, anti-patterns
`testing.md`	Vitest, Playwright WCAG 2.2 AA, responsive (3 viewports), Lighthouse CI thresholds
`design-skills.md`	45-skill orchestration: 4 tiers, mutual exclusivity, animation/color/font conflict resolution, pipeline
`error-logs.md`	Server-side error monitoring: fire-and-forget logger, secret redaction, IP hashing, `LOGS_ENABLED` feature gate, retention purge job, RLS zero-policy table.
`documentation.md`	What "update the documentation" expands to across the four doc surfaces: `.claude/rules/` (canonical), AI-tool config, synced mirrors, and user-facing docs.

Foundation Skills (Auto-Invoked)

Claude Code MUST proactively invoke these 5 foundation skills when writing or modifying code. They are auto-invoked — no user action required.

Skill	When to Invoke	What it Provides
`/supabase`	ANY Supabase product, client, auth, CLI, MCP, Storage, Edge Function, Realtime, Vector, Cron, Queue, or schema task	Current Supabase docs/changelog workflow, auth/RLS/Data API/security guidance, CLI/MCP troubleshooting
`/supabase-postgres-best-practices`	ANY Postgres query, RLS policy, schema change, index, RPC, migration, or database performance work	Postgres performance rules, query plans, indexing, RLS performance, schema design, locking, monitoring
`/vercel-react-best-practices`	ANY React component, Next.js page, data fetching, performance work	Server/Client decisions, React 19 patterns, App Router patterns, bundle optimization
`/tailwind-v4-shadcn`	ANY styling code, shadcn/ui component, theme configuration	Tailwind v4 patterns, shadcn/ui best practices, dark mode, avoids 8 error patterns
`/ui-ux-pro-max`	ANY UI/UX design, page layout, component creation, color/typography selection	50+ UI styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, 25 chart types, design system generation

Additionally, 45 skills across 4 tiers (foundation, aesthetic, refinement, workflow) are available. The full catalog with usage pipeline is documented in the Skills System section above and in .claude/rules/design-skills.md.

Automatic Invocation

Foundation skills are invoked automatically before writing code. Aesthetic, refinement, and workflow skills are invoked on-demand via /skill-name. Configuration is in CLAUDE.md (root), .claude/CLAUDE.md, and .claude/rules/design-skills.md.

Personal Preferences

Create .claude/CLAUDE.local.md (gitignored) for personal settings — preferred package manager, local URLs, machine-specific notes — that should not be committed or shared with the team:

# Personal Claude Code preferences (gitignored)

- Package manager: pnpm
- Local Supabase Studio: http://localhost:54323
- Always run `npm run lint` before committing
- Skip the changelog prompt for trivial doc edits

Getting Started

After cloning the boilerplate, the .claude/ directory is ready to use. Restart Claude Code to load the configuration. Copy .claude/CLAUDE.local.md.example to .claude/CLAUDE.local.md for personal preferences.