init repo

AGENTS.md

@@ -0,0 +1,78 @@
+# Bevy Game Project Rules
+
+## Mission
+
+Build game features fast, but keep code clean enough to survive workshop iteration.
+Target stack:
+
+- Rust `1.95.0`
+- Bevy `0.18.1`
+- 2D first
+- local assets in `assets/`
+
+## Hard rules
+
+- Use Bevy `0.18.1` APIs only.
+- Prefer Bevy built-ins before adding third-party crates.
+- Keep compile loop short. Small steps. Small diffs.
+- No giant god-systems. Split logic into focused systems and plugins.
+- Keep rendering, input, gameplay, UI, and debug concerns separate.
+- New feature must include:
+  - code change
+  - short reason
+  - how to run
+  - what to test manually
+- After code edits run, in order:
+  1. `cargo fmt --all`
+  2. `cargo check`
+  3. `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+- If command fails, quote exact error.
+- Do not migrate versions unless asked.
+- Do not invent APIs. Check local files first, then docs index in `docs/ai/bevy-source-index.md`.
+
+## Bevy design rules
+
+- App setup in `main.rs` stays thin.
+- Put features in plugins under `src/` when project grows.
+- Use:
+  - Components for entity data
+  - Resources for singleton state
+  - Events for loose coupling
+  - States for game flow
+- For temporary prototypes, prefer explicit code over macro cleverness.
+- Keep startup systems idempotent where possible.
+- Use `Name` on important entities in debug-heavy scenes.
+- Asset paths relative to `assets/`.
+
+## Architecture defaults
+
+When adding real gameplay, move toward this split:
+
+- `src/game/` core gameplay plugin
+- `src/player/` player components + systems
+- `src/ui/` UI plugin
+- `src/state/` app/game states
+- `src/debug/` debug helpers
+
+## Review checklist
+
+Before final answer:
+
+- Is ECS layout sane?
+- Are system names specific?
+- Are queries minimal?
+- Is state transition explicit?
+- Is UI separate from gameplay?
+- Are commands deferred only where needed?
+- Is code Bevy-idiomatic for `0.18.1`?
+- Did you list exact run/test commands?
+
+## AI context files
+
+Read when useful:
+
+- `docs/ai/bevy-quick-reference.md`
+- `docs/ai/bevy-project-patterns.md`
+- `docs/ai/bevy-debug-playbook.md`
+- `docs/ai/workshop-scope.md`
+- `ai/context/project-context.md`