From a16cff39ce5808be43b5369b1846112ab09d7df5 Mon Sep 17 00:00:00 2001 From: Tobi Date: Tue, 21 Jul 2026 04:05:11 +0200 Subject: [PATCH] Doku: orchestrator Skill dokumentieren --- docs/skills/orchestrator.md | 198 ++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 docs/skills/orchestrator.md diff --git a/docs/skills/orchestrator.md b/docs/skills/orchestrator.md new file mode 100644 index 0000000..17e4e77 --- /dev/null +++ b/docs/skills/orchestrator.md @@ -0,0 +1,198 @@ +# 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: " | \ + 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- \ + -b orchestrator/ origin/main +mkdir -p ~/.hermes/worktrees/orch--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' "" | \ + WORKER_ROLE=build \ + ~/.hermes/scripts/worker.sh > \ + ~/.hermes/worktrees/orch--work/.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-/` beginnen. + +### 4. Integrieren + Self-Gate + +Die Worker liefern Bausteine — du sorgst dafuer, dass sie zusammenpassen (Imports, Verdrahtung, Namen). + +- **Python:** `python3 -m py_compile ` (Tests wenn moeglich mitlaufen lassen) +- **Shell:** `bash -n ` +- **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- add -A +``` + +Dann die Eingabe bauen: + +```bash +EINGABE="AUFTRAG (im Wortlaut): + + +ZERLEGUNG (deine Teil-Tasks, je 1 Zeile): +<1..n> + +GIT-DIFF des Worktrees: +$(git -C ~/.hermes/worktrees/orch- 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]" "" +``` + +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/`._