nara AGENTS.md

Nara - Project Knowledge Base

Skills: Deep-dive procedures live in .agents/skills/ — load on demand.

AI Quickstart — First time here?

Read in this order (each builds on the previous):

1. This file — conventions, anti-patterns, dependency policy, common pitfalls, structure. ~270 lines.
2. routes/web.ts — all routes in one file. API surface at a glance.
3. .agents/skills/SKILL.md — skill index. Load relevant skill when touching that pattern.
4. docs/decisions/ — ADRs explain WHY decisions were made. Read when questioning a convention.

For database schema: ls migrations/ to see table names, read the specific migration file for column types and constraints.

Then verify your work with one command:

npm run check    # lint + frontend type check + layer lint + tests

Scaffold a new resource with one command:

npm run gen:resource products -- --fields="name:string,price:number"

Overview

AI-first TypeScript full-stack starter kit. Functions over classes, raw SQL over ORM, minimal abstractions.

• Backend: ultimate-express (uWebSockets.js) + better-sqlite3
• Frontend: Svelte 5 + Inertia.js + Bits UI (headless UI)
• Auth: Session-based + RBAC
• Validation: Zod

Philosophy

• No classes — functions only
• No unnecessary comments — code is self-documenting
• No abstractions — inline is fine
• Raw SQL — AI writes SQL, we just execute it
• Minimal code — less code = less bugs

Golden Principles

Opinionated, mechanical rules that keep the codebase legible for agents. Enforced by lint:layers, check:agents, check:security, or convention tests. Violations block commit.

1. Functions over classes — export const fn = () => ... or export function fn(). Never class. (ADR 0002, enforced structurally)
2. Raw SQL over ORM — write SQL in queries/, never use Prisma/Drizzle/Knex. (ADR 0001, dependency policy)
3. Descriptive handler names — createUser, addRole, listProducts. Never generic index/store/create/update/destroy. (ADR 0009, L11-L12)
4. Layer boundaries are hard — handlers → queries → services → core. Import direction enforced. Queries never import handlers. Validators never import services. (L14-L17)
5. Two response types, never mixed — page routes return res.inertia(), data routes return jsonSuccess()/jsonError(). (L3-L4)
6. api() wrapper for all frontend HTTP — never raw fetch() or axios in components, never router.post/put/patch/delete. (L5-L7)
7. Svelte 5 runes only — $state, $derived, $effect, $props. Never onMount, $:, export let, or Svelte stores. (L8)
8. Logger, not console — Logger.info/warn/error. console.log only in bootstrap files where Logger isn't initialized. (L9)
9. hashPassword() from Authenticate, never bcrypt direct — the wrapper enforces the correct cost factor. (L10)
10. English for all user-facing messages — error messages, toast, validation. (ADR 0010)
11. AGENTS.md stays in sync with code — every documented directory has an AGENTS.md, every Structure table matches the actual files. (check:agents, convention test)
12. Files stay small — source files under 500 lines. Split before they grow into monsters. (check:filesize)
13. Docs links resolve — no broken markdown links in AGENTS.md, skills, or ADRs. (check:links)
14. No new any — type safety is non-negotiable. Existing any is baselined; new any blocks CI. Use proper types. (check:types)