Site

AI Blueprint

The AI Blueprint helps Claude Code, Codex, Gemini, OpenCode, Cursor, and other coding agents make changes that fit Boilerplate Stack. It is developer tooling; the application does not require an AI assistant at runtime.

One instruction hierarchy

The repository keeps project knowledge in one hierarchy:

  • CLAUDE.md is Claude Code's concise root entrypoint.
  • AGENTS.md is the root entrypoint for Codex and generic coding agents.
  • .claude/rules/ contains canonical path-scoped project contracts.
  • .claude/references/ contains canonical catalogues loaded only when a rule or skill routes a task there.
  • .claude/skills/ contains canonical task workflows.
  • .claude/agents/, hooks, and settings define reviewed specialist and safety behavior.

Generated rule and skill mirrors are maintained by scripts/sync-ai-rules.sh. Do not hand-edit .agents/skills/, mirrored rule directories, or tool-specific skill discovery copies.

bash
bash scripts/sync-ai-rules.sh
pnpm run audit:ai-config
pnpm run audit:guardrails

Use bash scripts/sync-ai-rules.sh --check when validation must not modify the working tree.

How guidance loads

The root entrypoint holds only universal invariants and routes each task to the narrowest domain rule. Rules use paths: frontmatter, so unrelated database, billing, or visual guidance does not load for every task. Skill and agent bodies load only when their workflow is selected; references load through explicit links.

Start with .claude/rules/domain-map.md, then read the matching domain rule and .claude/rules/anti-patterns.md before editing. The validator checks rule scopes, frontmatter, local references, stale facts, generated mirrors, hook contracts, and context budgets.

Supabase and PostgreSQL contract

Business data is Account-owned. Membership is the tenant boundary; user_id may describe an actor, subject, or recipient but must not replace account_id as the business ownership key.

Database work follows these rules:

  • create a hand-authored migration with the repository-pinned Supabase CLI;
  • update the matching supabase/schema.sql or supabase/cms-schema.sql in the same change;
  • declare Data API grants separately from RLS policies;
  • target policy roles with TO and authorize rows through Account membership;
  • use security_invoker = true for views over protected data;
  • default to SECURITY INVOKER; necessary definers use an empty search_path, qualified objects, narrow execute privileges, and caller/argument validation;
  • modify credits only through the atomic credit RPCs and ledger;
  • verify indexes, explicit tenant filters, RLS, grants, and fresh-schema parity.

createClient() is the cookie-backed server client and enforces RLS. createServiceClient() and supabaseAdmin are server-only bypass surfaces; they never make user-specific data safe for a shared cache.

The Supabase MCP server is optional. If a developer enables it, use a development/test project, scope it to one project_ref, keep it read-only by default, expose only necessary feature groups, retain manual approval, and never commit tokens. Remote SQL and linked-project mutations always require explicit authorization.

Stripe and credit contract

Plans, prices, currencies, packs, and license facts come from config/pricing.ts. Stripe webhook effects are journaled and idempotent. Subscription creation does not grant paid credits. The normal grant path is a verified invoice.paid event; the explicit end-trial path may apply the same semantic ledger effect only after proving the expanded latest invoice is paid, so the later webhook becomes a no-op.

Credits are never written directly to accounts.credits_balance. Use the atomic add_credits and decrement_credits RPCs with reviewed reasons, metadata, and idempotency keys.

One project-wide design-system contract

DESIGN.md defines the shared visual and interaction language for marketing, authentication, dashboards, administration, and documentation. Frontend work verifies that contract against source-controlled runtime facts, in this order:

  1. app/globals.css for semantic oklch() tokens, themes, typography, radii, shadows, and Tailwind CSS 4 mappings;
  2. components.json for shadcn/ui integration and aliases;
  3. components/ui/, components/patterns/, and the nearest feature component;
  4. app/layout.tsx and route-level providers for fonts and Motion behavior;
  5. .claude/rules/frontend.md and the routed frontend reference.

The established fonts are DM Sans and JetBrains Mono. Reuse local components, tokens, icons, and assets. Every frontend change starts with the 320px composition, remains deliberate at 375px, and expands through 768px, 1280px, and 1440px while supporting both themes, reduced motion, configured locales, and WCAG 2.2 AA.

Impeccable 4.1.1 is the default visual director. Load it and every foundation or refinement skill required by the actual task—React/Next.js, shadcn, Tailwind, motion, accessibility, or performance—without loading unrelated skills or a second aesthetic direction. The bundle is vendored; its absent CLI, self-update path, and hook installer are not part of the repository workflow.

The shadcn and Tailwind skills work from local source and configuration. They do not imply that a missing CLI can be downloaded. Any new dependency or executable requires an exact reviewed addition through the repository's pnpm workflow.

Safety and local configuration

Shared hooks use argument arrays, confined physical paths, bounded input, and tested structured output. Blocking hooks fail closed on malformed input or the wrong Node runtime. These hooks are guardrails, not a shell or database sandbox; permissions, review, and targeted tests remain authoritative.

Personal instructions belong in the gitignored root CLAUDE.local.md, and personal approvals in .claude/settings.local.json. Never place secrets in either file or in tracked MCP/tool configuration.

Updating the blueprint

Edit canonical rules and skills first, synchronize mirrors, then run the AI configuration audit. Update this page only when the shipped developer workflow or public project contract changes. Avoid counts, package versions, exhaustive inventories, or copied code shapes that will drift from the repository.