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:**
  ```mermaid
  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.