Imported from movahedan/fivenines (
AGENTS.md). Install upstream withnpx skills add movahedan/fivenines. Copyright stays with the author.
AGENTS.md
Guidance for agents working in this monorepo. Map and pointers — standards in rules; procedures in skills; human setup in Build guide; commands in docs/CHEATSHEET.md. Intended product behavior and domain model: docs/product. Milestone delivery policy: docs/milestones. Technical execution plans stay in .cursor/plans; do not use them as the product reference. Human product pitch and how-to-play: wiki. Do not copy kernel formulas, ports, or cheatsheet tables into the wiki; do not treat the wiki as tick/economy truth. License: LICENSE (PolyForm Noncommercial 1.0.0).
Code review (Cursor and GitHub Copilot): the rubric lives in .github/copilot-instructions.md and path files under .github/instructions/. Read those when reviewing a diff or PR — do not invent a second checklist. Nested AGENTS.md files are implementation truth; they point at the matching instruction file. Copilot loads the .github files natively (settings). Cursor loads them because this map and code-review.mdc say to. Do not copy .cursor/rules/*.mdc into Copilot files.
Standards (.cursor/rules/)
| Rule | When |
|---|---|
| repo-invariants.mdc | Every session (always) |
| typescript.mdc | .ts / .tsx edits |
| security.mdc | .ts / .js (ReDoS, validation, auth) |
| testing.mdc | *.test.ts / *.spec.ts |
| clean-dom.mdc | UI apps + packages/ui |
| advisor.mdc | Review / trade-offs (@advisor or intelligent apply) |
| code-review.mdc | Cursor review: load .github/copilot-instructions.md |
Enforced by tooling: tools/typescript/base.json, biome.json.
Cursor skills
| Skill | Role |
|---|---|
| initiative-workflow | plan → build → docs → PR (per phase) |
| planning-workflow | .cursor/plans/*.plan.md |
| builder-workflow | Code/config execution; orchestration for Task spawn |
| documentation-sync | Plan doc list after build, before PR |
| git-pr-workflow | Commit, push, PR |
| monorepo-script-commands | Ink CLIs under tools/scripts/ |
Essential commands
Setup: Build guide · Commands: docs/CHEATSHEET.md.
bun run overall— quality gate (Lefthook pre-push runs the same with--quiet)bun test— tests (bunfig.toml+tools/tests-preset)bun run turbo run dev --filter=@apps/web— player UI Start SPA (hub/lab need Nest on :3002)bun run precommit— staged files, branch name, commit message
Architecture overview
Five Nines is a cloud tycoon: the kernel (@packages/fivenines-engine) owns demand, capacity, wallet/opex/jail, SLA ppm, and PAYG week close. @apps/web is the marketing site plus /hub ops console and /lab debug harness — hub/lab construct Game in the browser for now. Nest campaign/SSE is later.
Turborepo monorepo, Bun package manager and runtime.
Prerequisites: Git, Bun 1.4.2 (see root packageManager), Docker (full stack), Node ≥ 26, ~8GB+ RAM.
Day-to-day: dev stack on the host with bun run container … — docker-compose.dev.yml at repo root (Docker Compose).
Workspace names
Use each workspace’s package.json#name in Turbo --filter, compose, and commit scopes.
| Area | Examples |
|---|---|
apps/* |
@apps/web, @apps/nestjs, @apps/auth |
packages/* |
@packages/ui, @packages/shared, @packages/shared-react, @packages/shared-tanstack |
packages/* |
@packages/fivenines-engine |
tools/* |
@tools/scripts, @tools/typescript, @tools/tests-preset |
Repo layout
| Path | Role |
|---|---|
apps/, packages/ |
Applications and shared libraries |
tools/ |
TS presets (typescript/), test preset (tests-preset/), Bun CLIs (scripts/) |
docs/ |
Guides — CHEATSHEET, SCRIPTING, AUTO_VERSIONING, GITHUB_WORKFLOW_ENV |
turbo.json, biome.json, bunfig.toml |
Build, lint, test preload |
Nested AGENTS.md under each app, package, and tool workspace.
Workspaces
| Path | name |
Port | Role | Guide |
|---|---|---|---|---|
apps/figma-design |
@apps/figma-design |
3010 | Preserved Figma visual reference, local preview only; no production gameplay | AGENTS.md |
apps/web |
@apps/web |
3000 | Player + marketing UI (TanStack Start SPA, nginx dist/client); /hub /lab client Game |
AGENTS.md |
apps/nestjs |
@apps/nestjs |
3002 | Feature flags control plane (OpenAPI) | AGENTS.md |
apps/auth |
@apps/auth |
3001 | Auth (JWT, refresh, M2M). SSR login/register/OTP use ops tokens, not @packages/ui |
AGENTS.md |
packages/ui |
@packages/ui |
9000 | React + Storybook | AGENTS.md |
packages/analytics |
@packages/analytics |
— | Silktide consent + GTM after analytics consent (no Firebase) | AGENTS.md |
packages/fivenines-engine |
@packages/fivenines-engine |
— | Simulation kernel (Game.tick / dispatch): physics, wallet/opex/jail, SLA 168h ring, PAYG + week close |
AGENTS.md |
packages/shared |
@packages/shared |
— | Shared utilities | AGENTS.md |
packages/auth |
@packages/auth |
— | Auth session, React provider, scopes/JWT contract | AGENTS.md |
packages/http |
@packages/http |
— | HTTP fetcher (client / server / static; Orval mutator shape) | AGENTS.md |
packages/nestjs-sdk |
@packages/nestjs-sdk |
— | Orval client for @apps/nestjs |
AGENTS.md |
packages/shared-react |
@packages/shared-react |
— | Shared React hooks | AGENTS.md |
packages/shared-tanstack |
@packages/shared-tanstack |
— | TanStack list/virtual helpers | AGENTS.md |
Tools (tools/)
| Path | Role |
|---|---|
tools/scripts |
Bun CLIs (local, container, overall, …) — SCRIPTING.md |
tools/typescript |
TS presets — AGENTS.md |
tools/tests-preset |
Test preload + Testing Library — AGENTS.md |
Root package.json delegates to tools/scripts/ for Ink CLIs.
Docker Compose (host)
bun run container setup
bun run container up
bun run container checkProd-shaped file: bun run container --prod up. Extra compose flags after --: bun run container up -- --build. Help: bun run container.
Troubleshooting
- Docker —
bun run container compose -- ps - Postgres 18 volume — Compose mounts
postgres_dataat/var/lib/postgresqlwithPGDATA=/var/lib/postgresql/18/docker. A volume from 17 (.../data) will not start. Reset (bun run container cleanup) or dump/restore. - Hosts —
play.fivenines.com/auth.fivenines.com/api.fivenines.comin/etc/hosts(CHEATSHEET) - Container deps —
bun run container installafter new packages (namednode_modulesvolume;up --builddoes not refresh it) - Deps —
bun run local cleanup+bun install, orbun run nuke - Tests —
bun test packages/ui/src/…; preset: tools/tests-preset/AGENTS.md - Filters — workspace
namefrompackage.json, not folder name alone - Lint/types —
bun run lint -- --write,bun run typecheck
Dependabot: .github/dependabot.yml · docs/DEPENDABOT.md.
Stack notes
React 19, TanStack Start SPA (@apps/web static dist/client), NestJS, Orval, Tailwind, Biome, Lefthook, Docker Compose (bun run container …). Auth stays SSR in @apps/auth.
Read the nested AGENTS.md for the area you touch before editing.
When working with this codebase, run bun run overall before committing unless a narrower plan gate applies. Push runs it again via Lefthook. GitHub Overall is the same gate on Actions (required on main). GitHub Check is production compose for affected services, not that gate.