# AGENTS.md — fast map for agent sessions

Read [AGENT.md](AGENT.md) first; it is the binding entry point. This file is
only the navigation shortcut so sessions stop rediscovering the layout.

## Layout (post wiki migration, 2026-07-07)

- `DESIGN.md` — the constitution. Code follows it, never the reverse.
- `wiki/` — the single documentation tree. The old `spec/` and `knowledge/`
  directories are GONE; pages are typed by header (`Type: spec | knowledge |
  log`), not by directory:
  - `wiki/process/ROADMAP.md` — the dispatch board: work orders, suggested
    worktree names, parallel-conflict flags. Pick up work here.
  - `wiki/process/specs.md` — the spec status board (B1/B2/B3 tables).
  - `wiki/process/meta.md` — the spec format itself.
  - `wiki/mechanics/` — system specs (compute, detection, reach, cursor,
    intel, messages, economy, income, research, rollback, ...).
  - `wiki/interface/` — terminal style guide, views, agent-play protocol.
  - `wiki/world/` — places (basement-map, zplanes), characters (cast specs),
    story. `wiki/engineering/` — architecture, flow substrate.
  - `wiki/vision/` — design judgment. `wiki/log/` — the log index.
- `src/` — the sim lib. `sim.rs` is the orchestrator, `save.rs` the serde
  JSON save; these two are the parallel-agent conflict hotspots. Frontends
  are thin views: `src/bin/terminal/`, `src/bin/bevy.rs` (feature `bevy_ui`).
- `tools/check.sh` — the definition of done (fmt, tests, clippy both feature
  sets, bevy build, spec-header lint). Run before every commit.
- `wiki/log/` — one entry per session; `wiki/log/DEVLOG.md` is the ledger.
- `prompts/` — the dispatch library for sub-agent task types.

## Hard rules (from AGENT.md; the hooks enforce most of them)

- NEVER edit this main checkout. First action of any session: create a git
  worktree (`git worktree add .Codex/worktrees/<task> -b worktree-<task>
  origin/main`), do all edits/tests/commits there. Parallel sessions use the
  main checkout as shared ground; never `git reset`/`checkout --`/`stash` it.
- A commit touching `src/` must also touch `wiki/` or `DESIGN.md`
  (pre-commit hook + server-side Tangled pipeline). Behavior changes carry a
  `Defense:` paragraph in the commit message and the amendment in the same
  commit.
- Game rules live only in the lib; `Sim` never reads the wall clock or does
  I/O. Both frontends must surface any new system before its spec is
  IMPLEMENTED; set the spec `Status:` in the implementing commit.
- No emoji. No AI attribution in commits. `git add` only intended files —
  never `git add -A`.
- Ledger files (wiki/log/DEVLOG.md, the DESIGN.md decisions log, wiki status
  tables) merge by UNION — keep both sides' entries in any conflict.
- Landing: rebase onto `origin/main`, re-run `./tools/check.sh`, merge/push
  to main directly (the PR rule was removed 2026-07-07), then remove the
  worktree and delete its branch. No stale worktrees.
- Run at most ONE sim+save-heavy work order at a time (see the ROADMAP
  conflict flags); isolated items (frontend-only, test-only, docs) can run
  alongside anything.