[LTP] [PATCH v6] agents: Add AI agent configuration for code reviews

[LTP] [PATCH v6] agents: Add AI agent configuration for code reviews

[Andrea Cervesato]

From: Andrea Cervesato <andrea.cervesato@suse.com>

Add .agents/ directory with configuration files for automated code review
assistance. The configuration includes:

- ground-rules.md: Mandatory LTP development rules
- c-tests.md: C test writing guidelines and examples
- shell-tests.md: Shell test structure and style guide
- apply-patch.md: How to download and apply patches before review

AGENTS.md at root provides project overview and links to review protocol.
SKILL.md for code reviews.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
Changes in v6:
- make sure apply-patch.md is not override by the skill definition
- Link to v5: https://lore.kernel.org/r/20260224-agents_file-v5-1-3d5ce6477fc1@suse.com

Changes in v5:
- verified models: Kimi k3.5, GLM5, MiniMax M2.5, Claude Code
- adopt SKILL.md to make reviews more deterministic
- Link to v4: https://lore.kernel.org/r/20260217-agents_file-v4-1-e71ae27ea2d9@suse.com

Changes in v4:
- add patches apply section
- review the entire structure using Claude Code
- support as many LLM as possible
- use an imperative language
- edit/write new tests section
- Link to v3: https://lore.kernel.org/r/20260217-agents_file-v3-1-fc2e6f97e0a7@suse.com

Changes in v3:
- review and fix the agents review configuration
- Link to v2: https://lore.kernel.org/r/20260216-agents_file-v2-1-b6afff4195f2@suse.com

Changes in v2:
- rewrite the entire agents/ structure to reduce the LLM allucination
  and to focus on reviews only
- AGENTS.md now is defining basic project usage and it points to the
  agents/review.md for review requests
- Link to v1: https://lore.kernel.org/r/20260216-agents_file-v1-1-53ec6a8ecf32@suse.com
---
 .agents/apply-patch.md         | 123 +++++++++++++++++++++++++++++
 .agents/c-tests.md             | 170 +++++++++++++++++++++++++++++++++++++++++
 .agents/ground-rules.md        |  91 ++++++++++++++++++++++
 .agents/shell-tests.md         | 134 ++++++++++++++++++++++++++++++++
 .agents/skills/review/SKILL.md | 145 +++++++++++++++++++++++++++++++++++
 AGENTS.md                      | 117 ++++++++++++++++++++++++++++
 6 files changed, 780 insertions(+)

