218 lines
8.6 KiB
Markdown
218 lines
8.6 KiB
Markdown
---
|
||
inputDocuments:
|
||
- _bmad-output/planning-artifacts/prd.md
|
||
- _bmad-output/planning-artifacts/architecture.md
|
||
- _bmad-output/planning-artifacts/ux-design.md
|
||
- _bmad-output/planning-artifacts/epics.md
|
||
- CLAUDE.md
|
||
- README.md
|
||
bmadSkill: 'Tech Writer Agent (Paige) — /bmad-agent-bmm-tech-writer → [DP] Document Project'
|
||
bmadWorkflow: '_bmad/bmm/workflows/document-project/workflow.yaml'
|
||
---
|
||
|
||
<!-- 📚 Generated by BMAD Tech Writer Skill — Agent: Paige (Technical Writer) -->
|
||
<!-- Skill Command: /bmad-agent-bmm-tech-writer → [DP] Document Project -->
|
||
<!-- Workflow: _bmad/bmm/workflows/document-project/workflow.yaml -->
|
||
|
||
# Projekt-Kontext: CouncilOS
|
||
|
||
**Autor:** Paige (📚 BMAD Tech Writer Agent)
|
||
**Datum:** 2026-03-12
|
||
|
||
> Dieses Dokument ist die zentrale Referenz für alle KI-Assistenten (Claude Code, Cursor, etc.) und Entwickler, die am Projekt arbeiten.
|
||
|
||
---
|
||
|
||
## Was ist CouncilOS?
|
||
|
||
CouncilOS ist eine **visuelle No-Code-Plattform** für **zyklische Multi-Agenten-KI-Pipelines**. Nutzer bauen per Drag & Drop einen „KI-Rat" aus spezialisierten Agenten, die in Schleifen zusammenarbeiten — bis ein Dokument die gewünschte Qualität erreicht.
|
||
|
||
**Kern-USP:** Echte Zyklen (A→B→A→B→...) — kein lineares Abarbeiten.
|
||
|
||
---
|
||
|
||
## Projekt-Status
|
||
|
||
| Phase | Beschreibung | Status |
|
||
|-------|-------------|--------|
|
||
| Phase 1 | LangGraph-Engine Backend | ✅ Abgeschlossen |
|
||
| Phase 2 | Visueller Canvas Frontend | ✅ Abgeschlossen |
|
||
| 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
|
||
|
||
```
|
||
KI-Konzil/
|
||
├── README.md # Deutsches PRD (informell, Original)
|
||
├── CLAUDE.md # Konventionen für KI-Assistenten
|
||
├── .env.example # Umgebungsvariablen-Template
|
||
├── docker-compose.yml # Lokale Entwicklungsumgebung
|
||
│
|
||
├── _bmad/ # BMAD-METHOD Framework (v6)
|
||
│ ├── bmm/agents/ # Agent-Personas: pm, architect, dev, sm, qa, ...
|
||
│ ├── bmm/workflows/ # BMAD-Workflows: create-prd, create-architecture, ...
|
||
│ └── core/ # Core-Tasks und -Workflows
|
||
│
|
||
├── _bmad-output/ # BMAD Skill Output Artifacts
|
||
│ ├── planning-artifacts/
|
||
│ │ ├── product-brief.md # [Analyst] Produkt-Brief
|
||
│ │ ├── prd.md # [PM] Product Requirements Document
|
||
│ │ ├── architecture.md # [Architect] Architektur-Entscheidungen
|
||
│ │ ├── ux-design.md # [UX Designer] UI/UX Design
|
||
│ │ ├── epics.md # [PM] Epics & Stories
|
||
│ │ └── implementation-readiness.md # [Architect] Readiness-Check
|
||
│ └── implementation-artifacts/
|
||
│ ├── sprint-status.yaml # [SM] Sprint-Status-Tracking
|
||
│ ├── qa-e2e-tests.md # [QA] E2E-Test-Manifest
|
||
│ └── stories/ # [SM] Individuelle Story-Dateien
|
||
│
|
||
├── backend/ # FastAPI + LangGraph Backend (Python)
|
||
│ ├── main.py # FastAPI-Entrypoint
|
||
│ ├── state.py # CouncilState TypedDict + Konstanten
|
||
│ ├── database.py # Async SQLAlchemy Setup
|
||
│ ├── agents/ # master_agent, critic_agent, writer_agent
|
||
│ ├── api/ # REST-Routes + WebSocket + RunStore
|
||
│ ├── services/ # Graph-Builder, Blueprint-Service, Run-Service
|
||
│ ├── models/ # SQLAlchemy-Modelle
|
||
│ ├── tools/ # Tavily-Web-Suche, PyPDF+ChromaDB
|
||
│ └── tests/ # pytest-Tests (10 Dateien)
|
||
│
|
||
├── frontend/ # Next.js + React Flow Frontend (TypeScript)
|
||
│ ├── app/
|
||
│ │ ├── rat-architekt/ # Tab A: Canvas-Builder
|
||
│ │ ├── konferenzzimmer/ # Tab B: Execution-View
|
||
│ │ ├── components/ # React Flow Nodes, Edges, Panels
|
||
│ │ ├── store/ # Zustand State Management
|
||
│ │ └── utils/ # blueprint-parser, api-client
|
||
│ └── __tests__/ # Vitest-Tests
|
||
│
|
||
└── docs/ # Zusätzliche Dokumentation
|
||
└── test-coverage-analysis.md
|
||
```
|
||
|
||
---
|
||
|
||
## Kerndatenstruktur: CouncilState
|
||
|
||
```python
|
||
class CouncilState(TypedDict):
|
||
input_topic: str # Nutzerprompt oder PDF-Inhalt
|
||
current_draft: str # Aktuelles Dokument
|
||
feedback_history: Annotated[List[str], operator.add] # APPEND-ONLY
|
||
route_decision: str # "rework" | "approve" | custom
|
||
messages: Annotated[list, operator.add] # APPEND-ONLY
|
||
iteration_count: int # Schleifenzähler
|
||
critic_score: Optional[float] # 0–10
|
||
run_id: str
|
||
active_node: str
|
||
```
|
||
|
||
> **Wichtig:** `feedback_history` und `messages` werden **niemals überschrieben** — nur angehängt (`operator.add`-Reducer).
|
||
|
||
---
|
||
|
||
## Blueprint-JSON-Kanonisches Format
|
||
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"name": "Mein Rat",
|
||
"nodes": [
|
||
{
|
||
"id": "node-1",
|
||
"type": "agent",
|
||
"name": "Master KI",
|
||
"system_prompt": "...",
|
||
"model": "claude-3-5-sonnet-20241022",
|
||
"tools": { "web_search": false, "pdf_reader": false }
|
||
}
|
||
],
|
||
"edges": [
|
||
{ "id": "e-1", "source": "node-1", "target": "node-2", "type": "linear" },
|
||
{ "id": "e-2", "source": "node-2", "target": "node-1", "type": "conditional", "condition": "rework" }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API-Schnellreferenz
|
||
|
||
| Endpoint | Methode | Beschreibung |
|
||
|----------|---------|--------------|
|
||
| `/api/health` | GET | Health-Check |
|
||
| `/api/councils/` | POST | Blueprint erstellen |
|
||
| `/api/councils/` | GET | Alle Blueprints |
|
||
| `/api/councils/{id}` | GET/PUT/DELETE | Blueprint CRUD |
|
||
| `/api/councils/run` | POST | Phase-1-Run (hartcodiert) |
|
||
| `/api/councils/{id}/run` | POST | Blueprint-Run (dynamisch) |
|
||
| `/api/councils/run/{id}` | GET | Run-Status/Ergebnis |
|
||
| `/api/councils/run/{id}/approve` | POST | God Mode: Genehmigung |
|
||
| `/api/councils/run/{id}/state` | GET | God Mode: State |
|
||
| `/api/councils/upload-pdf` | POST | PDF-Upload |
|
||
| `/api/runs/` | GET | Run-Verlauf |
|
||
| `WS /ws/council/{id}` | WS | Live-Agent-Events |
|
||
|
||
---
|
||
|
||
## Schnellstart (Lokal)
|
||
|
||
```bash
|
||
# 1. Umgebungsvariablen setzen
|
||
cp .env.example .env
|
||
# → ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY eintragen
|
||
|
||
# 2. Alle Services starten
|
||
docker compose up -d
|
||
|
||
# 3. API testen
|
||
curl http://localhost:8000/api/health
|
||
# → {"status": "ok", "service": "CouncilOS API"}
|
||
|
||
# 4. Frontend öffnen
|
||
open http://localhost:3000
|
||
```
|
||
|
||
---
|
||
|
||
## Konventionen (Zusammenfassung aus CLAUDE.md)
|
||
|
||
| Bereich | Regel |
|
||
|---------|-------|
|
||
| Sprache (Code) | Englisch — Variablen, Funktionen, Commits |
|
||
| Sprache (UI) | Deutsch |
|
||
| Python-Style | PEP 8, Type Hints mandatory, ruff + black |
|
||
| Tests | LLMs immer mocken (`@patch("agents.*.ChatAnthropic")`) |
|
||
| Graph | Zyklen sind First-Class — niemals zu DAG vereinfachen |
|
||
| State | Nur `CouncilState` — keine interne Agent-State |
|
||
| Echtzeit | WebSocket für Updates — kein Polling |
|
||
| Human-in-Loop | Nur via LangGraph `interrupt_before` |
|
||
|
||
---
|
||
|
||
## BMAD Skill-Referenz
|
||
|
||
| Skill | Kommando | Artefakt |
|
||
|-------|---------|---------|
|
||
| 📊 Analyst (Mary) | `/bmad-agent-bmm-analyst` | `product-brief.md` |
|
||
| 📋 PM (John) | `/bmad-agent-bmm-pm` | `prd.md`, `epics.md` |
|
||
| 🎨 UX Designer | `/bmad-agent-bmm-ux-designer` | `ux-design.md` |
|
||
| 🏗️ Architect (Winston) | `/bmad-agent-bmm-architect` | `architecture.md`, `implementation-readiness.md` |
|
||
| 🏃 SM (Bob) | `/bmad-agent-bmm-sm` | `sprint-status.yaml`, `stories/*.md` |
|
||
| 💻 Dev (Amelia) | `/bmad-agent-bmm-dev` | Story-Implementierung |
|
||
| 🧪 QA (Quinn) | `/bmad-agent-bmm-qa` | `qa-e2e-tests.md` |
|
||
| 📚 Tech Writer (Paige) | `/bmad-agent-bmm-tech-writer` | `project-context.md` (dieses Dokument) |
|
||
| 🤖 BMAD Master | `/bmad-agent-bmad-master` | Orchestrierung |
|