mission-control-v2/docs/skills/orchestrator.md

orchestrator — Auftraege managen, nicht selbst ausfuehren

Kurz: Wenn ein Auftrag zu gross fuer einen Rutsch ist, zerlegt der Orchestrator-Skill ihn in Teil-Tasks, delegiert diese seriel an Worker-Modelle, integriert die Ergebnisse, laesst sie von zwei Zweitgutachtern pruefen und gibt dem Commander einen Vorschlag zur Entscheidung — der Orchestrator schreibt nie selbst Code.

Was der Skill tut

Der Skill beschreibt ein Manager-Modell, das komplexe Auftraege in klar abgegrenzte Teil-Tasks zerlegt, jeden Teil seriel (nacheinander) an ein passendes Worker-Modell delegiert, die Ergebnisse einsammelt und zusammensetzt, sie durch ein Zwei-Kritiker-Gate prueft und als Telegram-Vorschlag zurueckgibt. Der Commander entscheidet, ob er annimmt oder verwirft. Der Orchestrator selbst baut und deployt nie etwas.

Wann er zum Einsatz kommt

Situation	Aktion
Auftrag ist zu gross fuer einen Rutsch (2-4 Teil-Tasks)	Orchestrator (diese Datei)
Auftrag ist klein und einfach	Direkt bearbeiten, kein Orchestrator
Auftrag ist zu gross (breite Architektur-Aenderung, viele Module)	Etappen-Plan: in lauffaehige Teilprojekte zerlegen
Nur ein einziger Code-Review-Schritt ist nötig	Werkstatt-Skill (wartung)

Konfiguration

Vorhandene Skripte (immer mit vollem Pfad!)

Skript	Pfad	Aufgabe
Worker	~/.hermes/scripts/worker.sh	Delegiert einen Teil-Task an ein Worker-Modell (Ein-Schuss)
Fremdkritik	~/.hermes/scripts/fremdblick.sh	Laesst den zusammengesetzten Diff von einem zweiten Modell gegengelesen

Wichtig: Beide Skripte liegen NICHT auf dem PATH — sie muessen IMMER mit vollem Pfad aufgerufen werden. Glaubst du, sie fehlen: erst ls -la ~/.hermes/scripts/worker.sh ausfuehren.

Worker-Modelle

Rolle	Modell	Warum
Planung	gpt-oss-120b (heavy)	Fuer die initiale Architektur-Planung (laedt ~15s, stört Lucys Latenz gewollt — Hintergrundprozess)
Code-Bau	Qwen3-Coder-Next	Klein, passend neben dem Warm-Set, ideal fuer Teil-Task-Umsetzung

Arbeitsverzeichnis

Worktrees liegen unter ~/.hermes/worktrees/ (nicht /tmp — ueberlebt keinen Reboot). Die Live-Instanz ~/mission-control-v2 bleibt unberuehrt — immer im Worktree arbeiten.

Arbeitsablauf (Schritt-für-Schritt)

1. Beratung & Zerlegen

Bevor du selbst Tasks aufteilst, befragst du zwingend gpt-oss-120b nach einem Architektur-Plan:

printf '%s' "Auftrag: <Beschreibung>" | \
  WORKER_MODEL=gpt-oss-120b WORKER_ROLE=plan \
  ~/.hermes/scripts/worker.sh > /tmp/orch-plan.txt

Lies den Plan und zerlege den Auftrag in eine geordnete, nummerierte Liste von Teil-Tasks (2-4).

2. Worktree anlegen

mkdir -p ~/.hermes/worktrees && cd ~/mission-control-v2 && \
  git fetch -q origin && \
  git worktree add ~/.hermes/worktrees/orch-<slug> \
    -b orchestrator/<slug> origin/main
mkdir -p ~/.hermes/worktrees/orch-<slug>-work

Der Slug ist ein kurzer Kebab-Case-Name des Auftrags (z. B. login-fix).

3. Teil-Tasks seriel an Worker delegieren

Fuer jeden Bau-Teil-Task:

printf '%s' "<Kontext + genauer Auftrag>" | \
  WORKER_ROLE=build \
  ~/.hermes/scripts/worker.sh > \
  ~/.hermes/worktrees/orch-<slug>-work/<n>.out

