AGENTS.md: no build command, no commit/PR conventions, gotchas scattered — measured gaps + offer to fix
What is the type of issue?
Documentation is missing
What is the issue?
AGENTS.md documents test/lint/format flows thoroughly (just test, just fmt, just fix), but three things an agent needs to operate the repo are missing or scattered:
- No build command anywhere in the file. For a Rust/Bazel workspace this is the first thing a coding agent needs after editing (
cargo build -p <crate>/ the Bazel equivalent and when to prefer which). Agents currently have to guess, and guessing wrong on a Bazel-tracked crate is exactly the failure mode the file warns about elsewhere. - No commit-message / PR conventions. There is "Change size guidance (800 lines)" and code-review rules, but nothing tells an agent how to title commits/PRs or what a reviewable change should look like from the contribution side.
- Gotchas exist but are scattered (Bazel
compile_datapitfalls, "be patient with Rust locks, never kill the PID", first-run Bazel slowness). Consolidating them under a dedicated Gotchas/Pitfalls section makes them reliably discoverable for agents that skim by heading.
Measured with schliff, a deterministic (no-LLM) AGENTS.md scorer — reproducible:
$ pip install schliff==8.4.0 && schliff score AGENTS.md
structure 75/100
operational_coverage 55/100 <- build/gotchas/PR categories uncredited
efficiency 61/100
composite 66.4/100 [C]For calibration: across 7 major agent-ecosystem repos scored the same way today, this file ranks last — mostly because of the three gaps above, all of which are cheap to close.
Happy to submit a PR per docs/contributing.md that adds the build command(s), a short commit/PR-conventions block, and a consolidated Gotchas section (content sourced from what's already in the file — no invented guidance). Equally fine if you'd rather handle it in-house; the measurement above is reproducible either way.