# AGENTS.md — subagent constitution for C/Raylib project

> **This is loaded by every agent.** It contains ONLY project-specific,
> non-obvious rules. Never restate what a frontier model already knows about C
> or raylib.

---

## 1. C dialect & build rules

- **C99** (`-std=c99`). No C11/C17 features.
- **Compile with `-Wall -Wextra`** — zero warnings. If you cannot silence a
  warning without reducing correctness, flag it in your report.
- **Raylib is the ONLY external library.** Include `raylib.h` for all platform
  APIs (windowing, audio, input, font loading, drawing). Never include glfw,
  miniaudio, or stb headers directly. For web: `emscripten.h` is allowed behind
  `#ifdef PLATFORM_WEB`.
- **`build/font_data.h`** (generated by `xxd` from `resources/`) is an
  **array definition**, not a declaration. Include it in EXACTLY ONE `.c` file
  (currently `ui.c`). Guard its use with `#if FONT_EMBEDDED`. Never include it
  from a `.h` file or from multiple `.c` files — that causes multiple-definition
  link errors.
- **No dynamic allocation** unless paired with an explicit free in the same
  module's cleanup. No leaks.
- **No VLAs** (variable-length arrays on the stack). Use fixed-size buffers or
  guard with `MAX_*` constants.

## 2. Module boundaries (THE KEY RULE)

- **Your `.h` file IS your contract.** It declares every public type, constant,
  and function signature that other modules consume. Keep it minimal —
  consumers should not see implementation details.
- **Your `.c` file IS your implementation.** It is PRIVATE. Static functions
  are module-internal. No other module includes your `.c` file — ever.
- **Include guards:** Every `.h` file starts with `#pragma once`.
- **Self-contained headers:** A `.h` file must `#include` all types it
  references (directly or via forward declaration). Consuming agents should
  need to include ONLY your `.h`, not hunt for transitive includes.
- **Forward-declare when possible:** `typedef struct PlayerState PlayerState;`
  in a header avoids pulling in the full `types.h` when only a pointer is
  needed.

## 3. State management

- **No global mutable variables.** All shared state lives in `PlayerState` and
  is passed by pointer.
- **File-scope statics** are allowed ONLY for module-private data (e.g. cached
  fonts, colors, layout constants in the UI module).
- **Const correctness:** Mark pointers `const` when the function does not
  mutate the data. Example: `const char *path` in functions that only read.

## 4. Naming & vocabulary

- **Prefix public functions** with the module name or a clear namespace:
  - `player_*` for player module
  - `study_*` for study module
  - `ui_*` for UI module
- **Static helpers** (module-internal) may omit the prefix.
- **Verb-first naming:** `player_load`, `player_seek`, `study_detect_silence`.
- **Vocabulary is governed by `GLOSSARY.md`.** Reuse existing terms; never invent
  a synonym for a concept that already has a canonical name (see its "Avoid
  calling it…" column). Prefer standard, training-baked names over novel ones.
  If you genuinely need a new term, propose it — do not coin one silently in
  code.

## 5. Testing & verification

- **Build is the primary test.** If `make` exits 0 with zero warnings, your
  module compiles and links correctly.
- **If you add a new `.c` file**, note it in your report. The Makefile uses
  `$(wildcard src/*.c)` so new modules are auto-discovered — no `SRCS` edit
  needed. The orchestrator owns the Makefile for any structural changes.

## 6. What you may read from other modules

- **YES:** The `.h` header files of other modules (their contracts).
- **NO:** The `.c` implementation files of ANY other module. If you think you
  need to read a sibling's `.c` to understand its behavior, STOP — that means
  the `.h` contract is underspecified. Report this to the orchestrator.

## 7. Report format

After completing your work, write `reports/<module>.md` with:
1. **Files touched** (list paths)
2. **What you implemented** (bullet list of functions/changes)
3. **Build result** (`make` output — exit code + any warnings)
4. **Issues or contract gaps** discovered
5. **Any changes needed in other modules** (e.g. "study.h needs a new function
   declaration")

Keep the report concise — the orchestrator reads many of these per wave.

## 8. Tribal knowledge (`notes/`)

- **What it is:** project-specific, non-inferable knowledge and scar tissue —
  the operational gotchas, environment quirks, and hard-won debugging facts that
  a fresh frontier model could NOT derive by reading the source. This is the
  only kind of prose that belongs in docs here.
- **The test (P6):** *Could a fresh frontier model figure this out by reading
  the code? If yes, leave it out.* Never restate generic C/raylib/Linux
  best-practice the model already knows — that is noise.
- **Where it lives:** `notes/<topic>.md`, one file per topic. Existing entries:
  - `notes/restructure-plan.md` — module-decomposition plan
  - `notes/wsl-arch-razer-run.md` — running the desktop app under WSLg on the
    Arch/Razer dev machine (the `LIBGL_ALWAYS_INDIRECT` segfault trap)
- **When you add one:** after solving something non-obvious — a crash that only
  reproduces in one environment, a build/run invocation that needs specific env
  vars, an undocumented platform constraint. Write the symptom, the root cause,
  and the fix. Keep it to the non-inferable facts only.