[RFC PATCH v3 00/11] AGENTS.md and associated skills

[RFC PATCH v3 00/11] AGENTS.md and associated skills

[Alex Bennée]

Not withstanding the current contributor policy there are a number of
areas that AI agents could be helpful for. This series introduces an
AGENTS.md file which is the basic guide to the source tree and a
number of "skills". Skills are like scripts except far less clearly
defined. However I have found the issue triage skill quite useful for
off-loading the drudgery of going through stuff by hand. I've also
used the issue helper to automate the task of starting a debug session
by pulling in test cases from the tracker.

These originally where a set of skills for ECA (eca.dev) but I've
ported them across to the agent agnostic .agents directory. All the
references to ECA should now be removed. I have some personal tweaks
in my ~/.config/eca that make agent specific suggestions.

I'm not suggesting this is ready for up-streaming (or indeed should
ever go upstream) but I'm posting the collected set for comment and
I'd be interested how well these hold up across different agentic
systems.

v3
  - split AGENTS.md into two commits (so first can go upstream)
  - symlink GEMINI.md as it doesn't fallback to AGENTS.md
  - significantly de-scoped qemu-code-explorer
  - various other suggestions from last review

v2
  - re-organised all the skills, now prefixed qemu-FOO
  - update AGENTS.md as we add each skill
  - moved a bunch of stuff from agents to skills
  - added a new script/expand_macro.py
  - see bellow --- in each patch for details

