feat: Adding AGENTS.md repository instructions for AI tooling by CodeMaverick2 · Pull Request #1518 · munich-quantum-toolkit/core

CodeMaverick2 · 2026-02-16T02:22:01Z

Description -

Summary

Add AGENTS.md at the repository root to provide AI coding tools with project-specific instructions
Covers build commands, testing workflows, linting/formatting, documentation, and code conventions
Every command verified against actual project configuration files (CMakeLists.txt, pyproject.toml, noxfile.py, .pre-commit config.yaml, .clang-format, .clang-tidy, .cmake-format.yaml, .editorconfig)

Format

AGENTS.md follows the agents.md standard — the emerging universal format consumed by Codex, Cursor, CodeRabbit, Jules, Windsurf, Aider, and more.
CodeRabbit natively scans AGENTS.md for PR reviews.

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 · 2026-02-16T02:23:49Z

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 a new repository-level documentation file AGENTS.md that documents AI tooling and repository instructions: C++ and Python build/test/run commands, linting/formatting/type-checking and package tooling, pre-commit workflow, docs/stub generation, tech stack, and supported platforms. No code or public API changes.

Changes

Cohort / File(s)	Summary
AI Tooling Instructions `AGENTS.md`	New documentation describing project tech stack (`C++20`, `CMake ≥3.24`, `Python ≥3.10`, `LLVM 21+`), C++ and Python build/test/run commands, `uv` package workflow and build artifact locations, `ruff` linting, `ty` type checking, pre-commit and `nox` tasks (docs, stubs), project layout, and supported platforms (Linux/macOS/Windows; x86/arm64). No functional code or public API changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through lines of docs and thread,

Placed build commands where the pathways led.
CMake, uv, ruff—carrots neatly sown,
Tests and stubs in tidy rows are shown.
A little hop; the guide is grown.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically identifies the main change: adding AGENTS.md documentation for AI tooling instructions, matching the file added in the changeset.
Description check	✅ Passed	The description comprehensively covers the change summary, verification approach, standard compliance, and tool integration. All checklist items are marked complete. Minor formatting issue with 'Description - ' prefix, but content is substantially complete.
Linked Issues check	✅ Passed	The PR addresses all major requirements from issue `#1459`: AGENTS.md documentation covering build/test/run commands for C++/Python, pre-commit checks, documentation, stub generation, tooling constraints (C++20, CMake 3.24+, Python 3.10+, LLVM 21+, ruff, ty, uv), and platform support.
Out of Scope Changes check	✅ Passed	The changeset contains only AGENTS.md addition (+243 lines) with no functional code changes, perfectly aligned with the PR objective of providing documentation for AI tooling without introducing public API or code modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into `main`

_{✏️ 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

_{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`:
- Around line 193-205: The fenced code block in AGENTS.md that lists the project
layout lacks a language tag; update the opening triple-backtick for that block
to include a language specifier like "text" (i.e., change the code fence before
the directory list to ```text) so the directory structure renders correctly;
locate the block containing the lines starting with "include/mqt-core/" and
"src/" and add the language specifier to the existing fenced code block.

AGENTS.md

burgholzer · 2026-02-16T11:11:45Z

Thanks for your interest in contributing to the project as part of unitaryDESIGN! Great to see. Would you mind commenting 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.

I'll try to get some first feedback to you over the course of the day.

denialhaag

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

I have gone through everything now and left a few comments where I still see some room for improvement.

AGENTS.md

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@AGENTS.md`:
- Around line 40-45: Add a short note near the C++ linting section and/or the
CMake options table explaining that BUILD_MQT_CORE_BINDINGS is OFF by default
and that clang-tidy will not analyze bindings unless the linter build sets
-DBUILD_MQT_CORE_BINDINGS=ON; reference the CMake option name
BUILD_MQT_CORE_BINDINGS and the C++ linting/clang-tidy step in the docs so
readers know to enable bindings for full coverage.

AGENTS.md

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@AGENTS.md`:
- Around line 232-233: Replace the heading text "**MLIR caveats**" with "**MLIR
cautions**" in AGENTS.md so the phrasing reads "MLIR cautions: MLIR is disabled
automatically on macOS with GCC (ABI incompatibility) and with AppleClang < 17
(incomplete C++20 support)"; keep the rest of the sentence intact and do not
modify the adjacent note about stub files.
- Around line 220-223: Update the OS/compiler matrix in AGENTS.md to clearly
separate "Regular CI" (always run) from "Extensive CI (requires extensive-cpp-ci
label)"; state that Regular CI runs: Ubuntu (GCC only), macOS 15 only, Windows
2025 only, and does not run Clang/GCC cross-combinations, whereas Extensive CI
(triggered by the extensive-cpp-ci label) covers the full matrix: macOS 14–15,
Windows 2022–2025, and compilers GCC 14+, Clang 20+, MSVC and AppleClang 17+
(including mixed GCC/Clang combinations). Ensure the wording replaces the
current undifferentiated list so contributors know which platforms/compilers are
always tested vs. label-gated.

AGENTS.md

denialhaag

