Spec Ops Pipeline (Lead-Worker)

Was macht Spec Ops Pipeline (Lead-Worker)?

SKILL_DIR = das Verzeichnis, das diese Datei enthält.

Rollengrenzen (nicht verhandelbar)

Rolle	Darf	Darf nicht
Lead (du)	Code lesen/durchsuchen, Tests/Linter/Builds ausführen, Spezifikationen schreiben, Reviews durchführen und den Ausführungsstatus (im Run-Verzeichnis) verwalten, Worktrees via worktree.sh verwalten; nach explizitem Ja des Benutzers migrate_to_bare.sh --apply ausführen; sobald der Checkpoint bestätigt ist, genehmigte Arbeit auf sop/*-Branches committen (gestaged: auch zwischen Stages) und pr.sh open / pr.sh merge ausführen (Merge gemäß auto_merge_risk); gemäß auto_cleanup (oder mit Zustimmung des Benutzers) aufräumen nach gemergten PRs	Keine Anwendungsdatei bearbeiten, erstellen, löschen oder verschieben – weder im Haupt-Checkout noch in einem Worker-Worktree (einzige Ausnahmen: migrate_to_bare.sh --apply und der Fast-Forward von worktree.sh sync); Merge-Konflikte manuell lösen; eine Aufgabe mergen, die nicht APPROVED wurde; --admin verwenden oder Branch-Schutz umgehen
Worker (Subagent)	Whitelist-Dateien in seinem Worktree bearbeiten, bis die DoD erfüllt ist	Nicht-Whitelist-Dateien anfassen, committen/pushen, außerhalb seines Worktrees arbeiten

Hast du Lust, es „einfach zu reparieren“? Schreib eine Spezifikation.

Modellzuweisung

Preflight runtime gibt die Modelle pro Rolle (lead = Phase 1, lead_phase2, worker, worker_light, scout); der Reviewer läuft auf lead. Rollen, Standardwerte, Überschreibungen, Stufen: models.md. Wenn du nicht auf dem Lead-Modell der aktuellen Phase bist, sag dem Benutzer, wie er wechselt (/model, /effort in Claude Code); mach nicht stillschweigend weiter – außer bei einem single-Run, der das Lead-Modell von Phase 1 behält.

Sitzungen und Kontext

• Phase 1: Schritte 0–2 auf dem Lead-Modell von Phase 1.
• Phase 2: Schritte 3–6. split: Beginnt mit Resume in einer neuen Sitzung auf dem Lead-Modell von Phase 2, die nur Plan, Status und die Spezifikationen der aktuellen Stage liest (in sich geschlossen). single: Fährt in derselben Sitzung fort.

session_split (env SOP_SESSION_SPLIT): auto (Standard) = split für jede H-Risk-Aufgabe, drei oder mehr Aufgaben, oder staged-Modus, sonst single; always → split; never → single.

Der Checkpoint zeigt es an; der Benutzer kann es überschreiben.

Der Run-Status befindet sich im Run-Verzeichnis (run.run_dir, <git common dir>/sop-run/): außerhalb jedes Worktrees, von allen Worktrees gemeinsam genutzt, über Sitzungen hinweg erhalten. Verwende niemals einen Sitzungs-Notizblock.

Befehlskonsolenausgabe – führe jeden Lint/Test/Build/DoD-Befehl aus über bash SKILL_DIR/scripts/run_logged.sh <run dir>/logs/<slug>-<step>-<n>.log '<command>' (gibt exit=<rc> lines=<n> log=<path> + die letzten 40 Zeilen bei Fehler aus). Lies mehr aus dem Log nur, wenn der Tail einen Fehler nicht erklärt. Gib niemals die vollständige Testausgabe in den Chat.

Workflow

0. Preflight

bash SKILL_DIR/scripts/preflight.sh --agent <claude|gemini|codex> --fetch (deine eigene Laufzeit; --fetch aktualisiert zuerst eine entfernte default_base) gibt eine JSON-Zeile aus: runtime (notiere worker, session_split), config (notiere source_worktree, default_base, provision, max_parallel, auto_merge_risk, merge_method, auto_cleanup; Layout), leftovers, run, pr, baseline, base_check, docker_pool. Führe in einem Bare-Layout Lead-Git/Tests-Befehle innerhalb von source_worktree aus. Reagiere auf:

1. run.has_state: true (Run läuft): Frage den Benutzer, ob er es fortsetzen möchte, aufräumen (wenn alle Aufgaben PRs haben, die auf den Benutzer warten), oder archivieren (worktree.sh rundir --archive) und neu starten.
2. leftovers (Aufgaben früherer Runs): Erwähne sie.
3. config.offer_bare_migration: true: Führe bash SKILL_DIR/scripts/migrate_to_bare.sh (Trockenlauf) aus, frage den Benutzer, ob in das Bare-Repo-Worktree-Layout konvertiert werden soll, formatiert gemäß bare-layout.md. Nur bei explizitem Ja: migrate_to_bare.sh --apply, führe preflight.sh erneut aus, lies die Agent-Dokumentation aus dem neuen source_worktree. Blockiert oder abgelehnt → Standard-Layout.
4. pr.ok: false: Der Run committed nur lokal; der Checkpoint sagt dies. Notiere pr.into. Merge-Regeln: execution-plan.md.
5. base_check.match: false, fetch_error oder error: Stimme die Basis mit dem Benutzer ab, bevor es weitergeht.
6. docker_pool.error: Sag dem Benutzer, dass die Kapazität unbekannt ist; sonst docker: false: überspringe; sonst wenn free < config.max_parallel: warne (Schritt 3 prüft erneut).
7. baseline = Ausgabe von git status --porcelain=v1 && git diff HEAD | sha256sum, bereits in source_worktree ausgeführt. Behalte es für state.json.

1. Audit (schreibgeschützt)

• Lege mit dem Benutzer den Umfang fest (Pfade; Sicherheit/Performance/Schulden/Spezifikationslücken).
• Scanne statisch; für einen großen Umfang zuerst mit parallelen schreibgeschützten Scouts (scout.md) und überprüfe ihre Hinweise. Führe die vorhandenen Lint/Test/Type-Check-Befehle des Projekts zur Wahrheitsfindung via run_logged.sh aus (Protokolliere audit-<n>.log); installiere keine Tools und ändere keine Konfiguration.
• Erstelle einen Gap-Bericht: nummerierte Befunde mit file:line, Schweregrad, Beweis, vorgeschlagener Behebung. Gruppiere sie in Worker-große Aufgaben mit kleinen, sich nicht überlappenden Whitelists.
• Bei mehreren Aufgaben: Entwurf des Ausführungsplans gemäß execution-plan.md: keine Abhängigkeiten → independent (alle parallel); verwandt → staged (abhängigkeitsgeordnete Stages, parallel innerhalb einer Stage, jede baut auf dem integrierten Ergebnis der vorherigen Stage auf).

2. Spezifikation (Checkpoint)

• Fülle für jede Aufgabe worker-spec-template.md aus und wähle ihre Worker-Stufe (models.md). Fülle Repo-Regeln aus der Agent-Dokumentation (AGENTS.md, CLAUDE.md, auch in Verzeichnissen, die die Whitelist berührt): Test-/Lint-Befehle, Flags, Sprachregeln; füge Repo-Fallstricke aus deinem Gedächtnis und etwaigen worker_notes hinzu. Worker können deinen Kontext nicht sehen. Schreibe DoD-Befehle so, wie es diese Regeln erfordern.
• Speichere im Run-Verzeichnis, niemals in einem Worktree: gap-report.md, plan.md, spec-<slug>.md, <slug>.wl.
• Überlappungsprüfung pro Stage: bash SKILL_DIR/scripts/check_scope.sh --overlap <source_worktree> <slug>.wl...; OVERLAP → neu aufteilen oder neu stagen; prüfe jedes POSSIBLE von Hand.
• DoD-Trockenlauf: Führe jeden DoD-Befehl von independent / Stage-1-Aufgaben in source_worktree via run_logged.sh aus (Protokolliere <slug>-dry-<n>.log), notiere die Klasse in der Spezifikation, repariere BROKEN (Details); Stage 2+ bei Schritt 3.
• Plan-Kritiker: Bei 2+ Aufgaben, staged-Modus, einer H-Risk-Aufgabe oder auf Anfrage: ein schreibgeschützter Kritiker (lead-Modell nur, wenn eine Aufgabe H-Risk ist, sonst lead_phase2); entscheide über jeden Befund gemäß plan-critic.md. Eine Runde.
• Zeige den Checkpoint-Bericht und warte auf Genehmigung vor Schritt 3, im Format von execution-plan.md §3. Die Genehmigung muss explizit abdecken: im staged-Modus die lokalen Commits und Merges zwischen den Stages; immer den automatischen Commit, Push, PR und – gemäß der Merge-Spalte – den Merge nach APPROVE; mit auto_cleanup das Aufräumen nach jedem Merge; und, wenn die Docker-Pool-Zeile prune: ask sagt, worktree.sh pool --prune. Formulierung in §3.
• Phasengrenze: Nach Genehmigung schreibe <run dir>/state.json (§7) mit phase: 2 und der vereinbarten session, dann:

  • split, sag dem Benutzer:

    Plan genehmigt und gespeichert unter <run dir>. Führe /clear aus, wechsle zum Lead der Phase 2 (/model <lead_phase2.model>, /effort <lead_phase2.effort>), dann rufe diese Fähigkeit mit resume auf.

    (Codex / Antigravity: Starte eine neue Sitzung auf lead_phase2.)

  • single: Sag dem Benutzer, dass der Plan unter <run dir> gespeichert ist und der Run hier fortgesetzt wird; gehe zu Schritt 3, ohne Modelle zu wechseln (resume funktioniert trotzdem).

Resume (Phase 2)

Bei resume: entrypoints.md.

Cleanup (nachdem der Benutzer gemergt hat)

Bei cleanup: entrypoints.md.

Schritte 3–5 laufen einmal pro Stage (independent = eine einzelne Stage), in der Plan-Reihenfolge. Halte state.json aktuell: aktualisiere den Status einer Aufgabe bei Dispatch, jeder Review-Runde, Genehmigung oder Zurückstellung sowie die Stage, wenn sie integriert ist.

3. Worktree + Dispatch

1. Vor dem Erstellen der Worktrees der Stage: bash SKILL_DIR/scripts/worktree.sh pool. docker: false → überspringe; error → sag dem Benutzer, frage zuerst. Sonst, wenn free < Anzahl der Aufgaben der Stage, führe worktree.sh pool --prune nur aus, wenn die Genehmigung es abdeckt (es entfernt alle nicht verwendeten Compose-Netzwerke aller Projekte; sie werden neu erstellt), sonst frage den Benutzer.
2. Für jede Aufgabe: bash SKILL_DIR/scripts/worktree.sh create <slug> [--base <ref>] (Stage 1: --base weglassen; Stage 2+: --base sop-stage/<n-1>; worktree.sh path <slug> zeigt eine Vorschau). Überprüfe provisioned in der Ausgabe; stoppe, wenn ein erwarteter Eintrag fehlt. Stage 2+: Führe einen Trockenlauf jeder Aufgabe in ihrem neuen Worktree via run_logged.sh vor dem Dispatch aus (nur Pfad/Flag-Korrekturen; sonst frage).
3. Füge den Worktree-Pfad und die Basis in jede Spezifikation ein, dann entsende alle Workers der Stage parallel gemäß dispatch.md, jeweils auf dem Modell seiner worker_tier (worker / worker_light; Cap max_parallel).

4. Gate (pro Aufgabe)

1. bash SKILL_DIR/scripts/check_scope.sh <worktree> <whitelist-file> muss mit 0 beendet werden; bei Verstößen macht der Worker sie rückgängig (zählt als Review-Runde).
2. Führe jeden DoD-Befehl selbst im Worktree via run_logged.sh erneut aus (Protokolliere <slug>-gate-r<round>-<n>.log); alle müssen mit 0 beendet werden.

5. Review (pro Aufgabe) + Stage-Barriere

Befolge review-checklist.md: Der Diff wird auf lead-Modell überprüft (split: schreibgeschützter Reviewer-Subagent, du überprüfst seine Befunde; single: du) gegen die aufgezeichnete Basis. Gib APPROVE oder REQUEST_CHANGES mit nummerierten file:line Befunden aus; schleife mit dem Worker maximal 3 Runden, dann eskaliere an den Benutzer. Aufgaben schleifen unabhängig. Eine light-Aufgabe, die in Runde 1 fehlschlägt, wird auf dem worker-Modell neu entsendet (models.md).

• independent: Bei APPROVE, committen, pushen, öffne den PR mit pr.sh und merge ihn, wenn die Auto-Merge-Regeln es erlauben, ohne Nachfrage (§4a).
• staged: Wenn jede Aufgabe der Stage APPROVED ist, committe jede lokal, führe worktree.sh integrate <n> --base <stage base> sop/<slug>... aus und bestehe das Integrations-Gate (alle DoDs der Stage im Stage-Worktree) vor der nächsten Stage; Konflikte, Integrationsfehler und Eskalationen: execution-plan.md. Wenn noch mehr Stages kommen, setze current_stage auf die nächste in state.json und fahre in derselben Sitzung fort. Biete eine neue Sitzung (/clear, dann resume) nur an, wenn der Kontext zu groß geworden ist (zwei Stages durchlaufen, oder viele Review-Runden); es ist hier sicher.

6. Abschluss

1. Führe den Baseline-Befehl von Schritt 0 erneut aus; er muss übereinstimmen, sonst berichte genau, was sich im Haupt-Checkout geändert hat – repariere es nicht selbst.
2. PRs: independent-PRs existieren bereits (§5); liste jeden als merged, open (Grund) oder nur lokal auf. staged: Öffne den einzelnen PR vom letzten sop-stage/<n> mit pr.sh (Merge gemäß auto_merge_risk, §6).
3. Aufräumen von gemergten PRs' Worktrees und Branches, worktree.sh sync, und – sobald jede Aufgabe bereinigt ist – worktree.sh rundir --archive. Keine Frage nur mit auto_cleanup in der Genehmigung, sonst frage zuerst. Niemals --force.
4. Abschließende Zusammenfassung: Befunde adressiert, zurückgestellt (und blockierte Abhängigkeiten), Branches/PRs mit Status, was aufgeräumt wurde und was übrig ist. Wenn PRs auf den Benutzer warten, ende mit: Nachdem du sie gemergt hast, rufe diese Fähigkeit mit cleanup auf.

Skripte und Layout

Verwendung, Exit-Codes, Worktree-Pfade, Provisionierung, Konfigurationsüberschreibungen: scripts-and-layout.md.