[LTP] [PATCH v4] 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
- review.md: Review protocol for AI agents
- apply-patch.ms: How to download and apply patches before review

AGENTS.md at root provides project overview and links to review protocol.

Signed-off-by: Andrea Cervesato <andrea.cervesato@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.md              | 117 ++++++++++++++++++++++++++++++++++
 agents/apply-patch.md  | 123 +++++++++++++++++++++++++++++++++++
 agents/c-tests.md      | 170 +++++++++++++++++++++++++++++++++++++++++++++++++
 agents/ground-rules.md |  91 ++++++++++++++++++++++++++
 agents/review.md       | 108 +++++++++++++++++++++++++++++++
 agents/shell-tests.md  | 134 ++++++++++++++++++++++++++++++++++++++
 6 files changed, 743 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..050d1d1f557ab2e68758a70955c5b29b41b700f6
--- /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 `agents/review.md` and follow its instructions.
+
+### 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`
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/review.md b/agents/review.md
new file mode 100644
index 0000000000000000000000000000000000000000..a1b427e071ef2a72cfabcb2caf4e18c511879e78
--- /dev/null
+++ b/agents/review.md
@@ -0,0 +1,108 @@
+# LTP Patch Review Protocol
+
+You are an agent that performs a deep regression analysis on patches for the
+LTP - Linux Test Project.
+
+## Supported Review Inputs
+
+- **Git commit**: `abc1234` or `HEAD~1`
+- **Git branch**: `feature-branch`
+- **Multiple commits**: `abc1234..def5678` or `HEAD~3..HEAD`
+- **Patchwork URL**: `https://patchwork.ozlabs.org/patch/...`
+- **Lore URL**: `https://lore.kernel.org/ltp/...`
+- **Local patch file**: `./0001-fix-something.patch`
+- **GitHub PR**: `https://github.com/linux-test-project/ltp/pull/123`
+
+## Step 1: Load Core Files (MANDATORY)
+
+Before starting ANY review, MUST load BOTH files in this order:
+
+1. `agents/apply-patch.md` — Patch download and application instructions
+2. `agents/ground-rules.md` — Mandatory rules for all LTP code
+
+Do NOT proceed until both files have been read.
+
+## Step 2: Identify Patch Type
+
+Examine the changed files and classify the patch:
+
+- `*.c`, `*.h` files → **C test** → Load `agents/c-tests.md`
+- `*.sh` files → **Shell test** → Load `agents/shell-tests.md`
+- `Makefile*`, `configure.ac`, `*.mk` → **Build system** → No additional file
+- `*.rst`, `*.md`, `doc/**` → **Documentation** → No additional file
+- `.gitignore`, `.github/**` → **Repository config** → No additional file
+- Mixed C + Shell → Load BOTH `agents/c-tests.md` AND `agents/shell-tests.md`
+
+## Step 3: Review Commit Messages
+
+For EVERY commit (except those containing `--- b4-submit-tracking ---`):
+
+- MUST have `Signed-off-by:` tag
+- MUST be clear and follow kernel commit style
+- MUST use `[STAGING]` prefix if targeting unreleased kernel features
+- MUST have `Fixes: <hash>` if fixing an LTP commit
+- MUST have `Fixes: #N` if fixing GitHub issue N
+
+## Step 4: Run Type-Specific Checks
+
+### For C Tests
+
+MUST verify ALL of the following:
+
+1. Patch applies cleanly to latest master
+2. Code compiles without errors: `make -C <test-dir>`
+3. Test runs with `-i 0` without failures
+4. Test runs with `-i 10` without failures
+5. Test runs with `-i 100` without failures
+
+**Timeout rule**: If any step takes longer than 60 seconds, STOP and mark
+that step as `UNKNOWN` in the review output.
+
+**On failure**: If compilation or test fails, STOP and report the error.
+Do NOT attempt to fix the code unless explicitly asked.
+
+### For Shell Tests
+
+MUST verify ALL of the following:
+
+1. Patch applies cleanly to latest master
+2. `make check` emits no warnings for the test
+3. All rules from `agents/shell-tests.md` are satisfied
+
+### For Build System / Documentation / Config
+
+MUST verify:
+
+1. Patch applies cleanly to latest master
+2. Changes are consistent with existing patterns
+3. No unrelated changes included
+
+## Step 5: Output Review Verdict
+
+End EVERY review with this exact format:
+
+```
+### Summary
+
+- Signed-off-by: ✅ / ❌
+- Commit message: ✅ / ❌
+- Applies cleanly: ✅ / ❌ / N/A
+- Compiles: ✅ / ❌ / N/A
+- Tests pass (-i 0): ✅ / ❌ / UNKNOWN / N/A
+- Tests pass (-i 10): ✅ / ❌ / UNKNOWN / N/A
+- Tests pass (-i 100): ✅ / ❌ / UNKNOWN / N/A
+
+### Verdict
+
+**Approved** ✅ / **Needs revision** ❌ / **Needs discussion** ⚠️
+
+<explanation>
+```
+
+## Error Handling
+
+- If a file fails to load → STOP and report the error
+- If a patch does not apply → Report as "Applies cleanly: ❌" and STOP
+- If the build fails → Report as "Compiles: ❌" and include the error message
+- If tests fail → Report which iteration failed and include the failure output
+- If uncertain about a rule → Flag it as "Needs discussion" in the verdict
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.

---
base-commit: 4ebee67c1563b7a4282f37bfea1d4325b391d6db
change-id: 20260215-agents_file-344bdc3300d0

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