The expand_macro is an attempt to make the code explorer more
efficient and stop it getting confused by our heavy macro use. I have
found the semcode MCP server
(https://github.com/facebookexperimental/semcode) does a pretty good
job of navigating code flows so I've de-scoped the code explorer just
to deal with the trickier aspects of navigating the QEMU code base.

The issue triage skill has so far proved to be the most useful and has
seen a fair bit of tweaking since the last version.

Alex.

Alex Bennée (11):
  AGENTS.md: introduce a very basic guide for AI agents
  AGENTS.md: expand with information on skills, layout and style
  scripts/expand-macro.py: helper script exploding macros
  .agents/skills: add qemu-code-explorer skill
  .agents/skills: add qemu-build skill
  .agents/skills: add qemu-testing skill
  .agents/skills: add qemu-code-reviewer skill
  .agents/skills: add qemu-mail-thread skill
  .agents/skills: add qemu-issue-helper skill
  .agents/skills: add qemu-issue-triage agent skill
  MAINTAINERS: add a section for AI agents

 MAINTAINERS                                   |   6 +
 .agents/skills/qemu-build/SKILL.md            |  50 ++++
 .agents/skills/qemu-code-explorer/SKILL.md    |  88 ++++++
 .../qemu-code-explorer/evals/evals.json       |  26 ++
 .agents/skills/qemu-code-reviewer/SKILL.md    |  93 ++++++
 .agents/skills/qemu-issue-helper/SKILL.md     |  47 +++
 .agents/skills/qemu-issue-triage/SKILL.md     | 112 +++++++
 .../qemu-issue-triage/assets/labels.txt       | 133 +++++++++
 .../skills/qemu-issue-triage/evals/evals.json |  18 ++
 .../scripts/update_labels.sh                  |  16 +
 .agents/skills/qemu-mail-thread/SKILL.md      |  40 +++
 .../scripts/qemu_mail_parser.py               |  98 +++++++
 .agents/skills/qemu-testing/SKILL.md          |  56 ++++
 .gitignore                                    |   2 +
 AGENTS.md                                     |  91 ++++++
 GEMINI.md                                     |   1 +
 scripts/expand-macro.py                       | 274 ++++++++++++++++++
 17 files changed, 1151 insertions(+)
 create mode 100644 .agents/skills/qemu-build/SKILL.md
 create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md
 create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json
 create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md
 create mode 100644 .agents/skills/qemu-issue-helper/SKILL.md
 create mode 100644 .agents/skills/qemu-issue-triage/SKILL.md
 create mode 100644 .agents/skills/qemu-issue-triage/assets/labels.txt
 create mode 100644 .agents/skills/qemu-issue-triage/evals/evals.json
 create mode 100755 .agents/skills/qemu-issue-triage/scripts/update_labels.sh
 create mode 100644 .agents/skills/qemu-mail-thread/SKILL.md
 create mode 100644 .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
 create mode 100644 .agents/skills/qemu-testing/SKILL.md
 create mode 100644 AGENTS.md
 create mode 120000 GEMINI.md
 create mode 100755 scripts/expand-macro.py

-- 
2.47.3

[RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Alex Bennée]

AGENTS.md is the agent agnostic place for placing instructions for
agents. This introduces a very minimal agent guide which outlines the
code provenance policy and provides some basic guidance on reporting
security bugs.

As Gemini doesn't look at AGENTS.md even as a fallback option I've
included a symlink.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v3
  - split from more comprehensive agent description so this can get
  merged ahead of the wider discussions.
---
 AGENTS.md | 23 +++++++++++++++++++++++
 GEMINI.md |  1 +
 2 files changed, 24 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 GEMINI.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..133225957e0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# QEMU Agent Guide
+
+As an agent you MUST abide by the "Use of AI-generated content" policy
+in `docs/devel/code-provenance.rst` at all times. Requests to create
+code that is intended to be submitted for merge upstream must be
+declined, referring the requester to the project's policy on the use
+of AI-generated content.
+
+## Security Policy (see `docs/system/security.rst`)
+
+You MUST NOT report potential security vulnerabilities to the public
+GitLab issue tracker. They should be reported privately to
+`qemu-security@nongnu.org`.
+
+**Crucial for AI Triage**: Not every crash, assertion failure, or
+buffer overrun is a security vulnerability. Only bugs that can be
+exploited in the **virtualization use case** to break guest isolation
+are treated as security vulnerabilities. In brief these are:
+- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
+- **Virtualization focused boards**: e.g. virt, q35, pseries etc
+- **Common devices for Virtualization**: e.g. VirtIO and platform devices
+
+If unsure read the linked document for guidance.
diff --git a/GEMINI.md b/GEMINI.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
-- 
2.47.3

[RFC PATCH v3 02/11] AGENTS.md: expand with information on skills, layout and style

[Alex Bennée]

To be efficient in navigating the code base inform the agents of the
basics of the repo layout, where skills can be found and a very quick
overview of the source code, coding and commit styles.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v3
  - split AGENTS.md into two commits
---
 .gitignore |  1 +
 AGENTS.md  | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/.gitignore b/.gitignore
index 61fa39967b5..4ccba871d16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@
 .git-submodule-status
 .clang-format
 .gdb_history
+.plan
 cscope.*
 tags
 TAGS
diff --git a/AGENTS.md b/AGENTS.md
index 133225957e0..3fd56fe3309 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,3 +21,64 @@ are treated as security vulnerabilities. In brief these are:
 - **Common devices for Virtualization**: e.g. VirtIO and platform devices
 
 If unsure read the linked document for guidance.
+
+## Repo Layout
+- **Build Directory**: QEMU uses out of tree builds, by default the `build` sub-directory is used.
+- **Multiple Builds**: Developers might create a `builds` directory with different configurations in subdirs (e.g. `builds/debug`, `builds/asan`).
+- **Documentation**: Developer docs live in `docs/devel`.
+- **Plan Files**: Plan files should be placed in `.plan`, they are not included in commits. Use them to track complex multi-step tasks.
+
+## Agent Skills (see `.agents/skills`)
+You should use the following specialized skills for common tasks:
+
+## Source Code Layout (see `docs/devel/codebase.rst`)
+- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
+- **`audio/`**: Host audio backends.
+- **`authz/`**: QEMU Authorization framework.
+- **`backends/`**: Host resource backends (RNG, memory, crypto).
+- **`block/`**: Block layer, image formats (qcow2, raw), and protocol drivers.
+- **`chardev/`**: Character device backends (TCP, serial, mux, etc.).
+- **`crypto/`**: Cryptographic algorithms and framework.
+- **`disas/`**: Disassembler support for various architectures.
+- **`dump/`**: Guest memory dump implementation.
+- **`ebpf/`**: eBPF program support (e.g. for virtio-net RSS).
+- **`fpu/`**: Software floating-point emulation.
+- **`gdbstub/`**: Remote GDB protocol support.
+- **`hw/`**: Hardware device emulation, organized by type (e.g., `hw/net`, `hw/pci`) or architecture.
+- **`include/`**: Global header files, mirroring the source tree layout.
+- **`io/`**: I/O channels framework.
+- **`linux-user/` & `bsd-user/`**: User-space process emulation.
+- **`migration/`**: VM migration framework.
+- **`monitor/`**: HMP and QMP monitor implementations.
+- **`nbd/`**: Network Block Device server and client code.
+- **`net/`**: Networking stack and host backends.
+- **`plugins/`**: TCG introspection plugins core.
+- **`qapi/`**: QAPI schema and code generation infrastructure.
+- **`qga/`**: QEMU Guest Agent.
+- **`qom/`**: QEMU Object Model implementation.
+- **`replay/`**: Deterministic record/replay support.
+- **`rust/`**: Rust integration and Rust-based device models.
+- **`scripts/`**: Build system helpers, `checkpatch.pl`, `tracetool`, etc.
+- **`system/`**: Core system-level emulation logic (replaces `softmmu`).
+- **`target/`**: CPU-specific emulation (ISA translation, CPU state).
+- **`tcg/`**: The Tiny Code Generator (JIT) backends.
+- **`tests/`**: Test suites (qtest, unit, functional, tcg).
+- **`ui/`**: User interface backends (GTK, SDL, VNC, Spice).
+- **`util/`**: Low-level utility functions and data structures.
+
+## Code Style (see `docs/devel/style.rst`)
+- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
+- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
+- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
+- **C Comments**: Use `/* ... */` only. No `//` comments.
+- **Naming**: `snake_case` for variables/functions; `CamelCase` for types/enums.
+- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`). No `malloc`.
+- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
+- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` for Rust.
+
+## Commit Style
+- **Small Commits**: Favour small discreet commits changing one thing.
+- **Maintain Bisectability**: Each commit must compile and pass basic tests.
+- **Separate Refactoring**: Split code movement or style fixes from functional changes.
+- **Commit Messages**: Use a concise subject line, followed by a body explaining "why" (not just "what").
+- **Signed-off-by**: Every commit must have a `Signed-off-by` line.
-- 
2.47.3

[RFC PATCH v3 03/11] scripts/expand-macro.py: helper script exploding macros

[Alex Bennée]

QEMU makes heavy use of C Macros which can be confusing to humans and
seems almost impossible for AI agents to follow. In the past I've
dealt with this by compiling with V=1 and manually copying and pasting
the gcc command line and appending -E to run the pre-processor step.

With the modern build system we now have a compile_commands.json so we
can automate the process with a script.

There is some trickiness involved in following the line markers so we
know where in the source file we are. To handle this we implement a
PreprocessorState object to track where in the include chain we are.
This allows us to show the including location when we dump the
expanded macro.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v3
  - added missing SPDX identifier
---
 scripts/expand-macro.py | 274 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 274 insertions(+)
 create mode 100755 scripts/expand-macro.py

diff --git a/scripts/expand-macro.py b/scripts/expand-macro.py
new file mode 100755
index 00000000000..c0e728dfcc1
--- /dev/null
+++ b/scripts/expand-macro.py
@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Automate the expansion of QEMU macros based on compile_commands.json.
+#
+# This script runs the C preprocessor over a file to expand macros
+# in a specified line range, using the compilation flags defined in
+# compile_commands.json.
+#
+# Copyright (c) Linaro 2026
+#
+import os
+import sys
+import json
+import shlex
+import subprocess
+import argparse
+import re
+
+
+def find_compile_command(target_file, compile_commands):
+    """
+    Search compile_commands to find the rule to build target_file
+    """
+    target_abs = os.path.abspath(target_file)
+    for entry in compile_commands:
+        dir_path = entry.get('directory', '.')
+        file_abs = os.path.abspath(os.path.join(dir_path, entry['file']))
+        if file_abs == target_abs:
+            return entry
+    return None
+
+
+def process_command(command_entry):
+    """
+    Strip out output related options and return a command line that will
+    run the pre-processor only.
+    """
+    command = command_entry.get('command')
+    if not command:
+        args = command_entry.get('arguments', [])
+    else:
+        args = shlex.split(command)
+
+    if not args:
+        return None
+
+    out = []
+    it = iter(args)
+    for arg in it:
+        # the -M* options all deal with generating deps
+        if arg in ('-o', '-MF', '-MQ', '-MT', '-MD', '-MP'):
+            next(it, None)  # Skip the option's argument
+            continue
+        if arg == '-c':
+            continue
+        out.append(arg)
+
+    # Enable pre-processor output, don't strip comments, trace includes
+    out.extend(['-E', '-CC', '-H'])
+    return out
+
+
+def normalize_path(raw_path, working_dir):
+    """Normalize and make paths absolute."""
+    if not os.path.isabs(raw_path):
+        return os.path.abspath(os.path.join(working_dir, raw_path))
+    return os.path.normpath(raw_path)
+
+
+class PreprocessorState:
+    """Tracks the state of the preprocessor as we parse its output."""
+    def __init__(self):
+        self.stack = []
+        self.current_path = None
+        self.current_line = 0
+        self.current_instance_id = 0
+        self.next_instance_id = 1
+        self.sections = {}
+
+    def update_on_marker(self, new_line, flags, path):
+        """Update the file stack and instance tracking based on markers."""
+        # entering new file
+        if "1" in flags:
+            if self.current_path is not None:
+                self.stack.append((self.current_path, self.current_line,
+                                   self.current_instance_id))
+            self.current_path = path
+            self.current_line = new_line
+            self.current_instance_id = self.next_instance_id
+            self.next_instance_id += 1
+            return
+
+        # leaving file
+        if "2" in flags:
+            if self.stack:
+                _, _, popped_instance_id = self.stack.pop()
+                self.current_path = path
+                self.current_line = new_line
+                self.current_instance_id = popped_instance_id
+            else:
+                self.current_path = path
+                self.current_line = new_line
+                self.current_instance_id = self.next_instance_id
+                self.next_instance_id += 1
+            return
+
+        # return to previous file without explicit flag 2
+        if self.current_path != path:
+            if self.stack and self.stack[-1][0] == path:
+                _, _, popped_instance_id = self.stack.pop()
+                self.current_path = path
+                self.current_line = new_line
+                self.current_instance_id = popped_instance_id
+            else:
+                self.current_path = path
+                self.current_line = new_line
+                self.current_instance_id = self.next_instance_id
+                self.next_instance_id += 1
+            return
+            
+        self.current_line = new_line
+
+    def get_context_string(self, target_abs, working_dir):
+        """Generate a descriptive string showing the inclusion context."""
+        if self.stack:
+            ctx_path, ctx_line, _ = self.stack[-1]
+            try:
+                rel_ctx = os.path.relpath(ctx_path, working_dir)
+            except ValueError:
+                rel_ctx = ctx_path
+            return f"{rel_ctx}:{ctx_line}"
+
+        try:
+            rel_ctx = os.path.relpath(target_abs, working_dir)
+        except ValueError:
+            rel_ctx = target_abs
+        return f"{rel_ctx} (main file)"
+
+    def add_line(self, line, line_range, target_abs, working_dir):
+        """Add a line to the sections if it is within the requested range."""
+        start_line, end_line = line_range
+        if self.current_path == target_abs:
+            if start_line <= self.current_line <= end_line:
+                if self.current_instance_id not in self.sections:
+                    ctx_str = self.get_context_string(target_abs, working_dir)
+                    self.sections[self.current_instance_id] = {
+                        "context": ctx_str,
+                        "lines": []
+                    }
+                self.sections[self.current_instance_id]["lines"].append(line)
+        self.current_line += 1
+
+
+def format_output_sections(sections, target_file, start_line, end_line):
+    """Format the accumulated sections into the final output string."""
+    output_sections = []
+    for _instance_id, data in sections.items():
+        if not data["lines"]:
+            continue
+        header = f"/* Expansion from {data['context']} */"
+        body = "\n".join(data["lines"])
+        output_sections.append(f"{header}\n{body}")
+
+    if not output_sections:
+        return (f"/* Error: No lines found for {target_file} "
+                f"in range {start_line}-{end_line} */")
+
+    return "\n/* end of expansion */\n".join(output_sections)
+
+
+def extract_range(stdout, target_file, start_line, end_line, working_dir):
+    """
+    Parse the output of the pre-processor while tracking where we
+    are in the source code from the markers so we can extract the
+    range asked for.
+    """
+    state = PreprocessorState()
+    target_abs = os.path.abspath(target_file)
+    line_range = (start_line, end_line)
+
+    # The format is undocumented but see:
+    #
+    #  gcc/c-family/c-ppoutput.c:print_line_1
+    #
+    # where 1 = entering file, 2 = leaving file
+    # and the 3 or 3 4 depends on linemap_location_in_system_header_p
+    line_marker_re = re.compile(r'^# (\d+) "(.*?)"(.*)')
+
+    for line in stdout.splitlines():
+        match = line_marker_re.match(line)
+        if match:
+            new_line = int(match.group(1))
+            raw_path = match.group(2)
+            flags = match.group(3).split()
+
+            path = normalize_path(raw_path, working_dir)
+            state.update_on_marker(new_line, flags, path)
+            continue
+
+        state.add_line(line, line_range, target_abs, working_dir)
+
+    return format_output_sections(state.sections, target_file,
+                                  start_line, end_line)
+
+
+def main():
+    """Main entry point for the script."""
+    desc = 'Expand macros in a section of a file using compile_commands.json'
+    parser = argparse.ArgumentParser(description=desc)
+    parser.add_argument('file', help='Source file to expand macros in')
+    parser.add_argument('--range', help='Line range (e.g. 100-120)')
+
+    ctx_help = ('Context file (.c) to get compilation flags from '
+                '(useful for headers)')
+    parser.add_argument('--context', help=ctx_help)
+    parser.add_argument('--compile-commands', default='compile_commands.json',
+                        help='Path to compile_commands.json')
+    parser.add_argument('--show-command', action='store_true',
+                        help='Print the modified compile command and exit')
+
+    args = parser.parse_args()
+
+    if not os.path.exists(args.compile_commands):
+        print(f"Error: {args.compile_commands} not found.", file=sys.stderr)
+        sys.exit(1)
+
+    with open(args.compile_commands, encoding="utf-8") as f:
+        compile_commands = json.load(f)
+
+    query_file = args.context if args.context else args.file
+    entry = find_compile_command(query_file, compile_commands)
+
+    if not entry:
+        print(f"Error: Could not find compile command for {query_file}",
+              file=sys.stderr)
+        sys.exit(1)
+
+    cmdline = process_command(entry)
+    if not cmdline:
+        print(f"Error: Failed to process command for {query_file}",
+              file=sys.stderr)
+        sys.exit(1)
+
+    if args.show_command:
+        print(shlex.join(cmdline))
+        sys.exit(0)
+
+    working_dir = entry.get('directory', '.')
+    result = subprocess.run(cmdline, stdout=subprocess.PIPE,
+                            stderr=subprocess.PIPE, cwd=working_dir,
+                            universal_newlines=True, check=False)
+
+    if result.returncode != 0:
+        print(f"Preprocessor failed:\n{result.stderr}", file=sys.stderr)
+        sys.exit(result.returncode)
+
+    content = result.stdout
+    if args.range:
+        try:
+            start, end = map(int, args.range.split('-'))
+            content = extract_range(content, args.file, start, end,
+                                    working_dir)
+        except ValueError:
+            print(f"Error: Invalid range format {args.range}. Use start-end.",
+                  file=sys.stderr)
+            sys.exit(1)
+
+    print(content)
+
+
+if __name__ == "__main__":
+    main()
-- 
2.47.3

[RFC PATCH v3 04/11] .agents/skills: add qemu-code-explorer skill

[Alex Bennée]

This provides a skill detailing how to deal with some of QEMU's more
idiosyncratic coding conventions. Originally I had given instructions
on using tags and git grep but once I'd installed the semcode
MCP (https://github.com/facebookexperimental/semcode) it
was able to handle most code navigation pretty efficiently. So now
this skill just focuses on the things that are tricky for indexers to
handle, namely generated code and fancy macros.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v3
  - rewrote with a focus on generated code and macros for when code
  search MCPs run into trouble.
v2
  - remove personal gtag skill references, add global stanzas directly
  - moved macro information from AGENTS.md into code explorer
  - more imperative language to trigger its use
  - add section on using scripts/expand_macro.py
  - remove eca reference from evals.json (maybe we should just drop this)
---
 .agents/skills/qemu-code-explorer/SKILL.md    | 88 +++++++++++++++++++
 .../qemu-code-explorer/evals/evals.json       | 26 ++++++
 AGENTS.md                                     |  1 +
 3 files changed, 115 insertions(+)
 create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md
 create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json

diff --git a/.agents/skills/qemu-code-explorer/SKILL.md b/.agents/skills/qemu-code-explorer/SKILL.md
new file mode 100644
index 00000000000..7bca389b37d
--- /dev/null
+++ b/.agents/skills/qemu-code-explorer/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: qemu-code-explorer
+description: Advanced QEMU code exploration for special cases (generated code, complex macros, QOM) that are not easily handled by standard code exploration tools. Use this as a fallback strategy for build-time artifacts or hidden symbols.
+license: GPL-2.0-or-later
+---
+
+# QEMU Advanced Code Explorer
+
+When standard code navigation tools fail to find a symbol, it is often because the code is generated at build time or hidden behind complex macros. This skill covers how to find and understand those special cases.
+
+## 1. Searching Generated Code
+
+Generated source files do not reside in the source tree but in the build directory. If a primary symbol search fails, the symbol is likely generated.
+
+### QAPI (QEMU Interface)
+- **Source**: `qapi/*.json`
+- **Generated**: `build/qapi/` (headers and C files)
+- **Patterns**:
+  - `qmp_marshal_...`: Command marshallers.
+  - `qapi_free_...`: Type cleanup functions.
+  - `visit_type_...`: Visitor functions.
+- **Search**: Search the `build/` directory using standard text search tools.
+
+### Tracing
+- **Source**: `trace-events` files throughout the tree.
+- **Generated**: `build/trace/` (e.g., `trace/trace-hw_block.h`)
+- **Patterns**: `trace_...` functions.
+- **Search**: Check the build directory or the generated headers.
+
+### Decodetree (Instruction Decoding)
+- **Source**: `target/.../*.decode` files.
+- **Generated**: Usually included into source files as `.c.inc` artifacts in the build tree.
+- **Patterns**: `trans_...` functions are handwritten, but the decoder that calls them is generated.
+
+### Configuration
+- `build/config-host.h`: Global host configuration.
+- `build/config-target.h`: Target-specific configuration (e.g., `TARGET_X86_64`).
+
+## 2. Expanding Complex Macros
+
+QEMU uses deep macro nesting (especially in TCG and softfloat) which can be opaque to static analysis.
+
+### `scripts/expand-macro.py`
+Use this tool to see the exact C code after preprocessing for a specific range in a file.
+
+- **Usage**:
+  ```bash
+  python3 ./scripts/expand-macro.py FILE --context CONTEXT_FILE --range START_LINE-END_LINE
+  ```
+- **Example**:
+  To see how TCG helpers or softfloat parts expand:
+  ```bash
+  python3 ./scripts/expand-macro.py fpu/softfloat-parts.c.inc --context fpu/softfloat.c --range 191-264
+  ```
+
+## 3. QEMU-Specific Symbol Patterns
+
+Some symbols are "hidden" from simple search tools because of boilerplate-reducing macros.
+
+### QOM (QEMU Object Model)
+Macros like `OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` expand to multiple function declarations and casting macros.
+- If you see `MY_DEVICE(obj)`, it is likely defined via `OBJECT_DECLARE_TYPE(...)`.
+- Search for the type name string (e.g., `"my-device"`) to find the `TypeInfo` structure, which links everything together.
+
+### TCG Helpers
+- **Pattern**: `HELPER(foo)`
+- Defined in `helper.h` or similar, implemented as `helper_foo`.
+- If searching for `helper_foo` fails, search for the `HELPER(foo)` pattern in the source.
+
+### Error Handling
+- `ERRP_GUARD()`: Used at the start of functions to handle `error_propagate`.
+- `error_setg(errp, ...)`: Common pattern for reporting errors.
+
+## Decision Matrix
+
+| Scenario | Strategy |
+|------|--------|
+| Standard function/struct | Use primary code navigation tools. |
+| Symbol not found in source | Search `build/` directory for generated code. |
+| Macro expansion looks wrong | Use `scripts/expand-macro.py`. |
+| QOM casting macro (`TYPE_...`) | Search for the `TypeInfo` or `OBJECT_DECLARE_...` usage. |
+| TCG helper missing | Search for `HELPER(name)` pattern. |
+| Instruction decoding | Check `.decode` files and corresponding `trans_...` functions. |
+
+## Workflow Tips
+1. **Locate the Build Directory**: QEMU developers often use `build/` but it could be named differently. Always check.
+2. **Combine Tools**: Use primary tools first. If they fail, search the `build/` directory.
+3. **Check the Context**: If a `.c.inc` file is confusing, find the `.c` file that includes it to understand the macro context.
diff --git a/.agents/skills/qemu-code-explorer/evals/evals.json b/.agents/skills/qemu-code-explorer/evals/evals.json
new file mode 100644
index 00000000000..8eaa45b28b3
--- /dev/null
+++ b/.agents/skills/qemu-code-explorer/evals/evals.json
@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+{
+  "skill_name": "qemu-code-explorer",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Where is the function 'qemu_mutex_lock' defined and where is it used in the block layer (block/)?",
+      "expected_output": "The definition should be found (likely in util/qemu-thread-posix.c or similar) and usages in block/ should be listed using gtags."
+    },
+    {
+      "id": 1,
+      "prompt": "I'm seeing a reference to 'qmp_marshal_query_status' in some docs but I can't find it in the source tree. Can you find where it is defined?",
+      "expected_output": "The agent should identify this as QAPI generated code and look in the build directory (e.g., build/qapi/qapi-commands-control.c)."
+    },
+    {
+      "id": 2,
+      "prompt": "Find all implementations of trace points for 'virtio_net' in the generated code.",
+      "expected_output": "The agent should search for 'trace_virtio_net_*' in the build directory, specifically in generated trace headers/sources."
+    },
+    {
+      "id": 3,
+      "prompt": "Find all occurrences of the string 'Could not open' in the 'hw/' directory.",
+      "expected_output": "The agent should use git grep scoped to hw/ to find the string literals."
+    }
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
index 3fd56fe3309..a34a92244e5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,7 @@ If unsure read the linked document for guidance.
 
 ## Agent Skills (see `.agents/skills`)
 You should use the following specialized skills for common tasks:
+- `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 05/11] .agents/skills: add qemu-build skill

[Alex Bennée]

This provides basic instructions for building QEMU.

Tested-by: Chao Liu <chao.liu.zevorn@gmail.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v3
  - add builds to gitignore
v2
  - drop ECA/qemu-helper-agent sub-agent language
  - mention configure --help
  - drop mention of full paths - not needed for compilation
  - moved earlier is series so code-reviewer can refer to it
---
 .agents/skills/qemu-build/SKILL.md | 50 ++++++++++++++++++++++++++++++
 .gitignore                         |  1 +
 AGENTS.md                          |  1 +
 3 files changed, 52 insertions(+)
 create mode 100644 .agents/skills/qemu-build/SKILL.md

diff --git a/.agents/skills/qemu-build/SKILL.md b/.agents/skills/qemu-build/SKILL.md
new file mode 100644
index 00000000000..91819a0992a
--- /dev/null
+++ b/.agents/skills/qemu-build/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: qemu-build
+description: Provides step-by-step instructions on configuring and building QEMU. You MUST trigger this skill whenever the user asks to build QEMU or debug build failures. It includes critical details on build directory reuse and spawning sub-agents.
+license: GPL-2.0-or-later
+---
+
+# Instructions
+
+## Examining and Re-using Build Directories
+Before creating a new build directory, check if an existing one can be re-used. QEMU uses out-of-tree builds, typically in `build` or `builds/` sub-directories.
+
+1. **Check existing configs**: You can examine how an existing build directory was configured by checking its `config.log`. Run `head -n 2 builds/<dir>/config.log`. The second line typically contains the full `../configure` command line used.
+2. **Re-use and Reconfigure**: You have latitude to re-use existing directories when appropriate (e.g., `builds/debug` which is a general-purpose debug directory for whatever is currently going on). If an existing directory has the right flags (like debug/sanitizers) but the wrong target list, you can reconfigure it to keep the same config but change the `--target-list`:
+   ```bash
+   cd builds/debug
+   # Check the old config.log, then re-run configure with the new target-list
+   ../../configure <old-flags> --target-list=<new-targets>
+   ```
+
+## Launching Builds
+**Crucial**: You MUST NEVER run builds directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent.
+Pass the specific build commands, along with the required working directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you.
+For example: `task: "Navigate to builds/debug and run ninja. If it fails, report the exact compiler errors."`
+
+## Configuring a New Build
+If no suitable build directory exists, create a new one.
+
+1. **Create build directory**: `mkdir -p builds/test-target; cd builds/test-target`
+2. **Basic Configure**: `../../configure --target-list=[list of targets]`
+   - Common targets: `x86_64-softmmu`, `aarch64-softmmu`, `riscv64-softmmu`, `x86_64-linux-user`.
+3. **Common Options**:
+   - `--enable-debug-info`: Include symbols.
+   - `--enable-debug`: Enable assertions.
+4. **Sanitizers**:
+   - `--enable-asan`: Address Sanitizer.
+   - `--enable-tsan`: Thread Sanitizer.
+   - `--enable-ubsan`: Undefined Behavior Sanitizer.
+5. **Help**:
+   - `--help`: will give a comprehensive list of options
+
+## Building
+**Important**: Always re-run the build after making changes to the source code.
+
+## Reporting Results
+**Crucial**: After completing the build task, provide a concise summary of the results to the user.
+1. **Summary**: State whether the build passed or failed.
+2. **Failure Excerpts**: If the build fails, include relevant excerpts from the logs (e.g., compiler errors).
+
+## Debugging and Environment
+- **Verbose**: `V=1` for detailed output.
diff --git a/.gitignore b/.gitignore
index 4ccba871d16..83bdf3df59c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 /GNUmakefile
 /build/
+/builds/
 /.cache/
 /.vscode/
 *.pyc
diff --git a/AGENTS.md b/AGENTS.md
index a34a92244e5..29a13ca01b4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,7 @@ If unsure read the linked document for guidance.
 ## Agent Skills (see `.agents/skills`)
 You should use the following specialized skills for common tasks:
 - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
+- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 06/11] .agents/skills: add qemu-testing skill

[Alex Bennée]

This provides basic instructions for running tests but doesn't try to
exhaustively describe the whole setup.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v2
  - add link to testing docs.
---
 .agents/skills/qemu-testing/SKILL.md | 56 ++++++++++++++++++++++++++++
 AGENTS.md                            |  1 +
 2 files changed, 57 insertions(+)
 create mode 100644 .agents/skills/qemu-testing/SKILL.md

diff --git a/.agents/skills/qemu-testing/SKILL.md b/.agents/skills/qemu-testing/SKILL.md
new file mode 100644
index 00000000000..e5979dfc1c5
--- /dev/null
+++ b/.agents/skills/qemu-testing/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: qemu-testing
+description: Provides instructions on how to find, list, and run individual tests for QEMU (Unit, QTest, Functional, TCG). You MUST use this skill whenever the user asks about tests, wants to list available tests, or wants to run any test in a build directory, even for simple exploratory queries like "what tests can I run". It includes details about spawning sub-agents.
+license: GPL-2.0-or-later
+---
+
+# Instructions
+To run QEMU tests, you can use several different suites depending on what you are testing. **Note**: Ensure you have a recent build of QEMU before running tests. Use the `qemu-build` skill if you need to configure or run a build.
+
+For exhaustive details on the testing infrastructure, architectures, and specific test requirements, you MUST refer to the official documentation in:
+- `docs/devel/testing/` (specifically `main.rst`)
+
+## General Test Suites
+- **Unit Tests**: `make check-unit`
+- **QTest (Device emulation)**: `make check-qtest`
+- **Functional Tests (Python based)**: `make check-functional`
+- **TCG Tests (CPU instruction tests)**: `make check-tcg`
+
+## Launching Tests
+**Crucial**: You MUST NEVER run a test suites directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent. Pass the specific build or test commands, along with the required build directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you.
+For example: `task: "Navigate to builds/debug and check what meson tests touch replay and report back."` or `task: "Run make check-tcg in builds/arm and summarize any failing tests."`
+
+### From the Build Directory
+Most individual tests from within a build directory. Most (unit, qtest, block, functional) can be individually selected and run via meson.
+
+As QEMU often needs a newer meson than the build host you should use the build `pyenv` to launch it:
+- **Example**: `./pyvenv/bin/meson test --suite thorough --list` to see what tests are in the thorough test suite
+
+## Running Individual Tests
+
+### Meson Test Runner (Unit, QTest, Functional, softfloat etc)
+To run a single test, you can use the meson test runner from within your pyvenv:
+`./pyvenv/bin/meson test [testname]`
+Example: `./pyvenv/bin/meson test qtest-x86_64/boot-serial-test`
+
+### TCG Tests
+To run individual TCG tests for a specific architecture:
+1. Navigate to the relevant build directory, e.g.: `cd tests/tcg/aarch64-softmmu`
+2. Run a specific test with make: `make run-[testname]`
+   Example: `make run-memory-sve`
+3. Use `make help` within the architecture directory to see the full list of available tests.
+
+### Functional Tests
+Individual functional tests can be run directly using the run script although from the source directory:
+- **Example**: `./builds/all/run tests/functional/aarch64/test_virt_vbsa.py`
+
+### Environment Variables
+- `V=1` for verbose output from tests.
+- `SPEED=slow` to run slower tests that are normally skipped.
+
+## Reporting Results
+**Crucial**: After completing the build and test tasks, provide a concise summary of the results to the calling agent.
+1. **Summary**: State whether the build and tests passed or failed.
+2. **Failure Excerpts**: If any task fails, include relevant excerpts from the logs (e.g., compiler errors, test failures).
+3. **Full Paths**: Always provide the **absolute file paths** to the full logs and result sets for further inspection.
+
diff --git a/AGENTS.md b/AGENTS.md
index 29a13ca01b4..f5439282967 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,7 @@ If unsure read the linked document for guidance.
 You should use the following specialized skills for common tasks:
 - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
 - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
+- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 07/11] .agents/skills: add qemu-code-reviewer skill

[Alex Bennée]

This provides basic instructions for how to download and apply a
patch series from the mailing list.

Currently it is only taught about checkpatch but we could consider
adding common code smells and review comments that come up frequently.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v2
  - merge checkpatch skill
  - moved later in series to leverage build and test skills
  - properly reference qemu-build and qemu-tester skills
  - mention the qemu-code-explorer skill for navigation
---
 .agents/skills/qemu-code-reviewer/SKILL.md | 93 ++++++++++++++++++++++
 AGENTS.md                                  |  1 +
 2 files changed, 94 insertions(+)
 create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md

diff --git a/.agents/skills/qemu-code-reviewer/SKILL.md b/.agents/skills/qemu-code-reviewer/SKILL.md
new file mode 100644
index 00000000000..48ec6b07520
--- /dev/null
+++ b/.agents/skills/qemu-code-reviewer/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: qemu-code-reviewer
+description: Pull and apply patch series from mailing lists for review and testing in QEMU, including style and build validation.
+license: GPL-2.0-or-later
+---
+
+# QEMU Code Reviewer Skill
+
+This skill provides instructions on how to retrieve patch series submitted to the QEMU mailing list (`qemu-devel@nongnu.org`) using `b4` or manual methods.
+
+## Using b4 (Recommended)
+
+`b4` is the preferred tool for working with patch series from public-inbox instances like `lore.kernel.org`.
+
+### 1. Fetching a series
+To download a series and prepare it for `git am`:
+```bash
+b4 am <message-id-or-url>
+```
+This creates a `.mbx` file containing the entire series, properly ordered.
+
+### 2. Applying a series directly
+To apply a series directly to your current branch:
+```bash
+b4 shazam <message-id-or-url>
+```
+This is often the fastest way to get a series ready for testing.
+
+### 3. Creating a local branch for the series
+```bash
+b4 am -t <message-id-or-url>
+git am ./*.mbx
+```
+The `-t` flag (or `--trust-all`) can be useful if you know the source.
+
+## Manual mbox Retrieval (Alternative)
+
+If `b4` is unavailable, you can fetch the mbox manually from `lore.kernel.org`.
+
+### 1. Locate the thread
+Find the patch series on [lore.kernel.org/qemu-devel/](https://lore.kernel.org/qemu-devel/).
+
+### 2. Download the mbox
+Every thread on lore has an `mbox.gz` link. You can use `curl` or `wget`:
+```bash
+curl -L "https://lore.kernel.org/qemu-devel/<message-id>/raw" -o series.mbox
+```
+*Note: Appending `/raw` to the message URL usually provides the mbox format.*
+
+### 3. Apply with git am
+```bash
+git am series.mbox
+```
+
+## Post-Application Steps
+
+Once the patches are applied, you should perform initial validation:
+
+### 1. Style Check
+Run the QEMU checkpatch script to ensure the patches follow the project's coding style.
+
+- **Check applied patches**:
+  ```bash
+  ./scripts/checkpatch.pl master..HEAD
+  ```
+- **Check a specific commit**:
+  ```bash
+  ./scripts/checkpatch.pl <commit-hash>^..
+  ```
+- **Check a specific file**:
+  ```bash
+  ./scripts/checkpatch.pl -f <file-path>
+  ```
+- **Strict mode** (often required for new code or specific subsystems):
+  ```bash
+  ./scripts/checkpatch.pl --strict <commit-range>
+  ```
+
+### 2. Build and Test
+Refer to the `AGENTS.md` or the `qemu-build` and `qemu-testing` skills for build and test instructions.
+- Ensure you are in a clean build directory.
+- Run `ninja` or `make`.
+- Run relevant tests (e.g., `make check-qtest`).
+
+### 3. Reviewing Patches
+Refer to the `qemu-code-explorer` skill for navigating the code base and resolving functions and where they are called from.
+
+
+
+## Common Troubleshooting
+
+- **Applying fails**: If `git am` fails due to conflicts, you may need to use `git am --3way` or manually resolve conflicts.
+- **Missing dependencies**: Ensure your tree is up to date with the base branch the patches were intended for (usually `master`).
diff --git a/AGENTS.md b/AGENTS.md
index f5439282967..fe50057cef7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,6 +33,7 @@ You should use the following specialized skills for common tasks:
 - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
 - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
 - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
+- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 08/11] .agents/skills: add qemu-mail-thread skill

[Alex Bennée]

Teach agents how to fetch and deal with archives of mail threads.

Just YOLO'ing the entire mail thread into an LLM context is quite
expensive especially if reviewing a thread against your current tree
state. This skill allows the agent to extract just the comments and
tags saving tokens.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v3
  - add header.
v2
  - rename to qemu-mail-thread
  - add instructions on fetching threads via b4
  - refactor the metadata handling in the script
  - mention in AGENTS skill list
---
 .agents/skills/qemu-mail-thread/SKILL.md      | 40 ++++++++
 .../scripts/qemu_mail_parser.py               | 98 +++++++++++++++++++
 AGENTS.md                                     |  1 +
 3 files changed, 139 insertions(+)
 create mode 100644 .agents/skills/qemu-mail-thread/SKILL.md
 create mode 100644 .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py

diff --git a/.agents/skills/qemu-mail-thread/SKILL.md b/.agents/skills/qemu-mail-thread/SKILL.md
new file mode 100644
index 00000000000..a3257dabc2f
--- /dev/null
+++ b/.agents/skills/qemu-mail-thread/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: qemu-mail-thread
+description: Fetch and extract reviewer comments from QEMU mailing list threads, handling mbox files or raw text dumps.
+license: GPL-2.0-or-later
+---
+
+# QEMU Mail Thread
+
+This skill helps you fetch and extract reviewer comments from QEMU mailing list threads. It can handle standard `mbox` files (e.g., from `b4 mbox`) or raw text dumps from the user.
+
+## How to fetch a mail thread
+
+If you have a Message-ID (e.g., from a patch series), use `b4` to fetch the entire thread:
+
+```bash
+b4 mbox <message-id>
+```
+
+This will typically save an `.mbx` file in your current directory.
+
+## How to parse comments
+
+Use the included Python script to extract feedback, filtering out quoted text and diffs.
+
+```bash
+python .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py <path_to_mail_thread_file>
+```
+
+The script automatically detects whether the input is a standard mbox or a raw text dump.
+
+## Expected Output
+The script generates `parsed_comments.txt` in the current working directory:
+```
+--- REPLY FROM Reviewer Name <email@example.com> ---
+Subject: Re: [PATCH 01/10] ...
+Comment text here...
+============================================================
+```
+
+Use this structured text to efficiently analyze the feedback and identify outstanding suggestions.
diff --git a/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
new file mode 100644
index 00000000000..fdaac57ac15
--- /dev/null
+++ b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+import sys
+import os
+import mailbox
+
+
+def is_metadata_line(line):
+    """Check if a line is metadata (quotes, diff, etc.)"""
+    return (line.startswith(">") or
+            line.startswith("---") or
+            line.startswith("diff "))
+
+
+def parse_raw_text(text, output_f):
+    # Split by the separator used in lore.kernel.org / b4 dumps
+    messages = text.split("----------------------------------------")
+    for msg in messages:
+        if not msg.strip(): continue
+
+        lines = msg.strip().split('\n')
+        author = ""
+        subject = ""
+        body_start = 0
+        for i, line in enumerate(lines):
+            if line.startswith("From: "): author = line[6:]
+            if line.startswith("Subject: "): subject = line[9:]
+            if not line.strip() and body_start == 0:
+                body_start = i + 1
+                break
+
+        is_reply = subject and ("Re: " in subject or subject.startswith("Re:"))
+
+        if is_reply and author != "" and not author.startswith("qemu-devel"):
+            output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
+
+            for line in lines[body_start:]:
+                if not is_metadata_line(line):
+                    output_f.write(line + "\n")
+            output_f.write("="*60 + "\n\n")
+
+
+def parse_mbox(mbox_path, output_f):
+    mbox = mailbox.mbox(mbox_path)
+    for message in mbox:
+        subject = message['subject']
+        if subject and 'Re: ' in subject:
+            author = message['from']
+            output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
+
+            payload = message.get_payload()
+            body = ""
+            if isinstance(payload, list):
+                # Handle multipart
+                for part in payload:
+                    if part.get_content_type() == 'text/plain':
+                        body = part.get_payload(decode=True).decode('utf-8', errors='ignore')
+                        break
+            else:
+                body = message.get_payload(decode=True).decode('utf-8', errors='ignore')
+
+            # Simple heuristic to extract comments
+            for line in body.split('\n'):
+                if line.strip() and not is_metadata_line(line.strip()):
+                    output_f.write(line + "\n")
+            output_f.write("="*60 + "\n\n")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python qemu_mail_parser.py <mail_thread_file>")
+        sys.exit(1)
+
+    input_file = sys.argv[1]
+    output_file = "parsed_comments.txt"
+
+    if not os.path.exists(input_file):
+        print(f"Error: File not found - {input_file}")
+        sys.exit(1)
+
+    with open(output_file, "w", encoding="utf-8") as out_f:
+        # Detect if it's an mbox or raw text
+        with open(input_file, 'rb') as f:
+            header = f.read(15)
+            is_mbox = header.startswith(b'From mboxrd@z ')
+
+        if is_mbox:
+            print(f"Parsing {input_file} as mbox...")
+            parse_mbox(input_file, out_f)
+        else:
+            print(f"Parsing {input_file} as raw text dump...")
+            with open(input_file, "r", encoding="utf-8", errors='ignore') as f:
+                text = f.read()
+            parse_raw_text(text, out_f)
+
+    print(f"Done. Extracted comments saved to {output_file}")
+
+if __name__ == "__main__":
+    main()
diff --git a/AGENTS.md b/AGENTS.md
index fe50057cef7..26a9c93007b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,6 +34,7 @@ You should use the following specialized skills for common tasks:
 - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
 - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
 - `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
+- `qemu-mail-thread`: For analyzing and parsing mailing list threads.
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 09/11] .agents/skills: add qemu-issue-helper skill

[Alex Bennée]

This provides basic instructions for fetching issue details and
summarising details about the issue for other agents.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 .agents/skills/qemu-issue-helper/SKILL.md | 47 +++++++++++++++++++++++
 AGENTS.md                                 |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 .agents/skills/qemu-issue-helper/SKILL.md

diff --git a/.agents/skills/qemu-issue-helper/SKILL.md b/.agents/skills/qemu-issue-helper/SKILL.md
new file mode 100644
index 00000000000..725097bac36
--- /dev/null
+++ b/.agents/skills/qemu-issue-helper/SKILL.md
@@ -0,0 +1,47 @@
+---
+name: qemu-issue-helper
+description: Summarize QEMU issue analysis for main agent. Helps sub-agents report findings including build config, CLI, tests, and GitLab issue data. Trigger when analyzing QEMU bugs or issues reported on GitLab.
+license: GPL-2.0-or-later
+---
+
+# QEMU Issue Helper
+
+Assist sub-agent in summarizing issue analysis for main agent.
+
+## Fetching Issue Data
+
+Use `glab` to retrieve issue details from GitLab. QEMU primary repo: `qemu-project/qemu`.
+
+### Commands
+- **View issue**: `glab issue view <ID_OR_URL> -R qemu-project/qemu`
+- **View comments**: `glab issue view <ID_OR_URL> -R qemu-project/qemu --comments`
+- **Search issues**: `glab issue list -R qemu-project/qemu --search "<KEYWORDS>"`
+
+## Report Format
+
+Sub-agent MUST provide a summary of the GitLab issue discussion and findings in this format:
+
+### 1. Issue Context
+- **Source**: GitLab URL/ID.
+- **Title**: Short issue description.
+- **Reporter**: User who found it.
+- **Relevant Commits**: List any commits mentioned in the issue that are related to the bug or previous attempts to fix it.
+
+### 2. Build & Reproduction (from issue)
+- **Reported Environment**: Host OS, CPU, QEMU version.
+- **Build Configuration**: Required `configure` flags mentioned in the issue.
+- **Reproduction CLI**: Exact QEMU command used to reproduce.
+
+### 3. Proposed Fixes & Series
+- **Proposed Fixes**: Flag any specific code snippets or logic fixes suggested in the comments.
+- **Patch Series**: Note if any patch series or Merge Requests have been linked.
+
+### 4. Discussion Summary
+- **Current Consensus**: What is the community's current understanding of the bug?
+- **Key Constraints**: Note any blockers, requirements, or specific feedback from maintainers.
+- **Next Steps**: What is needed to move the issue forward?
+
+## Rules
+- **No Independent Analysis**: Do not perform your own root cause analysis. Summarize ONLY what is present in the issue tracker.
+- **Terse**: Use brief technical English.
+- **Links**: Provide direct links to relevant comments or patches if available.
diff --git a/AGENTS.md b/AGENTS.md
index 26a9c93007b..6a91c39638e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -35,6 +35,7 @@ You should use the following specialized skills for common tasks:
 - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
 - `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
 - `qemu-mail-thread`: For analyzing and parsing mailing list threads.
+- `qemu-issue-helper`: For fetching and summarising issue details from the bug tracker.
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 10/11] .agents/skills: add qemu-issue-triage agent skill

[Alex Bennée]

While triaging the issue tracker I wondered if this would be a
suitable job for an AI agent. Unfortunately the OSS program doesn't
give any credits to run agents in gitlab. However I do have access to
models from my editor and ECA so I built one and tested it on a few
issues.

We might want to consider adding some common "issue smells" for common
problems in issues. For example triggering asserts that have been
added to the code and other such annoyances.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v4
  - fix a bunch of typos in SKILL
  - update evals
  - remove mentions of ECA
  - fix typo referencing old skill name
  - remove eca__spawn_agent reference
  - clean-up authentication handling
  - teach it about scoped labels
  - make less chatty in the comments
  - updated commit msg
  - suggest running things in parallel (use agents)
  - more pointers to incompleteness
v3
  - more imperative phrasing
v2
  - prefer sub-agent
  - mention parameters
  - don't be over eager to tag host or target for generic bugs
  - signoff comments as an agent on behalf of the user
  - detect patch available and apply appropriate tags
---
 .agents/skills/qemu-issue-triage/SKILL.md     | 112 +++++++++++++++
 .../qemu-issue-triage/assets/labels.txt       | 133 ++++++++++++++++++
 .../skills/qemu-issue-triage/evals/evals.json |  18 +++
 .../scripts/update_labels.sh                  |  16 +++
 AGENTS.md                                     |   1 +
 5 files changed, 280 insertions(+)
 create mode 100644 .agents/skills/qemu-issue-triage/SKILL.md
 create mode 100644 .agents/skills/qemu-issue-triage/assets/labels.txt
 create mode 100644 .agents/skills/qemu-issue-triage/evals/evals.json
 create mode 100755 .agents/skills/qemu-issue-triage/scripts/update_labels.sh

diff --git a/.agents/skills/qemu-issue-triage/SKILL.md b/.agents/skills/qemu-issue-triage/SKILL.md
new file mode 100644
index 00000000000..a0802e24dd3
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: qemu-issue-triage
+description: Use this skill to triage and label GitLab issues for the QEMU project
+license: GPL-2.0-or-later
+---
+
+# Instructions
+
+This skill provides specialized instructions for triaging GitLab issues for the QEMU project.
+
+## Parameter Handling & Execution Strategy (CRITICAL)
+1. **Parameters**: If the user invokes this skill with multiple arguments or a list of IDs (e.g., `#3430, #3426`), treat each as an independent target.
+2. **Sub-Agent Mandate**: To prevent polluting the main conversation context, **you MUST ALWAYS spawn a sub-agent** to perform the actual triage.
+   - **Parallelization**: When multiple IDs are provided, spawn one sub-agent per issue in parallel to improve efficiency.
+   - Do NOT run `glab` commands or read the label cache directly in the main context.
+   - In the `task` parameter for the sub-agent, provide the target `<issue-id>` and explicitly instruct the sub-agent to follow the "Triage Workflow" and "Asset Management" rules defined below.
+   - Wait for the sub-agent to finish and simply report its summary to the user.
+
+## Goal
+Automate the initial triage of new bug reports and feature requests in the QEMU GitLab repository.
+
+## Prerequisites
+- `glab` CLI tool installed.
+- An authentication method: Use `glab auth status` to check. You can pass a token by using `env GITLAB_TOKEN=<token>` in front of commands if you have it.
+- Target Repo: Use `-R qemu-project/qemu` if not in a clone, or ensure the remote is set correctly.
+
+## Asset Management (Label Cache)
+This skill uses a cached list of labels to avoid unnecessary API calls and ensure consistent labeling.
+- **Cache Location:** `assets/labels.txt` relative to this skill.
+- **Updating the Cache:** If the user asks to update the labels, or if you suspect a label is missing, run the provided script:
+  ```bash
+  cd .agents/skills/qemu-issue-triage/scripts && ./update_labels.sh
+  ```
+- **Using the Cache:** Before applying labels, ALWAYS read `assets/labels.txt` (or use `grep` on it) to review the available labels and their descriptions. This ensures you use the exact spelling and understand the intent behind the label (e.g., `kind::Bug`, `Storage`). Do NOT guess label names.
+
+## Triage Workflow
+
+### 1. Information Gathering
+Fetch the issue details:
+```bash
+glab issue view <issue-id> -R qemu-project/qemu --comments
+```
+
+### 2. Evaluate Completeness
+Analyze the issue against the bug template requirements:
+- **Host Arch/OS**: Is the host environment specified?
+- **Guest Arch/OS**: Is the guest environment specified?
+- **QEMU Version**: Is the version mentioned?
+- **Reproduction Steps**: Are there clear steps to reproduce?
+- **Expected vs Actual**: Is the bug clearly described?
+
+**Workflow::Needs Info Triggers (CRITICAL):**
+Request more information and apply the `workflow::Needs Info` label if any of the following are true:
+- **Missing Command Line**: The full QEMU command line (`qemu-system-* ...`) used to reproduce the issue is missing.
+- **Old QEMU Version**: The reported version is older than the last two major releases. Ask the reporter to re-test with the current upstream master or the latest stable release.
+- **Distro Version**: The version string suggests a downstream/distro-specific package (e.g., contains suffixes like `.el9`, `.fc40`, `-ubuntu`, or long strings like `7.2.0-14.sc05...`). Ask the reporter to reproduce the issue using a clean build from the current upstream source to rule out distro-specific patches.
+
+**Actions:**
+- If information is missing based on the triggers above, add the `workflow::Needs Info` label and post a polite comment asking for the specific missing details. (Remember to sign the comment as "Issue Agent Bot on behalf of the user" per the Guidelines).
+- If the issue is well-defined and uses a recent upstream version, proceed to categorization.
+
+### 3. Categorization & Labelling
+Apply labels based on the issue content. **Crucially, consult `assets/labels.txt` to find the exact matching labels for the categories below.**
+
+#### Scoped Labels (Prefix::Label)
+QEMU uses scoped labels (e.g., `kind::Bug`, `workflow::Triaged`) to group related categories.
+- **Prefixes:** Common prefixes include `kind::`, `workflow::`, `Closed::`, `Audit Tooling::`, `GUI::`.
+- **Constraint:** Only one label from that scope can be active at a time. Applying a new scoped label of the same type (e.g `workflow::`) will remove the other.
+
+#### Kinds
+- `kind::Bug`: For unexpected behavior.
+- `kind::Feature Request`: For new functionality.
+- `kind::Task`: For research, investigations, and miscellaneous issues.
+
+#### Targets (target: *) and Hosts (host: *)
+Detect the guest architecture (`target: *`) or host environment (`host: *`).
+**IMPORTANT:** Be conservative when applying `target:` and `host:` labels. Many bugs (e.g., in generic devices like USB, PCI, or block controllers) apply to ANY guest that includes the device. The reproducer (like a `qtest` invocation) might just use a convenient target (e.g., `i386`) as an example. ONLY apply `target:` or `host:` labels if the bug is strictly architecture- or host-dependent (e.g., a bug in ARM CPU emulation, or a macOS-specific build failure).
+
+#### Accelerators (accel: *)
+Detect the accelerator mentioned (e.g., `accel: KVM`, `accel: TCG`, `accel: HVF`).
+
+#### Subsystems
+Identify the relevant subsystem (e.g., `Storage`, `Networking`, `device:virtio`, `Migration`).
+
+#### Testcases
+- If the issue provides a minimal C program, a shell script, or a specific disk image to reproduce the bug, apply the `TestCase` label.
+
+#### Patches and Fixes
+- If the issue description or comments contain a link to a patch on the mailing list (e.g., `lore.kernel.org`, `patchew.org`), or explicitly mention that a patch/fix has been submitted, apply the `workflow::Patch available` label.
+
+#### Workflow Management
+The `workflow::` labels track the lifecycle of an issue.
+- **Single Workflow Label:** An issue can only have one `workflow::` label at a time.
+- **Transitioning:** Adding a new workflow label will automatically remove the old one (e.g., adding `workflow::Patch available` will remove `workflow::Triaged`).
+
+#### Other comments
+- If other developers have commented see if those comments imply additional tags should be applied.
+
+### 4. Updating the Issue
+Apply the labels and optionally assign a priority if clear.
+**Transitioning Workflow Example:**
+```bash
+glab issue update <issue-id> -R qemu-project/qemu --label "workflow::Triaged,kind::Bug"
+```
+
+## Guidelines
+- Be polite and professional in comments.
+- **IMPORTANT:** Any comments added to the issue MUST include the phrase: "Issue Agent Bot on behalf of the user" (e.g., as a sign-off at the end of the message).
+- Avoid commenting unless additional information is needed, specifically a comment to acknowledge the report is superfluous.
+- Use `workflow::Triaged` once categorization is complete.
+- Avoid assigning issues to specific people unless they are explicitly mentioned or are the known maintainer for a very specific subsystem.
+- Use the `scripts/get_maintainer.pl` logic (via file paths mentioned in the issue) to identify potential subsystems.
diff --git a/.agents/skills/qemu-issue-triage/assets/labels.txt b/.agents/skills/qemu-issue-triage/assets/labels.txt
new file mode 100644
index 00000000000..12d3cc7e6f0
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/assets/labels.txt
@@ -0,0 +1,133 @@
+ACPI                            Power Management related (ACPI / SMBIOS / HEST / GHES)
+Audio                           Audio devices; both backend (host audio) and frontend (guest audio)
+Audit Tooling::AI               For bugs found with AI assisted tools such as Mythos and other similar things
+Audit Tooling::Fuzzer           Issues found via fuzzing. For security issues, please consult https://www.qemu.org/contribute/security-process/
+Audit Tooling::Other            Some unknown/unclassified type of audit tooling.
+Audit Tooling::Sanitizer        For issues found using sanitizers such as asan, lsan and tsan
+Audit Tooling::Static Analysis  Static analysis such as Coverity or more modern compilers.
+Bite Sized                      Candidates for first contributions; see also https://wiki.qemu.org/Contribute/BiteSizedTasks
+Build System                    configure, make, Meson, ninja, gcc, clang, ccache, etc.
+CI                              Continuous Integration; gitlab, patchew, etc.
+CLI                             Command Line Interface
+Chardev                         Character device backends and related issues
+Closed::Duplicate               There is already another ticket that is about the same issue
+Closed::Fixed                   The issue was fixed. Yay!
+Closed::Invalid                 This issue was not really a problem
+Closed::NotOurBug               This is a bug, but not a bug in QEMU. Please report it and/or include a link to the report.
+Closed::NotReproducible         This issue was not reproducible
+Closed::UnbackedFeature         Nobody was willing to work on this feature request
+Closed::WontFix                 The issue was acknowledged, but the fix would be too complex, too expensive, or would introduce other problems.
+Cryptography                    
+Documentation                   Sphinx documentation, man pages, the wiki, --help output, etc.
+GDB                             Issues relating to using GDB via the gdbstub
+GUI                             Graphical User Interface (gtk, SDL, curses, VNC, spice, ...)
+GUI::Cocoa                      Cocoa
+GUI::DBus                       DBus
+GUI::GTK                        GTK
+GUI::SDL                        SDL
+GUI::SPICE                      SPICE
+GUI::VNC                        
+Guest Agent                     Issues related to the qemu-guest-agent binary. https://wiki.qemu.org/Features/GuestAgent
+Hard                            
+Launchpad                       Issues migrated from Launchpad
+Migration                       
+Modules                         
+Networking                      
+Python                          Python library issues (./python/)
+QAPI/QMP                        QEMU API / QEMU Machine Protocol, HMP and CLI, etc.
+QOM                             QEMU Object Model
+Regression                      This is a regression from previously working behaviour
+Security                        This is a security issue - see https://www.qemu.org/docs/master/system/security.html for guidance
+Semihosting                     Semihosting calls provide a simple ABI for early bring-up of embedded devices, see https://www.qemu.org/docs/master/about/emulation.html#semihosting
+Softfloat                       QEMU's FPU emulation code (TCG only)
+Stable::can't fix               The bug was reported on a stable branch but the fix is too invasive for backporting
+Stable::obsolete                The bug was reported on a stable branch that is not maintained anymore
+Stable::to backport             The bug was reported on a stable branch and needs to be backported on the next release from the branch
+Storage                         Block subsystem, Storage devices, etc.
+TCG plugins                     Anything related to the TCG plugins feature
+TestCase                        The report includes a testcase
+Tests                           qtests, iotests, acceptance tests, VM tests, docker tests, and more. See https://www.qemu.org/docs/master/devel/testing/index.html
+USB                             
+VFIO                            
+accel: HAX                      Intel's Hardware Accelerated Execution Manager (HAXM)
+accel: HVF                      Apple Hypervisor Framework
+accel: KVM                      Linux Kernel-based Virtual Machine
+accel: TCG                      QEMU Tiny Code Generator
+accel: WHPX                     Microsoft Windows Hypervisor Platform (WHPX)
+accel: Xen                      Xen Hypervisor
+block:9p                        The 9p network file system
+block:NVMe                      
+block:curl                      
+block:nbd                       
+block:nfs                       Issues related to the NFS backend
+block:qcow2                     
+block:ssh                       
+block:vmdk                      
+bsd-user                        
+device: PCI                     
+device: TPM                     Trusted Platform Module (TPM) devices
+device: iommu                   
+device: mmio                    mmio and other directly emulated devices
+device:graphics                 Issues relating to display device emulation, or rendering in general. See also "GUI".
+device:input                    Keyboards, Mice, Touchscreens, HIDs, etc.
+device:iommu                    IOMMU and SMMU
+device:pflash                   Parallel NOR flashes emulation
+device:sdmmc                    SD or (e)MMC cards emulation
+device:virtio                   virtio-related issues. https://www.linux-kvm.org/page/Virtio
+device:watchdog                 
+efi                             EFI firmware related issues
+flaky-ci                        For test cases that are flaky when run under our CI
+gitlab                          
+guest: AIX                      
+guest: BSD                      Guest OS is BSD (NetBSD/FreeBSD/OpenBSD/etc)
+guest: Linux                    Guest OS is Linux/Linux-based
+guest: Windows                  Microsoft Windows guest
+guest: macOS                    Apple macOS / Darwin as  guest OS
+guest: os2                      
+host: aarch64                   Bugs reproducible on AArch64 hosts
+host: arm                       Bugs reproducible on ARM hosts
+host: loongarch64               Bugs reproducible on LoongArch64 hosts.
+host: mips                      Bugs reproducible on MIPS hosts
+host: ppc                       Bugs reproducible on Power hosts
+host: riscv                     Bugs reproducible on RISC-V hosts
+host: s390                      Bugs reproducible on s390 hosts
+host: sparc64                   Bugs specific to Sparc64 hosts
+host: x86                       Bugs reproducible on x86 hosts
+host:32bit                      These are mostly TCG related bugs where we sometimes struggle with emulating larger guests, especially atomic and address space issues.
+hostos: BSD                     FreeBSD, OpenBSD, NetBSD, and derivatives as host OSes
+hostos: Linux                   Linux-based host operating systems (Fedora, RHEL/CentOS, Debian, Ubuntu, openSuSE et al)
+hostos: Windows                 Microsoft Windows host OS
+hostos: macOS                   Apple macOS / Darwin as a host OS
+icount                          issues relating to icount, deterministic execution and record/replay functionality
+kind::Bug                       Bug or defect in functionality.
+kind::Feature Request           Feature request or new functionality.
+kind::Task                      Research, investigations, and miscellaneous issues.
+libvfio-user                    
+linux-user                      issues with QEMU's lightweight user-mode emulator
+qemu-img                        
+sysadmin                        Issues related to QEMU project infrastructure. You should probably also check on the projects IRC channel if the issue is urgent - https://www.qemu.org/support/
+target: alpha                   DEC Alpha [alpha]
+target: arm                     Arm AArch32 or AArch64 [arm, aarch64]
+target: avr                     Atmel AVR [avr]
+target: hexagon                 Qualcomm Hexagon [hexagon]
+target: hppa                    Hewlett-Packard Precision Architecture; HP/HP, PA-RISC [hppa]
+target: i386                    Intel/AMD x86 [i386, x86_64]
+target: loongarch               loongarch64 target architecture
+target: m68k                    Motorola 68000 [m68k]
+target: microblaze              Xilinx MicroBlaze [microblaze, microblazeel]
+target: mips                    MIPS [mips, mipsel, mips64, mips64el]
+target: nios2                   Altera Nios II [nios2]
+target: openrisc                OpenRISC [or1k]
+target: ppc                     IBM Power Architecture, PowerPC [ppc, ppc64, ppc64le]
+target: riscv                   RISC-V [riscv32, riscv64]
+target: rx                      Renesas RX [rx]
+target: s390x                   IBM Z, SystemZ, zSeries [s390x]
+target: sh4                     Renesas SuperH [sh4, sh4eb]
+target: sparc                   Sun Microsystems SPARC [sparc, sparc64]
+target: tricore                 Infineon TriCore [tricore]
+target: xtensa                  Tensilica Xtensa [xtensa, xtensaeb]
+workflow::Confirmed             Bugs that have been confirmed and reproduced.
+workflow::In Progress           Someone is working on this issue.
+workflow::Needs Info            Issue has insufficient information to verify.
+workflow::Patch available       A patch is available
+workflow::Triaged               Issue has been triaged and given a topic label.
diff --git a/.agents/skills/qemu-issue-triage/evals/evals.json b/.agents/skills/qemu-issue-triage/evals/evals.json
new file mode 100644
index 00000000000..572c0723fd4
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/evals/evals.json
@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+{
+  "skill_name": "qemu-issue-triage",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Update the cached list of GitLab labels for the QEMU project.",
+      "expected_output": "The skill should fetch the latest labels from GitLab and save them to the skill's assets directory.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Triage issue #1234. Assume the user provided clear steps but no subsystem label is obvious.",
+      "expected_output": "The skill should read the cached label list (not fetch from GitLab) and apply relevant kind/target labels.",
+      "files": []
+    }
+  ]
+}
\ No newline at end of file
diff --git a/.agents/skills/qemu-issue-triage/scripts/update_labels.sh b/.agents/skills/qemu-issue-triage/scripts/update_labels.sh
new file mode 100755
index 00000000000..1605eab4de5
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/scripts/update_labels.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: GPL-2.0-or-later
+set -e
+
+if [ -z "$GITLAB_TOKEN" ]; then
+    echo "GITLAB_TOKEN is not set. Attempting to fetch via pass..."
+    export GITLAB_TOKEN=$(pass gitlab-api)
+fi
+
+echo "Fetching labels from qemu-project/qemu..."
+# Fetch labels using API and format as "Name        Description"
+glab api /projects/qemu-project%2Fqemu/labels --paginate | \
+    jq -r '.[] | [ .name, .description ] | @tsv' | \
+    column -t -s $'\t' > ../assets/labels.txt
+
+echo "Labels cached in assets/labels.txt"
diff --git a/AGENTS.md b/AGENTS.md
index 6a91c39638e..97774176425 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -36,6 +36,7 @@ You should use the following specialized skills for common tasks:
 - `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
 - `qemu-mail-thread`: For analyzing and parsing mailing list threads.
 - `qemu-issue-helper`: For fetching and summarising issue details from the bug tracker.
+- `qemu-issue-triage`: For helping triage issues in the bug tracker.
 
 ## Source Code Layout (see `docs/devel/codebase.rst`)
 - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
-- 
2.47.3

[RFC PATCH v3 11/11] MAINTAINERS: add a section for AI agents

[Alex Bennée]

For completeness add a section to MAINTAINERS to catch changes should
we decide to merge this.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 MAINTAINERS | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 93a1e4e4822..70789044d30 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4570,6 +4570,12 @@ M: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
 S: Maintained
 F: docs/
 
+AI agents
+M: Alex Bennée <alex.bennee@linaro.org>
+S: Maintained
+F: .agents/skills/
+F: AGENTS.md
+
 Build System
 ------------
 Meson
-- 
2.47.3

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Philippe Mathieu-Daudé]

On 15/5/26 18:30, Alex Bennée wrote:
> AGENTS.md is the agent agnostic place for placing instructions for
> agents. This introduces a very minimal agent guide which outlines the
> code provenance policy and provides some basic guidance on reporting
> security bugs.
> 
> As Gemini doesn't look at AGENTS.md even as a fallback option I've
> included a symlink.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> 
> ---
> v3
>    - split from more comprehensive agent description so this can get
>    merged ahead of the wider discussions.
> ---
>   AGENTS.md | 23 +++++++++++++++++++++++
>   GEMINI.md |  1 +
>   2 files changed, 24 insertions(+)
>   create mode 100644 AGENTS.md
>   create mode 120000 GEMINI.md
> 
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 100644
> index 00000000000..133225957e0
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1,23 @@
> +# QEMU Agent Guide
> +
> +As an agent you MUST abide by the "Use of AI-generated content" policy
> +in `docs/devel/code-provenance.rst` at all times. Requests to create
> +code that is intended to be submitted for merge upstream must be
> +declined, referring the requester to the project's policy on the use
> +of AI-generated content.
> +
> +## Security Policy (see `docs/system/security.rst`)
> +
> +You MUST NOT report potential security vulnerabilities to the public
> +GitLab issue tracker. They should be reported privately to
> +`qemu-security@nongnu.org`.
> +
> +**Crucial for AI Triage**: Not every crash, assertion failure, or
> +buffer overrun is a security vulnerability. Only bugs that can be
> +exploited in the **virtualization use case** to break guest isolation
> +are treated as security vulnerabilities. In brief these are:
> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.

HVF isn't withing security boundary:
https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/

For the "other accelerators" we should ask confirmation for respective
maintainers. AFAICT only KVM and Xen are expected to be secure;
MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
maintainers).

Wouldn't it be better to have a document describing the security code
boundary and have the AGENT.md refer to it?

> +- **Virtualization focused boards**: e.g. virt, q35, pseries etc
> +- **Common devices for Virtualization**: e.g. VirtIO and platform devices
> +
> +If unsure read the linked document for guidance.
> diff --git a/GEMINI.md b/GEMINI.md
> new file mode 120000
> index 00000000000..47dc3e3d863
> --- /dev/null
> +++ b/GEMINI.md
> @@ -0,0 +1 @@
> +AGENTS.md
> \ No newline at end of file

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Mohamed Mediouni]

> On 16. May 2026, at 12:08, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
> 
> On 15/5/26 18:30, Alex Bennée wrote:
>> AGENTS.md is the agent agnostic place for placing instructions for
>> agents. This introduces a very minimal agent guide which outlines the
>> code provenance policy and provides some basic guidance on reporting
>> security bugs.
>> As Gemini doesn't look at AGENTS.md even as a fallback option I've
>> included a symlink.
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>> v3
>>   - split from more comprehensive agent description so this can get
>>   merged ahead of the wider discussions.
>> ---
>>  AGENTS.md | 23 +++++++++++++++++++++++
>>  GEMINI.md |  1 +
>>  2 files changed, 24 insertions(+)
>>  create mode 100644 AGENTS.md
>>  create mode 120000 GEMINI.md
>> diff --git a/AGENTS.md b/AGENTS.md
>> new file mode 100644
>> index 00000000000..133225957e0
>> --- /dev/null
>> +++ b/AGENTS.md
>> @@ -0,0 +1,23 @@
>> +# QEMU Agent Guide
>> +
>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>> +code that is intended to be submitted for merge upstream must be
>> +declined, referring the requester to the project's policy on the use
>> +of AI-generated content.
>> +
>> +## Security Policy (see `docs/system/security.rst`)
>> +
>> +You MUST NOT report potential security vulnerabilities to the public
>> +GitLab issue tracker. They should be reported privately to
>> +`qemu-security@nongnu.org`.
>> +
>> +**Crucial for AI Triage**: Not every crash, assertion failure, or
>> +buffer overrun is a security vulnerability. Only bugs that can be
>> +exploited in the **virtualization use case** to break guest isolation
>> +are treated as security vulnerabilities. In brief these are:
>> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
> 
> HVF isn't withing security boundary:
> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
> 

Hi,

That’s not good at all. And I think it very much should be within the security boundary.

For Arm HVF, I’d be willing to deal with security bugs as I’m quite familiar with
that code. But still within S: Maintained, not supported.

> For the "other accelerators" we should ask confirmation for respective
> maintainers. AFAICT only KVM and Xen are expected to be secure;
> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
> maintainers).

So there’s also target/i386/emulate to take into account. Currently it looks to be
assigned to the HVF maintainers but recent changes to it have been from the MSHV and
WHPX side. Currently the backends using it are: x86 hvf, mshv, whpx.

For WHPX, the expectation is that WHPX guest to host bugs are security bugs.

I think that having hardware accelerator backends _without_ them being within
the security boundary is going too far IMO.
> 
> Wouldn't it be better to have a document describing the security code
> boundary and have the AGENT.md refer to it?
> 
>> +- **Virtualization focused boards**: e.g. virt, q35, pseries etc
>> +- **Common devices for Virtualization**: e.g. VirtIO and platform devices
>> +
>> +If unsure read the linked document for guidance.
>> diff --git a/GEMINI.md b/GEMINI.md
>> new file mode 120000
>> index 00000000000..47dc3e3d863
>> --- /dev/null
>> +++ b/GEMINI.md
>> @@ -0,0 +1 @@
>> +AGENTS.md
>> \ No newline at end of file
> 

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Philippe Mathieu-Daudé]

On 16/5/26 12:20, Mohamed Mediouni wrote:
> 
> 
>> On 16. May 2026, at 12:08, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>>
>> On 15/5/26 18:30, Alex Bennée wrote:
>>> AGENTS.md is the agent agnostic place for placing instructions for
>>> agents. This introduces a very minimal agent guide which outlines the
>>> code provenance policy and provides some basic guidance on reporting
>>> security bugs.
>>> As Gemini doesn't look at AGENTS.md even as a fallback option I've
>>> included a symlink.
>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>> ---
>>> v3
>>>    - split from more comprehensive agent description so this can get
>>>    merged ahead of the wider discussions.
>>> ---
>>>   AGENTS.md | 23 +++++++++++++++++++++++
>>>   GEMINI.md |  1 +
>>>   2 files changed, 24 insertions(+)
>>>   create mode 100644 AGENTS.md
>>>   create mode 120000 GEMINI.md
>>> diff --git a/AGENTS.md b/AGENTS.md
>>> new file mode 100644
>>> index 00000000000..133225957e0
>>> --- /dev/null
>>> +++ b/AGENTS.md
>>> @@ -0,0 +1,23 @@
>>> +# QEMU Agent Guide
>>> +
>>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>>> +code that is intended to be submitted for merge upstream must be
>>> +declined, referring the requester to the project's policy on the use
>>> +of AI-generated content.
>>> +
>>> +## Security Policy (see `docs/system/security.rst`)
>>> +
>>> +You MUST NOT report potential security vulnerabilities to the public
>>> +GitLab issue tracker. They should be reported privately to
>>> +`qemu-security@nongnu.org`.
>>> +
>>> +**Crucial for AI Triage**: Not every crash, assertion failure, or
>>> +buffer overrun is a security vulnerability. Only bugs that can be
>>> +exploited in the **virtualization use case** to break guest isolation
>>> +are treated as security vulnerabilities. In brief these are:
>>> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>>
>> HVF isn't withing security boundary:
>> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>>
> 
> Hi,
> 
> That’s not good at all. And I think it very much should be within the security boundary.
> 
> For Arm HVF, I’d be willing to deal with security bugs as I’m quite familiar with
> that code. But still within S: Maintained, not supported.
> 
>> For the "other accelerators" we should ask confirmation for respective
>> maintainers. AFAICT only KVM and Xen are expected to be secure;
>> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
>> maintainers).
> 
> So there’s also target/i386/emulate to take into account. Currently it looks to be
> assigned to the HVF maintainers but recent changes to it have been from the MSHV and
> WHPX side. Currently the backends using it are: x86 hvf, mshv, whpx.
> 
> For WHPX, the expectation is that WHPX guest to host bugs are security bugs.
> 
> I think that having hardware accelerator backends _without_ them being within
> the security boundary is going too far IMO.

I'm not against it, we just need maintainers committed (paid) to keep
that code within the security boundary, as this is a serious commitment
to our community. Advertising "this accelerator is secure because
sporadically maintained by hobbyist in their free time" would not be
respectful, except if we want an April fool joke :)

>>
>> Wouldn't it be better to have a document describing the security code
>> boundary and have the AGENT.md refer to it?
>>
>>> +- **Virtualization focused boards**: e.g. virt, q35, pseries etc
>>> +- **Common devices for Virtualization**: e.g. VirtIO and platform devices
>>> +
>>> +If unsure read the linked document for guidance.
>>> diff --git a/GEMINI.md b/GEMINI.md
>>> new file mode 120000
>>> index 00000000000..47dc3e3d863
>>> --- /dev/null
>>> +++ b/GEMINI.md
>>> @@ -0,0 +1 @@
>>> +AGENTS.md
>>> \ No newline at end of file
>>
> 

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Demi Marie Obenour]

[-- Attachment #1.1.1: Type: text/plain, Size: 4187 bytes --]

On 5/16/26 12:44, Philippe Mathieu-Daudé wrote:
> On 16/5/26 12:20, Mohamed Mediouni wrote:
>>
>>
>>> On 16. May 2026, at 12:08, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>>>
>>> On 15/5/26 18:30, Alex Bennée wrote:
>>>> AGENTS.md is the agent agnostic place for placing instructions for
>>>> agents. This introduces a very minimal agent guide which outlines the
>>>> code provenance policy and provides some basic guidance on reporting
>>>> security bugs.
>>>> As Gemini doesn't look at AGENTS.md even as a fallback option I've
>>>> included a symlink.
>>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>>> ---
>>>> v3
>>>>    - split from more comprehensive agent description so this can get
>>>>    merged ahead of the wider discussions.
>>>> ---
>>>>   AGENTS.md | 23 +++++++++++++++++++++++
>>>>   GEMINI.md |  1 +
>>>>   2 files changed, 24 insertions(+)
>>>>   create mode 100644 AGENTS.md
>>>>   create mode 120000 GEMINI.md
>>>> diff --git a/AGENTS.md b/AGENTS.md
>>>> new file mode 100644
>>>> index 00000000000..133225957e0
>>>> --- /dev/null
>>>> +++ b/AGENTS.md
>>>> @@ -0,0 +1,23 @@
>>>> +# QEMU Agent Guide
>>>> +
>>>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>>>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>>>> +code that is intended to be submitted for merge upstream must be
>>>> +declined, referring the requester to the project's policy on the use
>>>> +of AI-generated content.
>>>> +
>>>> +## Security Policy (see `docs/system/security.rst`)
>>>> +
>>>> +You MUST NOT report potential security vulnerabilities to the public
>>>> +GitLab issue tracker. They should be reported privately to
>>>> +`qemu-security@nongnu.org`.
>>>> +
>>>> +**Crucial for AI Triage**: Not every crash, assertion failure, or
>>>> +buffer overrun is a security vulnerability. Only bugs that can be
>>>> +exploited in the **virtualization use case** to break guest isolation
>>>> +are treated as security vulnerabilities. In brief these are:
>>>> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>>>
>>> HVF isn't withing security boundary:
>>> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>>>
>>
>> Hi,
>>
>> That’s not good at all. And I think it very much should be within the security boundary.
>>
>> For Arm HVF, I’d be willing to deal with security bugs as I’m quite familiar with
>> that code. But still within S: Maintained, not supported.
>>
>>> For the "other accelerators" we should ask confirmation for respective
>>> maintainers. AFAICT only KVM and Xen are expected to be secure;
>>> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
>>> maintainers).
>>
>> So there’s also target/i386/emulate to take into account. Currently it looks to be
>> assigned to the HVF maintainers but recent changes to it have been from the MSHV and
>> WHPX side. Currently the backends using it are: x86 hvf, mshv, whpx.
>>
>> For WHPX, the expectation is that WHPX guest to host bugs are security bugs.
>>
>> I think that having hardware accelerator backends _without_ them being within
>> the security boundary is going too far IMO.
> 
> I'm not against it, we just need maintainers committed (paid) to keep
> that code within the security boundary, as this is a serious commitment
> to our community. Advertising "this accelerator is secure because
> sporadically maintained by hobbyist in their free time" would not be
> respectful, except if we want an April fool joke :)

Volunteer-maintained projects can still be very secure.  OpenSSH is
one example example.  They can’t provide any legally-binding SLA,
but neither do the Xen Project, curl, Qubes OS, or many other projects
that do have paid maintainers.

Also, "Maintained" usually is greater than "Odd fixes", which is
going to be the state of QEMU’s USB support even once someone is
paid to fix vulnerabilities in it.

If the maintainer of a subsystem is willing to provide security
support, I think they should be given a chance.
-- 
Sincerely,
Demi Marie Obenour (she/her/hers)

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 7253 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Demi Marie Obenour]

[-- Attachment #1.1.1: Type: text/plain, Size: 4522 bytes --]

On 5/17/26 17:11, Demi Marie Obenour wrote:
> On 5/16/26 12:44, Philippe Mathieu-Daudé wrote:
>> On 16/5/26 12:20, Mohamed Mediouni wrote:
>>>
>>>
>>>> On 16. May 2026, at 12:08, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>>>>
>>>> On 15/5/26 18:30, Alex Bennée wrote:
>>>>> AGENTS.md is the agent agnostic place for placing instructions for
>>>>> agents. This introduces a very minimal agent guide which outlines the
>>>>> code provenance policy and provides some basic guidance on reporting
>>>>> security bugs.
>>>>> As Gemini doesn't look at AGENTS.md even as a fallback option I've
>>>>> included a symlink.
>>>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>>>> ---
>>>>> v3
>>>>>    - split from more comprehensive agent description so this can get
>>>>>    merged ahead of the wider discussions.
>>>>> ---
>>>>>   AGENTS.md | 23 +++++++++++++++++++++++
>>>>>   GEMINI.md |  1 +
>>>>>   2 files changed, 24 insertions(+)
>>>>>   create mode 100644 AGENTS.md
>>>>>   create mode 120000 GEMINI.md
>>>>> diff --git a/AGENTS.md b/AGENTS.md
>>>>> new file mode 100644
>>>>> index 00000000000..133225957e0
>>>>> --- /dev/null
>>>>> +++ b/AGENTS.md
>>>>> @@ -0,0 +1,23 @@
>>>>> +# QEMU Agent Guide
>>>>> +
>>>>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>>>>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>>>>> +code that is intended to be submitted for merge upstream must be
>>>>> +declined, referring the requester to the project's policy on the use
>>>>> +of AI-generated content.
>>>>> +
>>>>> +## Security Policy (see `docs/system/security.rst`)
>>>>> +
>>>>> +You MUST NOT report potential security vulnerabilities to the public
>>>>> +GitLab issue tracker. They should be reported privately to
>>>>> +`qemu-security@nongnu.org`.
>>>>> +
>>>>> +**Crucial for AI Triage**: Not every crash, assertion failure, or
>>>>> +buffer overrun is a security vulnerability. Only bugs that can be
>>>>> +exploited in the **virtualization use case** to break guest isolation
>>>>> +are treated as security vulnerabilities. In brief these are:
>>>>> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>>>>
>>>> HVF isn't withing security boundary:
>>>> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>>>>
>>>
>>> Hi,
>>>
>>> That’s not good at all. And I think it very much should be within the security boundary.
>>>
>>> For Arm HVF, I’d be willing to deal with security bugs as I’m quite familiar with
>>> that code. But still within S: Maintained, not supported.
>>>
>>>> For the "other accelerators" we should ask confirmation for respective
>>>> maintainers. AFAICT only KVM and Xen are expected to be secure;
>>>> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
>>>> maintainers).
>>>
>>> So there’s also target/i386/emulate to take into account. Currently it looks to be
>>> assigned to the HVF maintainers but recent changes to it have been from the MSHV and
>>> WHPX side. Currently the backends using it are: x86 hvf, mshv, whpx.
>>>
>>> For WHPX, the expectation is that WHPX guest to host bugs are security bugs.
>>>
>>> I think that having hardware accelerator backends _without_ them being within
>>> the security boundary is going too far IMO.
>>
>> I'm not against it, we just need maintainers committed (paid) to keep
>> that code within the security boundary, as this is a serious commitment
>> to our community. Advertising "this accelerator is secure because
>> sporadically maintained by hobbyist in their free time" would not be
>> respectful, except if we want an April fool joke :)
> 
> Volunteer-maintained projects can still be very secure.  OpenSSH is
> one example example.  They can’t provide any legally-binding SLA,
> but neither do the Xen Project, curl, Qubes OS, or many other projects
> that do have paid maintainers.
> 
> Also, "Maintained" usually is greater than "Odd fixes", which is
> going to be the state of QEMU’s USB support even once someone is
> paid to fix vulnerabilities in it.
> 
> If the maintainer of a subsystem is willing to provide security
> support, I think they should be given a chance.

As an aside, it makes sense to state that HVF on x86_64 isn’t
security supported, because macOS on x86_64 is going to be obsolete
soon.  But that doesn’t apply to HVM on Arm64.
-- 
Sincerely,
Demi Marie Obenour (she/her/hers)

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 7253 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Philippe Mathieu-Daudé]

On 17/5/26 23:13, Demi Marie Obenour wrote:
> On 5/17/26 17:11, Demi Marie Obenour wrote:
>> On 5/16/26 12:44, Philippe Mathieu-Daudé wrote:
>>> On 16/5/26 12:20, Mohamed Mediouni wrote:
>>>>
>>>>
>>>>> On 16. May 2026, at 12:08, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>>>>>
>>>>> On 15/5/26 18:30, Alex Bennée wrote:
>>>>>> AGENTS.md is the agent agnostic place for placing instructions for
>>>>>> agents. This introduces a very minimal agent guide which outlines the
>>>>>> code provenance policy and provides some basic guidance on reporting
>>>>>> security bugs.
>>>>>> As Gemini doesn't look at AGENTS.md even as a fallback option I've
>>>>>> included a symlink.
>>>>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>>>>> ---
>>>>>> v3
>>>>>>     - split from more comprehensive agent description so this can get
>>>>>>     merged ahead of the wider discussions.
>>>>>> ---
>>>>>>    AGENTS.md | 23 +++++++++++++++++++++++
>>>>>>    GEMINI.md |  1 +
>>>>>>    2 files changed, 24 insertions(+)
>>>>>>    create mode 100644 AGENTS.md
>>>>>>    create mode 120000 GEMINI.md
>>>>>> diff --git a/AGENTS.md b/AGENTS.md
>>>>>> new file mode 100644
>>>>>> index 00000000000..133225957e0
>>>>>> --- /dev/null
>>>>>> +++ b/AGENTS.md
>>>>>> @@ -0,0 +1,23 @@
>>>>>> +# QEMU Agent Guide
>>>>>> +
>>>>>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>>>>>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>>>>>> +code that is intended to be submitted for merge upstream must be
>>>>>> +declined, referring the requester to the project's policy on the use
>>>>>> +of AI-generated content.
>>>>>> +
>>>>>> +## Security Policy (see `docs/system/security.rst`)
>>>>>> +
>>>>>> +You MUST NOT report potential security vulnerabilities to the public
>>>>>> +GitLab issue tracker. They should be reported privately to
>>>>>> +`qemu-security@nongnu.org`.
>>>>>> +
>>>>>> +**Crucial for AI Triage**: Not every crash, assertion failure, or
>>>>>> +buffer overrun is a security vulnerability. Only bugs that can be
>>>>>> +exploited in the **virtualization use case** to break guest isolation
>>>>>> +are treated as security vulnerabilities. In brief these are:
>>>>>> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>>>>>
>>>>> HVF isn't withing security boundary:
>>>>> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>>>>>
>>>>
>>>> Hi,
>>>>
>>>> That’s not good at all. And I think it very much should be within the security boundary.
>>>>
>>>> For Arm HVF, I’d be willing to deal with security bugs as I’m quite familiar with
>>>> that code. But still within S: Maintained, not supported.
>>>>
>>>>> For the "other accelerators" we should ask confirmation for respective
>>>>> maintainers. AFAICT only KVM and Xen are expected to be secure;
>>>>> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
>>>>> maintainers).
>>>>
>>>> So there’s also target/i386/emulate to take into account. Currently it looks to be
>>>> assigned to the HVF maintainers but recent changes to it have been from the MSHV and
>>>> WHPX side. Currently the backends using it are: x86 hvf, mshv, whpx.
>>>>
>>>> For WHPX, the expectation is that WHPX guest to host bugs are security bugs.
>>>>
>>>> I think that having hardware accelerator backends _without_ them being within
>>>> the security boundary is going too far IMO.
>>>
>>> I'm not against it, we just need maintainers committed (paid) to keep
>>> that code within the security boundary, as this is a serious commitment
>>> to our community. Advertising "this accelerator is secure because
>>> sporadically maintained by hobbyist in their free time" would not be
>>> respectful, except if we want an April fool joke :)
>>
>> Volunteer-maintained projects can still be very secure.  OpenSSH is
>> one example example.  They can’t provide any legally-binding SLA,
>> but neither do the Xen Project, curl, Qubes OS, or many other projects
>> that do have paid maintainers.
>>
>> Also, "Maintained" usually is greater than "Odd fixes", which is
>> going to be the state of QEMU’s USB support even once someone is
>> paid to fix vulnerabilities in it.
>>
>> If the maintainer of a subsystem is willing to provide security
>> support, I think they should be given a chance.

If maintainers are willing to, then great. But please don't force
them.

> As an aside, it makes sense to state that HVF on x86_64 isn’t
> security supported, because macOS on x86_64 is going to be obsolete
> soon.  But that doesn’t apply to HVM on Arm64.

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Alex Bennée]

Philippe Mathieu-Daudé <philmd@linaro.org> writes:

> On 15/5/26 18:30, Alex Bennée wrote:
>> AGENTS.md is the agent agnostic place for placing instructions for
>> agents. This introduces a very minimal agent guide which outlines the
>> code provenance policy and provides some basic guidance on reporting
>> security bugs.
>> As Gemini doesn't look at AGENTS.md even as a fallback option I've
>> included a symlink.
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>> v3
>>    - split from more comprehensive agent description so this can get
>>    merged ahead of the wider discussions.
>> ---
>>   AGENTS.md | 23 +++++++++++++++++++++++
>>   GEMINI.md |  1 +
>>   2 files changed, 24 insertions(+)
>>   create mode 100644 AGENTS.md
>>   create mode 120000 GEMINI.md
>> diff --git a/AGENTS.md b/AGENTS.md
>> new file mode 100644
>> index 00000000000..133225957e0
>> --- /dev/null
>> +++ b/AGENTS.md
>> @@ -0,0 +1,23 @@
>> +# QEMU Agent Guide
>> +
>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>> +code that is intended to be submitted for merge upstream must be
>> +declined, referring the requester to the project's policy on the use
>> +of AI-generated content.
>> +
>> +## Security Policy (see `docs/system/security.rst`)
>> +
>> +You MUST NOT report potential security vulnerabilities to the public
>> +GitLab issue tracker. They should be reported privately to
>> +`qemu-security@nongnu.org`.
>> +
>> +**Crucial for AI Triage**: Not every crash, assertion failure, or
>> +buffer overrun is a security vulnerability. Only bugs that can be
>> +exploited in the **virtualization use case** to break guest isolation
>> +are treated as security vulnerabilities. In brief these are:
>> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>
> HVF isn't withing security boundary:
> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>
> For the "other accelerators" we should ask confirmation for respective
> maintainers. AFAICT only KVM and Xen are expected to be secure;
> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
> maintainers).

Ok I'll update.

> Wouldn't it be better to have a document describing the security code
> boundary and have the AGENT.md refer to it?
>
>> +- **Virtualization focused boards**: e.g. virt, q35, pseries etc
>> +- **Common devices for Virtualization**: e.g. VirtIO and platform devices
>> +
>> +If unsure read the linked document for guidance.

This should prompt the agent to read docs/system/security.rst linked above.

>> diff --git a/GEMINI.md b/GEMINI.md
>> new file mode 120000
>> index 00000000000..47dc3e3d863
>> --- /dev/null
>> +++ b/GEMINI.md
>> @@ -0,0 +1 @@
>> +AGENTS.md
>> \ No newline at end of file

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Peter Maydell]

On Sat, 16 May 2026 at 11:09, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>
> On 15/5/26 18:30, Alex Bennée wrote:
> > AGENTS.md is the agent agnostic place for placing instructions for
> > agents. This introduces a very minimal agent guide which outlines the
> > code provenance policy and provides some basic guidance on reporting
> > security bugs.
> >
> > As Gemini doesn't look at AGENTS.md even as a fallback option I've
> > included a symlink.
> >
> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

> > +## Security Policy (see `docs/system/security.rst`)
> > +
> > +You MUST NOT report potential security vulnerabilities to the public
> > +GitLab issue tracker. They should be reported privately to
> > +`qemu-security@nongnu.org`.
> > +
> > +**Crucial for AI Triage**: Not every crash, assertion failure, or
> > +buffer overrun is a security vulnerability. Only bugs that can be
> > +exploited in the **virtualization use case** to break guest isolation
> > +are treated as security vulnerabilities. In brief these are:
> > +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>
> HVF isn't withing security boundary:
> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>
> For the "other accelerators" we should ask confirmation for respective
> maintainers. AFAICT only KVM and Xen are expected to be secure;
> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
> maintainers).
>
> Wouldn't it be better to have a document describing the security code
> boundary and have the AGENT.md refer to it?

We do have such a document:
https://qemu-project.gitlab.io/qemu/system/security.html
and the AGENTS.md does tell the LLM about it.

It puts all the virtualization accelerators within the
security use case boundary. Personally I think this is
reasonable -- the main reasons for having TCG outside it are
(1) the TCG emulation itself is a lot of code and
(2) it is a convenient way to rule out an enormous amount
of old board and device model code in one go.
This applies much less to the hvf, whpx, etc cases as they are
using almost exactly the same board/device/core code as KVM.

The idea as I understand it here is that by giving a very
brief summary of the other document you make sure that the
important parts we want to emphasize are in the agent's context
and clearly stated. But I'm no expert on how to craft these
files...

thanks
-- PMM

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Sat, 16 May 2026 at 11:09, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>>
>> On 15/5/26 18:30, Alex Bennée wrote:
>> > AGENTS.md is the agent agnostic place for placing instructions for
>> > agents. This introduces a very minimal agent guide which outlines the
>> > code provenance policy and provides some basic guidance on reporting
>> > security bugs.
>> >
>> > As Gemini doesn't look at AGENTS.md even as a fallback option I've
>> > included a symlink.
>> >
>> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
>> > +## Security Policy (see `docs/system/security.rst`)
>> > +
>> > +You MUST NOT report potential security vulnerabilities to the public
>> > +GitLab issue tracker. They should be reported privately to
>> > +`qemu-security@nongnu.org`.
>> > +
>> > +**Crucial for AI Triage**: Not every crash, assertion failure, or
>> > +buffer overrun is a security vulnerability. Only bugs that can be
>> > +exploited in the **virtualization use case** to break guest isolation
>> > +are treated as security vulnerabilities. In brief these are:
>> > +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>>
>> HVF isn't withing security boundary:
>> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>>
>> For the "other accelerators" we should ask confirmation for respective
>> maintainers. AFAICT only KVM and Xen are expected to be secure;
>> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
>> maintainers).
>>
>> Wouldn't it be better to have a document describing the security code
>> boundary and have the AGENT.md refer to it?
>
> We do have such a document:
> https://qemu-project.gitlab.io/qemu/system/security.html
> and the AGENTS.md does tell the LLM about it.
>
> It puts all the virtualization accelerators within the
> security use case boundary. Personally I think this is
> reasonable -- the main reasons for having TCG outside it are
> (1) the TCG emulation itself is a lot of code and
> (2) it is a convenient way to rule out an enormous amount
> of old board and device model code in one go.
> This applies much less to the hvf, whpx, etc cases as they are
> using almost exactly the same board/device/core code as KVM.
>
> The idea as I understand it here is that by giving a very
> brief summary of the other document you make sure that the
> important parts we want to emphasize are in the agent's context
> and clearly stated. But I'm no expert on how to craft these
> files...

Yeah compared to normal programming its a bit imprecise - almost like
natural language is full of ambiguity and ad-hoc grammar ;-)

There is essentially a trade off about how many tokens you commit to the
permanent context (system prompt + agents.md + list of skills/rules) so the
agent will load stuff when needed but you don't pay an excessive token
cost for every query. Also while the frontier models have quite large
context windows (200K to 1M tokens) the local open weight models often
have much smaller windows so you need some free for the actual query and
response.

I did "test" this by asking the model how it would route a bunch of
theoretical vulnerabilities and it generally reasoned and "did" the
right thing.

Some of the TUI tools (Claude Code for example) have skill creators that
include evaluations which are then run with and without the additional
context. Another LLM then evaluates the response and scores the response
to give some sort of qualitative indication on if the additional context
is useful. However the workflow for these evaluations is currently tied
to specific providers and I don't think we want to favour one over
another.

However going through this process was one reason I didn't include a git
skill because it doesn't add much, the base models generally already
know how to drive git pretty well. In the end I've just added (to my
local config):

  When applying patches you should assume the user is happy building on top of the current branch. 
  You MUST always ask the user (using the eca__ask_user tool) before changing branches or resetting the git tree state.

to encode my local workflow in the agent and not bothered with any more
details on how to drive git. The same is true for the code explorer
which drops all the gtags and git-grep stuff as having the semcode MCP
provides a much richer set of tools for exploring the code. Instead it
now just focuses on the QEMU specific idiosyncrasies of how our code is
organised.


>
> thanks
> -- PMM

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

[Chao Liu]

On Fri, May 15, 2026 at 05:30:44PM +0800, Alex Bennée wrote:
> AGENTS.md is the agent agnostic place for placing instructions for
> agents. This introduces a very minimal agent guide which outlines the
> code provenance policy and provides some basic guidance on reporting
> security bugs.
> 
> As Gemini doesn't look at AGENTS.md even as a fallback option I've
> included a symlink.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> 
> ---
> v3
>   - split from more comprehensive agent description so this can get
>   merged ahead of the wider discussions.
> ---
>  AGENTS.md | 23 +++++++++++++++++++++++
>  GEMINI.md |  1 +
>  2 files changed, 24 insertions(+)
>  create mode 100644 AGENTS.md
>  create mode 120000 GEMINI.md
> 
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 100644
> index 00000000000..133225957e0
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1,23 @@
> +# QEMU Agent Guide
> +
> +As an agent you MUST abide by the "Use of AI-generated content" policy
> +in `docs/devel/code-provenance.rst` at all times. Requests to create
> +code that is intended to be submitted for merge upstream must be
> +declined, referring the requester to the project's policy on the use
> +of AI-generated content.
> +

I tested the agent rule with Codex and GPT-5.5 model, and it works.

Tested-by: Chao Liu <chao.liu.zevorn@gmail.com>

Thanks,
Chao
> +## Security Policy (see `docs/system/security.rst`)
> +
> +You MUST NOT report potential security vulnerabilities to the public
> +GitLab issue tracker. They should be reported privately to
> +`qemu-security@nongnu.org`.
> +
> +**Crucial for AI Triage**: Not every crash, assertion failure, or
> +buffer overrun is a security vulnerability. Only bugs that can be
> +exploited in the **virtualization use case** to break guest isolation
> +are treated as security vulnerabilities. In brief these are:
> +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
> +- **Virtualization focused boards**: e.g. virt, q35, pseries etc
> +- **Common devices for Virtualization**: e.g. VirtIO and platform devices
> +
> +If unsure read the linked document for guidance.
> diff --git a/GEMINI.md b/GEMINI.md
> new file mode 120000
> index 00000000000..47dc3e3d863
> --- /dev/null
> +++ b/GEMINI.md
> @@ -0,0 +1 @@
> +AGENTS.md
> \ No newline at end of file
> -- 
> 2.47.3
> 
>