AGENTS.md

Slopproof is a full-stack template built around a verifiable API contract. src/contract generates openapi.json, which generates src/sdk; the running API and the tests must agree with all three. A change is done when pnpm check passes, plus pnpm check:drift and pnpm build && pnpm verify:app for changes to the contract, database, auth, or UI flows.

Architecture map

• UI and page routes reach data only through the SDK (#/sdk/...) or a server function in #/lib/*.functions.ts. src/server, drizzle-orm, pg and better-auth (its client included) stay behind those: account actions are server functions that run Better Auth's router in-process (callAuthEndpoint), so rate limits and the endpoint allowlist apply. Authorization happens in the Effect Authentication middleware; the _authed route guard is only a UX redirect.
• Boundaries are enforced by Fallow zones in .fallowrc.json and by no-restricted-imports in .oxlintrc.json. A new top-level src/ directory needs a zone before it can be used.
• Imports use the #/ alias (package.json#imports) with explicit .ts or .tsx extensions.

Where code goes

The UI follows Bulletproof React, with src/routes/ as the app layer. Imports flow one way: components → features → app (routes/).

• Feature code: src/features/<name>/. Read src/features/AGENTS.md before adding or changing one: it holds the data-access and mutation-hook conventions.
• UI shared by several features and free of feature knowledge: src/components/ (table above); shadcn primitives go in components/ui/ through pnpm exec shadcn add.
• Route files hold the route definition and a small page component that composes features (skill add-page).
• Naming: files and folders are kebab-case (Oxlint unicorn/filename-case; folders by tests/unit/repo-policy.test.ts). TanStack route names keep their prefixes (__root.tsx, _authed.tsx, $.ts, -private/, (group)/). src/sdk/ is generated and exempt.
• Import the file that defines a symbol. Barrel files (index.ts re-exporting a folder) fail Oxlint oxc/no-barrel-file; the only one is src/server/db/schema/index.ts, Drizzle's schema entry.

Code style

Code is read by agents one file at a time: a module fits one read, a name greps to its definition, and a failure says what was wrong. Oxlint (.oxlintrc.json) enforces the numbers; the rest is for review. Tests: tests/AGENTS.md; dependencies of the Effect API: src/server/AGENTS.md.

• Size. Functions up to 20 lines, components (.tsx) up to 80, files up to 300, blank and comment lines not counted (max-lines-per-function, max-lines). Over a limit, split by responsibility, not by moving lines: a component extracts a child component, a Layer moves its methods into functions that take the service (listPublic(db, page)), a switch that maps codes to text becomes a table.
• Nesting. At most two nested blocks per function (max-depth), three nested callbacks (max-nested-callbacks), JSX four elements deep (react/jsx-max-depth), three parameters, more go in an options object (max-params). Return early; no nested ternaries (no-nested-ternary).
• Names. A name says what the value is, specifically enough that rg -w <name> finds its definition and its uses: outcome, listed, lintRun, never result, info, item, tmp (id-denylist). data and handler are keys TanStack and Effect impose: keep them as keys, destructure into a specific name (({ data: credentials })), and never declare your own. Name a module after what it does, never utils.ts or helpers.ts (src/lib/utils.ts is shadcn's).
• Types. No any (no-explicit-any, no-unsafe-*): read an untyped library value as unknown and narrow it. Exports of src/server, src/lib, src/contract and scripts declare their return type (explicit-module-boundary-types); components and hooks infer theirs.
• Errors. A message names the offending value and the shape expected: `${name} must be an integer between ${min} and ${max} (got "${raw}")` (unicorn/error-message only rejects an empty one). Never echo a secret, a password or user content: give its length, scheme or path (env holds credentials as Redacted, which print as <redacted>). Across a trust boundary the client gets a generic message and log gets the cause (src/lib/server-function-errors.ts).
• Comments. Say why, not what. Keep them when you refactor, update them when the reason changes. A line that exists because of an upstream bug or limit links the issue (better-auth#9920) and says when to remove it. Exports of src/server, src/lib and features/*/{api,utils} get a JSDoc sentence on intent, plus a one-line example when the types do not make the call obvious.
• Logging. Server code logs through log (src/server/log.ts), one JSON object per line; console is for scripts (no-console).

Workflows

Each multi-step workflow is a project skill in .agents/skills/ (linked into .claude/skills/). Load it first:

First setup. Run pnpm install && pnpm bootstrap. This creates .env with a secret, starts Postgres and Mailpit (pnpm mail:up, the local inbox for account emails), and applies migrations.

Verify

Read tests/AGENTS.md before you write or change a test: it says which layer a behavior belongs in and how each layer's harness works.

Every gate's failure message says how to fix it. What each gate covers, how to make a reviewed exception, the Lighthouse policy and the less common commands (audit:check, sbom:release) are in docs/agents/gates.md.

Memory safety

A misconfigured lint once used 17 GB of memory.

• To check a few files, pass explicit paths: pnpm lint src/x.ts, pnpm exec oxfmt --check src/x.ts.
• Keep node_modules/**, .output/**, and .repos/** out of every tool's scope. .oxlintrc.json and .oxfmtrc.json list all three in ignorePatterns, tsconfig.json includes only src, scripts, tests, and *.config.ts (and excludes node_modules, .output, and .repos), and .fallowrc.json lists all three in ignorePatterns. A new tool or config needs the same exclusions.
• Run heavy commands one at a time (pnpm build, type-aware lint, verify:app, lighthouse); on Linux under a memory cap, see docs/operations.md.
• Read upstream code with gh api or a sparse clone of the listed paths into .repos/ (dependency-sources.md), never a full clone.

Generated and vendored files

Regenerate these files; edit their sources instead. Claude Code refuses edits to them (.claude/settings.json): a refused edit means change the source and run the command.

• src/sdk/** and openapi.json: pnpm codegen
• src/routeTree.gen.ts: pnpm dev or pnpm build
• drizzle/**: pnpm db:generate (only the new SQL file may be adjusted by hand, before it is committed; tests/unit/repo-policy.test.ts rejects edits to migrations already in the journal)
• .agents/skills/shadcn/** and skills-lock.json: the skills CLI (docs/agents/skills.md). The other skills in .agents/skills/ are this repo's own and are edited by hand.
• .repos/**: the sparse clones in dependency-sources.md

Version policy

Dependencies are pinned exactly, fresh releases are quarantined for a day, and the pre-release packages (nitro, @tanstack/react-start, oxfmt, @hey-api/openapi-ts) are upgraded one per PR with check, check:drift and verify:app passing. The upgrade-prerelease-deps skill holds the full policy; load it before changing package.json or pnpm-workspace.yaml.

Sharp edges

• Effect v4. v4 became stable in October 2026, so most examples on the web still use the v3 API. Before writing Effect code, read node_modules/effect/AGENTS.md in full; look up APIs in node_modules/effect/src.
• TypeScript. The project has one TypeScript, 7.0.2 (no JS compiler API). Hey API stays on its next snapshot; 0.99.0 crashes on TS 7 (ADR 0002). scripts/*.ts run through Node's type stripping, so use erasable syntax only (no enums, namespaces, or constructor parameter properties). The TanStack lint plugins run without type information under Oxlint (pnpm-workspace.yaml explains the peer rule).
• CSP. No policy allows 'unsafe-inline' (ADR 0010): style with classes, and put head scripts and styles through the route's head() so the router adds the nonce.
• Tailwind. Keep @import "tailwindcss" source("../") in src/styles/app.css. Without it, Tailwind scans .output, SSR and client CSS hashes diverge, and the CSS returns 404 in production (guarded by tests/integration/assets.test.ts and tests/unit/repo-policy.test.ts).
• Origin. APP_URL must be the public origin. SSR uses it as the SDK base URL, and a mismatch changes TanStack Query keys and causes a refetch after hydration. src/start.ts rejects state-changing requests from any other origin.
• Prerender. Nitro, the deployment layer, prerenders the routes in vite.config.ts and writes each page's hash-based CSP in its prerender:generate hook (ADR 0004).

Library docs and skills

• TanStack Start and Router: run pnpm dlx @tanstack/intent@0.4.0 list, then pnpm dlx @tanstack/intent@0.4.0 load <package>#<skill> for the matching skill (for example, @tanstack/start-client-core#start-core/execution-model). The Load: lines that intent list prints use @tanstack/intent@latest; replace @latest with @0.4.0.
• shadcn/ui: the skill in .agents/skills/shadcn loads automatically. Run the pinned CLI with pnpm exec shadcn … wherever the skill says npx shadcn@latest.
• Better Auth, Fallow, and Playwright traces: see docs/agents/skills.md.
• Upstream docs or source not in node_modules: see docs/agents/dependency-sources.md. Snapshots in .repos/ are read-only reference material.

Decisions

Architecture decisions are recorded in docs/decisions/. Read the relevant ADR before reversing a choice, for example adding tRPC or Zod, moving prerendering, or upgrading Drizzle to 1.0.