docs: add AGENTS.md and model-selection guidance - #3
Conversation
Adds a comprehensive AGENTS.md at the repo root with project conventions, build/test commands, and code-style guidance distilled from CI workflows and existing source. Updates copilot-instructions.md with a leading note directing agents to AGENTS.md as the canonical source, avoiding drift between the two files. Assisted-by: GitHub Copilot:claude-opus-4.7
Adds guidance on choosing between premium and cheap models for code-assistant work, including escalation/de-escalation triggers, sub-agent routing defaults, /fleet rules, and session-hygiene tips. Keeps premium reasoning for genuinely hard problems and routes mechanical work to cheaper models. Assisted-by: GitHub Copilot:claude-opus-4.7
There was a problem hiding this comment.
Pull request overview
This PR adds repository-specific guidance for AI coding assistants (and humans) by introducing a root-level AGENTS.md that documents the repo’s current Rust/CI/tooling conventions, and updates Copilot instructions to point to that file as the canonical reference.
Changes:
- Add
AGENTS.mdwith repository overview, layout, CI command equivalents, and contribution/convention guidance. - Update
.github/copilot-instructions.mdto be minimal and direct readers toAGENTS.mdfirst.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
AGENTS.md |
New canonical agent/developer guidance, including build/test/lint commands and repo conventions. |
.github/copilot-instructions.md |
Adds a short header directing agents to AGENTS.md as the primary guidance source. |
| ## Incorporated from `.github/copilot-instructions.md` | ||
|
|
||
| The following is the full, verbatim content of | ||
| `.github/copilot-instructions.md` as of this commit, included here so | ||
| this AGENTS.md remains a strict superset: |
| - **Panics & indexing.** Clippy's `correctness`, `suspicious`, `perf`, | ||
| and `style` groups are *forbidden* (not just denied). In practice this | ||
| means: no `unwrap()`/`expect()`/`panic!()` in non-test code, no direct | ||
| slice indexing where `.get(..)` is appropriate, no | ||
| integer-overflow-prone arithmetic without `checked_`/`wrapping_`/ | ||
| `saturating_` as appropriate. The `address-review` skill explicitly | ||
| treats any reviewer suggestion to use `unwrap()`/`panic!()`/raw | ||
| indexing as **invalid** | ||
| (`.github/skills/address-review/SKILL.md:40`). |
| - Do not introduce `unwrap()`, `expect()` (outside tests), `panic!()`, | ||
| direct slice indexing without bounds handling, or any `unsafe` block | ||
| without a `// SAFETY:` comment. The clippy policy treats these as | ||
| build failures. |
| Concretely, as of this writing: | ||
|
|
||
| - `Cargo.toml` still declares `name = "embedded-rust-template"` and | ||
| `repository = "https://github.com/OpenDevicePartnership/embedded-rust-template"` |
There was a problem hiding this comment.
We should wait until the first PR is in before generating this agents.md.
| Treat this AGENTS.md as the contract for *how* to add that driver code, | ||
| not as documentation of an existing driver. | ||
|
|
||
| ## Repository layout |
There was a problem hiding this comment.
You had another PR with agent .md files, so my comments are basically the same here. I really like how this whole file helps an AI agent to work in the repo, but can we maybe reference the actual item instead of describing it here? For instance, this table could be created by the agent by just looking at the directory structure and pulling each README.md in each folder and reading its header. That means we need to create a spec on how the README's are used and that they all have a proper header, so maybe that's a goal we can shoot for?
This PR adds an
AGENTS.mdfile (see agents.md) tailored to this repository, distilled from the project's CI workflows, configuration, source layout, and conventions. The goal is to give any AI coding agent (Copilot, Claude, Cursor, etc.) enough repo-specific context to be immediately productive without re-deriving conventions from scratch.Commit 1 —
docs: add AGENTS.md ...AGENTS.mdwith project overview, build/test/lint/fmt commands, code layout, contribution patterns, and any quirks observed (e.g.,defmtfeature constraints, nightly-onlyrustfmt.tomloptions, workspace layout)..github/copilot-instructions.mdupdated to point atAGENTS.mdas the authoritative source, so Copilot-specific configuration does not drift out of sync with the broader agent guidance. Where nocopilot-instructions.mdexisted, a minimal pointer file was added.Commit 2 —
docs(AGENTS.md): add model selection & cost discipline section/fleetrules, and session-hygiene tips. The aim is to keep premium reasoning for genuinely hard work and route mechanical edits to cheaper models, reducing wasted spend without sacrificing quality.No source code, dependencies, or CI behavior is changed by this PR — it is documentation only.
Marked as draft for review; happy to iterate on tone, scope, or any repo-specific detail that should be tightened up.
Assisted by GitHub Copilot (Claude Opus 4.7).