ClawdDotNet/docs/Orchestrator-Erweiterungskonzept-2026.md

ClawdDotNet — Orchestrator-Erweiterungskonzept 2026

Stand: 31. August 2026

Konzept- und Entwurfsdokument. Entstanden aus dem Marktvergleich (LangGraph, CrewAI, AutoGen, Letta, OpenHands, OpenClaw, Grokbot) und der anschließenden Detailabstimmung.

Dieses Dokument beschreibt die neuen Kollaborations-, Daten-, Sicherheits- und Resilienz-Konzepte, um ClawdDotNet als universellen, betriebssicheren Orchestrator für spezialisierte Agententeams (Finanzanalyse, Software-Engineering, SEO/Marketing, Research) zu erweitern.

---

1. Übersicht der Kernsäulen

                                  Architektur-Übersicht
 ┌─────────────────────────────────┬─────────────────────────────────┬─────────────────────────────────┐
 │   1. WORKFLOW & KOLLABORATION   │    2. DATEN & GEDÄCHTNIS        │    3. SICHERHEIT & DEFENSE      │
 │ • Hybride State-Graphs (YAML)   │ • Schematisierte Instanz-DB     │ • 5-Stufen Schutz vor Amoklauf  │
 │ • Debatten & Judge-Agent        │ • Task-Memory-Flush             │ • Quarantäne & Circuit Breaker  │
 │ • Ephemere Worker vs. Assistent │ • Scratchpad-Lifecycle          │ • 1-Klick Rollback via RunId    │
 ├─────────────────────────────────┼─────────────────────────────────┼─────────────────────────────────┤
 │   4. HITL & EILMELDUNGEN        │    5. PROMPTS & TEMPLATES       │    6. RESILIENZ & BENCHMARK     │
 │ • ask_supervisor -> ask_human   │ • Instanz-Setup für Personalmgr.│ • Multi-LLM Fallback-Kaskade    │
 │ • Mid-Execution Eilmeldungen    │ • Dynamische Prompt-Templates   │ • Evals as Code / Modell-Vergl. │
 │ • Interaktive Messenger-Buttons │ • ext_clitools/ Build-Struktur  │ • Kosten- & Latenz-Benchmarking │
 └─────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┘

---

2. Säule 1: Workflow-Topologien & Kollaborationsmuster

2.1 Hybride State-Graphs & Deterministische Pipelines

• Ziel: Kombination von deterministischer Prozesskonformität (für Pflicht- und Prüfschritte) mit agentischer Autonomie (für Recherche und Synthese).
• Struktur: Workflows werden deklarativ in YAML-Dateien im Agenten- oder Instanz-Ordner definiert.
• Berechtigungsregel: Ein Agent kann Workflow-Definitionen nicht eigenständig manipulieren. Änderungen erfolgen ausschließlich durch den Menschen oder über einen expliziten Workflow-Manager-Task.
• Ablauf:

  flowchart LR
      A[Task Start] --> B[Node 1: Deterministic Data Fetch]
      B --> C[Node 2: Agent Analyse & Draft]
      C --> D{Node 3: Deterministic Rule Check}
      D -- Fail --> C
      D -- Pass --> E[Node 4: Staging Approval]
      E --> F[Done: Deliverable Commit]
  

2.2 Multi-Agenten-Debatten mit „Judge Agent“

• Ziel: Iterative Qualitätsverbesserung durch Arbeiter-Kritiker-Zyklen (Arbeiter entwirft \leftrightarrow Kritiker prüft) ohne Gefahr von Deadlocks oder Endlosschleifen.
• Steuerung im Taskboard:
  • Arbeiter markiert Task als in_review.
  • Kritiker prüft gegen definierte Abnahmekriterien (acceptance). Bei Mängeln: Revisions-Task mit Feedback (Runde 1/N).
  • Abbruch-Bedingung: Maximal 3 Iterationsrunden oder Erreichen des Ziel-Scores.
  • Judge-Agent: Bei verbleibendem Dissens nach Runde 3 greift automatisch der Supervisor/Judge-Agent ein und fällt die finale Entscheidung oder eskaliert gezielt an den Menschen.

