---
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 |