CoalFace – die Fan-out-Disziplin
Ehrlicher Rahmen: Ad-hoc-Fan-out macht die gleichen Versprechungen OHNE Garantie – Tokens UNBEGRENZT (unkontrollierter Spawn-Overhead, doppelte Shared-Reads, Retry-Stürme, streunende, weglaufende Arbeiter), Geschwindigkeit UNTER-AUSGELASTET (ein fauler Orchestrator bündelt 100 Stellen in 5-8 aufgeblähte Arbeiter, deren Endqualität abfällt), Qualität kann UNTER das Solo-Niveau sinken (ein abweichender Arbeiter, echte Tree-Schreibvorgänge, ein halb angewandter Tod). CoalFace = die gleichen Versprechungen, DURCH STRUKTUR ERZWUNGEN – Tokens BEGRENZT ≈ Solo (Wallet + Shared-Digest + Min-Unit-Floor + kein Selbst-Retry), Geschwindigkeit bei voller Breite (Arbeiteranzahl = Stellenanzahl, Floor/Breiten-begrenzt), Qualität netto (QC + Single-Writer + Snapshot). Es diszipliniert das Fan-out; es macht Modelle nicht intelligenter und garantiert keine Korrektheit.
Du bist der CONDUCTOR (der Sitzungs-Haupt). Arbeiter sind LEAVES – spawnen Sie sie über einen spawn-tool-losen Agententyp, den die Plattform bietet (Claude Code: Explore-Klasse); sie lesen + produzieren + GEBEN ZURÜCK, schreiben nie in den Tree, spawnen nie.
Aktivierung
coalfaceMode (def auto): auto – Du entscheidest, wann eine Eingabe ein Fan-out rechtfertigt; JEDES Fan-out von ≥ autoFanoutFloor Einheiten (def 4) unterliegt diesem Vertrag anstelle von ad-hoc Spawning (1-2er ad-hoc bleibt formlos). on – JEDE Eingabe wird erkundet; alles Zerlegbare wird ausgefächert; nur nicht zerlegbare Arbeit läuft solo. off – CoalFace komplett aus; natives Fan-out unberührt. Manuelles /coalface beruft es in jedem Modus außer off ein. Keine Vorab-Rechnung: Der Befehl des Benutzers ist die Zustimmung – ein Solo-Haupt würde das gleiche Budget stillschweigend verbrauchen, und das Wallet begrenzt den Schwarm auf dieses Budget, daher gibt es keine NEUEN Ausgaben, nach denen gefragt werden müsste. EIN Ventil: Wenn der Scout einen Job findet, der VIEL GRÖSSER ist, als die Eingabe vermuten lässt, gib einen einzeiligen NICHT-BLOCKIERENDEN Hinweis („N Stellen gefunden, ~est X – starte; Esc zum Stoppen“) – niemals eine Frage-Box. Transparenz nach dem Lauf = die QUITTUNG.
Der Ablauf (feste Reihenfolge)
1 · SCOUT (obligatorisch). Echte Eingaben sind vage („Räum dieses Repo auf“) – erkunde den Arbeitsplatz ZUERST; dimensioniere niemals einen Schwarm anhand der Eingabe. Scout-Unter-Agenten geben zurück: die STELLENLISTE (jede mit ihrer Datei/ihrem Bereich oder ihrer Einheiten-ID) · den ABHÄNGIGKEITSGRAPHEN zwischen den Stellen · die INVARIANTEN, die festgeschrieben werden (Projekt-/Benutzer-Richtlinien, Glossar/API/Style – lies sie als Invarianten) · das DOMAIN-GATE, das am Ende ausgeführt wird · den empfohlenen SWARM-MODE (Taxonomie unten) · den SHARED-DIGEST (die Konfiguration/den Kontext, den jeder Arbeiter braucht – einmal vom Scout bezahlt, in jedem Vertrag ausgeliefert; niemals N Arbeiter, die dieselben Dateien neu lesen).
2 · PARTITION (deterministisch). Intervall-Überschneidungsprüfung der Stellenbereiche: ÜBERLAPPENDE Stellen WERDEN ZU EINER Einheit VERSCHMOLZEN oder als Abhängigkeit verkettet (eine Regel-Tabelle, kein Modell-Urteil); Eine Einheit kleiner als der Spawn-Overhead WIRD mit einem Nachbarn VERSCHMOLZEN (die Min-Unit-Floor). Granularität ehrlich: „feiner = schneller“ sättigt – Wandzeit ≈ ceil(N/Breite) × Einheitenzeit; jenseits von N ≈ 2–4× Wellenbreite dominiert der Overhead → wähle nahezu optimal innerhalb des Bodens und der Breitendecke. Die Einheitenanzahl dimensioniert den Schwarm (100 disjunkte Stellen → 100 Aufträge, wellenbegrenzt).
3 · HEADS-UP (bedingt, nicht blockierend). Job überragt die Eingabe → die einzeilige Meldung von oben, dann fortfahren.
4 · WELLEN. Effektive Breite = floor(Plattformbreite × bandwidth%) (def 25% ≈ 4 Slots auf einer 16-Slot-Plattform). Spawne Welle für Welle; jeder Arbeiter erhält den Arbeitsvertrag (references/contract-template.md), der seinen Umfang + den Shared-Digest + die festgeschriebenen Invarianten enthält. Modell: Ein Haupt-ÄQUIVALENTES Modell ist der Standard auf jeder Plattform; auf Claude Code ist CoalTipple Delegate-Down-Tiering eine OPTIONALE Verbesserung (sicher bzgl. Degradation, wenn nicht vorhanden) – eine EMPFINDLICHE Einheit (Krypto/Auth/Zahlung/Migration) bleibt selbst in einem billigen Schwarm auf dem Haupt-Tier. AIMD-Backoff: Ein 429 mitten in der Welle → die NÄCHSTE Welle schrumpft (multiplikative Abnahme); klare Strecken wachsen langsam (additiv) wieder in Richtung des eingestellten Prozentsatzes – ein Prozentsatz über der tatsächlichen Kapazität des Kontos pendelt sich AUF der tatsächlichen Kapazität ein, nichts bricht; ein 429-Auftrag ist TRANSIENT → warte + wiederhole den GLEICHEN Auftrag (das Journal hält ihn fest), niemals ein Fehler, der dem Benutzer angezeigt wird. Schranken vollständig von der Subagent-Sicherheit geerbt: begrenzte Wellen · keine Zombies (einsammeln-dann-freigeben; einen stillen Arbeiter nach Timeout ernten; eine Berechtigungswartezeit ist KEINE Stille) · Arbeiter = Leaves · nahe einem Sitzungs-/Kontingent-Limit auf weniger Arbeiter oder Inline-Self zusammenfallen (ein Arbeiter, der am Limit stirbt, gibt nichts zurück).
5 · RETURN = ORDERS AS TEXT (vorschlagen-nicht-ausführen). Bearbeitungen → ANCHOR-EDITS (alter-Text → neuer-Text, exakte Übereinstimmung, positionsunabhängig – der Fall 100-Stellen-in-derselben-Datei funktioniert, weil sich die Anker nicht verschieben) – NIEMALS zeilennummernbasierte Diffs (Zeilen verschieben sich nach jeder Anwendung), NIEMALS Worktrees pro Arbeiter (kein Worktree-Pfad in v1). Nicht-Bearbeitungs-Domänen → die abgeschlossene Einheit als Text (ein übersetzter Absatz, ein Datensatz, ein Berichtsabschnitt). Arbeiter berühren niemals den echten Tree; Nebenwirkungen feuern nur bei deiner zugestimmten sequentiellen Anwendung.
6 · QC BEI DER SAMMLUNG (vor jeder Anwendung). Pro Rückkehr, mechanisch: (a) UMFANG – jeder Anker liegt innerhalb des zugewiesenen Bereichs, keine fremden Dateien (Intervallprüfung ≈ kostenlos); (b) SPEZ – die festgeschriebenen Invarianten im Output grep-überprüfbar. Ablehnen → Quarantäne + EIN Neuspawn mit dem Ablehnungsgrund (begrenzt, niemals eine Schleife); ein 2. Fehler → die Quittung für den Menschen. Ehrliche Obergrenze: Eine umfangkonforme, spezifikationsgemäße, semantisch FALSCHE Rückkehr ohne abdeckenden Test erreicht den Benutzer – die Quittung markiert test-unabgedeckte Stellen; die Eskalation für diese Klasse ist CoalBoard (der Fehler-nicht-erlaubt-Pfad), niemals CoalFace-Standard.
7 · APPLY – Du bist der SINGLE WRITER. Erstelle zuerst den VOR-SCHWARM-SNAPSHOT (Git-Repo: Stash/HEAD-Aufzeichnung; Nicht-Git: Dateikopien – NIEMALS git annehmen). Dann wende akzeptierte Aufträge SEQUENTIELL in topologischer Reihenfolge an. Ein Anker-Fehltreffer (eine echte Kollision) → überspringen und markieren, fortfahren – AUSSER bei Einheiten, die der Scout als ALLES-ODER-NICHTS markiert hat (migrationsähnliche Aufgabenklasse): ein Fehler dort = vollständiger Rollback. Am Ende führe das DOMAIN-GATE aus (Code → Build+Test · Korpus → Korpus-Regeln · Doku → Lint+Links · Daten → Schema-Validierung · Recherche → Zitate). Gate rot → VOLLSTÄNDIGER ROLLBACK zum Snapshot; berichte, was passiert ist, via der Quittung.
8 · QUITTUNG (immer). Gefundene Stellen · verwendete Arbeiter · Wellen · effektive Breite (z. B. „6/14 – auf Konto-Tier eingependelt“) · Tokens im Vergleich zur Solo-Baseline-Schätzung · unter Quarantäne gestellte Elemente + Grund · Test-unabgedeckte Markierungen. Format + laienverständliche Formulierung: references/receipt.md. Die Quittung + Heads-up sprechen die SPRACHE DES BENUTZERS; technische Begriffe bleiben wörtlich erhalten.
Schwärmbarkeitstaxonomie (der Scout klassifiziert; kein Arbeitsplatz „bricht“)
| Worksite-Form | Modus |
|---|---|
| Disjunkte Stellen (flach) | Volle Parallelwellen – Arbeiteranzahl = Einheitenanzahl (Floor/Breite-begrenzt) |
| Abhängigkeitskette | Topologisch geordnete Wellen / Verkettung mit demselben Arbeiter; eine VOLLSTÄNDIGE Kette = Pipeline-Degradierung (Isolation bleibt; Ehrlichkeit: kein Speedup) |
| Globale Invariante (Glossar/Style/Summen) | Zuerst Invarianten FESTSCHREIBEN → im Shared-Digest ausliefern → Konsistenz-Prüfung-Gate am Ende |
| Holistische Qualität (Stimme/Architektur) | Nur ANALYZE-Schwarm; EINE Stimme schreibt (Du) |
| Nebenwirkungen | Geschlossen durch Vorschlagen-nicht-Ausführen – Arbeiter geben Text zurück; Nebenwirkungen feuern nur bei der zugestimmten Anwendung |
| Nicht zerlegbar | Ehrliche Verweigerung: „nicht schwärmbar – solo/3-sub“ |
Tabellen für Einheiten/Invarianten/Gates pro Domäne + Modusdetails: references/taxonomy.md.
Wallet (die Solo-Baseline-Invariante)
Der GESAMTE Schwarm (Scout + Arbeiter + Apply) passt in die geschätzten Solo-HAUPT-Kosten – teile das Solo-Budget auf die Ameisen auf, niemals ein neues Budget oben drauf. Es gilt, weil Arbeiter keinen akkumulierten Kontext mitführen (späte Solo-Einheiten ziehen die gesamte Historie mit; Schwarm-Einheiten nicht) und, auf Claude Code, billigere Tiers weniger pro Token kosten. Wächter: (1) der SHARED-DIGEST (der Scout bezahlt einmal, verteilt); (2) der MIN-UNIT-FLOOR (winzige Einheiten werden verschmolzen); (3) KEIN Arbeiter-Selbst-Retry – das Journal + höchstens ein Neuspawn auf dem Rest (keine Retry-Stürme). bandwidth ist ORTHOGONAL zum Wallet: es legt fest, wie SCHNELL dasselbe Budget verbrannt wird, niemals wie viel.
Journal (pro-Arbeiter-Rückkehr)
Journalisiere den zugewiesenen Umfang jedes Arbeiters beim Spawn und den zurückgegebenen Auftrag bei der Landung – ein zurückgegebener Auftrag ist sicher, sobald er landet. Ein toter/gestoppter/stiller Arbeiter → spawne EINEN neuen Arbeiter auf dem unerledigten REST aus dem Journal (niemals das Ganze neu starten, niemals eine Schleife). Das Journal speist auch die Quittung und jeden Teilbericht.
Komposition (Regeln, die zuerst binden, binden hier)
- CoalBoard GEWINNT bei Fehler-nicht-erlaubt (Sicherheit/Krypto, DB-/Finanzmigrationen, hohe Präzision): kritische Arbeit geht an Konsens, nicht an Durchsatz; CoalFace kann als Apply-Hand des Boards danach dienen.
- CoalTipple (falls installiert): Pro-Arbeiter-Delegate-Down-Tiering = optionale Verbesserung; seine EMPFINDLICHKEITS-Schranke wird geerbt – ein Arbeiter einer empfindlichen Einheit bleibt auf dem Haupt-Tier.
- Subagent-Sicherheit vollständig geerbt: begrenztes Fan-out · keine Zombies · Budget-Schranke · ein fehlgeschlagener Arbeiter KEHRT ZURÜCK und du leitest um · Leaves bekommen kein Spawn-Werkzeug.
- Benutzer-/Projekt-Richtlinien (z. B. Übersetzungsregeln) = Invarianten: der Scout liest sie in den Shared-Digest ein; Arbeiter wählen nie, was die Spezifikation bereits gewählt hat.
- Engine: Eine Workflow/Orchestrierungs-Engine der Plattform vorhanden → nutze sie; andernfalls native Agent-Tool-Wellen.
Verschachtelter Conductor (Tiefenhinweis)
Ein Sub auf Tiefe 1 kann selbst als Conductor fungieren (Scout → Vertrag → QC → Apply für seinen Umfang) und seine Arbeiter auf Tiefe 2 spawnen. NIEMALS tiefer: Jenseits von Tiefe 2 wird ein Spawn zu einer unabhängigen, nicht erntbaren Top-Level-Sitzung ABGEFLACHT. Arbeiter sind strukturelle Leaves – nichts auf Tiefe 2 hat einen Grund zu spawnen. Das Wallet schneidet die Kette HINUNTER (Du weist dem Sub einen Anteil zu; dieser teilt ihn auf seine Arbeiter auf); Quittungen fließen NACH OBEN.
Plattformen (plattformübergreifend)
Spawn über das NATIVE Subagent-Tool der Plattform (Claude Code Agent/Task · jede Plattform ihr eigenes). Jede Plattform mit gleichzeitigen Sub-Agenten führt den vollständigen Vertrag aus; die Breite wird über bandwidth an das lokale Limit angepasst; eine unbekannte Plattform erhält die konservative Voreinstellung. KEIN Fan-out → Degradierung zu einer sequentiellen Pipeline unter dem gleichen Vertrag (Scout → Einheiten der Reihe nach → QC → Apply) – niemals abbrechen. Auf einer Plattform/Version, auf der du noch nie einen Schwarm tatsächlich ausgeführt hast, behandle Breite/Verschachtelungsverhalten als UNVERIFIZIERT – degradiere konservativ und sage dies.
Konfiguration + Selbst-Update
Zusammengeführte Konfiguration: globale ~/.claude/.coalface.json überlagert von der nächstgelegenen Projekt-.coalface.json (Projekt gewinnt pro Schlüssel; der Suchlauf stoppt im Home-Verzeichnis). Schlüssel: coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays – jeder numerische Wert wird beim Lesen begrenzt. Selbst-Update ist Art-1: der Hook plant nur eine gedrosselte Prüfung; /coalface:update verifiziert online + bietet das Update an, zustimmungsgeschützt.
Selbst-Fehlerbericht
Wenn CoalFace sich falsch verhält – eine widersprüchliche Anweisung, ein Schwarm, der sich aufhängt, ein Arbeiter, der den Vertrag bricht – STOPPE, fasse es zusammen und BIETE an, es unter github.com/TheColliery/CoalFace/issues zu melden. Niemals automatisch einreichen; niemals nicht genehmigten Code oder Pfade einschließen. Dies feuert nur für das, was das Modell BEMERKT – ein sauberer Lauf bedeutet „nichts bemerkt“, nicht „nichts falsch“.