CLAUDE.md

Rules for any AI agent working in this repo. From the AuthentaLink Playbook: https://github.com/GeorgeAuth26/authentalink-playbook

How we work

• No approved plan, no code. Run the prd-gate skill first. Lite for small, isolated changes; Full for anything that touches schema, endpoints, AI agents, scheduled jobs, auth, payments or more than 3 files.
• Map first. Every plan carries a process map (every screen, state, email and side). No map, no approval. Before merge, mark every box Match, Different or Not built with file and line; one Different stops the merge. Draw maps from rulings or code, never from memory.
• Recon, confirm, stop. Read first, state your plan, and wait for an explicit GO.
• qa-gate before every commit. It fails closed.
• Gates with receipts. When a plan is approved, write its scorecard at docs/prds/gates/<plan name>.md before any build code. Only scripts/gates-check.sh checks a box. Never hand-type a receipt. Paste the checker's output word for word in every report. After a crash, run the checker first: the receipts are the sprint's state.
• One commit per task, naming the plan and its requirement numbers.
• Shipped = merged to main + pushed + published + checked live. Nothing less is shipped.
• Clean tree at the end of every turn. Never force-push main.
• Human first. Every product question opens with three plain lines: the human situation, the exact object and field changing (strict nouns from the project's canonical model file), and when the person notices the problem and how hard it is to fix. Never answer by keyword-matching a past ruling.
• New-user walk before Shipped. Nothing a user sees is stamped Shipped until the live site has been walked as a brand-new person, phone and desktop, logged out and on the founder's standing test account. The AI never creates accounts or enters passwords.
• Kill check before anything retires. List every dependent from the code with a verdict for each. No kill check, no retirement. A guard test fails if live code still calls anything retired.
• One board. Work only on items on the project's board. New ideas answer "Why now, and why today?" and get the founder's yes by name before they join it.

The 12 rules

1. Think before coding. Before any build: component tree, data shapes, state flow, and three named edge cases or timing bugs with how you'll block them. Ask, don't guess. Push back when a simpler way exists.
2. Simplicity first. Minimum code, nothing speculative, no single-use abstractions.
3. Surgical changes. Touch only what you must. Match the existing style.
4. Goal-driven. Define success first. Loop until verified.
5. Model for judgment only. If code can answer, code answers.
6. Token budgets are real. Per task: ____. Per session: ____. Surface a breach; never overrun silently.
7. Surface conflicts. Pick the more recent or better-tested pattern, say why, flag the other.
8. Read before you write. Exports, callers, shared utilities.
9. Tests verify intent. Every rule gets a removal check: red with it removed, green with it restored.
10. Checkpoint every significant step. Done, verified, left.
11. Match conventions. Raise harmful ones; don't fork silently.
12. Fail loud. Skipped means not done. NOT RUN is never PASS.

Reporting

Plain words. Answer: what happened, why, what's next, is it done, and what it means for the customer. Never print a secret or environment value.

Project constraints (fill these in)

• Type-error ceiling: ____ (must not rise)
• Files no agent may touch: ____
• All AI calls go through: ____ (one client file, model names as constants)
• Read-only fields: ____
• Schema changes are additive only; no destructive migrations or schema push
• Every new foreign key to a user table is covered by account deletion
• No em dashes in user-facing strings
• Switches (feature flags) publish off; the founder says when they go on