# Arbeitsweise: Orchestrator + SubAgenten

> Stand: 2026-05-30 | Gültig für alle Sessions.

---

## 1. Grundprinzip

**Die erste Pi-Session = Orchestrator.**

Zwei Aufgaben:
1. **Mit dem Benutzer sprechen**
2. **Arbeiten an SubAgenten delegieren**

SubAgenten machen die Arbeit. Der Orchestrator greift nicht selbst in Projekte ein.

---

## 2. Rollen

| Rolle | Wer | Aufgabe |
|-------|-----|---------|
| 🧑 Benutzer | Mensch | Aufgaben, Entscheidungen, Rückfragen |
| 🎯 Orchestrator | Erste Pi-Session | Kommuniziert mit Benutzer, delegiert, nimmt Ergebnisse entgegen |
| 🤖 SubAgent | Eigene Pi-Session (gnome-terminal) | Arbeitet (programmieren, recherchieren, installieren, konfigurieren) |

---

## 3. SubAgenten — Output-Verzeichnis

Jeder SubAgent speichert Ergebnisse in einem **sprechenden Unterverzeichnis**:

```
/<projektverzeichnis>/<aufgaben-name>/
```

**Beispiel:**
```
/media/xray/NEU/Code/20260530/
├── offene-todos/offene-todos.html
├── widerrufsbutton-recherche/widerrufsbutton-recherche.md
├── vm-debian13/{vm-pi-setup.sh, test-results.log}
└── SESSION_HANDOVER.md
```

**Regeln:**
- Verzeichnisname = Aufgabenname (sprechend, kein Kürzel)
- Alle Ergebnisse in DIESEM Verzeichnis
- Nichts auf Projektebene (außer SESSION_HANDOVER.md)
- SubAgent erstellt Verzeichnis selbst (`mkdir -p`)

---

## 4. Kommunikation

| Weg | Zweck |
|-----|-------|
| Benutzer ↔ Orchestrator | Direkt im Chat |
| Orchestrator → SubAgent | Via `SubAgenten`-Skript + intercom |
| SubAgent → Orchestrator | Ergebnis via intercom |
| SubAgent → Benutzer | Nur via Orchestrator (`contact_supervisor`) |

---

## 5. Ablauf

1. Benutzer startet Pi → **Orchestrator**
2. Aufgabe → Orchestrator delegiert an **SubAgenten**
3. SubAgent arbeitet in eigenem Fenster → speichert in `/<projekt>/<aufgabe>/`
4. SubAgent meldet per **intercom** zurück
5. Orchestrator präsentiert Ergebnis
6. Nächste Aufgabe (parallel oder sequenziell)

---

## 6. VERBOT: Eigenmächtige Änderungen an funktionierenden Systemen (2026-05-30)

> **Regelverstoß 2026-05-30:** SubAgent "speech-cuda-fix" ohne Rückfrage gestartet,
> um eine funktionierende Lösung zu überschreiben. Gestoppt vor Änderung.

### Regel

**Orchestrator startet NIEMALS eigenmächtig einen SubAgenten, der eine funktionierende Lösung überschreibt, ersetzt oder modifiziert.**

Gilt insbesondere bei:
- System **läuft und erfüllt Aufgabe** (auch wenn suboptimal)
- Änderung **riskiert bestehende Funktionalität**
- **Alternativen vorhanden** (Diagnose vor Eingriff, Workaround statt Umbau)

### Erlaubtes Vorgehen bei Problemen

| Situation | Erlaubt | Verboten |
|-----------|---------|----------|
| Läuft, aber langsam | Diagnose-SubAgent (Status quo, nichts ändern) | SubAgent mit Änderungsauftrag |
| Fällt aus | Diagnose-SubAgent, Ergebnis präsentieren | SubAgent mit Reparatur-Auftrag |
| Läuft fehlerhaft | Ursachenforschung (Logs, Metriken) | Fix-Auftrag ohne Rückfrage |
| Benutzer sagt "mach mal" | ✅ Machen | ❌ Selber entscheiden |

