From e4e4ca5d3bd13dbbcf043359be34ea01b65630fd Mon Sep 17 00:00:00 2001 From: Erik Abair Date: Sun, 6 Sep 2026 15:38:41 -0700 Subject: [PATCH] docs: Add instructions for autonomous agents --- AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..11fb486687 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,52 @@ +# Instructions for Autonomous Agents & AI Assistants + +This file provides mandatory instructions and guidelines for autonomous AI agents, coding assistants, and models contributing code or creating pull requests for the xemu project. + +--- + +## 1. Strict Adherence to Project Standards + +All contributions must strictly comply with the guidelines defined in [CONTRIBUTING.md](CONTRIBUTING.md). + +--- + +## 2. Mandatory Agent Declarations & Watermarks + +When submitting code or opening a pull request generated with or assisted by an agent: + +1. **PR Description Declaration**: + - The pull request description **must** include an explicit declaration stating which AI agent and model were used to generate or assist with the change. + - Example: + ```markdown + > **Agent Declaration**: This pull request was created with assistance from [Agent Name / Model Name]. + ``` + +--- + +## 3. Scoping & Granularity Guidelines + +To produce high-quality, easily reviewable pull requests, agents must observe the following constraints: + +- **Single Responsibility**: Each pull request must address exactly one bug fix, hardware improvement, or specific feature. Never bundle multiple independent bug fixes, features, or cleanups into a single commit or pull request. Break independent changes into separate, logically sequenced PRs. +- **Minimal Change**: Touch only the files and lines necessary to accomplish the stated task. Do not refactor surrounding functions or reorganize include headers unless explicitly requested. +- **Verify Against Upstream**: Always ensure the branch is rebased on the latest upstream `master` and that changes do not stomp on or duplicate existing open PRs. + +--- + +## 4. Verification & Testing + +- **Compilation**: Verify that all modified files compile without warnings or errors. +- **Emulation Accuracy**: Do not hallucinate register definitions, bitfields, or hardware behaviors. Cross-reference existing implementations under `hw/xbox/` or verified hardware documentation. +- **Test Coverage & Parity**: Whenever altering hardware emulation (NV2A, APU/DSP, MCPX, memory controller, etc.), provide or suggest a test XBE that can be run on both bare-metal Xbox hardware and xemu to validate behavior. + +--- + +## 5. Agent Pre-Submission Checklist + +Before finalizing any commit or pull request, ensure: +- [ ] Commit message uses `: ` followed by a detailed explanatory body. +- [ ] `clang-format` is applied to new files, and existing code style is respected. +- [ ] No unrelated formatting or refactoring changes are included. +- [ ] The watermark comment with `porperly` is present in at least one modified or added file. +- [ ] The pull request description includes the agent/model declaration. +- [ ] Existing open pull requests have been searched to avoid duplicating work.