Thanks a lot for addressing my comments! This looks good from my side now. 🙂

I propose leaving this PR open for a bit longer so that other contributors (in particular, @burgholzer) can also review the file.

CodeMaverick2 · 2026-02-17T16:46:01Z

Thanks again!

@burgholzer would appreciate your review whenever you get a chance

CodeMaverick2 · 2026-02-20T08:20:11Z

Thanks again!

@burgholzer would appreciate your review whenever you get a chance

@burgholzer Bumping this in case missed Whenever you get time

burgholzer · 2026-02-20T08:22:54Z

Thanks for the ping. This is still in my pile of reviews. I'll try to get to it today 👍🏻

CodeMaverick2 · 2026-02-20T09:30:58Z

Thanks for the ping. This is still in my pile of reviews. I'll try to get to it today 👍🏻

Thanks for the update! Really appreciate you fitting this into your review pile

burgholzer

Thanks @CodeMaverick2 for the initial draft here.
I gave this a fairly thorough review now. Please don't be overwhelmed by the number of comments that you will find inline. I tried to keep them as small an isolated as possible.

Overall, this feels like it definitely needs a bit of work to become useful. However, it seems like a solid start. I hope the comments help you to improve this further.

AGENTS.md

CodeMaverick2 · 2026-02-20T18:24:11Z

@burgholzer Addressed all your review comments removed redundant/prek-enforced sections, split code blocks into separate cells, added missing info (QIR, free-threading, Stable ABI, label-based testing, version-specific nox), and pointed to config files instead of duplicating rules.

…ck2/core into aiToolingInstructions

CodeMaverick2 · 2026-02-20T19:27:32Z

@burgholzer Sorry about that missed 2 comments that were resolved without being addressed.
Now fixed: removed the license headers and capitalization bullets (linter handles these), and added Python platform support info (versions, wheel platforms, Stable ABI, free-threading, extensive-python-ci label).

CodeMaverick2 and others added 3 commits February 13, 2026 13:28

Added AGENTS.md repository instructions for AI tooling

4c3caca

Merge branch 'munich-quantum-toolkit:main' into aiToolingInstructions

12c464d

🎨 pre-commit fixes

b42b050

coderabbitai bot requested changes Feb 16, 2026

View reviewed changes

AGENTS.md Show resolved Hide resolved

CodeMaverick2 added 2 commits February 16, 2026 07:58

captilazation ci fail fix

dfcc66f

coderabbit suggested fix

6316c72

coderabbitai bot approved these changes Feb 16, 2026

View reviewed changes

ci: retrigger CI

3d97cfe

burgholzer mentioned this pull request Feb 16, 2026

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

Open

8 tasks

burgholzer added documentation Improvements or additions to documentation usability Anything related to usability backport-potential Changes to be backported to the stable branch unitaryDESIGN Issues and PRs intended for unitaryDESIGN labels Feb 16, 2026

CodeMaverick2 mentioned this pull request Feb 16, 2026

📝 Add repository instructions for AI tooling #1459

Open

denialhaag requested changes Feb 16, 2026

View reviewed changes

suggestion fixes

ec9e4d0

coderabbitai bot requested changes Feb 16, 2026

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

coderabbit suggestion

987b2f7

CodeMaverick2 requested a review from denialhaag February 16, 2026 16:35

coderabbitai bot requested changes Feb 16, 2026

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

AGENTS.md Outdated Show resolved Hide resolved

fix

61c7602

coderabbitai bot approved these changes Feb 16, 2026

View reviewed changes

denialhaag reviewed Feb 16, 2026

View reviewed changes

Merge branch 'main' into aiToolingInstructions

0ed2284

Merge branch 'main' into aiToolingInstructions

f2c50d5

burgholzer requested changes Feb 20, 2026

View reviewed changes

CodeMaverick2 and others added 2 commits February 20, 2026 23:48

review fixes

6eebd51

🎨 pre-commit fixes

20abc0b

CodeMaverick2 requested a review from burgholzer February 20, 2026 18:24

CodeMaverick2 added 2 commits February 21, 2026 00:46

2 fixes

63a1553

Merge branch 'aiToolingInstructions' of https://github.com/CodeMaveri…

26d810d

…ck2/core into aiToolingInstructions

Merge branch 'main' into aiToolingInstructions

9590c8c

Uh oh!

Comments

Conversation

CodeMaverick2 commented Feb 16, 2026

Description -

Checklist:

Uh oh!

coderabbitai bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

burgholzer commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

denialhaag left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

denialhaag left a comment

Choose a reason for hiding this comment

Uh oh!

CodeMaverick2 commented Feb 17, 2026

Uh oh!

CodeMaverick2 commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

burgholzer commented Feb 20, 2026

Uh oh!

CodeMaverick2 commented Feb 20, 2026

Uh oh!

burgholzer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CodeMaverick2 commented Feb 20, 2026

Uh oh!

CodeMaverick2 commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

coderabbitai bot commented Feb 16, 2026 •

edited

Loading

burgholzer commented Feb 16, 2026 •

edited

Loading

CodeMaverick2 commented Feb 20, 2026 •

edited

Loading