Decisions
Product goals, constraints, and the rationale a later change has to keep. The code shows the current setting. These files say what must not be undone by accident.
What you fill in
ai/core/identity.md ships with “What we are building” empty. That is deliberate. The founding state does not invent who your application is for. You write that paragraph in present tense, as facts about the application, and commit it. Until then, a session continues the work you asked for and does not invent a product.
How a decision is kept
Files in ai/decisions/ are living decisions, named XX-topic.md. Edit one in place. Do not renumber it. Git is the history, so these are not append-only ADRs.
A new file has to pass three tests. Otherwise it does not get written:
The code cannot carry it. Config, package.json, and the schema already show the current setting. The file is for the refusal and the consequence. The mistake would be structural: undoing it changes what the application is, or it starts a second way of doing the same thing. And it is meant to hold until someone reverses it on purpose. A setting that should flip as the app grows is a tuning, not a decision.
Decisions in force
| File | The choice |
|---|---|
| 01-framework-stack | React Router 8 Framework Mode, Vite, Node 24. |
| 02-typescript-language | TypeScript. UI is tsx. Other source is ts. |
| 03-npm-package-manager | npm and package-lock.json. One install graph. |
| 04-zod-schemas | Zod at every boundary. No cast of untrusted input. |
| 05-oxlint-linting | Oxlint checks patterns of use. It does not format. |
| 06-oxfmt-formatting | Oxfmt owns layout. It does not lint. |
| 07-vitest | Vitest runs the module tests. No default DOM. |
| 08-ui-core | Tailwind, vendored shadcn, Base UI. The catalog stays in git. |
| 09-database | SQLite through Prisma. CUID2 ids. One ORM. |
| 10-env | Zod parses env. Flags are explicit. A set key is not a switch. |
| 11-msw-mocks | MSW intercepts vendor HTTP locally. Production does not start it. |
| 12-email | sendEmail. Resend is a fetch behind that function. |
| 13-auth | Magic link and GitHub. A session row. No passwords. |
| 14-routing | autoRoutes. Layouts are _layout.tsx only. |
| 15-payments | Stripe Checkout subscriptions, off until you turn them on. |
Skills
ai/skills/ holds the recipes. Read one before the matching job. A skill does not repeat what a tool file already says.
| Skill | When |
|---|---|
| plan | Plan a change, or you were told to write a plan. |
| implement | Implement a change. |
| expand-and-contract | Rename, drop, or retype a production column. |
| react-router | Add a route module, a loader, an action, or pending UI. |
| routing | Organize route files or add a URL. |
| validate | Format, lint, typecheck, or test. |
| bug-squash | A check fails, or the app is wrong. |
| deploy | Deploy, push, or land a change in production. |
| thank-you-page | Write the page a buyer sees after they pay. |
ai/guides/stripe-subscriptions.md is the one-time bring-up for turning subscriptions on. When that bring-up works, remove the guide and its row. The decision stays.