|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Guidance for coding agents working in this repository. Humans: see |
| 4 | +[`README.md`](README.md) to run it and [`docs/`](docs/) for the full design. |
| 5 | + |
| 6 | +## What this is |
| 7 | + |
| 8 | +An AI-driven, web-based D&D experience: an LLM Dungeon Master narrates, a |
| 9 | +deterministic rules engine adjudicates, multiple players share a real-time |
| 10 | +session, and art is generated on demand. Monorepo of npm workspaces |
| 11 | +(`packages/engine`, `protocol`, `server`, `web`). |
| 12 | + |
| 13 | +**Read [`docs/architecture.md`](docs/architecture.md) first** — it's the code map |
| 14 | +and the turn-flow walkthrough. The deeper rationale is in |
| 15 | +[`docs/DESIGN.md`](docs/DESIGN.md) (cited from source comments as `docs/DESIGN.md §N`). |
| 16 | + |
| 17 | +## The invariant you must not break |
| 18 | + |
| 19 | +> **The engine is the source of truth; the LLM only narrates.** |
| 20 | +
|
| 21 | +The LLM proposes actions through the tool layer (`server/src/gameEngine.ts`); the |
| 22 | +engine (`packages/engine`) validates, rolls dice (seeded), and applies results. The |
| 23 | +model never sets HP, decides hits, or invents numbers. If a change would let the LLM |
| 24 | +mutate state directly, it's wrong — route it through a tool that calls the engine. |
| 25 | + |
| 26 | +## Setup & commands |
| 27 | + |
| 28 | +Node 20+ (CI uses 22). From the repo root: |
| 29 | + |
| 30 | +```bash |
| 31 | +npm install |
| 32 | +npm run build --workspace @ai-dm/engine # MUST build engine first — others consume its dist/ |
| 33 | +npm run typecheck # all workspaces |
| 34 | +npm test # engine unit tests + server integration tests |
| 35 | +``` |
| 36 | + |
| 37 | +Run locally: |
| 38 | + |
| 39 | +```bash |
| 40 | +npm run dev:server # http + ws on :8787 (scripted DM, JSON store — no cloud needed) |
| 41 | +npm run dev:web # Vite on :5173, proxies /api and /ws to the server |
| 42 | +``` |
| 43 | + |
| 44 | +A single package: append `--workspace @ai-dm/<name>` to `typecheck`/`test`/`build`. |
| 45 | + |
| 46 | +## Before you say "done" |
| 47 | + |
| 48 | +Always, from the root: **`npm run build --workspace @ai-dm/engine && npm run typecheck && npm test`**. |
| 49 | +If you touched a package's behavior, add or update its tests. Report failures with the |
| 50 | +actual output — don't claim green you haven't seen. Tests are colocated as `*.test.ts` |
| 51 | +(engine: pure unit tests; server: `backend.test.ts` + focused loop/memory/dm tests). |
| 52 | + |
| 53 | +## Code conventions |
| 54 | + |
| 55 | +- **Strict TypeScript** (`tsconfig.base.json`): `strict`, `noUncheckedIndexedAccess`, |
| 56 | + `noImplicitOverride`, `verbatimModuleSyntax`. |
| 57 | +- **ESM / NodeNext:** relative imports use a **`.js` extension** even from `.ts` |
| 58 | + files (e.g. `import { x } from "./store.js"`). Type-only imports use `import type`. |
| 59 | +- **Seeded randomness only.** Never call global `Math.random()` in the engine or game |
| 60 | + logic — use the session's `RNG`, so turns replay identically and snapshots are exact. |
| 61 | +- **Wire types live in `@ai-dm/protocol`.** Don't redefine DTOs/messages in the web; |
| 62 | + import them. Changing a shape? Update protocol, then both sides. |
| 63 | +- **Match the surrounding style** (comment density, naming, idiom). Files carry a |
| 64 | + short top-of-file comment explaining their role and citing `docs/DESIGN.md §N` where |
| 65 | + relevant — keep that habit. |
| 66 | +- **Client never sees enemy stat blocks.** `CreatureView.sheet` is for PCs only. |
| 67 | + |
| 68 | +## Where things live |
| 69 | + |
| 70 | +| You want to change… | Look in | |
| 71 | +|----------------------|---------| |
| 72 | +| Rules / dice / combat math | `packages/engine/src/*` | |
| 73 | +| What the DM can *do* (tools) | `server/src/gameEngine.ts` | |
| 74 | +| DM prompt / context / scripted fallback | `server/src/dm.ts`, `geminiDm.ts` | |
| 75 | +| The turn loop / WebSocket | `server/src/index.ts` | |
| 76 | +| Session shape, snapshots, `toView` | `server/src/session.ts` | |
| 77 | +| Persistence | `server/src/store.ts`, `postgres.ts` | |
| 78 | +| Scaling (broadcast/lock/presence) | `server/src/realtime.ts`, `runtime.ts` | |
| 79 | +| Character building / spells / inventory / XP | `server/src/srd.ts`, `srdContent.ts` | |
| 80 | +| REST endpoints | `server/src/routes.ts` | |
| 81 | +| Wire types | `packages/protocol/src/index.ts` | |
| 82 | +| UI screens / play table | `packages/web/src/screens/*`, `components.tsx` | |
| 83 | + |
| 84 | +## Git & deployment |
| 85 | + |
| 86 | +- This repo deploys on **push to `main`** via GitHub Actions → Cloud Run. Don't push |
| 87 | + or commit unless the user asks; branch off `main` if they do. |
| 88 | +- Commit messages end with the trailer: |
| 89 | + `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>` |
| 90 | +- After a deploy, **verify the run's conclusion** (`gh run view <id> --json conclusion`), |
| 91 | + not just that the command exited — `gh run watch` can report success for a run that |
| 92 | + already failed. |
| 93 | +- Deployment setup and topology: [`docs/DEPLOY.md`](docs/DEPLOY.md); infra is Terraform |
| 94 | + in [`infra/`](infra/). |
| 95 | + |
| 96 | +## Gotchas learned the hard way |
| 97 | + |
| 98 | +- **Build the engine before typecheck/test**, or you'll hit `Cannot find module |
| 99 | + '@ai-dm/engine'`. |
| 100 | +- **Backtick characters inside SQL string templates** in `postgres.ts` break the JS |
| 101 | + template literal — avoid them in comments there. |
| 102 | +- **`ensureCharacterFields` runs on read** and must stay idempotent (returns `true` |
| 103 | + only when it actually changed something). New backfills go there. |
| 104 | +- Cloud Run reserves `/healthz` at the frontend — the health endpoint is `/api/health`. |
0 commit comments