[LTP] [PATCH v5] agents: Add AI agent configuration for code reviews
Andrea Cervesato
andrea.cervesato@suse.de
Tue Feb 24 09:07:24 CET 2026
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 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 | 150 ++++++++++++++++++++++++++++++++++++
AGENTS.md | 117 ++++++++++++++++++++++++++++
6 files changed, 785 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..72029f689820ba2cb5a65f92dad03d436ea0a79f
--- /dev/null
+++ b/.agents/skills/review/SKILL.md
@@ -0,0 +1,150 @@
+---
+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: Fetch and Apply Patch
+
+```bash
+# Clean state
+git checkout <base-branch>
+git branch -D review/<name> 2>/dev/null
+
+# Fetch patch
+b4 am <message-id>
+
+# Apply patch
+git checkout -b review/<name> <base-branch>
+git am <mbox-file>
+```
+
+### 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: f062b34785db121c841f2faed8233b0943cdff27
change-id: 20260215-agents_file-344bdc3300d0
Best regards,
--
Andrea Cervesato <andrea.cervesato@suse.com>
More information about the ltp
mailing list