+1

CLAUDE.md

@@ -10,6 +10,12 @@ Pure Rust game: SDL3 windowing, wgpu rendering, rapier3d physics, low-res retro
 - **NO inline paths** — always add `use` statements at the top of files, never inline
 - **NO `use` statements inside functions or impl blocks** — all `use` must be at the file (module) level
 
+**Intent-Based Architecture:**
+- Systems don't call each other. Cross-system communication goes through **intents** — one-frame typed structs in `Storage<T>` queues on `World`
+- Producer inserts intent → consumer reads, acts, removes. Producer doesn't know which system processes it
+- The main loop is a flat pipeline; systems self-gate based on data presence
+- See `docs/self-gating-systems.md` for full pattern + examples
+
 **Storage Parameters:**
 - Functions should take specific storages they need rather than `&World` or `&mut World`
 - Pass individual fields (`&world.transforms`, `&mut world.state_machines`) at the call site