# OpenClaw ↔ Nexus Task Board Flow

> Letzte Aktualisierung: 2026-06-21  
> Status: kanonische Arbeitsbeschreibung für Iris, Sub-Agenten und das Nexus Task Board

Diese Datei beschreibt den gewünschten und umgesetzten Arbeitsfluss zwischen:

- **Bao** als Auftraggeber
- **Iris** als Chief of Staff / Koordinatorin
- **Sub-Agenten** als ausführende Spezialisten
- **OpenClaw** als Agent-Runtime
- **Nexus Task Board** als sichtbare Aufgabenquelle
- **MCP `/mcp`** als Agent Data Plane fuer Board-Operationen

---

## 1. Kurzfassung

**Eine Hauptaufgabe gehört Iris.**  
Wenn Iris Arbeit delegiert, wird diese Delegation **nicht unsichtbar im Chat** geführt, sondern als **sichtbare Child-Task** im Nexus Task Board angelegt.

Das bedeutet:

- **Parent-Task** = Verantwortung von Iris
- **Child-Task** = konkrete Arbeitsaufgabe für einen Spezial-Agenten
- **Board** = sichtbare Wahrheit für Aufgabenstatus und Ownership
- **OpenClaw** = Ausführungspfad für Agentenarbeit
- **MCP** = bevorzugter Agentenpfad zu Nexus; `/api/bridge` bleibt
  kompatible interne Fassade, `/api/dashboard` bleibt UI/Admin

---

## 2. Die Hauptidee

Früher war Delegation leicht unsichtbar oder lief über einen separaten `Delegated`-Status.

Der neue Flow ersetzt das durch:

1. **Iris übernimmt eine Parent-Task**
2. **Iris zerlegt die Arbeit bei Bedarf in Subtasks**
3. **Jede echte Delegation wird als Child-Task auf dem Board angelegt**
4. **Der zuständige Agent arbeitet gegen diese Child-Task**
5. **Iris integriert die Ergebnisse zurück in die Parent-Task**
6. **Erst wenn alles fertig ist, geht die Parent-Task in Review**

---

## 3. Systembild

```mermaid
flowchart LR
    Bao[Bao\nAuftraggeber]
    Iris[Iris\nChief of Staff]
    Board[Nexus Task Board\nParent + Child Tasks]
    OC[OpenClaw Runtime]
    Agents[Sub-Agenten\nDeveloper / Reviewer / Architekt / ...]

    Bao -->|Auftrag / Priorisierung| Iris
    Iris -->|legt Parent-Task an / übernimmt Task| Board
    Iris -->|delegiert konkrete Arbeit| OC
    OC -->|führt Agenten-Task aus| Agents
    Iris -->|legt Child-Tasks an| Board
    Agents -->|MCP Tools /mcp| Board
    Agents -->|liefern Ergebnis / melden Blocker| Iris
    Iris -->|integriert Ergebnis| Board
    Board -->|Review für Bao| Bao
```

---

## 4. Rollen und Verantwortlichkeiten

### Bao
- gibt Aufgaben inhaltlich vor
- priorisiert und nimmt fertige Arbeit ab
- verschiebt fertige Hauptaufgaben aus **Review** nach **Done** oder zurück

### Iris
- übernimmt die Parent-Task
- analysiert, zerlegt, delegiert und reviewed
- hält die Hauptaufgabe auf dem Board aktuell
- erstellt sichtbare Child-Tasks für delegierte Arbeit
- entscheidet, ob etwas **In Progress**, **Blocked** oder **Review** ist

### Sub-Agenten
- arbeiten **nicht** direkt gegen eine diffuse Hauptaufgabe
- arbeiten gegen eine **konkret zugewiesene Child-Task**
- melden Fortschritt, Ergebnisse und Blocker an Iris

### OpenClaw
- führt die Agentenarbeit technisch aus
- liefert Nachrichten, Status und Arbeitsergebnisse zurück
- ersetzt nicht das Board als Aufgabenwahrheit

### MCP Agent Data Plane
- stellt `nexus_get_board`, `nexus_agent_overview`, Task-, Child-,
  Activity-, Status-, Checkpoint- und Handoff-Tools bereit
- nutzt nur kanonische States: `Backlog`, `In progress`, `Blocked`,
  `Done`, `Review`
- ist Fassade ueber `ITaskBridgeService`, keine zweite Board-Domaenenlogik

### Nexus Task Board
- ist die **sichtbare operative Quelle** für Aufgaben
- zeigt Parent-Task, Child-Tasks, Ownership und Status
- dokumentiert den tatsächlichen Arbeitsfluss

