diff --git a/AGENTS.md b/AGENTS.md index d7a928f7f..ddf45e045 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,10 +72,25 @@ `.agents/plugins/marketplace.json`. - The `trtmc-agent-skills` plugin is marked `INSTALLED_BY_DEFAULT` and exposes repo-local skills from `plugins/trtmc-agent-skills/skills/`. -- Use `$write-git-messages` when drafting or reviewing commit messages, PR - titles, PR descriptions, squash merge messages, or rebase message text. -- If `$write-git-messages` is not listed in the active runtime skills, load - `plugins/trtmc-agent-skills/skills/write-git-messages/SKILL.md` directly and - follow it. +- **If a skill below is not listed in the active runtime skills, load + `plugins/trtmc-agent-skills/skills//SKILL.md` directly and follow it.** + Registration is through the Codex plugin path, so other agent runtimes do not + list these; an empty runtime skill list is not evidence that no skill covers + the task. +- Consult the skill that matches the task before starting it: + +| Task | Skill | +| --- | --- | +| Onboard a Hugging Face model, or extend a family, to produce a bundle | `transform-model` | +| TensorRT output disagrees with the reference, or validation fails numerically | `debug-trt-mismatch` | +| FP16/BF16 dtype threading and explicit FP32 boundaries | `fp16-trt-network` | +| Evaluate a precision or quantization format for a model | `optimize-model-precision` | +| Diagnose runtime cost, or produce performance evidence | `profile-model` | +| Prepare a build or validation environment on an unfamiliar host | `setup-trtmc-environment` | +| Publish a change as a pull request | `submit-github-pr` | +| Monitor PR CI, diagnose failed checks, rebase onto `github/main` | `pr-babysitter` | +| Turn a finding into a GitHub issue | `submit-github-bug-issue` | +| Draft or review commit messages, PR titles, PR descriptions, merge messages | `write-git-messages` | +| Keep the website, skills, commands, and architecture docs aligned | `doc-sync` | diff --git a/website/docs/agent-guide.md b/website/docs/agent-guide.md index 53f1054fa..1fc589945 100644 --- a/website/docs/agent-guide.md +++ b/website/docs/agent-guide.md @@ -24,6 +24,20 @@ Before changing or running anything, an agent must: publication evidence in its report; and 5. state which meaningful validations were not run. +## Repository skills + +The repository ships task-specific skills under +`plugins/trtmc-agent-skills/skills/`. They are registered through the Codex +plugin path, so another agent runtime will not list them: read +`plugins/trtmc-agent-skills/skills//SKILL.md` directly. An empty runtime +skill list is not evidence that no skill covers the task. + +Start from the routing table in +[`AGENTS.md`](https://github.com/NVIDIA/TensorRT-Model-Connect/blob/main/AGENTS.md). +The two that cover the most common contributions are `transform-model`, for +onboarding a Hugging Face model or extending a family, and +`debug-trt-mismatch`, for output that disagrees with the reference. + ## Safety boundaries An agent must not: diff --git a/website/docs/extend/add-model-family.md b/website/docs/extend/add-model-family.md index 16e8c92cd..0fb8e2bee 100644 --- a/website/docs/extend/add-model-family.md +++ b/website/docs/extend/add-model-family.md @@ -105,6 +105,47 @@ The expected diff boundary for a normal family contribution is `families/my_family/**`. Examples, benchmarks, and BYOK are optional consumers of public APIs; neither a family nor core may import their implementation. +## Reproduce the pre-merge gates before you push + +`.github/workflows/community-cpu.yml` runs four jobs on every pull request, and +`Community CPU / Required` fails unless all four pass. Each has a local +equivalent, so a failure does not have to cost a push and a CI round trip. + +The source-quality gate invokes `python`, `lizard`, `ruff`, and `clang-format` +by name. Create and activate its environment before running the commands: + +```bash +python3 -m venv .venv-ci +source .venv-ci/bin/activate +python3 -m pip install --requirement requirements/community-ci.txt +export RUNNER_TEMP="${RUNNER_TEMP:-$(mktemp -d)}" +``` + +Then run from the repository root, with `` as the commit you branched +from (`upstream/main` or `github/main`): + +| Pre-merge job | Run locally | Covers | +| --- | --- | --- | +| `Community CPU / Source quality` | `python3 -m tools.community_ci source-quality --base ` | the `core/runtime` complexity ceiling across the whole tree; `ruff` and `clang-format` on changed files; model architecture contracts | +| `Community CPU / Ownership and impact` | `python3 -m tools.community_ci impact --base ` | ownership resolution and the CPU test scope your change selects | +| `Community CPU / Unit / C++ and Python` | `python3 -m tools.community_ci unit` | compiles the shared runtime and runs the source-only C++ and Python unit tests in the CI container | +| `Community CPU / Docs` | `cd website && npm ci && npm run test:model-support && npm run build` | the generated model support inventory and the production documentation build | + +The unit command builds and runs the CI container, so it needs a working Docker +daemon. Its image follows the Docker host architecture unless +`DOCKER_DEFAULT_PLATFORM` overrides it; pre-merge runs on `linux/amd64`. Before +chasing a platform-specific failure, check whether it also fails on the base +branch. + +Two failure modes worth knowing, because both look like success: + +- A **skipped** test is not a passing test. `pytest` skips whatever its + `importorskip` guards cannot import, so a virtual environment without + `numpy`, `torch`, or `safetensors` silently drops that coverage. Run with + `-rs` and read which tests skipped, not only the count. +- The **complexity ceiling for `core/runtime` is 10**, and it is checked against + the whole tree rather than only your diff. + An E2E manifest may declare an exact `hf_id` (and, when available, `hf_revision`) or omit `hf_id` for a prepared local checkpoint supplied through the family-specific model-directory environment variable. Do not invent an HF