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.

Database/Auth provider 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:

Start from the domain ownership index in database/README.md and the SQL workflow guide. Read the matching source, callers, tests and manifest dependencies instead of loading an entire generated schema into the model context.

  • update the owning SQL source under database/ and its manifest dependencies;
  • validate assembly in memory with pnpm run db:schema:check; init, audits and guarded local start/reset need no exports or separate migration history;
  • declare narrow login/capability ACLs separately from RLS policies, with any provider-native exposure confined to its explicit overlay;
  • 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.

Business persistence uses the shared Prisma runtime on Supabase or Neon with explicit actor, maintenance, platform-log and financial-worker capabilities. Supabase clients are provider-native Auth/Storage boundaries only; Better Auth uses its isolated authn schema. No privileged client or role makes user-specific data safe for a shared cache, and provider subjects never replace canonical application actors.

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.

Payments and credit contract

Plans, prices, currencies, packs, and license facts come from config/pricing.ts. Selected-provider webhook effects are normalized, journaled, and idempotent. Subscription creation does not grant paid credits. The grant path is a verified paid provider event using one semantic provider-period key. The durable end_trial command records intent before its one-shot mutation and completes only after provider state, signed local state, and normalized paid proof converge; it never grants synchronously.

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/root-shell.tsx, app/[locale]/layout.tsx and route-group 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.