pi-system/memory/arbeitsweise.md

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

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

# 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

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

Hängende Prompts finden:

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):

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