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

```bash
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

```bash
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:

```bash
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):**

```bash
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:

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

Dann die Eingabe bauen:

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

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

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

```bash
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
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/`._