Model-Optimizer AGENTS.md

Agent Instructions for ModelOpt

These instructions apply to AI-assisted work in this repository.

Repository orientation

• Start with README.md for project overview and install.
• Use modelopt/ for source, tests/ for focused test coverage, and examples/ or docs/ for usage patterns.
• Agent skills live under plugins/modelopt/skills/, the installable plugin's canonical skill tree. .agents/skills and .claude/skills expose those skills through relative symlinks. Shared agent config and scripts remain under .agents/. See .agents/README.md for the convention.

Coding guidelines

• Coding guide: Code development and review require reading and following the coding standards in CONTRIBUTING.md; do not skip this step.
• Use relative paths from the repo root in commands and file references.

Iterative development

• Running tests: Follow the writing and running tests instructions. For fast initial iteration, choose focused tests for the changed area from tests/.
• Running pre-commit: Follow the pre-commit hook instructions. Hooks may modify files; review and re-stage those changes before committing.
• Signed commit: Use git commit -s -S -m "<message>" for commits so they follow the signing your work requirements.
• Never git push without explicit approval in the current turn. Commit locally is fine; publishing to a remote is not.
• After git commit, stop and wait for the user to say "push", "publish", "ship", or equivalent before running git push, gh pr create, or any push-option flags like -o merge_request.create.

Contributing and PR readiness

• Before opening or marking a PR ready for review, read the submitting your code guidance.
• Read .github/PULL_REQUEST_TEMPLATE.md and satisfy the checklist.
• PR description: fill the template sections — what changed and why, a usage snippet if it adds an API or flag, and what you actually ran under Testing. Root cause, benchmark numbers, and design rationale belong here. Don't restate the diff file by file.
• Only changelog-worthy changes get a CHANGELOG.rst entry: new features, backward breaking changes, deprecations, and fixes for critical or known bugs from a previous release. Skip bugs introduced and fixed within the same unreleased cycle.
• Keep each entry to one or two sentences written for external users: what changed and what they need to do. No internal bug numbers (e.g. NVBug IDs), root-cause analysis, or implementation detail — that belongs in the PR description. File features under the matching **New Features** sub-section used by recent releases (e.g. *Quantization*, *Speculative Decoding*, *Megatron Framework (M-LM / M-Bridge)*, *Misc*) rather than relabeling existing ones.