From 4c2d585f2d48be9937b7c9babfc0b5bc47c45966 Mon Sep 17 00:00:00 2001
From: "M.Schirmer" <fain.marcel@gmail.com>
Date: Wed, 7 Jan 2026 17:04:01 +0100
Subject: [PATCH] update AI helper for runner creations

---
 README.md        | 2 +-
 runner-agents.md | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b435a65..51ac2c8 100644
--- a/README.md
+++ b/README.md
@@ -104,7 +104,7 @@ No runner for your environment exists? No problem: use `runners-agents.md` to gu
 
 ## Development
 
-Runner development guidelines, including required data formats for keymaps, tests (`run_test.sh`), and Gitea CI (Neovim AppImage on ARM runners), are documented in `runner-agents.md`.
+Runner development guidelines, including required data formats for keymaps, tests (`run_test.sh`), Gitea CI (Neovim AppImage on ARM runners), and framework-agnostic best practices (naming conventions, TSamNearest priority, reporter payloads, failed-only behavior), are documented in `runner-agents.md`.
 
 Tests are written with `plenary.nvim` / `busted`. Mocks and stubs are allowed.
 
diff --git a/runner-agents.md b/runner-agents.md
index 287504a..0d206d7 100644
--- a/runner-agents.md
+++ b/runner-agents.md
@@ -237,3 +237,11 @@ jobs:
       - name: Run tests
         run: bash run_test.sh
 ```
+
+## Zusaetzliche Runner-Guidelines (framework-agnostisch)
+
+- **Testnamen-Konvention:** Runner sollen eine konsistente, dokumentierte Full-Name-Bildung verwenden (z. B. `Parent/Subtest`), inklusive Mehrfach-Nesting. Diese Konvention muss in `results.*`, `parse_test_output` und `collect_failed_locations` uebereinstimmen.
+- **TSamNearest-Prioritaet:** Falls moeglich, gelten folgende Regeln: Test-Block > Describe/Context-Block > File-Command. Das Verhalten muss getestet werden (Cursor im Test, zwischen Tests, ausserhalb von Describe/Context).
+- **Reporter-Payload-Schema:** Wenn ein Custom-Reporter verwendet wird, soll dessen JSON-Payload dokumentiert und stabil sein (z. B. `{ name, status, file, location, output }`), damit Parser/Quickfix/Detail-Output konsistent bleiben.
+- **Failed-Only-Logik:** Failed-Only muss auf den letzten Fehlermeldungen basieren und nur die fehlerhaften Tests erneut ausfuehren. Die Pattern-Strategie (z. B. Titel-only vs. Full-Name) muss getestet werden.
+- **CI-Installations-Snippet:** Die Neovim-Installation in CI soll als „authoritative snippet“ behandelt werden und in Runner-Repos 1:1 uebernommen werden.