# AGENTS.md — REBNO Project Instructions

## Project

**REBNO** — ground-up rebuild of *BN Online* (a late-1990s/early-2000s GameMaker 5.3a multiplayer game) on a modern web stack. Target: Chrome users walk around and chat in real time, then full feature parity with the original.

**Core Value:** Original BN Online players can open Chrome, log in with their migrated account, walk around, and chat with each other in real time — bug-free.

## Source-of-Truth Files

Everything depends on two files in `legacy/open-source-release/`:

- `BN Online Client 5-8.gmd` — latest client revision
- `BN Online Master 5-4.gmd` — latest server revision

Older revisions in `legacy/source-archive/` and `legacy/servers/` are reference-only. Do not target them as primary inputs.

## Repo Layout

| Path | Purpose |
|---|---|
| `decomp/wiki/` | 17-doc reverse-engineering knowledge base for GameMaker 5.3a — read these before reasoning about extraction, the `.gmd` format, the 39dll wire protocol, or `.bno`/`.bnb`/`.bnu` save data |
| `legacy/open-source-release/` | Authoritative source `.gmd` files (the two listed above) |
| `legacy/source-archive/`, `legacy/servers/` | Older revisions — reference only |
| `legacy/unity-project/`, `legacy/maya-project/` | Prior abandoned remake attempts and original Maya assets — informative, not authoritative |
| `legacy/audio/`, `legacy/open-source-release-extras/` | Original audio + assorted artifacts |
| `.planning/` | GSD workflow state — see below |
| `.planning/codebase/` | 7 docs mapping the existing brownfield codebase |
| `.planning/research/` | 5 docs of project-level research (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY) |

## Tech Stack (decided)

- **Server**: Node 22 + TypeScript + Colyseus 0.17 + `ws` + Better-Auth + argon2id + better-sqlite3 + Litestream
- **Client**: TypeScript + Vite — engine = Phaser 3 (preferred) OR PixiJS (fallback). Final choice locked by ADR at end of Phase 2.
- **Transport**: WebSocket binary frames; authoritative server; clients send intent
- **Persistence**: SQLite + Litestream → Tigris bucket on Fly.io. Postgres only if Phase 3 surfaces a relational requirement.
- **Hosting**: Fly.io single machine, persistent volume, <50 CCU target
- **Monorepo**: pnpm workspaces. Shared packages: `protocol` (wire types + codec) and `game-logic` (pure deterministic simulation, runs in Node + browser identically).

See `.planning/research/STACK.md` for version pins, alternatives matrix, and Fly.io specifics.

## Hard Rules

1. **Server-authoritative.** Clients send intent. Server emits state. Never trust client positions, scores, chat origin.
2. **No faithful port of plaintext passwords.** Original `localList.txt` plaintext archive is a security incident, not a feature. argon2id from packet 1.
3. **No faithful port of "run clipboard as superuser" admin.** Original RCE-as-a-feature admin model is replaced by a separate authenticated web UI in Phase 7.
4. **`.bno` / `.bnb` / `.bnu` parsing requires extracted GML first.** These formats only exist as the call order of `file_bin_*` ops in the project's own GML. Do NOT hex-inspect; extract Phase 1, derive Phase 3, parse Phase 4+.
5. **39dll wire protocol = call order.** Same principle. Reverse it from `write*`/`read*` sequences in extracted Master GML, not from packet captures.
6. **Extract → document → rewrite, in that order.** Phases 1-3 produce schemas; Phases 4+ consume them. No new TypeScript before Phase 4.
7. **Modern decompilers (UTMT, Altar.NET) cannot read GM 5.3a.** Use era-appropriate tools: GM Decompiler v2.1, GMD-Recovery, LateralGM, in a WinXP VM. See `decomp/wiki/13-modern-tool-incompat.md`.
8. **Repo stays private through Phase 7.** BNO is Capcom-derived (Mega Man Battle Network). Legal/IP path deferred. Verify `legacy/` is not pushed publicly until cleared.

## GSD Workflow

This project uses the GSD (Get Shit Done) phased-execution system. Workflow state lives in `.planning/`:

- `PROJECT.md` — project context, requirements, constraints, decisions (read first)
- `REQUIREMENTS.md` — 49 v1 requirements with REQ-IDs, traceability table
- `ROADMAP.md` — 7 phases with goals, requirement mapping, success criteria
- `STATE.md` — current phase + status (read to know where work is)
- `config.json` — workflow preferences (mode=yolo, granularity=standard, parallelization=on, model_profile=quality, research=on, plan_check=on, verifier=on)
- `research/` — project-level research outputs (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY)
- `codebase/` — codebase map (STACK, INTEGRATIONS, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, CONCERNS)

### Workflow Discipline