---

## 5. Parent-Task vs. Child-Task

| Ebene | Zweck | Owner | Sichtbarkeit |
|---|---|---|---|
| Parent-Task | Hauptauftrag / Koordination | Iris | Board |
| Child-Task | Delegierter Arbeitsblock | zuständiger Agent | Board |

### Parent-Task-Regeln
- bleibt bei Iris
- bleibt in der Regel **In Progress**, solange Koordination läuft
- geht erst auf **Review**, wenn alle nötigen Child-Tasks erledigt und integriert sind
- geht nur auf **Blocked**, wenn Iris insgesamt nicht weiterkommt

### Child-Task-Regeln
- repräsentiert eine echte delegierte Teilaufgabe
- hat klare Ownership (`AssignedTo`)
- zeigt sichtbar, welcher Agent woran arbeitet
- wird nicht für triviale Mini-Schritte missbraucht

---

## 6. Zustandsmodell

### Parent-Task-Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Backlog
    Backlog --> InProgress: Iris übernimmt
    InProgress --> InProgress: Child-Tasks anlegen / koordinieren
    InProgress --> Blocked: Gesamtblocker
    InProgress --> Review: alles integriert
    Review --> Done: Bao nimmt ab
    Review --> Backlog: Bao gibt zurück
    Blocked --> Backlog: Blocker gelöst
```

### Child-Task-Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Backlog
    Backlog --> InProgress: Agent startet
    InProgress --> Done: Ergebnis geliefert
    InProgress --> Blocked: Agent kommt nicht weiter
    Blocked --> Backlog: neu geplant / entsperrt
    Blocked --> InProgress: Iris stößt Weiterarbeit an
```

---

## 7. Der konkrete Arbeitsablauf

### Fall A: Bao gibt Iris einen neuen Auftrag

1. Bao formuliert einen Auftrag
2. Iris prüft Ziel, Scope, Risiko und Umgebung
3. Iris übernimmt oder erstellt die **Parent-Task**
4. Parent-Task geht auf **In Progress**
5. Wenn nötig zerlegt Iris die Arbeit in **Child-Tasks**
6. Child-Tasks werden passenden Agenten zugewiesen
7. Agenten arbeiten die Child-Tasks ab
8. Iris sammelt Ergebnisse ein und integriert sie
9. Parent-Task geht auf **Review**
10. Bao entscheidet: **Done** oder zurück nach **Backlog**

### Fall B: Agent meldet einen Blocker

1. Agent meldet Blocker an Iris
2. Iris prüft, ob der Blocker lokal lösbar ist
3. Wenn nein: die betroffene **Child-Task** geht auf **Blocked**
4. Falls nötig entsteht eine neue Ursachen-Task / neue Child-Task
5. Parent-Task bleibt **In Progress**, solange der Gesamtauftrag noch koordiniert wird
6. Nur wenn die Hauptaufgabe insgesamt feststeckt, geht die **Parent-Task** auf **Blocked**

---

## 8. OpenClaw- und Board-Interaktion

```mermaid
sequenceDiagram
    participant Bao
    participant Iris
    participant Board as Nexus Task Board
    participant OpenClaw
    participant Agent as Sub-Agent

    Bao->>Iris: Auftrag
    Iris->>Board: Parent-Task übernehmen / anlegen
    Iris->>Board: Child-Task anlegen
    Iris->>OpenClaw: Agentenauftrag starten
    OpenClaw->>Agent: Task ausführen
    Agent-->>Iris: Ergebnis / Rückfrage / Blocker
    Iris->>Board: Child-Task aktualisieren
    Iris->>Board: Parent-Task integrieren
    Iris->>Board: Parent auf Review setzen
    Board-->>Bao: Review sichtbar
```

---

## 9. Regeln für gutes Schneiden von Child-Tasks

Eine Child-Task ist sinnvoll, wenn sie:

- einen **klaren Arbeitsblock** darstellt
- einen **eigenen Verantwortlichen** hat
- ein **eigenes Ergebnis** liefern soll
- unabhängig als **Done** oder **Blocked** sichtbar sein kann

Keine gute Child-Task ist:

- „Datei öffnen"
- „kurz nachschauen"
- „eine Kleinigkeit prüfen"

Faustregel:

> **Eine Child-Task soll ein echter delegierbarer Arbeitsauftrag sein, kein Mikro-Schritt.**

---

## 10. Board-Sicht: was sichtbar sein soll

