adonisjs-starter-kit AGENTS.md

Agent instructions

Meta-rule

ALWAYS look for the existing pattern before writing anything new. This repo is highly consistent; new code should mirror the closest existing example, not invent shape. Search first, code second.

Scope

• Minimal diff. Prefer the smallest change that satisfies the request — don't refactor unrelated code, rename identifiers "on the way", or restructure imports beyond the diff.
• If the task drifts, ask before expanding scope.

Stack

AdonisJS 7 (session auth + Bouncer + Lucid), Inertia + React 19, Tailwind 4 + shadcn/Radix, Postgres 16, pnpm monorepo (Turbo).

Commands

• pnpm dev — dev server
• pnpm test — full suite
• pnpm typecheck && pnpm lint — before saying "done"
• pnpm infra:up — Postgres + Mailpit via compose
• pnpm ace <cmd> — Adonis CLI from the repo root (shortcut for pnpm --filter web exec node ace <cmd>)
• pnpm ace make:module <name> [--db] [--i18n] [--events] — scaffold a module and wire every touchpoint (alias, preload, migration path, tsconfig include, i18n loader)

Done criteria

Before reporting completion:

• Run pnpm typecheck && pnpm lint.
• Run the narrowest relevant test first (module functional spec) before falling back to pnpm test.
• If a required command failed to run (missing infra, no network, etc.), stop and report the failure with the relevant output — do not claim completion.

Architecture — module per bounded context

Every bounded context lives at app/<mod>/ as a self-contained module. A module owns the ubiquitous language of one context and may hold multiple aggregates inside — modules are not 1:1 with aggregates. Existing modules: auth, users, marketing, analytics, common, core, notifications. Each module dir is aliased as #<mod>/* in apps/web/package.json → "imports" — see the module-scaffolding skill to add one.

app/<module>/
  actions/            # single-purpose class with .handle(input)
  controllers/        # thin: validate → action → redirect/render
  queries/            # read-only Lucid query classes
  policies/           # extend BasePolicy, one per resource
  models/, mixins/, services/, exceptions/, enums/
  middleware/         # singular — HTTP middleware (registered in start/kernel.ts)
  transformers/
  validators/         # one file per entity — validators/users.ts, validators/tokens.ts
  database/{factories,migrations,seeders}/
  resources/lang/     # i18n JSON, per module per locale
  ui/                 # Inertia pages + React components
  mails/              # BaseMail classes — *_notification.ts (see the mail skill)
  notifications/      # Notification classes (if the module emits)
  types/events.ts     # EventsList declaration merge (if the module emits)
  start/{events,view}.ts
  routes.ts
  tests/{unit,functional}/