docs: add AGENTS.md and model-selection guidance#75
Open
felipebalbi wants to merge 2 commits into
Open
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.
Comment on lines
+25
to
+28
| | `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). | |
Comment on lines
+54
to
+57
| ## 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 |
williampMSFT
approved these changes
May 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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).