diff --git a/.agents/apply-patch.md b/.agents/apply-patch.md
new file mode 100644
index 0000000000000000000000000000000000000000..590c94b38ee8fd935bde3d453a4beedf806aad9a
--- /dev/null
+++ b/.agents/apply-patch.md
@@ -0,0 +1,123 @@
+# Downloading and Applying Patches
+
+This file provides instructions for downloading and applying patches from
+various sources. Use the appropriate section based on the input type.
+
+## Quick Reference
+
+- **Git commit**: No download needed - checkout directly
+- **Git branch**: No download needed - checkout directly
+- **Multiple commits**: Cherry-pick the range
+- **Patchwork URL**: Use b4 or curl + git am
+- **Lore URL**: Use b4 or curl + git am
+- **Local patch file**: git am directly
+- **GitHub PR**: Use gh or git fetch
+
+## From Git Commit
+
+```sh
+git checkout -b review/<name> <commit-hash>
+```
+
+## From Git Branch
+
+```sh
+git checkout -b review/<name> <branch-name>
+```
+
+## From Multiple Commits
+
+```sh
+git checkout -b review/<name> master
+git cherry-pick <start-commit>..<end-commit>
+```
+
+## From Patchwork URL
+
+### Option 1: Using b4 (RECOMMENDED)
+
+```sh
+git checkout master && git pull origin master
+git checkout -b review/<patch-name> master
+b4 shazam <message-id>
+```
+
+To get the Message-ID: open the Patchwork patch page and find it in the details.
+
+### Option 2: Without b4
+
+```sh
+git checkout master && git pull origin master
+git checkout -b review/<patch-name> master
+curl -sL "https://patchwork.ozlabs.org/patch/<id>/mbox/" -o /tmp/patch.mbox
+git am /tmp/patch.mbox
+```
+
+## From Lore URL
+
+### Option 1: Using b4 (RECOMMENDED)
+
+```sh
+git checkout master && git pull origin master
+git checkout -b review/<patch-name> master
+b4 shazam <message-id>
+```
+
+### Option 2: Without b4
+
+```sh
+git checkout master && git pull origin master
+git checkout -b review/<patch-name> master
+curl -sL "https://lore.kernel.org/ltp/<message-id>/raw" -o /tmp/patch.mbox
+git am /tmp/patch.mbox
+```
+
+## From Local Patch File
+
+```sh
+git checkout master && git pull origin master
+git checkout -b review/<patch-name> master
+git am /path/to/patch.patch
+```
+
+## From GitHub PR
+
+### Option 1: Using gh (RECOMMENDED)
+
+```sh
+git checkout master && git pull origin master
+gh pr checkout <pr-number>
+```
+
+### Option 2: Without gh
+
+```sh
+git checkout master && git pull origin master
+git fetch origin pull/<pr-number>/head:review/pr-<pr-number>
+git checkout review/pr-<pr-number>
+```
+
+## Applying a Patch Series
+
+For multiple patches in order:
+
+```sh
+git am /tmp/patch1.mbox /tmp/patch2.mbox /tmp/patch3.mbox
+```
+
+Or concatenate:
+
+```sh
+cat /tmp/patch*.mbox | git am
+```
+
+## b4 Command Reference
+
+- `b4 shazam <msgid>`: Download and apply patches directly
+- `b4 am <msgid>`: Download patches as mbox (does not apply)
+- `b4 am -o . <msgid>`: Save mbox to current directory
+
+**Options:**
+
+- `-o <dir>`: Save mbox to specific directory
+- `-m <file>`: Use local mbox file instead of fetching
diff --git a/.agents/c-tests.md b/.agents/c-tests.md
new file mode 100644
index 0000000000000000000000000000000000000000..db4d8ef9a2810b61102496c7d5fb0412c3ded88c
--- /dev/null
+++ b/.agents/c-tests.md
@@ -0,0 +1,170 @@
+# C Test Rules
+
+This file contains MANDATORY rules for C tests. Load this file when reviewing
+or writing any patch that modifies `*.c` or `*.h` files.
+
+## Required Test Structure
+
+Every C test MUST follow this structure:
+
+```c
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * Copyright (c) YYYY Author Name <email@example.org>
+ */
+
+/*\
+ * High-level RST-formatted test description goes here.
+ * Explain _what_ is being tested (exported to docs).
+ *
+ * The following part is OPTIONAL:
+ * [Algorithm]
+ *
+ * Explaination of how algorithm in the test works in a list (-) syntax.
+ */
+
+#include "tst_test.h"
+
+static void run(void)
+{
+    tst_res(TPASS, "Test passed");
+}
+
+static struct tst_test test = {
+    .test_all = run,
+};
+```
+
+## Checklist
+
+When reviewing or writing C tests, verify ALL of the following:
+
+### 1. Coding Style
+
+- Code MUST follow Linux kernel coding style
+- `make check` or `make check-$TCID` MUST pass (uses vendored `checkpatch.pl`)
+
+### 2. API Usage
+
+- MUST use new API (`tst_test.h`), NOT old API (`test.h`)
+- MUST NOT define `main()` (unless `TST_NO_DEFAULT_MAIN` is used)
+- MUST use `struct tst_test` for configuration
+- Handlers MUST be thin; logic goes in `.setup` and `.cleanup` callbacks
+
+### 3. Syscall Usage
+
+- Syscall usage MUST match man pages and kernel code
+
+### 4. File Organization
+
+- New test binary MUST be added to corresponding `.gitignore`
+- Datafiles go in `datafiles/` subdirectory (installed to `testcases/data/$TCID`)
+- Syscall tests go under `testcases/kernel/syscalls/`
+- Entry MUST exist in appropriate `runtest/` file
+- Sub-executables MUST use `$TESTNAME_` prefix
+- MUST use `.needs_tmpdir = 1` for temp files (work in current directory)
+
+### 5. Result Reporting
+
+- MUST use `tst_res()` for results: `TPASS`, `TFAIL`, `TCONF`, `TBROK`, `TINFO`
+- MUST use `tst_brk()` for fatal errors that abort the test
+- MUST use `TEST()` macro to capture return value (`TST_RET`) and errno (`TST_ERR`)
+- MUST return `TCONF` (not `TFAIL`) when feature is unavailable
+
+### 6. Safe Macros
+
+- MUST use `SAFE_*` macros for system calls that must not fail
+- Safe macros are defined in `include/` directory
+
+### 7. Kernel Version Handling
+
+- MUST use `.min_kver` for kernel version gating
+- MUST prefer runtime checks over compile-time checks
+
+### 8. Tagging
+
+- Regression tests MUST include `.tags` in `struct tst_test`
+
+### 9. Cleanup
+
+- Cleanup MUST run on ALL exit paths
+- MUST unmount, restore sysctls, delete temp files, kill processes
+
+### 10. Static Variables
+
+- Static variables MUST be initialized before use in test logic (for `-i` option)
+- Static allocated variables MUST be released in cleanup if allocated in setup
+
+### 11. Memory Allocation
+
+- Memory MUST be correctly deallocated
+- EXCEPTION: If `.bufs` is used, ignore check for memory allocated with it
+
+### 12. String Handling
+
+- MUST use `snprintf()` when combining strings
+
+### 13. Deprecated Features
+
+- MUST NOT define `[Description]` in the test description section
+
+## Code Examples
+
+### CORRECT: New API
+
+```c
+#include <stdlib.h>
+#include "tst_test.h"
+
+static int fd;
+
+static void setup(void)
+{
+    fd = SAFE_OPEN("test_file", O_RDWR | O_CREAT, 0644);
+}
+
+static void cleanup(void)
+{
+    if (fd > 0)
+        SAFE_CLOSE(fd);
+}
+
+static void run(void)
+{
+    SAFE_WRITE(SAFE_WRITE_ALL, fd, "a", 1);
+    tst_res(TPASS, "write() succeeded");
+}
+
+static struct tst_test test = {
+    .test_all = run,
+    .setup = setup,
+    .cleanup = cleanup,
+    .needs_tmpdir = 1,
+    .needs_root = 1,
+};
+
+```
+
+### INCORRECT: Legacy/Unsafe
+
+```c
+/* WRONG: old header */
+#include "test.h"
+
+/* WRONG: defining main */
+int main(void)
+{
+    /* WRONG: unsafe call, hardcoded path */
+    int fd = open("/tmp/file", O_RDWR);
+
+    if (fd < 0) {
+        /* WRONG: use tst_res or SAFE macro */
+        perror("open");
+        exit(1);
+    }
+
+    /* WRONG: old print function */
+    tst_resm(TPASS, "test passed");
+    tst_exit();
+}
+```
diff --git a/.agents/ground-rules.md b/.agents/ground-rules.md
new file mode 100644
index 0000000000000000000000000000000000000000..9c53f1a5289a6b61a879164bc309ac10177b807a
--- /dev/null
+++ b/.agents/ground-rules.md
@@ -0,0 +1,91 @@
+# Ground Rules
+
+These rules are **MANDATORY** and must **NEVER** be violated when writing or
+reviewing LTP code. Violations MUST be flagged in reviews.
+
+## Rule 1: No Kernel Bug Workarounds
+
+Code MUST NOT work around known kernel bugs.
+
+NEVER work around a kernel bug in LTP test code. Workarounds mask failures for
+everyone else. If a test fails because a fix was not backported, that is the
+expected (correct) result.
+
+## Rule 2: No Sleep-Based Synchronization
+
+Code MUST NOT use `sleep()`/`nanosleep()` for synchronization.
+
+NEVER use sleep to synchronize between processes. It causes rare flaky failures,
+wastes CI time, and breaks under load.
+
+**Use instead:**
+
+- Parent waits for child to finish → `waitpid()` / `SAFE_WAITPID()`
+- Child must reach code point before parent continues → `TST_CHECKPOINT_WAIT()` / `TST_CHECKPOINT_WAKE()`
+- Child must be sleeping in a syscall → `TST_PROCESS_STATE_WAIT()`
+- Async or deferred kernel actions → Exponential-backoff polling loop
+
+## Rule 3: Runtime Feature Detection Only
+
+Code MUST use runtime checks, NOT compile-time assumptions.
+
+Compile-time checks (`configure.ac`) may ONLY enable fallback API definitions
+in `include/lapi/`. NEVER assume compile-time results reflect the running kernel.
+
+**Runtime detection methods:**
+
+- errno checks (`ENOSYS` / `EINVAL`)
+- `.min_kver` in test struct
+- `.needs_kconfigs` in test struct
+- Kernel `.config` parsing
+
+## Rule 4: Minimize Root Usage
+
+Tests MUST NOT require root unless absolutely necessary.
+
+If root is required, the reason MUST be documented in the test's doc comment.
+Drop privileges for sections that do not need them.
+
+## Rule 5: Always Clean Up
+
+Tests MUST clean up on ALL exit paths (success, failure, early exit).
+
+Every test MUST leave the system exactly as it found it:
+
+- Filesystems → Unmount
+- Sysctls, `/proc`/`/sys` values → Restore
+- Temp files/dirs → Delete
+- Spawned processes → Kill
+- Cgroups/namespaces → Remove
+- Loop devices → Detach
+- Ulimits → Restore
+
+**Prefer library helpers:** `.needs_tmpdir`, `.save_restore`, `.needs_device`,
+`.restore_wallclock`, `.needs_cgroup_ctrls`
+
+## Rule 6: Write Portable Code
+
+- MUST NOT use nonstandard libc APIs when portable equivalent exists
+- MUST NOT assume 64-bit, page size, endianness, or tool versions
+- Architecture-specific tests MUST still compile everywhere (use `.supported_archs`)
+- Shell tests MUST be portable POSIX shell (no bash-isms)
+
+Verify with `make check`.
+
+## Rule 7: One Logical Change Per Patch
+
+- Each patch MUST contain exactly ONE logical change
+- Each patch MUST compile successfully on its own
+- Each patch MUST keep all tests and tooling functional
+- Each patch MUST NOT introduce intermediate breakage
+- Commit message MUST clearly explain the change
+
+Patches mixing unrelated changes will be delayed or ignored.
+
+## Rule 8: Unreleased Kernel Features
+
+- Tests for unreleased kernel features MUST use `[STAGING]` subject prefix
+- Staging tests MUST go into `runtest/staging` only
+
+Tests for features not yet in a mainline kernel release will NOT be merged into
+default test suites until the kernel code is finalized and released.
diff --git a/.agents/shell-tests.md b/.agents/shell-tests.md
new file mode 100644
index 0000000000000000000000000000000000000000..5f95e36a0bba5cf23ae72fa31fca9cd5d3e0f826
--- /dev/null
+++ b/.agents/shell-tests.md
@@ -0,0 +1,134 @@
+# Shell Test Rules
+
+This file contains MANDATORY rules for shell tests. Load this file when
+reviewing or writing any patch that modifies `*.sh` files.
+
+## Required Test Structure
+
+Every shell test MUST follow this exact structure, in this exact order.
+Omitting or reordering blocks will break the shell loader.
+
+```sh
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) YYYY Author Name <email@example.org>
+# ---
+# doc
+# Brief RST description of what the test verifies.
+#
+# Additional detail if needed (exported to generated docs).
+# ---
+# ---
+# env
+# {
+#  "needs_root": true,
+#  "needs_tmpdir": true
+# }
+# ---
+
+TST_SETUP=setup
+TST_CLEANUP=cleanup
+
+. tst_loader.sh
+
+setup()
+{
+    tst_res TINFO "setup executed"
+}
+
+cleanup()
+{
+    tst_res TINFO "cleanup executed"
+}
+
+tst_test()
+{
+    tst_res TPASS "Test passed"
+}
+
+. tst_run.sh
+```
+
+## Structure Checklist
+
+When reviewing or writing shell tests, verify ALL of the following:
+
+### Block 1: Shebang + License + Copyright
+
+- Shebang MUST be exactly `#!/bin/sh`
+- License MUST be `GPL-2.0-or-later`
+- Copyright line MUST be present with year and author
+
+### Block 2: Doc Block
+
+- `# --- doc` block MUST be present
+- MUST contain RST-formatted description of WHAT is tested
+- Will be exported to online test catalog
+
+### Block 3: Env Block
+
+- `# --- env` block MUST be present (even if empty: `{}`)
+- MUST contain JSON serialization of `struct tst_test` fields
+- Valid keys: `"needs_root"`, `"needs_tmpdir"`, `"needs_kconfigs"`, `"tags"`, etc.
+
+### Block 4: Variable Assignments
+
+- `TST_SETUP` and `TST_CLEANUP` MUST be set BEFORE sourcing `tst_loader.sh`
+- These are optional but if used, MUST be set here
+
+### Block 5: Source Loader
+
+- `. tst_loader.sh` MUST come AFTER variable assignments
+- `. tst_loader.sh` MUST come BEFORE function definitions
+
+### Block 6: Function Definitions
+
+- `setup()` and `cleanup()` MUST be defined AFTER loader is sourced
+- Function names MUST match variables set in Block 4
+
+### Block 7: Test Function
+
+- `tst_test()` function MUST contain actual test logic
+- MUST use `tst_res` and `tst_brk` for reporting
+
+### Block 8: Source Runner
+
+- `. tst_run.sh` MUST be the LAST line of the file
+- NOTHING may come after this line
+
+## Coding Style Checklist
+
+- MUST be portable POSIX shell only (no bash-isms)
+- MUST NOT use `[[ ]]` (use `[ ]` instead)
+- MUST NOT use arrays
+- MUST NOT use `function` keyword
+- MUST NOT use process substitution
+- MUST work with `dash`
+- Lines SHOULD be under 80 characters
+- MUST use tabs for indentation
+- All variable expansions MUST be quoted
+- SHOULD avoid unnecessary subshells
+- Functions MUST NOT be named after common shell commands
+
+**Allowed exceptions:**
+
+- `local` keyword inside functions
+- `-o` and `-a` test operators
+
+## Env Block Reference
+
+- `"needs_root"` (bool): Test requires root privileges
+- `"needs_tmpdir"` (bool): Test needs a temporary directory
+- `"needs_kconfigs"` (array): Required kernel configs, e.g. `["CONFIG_NUMA=y"]`
+- `"tags"` (object): Git tags, e.g. `{"linux-git": "<hash>"}`
+- `"min_kver"` (string): Minimum kernel version
+
+## Running Shell Tests from Source Tree
+
+```sh
+# From the test's directory (adjust ../ depth as needed)
+PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh
+```
+
+The path must reach `testcases/lib/` where `tst_loader.sh`, `tst_run.sh`, and
+`tst_run_shell` binary reside.
diff --git a/.agents/skills/review/SKILL.md b/.agents/skills/review/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..7ea0c32adf2aff84d4e0d8bec63432b205bd6f2e
--- /dev/null
+++ b/.agents/skills/review/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: review
+description: LTP Patch Review Skill
+---
+
+# LTP Patch Review Protocol
+
+You are an agent that performs a deep regression analysis on patches for the
+LTP - Linux Test Project.
+
+## Phase 1: Setup
+
+### Step 1.1: Load Core Files
+
+```
+Read: .agents/apply-patch.md
+Read: .agents/ground-rules.md
+```
+
+### Step 1.2: Prepare and apply patches
+
+```bash
+git checkout <base-branch>
+git branch -D review/<name> 2>/dev/null
+git checkout -b review/<name> <base-branch>
+```
+
+Then you MUST follow the `.agents/apply-patch.md` instructions.
+
+### Step 1.3: Identify Patch Type
+
+Check changed files and load corresponding rules:
+
+- `*.c` or `*.h` → Read `.agents/c-tests.md`
+- `*.sh` → Read `.agents/shell-tests.md`
+- Mixed → Read both
+
+## Phase 2: Commit Message Checks
+
+For EACH commit, verify in this order:
+
+- **2.1 Signed-off-by**: `git log -1 --format=%b | grep "^Signed-off-by:"` → Line exists
+- **2.2 Subject line**: `git log -1 --format=%s` → Clear, <72 chars
+- **2.3 Body**: `git log -1 --format=%b` → Explains "why"
+- **2.4 Fixes tag**: (if fixing bug) → `Fixes:` present
+
+## Phase 3: Build Checks
+
+Run in this EXACT order. Stop on first failure.
+
+- **3.1 Checkpatch**: `make -C <test-dir> check-<testname>` → No errors for this test
+- **3.2 Compile**: `make -C <test-dir> <testname>` → Exit code 0
+- **3.3 Each patch compiles**: `git checkout HEAD~N && make -C <dir>` → Exit code 0 for each
+
+## Phase 4: Runtime Checks
+
+Run in this EXACT order. Mark UNKNOWN if requires privileges or times out (>60s).
+
+- **4.1 Run -i 0**: `./<test> -i 0` → No TFAIL/TBROK
+- **4.2 Run -i 10**: `./<test> -i 10` → No TFAIL/TBROK
+- **4.3 Run -i 100**: `./<test> -i 100` → No TFAIL/TBROK
+
+## Phase 5: Code Review (C Tests)
+
+Check EACH rule. Mark ✅, ❌, or N/A.
+
+### Ground Rules (MANDATORY - any ❌ = reject)
+
+- **G1 No kernel bug workarounds**: Read code for workaround comments
+- **G2 No sleep-based sync**: `grep -n "sleep\|nanosleep" <file>`
+- **G3 Runtime feature detection**: Check for runtime checks, not just `#ifdef`
+- **G4 Root only if needed**: Check `.needs_root` matches actual need
+- **G5 Cleanup on all paths**: Check cleanup() handles all resources
+- **G6 Portable code**: `make check` passes
+- **G7 One change per patch**: Review diff scope
+- **G8 Staging for unreleased**: Check if kernel feature is released
+
+### C Test Rules
+
+- **C1 SPDX header**: First line is `// SPDX-License-Identifier: GPL-2.0-or-later`
+- **C2 Copyright**: Second block has `Copyright`
+- **C3 Doc comment**: `/*\` block exists with description
+- **C4 Uses tst_test.h**: `grep "tst_test.h" <file>`
+- **C5 No main()**: `grep "^int main\|^void main" <file>` returns empty
+- **C6 struct tst_test**: `grep "struct tst_test test" <file>`
+- **C7 .gitignore entry**: `grep <testname> <dir>/.gitignore`
+- **C8 runtest entry**: `grep <testname> runtest/*`
+- **C9 SAFE\_\* macros**: No raw syscalls that should use SAFE\_\*
+- **C10 Static vars reset**: Static vars in run() are reset or set in setup()
+- **C11 Result reporting**: Uses tst_res()/tst_brk() correctly
+- **C12 TCONF for unsupported**: Feature unavailable → TCONF, not TFAIL
+
+## Phase 6: Output
+
+ALWAYS output in this EXACT format:
+
+```
+## Review: <patch-subject>
+
+### Commits
+- <hash1>: <subject1> - Signed-off-by: ✅/❌
+- <hash2>: <subject2> - Signed-off-by: ✅/❌
+
+### Build
+- Checkpatch: ✅/❌
+- Compiles: ✅/❌
+- Each patch compiles alone: ✅/❌
+
+### Runtime
+- Tests pass (-i 0): ✅/❌/UNKNOWN
+- Tests pass (-i 10): ✅/❌/UNKNOWN
+- Tests pass (-i 100): ✅/❌/UNKNOWN
+
+### Code Review
+- Ground rules: ✅ all pass / ❌ <list violations>
+- C test rules: ✅ all pass / ❌ <list violations>
+
+### Issues Found
+1. <issue or "None">
+
+### Summary
+- Signed-off-by: ✅/❌
+- Commit message: ✅/❌
+- Applies cleanly: ✅/❌
+- Compiles: ✅/❌
+- Tests pass (-i 0): ✅/❌/UNKNOWN
+- Tests pass (-i 10): ✅/❌/UNKNOWN
+- Tests pass (-i 100): ✅/❌/UNKNOWN
+
+### Verdict
+
+**Approved** ✅ / **Needs revision** ❌ / **Needs discussion** ⚠️
+
+<one-line-reason>
+```
+
+## Decision Rules
+
+- ANY ground rule violation → **Needs revision** ❌
+- Build failure → **Needs revision** ❌
+- Test failure (not UNKNOWN) → **Needs revision** ❌
+- Missing Signed-off-by → **Needs revision** ❌
+- Missing runtest/gitignore → **Needs revision** ❌
+- All checks pass → **Approved** ✅
+- Uncertain about rule → **Needs discussion** ⚠️
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..b25569146cc06b4cd4f8a9479657e6ae05b9bec9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,117 @@
+# Linux Test Project (LTP)
+
+LTP delivers tests to the open source community that validate the
+reliability, robustness, and stability of the Linux kernel and related
+features. Tests are written in C or portable POSIX shell. The project uses
+GNU Autotools for its build system and follows the Linux kernel coding style.
+
+**License**: GPL-2.0-or-later (`SPDX-License-Identifier: GPL-2.0-or-later`)
+
+## Technology Stack
+
+- **Languages**: C (primary), portable POSIX shell
+- **Build system**: GNU Autotools (autoconf, automake, make)
+- **Compiler**: gcc (clang also supported in CI)
+- **Coding style**: Linux kernel coding style
+- **Test runner**: kirk (replacing legacy `runltp`)
+- **Documentation**: reStructuredText + Sphinx
+
+## Project Structure
+
+- `testcases/` — All test binaries (C and shell)
+  - `testcases/kernel/syscalls/` — Syscall and libc wrapper tests
+  - `testcases/open_posix_testsuite/` — Open POSIX testsuite fork
+  - `testcases/lib/` — Shell test library and shell loader
+- `include/` — LTP library headers (`tst_test.h` is the main API)
+  - `include/lapi/` — Fallback kernel API definitions for older systems
+  - `include/mk/` — Build system include files
+- `lib/` — LTP C library source (`tst_*.c` files)
+  - `lib/newlib_tests/` — LTP library self-tests
+- `runtest/` — Runtest files defining test suites (e.g. `syscalls`, `mm`)
+- `scenario_groups/` — Default sets of runtest files
+- `doc/` — Sphinx documentation (RST format)
+- `scripts/` — Helper scripts
+- `ci/` — CI dependency installation scripts
+- `.github/workflows/` — GitHub Actions CI workflows
+- `tools/` — Release and maintenance tools
+- `.agents/` — AI agent configuration files
+
+## Environment Setup
+
+### Prerequisites
+
+- git
+- autoconf, automake, m4
+- make
+- gcc
+- pkgconf / pkg-config
+- libc headers
+- linux headers
+
+### Download Source
+
+```sh
+git clone --recurse-submodules https://github.com/linux-test-project/ltp.git
+cd ltp
+```
+
+### Build from Source
+
+```sh
+make autotools
+./configure
+make
+```
+
+### Install (default prefix: /opt/ltp)
+
+```sh
+make install
+```
+
+## Agent Instructions
+
+All agent configuration files are in the `.agents/` directory.
+
+### Task: Patch Review
+
+**Trigger**: User requests a review of a patch, commit, branch, PR, or patchwork/lore URL.
+
+**Action**: Load the `review` skill via `skill({ name: "review" })`.
+
+### Task: Write or Modify C Tests
+
+**Trigger**: User asks to write, fix, or modify a C test.
+
+**Action**: Load `.agents/c-tests.md` and `.agents/ground-rules.md` before writing code.
+
+### Task: Write or Modify Shell Tests
+
+**Trigger**: User asks to write, fix, or modify a shell test.
+
+**Action**: Load `.agents/shell-tests.md` and `.agents/ground-rules.md` before writing code.
+
+### Task: General Questions
+
+**Trigger**: User asks about LTP architecture, APIs, or how to do something.
+
+**Action**: Use the project structure and documentation paths below to find answers.
+
+## Additional Resources
+
+- Documentation: https://linux-test-project.readthedocs.io/
+- Source code: https://github.com/linux-test-project/ltp
+- Mailing list: https://lore.kernel.org/ltp/
+- Patchwork: https://patchwork.ozlabs.org/project/ltp/list/
+- Kirk (test runner): https://github.com/linux-test-project/kirk
+- Linux kernel coding style: https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+### In-Repository Documentation
+
+- Development guide: `doc/developers/`
+- Maintenance guide: `doc/maintenance/`
+- User guide: `doc/users/`
+- C API reference: `doc/developers/api_c_tests.rst`
+- Shell API reference: `doc/developers/api_shell_tests.rst`
+- Build system: `doc/developers/build_system.rst`
+- Test writing tutorial: `doc/developers/test_case_tutorial.rst`

---
base-commit: 52e2dad4ce4ae53554f127b3bdf01c1c632e8220
change-id: 20260215-agents_file-344bdc3300d0

Best regards,
-- 
Andrea Cervesato <andrea.cervesato@suse.com>


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v6] agents: Add AI agent configuration for code reviews

[Petr Vorel]

Hi Andrea,

thanks for your work. On a first look LGTM.

Acked-by: Petr Vorel <pvorel@suse.cz>

I wonder if we can somehow avoid duplicity with our Ground Rules
https://linux-test-project.readthedocs.io/en/latest/developers/ground_rules.html
Ideally text would be just in a single document.

...
> +### 6. Safe Macros
> +
> +- MUST use `SAFE_*` macros for system calls that must not fail
> +- Safe macros are defined in `include/` directory
Actually the signatures are defined there, the code mostly not, but that's minor
detail.

> +
> +### 7. Kernel Version Handling
> +
> +- MUST use `.min_kver` for kernel version gating
> +- MUST prefer runtime checks over compile-time checks
...

I guess I should send v2 for my patch and that could be updated here
https://patchwork.ozlabs.org/project/ltp/patch/20260128080121.18878-1-pvorel@suse.cz/
https://lore.kernel.org/ltp/20260128080121.18878-1-pvorel@suse.cz/

> +
> +### 13. Deprecated Features
> +
> +- MUST NOT define `[Description]` in the test description section

When we handle details like this, we may want to add rule to avoid unnecessary
tags e.g. .mount_device:

metadata/metaparse.c

static struct implies {
	const char *flag;
	const char **implies;
} implies[] = {
	{"mount_device", (const char *[]) {"format_device", "needs_device",
		"needs_tmpdir", NULL}},
	{"format_device", (const char *[]) {"needs_device", "needs_tmpdir",
		NULL}},
	{"all_filesystems", (const char *[]) {"needs_device", "needs_tmpdir",
		NULL}},
	{"needs_device", (const char *[]) {"needs_tmpdir", NULL}},
	{"needs_checkpoints", (const char *[]) {"needs_tmpdir", NULL}},
	{"resource_files", (const char *[]) {"needs_tmpdir", NULL}},
	{NULL, (const char *[]) {NULL}}
};

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v6] agents: Add AI agent configuration for code reviews

[Andrea Cervesato via ltp]

Hi,

> https://linux-test-project.readthedocs.io/en/latest/developers/ground_rules.html
> Ideally text would be just in a single document.

I was thinking the same, but at the moment I don't know how to combine
these two things. One is a documentation oriented format, the other is a
list of rules for the agent.

--
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v6] agents: Add AI agent configuration for code reviews

[Petr Vorel]

Hi Andrea,

> > https://linux-test-project.readthedocs.io/en/latest/developers/ground_rules.html
> > Ideally text would be just in a single document.

> I was thinking the same, but at the moment I don't know how to combine
> these two things. One is a documentation oriented format, the other is a
> list of rules for the agent.

No problem, thanks for considering it. I was also thinking about mentioning the
rules in the Patch review [1] in the Maintainers section. Probably the rules for
AI review might be different from review doing by humans, but at least mention
that we have some rules for AI might be useful for the maintainers who read the
Patch review page.

Kind regards,
Petr

[1] https://linux-test-project.readthedocs.io/en/latest/maintainers/patch_review.html

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp