docs: Add AGENTS.md with repository instructions for AI tooling

[mhmohona]

Description

Adds AGENTS.md file to provide repository instructions for AI coding agents (Copilot, Claude Code, Cursor, CodeRabbit, etc.).

The file follows the AGENTS.md format — concise, bullet-point-driven instructions optimized for agent consumption. The Ruff CLAUDE.md and apache airflow AGENTS.md was used as additional inspiration for the development guidelines section, as suggested in the issue.

Fixes #1459

Checklist:

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds AGENTS.md, an agent-facing repository guide documenting MQT Core development standards, environment constraints, C++/Python build and test commands, tooling versions, docs/stub generation, development workflow, and self-review checklists; no code or public API changes. (48 words)

Changes

Cohort / File(s)	Summary
AI Tooling Documentation AGENTS.md	New comprehensive agent-facing guide covering environment versions, C++ (CMake/C++20) and Python (uv) build/workflows, test commands, linting/formatting (ruff, ty), docs and stub generation, cross-platform notes, tooling versions, development guidelines, and PR/self-review checklists.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 I nibbled through specs, left a tidy map,
For builds and tests and every tiny gap,
With cmake, uv, and ruff in tow,
Stubs and docs now clearly show,
A hop for devs — quick, neat, and apt.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'docs: Add AGENTS.md with repository instructions for AI tooling' accurately describes the main change—adding documentation for AI agents.
Description check	✅ Passed	The PR description includes clear summary of changes, references the fixed issue #1459, follows the repository's template structure, and all checklist items are marked as complete.
Linked Issues check	✅ Passed	The AGENTS.md file addresses all core requirements from issue #1459: C++ build/test instructions, Python build with uv, pre-commit checks, docs building, stub generation, tooling versions, and repository information.
Out of Scope Changes check	✅ Passed	The PR contains only the AGENTS.md documentation file addition with no code changes or unrelated modifications, staying focused on the issue's requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@AGENTS.md`:
- Line 41: The current line referencing the command "nox -s docs -- -b html" in
AGENTS.md incorrectly implies it also serves content; update the wording to
state explicitly that this command only builds the HTML and does not start a web
server, and add a follow-up sentence instructing readers to run a simple local
HTTP server to preview the built docs (mention common options like using
Python's built-in http.server or a small Node/static server) so users know they
must run a separate serve step.

[burgholzer]

Thanks for your interest in contributing to the project as part of unitaryDESIGN!
Great to see you being active across different issues.

Generally, it would be great if you could comment on the respective issue (#1459) to indicate that you are working on this issue. Otherwise, there is no way that we could assign the issue to you, if your solution should be accepted.

There is a competing solution in #1518 that seems a little more extensive than the one being proposed here, so I am slightly leaning towards that at the moment, but this is definitely not a definitive decision.

[denialhaag]

Hi, @mhmohona! Thanks a lot for the proposal! 🙂

I have gone through everything now and left a couple of suggestions. Regarding the comment by @burgholzer, I explicitly did not comment on information that may still be missing, and leave that up to your judgment.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Line 11: Change the "For C++ only:" prefix to use an em dash with surrounding
spaces for typographic consistency in the AGENTS.md line containing "For C++
only: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
-DBUILD_MQT_CORE_TESTS=ON`, then `cmake --build build` — replace the colon with
" — " so the line reads e.g. "For C++ only — `cmake -S . -B build
-DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_TESTS=ON`, then `cmake --build
build`".
- Around line 34-35: The three consecutive sentences in AGENTS.md that start
with "We use" (the lines mentioning `clang-format`/`clang-tidy` and `typos`) are
repetitive; rewrite them to vary sentence openings and improve flow by combining
related tooling into one sentence or using different constructions (e.g., "For
C++ formatting and linting, we rely on `clang-format` and `clang-tidy`" and
"Spell checking across the codebase is performed with `typos`"), updating the
sentences that mention `clang-format`, `clang-tidy`, and `typos`.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Line 12: Update the Platform line that currently reads "**Platform**:
Operating in a Linux environment with support for x86_64 (amd64) and arm64." to
reflect all target OSes and architectures by changing it to something like
"**Platform**: Operating on Linux, macOS, and Windows with support for x86_64
(amd64) and arm64." Ensure the revised sentence replaces the existing platform
line in AGENTS.md so it matches the project platform scope.
- Line 13: AGENTS.md currently states "3.10–3.14" which wrongly implies an upper
bound; update the Python version wording to reflect the actual constraint
(requires-python = ">=3.10") by replacing "3.10–3.14" with "3.10+" (or
alternatively list only CI-tested versions), and ensure any mention of
conditional dependencies for 3.14 remains separate; edit the AGENTS.md string
"3.10–3.14" so it matches the project requirement and does not imply support up
to 3.14.

[coderabbitai]

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@AGENTS.md`:
- Line 13: Update the Python version wording under the "Python Context" line
that currently reads “3.10–3.14” to avoid implying an upper bound; change it to
“3.10+” (or alternatively list only the CI-tested versions) so the docs reflect
the project minimum requirement—edit the AGENTS.md entry for the "Python
Context" line to replace “3.10–3.14” with the chosen phrasing.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Around line 33-34: Replace the colon after "Configure Release build" and
"Configure Debug build" with an em dash (—) for consistent em-dash style in the
two bullet lines; edit the two lines that currently read "Configure Release
build: `...`" and "Configure Debug build: `...`" to use an em dash before the
inline code block instead of a colon.

---

Duplicate comments:
In `@AGENTS.md`:
- Line 12: Update the platform scope line that currently reads "**Platform**:
Operating in a Linux environment with support for x86_64 (amd64) and arm64." to
include macOS and Windows as supported OSes for both x86_64 (amd64) and arm64
architectures; locate the exact "**Platform**" line in AGENTS.md and revise it
to mention Linux, macOS, and Windows with the supported architectures
(x86_64/amd64 and arm64).
- Around line 63-68: The bullet list in AGENTS.md repeats the word "Use" at the
start of six consecutive bullets, creating a stilted rhythm; rewrite the bullets
to vary sentence structure and improve flow by alternating sentence starts
(e.g., "Prefer uv as the mandatory package manager", "Adopt nanobind (~2.11.0)
for Python bindings instead of pybind11", "Ruff is required for
linting/formatting with ALL rules enabled", "Replace mypy with ty for static
type checking", "Target LLVM 21.1+ for MLIR-based compilation dialects", and
"Apply clang-format and typos for C++ style and spell checking"), preserving the
same requirements and versions exactly.

[denialhaag]

Thanks a lot for addressing my comments! 🙂

I propose leaving this PR open alongside #1518 so that other contributors (in particular, @burgholzer) can review your changes.

[burgholzer]

Okay, I was in the middle of a proper review for this, when I noticed that several of the comments from the previous review have simply been resolved without being addressed.
This is not acceptable and against the contributing guidelines for this repository. @mhmohona please do not do that.

You will find some (incomplete) new comments with this review.
Please also go back to the comments from the past review and revisit whether they have been addressed and address them if not.

[burgholzer]

@mhmohona why was this comment resolved but not addressed? Please follow the contributing guidelines for the project, particularly https://mqt.readthedocs.io/projects/core/en/latest/contributing.html#pull-request-workflow

Respond to comments to signal that you have addressed the feedback. Do not resolve review comments yourself; the reviewer will do so once satisfied.

[burgholzer]

Probably best to show a different build directory than build here as this is also the default used by the Python package builds and this might interfere.

[burgholzer]

I am not 100% sure if it is fair to assume that ctest is present in the environment that this is executed in. Maybe it is better to replace these with directly running the built test executables.
@denialhaag thoughts from your side?

[denialhaag]

I'm not super sure myself, but directly running the test executable seems more stable. 👍

[mhmohona]

Hey @burgholzer @denialhaag, whenever you get a chance, would you please take a look at this PR? I'd really appreciate your review. Thanks!

[burgholzer]

Hey @mhmohona 👋🏼
Just wanted to let you know that we decided to go with #1518 for closing the issue.
In any case, we thank you a lot for your submission.
We will try to get at least one more submission from you over the finish line 🚀