Comment by numpy-thagoras

Here you go:

  # ASCII RPG

  This repo uses Rust + Bevy (0.16.1), multi-crate workspace, RON assets, and a custom ASCII UI. The rules below keep contributions consistent, testable, and verifiable.

  ## Quick rules (read me first)
  - Read/update CURRENT_TASK.md each step; delete when done.
  - Build/lint/test (fish): cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
  - Run dev tools: asset-editor/dev.fish; debug via /tmp/ascii_rpg_debug; prefer debug scripts in repo root.
  - Logging: use info!/debug!/warn!/error! (no println!); avoid per-frame logs unless trace!.
  - ECS: prefer components over resource maps; use markers + Changed<T>; keep resources for config/assets only.
  - UI: adaptive content; builder pattern; size-aware components.
  - Done = compiles clean (clippy -D warnings), tests pass, verified in-app, no TODOs/hacks.
  - If blocked: state why and propose the next viable step.
  - Before large refactors/features: give 2–3 options and trade-offs; confirm direction before coding.

  ## 1) Build, lint, test (quality gates)
  - Fish shell one-liner:
   - cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
  - Fix all warnings. Use snake_case for functions/files, PascalCase for types.
  - Prefer inline rustdoc (///) and unit tests over standalone docs.

  ## 2) Run and debug (dev loop)
  - Start the app with debug flags and use the command pipe at /tmp/ascii_rpg_debug.
  - Quick start (fish):
   - cargo run --bin app -- --skip-main-menu > debug.log 2>&1 &
   - echo "debug viewport 0 0" > /tmp/ascii_rpg_debug
   - echo "ui 30 15" > /tmp/ascii_rpg_debug
  - Helper scripts at repo root:
   - ./debug.sh, ./debug_keyboard.sh, ./debug_click.sh, ./debug_world.sh
  - Logging rules:
   - Use info!/debug!/warn!/error! (never println!).
   - Don’t log per-frame unless trace!.
   - Use tail/grep to keep logs readable.

  ## 3) Testing priorities
  1) Unit tests first (small, deterministic outputs).
  2) Manual testing while iterating.
  3) End-to-end verification using the debug system.
  4) UI changes require visual confirmation from the user.

  ## 4) Architecture guardrails
  - ECS: Components (data), Systems (logic), Resources (global), Events (comm).
  - Principles:
   - Prefer components over resource maps. Avoid HashMap<Entity, _> in resources.
   - Optimize queries: marker components (e.g., IsOnCurrentMap), Changed<T>.
   - Separate concerns: tagging vs rendering vs gameplay.
   - Resources only for config/assets; not entity collections/relationships.
  - UI: Adaptive content, builder pattern, size-aware components.
  - Code layout: lib/ui (components/builders), engine/src/frontend (UI systems), engine/src/backend (game logic).

  ## 5) Completion criteria (definition of done)
  - All crates compile with no warnings (clippy -D warnings).
  - All tests pass. Add/adjust tests when behavior changes.
  - Feature is verified in the running app (use debug tools/logs).
  - No temporary workarounds or TODOs left in production paths.
  - Code follows project standards above.

  ## 6) Never-give-up policy
  - Don’t mark complete with failing builds/tests or known issues.
  - Don’t swap in placeholder hacks and call it “done”.
  - If truly blocked, state why and propose a viable next step.

  ## 7) Debug commands (reference)
  - Pipe to /tmp/ascii_rpg_debug:
   - debug [viewport X Y] [full]
   - move KEYCODE (Arrow keys, Numpad1–9, Space, Period)
   - click X Y [left|right|middle]
   - ui X Y
  - Coordinates: y=0 at bottom; higher y = higher on screen.
  - UI debug output lists text top-to-bottom by visual position.

  ## 8) Dev convenience (asset editor)
  - Combined dev script:
   - ./asset-editor/dev.fish (starts backend in watch mode + Vite dev)
  - Frontend only:
   - ./asset-editor/start-frontend.fish

  ## 9) Tech snapshot
  - Rust nightly (rust-toolchain.toml), Bevy 0.16.1.
  - Workspace layout: apps/ (game + editors), engine/ (frontend/backend), lib/ (shared), asset-editor/.

  Keep changes small, tested, and instrumented. When in doubt: write a unit test, run the app, and verify via the debug pipe/logs.

  ## 10) Design-first for large changes
  - When to do this: large refactors, cross-crate changes, complex features, public API changes.
  - Deliverable (in CURRENT_TASK.md):
   - Problem and goals (constraints, assumptions).
   - 2–3 candidate approaches with pros/cons, risks, and impact.
   - Chosen approach and why; edge cases; test plan; rollout/rollback.
  - Keep it short (5–10 bullets). Get confirmation before heavy edits.