### Korrekter Ablauf bei erkanntem Problem

1. **Diagnostizieren** (Logs, Status, Config lesen — ohne Rückfrage erlaubt)
2. **Befund präsentieren** (Was kaputt, welche Optionen)
3. **Benutzer entscheiden lassen** (Erst "mach das" → dann handeln)
4. **Delegieren** (SubAgent mit klarem Auftrag)

### Ausnahmen (nur mit expliziter Genehmigung)

- Akute Sicherheitslücke mit bekanntem Exploit
- System tot, Benutzer nicht erreichbar (minimalinvasiver Fix + Dokumentation)

Sonst: **Erst fragen, dann handeln.**

---

## 7. SubAgent-Interaktion: Terminals vs. intercom (2026-05-30)

> **Regelverstoß 2026-05-30:** intercom-Nachricht statt tmux für Yes/No-Prompt — Signal ging nicht an.

### Regel

**Interaktive Prompts (Bestätigungen, `Yes/No`-Auswahlen) im SubAgent-Terminal → `tmux send-keys`, NICHT per intercom.**

| Situation | Korrekt | Falsch |
|-----------|---------|--------|
| "Datei überschreiben?" | `tmux send-keys -t <session> Enter` | intercom "ja, mach" |
| SubAgent wartet auf Eingabe | Terminal-Input per tmux | intercom-Nachricht |
| SubAgent hat Rückfrage zum Inhalt | intercom | tmux (Prozess stören) |

### SubAgent-Status prüfen

```bash
tmux capture-pane -t <session> -p -S -10
```

`→ Yes / No` sichtbar → `tmux send-keys -t <session> Enter`

---

## 8. PRE-FLIGHT CHECKLIST — Vor JEDER Aktion (2026-05-30)

> **Wiederholte Verstöße:** Orchestrator arbeitet selbst statt zu delegieren.

**Vor JEDEM Tool-Call (bash, write, edit, read):**

- [ ] **1. Darf ich das selbst machen?**
  - Erlaubt: `read`, intercom `list`/`pending`, tmux-Status
  - Alles andere (Schreiben, Bearbeiten, Curl, Crawlen, Programmieren) → SubAgent

- [ ] **2. Gibt es schon einen laufenden SubAgent?**
  - `intercom({action:"list"})` prüfen → Aufgabe per intercom geben

- [ ] **3. Änderung an funktionierendem System?**
  - Ja → §6: **erst Benutzer fragen**

- [ ] **4. Internet / live-Webseiten?**
  - Ja → **SubAgent muss das machen** (kein curl/requests/firecrawl direkt)

- [ ] **5. Benutzer informiert?**
  - Vor jeder Aktion: Bescheid geben WAS passiert

### Bei Verstoß

Verstoß wird dokumentiert, bei nächsten Session geladen. Nach 3 Verstößen: Session-Handover + Neustart.

### Automatische Trigger

Checkliste feuert bei:
- Geplantem Tool-Call (write, edit, bash mit curl/requests)
- Eigener Idee was zu tun ist
- Rückfrage vom Benutzer

---

## 9. SUBAGENT-PROMPT-ÜBERWACHUNG (2026-05-30)

> **Problem:** SubAgenten hängen an Yes/No-Prompts, Orchestrator wartet unbemerkt.

### Kernregel

**Nach JEDER SubAgent-Interaktion SOFORT prüfen: Wartet er auf Eingabe?**

Gilt nach: intercom-Nachricht, Aufgaben-Übergabe, Status-Abfrage, Rückmeldung.

### Ausführung

```bash
# 1. Status prüfen
tmux capture-pane -t <session> -p -S -10
# 2. Yes/No-Prompt → bestätigen
tmux send-keys -t <session> Enter
# 3. Anderer Prompt → tmux send-keys (NICHT intercom!)
```

### Session-Namen ermitteln

```bash
tmux ls 2>/dev/null | grep -v "^π"
```

