auth-app — agent instructions

Source of truth for coding agents working in this repo.

What this is

An Express + React + Postgres app with Better Auth email/password login. Scope is auth only — there are no domain APIs, and adding one is out of scope unless asked.

Commands

npm run verify (typecheck + lint + format + test + deps:sync + knip + audit) is the fast definition of green — the pre-push hook runs exactly this. CI additionally runs coverage, the Playwright e2e suite and Semgrep, so npm run verify:full (verify

• coverage + e2e + semgrep) is what "green in CI" actually means.

Coverage thresholds live in vitest.config.ts and are measured floors that ratchet upward. WON'T lower one to make a red build green — write the test, or say plainly in the PR that the number is being restated and why.

Layout

• apps/api — Express. auth.ts is the security boundary; app.ts is a factory so tests can build the app without a port.
• apps/web — Vite + React SPA.
• packages/shared — zod schemas imported by both sides. This is the contract.
• docs/plans/ — the plan behind every change (see "Plans", below).

Rules

WON'T — hard prohibitions

Each of these is phrased so that a violation is visible in a diff.

• WON'T weaken, skip, or mock an auth check to make a test pass. If a test fails, report the failure. A green suite bought by deleting the assertion is worse than a red one, because it lies.
• WON'T hand-edit apps/api/src/db/schema.ts. It is generated by the Better Auth CLI. Change auth.ts, then regenerate and add a migration.
• WON'T apply a migration or drop data without asking first. Schema changes are one-way doors.
• WON'T commit or push unless explicitly asked.
• WON'T add a dependency without flagging it first, with a one-line reason.
• WON'T bump a shared package in one workspace only. zod and better-auth are declared in more than one package.json; raise the version in every workspace that declares it, in the same commit. Split versions install two copies, and a zod schema built by one copy does not validate against the other — a runtime failure no type check catches. npm run deps:sync enforces this in verify; it is not a matter of remembering.
• WON'T log secrets. The logger redacts cookies, auth headers, passwords and tokens — do not log around it.
• WON'T loosen CORS, cookie flags, or trustedOrigins to fix a bug. If a request is blocked, that is usually the guardrail working. Understand it first.

The confidence loop

Before implementing anything non-trivial, self-score your plan 1–10 on how confident you are that it is correct and complete.

If you are below 8, stop and ask. Name specifically what you are guessing about — a file you haven't read, an API you're unsure of, a requirement with two plausible readings.

A question costs the user thirty seconds. A wrong guess costs an hour of debugging code that is mostly right, which is the most expensive kind of wrong. Do not paper over uncertainty with a plausible-looking implementation.

Verify before claiming

Don't say "this works" because it typechecks. Run it. npm run verify is the floor; for anything touching auth, drive the actual flow: npm run smoke runs the README's curl walkthrough (signup → session → sign-out → sign-in) against a running server and fails loudly on any step.

Code search

Prefer the semble MCP for locating code: one focused search query (pass the repo root as repo) returns the file and exact line; find_related finds similar code elsewhere in the repo. Fall back to grep only when semble misses. Agents without the MCP installed just use grep — this is advisory.

Plans

Every meaningful change gets a plan committed to docs/plans/NNN-slug.md, and the commit that implements it carries a trailer:

Plan: docs/plans/001-auth-login.md

The commit-msg hook rejects commits without it — the convention is enforced, not merely encouraged. git log --grep='^Plan:' reconstructs the reasoning behind the whole history.

What is enforced vs. advisory

This file is advisory: it shapes behavior, but nothing stops an agent from ignoring it. That is precisely why the things that actually matter are enforced by tools instead — permission rules in .claude/settings.json, git hooks in .husky/, secret scanning, CI, and CODEOWNERS.

The principle: anything an agent could disable, enforce somewhere the agent isn't.

Claude Code specifics

Plan mode

Use plan mode before touching apps/api/src/auth.ts, apps/api/drizzle/, or anything under packages/shared/ — a change to any of them has a blast radius beyond the file you're editing.

Permissions

.claude/settings.json denies edits to .env, .husky/, .github/workflows/, .claude/, and the generated db/schema.ts; it asks before auth.ts, packages/shared/, and migrations.

If a tool call is denied, that is the guardrail working — do not route around it. Don't try the same edit via Bash, don't rewrite the settings file, and don't propose disabling the hook. Tell the user what you wanted to do and why, and let them decide.

Nested instructions

apps/api/, apps/web/, and packages/shared/ each have their own CLAUDE.md with rules specific to that workspace. They load automatically when you read a file in that directory, so you don't need to go looking for them.