92 lines
4.2 KiB
Markdown
92 lines
4.2 KiB
Markdown
# AGENTS.md
|
||
|
||
Guidance for AI coding agents (Cursor, Claude Code, Copilot, Codex, and similar) working in this repository.
|
||
|
||
## EchoVault (required)
|
||
|
||
This project uses the **EchoVault** MCP server (`user-echovault`) as persistent memory across sessions.
|
||
Use it aggressively. Skipping it means the next agent starts from zero.
|
||
|
||
### When to call what
|
||
|
||
| Tool | When |
|
||
| --- | --- |
|
||
| `memory_context` | **Session start** and after a major topic change. Loads recent decisions for this project. |
|
||
| `memory_search` | Before work on a familiar/unclear topic, and whenever the user’s request may relate to prior decisions or bugs. |
|
||
| `memory_save` | **Before ending** any session where you made decisions, fixed bugs, discovered non-obvious patterns, or changed architecture/infra. Not optional. |
|
||
|
||
Prefer `project: "the-living-world"` when the tool accepts a project filter.
|
||
|
||
### What to save
|
||
|
||
Save when you:
|
||
|
||
- Chose an approach (X over Y) or fixed a non-obvious bug
|
||
- Learned something about this codebase that is not obvious from reading the code
|
||
- Set up tooling/config the next agent will need
|
||
- Were corrected or given a durable requirement by the user
|
||
|
||
Do **not** save: typos, pure formatting, facts already clear from the code, or duplicates of existing memories.
|
||
|
||
### How to write a good memory
|
||
|
||
- `title` — short (≤60 chars)
|
||
- `what` — 1–2 sentences the next agent needs
|
||
- `why` / `impact` — reasoning and what changed
|
||
- `category` — one of: `decision`, `bug`, `pattern`, `learning`, `context`
|
||
- `tags` / `related_files` — so search can find it
|
||
- `details` — write for an agent with **zero** context. Prefer:
|
||
|
||
```
|
||
Context
|
||
Options considered
|
||
Decision
|
||
Tradeoffs
|
||
Follow-up
|
||
```
|
||
|
||
### Session checklist
|
||
|
||
1. Call `memory_context` (and `memory_search` if the task is specific).
|
||
2. Do the work.
|
||
3. Call `memory_save` for every meaningful decision or fix before you stop.
|
||
|
||
## Project snapshot
|
||
|
||
The Living World is a web game whose map is a real place: the API imports OpenStreetMap via Overpass into an Arch ECS world and serves chunked geometry; a PixiJS client renders it.
|
||
|
||
| Area | Path / stack |
|
||
| --- | --- |
|
||
| API | `src/TheLivingWorld.Api` — .NET 10, minimal APIs |
|
||
| Core / ECS | `src/TheLivingWorld.Core` — Arch, geo, export |
|
||
| OSM import | `src/TheLivingWorld.Osm` — Overpass + import pipeline |
|
||
| Web client | `src/TheLivingWorld.Web` — TypeScript, Vite, PixiJS 8 |
|
||
| Aspire host | `src/TheLivingWorld.AppHost` |
|
||
| Tests | `tests/TheLivingWorld.Tests` (xUnit), Vitest under the web project |
|
||
|
||
Worlds are stored as files under `data/` (not committed). Cap: `WorldStorage:MaxConcurrentWorlds`.
|
||
Ready worlds run a live game clock on the server (5 game minutes per real second at x1; default start
|
||
12 April 2012 06:00) plus weather: a Köppen-lite climate preset per world, with drifting pressure systems as
|
||
ECS entities on top of a deterministic seasonal/diurnal baseline. UI: main menu (list + create, with a climate
|
||
picker) → map screen with pause, speed, clock and weather, and a renderer that washes the map for time of
|
||
day, cloud, fog and lying snow and drops rain or snow through it.
|
||
|
||
New ECS components must be added to the probe entity in `SimulationComponents` — Arch assigns component type
|
||
ids on first use without a lock, and two threads racing there hand out the same id.
|
||
|
||
`StoredWorldDto` is what `state.json` holds; `WorldSummaryDto` is what clients get. Cross only via
|
||
`ToSummary()` — the wire type deliberately has no field for the simulation's bookkeeping.
|
||
|
||
Keep wire DTOs in sync: `TheLivingWorld.Core.Contracts` and `src/TheLivingWorld.Web/src/api/types.ts`.
|
||
|
||
## Working conventions
|
||
|
||
- Prefer small, focused diffs. Do not rewrite unrelated code or add docs the user did not ask for.
|
||
- Match existing naming, comments, and file layout.
|
||
- Backend tests: `dotnet test tests/TheLivingWorld.Tests/TheLivingWorld.Tests.csproj`
|
||
- Frontend checks: `npm --prefix src/TheLivingWorld.Web test` and `npm --prefix src/TheLivingWorld.Web run typecheck`
|
||
- Full stack: `run.cmd` or `dotnet run --project src/TheLivingWorld.AppHost`
|
||
- Do not commit unless the user asks. Do not invent secrets or commit `data/`.
|
||
|
||
Details of the import pipeline, API surface, and renderer live in [README.md](README.md) — read that before large map/API changes.
|