docs: add AGENTS.md and model-selection guidance#75
Conversation
Document toolchain, build/lint/test commands, workspace layout, and agent-relevant conventions for AI assistants working in this repo. Mirrors what the .husky/pre-commit hook and check.yml CI workflow run, plus the no_std and CODEOWNERS constraints. 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
Adds repository-specific guidance for AI coding agents by introducing a root AGENTS.md and pointing GitHub Copilot’s configuration at it, with additional “model selection & cost discipline” guidance intended to reduce unnecessary premium-model usage.
Changes:
- Add
AGENTS.mddocumenting workspace layout, toolchain prerequisites, canonical build/test/lint commands, and contribution workflow. - Add
.github/copilot-instructions.mdthat links toAGENTS.mdas the authoritative agent guidance source. - Add a “Model selection & cost discipline” section to
AGENTS.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.
| File | Description |
|---|---|
| AGENTS.md | New agent guide covering repo overview, commands, conventions, workflow, and model-selection guidance. |
| .github/copilot-instructions.md | New Copilot instructions pointing to AGENTS.md, with a short repo summary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `espi-device` | eSPI device abstraction used by the EC service. | | ||
| | `espi-device-stub` | Stub eSPI device for host-side testing. | | ||
| | `hafnium` | Rust bindings for Hafnium hypervisor APIs. | | ||
| | `odp-ffa` | Rust bindings for the Arm Firmware Framework (FF-A). | |
| ## 3. Build, test, lint — the canonical commands | ||
|
|
||
| These mirror `.husky/pre-commit` and `.github/workflows/check.yml`. **Run the | ||
| precommit script before considering any change done**: |
| # Clippy on the rest of the workspace (host target) | ||
| cargo clippy -- -D warnings | ||
|
|
||
| # Host build / type-check across the feature powerset (excluding aarch64-only crates) |
| ( cd platform/qemu-sp && cargo build --target=aarch64-unknown-none ) | ||
| ( cd platform/ihv1-sp && cargo build --target=aarch64-unknown-none ) | ||
|
|
||
| # Supply-chain checks |
|
|
||
| ## 4. Workspace conventions | ||
|
|
||
| - **Edition**: `2021`. Workspace `version = "0.1.0"`. |
| - **Formatting**: rustfmt with `max_width = 120` (see `rustfmt.toml`). | ||
| - **Line endings**: LF. Do not introduce CRLF. | ||
| - **Dependencies**: prefer adding to `[workspace.dependencies]` and referencing | ||
| them from member crates with `dep = { workspace = true }`. Match existing |
|
|
||
| Short version: | ||
|
|
||
| - Cargo workspace, `resolver = "2"`, edition `2021`, MSRV **1.85**. |
| (set in the workspace `Cargo.toml`); do not relax it. | ||
| - `rustfmt.toml` sets `max_width = 120`. Use LF line endings. | ||
| - Prefer `[workspace.dependencies]` entries with | ||
| `dep = { workspace = true }` in member crates. |
|
|
||
| - The `platform/*-sp` binaries and the lower-level crates target | ||
| `aarch64-unknown-none[-softfloat]` and are `#![no_std]`. They must not gain a | ||
| transitive dependency on `std`. The `no-std.yml` workflow guards this with |
rogurr
left a comment
rogurr
left a comment
There was a problem hiding this comment.
Same comment as other agents.md files, we probably need to come up with a spec for ODP that outlines how readme files are handled in the repo and maybe point these agent.md files to those then use these to augment it with unspoken rules.
dymk
left a comment
dymk
left a comment
There was a problem hiding this comment.
Thanks for putting this together — it's a really helpful orientation, and most of the concrete details check out (resolver, MSRV, lint floor, release profile, max_width, tool versions, CI jobs). I left a few suggestions below — mostly accuracy nits, plus one thought on where the model-selection section might fit best. Nothing blocking; feel free to take or leave any of them.
| | Supply-chain check | `cargo deny --all-features --target=aarch64-unknown-none check` | | ||
| | Doc build (nightly) | `cargo +nightly doc --no-deps --all-features --target=aarch64-unknown-none` | | ||
|
|
||
| ## Model selection & cost discipline |
There was a problem hiding this comment.
This section looks accurate for Copilot CLI specifically (the /fleet, /compact, task sub-agent table, and model IDs all line up). Since AGENTS.md is the shared cross-agent file (Claude, Codex, etc. read it too), would it make sense to move this into .github/copilot-instructions.md — which this PR already sets up as the Copilot-specific spot — or maybe generalize the wording so it's harness-neutral? Also an open question, totally your call: is per-contributor model/cost guidance something you'd want in the upstream repo, or more of a personal-config thing? (Hard-coded model IDs like claude-haiku-4.5 may also date a bit over time.)
|
|
||
| - The `platform/*-sp` binaries and the lower-level crates target | ||
| `aarch64-unknown-none[-softfloat]` and are `#![no_std]`. They must not gain a | ||
| transitive dependency on `std`. The `no-std.yml` workflow guards this with |
There was a problem hiding this comment.
This references no-std.yml, but the file is actually nostd.yml (no hyphen) — its internal name: is no-std, which is probably where the mix-up crept in. §7 already calls it nostd.yml, so this keeps the two consistent.
| | `ec-service-lib` | Common code shared by EC secure-partition implementations. | | ||
| | `espi-device` | eSPI device abstraction used by the EC service. | | ||
| | `espi-device-stub` | Stub eSPI device for host-side testing. | | ||
| | `hafnium` | Rust bindings for Hafnium hypervisor APIs. | |
There was a problem hiding this comment.
This table doesn't quite match [workspace].members: qemu-sp-uart is a member but isn't listed, and hafnium is listed here but is actually a path dependency rather than a workspace member. Might be worth adding qemu-sp-uart and noting hafnium separately, if you'd like the table to mirror members exactly.
|
|
||
| ## 3. Build, test, lint — the canonical commands | ||
|
|
||
| These mirror `.husky/pre-commit` and `.github/workflows/check.yml`. **Run the |
There was a problem hiding this comment.
The cargo deny line doesn't actually run in .husky/pre-commit — it's commented out there (the hook only checks deny is installed). It does run in CI (check.yml), so maybe attribute it to CI to avoid confusion.
|
|
||
| - Rust toolchain is pinned via `rust-toolchain.toml`. Required components: | ||
| `rust-src`, `llvm-tools-preview`, `rustfmt`, `rust-analyzer`. | ||
| - Required targets: `aarch64-unknown-none` and `aarch64-unknown-none-softfloat`. |
There was a problem hiding this comment.
rust-toolchain.toml only pins aarch64-unknown-none-softfloat, so the plain aarch64-unknown-none has to be added manually (which is what the pre-commit check_rustup_target guard is for). Might be worth mentioning that only softfloat auto-installs.
| workspace layout, conventions, and PR workflow used by GitHub Copilot and | ||
| other AI coding assistants. | ||
|
|
||
| Short version: |
There was a problem hiding this comment.
This file calls AGENTS.md the "single source of truth" and then restates a fair bit of the specifics, which could drift over time. Might be cleaner to keep it mostly as a pointer with one or two highlights? (The same idea loosely applies to §3 vs the §9 quick-ref table in AGENTS.md — though that overlap may be intentional for convenience.)
| cargo clippy -- -D warnings | ||
|
|
||
| # Host build / type-check across the feature powerset (excluding aarch64-only crates) | ||
| cargo hack check --feature-powerset --exclude=ihv1-ec-sp --exclude=qemu-ec-sp |
There was a problem hiding this comment.
The host cargo hack here uses --exclude=ihv1-ec-sp --exclude=qemu-ec-sp, while CI (check.yml) uses --skip time-driver — so it doesn't quite mirror both. Maybe just note they differ.
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).