2.3 Ephemere Subagenten vs. Feste Team-Assistenten

• Aufgabenteilung:
  • Personalmanager-Agent: Erstellt vollwertige, persistente Team-Agenten mit eigenem Workspace und Langzeitgedächtnis für dauerhafte Rollen.
  • Ephemere Subagenten (Worker): Kurzlebige, zustandslose Worker für massiv-parallele Tool-Jobs (z. B. 20 Webseiten parallel crawlen).
• Budget-Hard-Cap: Vor dem Start eines Subagenten muss ein Teilbudget aus dem Haupttask reserviert werden (CAS im BudgetGuard). Bei Überschreitung des Instanz-Budgets wird der Aufruf sofort abgelehnt.
• Vererbung von RootRunId: Jeder Subagent erbt RootRunId und ParentRunId (#207), wodurch Gesamtkosten und Fehlerhistorie im Audit-Log lückenlos zusammengeführt werden.

---

3. Säule 2: Datenhaltung, Gedächtnis-Hygiene & Task-Lifecycle

3.1 Schematisierte Instanz-Datenbank („DocumentDB / CollectionStore“)

• Konzept: JSON-Dokumenten-Store mit strikter Schema-Validierung, basierend auf dem bewährten SqliteStorage (WAL-Modus, keine Dateisperren-Konflikte).
• Ablage: SharedWorkspace/data/collections/ (oder als SQLite-Tabelle InstanceCollections).
• Schema-Bindung: Ein Lead-Agent definiert einmalig schema.json. Alle insert/update-Aufrufe werden vor der Ausführung gegen das Schema validiert.
• Revisionssicherheit & Gleichzeitigkeit:
  • Jedes Dokument führt _id, _version, _created_by, _updated_at, _run_id und _is_deleted.
  • Gleichzeitige Updates nutzen Optimistic Locking (CAS auf _version).
  • Reines Append-Only: Kein physisches DELETE — nur logische Soft-Deletes.

3.2 Task-spezifischer Memory-Flush (Kontext-Reset)

• Problem: Ein Agent darf nach einer Nvidia-Analyse nicht mit Nvidia-Zahlen im Kopf an die Volkswagen-Analyse gehen.
• 3-Stufen-Gedächtnisfluss:
  1. Working Memory (Scratchpad): Während des Tasks liegt das Rohwissen im Task-Scratchpad (scratch/t-<id>.md).
  2. Memory-Commit bei Task-Abschluss: Beim Übergang auf done filtert der Agent generalisierbare Kernfakten heraus und schreibt sie mit passendem Subject und Key ins Langzeitgedächtnis.
  3. Kontext-Reset: Beim Wechsel auf einen neuen Task startet der Agent mit leerem Prompt-Kontext. Das automatische Memory-Recall lädt ausschließlich Fakten zum neuen Thema.

3.3 Scratchpad-Lifecycle & Archivierung

• Aktiv: Während in_progress unter SharedWorkspace/scratch/t-<id>.md.
• Archivierung: Bei done oder canceled verschiebt der Taskboard-Scanner das Scratchpad atomar nach SharedWorkspace/scratch/archive/.
• Retention: Ein wöchentlicher Wartungs-Job bereinigt archivierte Scratches älter als X Tage (Standard: 30 Tage).

---

4. Säule 3: Sicherheit, Containment & Disaster Recovery

4.1 5-Stufen-Schutz gegen amoklaufende Agenten

1. Prevent (Keine Zerstörungsgewalt):
   • Reines Append-Only & Soft-Deletes in Datenbanken und Collections.
   • Kein Hard-Delete im Dateisystem: FileRW-Papierkorb (#195) und protectedPaths für Systemordner.
   • Unveränderliche Identitäten: Identity.md und Soul.md sind schreibgeschützt (#205).
2. Contain (Blast Radius):
   • Strikt getrennte Workspaces (personal vs. shared).
   • Rate-Limits für Task-Erstellung (z. B. max. 10 Tasks / Stunde je Agent).
3. Detect (Anomalie-Erkennung & Circuit Breaker):
   • Häufen sich Fehler oder Massenänderungen (> 5 Fehlversuche / 3 Minuten), stoppt der Engine-Circuit-Breaker den Agenten automatisch.
4. Isolate (Quarantäne & Not-Aus):
   • Der Agent wird in den Status Quarantined versetzt; laufende Hintergrund-Tasks werden auf blocked gesetzt.
   • Quarantäne kann durch den Supervisor-Agenten oder per Messenger-Befehl (/quarantine @agent) ausgelöst werden.
5. Recover (1-Klick-Rollback / Time-Travel):
   • Jede Aktion trägt die gestempelte RunId im Audit-Log.
   • Mit einem Befehl (clawddotnet rollback --agent "@agent" --since "12:00") werden alle Datei- und Collection-Änderungen des Zeitraums atomar zurückgedreht.

4.2 Schutz vor lateraler Team-Infektion

• Untrusted Content Framing (#193): Alle externen Tool-Ergebnisse, Scratches und Dokumente fremder Agenten werden im Prompt in <untrusted_source>-Tags gekapselt. Der Kern-Prompt verbietet die Befehlsausführung aus diesen Datenquellen strikt.

---

5. Säule 4: Human-in-the-Loop & Live-Intervention

5.1 Mehrstufige Eskalation: ask_supervisor \rightarrow ask_human

• Stufe 1 (ask_supervisor): Bei Mehrdeutigkeiten oder Blockaden wendet sich der Agent zuerst an den leitenden Team-Agenten. Kann dieser die Frage anhand von Projektregeln oder Kontext beantworten, läuft der Task ohne Menschen-Wartezeit weiter.
• Stufe 2 (ask_human): Kann der Supervisor nicht entscheiden, wird die Frage als interaktive Nachricht (Telegram Inline-Buttons, Rocket.Chat) mit konkreten Auswahlschaltflächen an den Menschen gesendet.

5.2 Mid-Execution Priority Injects (Eilmeldungen & Zwischenrufe)

• Mechanismus: Vor jedem OpenRouter-Inferenz-Schritt prüft die AgentEngine eine instanzinterne Prioritäts-Queue.
• Eilmeldungen: Erkennt ein Monitor-Agent eine dringende Meldung (z. B. Veröffentlichung von Quartalszahlen), injiziert die Engine vor dem nächsten Denk-Schritt eine Systemnachricht: [SYSTEM / EILMELDUNG von @market-watcher]: Neue Quartalszahlen NVDA soeben gemeldet: ...
• Der arbeitende Analyst bindet die neue Information unmittelbar ein, ohne dass der Task abgebrochen werden muss.

---

6. Säule 5: Vorlagen, Build-Struktur & Modell-Resilienz

6.1 Instanz-Erstellungsleitfaden & Dynamische Prompt-Templates

• Leitfaden für KI-Personalmanager: Umfassender Prompt- und Best-Practice-Katalog für den Supervisor zur fehlerfreien Zusammenstellung neuer Agententeams.
• Dynamische Prompt-Templates (Scriban/Liquid): Variablen wie {{team_roster}} oder {{current_date}} in Identity.md und Soul.md sorgen dafür, dass neue Agenten im Team sofort von allen Kollegen erkannt werden.

6.2 Externe CLI-Tools Verzeichnisstruktur (ext_clitools/)

• Strukturierte und versionierte Ablage externer Binaries im Build:

  clawddotnet/
  └── ext_clitools/
      ├── ffmpeg/
      ├── yt-dlp/
      └── typst/
  

6.3 Multi-LLM Fallback & Modell-Benchmarking („Evals as Code“)

• Fallback-Kaskade: Konfiguration eines Ausweichmodells pro Agent (z. B. Primär: anthropic/claude-3.7-sonnet, Fallback: google/gemini-2.5-pro). Bei 5xx-Fehlern oder anhaltendem 429-Rate-Limit schaltet die Engine unterbrechungsfrei um.
• Evals-Test-Runner: Automatisierter Benchmark, der definierte Testaufgaben gegen unterschiedliche Modelle laufen lässt, um Qualität, Latenz und Tokenkosten quantitativ zu vergleichen.