- **Per-phase flow**: `/gsd-discuss-phase N` → `/gsd-plan-phase N` → `/gsd-execute-phase N` → `/gsd-verify-work N`
- **Atomic commits**: Each phase commits its artifacts immediately. Use `gsd-sdk query commit "msg" <files>`.
- **Phases 1-3 do NOT parallelize with Phase 4+.** Within a phase, parallel plan execution is fine.
- **Hard milestone**: CLI-08 in Phase 6 — two players move + chat over deployed server. Entire rebuild gates here.
- **Research-flagged phases** (1, 3, 7) need deeper per-phase research at planning time.

## Phase Roadmap (high level)

1. **Extraction** — both `.gmd` → diffable per-resource trees (8 reqs)
2. **Client Engine Documentation** — document client engine + Phaser/Pixi ADR (4 reqs)
3. **Server Documentation & Schemas** — reverse 39dll, save formats, persistence ADR, closed parity checklist (6 reqs)
4. **Server Rebuild (MVP)** — Node + Colyseus authoritative server for movement+chat slice (12 reqs)
5. **Deploy** — Fly.io + Litestream + CI/CD + restore runbook (8 reqs)
6. **Client Rebuild — MVP Gate** — Vite+Phaser/Pixi client, **CLI-08 hard milestone** (10 reqs incl. AST-01)
7. **Full Parity** — closed parity checklist resolved + admin UI + asset pipeline (11 reqs)

See `.planning/ROADMAP.md` for full goals, success criteria, and dependencies.

## Conventions

- **Code**: TypeScript everywhere. Strict mode. Shared types via `packages/protocol`.
- **Docs**: Markdown. Per-asset documentation goes under `docs/extracted-engine/` and `docs/extracted-server/` once Phases 2/3 produce them.
- **ADRs**: `docs/adr/NNNN-title.md` for any decision that locks future work.
- **Commits**: Each plan = one commit. Commit messages reference REQ-IDs where applicable.

## Requirements Traceability (traceable-reqs)

The repo uses [traceable-reqs](https://github.com/BigscreenVR/traceable-reqs) for tag-based requirements tracing. The manifest at `traceable-reqs.toml` is authoritative for the 61 v1 requirement IDs in canonical form `REQ-<PREFIX>-<NUM>` (e.g. `REQ-SRV-03`). Human prose in `.planning/REQUIREMENTS.md` and `ROADMAP.md` may continue to use the bare prefix form (`SRV-03`, `CLI-08`) — these are the same IDs.

### Tagging contract — applies to every plan, every agent

When a plan produces an artifact that satisfies a requirement, embed a tag in the artifact:

| Stage  | Where it lives                                | Tag form                  |
|--------|-----------------------------------------------|---------------------------|
| `doc`  | Markdown — prose, ADRs, runbooks              | `[doc->REQ-CDOC-01]`      |
| `impl` | TS / Rust / C / C++ / Python source comments  | `// [impl->REQ-SRV-03]`   |
| `unit` | Unit-test source comments                     | `// [unit->REQ-SRV-03]`   |
| `int`  | Integration / E2E test source comments        | `// [int->REQ-CLI-08]`    |

Rules:

- Tags live **only in comments** (Rust/TS/C/C++/Python) or **on any line** in Markdown.
- Multiple tags on one line are allowed and counted independently: `// [impl->REQ-SRV-03] [impl->REQ-SRV-04]`.
- A tag pointing at an ID not in `traceable-reqs.toml` is an `undeclared_id` finding — fix the typo or add the requirement.
- A bracketed token containing `->` that doesn't exactly match `[stage->REQ-ID]` is a `parse_error` — no internal spaces.
- Default `required_stages = ["doc"]`. Code-bearing requirements add `impl`/`unit` to their `required_stages` at phase plan time, not before.

### Verifying

```bash
pnpm trace:list              # list reqs and stage status
pnpm trace:check             # exit non-zero if any finding
pnpm trace:check:json        # structured JSON for CI / agents
traceable-reqs trace REQ-SRV-03   # drill down on one req
```

Phase verification (`/gsd-verify-work`) treats `missing_stage` for the **phase's reqs** as a verification failure. CI hard-gate (`pnpm trace:check` blocks merge) is deferred to Phase 5 alongside the GitHub Actions pipeline (DEP-04). Until then, run `pnpm trace:check` locally before claiming a phase complete.

### Adding or modifying requirements

1. Add the human row to `.planning/REQUIREMENTS.md` (bare prefix form).
2. Mirror to `traceable-reqs.toml` as `REQ-<PREFIX>-<NUM>` with the same title.
3. Set `required_stages` only for the stages the requirement genuinely needs — start with `doc` and tighten at plan time.
4. Update `ROADMAP.md` mapping if the phase changes.
5. Run `pnpm trace:check` to confirm the manifest parses and IDs match what's tagged.

## Reference

- Reverse-engineering wiki entry point: `decomp/wiki/00-overview.md`
- Extraction pipeline procedure: `decomp/wiki/15-extraction-pipeline.md`
- Wire-protocol notes: `decomp/wiki/08-39dll-networking.md`
- Save-format notes: `decomp/wiki/16-bno-bnb-notes.md`
- Concerns / risks (read before planning): `.planning/codebase/CONCERNS.md`

---
*Generated: 2026-05-02 at project initialization*