Create AGENTS.md

1 files changed, 74 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..14fee25
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,74 @@
+# AGENTS.md
+
+## Git discipline
+
+**Every feature or fix gets its own branch.** Never work directly on `main`.
+
+### Starting work
+```sh
+git checkout -b feat/<short-description>   # new feature
+git checkout -b fix/<short-description>    # bug fix
+```
+
+### Committing
+- Commit after every meaningful, compiling change — small commits make rollbacks painless.
+- Commit messages: imperative, lowercase, no period. E.g. `add attack animation`, `fix entity occlusion`.
+- Never commit broken code. Run `cargo build` before every commit.
+
+### Before merging
+```sh
+git checkout main
+git merge --no-ff feat/<branch>   # always a merge commit, preserves history
+```
+
+### Rollbacks
+- `git revert <sha>` to undo a specific commit without rewriting history.
+- `git reset --hard <sha>` only on local branches you haven't pushed.
+- If a branch goes off the rails, abandon it: `git checkout main && git branch -D feat/broken`.
+
+### Change tracking
+- `git --no-pager log --oneline --graph` to visualise history.
+- `git --no-pager diff main...feat/branch` to see what a branch adds before merging.
+- Tags for milestones: `git tag -a v0.1 -m "turn-based loop + entities + combat"`.
+
+---
+
+## Project structure
+
+```
+src/
+├── main.rs       — window, input, game loop
+├── game.rs       — game state, maze, entities, combat, inventory, animation
+├── renderer.rs   — ray-caster, entity sprites, HUD, screen effects
+└── texture.rs    — procedural texture generation (wall, floor, exit)
+docs/
+├── PLAN.md       — phased implementation plan
+├── CONTEXT.md    — canonical domain glossary
+└── adr/          — architecture decision records
+```
+
+## Build & run
+
+```sh
+cargo build              # debug build
+cargo build --release    # release (no console on Windows)
+cargo run                # build + run
+```
+
+No external build tools — just `cargo`.
+
+## Code style
+
+- Rust 2024 edition.
+- No `ref mut` in patterns (2024 makes it implicit).
+- `#[allow(dead_code)]` on deliberately unused scaffolding for future phases.
+- Public fields only where needed by other modules; prefer private otherwise.
+- Constants for magic numbers (`MOVE_DURATION`, `MAX_HP`, etc.).
+- Messages use `.to_uppercase()` for display — the 5×5 font only has uppercase glyphs.
+
+## Design philosophy
+
+- **Turn-based but smooth.** Player actions trigger discrete turns, but all movement is animated (180ms walk, 120ms turn, 120ms attack lunge).
+- **One cell, one entity.** A grid cell holds at most one enemy, hallucination, or pickup.
+- **The dungeon lies to you.** Hallucinations and fake pickups look real. Sanity controls how much the world gaslights the player.
+- **Weakness is hunger, not a timer.** It drains HP to 1 at max, but only enemies can kill you.