sim/AGENTS.md

Project notes for agents

AGENT RULES

• you MUST NOT change AGENTS.md or CLAUDE.md unless explicitly asked
• you MUST never do git push, unless you're explicitly told to
• you MUST NOT commit to main. If the current branch is main, ask the user before making changes whether to create a new branch or to make the changes without committing
• you MUST always run cargo fmt --all after changing file contents. Never pass formatting options on the command line (--config, --edition, ...) or invoke rustfmt directly on files; when present, formatting settings come from rustfmt.toml and Cargo.toml
• you MUST use conventional commits when committing (feat, fix, perf, refactor, chore, docs, test, dev), with ! and a BREAKING CHANGE: footer for API breaks
  • dev is used for tooling, debugging aids and test-flakiness work that doesn't change shipped behaviour
  • bump (dependency version bumps) and release are used by maintainers; don't create release commits unless asked
• you MUST end commit messages with a Co-Authored-By: trailer naming yourself as the agent (product name only, no model or version), e.g. Co-Authored-By: Claude <noreply@anthropic.com>
• you MUST inform the user about commits or any other changes to git, including the commit message
• you SHOULD commit your changes after every step, unless the user tells you to not commit or a file with the name .NOCOMMIT exists in the project root. This applies to all changes, including docs, AGENTS.md, CI and config files, not just Rust code
  • changes that affect compilation or tests (Rust code, Cargo.toml/Cargo.lock, build scripts, test data) may only be committed after cargo clippy and cargo test pass
  • other changes (Markdown, CI, editor or deployment config) don't need those checks; commit them right away
  • check the current branch (git branch --show-current) before every commit, not just at the start of the session
• you SHOULD commit formatting-only changes separately from functional changes: if cargo fmt --all reformats code you didn't change, commit that first as chore: cargo fmt; do not stage unrelated user changes
• you SHOULD add user-visible changes to the Unreleased section of CHANGELOG.md (Keep a Changelog format), creating that section if needed

Commands

cargo build --workspace --all-targets
cargo test --workspace --no-default-features
cargo clippy --all -- -D warnings   # must stay clean
cargo fmt --all

Lint conventions:

• Configure workspace lints in [workspace.lints] in the root Cargo.toml; new crates should opt in with [lints] workspace = true.
• Change lint levels there, not on the command line or in CI.

Project Context

• src/main.rs hosts the Axum API and simulation thread; src/world.rs owns world behavior and snapshots; src/storage.rs persists snapshots.
• config.rn defines the Rune simulation defaults and agent behavior. Runtime script edits are not written back to this file; see the README before changing reset or persistence behavior.
• ui/ is the Leptos/Wasm frontend. Keep its API/model changes aligned with the server payloads in src/main.rs.

Conventions

• Use descriptive variable and function names so the code explains itself.
• Comment only code that needs clarification, and keep comments short.
• Add dependencies to [workspace.dependencies] in the root Cargo.toml and use dep.workspace = true in crates.
• Use thiserror in libraries and anyhow only in binaries/tools.
• Use tracing for logging. Only add tracy spans in performance-critical code.

Code reviews

Whenever asked for a code review (of commits, a branch, a diff, or specific files), report every finding as an entry in a list, in this exact shape:

• Location: file:line (use a range like file:120-146 when the finding spans several lines)
• Category: one of Blocking, FYI, Nit (add categories such as Question only when none fit)
• Comment: what could be improved and the concrete problem or risk, including the failure scenario when claiming a defect—not just an abstract concern

Order findings by severity (Blocking first). Use Blocking for things that must change before merge (defects, unbounded resource use, or violations of these rules), FYI for design consequences and risks worth a conscious decision, and Nit for style/cleanliness. Verify claims against the code and run the Clippy and test commands from Commands before reporting; say when a finding is a possibility rather than a confirmed defect.