Auftragsbuch: 'doku/orchestrator-skill' angenommen (Ein-Klick-Gate)
This commit is contained in:
Auftragsbuch
@@ -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: <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/`._
|
||||||
Reference in New Issue
Block a user