docs: add AGENTS.md and model-selection guidance#117
Open
felipebalbi wants to merge 2 commits into
Open
Conversation
Introduce a repository-root AGENTS.md following the agents.md convention. It documents the project layout, toolchain, exact CI commands (build/test/lint/doc/no-std/examples/MSRV/supply-chain), register regeneration workflow, coding conventions (no_std, panic- free, defmt/log shim, async drop safety), testing patterns, commit conventions including the Assisted-by trailer, and PR-review focus areas. Prepend a pointer note to .github/copilot-instructions.md so that tools that look there are redirected to AGENTS.md while preserving the existing PR-review guidance for backward compatibility. 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
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an AGENTS.md repository guide intended to centralize repo-specific conventions for AI agents (and humans), and updates Copilot’s instruction file to point to it as the authoritative reference.
Changes:
- Introduces
AGENTS.mdwith project overview, repo layout, CI-equivalent commands, coding/review conventions, and commit/AI attribution guidance. - Updates
.github/copilot-instructions.mdto direct agents toAGENTS.mdas the source of truth. - Adds a “Model selection & cost discipline” section to guide cost-aware model usage by agents.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
AGENTS.md |
New comprehensive repo guide for agents covering workflows, conventions, and review focus areas. |
.github/copilot-instructions.md |
Adds a top-of-file pointer directing readers/tools to AGENTS.md. |
| # AGENTS.md — tps6699x | ||
|
|
||
| > Operational guide for AI coding agents working on | ||
| > [`openDevicePartnership/tps6699x`](https://github.com/openDevicePartnership/tps6699x). |
| - License: MIT. | ||
| - Cargo features: | ||
| - `defmt` — `defmt` logging via the `fmt` macros. | ||
| - `log` — `log` crate logging via the `fmt` macros (mutually compatible with `defmt`; one or the other typically). |
Comment on lines
+102
to
+104
| The list below mirrors `.github/workflows/check.yml`, | ||
| `.github/workflows/nostd.yml`, and `.github/workflows/device-driver.yml` | ||
| exactly. Run these before pushing. |
Comment on lines
+295
to
+304
| From `.github/copilot-instructions.md` and `CONTRIBUTING.md`: | ||
|
|
||
| - **Subject**: capitalized, ≤ 50 characters, imperative mood ("Fix bug", not | ||
| "Fixed bug"). No trailing period. | ||
| - **Blank line** between subject and body. | ||
| - **Body**: wrap at 72 characters; explain *what* and *why*, not *how*. | ||
| - Each commit must build cleanly without warnings; squash typo/format fixups | ||
| before pushing. | ||
| - **Do not** force-push to shared branches. | ||
|
|
Comment on lines
+1
to
+8
| # NOTE FOR AI AGENTS | ||
| # | ||
| # The authoritative guide for working in this repository is `AGENTS.md` at the | ||
| # repository root. It is a strict superset of this file (project overview, | ||
| # build/test/lint commands, coding conventions, async/panic safety, commit | ||
| # conventions including the `Assisted-by` trailer, and PR-review focus areas). | ||
| # Read `AGENTS.md` first; this file is preserved for backward compatibility | ||
| # with tools that still look for `.github/copilot-instructions.md`. |
| - Missing or stale `.github/copilot-instructions.md` — re-add the pointer | ||
| block described in §11 rather than removing the file. | ||
|
|
||
| ## Model selection & cost discipline |
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).