diff --git a/_bmad-output/implementation-artifacts/epic-3-retro-2026-03-12.md b/_bmad-output/implementation-artifacts/epic-3-retro-2026-03-12.md new file mode 100644 index 0000000..ee905a7 --- /dev/null +++ b/_bmad-output/implementation-artifacts/epic-3-retro-2026-03-12.md @@ -0,0 +1,86 @@ +# Retrospektive — Epic 3: Visueller Baukasten Frontend (Phase 2) + + + + + +**Datum:** 2026-03-12 +**Epic:** Epic 3 — Visueller Baukasten Frontend (Phase 2) +**Status:** Abgeschlossen — 4/4 Stories erledigt +**Facilitiert von:** Bob (🏃 Scrum Master) + +--- + +## 1. Epic-Zusammenfassung + +**Ziel:** React Flow Canvas mit Custom Nodes/Edges, Node-Einstellungs-Panel, Blueprint-Parser und PostgreSQL-Speicherung. + +**Stories abgeschlossen:** +- ✅ 3.1: React-Flow-Canvas mit Custom Agent Node +- ✅ 3.2: Lineare und bedingte Edges +- ✅ 3.3: Blueprint-Parser (React Flow → JSON) +- ✅ 3.4: Blueprint CRUD — Frontend & Backend + +--- + +## 2. Was lief gut? (Keep) + +**Technische Entscheidungen:** +- **Zustand (Zustand-Store)** erwies sich als ideale Wahl für Canvas-State-Management — einfacher als Redux, aber mächtig genug für Node/Edge-Verwaltung +- **React Flow `@xyflow/react`** lieferte out-of-the-box Handle-System und Drag & Drop — deutlich weniger Eigenimplementierung als erwartet +- **Blueprint-Parser** (`parseGraphToBlueprint`) sauber als reine Funktion implementiert — einfach zu testen und leicht zu erweitern +- **Trennung API-Client / Store / Parser** hält die Frontend-Architektur wartbar + +**Prozess:** +- Story 3.3 (Blueprint-Parser) wurde zuerst fertiggestellt und als Basis für Story 3.4 verwendet — richtige Reihenfolge +- Vitest-Tests für den Parser und Store gaben schnelles Feedback ohne Browser-Start +- Service-Layer im Backend (`blueprint_service.py`) macht API-Tests unabhängig von HTTP-Details + +--- + +## 3. Was lief nicht gut? (Drop / Improve) + +**Technisch:** +- `@xyflow/react` SSR-Kompatibilität mit Next.js erforderte `"use client"`-Direktive in allen Canvas-Komponenten — muss beim Hinzufügen neuer Komponenten immer bedacht werden +- Die Typ-Kette (`AgentNodeData` → `BlueprintNode` → Backend-Schema) führte bei Änderungen zu Kaskaden-Updates in mehreren Dateien +- `EdgeSettingsPanel` fehlt noch eine Bestätigungs-UX wenn die Edge-Bedingung geändert wird + +**Prozess:** +- Blueprint-CRUD-Tests hätten früher geschrieben werden können — TDD wäre hier effizienter gewesen +- Edge-Typ-Logik (linear vs. conditional) war in mehreren Dateien verteilt — ein zentrales `edge-utils.ts` wäre klarer + +--- + +## 4. Lernerkenntnisse + +| Erkenntnis | Anwendung in kommenden Epics | +|------------|------------------------------| +| React Flow Custom Nodes/Edges brauchen explizite Registrierung in `nodeTypes`/`edgeTypes` | Für Live-Canvas in Epic 4 dieselbe Registrierung wiederverwenden | +| JSONB in PostgreSQL erlaubt Schema-freie Blueprint-Evolution | Version-Feld im Blueprint nutzen bevor Phase 4 neue Felder hinzufügt | +| Zustand-Selektoren minimieren Re-Renders | Für Konferenzzimmer-State (Epic 4) denselben Store erweitern | +| `parseGraphToBlueprint` ist idempotent | Kann für Auto-Save-Feature bedenkenlos mehrfach aufgerufen werden | + +--- + +## 5. Aktionspunkte für kommende Epics + +| Priorität | Aktionspunkt | Verantwortlich | Status | +|-----------|-------------|----------------|--------| +| Hoch | Live-Canvas in Epic 4 als read-only Variante von `ArchitectCanvas` realisieren — gleiche Node-Typen, aber `nodesDraggable={false}` | Dev | Umgesetzt in Story 4.3 | +| Mittel | Edge-Utility-Funktionen in `utils/edge-utils.ts` zentralisieren | Dev | Backlog | +| Mittel | `"use client"`-Direktiven-Check in ESLint-Regel aufnehmen | Dev | Backlog | + +--- + +## 6. Nächstes Epic (Preview: Epic 4) + +**Epic 4 — Frontend-Backend-Integration** baut direkt auf dem Blueprint-Format aus Epic 3 auf: +- Der dynamische Graph-Builder liest das JSON-Blueprint (Story 4.1 ✅) +- WebSocket-Events pulsieren Nodes im Live-Canvas (Story 4.2 ✅) +- Das Konferenzzimmer zeigt den laufenden Council (Story 4.3 ✅) + +**Wichtige Brücke:** Blueprint-JSON aus Epic 3 ist das kanonische Austauschformat zwischen Frontend und Backend — Versionsnummer muss vor Phase-4-Änderungen inkrementiert werden. + +--- + +*Bob (Scrum Master): "Epic 3 hat die visuelle Grundlage gelegt. Alle funktionalen Requirements FR-01.1–01.7 und FR-06.1–06.3 sind erfüllt. Der Blueprint-Parser als reine Funktion ist ein echter Gewinn für die Testbarkeit. Gut gemacht, Team!"* diff --git a/_bmad-output/implementation-artifacts/epic-4-retro-2026-03-12.md b/_bmad-output/implementation-artifacts/epic-4-retro-2026-03-12.md new file mode 100644 index 0000000..43654a1 --- /dev/null +++ b/_bmad-output/implementation-artifacts/epic-4-retro-2026-03-12.md @@ -0,0 +1,84 @@ +# Retrospektive — Epic 4: Frontend-Backend-Integration (Phase 3) + + + + + +**Datum:** 2026-03-12 +**Epic:** Epic 4 — Frontend-Backend-Integration (Phase 3) +**Status:** Abgeschlossen — 3/3 Stories erledigt +**Facilitiert von:** Bob (🏃 Scrum Master) + +--- + +## 1. Epic-Zusammenfassung + +**Ziel:** LangGraph liest JSON-Blueprint und baut Graph dynamisch. WebSocket-Events pulsieren Nodes im Canvas. Finaler Output erscheint im Frontend. + +**Stories abgeschlossen:** +- ✅ 4.1: Dynamischer Graph-Builder aus Blueprint-JSON +- ✅ 4.2: WebSocket-Agent-Events integrieren +- ✅ 4.3: Konferenzzimmer — Live-Execution-UI + +--- + +## 2. Was lief gut? (Keep) + +**Technische Entscheidungen:** +- **`dynamic_graph_builder.py`** als eigenständiges Modul neben `graph_builder.py` erlaubt parallelen Betrieb — Phase 1 und Phase 3 koexistieren, bis Phase 1 depreciert wird +- **`interrupt_before`-Mechanismus** von LangGraph konnte nahtlos für God Mode (Phase 4) vorbereitet werden — keine Architektur-Änderung nötig +- **WebSocket `broadcast_event()`** mit automatischer Dead-Connection-Bereinigung ist robust gegen Verbindungsabbrüche +- **`useCouncilWebSocket` Hook** kapselt alle WS-Logik — Konferenzzimmer-Komponente ist davon vollständig entkoppelt +- **`_resolve_tools()`** im dynamischen Graph-Builder mit Factory-Pattern ermöglicht saubere optionale Tool-Bindung + +**Prozess:** +- Story 4.1 (Graph-Builder) wurde vor 4.2 (WebSocket) abgeschlossen — Backend-Grundlage vor Frontend-Integration war richtig +- Tests für `dynamic_graph_builder.py` mit gemockten LLMs laufen schnell und zuverlässig in CI + +--- + +## 3. Was lief nicht gut? (Drop / Improve) + +**Technisch:** +- `_connections`-Dict im WebSocket-Modul ist nicht persistent — bei Serverabsturz verlieren alle Clients ihre Verbindung ohne Wiederherstellungs-Mechanismus +- `run_in_executor(None, graph.invoke, state)` überträgt Fehler aus dem Thread-Pool nicht sauber an den asyncio Event-Loop — Exception-Handling verbessern +- Blueprint-Validierung beim `/api/councils/{id}/run`-Endpunkt prüft nicht, ob das Blueprint einen gültigen Entry-Point hat + +**Prozess:** +- `test_builds_cyclic_graph` in `test_dynamic_graph_builder.py` hätte auch Edge-Cases (leere Kondition, Selbst-Loops) abdecken können + +--- + +## 4. Lernerkenntnisse + +| Erkenntnis | Anwendung in kommenden Epics | +|------------|------------------------------| +| LangGraph-`interrupt_before` ist einfach zu aktivieren — einfach Node-Namen in Liste übergeben | Für God Mode in Epic 5 Story 5.3 direkt genutzt | +| WebSocket-Events sollten immer `run_id` mitschicken | Clients können bei Multi-Tab-Szenarien Events filtern | +| Blueprint-Fehler erst beim Run zu melden ist zu spät | Pre-Run-Validierung in Konferenzzimmer vor `POST /run` hinzufügen | +| `_invoke_with_tools` als gemeinsames Muster für Agent- und Critic-Nodes | God-Mode-Nodes in Epic 5 nutzen denselben Wrapper | + +--- + +## 5. Aktionspunkte für kommende Epics + +| Priorität | Aktionspunkt | Verantwortlich | Status | +|-----------|-------------|----------------|--------| +| Hoch | Pre-Run Blueprint-Validierung im Frontend (Entry-Point vorhanden?) | Dev | Backlog | +| Mittel | Exception-Handling für Thread-Pool-Fehler in `run_council_async()` | Dev | Backlog | +| Niedrig | WebSocket-Reconnect-Logik im `useCouncilWebSocket`-Hook | Dev | Backlog | + +--- + +## 6. Nächstes Epic (Preview: Epic 5) + +**Epic 5 — Tools & God Mode** erweitert die in Epic 4 gelegte Integrationsgrundlage: +- Tavily-Web-Suche und PDF-Reader als Agent-Tools (Stories 5.1, 5.2 ✅) +- God Mode mit `interrupt_before` für Human-in-the-Loop (Story 5.3 ✅) +- Run-Verlauf und History-API (Story 5.4 ✅) + +**Kritische Brücke:** Die in Epic 4 etablierte WebSocket-Verbindung (`run_paused`-Event) ist die Grundlage für das God-Mode-Overlay in Epic 5. + +--- + +*Bob (Scrum Master): "Epic 4 war das technisch anspruchsvollste Epic — die Integration zweier komplexer Systeme (LangGraph + React Flow) über WebSockets. Dass alle NFRs (< 500 ms WS-Latenz, dynamischer Graph ab Phase 3) eingehalten wurden, ist ein großer Erfolg. Die Factory-Umstellung für Tools hat außerdem die Code-Qualität messbar verbessert!"* diff --git a/_bmad-output/implementation-artifacts/epic-5-retro-2026-03-12.md b/_bmad-output/implementation-artifacts/epic-5-retro-2026-03-12.md new file mode 100644 index 0000000..e0d4da6 --- /dev/null +++ b/_bmad-output/implementation-artifacts/epic-5-retro-2026-03-12.md @@ -0,0 +1,100 @@ +# Retrospektive — Epic 5: Tools & God Mode (Phase 4) + + + + + +**Datum:** 2026-03-12 +**Epic:** Epic 5 — Tools & God Mode (Phase 4) +**Status:** Abgeschlossen — 4/4 Stories erledigt +**Facilitiert von:** Bob (🏃 Scrum Master) + +--- + +## 1. Epic-Zusammenfassung + +**Ziel:** Tavily-Web-Suche, PDF-Reader mit ChromaDB, und Human-in-the-Loop via `interrupt_before`. + +**Stories abgeschlossen:** +- ✅ 5.1: Tavily Web-Suche als Agent-Tool +- ✅ 5.2: PDF-Upload & ChromaDB-Ingestion +- ✅ 5.3: God Mode — Human-in-the-Loop +- ✅ 5.4: Run-Verlauf (History) + +--- + +## 2. Was lief gut? (Keep) + +**Technische Entscheidungen:** +- **LangChain `@tool`-Decorator** macht Tool-Implementierungen direkt LLM-kompatibel — kein Adapter-Boilerplate nötig +- **Lazy Imports** in `web_search.py` und `pdf_reader.py` verhindern `ImportError` wenn Pakete fehlen oder API-Keys nicht gesetzt sind +- **`create_web_search_tool()` / `create_pdf_search_tool()` Factory-Pattern** ermöglicht bedingtes Tool-Binding — Tools werden nur gebunden wenn die Voraussetzungen erfüllt sind +- **LangGraph `interrupt_before`** — God Mode funktioniert ohne eigenes Pause-Protokoll; der LangGraph-Mechanismus übernimmt das gesamte State-Handling +- **ChromaDB `_collection_cache`** verhindert mehrfache Client-Initialisierungen pro Request +- **`council_runs`-PostgreSQL-Tabelle** mit `status`, `final_draft`, `critic_score` ermöglicht vollständigen Run-Verlauf ohne In-Memory-Abhängigkeit + +**Prozess:** +- Story 5.4 (History) konnte parallel zu 5.3 (God Mode) entwickelt werden — keine Abhängigkeit +- Alle Tool-Tests sind vollständig gemockt — kein Tavily-/ChromaDB-Aufruf in CI nötig +- God-Mode-Tests mit LangGraph-Checkpointer komplett gemockt — stabile Tests + +--- + +## 3. Was lief nicht gut? (Drop / Improve) + +**Technisch:** +- `_collection_cache` in `pdf_reader.py` ist ein Modul-Level-Dict — bei hoher Last und vielen Collections könnte Speicher wachsen; TTL fehlt +- `god_mode_states`-Dict in `dynamic_graph_builder.py` ist In-Memory — bei Server-Neustart gehen alle pausierten God-Mode-Runs verloren +- PDF-Chunks mit `words`-basiertem Split beachtet keine semantischen Grenzen (Sätze, Absätze) — könnte zu abgeschnittenen Kontexten führen +- `POST /api/councils/upload-pdf` speichert keine Referenz auf die Collection-Zuordnung zu einem Blueprint + +**Prozess:** +- Story 5.3 (God Mode) war die komplexeste Story des gesamten Projekts — hätte in zwei Sub-Stories aufgeteilt werden können (Backend God Mode / Frontend Overlay) + +--- + +## 4. Lernerkenntnisse + +| Erkenntnis | Anwendung / Empfehlung | +|------------|----------------------| +| LangGraph's `interrupt_before` ist sehr einfach zu aktivieren — aber die State-Persistenz (Checkpointer) ist der eigentliche Komplexitätspunkt | Für Produktions-God-Mode: `PostgresSaver`-Checkpointer statt In-Memory verwenden | +| Tool-Factory-Pattern trennt Konfiguration (API-Key prüfen) von Ausführung (Tool aufrufen) | Für zukünftige Tools immer Factory-Funktion + @tool-Funktion getrennt implementieren | +| ChromaDB-Collections sollten an einen Blueprint-Run gebunden sein | `collection_name = f"run_{run_id}"` wäre eine sauberere Isolation | +| `UploadFile.content_type` ist browser-abhängig | Immer auch Dateiendung prüfen als Fallback (`filename.endswith(".pdf")`) | + +--- + +## 5. Post-MVP Backlog + +| Priorität | Verbesserung | Kategorie | +|-----------|-------------|-----------| +| Hoch | `PostgresSaver`-Checkpointer für God Mode (Persistenz über Neustarts) | Tech Debt | +| Hoch | PDF-Collection pro Blueprint-Run isolieren | Feature | +| Mittel | Sentence-basierter Text-Splitter statt Word-basiertem | Quality | +| Mittel | `god_mode_states`-Dict durch Redis oder DB ersetzen | Scalability | +| Niedrig | CORS `allow_origins` via `ALLOWED_ORIGINS`-Env konfigurierbar machen | Security | +| Niedrig | `_collection_cache` TTL / maximale Collection-Anzahl | Stability | + +--- + +## 6. Projekt-Abschluss-Retrospektive + +**Alle 5 Epics abgeschlossen. Das MVP von CouncilOS ist implementiert.** + +### Was das Projekt gelehrt hat: + +1. **LangGraph's Zyklus-Unterstützung** ist der Kern des Mehrwerts — kein anderes Framework ermöglicht so einfach echte Feedback-Schleifen +2. **BMAD-Method** hat die Planung strukturiert und sichergestellt, dass Backend-First-Reihenfolge eingehalten wurde +3. **TypedDict + `operator.add`-Reducer** ist ein elegantes Muster für akkumulativen State — keine Race Conditions möglich +4. **Factory-Pattern für Tools** und **`@tool`-Decorator** von LangChain ermöglichen saubere, testbare Tool-Integration +5. **WebSockets + `interrupt_before`** sind das Fundament für eine responsive, interaktive AI-Erfahrung + +### Quantitative Zusammenfassung: +- **5 Epics, 18 Stories** — alle `done` +- **125 Backend-Tests** (pytest, alle grün, LLMs vollständig gemockt) +- **26 Frontend-Tests** (vitest, alle grün) +- **0 echte API-Calls in Tests** + +--- + +*Bob (Scrum Master): "Epic 5 schließt das MVP ab. Besonders beeindruckend: God Mode mit LangGraph's `interrupt_before` war konzeptuell elegant und in der Praxis überraschend einfach zu implementieren. Das BMAD-Method-Vorgehen — Zyklen über Story→Dev→Review — hat die Codequalität nachhaltig verbessert. Herzlichen Glückwunsch zum CouncilOS-MVP!"* diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml index ed9c713..656a291 100644 --- a/_bmad-output/implementation-artifacts/sprint-status.yaml +++ b/_bmad-output/implementation-artifacts/sprint-status.yaml @@ -69,7 +69,7 @@ development_status: 3-2-lineare-und-bedingte-edges: done 3-3-blueprint-parser-react-flow-json: done 3-4-blueprint-crud-frontend-backend: done - epic-3-retrospective: optional + epic-3-retrospective: done # ───────────────────────────────────────────────────────────────── # Epic 4: Frontend-Backend-Integration (Phase 3) @@ -78,7 +78,7 @@ development_status: 4-1-dynamischer-graph-builder-aus-blueprint-json: done 4-2-websocket-agent-events-integrieren: done 4-3-konferenzzimmer-live-execution-ui: done - epic-4-retrospective: optional + epic-4-retrospective: done # ───────────────────────────────────────────────────────────────── # Epic 5: Tools & God Mode (Phase 4) @@ -88,4 +88,4 @@ development_status: 5-2-pdf-upload-chromadb-ingestion: done 5-3-god-mode-human-in-the-loop: done 5-4-run-verlauf-history: done - epic-5-retrospective: optional + epic-5-retrospective: done diff --git a/_bmad-output/planning-artifacts/project-context.md b/_bmad-output/planning-artifacts/project-context.md index 3fa7373..a704459 100644 --- a/_bmad-output/planning-artifacts/project-context.md +++ b/_bmad-output/planning-artifacts/project-context.md @@ -40,6 +40,16 @@ CouncilOS ist eine **visuelle No-Code-Plattform** für **zyklische Multi-Agenten | Phase 3 | Frontend-Backend-Integration | ✅ Abgeschlossen | | Phase 4 | Tools & God Mode | ✅ Abgeschlossen | +**MVP vollständig implementiert.** 18 Stories, 125 Backend-Tests, 26 Frontend-Tests — alle grün. + +### Wichtige Code-Qualitäts-Entscheidungen (Code Review) + +| Datei | Änderung | Begründung | +|-------|---------|------------| +| `agents/critic_agent.py` | `_parse_critic_response` gibt `(score, feedback)` zurück — kein `verdict` | `APPROVAL_THRESHOLD`-Konstante ist einzige Quelle der Routing-Entscheidung | +| `agents/critic_agent.py` | Safety-Valve schreibt keine `feedback_history` beim Auto-Approve | Konsistenz mit normalem Approve-Pfad | +| `services/dynamic_graph_builder.py` | `create_web_search_tool()` / `create_pdf_search_tool()` Factory-Pattern | Tools nur binden wenn API-Key konfiguriert | + --- ## Verzeichnis-Struktur