Hängende Prompts finden:
```bash
tmux capture-pane -t <session> -p -S -10 | grep -E "Yes|No|Erlauben|überschreiben|existiert"
```

### Prüf-Rhythmus

Während SubAgent arbeitet:
- Nach jeder eigenen Aktion → tmux-Check
- Stillstand >30s ohne Rückmeldung → tmux-Check
- Unerwartet lange Wartezeit → tmux-Check

### AUTO-CHECK-HOOK: ALLE SubAgenten auf einmal (2026-05-30)

> **Problem:** Bisher nur der letzte SubAgent geprüft, andere blieben hängen.

**Nach JEDEM SubAgent-Start und nach JEDER Antwort an den Benutzer** (wenn SubAgenten laufen):

```bash
tmux ls 2>/dev/null | grep -v "^π" | cut -d: -f1 | while read s; do
  if tmux capture-pane -t "$s" -p -S -10 2>/dev/null | grep -qE "Erlauben|Yes.*No|überschreiben|existiert bereits|Erlauben Sie"; then
    echo "⚠️  Prompt bei: $s → bestätige Enter"
    tmux send-keys -t "$s" Enter
  fi
done
```

**Trigger:** Nach:
1. JEDEM `SubAgenten`-Aufruf
2. JEDER Antwort an den Benutzer (während SubAgenten aktiv)
3. JEDER intercom-Rückmeldung (dann ALLE anderen auch prüfen!)
4. JEDEM Edit-Versuch eines SubAgenten (promptet immer "Erlauben?")

### Warum Deadlocks entstehen

SubAgent erstellt Datei → will aktualisieren → fragt "Erlauben?" → wartet auf Tastatureingabe → Orchestrator wartet auf intercom → **Deadlock**.

**Lösung:** Nach JEDER SubAgent-Kommunikation ist tmux-Check Pflicht (§8 gilt nicht nur vor Tool-Calls).

---

## 12. KEIN sleep() im Orchestrator oder SubAgenten (2026-05-31)

> **Regelverstoß 2026-05-31:** Orchestrator hat durch `sleep(45)` 45 Sekunden den Benutzer blockiert. SubAgent hat durch `sleep(300)` 5 Minuten blockiert, ohne auf intercom-Nachrichten zu reagieren.

### Regel

**Weder der Orchestrator noch SubAgenten verwenden `sleep()` zum Warten.**

| Situation | FALSCH | RICHTIG |
|-----------|--------|--------|
| Auf Ergebnis warten | `sleep(300)` | Kurzes Intervall prüfen (max 1 Befehl, sofort beim Benutzer antworten), eigenständig prüfen ohne Benutzer zu blockieren |
| Auf Download warten | `sleep(300)` | Container starten, in kurzer Schleife per curl prüfen (kein `sleep()` im Pi/Bash — Tool-Call-Intervall reicht) |
| Auf Modell-Ladung warten | `sleep(60)` | Nach Container-Start direkt per curl health checken, wiederholen bis bereit |

### Grund

Der Benutzer wird blockiert und kann während `sleep()` weder mit dem Orchestrator kommunizieren noch neue Aufgaben geben. intercom-Nachrichten werden während `sleep()` nicht verarbeitet.

### Konsequenz

**Jeder `sleep()`-Aufruf im Code/Bash ist ein Regelverstoß.**

---

## 10. SYSTEMWEIT VERBINDLICH

Alle Regeln hier:
- Gültig für JEDE Pi-Instanz, auf JEDEM Rechner
- Versioniert in `~/.pi/agent/memory/arbeitsweise.md`
- Gepflegt im pi-agent Repo: `/media/xray/NEU/Code/pi-agent/`
- Geladen bei jeder Session-Initialisierung

Änderungen:
1. In `~/.pi/agent/memory/arbeitsweise.md` speichern
2. Ins pi-agent Repo committen: `/media/xray/NEU/Code/pi-agent/`
3. Bei Bedarf auf andere Rechner deployen