• Die Ausgabe beginnt mit FEHLT: → zu wenig Kontext, nachliefern und erneut rufen.
• Enthaltene Code-Zaunen (```) oder Prosa entfernen, sauberes Artefakt bleibt.
• Du schreibst das Artefakt mit deinen Datei-Tools an seinen Platz im Worktree.
• Schreibziel-Pflicht: Jedes write_file/patch MUSS mit ~/.hermes/worktrees/orch-<slug>/ beginnen.

4. Integrieren + Self-Gate

Die Worker liefern Bausteine — du sorgst dafuer, dass sie zusammenpassen (Imports, Verdrahtung, Namen).

• Python: python3 -m py_compile <dateien> (Tests wenn moeglich mitlaufen lassen)
• Shell: bash -n <dateien>
• Frontend: im Worktree cd frontend && npm install && npm run build, neues frontend/dist MIT-committen

Live-Checkout unberuehrt (zwei Beweise):

git -C ~/mission-control-v2 status --porcelain -uno  # MUSS LEER sein
curl -sf http://127.0.0.1:9001/api/health            # MUSS Gruen zeigen

5. Zwei-Kritiker-Gate

Zwei Zweitgutachter mit je anderer Staerke lesen den gesamten Diff gegen origin/main:

Zuerst ALLES stagen:

git -C ~/.hermes/worktrees/orch-<slug> add -A

Dann die Eingabe bauen:

EINGABE="AUFTRAG (im Wortlaut):
<urspruenglicher Auftrag>

ZERLEGUNG (deine Teil-Tasks, je 1 Zeile):
<1..n>

GIT-DIFF des Worktrees:
$(git -C ~/.hermes/worktrees/orch-<slug> diff --cached origin/main)"

Kritik A — Kompetenz (Qwen3-Coder-Next, noch warm):

printf '%s' "$EINGABE" | FREMDBLICK_MODE=code \
  ~/.hermes/scripts/fremdblick.sh

Kritik B — Fremd-Blick (GLM-4.6V-Flash, andere Modellfamilie):

printf '%s' "$EINGABE" | FREMDBLICK_MODE=code \
  FREMDBLICK_MODEL=GLM-4.6V-Flash FREMDBLICK_MAXTOK=3000 \
  ~/.hermes/scripts/fremdblick.sh

Gate-Regel (streng):

Urteil	Aktion
Beide FREIGABE	Vorschlag erstellen
Einer ABGELEHNT	Nachbessern (max. 2 Runden), dann erneut gaten
Einer FREIGABE-MIT-VORBEHALT	Vorbehalte im Vorschlag ehrlich ausweisen
Kritiker fiel aus (FEHLGESCHLAGEN)	Einmal wiederholen, sonst "⚠ Kritik X fiel aus" vermerken

Wichtig: Ein Kritiker sagt JEWEILS ABGELEHNT oder FREIGABE oder FREIGABE-MIT-VORBEHALT. Sagt AUCH NUR EINER ABGELEHNT → nachbessern. Nur wenn BEIDE tragen → Vorschlag.

6. Telegram-Vorschlag

bash ~/mission-control-v2/deploy/notify.sh -s "[Orchestrator]" "<text>"

Der Vorschhalt enthaelt:

• 1-2 Saetze: was gebaut wurde, was der Commander entscheiden soll
• Die Zerlegung (welcher Teil-Task an welches Worker-Modell)
• Geaenderte/neue Dateien · Kern des Diffs
• Self-Gate-Ergebnis · Kritiker-Urteil KONKRET (nicht nur "ok")
• Branch-Name · Frage "merge oder verwerfen?"

7. Nichts loeschen

Worktree + Branch + rohe Worker-Ausgaben bleiben liegen, bis der Commander entschieden hat.

Leitplanken (nicht verhandelbar)

• Du delegierst, du baust NICHT selbst. Jedes Bau-Artefakt MUSS aus einem worker.sh-Aufruf stammen. Selbstgebaut = gescheiterter Lauf.
• "Task zu klein" ist KEIN Freibrief. Planung, Delegation oder Zwei-Kritiker-Gate NICHT eigenmaechtig ueberspringen — auch nicht "transparent angesagt".
• Propose-only. Am Ende steht IMMER ein Telegram-Vorschlag; die Entscheidung trifft der Commander. NIEMALS auf main committen, mergen oder deployen.
• Nur im Worktree arbeiten. Die Live-Instanz ~/mission-control-v2 bleibt unberuehrt.
• Security-Config ist TABU: keine Tokens, approvals, ufw, sudoers, ssh-Keys anfassen.
• Hermes-first: Bevor ein Teil-Task NEUE Infrastruktur baut, pruefe ob hermes-agent das nativ kann.

Pitfalls

Falle	Vermeidung
Code selbst schreiben statt Worker zu delegieren	Jedes Artefakt MUSS worker.sh-Quelle haben
In Live-Checkout schreiben statt Worktree	Schreibziel muss mit ~/.hermes/worktrees/ beginnen
/tmp fuer Worktrees nutzen	~/.hermes/worktrees/ — ueberlebt Reboots
git diff ohne add -A → Kritiker sehen LEEREN Diff	Immer zuerst git add -A, dann git diff --cached
Zu wenig Kontext fuer Worker → FEHLT:	Betroffene Datei/Ausschnitt + Beispiel + genaue Signatur mitgeben
Grosse Artefakte in Antwort kippen → Output-Limit	In Dateien schreiben, Pfade + 1-Zeilen-Zusammenfassung in Antwort
Fremdblick-Skript nicht gefunden	Immer vollen Pfad ~/.hermes/scripts/fremdblick.sh verwenden
Lockfile-Dreck beim Frontend-Build	Nach npm install: git checkout -- frontend/package-lock.json falls nicht geaendert
Nur Health-Curl als Beweis	git status --porcelain -uno MUSS LEER sein (Health-Curl allein reicht NICHT)

Konsistenz mit MC2-Konventionen

• Sprache: Deutsch, direkt, kein Marketing-Sprech.
• Struktur: Kurze Beschreibung → Wann einsetzen → Konfiguration → Arbeitsablauf → Pitfalls → Konsistenz.
• Querverweise: Verweise auf Werkstatt-Skill, Auftragsbuch, Worker- und Fremdkritik-Skripte.
• Tabellen: Wo sinnvoll (Situationen, Modelle, Gate-Regeln, Pitfalls) als Tabelle formatiert.
• Code-Blöcke: Alle Befehle als bash-Code-Blöcke mit klaren Variablen-Platzhaltern.
• Keine Secrets: Tokens und Pfade werden referenziert, nicht ausgeschrieben.
• Leitplanken: Nicht-verhandelbare Regeln als eigene Sektion, um Delegationstreue zu erzwingen.

---

Diese Datei wurde als Skill-Dokumentation im MC2-Repo erstellt. Sie ist Teil der Skills-Docs in docs/skills/.