Im Board soll erkennbar sein:

- welche Parent-Task Iris gerade steuert
- welche Child-Tasks darunter existieren
- welcher Agent welche Child-Task besitzt
- welche Child-Task blockiert ist
- welche Parent-Task in Review auf Bao wartet

Im Task-Detail sollen sichtbar sein:

- Parent/Child-Beziehung
- `AssignedTo`
- Status
- erwarteter nächster Beitrag / letzter Aktivitätshinweis
- Child-Task-Liste direkt unter der Parent-Task

---

## 11. Kanonische Regeln

### Regel 1 — Das Board ist die sichtbare Aufgabenwahrheit
Chat und Agentenläufe ergänzen das Board, ersetzen es aber nicht.

### Regel 2 — Iris bleibt Ownerin der Hauptaufgabe
Delegation verschiebt Verantwortung nicht automatisch auf den Agenten.

### Regel 3 — Delegation ist sichtbar
Jede echte delegierte Arbeit wird als Child-Task abgebildet.

### Regel 4 — Kein künstlicher Wartezustand auf Parent-Ebene
Die Parent-Task bleibt **In Progress**, solange Iris aktiv koordiniert.

### Regel 5 — Blocker präzise markieren
Wenn nur ein Arbeitspaket hängt, blockiert zuerst die **Child-Task**, nicht automatisch die ganze Parent-Task.

### Regel 6 — Review ist Bao-Gate
Fertige Hauptaufgaben gehen erst in **Review**, dann nach Bao-Entscheid auf **Done** oder zurück.

---

## 12. Beispiel

### Parent-Task
**„Nexus Taskflow auf Parent-/Child-Modell umstellen“** — Owner: `iris`

### Mögliche Child-Tasks
- **PO-Spezifikation und Akzeptanzkriterien ausarbeiten** — Owner: `product-owner`
- **Schnelle Voranalyse / kleiner Patch** — Owner: `programmer-fast`
- **Backend-State-Handling anpassen** — Owner: `programmer`
- **Frontend-Board-Spalten und Labels anpassen** — Owner: `programmer`
- **Workflow verifizieren / Regression prüfen** — Owner: `reviewer`
- **Deploy-/Runtime-Auswirkung prüfen** — Owner: `architekt`

So sieht Bao später nicht nur „Iris arbeitet daran“, sondern konkret:

- welcher Teil erledigt ist
- welcher Teil noch läuft
- welcher Teil blockiert ist
- worauf Iris gerade wartet

---

## 13. Anti-Patterns

Diese Muster sollen vermieden werden:

- Parent-Task auf einen bloßen **Delegated**-Wartestatus schieben
- Delegation nur im Chat sichtbar machen
- Child-Tasks ohne klare Ownership anlegen
- Blocker nur mündlich erwähnen, aber nicht im Board markieren
- zehn Mikro-Subtasks für einen Mini-Arbeitsschritt erzeugen

---

## 14. Entscheidungsregel für Iris

Wenn Iris unsicher ist, ob sie eine Child-Task anlegen soll, gilt:

**Child-Task anlegen**, wenn mindestens einer der Punkte zutrifft:

- anderer Agent übernimmt echte Arbeit
- eigener Status muss sichtbar verfolgt werden
- eigener Blocker ist möglich
- Bao soll Transparenz über diesen Teil sehen

---

## 15. Technische Leitplanken

- `parentTaskId` verknüpft Child-Tasks mit der Parent-Task
- `AssignedTo` zeigt den operativen Owner
- Child-Tasks dürfen geplant in `Backlog` erstellt werden; nur aktiv gestartete Delegationen beginnen direkt in `In progress`
- Agentenstatus und Boardstatus dürfen sich ergänzen, aber nicht widersprechen
- Board-Spalten und API-State-Mapping müssen das Parent-/Child-Modell sauber abbilden
- UI und Doku müssen dieselbe Sprache sprechen
- Mission-Control-Gateway-Daten bleiben read-only im Browser: Nexus proxyt Status,
  Version und redigierte Activity; Gateway-Token und direkte Gateway-URLs bleiben
  im Backend.
- Config-Writes sind Bao/Owner-only, legen vor dem Austausch ein `.bak` an und
  schreiben einen `config_audit` Activity-Eintrag.

---

## 16. Merksatz

> **Iris koordiniert die Hauptaufgabe. Agenten erledigen sichtbare Child-Tasks. Das Board zeigt die Wahrheit. OpenClaw führt aus.**
