# SSH Direct Review Protocol (A+B-Methode, 01.09.2026)

## Problem

Sub-Agenten sehen `/srv/work/tasks/` NICHT im NFS-Share. Sie haben keinen Zugriff auf
Master-Dateien. URLs allein reichen nicht (`curl -s https://domain/` liefert leer oder
scheitert am Tool-Limit). Datei-basierte Reviews mit 5 Prüfpunkten pro Task führen
dazu, dass Sub-Agenten am Iterations-Limit scheitern.

## Lösung: A+B Methode

**A = Task kleiner schneiden** (1 Prüfpunkt statt 5 pro Task)
**B = Inhalt per SSH direkt schicken** (scp + hermes chat --oneshot statt Datei-Queue)

## Workflow

```mermaid
sequenceDiagram
    Master->>Master: Schreibe Einzel-Punkt-Prompt in /tmp/prompt.txt
    Master->>SubAgent: scp /tmp/prompt.txt user@zt-ip:/tmp/review.txt
    Master->>SubAgent: ssh user@zt-ip 'hermes chat --oneshot --query-file /tmp/review.txt'
    SubAgent->>Master: Ergebnis (stdout)
    Master->>Master: Prüft Ergebnis, baut bei Bedarf nächsten Prompt
```

## Prompt-Format (erfolgreich getestet)

```
PRUEFE FOLGENDE RESSOURCEN-SEITE AUF DESIGN-FEHLER:

CSS-Variablen (aktuell deployed):
--bg:#0f172a
--surface:#1e293b
--ink:#4ade80

ANTWORTE NUR MIT: "OK" ODER "FEHLER: <beschreibung>"

1. Ist --muted(#94a3b8) auf --surface(#1e293b) lesbar?
2. Ist die Card-Grid-Aufteilung sinnvoll?
3. Fehlt ein visuelles Element?
```

## Regeln

1. **NUR EIN Prüfpunkt pro Fachgebiet** — 3-5 eng verwandte Fragen in EINEM Prompt
   (z.B. alle Kontrast-Fragen zusammen), aber NICHT Inhalt+Design+Code in einem Task
2. **Antwortformat erzwingen** — "ANTWORTE NUR MIT: OK ODER FEHLER: <beschreibung>"
3. **CSS-Werte direkt einbetten** — keine URL, kein Pfad, kein Verweis auf Master-Dateien
4. **hermes chat --oneshot** verwenden (nicht --query-file mit langen Sessions)
5. **Bei Tool-Limit:** Task war zu groß, z.B. bei UnraidHermes 11 Prüfpunkte scheiterten,
   3-5 funktionierten. Noch kleiner schneiden.
6. **scp vor ssh** — Prompt-Datei auf Sub-Agent kopieren, dann erst ausführen
7. **PATH setzen** — Sub-Agenten haben `hermes` nicht in $PATH →
   `PATH=/home/mehlzoerwer/.local/bin:/usr/bin:/bin hermes chat ...`

## Warum das funktioniert

- **Kein Dateisystem-Zugriff nötig** — der Prompt-Text kommt via scp auf /tmp/
- **Kein Tool-Limit durch file-reads** — der Agent muss keine URLs laden, keine Dateien suchen
- **Kein Permission-Problem** — /tmp/ ist für alle beschreibbar
- **Ein Checkpoint pro Durchlauf** — der Agent hat genau EINE Aufgabe: die 3-5 Fragen beantworten
- **Schnell** (~30s pro Agent, ~2 Min für Team-Review aller 3)
- **Kostengünstig** — ein Free-Modell ($0) für diese Mini-Tasks

## Fallstricke

- **Anführungszeichen im Prompt** — bei ssh-Befehl müssen einfache Anführungszeichen escaped werden.
  Lösung: Prompt in Datei schreiben, scp, dann `--query-file` nutzen. KEINE inline-Prompts per
  `ssh ... 'hermes chat -q "..."'` — das bricht bei Sonderzeichen.
- **Timeout** — `hermes chat --oneshot` kann bei Modell-Last 60s+ dauern.
  `background=true, timeout=120` für die ssh-Ausführung.
- **kein Ergebnis** — wenn der Sub-Agent am Tool-Limit scheitert, kommt "noch nicht fertig".
  Dann war der Prompt zu groß → noch kleiner schneiden.
- **Falsches Antwortformat** — manche Agenten ignorieren "ANTWORTE NUR MIT" und schreiben
  Essays. Entweder Prompt verschärfen ("WENN DU MEHR SCHREIBST WIRD ES VERWORFEN") oder
  die Antwort manuell parsen.

## Getestete Konfigurationen (01.09.2026)

| Agent | Erfolg | Dauer | Prompt-Größe |
|-------|--------|-------|-------------|
| UnraidHermes | ✅ OK (nur nach URL-Korrektur) | 47s | 11 Punkte → zu groß, scheiterte. 3 Punkte → OK |
| SwitchHermes | ✅ OK | 34s | 5 Design-Fragen |
| LaptopHermes | ✅ OK | 6s | 5 Tech-Fragen (gab nur "OK" zurück) |

## Voraussetzungen

- SSH-Key vom Master zum Sub-Agenten (ed25519, in `authorized_keys`)
- `scp` + `ssh` auf beiden Seiten
- Hermes auf dem Sub-Agenten installiert
- Kein NFS nötig