docs: add AGENTS.md and model-selection guidance#23
Open
felipebalbi wants to merge 2 commits into
Open
Conversation
Document workspace layout (embedded-fans + embedded-fans-async), the public trait surface, MSRV, no_std targets, required CI commands, commit-message and AI-attribution rules, and pilot-specific notes for Copilot, Claude, Cursor, and CLI agents. Also prepend a pointer note to .github/copilot-instructions.md so existing Copilot users discover the new guide while keeping the original commit-message rules authoritative. 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
felipebalbi
marked this pull request as ready for review
May 26, 2026 20:04
felipebalbi
requested review from
RobertZ2011,
Copilot,
jerrysxie,
kurtjd and
williampMSFT
May 26, 2026 20:04
There was a problem hiding this comment.
Pull request overview
Adds a repository-specific AI agent guide intended to centralize conventions and CI-aligned workflows, and updates Copilot instructions to point to it as the canonical reference.
Changes:
- Introduces
AGENTS.mdwith workspace layout, public API invariants, local/CI commands, and agent workflow guidance. - Adds a “Model selection & cost discipline” section to
AGENTS.md. - Updates
.github/copilot-instructions.mdto link toAGENTS.mdwhile keeping commit/attribution rules authoritative.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
AGENTS.md |
New agent-facing repository guide plus model-selection guidance. |
.github/copilot-instructions.md |
Adds a pointer to AGENTS.md as the full agent guide. |
| agents. | ||
|
|
||
| If you are an agent reading this for the first time on a new task, read | ||
| this entire file before making changes. It is intentionally short. |
Comment on lines
+253
to
+254
| footprint minimal — currently the only runtime dep is optional | ||
| `defmt`. |
Comment on lines
+145
to
+175
| Agents should prefer the same commands CI runs so that local | ||
| verification matches the gate. All commands run from the workspace | ||
| root unless noted. | ||
|
|
||
| ### Toolchain | ||
|
|
||
| - Stable Rust with components `rustfmt`, `clippy`. | ||
| - Nightly Rust for `cargo doc` (only required if you want to mirror | ||
| the CI doc job; see below). | ||
| - The pinned MSRV is `1.79`; `cargo check --locked` must succeed on | ||
| that exact toolchain. | ||
| - For `no_std` verification you also need the targets | ||
| `thumbv7m-none-eabi` and `aarch64-unknown-none`. | ||
|
|
||
| ```sh | ||
| rustup component add rustfmt clippy | ||
| rustup target add thumbv7m-none-eabi aarch64-unknown-none | ||
| ``` | ||
|
|
||
| ### Required pre-PR checks | ||
|
|
||
| Run these and fix any failure before handing work back to a human: | ||
|
|
||
| ```sh | ||
| cargo fmt --all -- --check | ||
| cargo clippy --all-targets --all-features --locked -- -D warnings | ||
| cargo test --all-features --locked | ||
| cargo check --locked | ||
| cargo check --target thumbv7m-none-eabi --no-default-features --locked | ||
| cargo check --target aarch64-unknown-none --no-default-features --locked | ||
| ``` |
Comment on lines
+403
to
+409
| ## 8. Pilot-specific notes | ||
|
|
||
| The rules above apply to every agent. The notes in this section call | ||
| out tool-specific nuances. If your tool is not listed, follow the | ||
| GitHub Copilot section as the baseline. | ||
|
|
||
| ### GitHub Copilot (Chat, CLI, Coding Agent) |
Comment on lines
+449
to
+452
| End of `AGENTS.md`. Keep this file current — when CI, MSRV, | ||
| workspace layout, or commit policy changes, update this file in the | ||
| same PR. | ||
|
|
| @@ -1,3 +1,8 @@ | |||
| > **Note:** See [`AGENTS.md`](../AGENTS.md) at the repository root for the | |||
| > full AI-agent guide (workspace layout, public API contract, required CI | |||
| > commands, and pilot-specific notes). The rules below remain authoritative | |||
felipebalbi
enabled auto-merge (squash)
May 27, 2026 01:03
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).