# KAIRO-ARCH-01 – Abschlussbericht

**Status:** abgeschlossen  
**Stand:** 2026-07-05  
**Auftrag:** `docs/architecture/Kairo_Target_Architecture_Assignment_Method_Driven_Adaptive_Steering_Core_v0.2.md`  
**Ergebnis:** Zielarchitektur v0.1 (Nordstern, keine Implementierung)

---

## 1. Erstellte Dateien

| Datei | Zweck |
|-------|-------|
| `docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md` | Technische Zielarchitektur (20 Kapitel) |
| `docs/architecture/KAIRO-ARCH-01_Completion_Report_v0.1.md` | Dieser Abschlussbericht |

**Gelesene Grundlagen (alle vorhanden):**

- `docs/architecture/Kairo_Core_Model_Decision_v0.2.md`
- `docs/architecture/Kairo_Method_Design_Principles_v0.1.md`
- `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md`
- `docs/product/Kairo_Canonical_Operating_Model_v0.1.md`
- `docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md`
- `docs/architecture/Kairo_Tenant_Invariants_v0.1.md`
- `docs/sprints/Sprint0_AP0_7_Completion_Report_v0.2.md`

**Fehlende Dokumente:** keine — alle im Auftrag genannten Grundlagen waren im Repo vorhanden.

---

## 2. Wichtigste Architekturentscheidungen

| # | Entscheidung |
|---|--------------|
| 1 | **Kairo ist methodengeführter Steuerungskern**, keine freie Workflow Engine |
| 2 | **Drei Ebenen:** Steering Method → Steering Workflow (Lifecycle/Hooks) → Workflow Runtime (später) |
| 3 | **Method Registry** als zentraler Erweiterungspunkt — analog zu bestehendem Capability/Feature-Registry-Muster |
| 4 | **Hook Slugs** als stabile Einhängepunkte zwischen Core, Methoden und späteren Workflow-Fragmenten |
| 5 | **Standard Lifecycle** (12 Schritte) als gemeinsame Basis; Methoden aktivieren/spezialisieren |
| 6 | **Gemeinsame Kernstrukturen** — RoadmapItem als generisches Strukturelement (Milestone, Feature, Kapitel, Reifegradstufe) |
| 7 | **Attention/NextAction** als erklärbare Read Models im Data Layer; Signal Rule Providers methodenregistrierbar |
| 8 | **Kairo bleibt Steering Authority** — Agenten sind Actors/Provider, nicht eigenständige Steuerungsinstanzen |
| 9 | **Prompt/Workflow-Runtime bleibt eingefroren** bis Operating-Model-MVP (AP0.8–0.10) trägt |
| 10 | **Neue Schicht `backend/steering/`** — schrittweise nach AP0.8, ohne Foundation-Umbau |

---

## 3. Kritische Bewertung der fachlichen Annahmen

### 3.1 Bestätigt

Die fachliche Präferenz **„methodengeführter Steuerungskern statt freier Workflow-Baukasten“** ist aus Sicht der Codebase **tragfähig**:

- Registry-Muster (Capabilities, Features, Prompts) ist etabliert und erprobt
- Tenant/Actor/Capability-Foundation ist produktionsreif (AP0.7)
- Data Layer als Read-Schicht passt zur Attention-/Signal-Architektur
- Product Reset und Principle Gate verbieten vorzeitige Workflow/KI-Ausbauten — konsistent mit Zielarchitektur

### 3.2 Präzisiert

| Annahme | Bewertung |
|---------|-----------|
| Standard Lifecycle (12 Schritte) | Tragfähig als **generische Steuerungslogik**; UI muss fachliche Labels zeigen, nicht technische States |
| Hook Registry | Sinnvoll; Versionierung über `since_version` + Deprecation, nicht über Slug-Änderung |
| Structure Builder | Korrekt als methodenspezifische Erweiterung; **muss Domain Services nutzen**, nicht Router/SQL |
| Milestone als eigenes Objekt (AP0.8) | MVP-pragmatisch; Zielarchitektur empfiehlt **Konsolidierung zu RoadmapItem** in Phase C |
| Methoden sofort im MVP | **Nein** — erst Operating-Model-Entitäten, dann SteeringContext + erste Built-in Method |

### 3.3 Abweichung von Method Design Principles

Keine inhaltliche Abweichung. Technische Präzisierung: AP0.8 Attention startet als **globaler Rule Provider** in `data_layer/attention.py` und wird später in die Signal Engine refactored — bewusste Brücke, kein Widerspruch.

---

## 4. Empfohlene Zielarchitektur

**Kurzfassung:**

```text
Foundation (bestehend)
  + Domain Operating Model (AP0.8 → AP0.9)
  + Steering Core (Method/Hooks/Lifecycle/Signals)
  + Method Packages (Built-in)
  + später: Workflow Fragments + Runtime + Agent/LLM Nodes
```

**Kernmodell:**

```text
Initiative
  → SteeringContext (method_key, version, lifecycle_state)
    → Method Registry → Structure Builders + Strategies + Signal Rules
      → gemeinsame Strukturen (Roadmap, Backlog, Action, Blocker, Evidence, Review, …)
        → Attention / NextAction (Read Models)
          → Assignment → Waiting → Result Intake → Review → Adaptation
```

Das vollständige Dokument: `Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md`.

---

## 5. Was gegenüber der bisherigen Architektur geändert werden sollte

| Bereich | Bisher | Soll (Ziel) |
|---------|--------|-------------|
| Produktkern | Initiative → Action (flach) | Methodengeführter SteeringContext + Operating Model |
| Steuerungslogik | verstreut in Services/Data Layer | `backend/steering/` mit Registry, Lifecycle, Hooks, Signals |
| Blocker | nur Action-Status | eigenes Objekt (AP0.8) |
| Struktur | keine Roadmap/Backlog/Milestone | Operating Model + RoadmapItem-Generik |
| Attention | fehlt | Data Layer + später Signal Engine |
| Methoden | nicht modelliert | Method Registry + Built-in Methods |
| Workflow/Prompt | technisch vorhanden, eingefroren | später hook-gebundene Fragmente, nicht Produktkern |
| Milestone (AP0.8) | — | eigene Tabelle als Brücke → RoadmapItem konsolidieren |

**Was bleibt unverändert:**

- TenantContext, Actor-Modell, Capabilities, Audit-Grundlage
- Router dünn / Services Write / Data Layer Read
- Frontend Widget/View Registry
- Nummerierte Migrationen, Registry-first Capabilities

---

## 6. Risiken

| Risiko | Schwere | Hinweis |
|--------|---------|---------|
| Vorzeitige Workflow-Runtime | hoch | Operating Model MVP zuerst |
| Over-Engineering Steering-Schicht | mittel | Skeleton erst nach AP0.8 |
| Doppelmodell Milestone/RoadmapItem | mittel | ADP vor Konsolidierung |
| Lifecycle zu abstrakt für Nutzer | mittel | Fachliche UI-Labels |
| Methoden-Explosion | mittel | Built-in only, Review-Gate |
| Agenten ohne klare Authority-Grenze | hoch | Canonical Model §11 durchsetzen |

---

## 7. Offene Entscheidungen

1. **SteeringContext-Einführung** — mit AP0.9 oder als AP1.0?
2. **Milestone → RoadmapItem Migration** — Zeitpunkt und Strategie
3. **Generisches Assignment** — über Actions hinaus, wann?
4. **Scheduler für Waiting/Reminder** — Infrastruktur-Wahl
5. **Audit `actor_id`-Spalte** — Nachzug vor Agent-Integration
6. **Erste Built-in Method** — `generic_operating` vs. direkt `product_milestone_driven`?

Diese Punkte sollten als Architecture Decision Proposals vor der Steering-Core-Implementierung geklärt werden.

---

## 8. Empfehlung für den nächsten Schritt

**Nicht** sofort `backend/steering/` implementieren.

**Empfohlene Reihenfolge:**

1. **AP0.8 freigeben und umsetzen** (`Sprint0_AP0_8_Assignment_v0.1.md`) — Attention, Blocker, BacklogItem, Milestone
2. **AP0.9** — Evidence, Decision, Review, RecurringElement
3. **AP0.10** — Validierung mit realem Testvorhaben
4. **ADP:** SteeringContext-Einführung + Milestone/RoadmapItem-Strategie
5. **Danach:** `backend/steering/` Skeleton + erste Built-in Method

Die Zielarchitektur dient als **Nordstern** für AP0.8–AP0.10 und verhindert Rückfall auf reines Initiative→Action sowie vorzeitige Workflow-Engine-Arbeit.

---

*KAIRO-ARCH-01 abgeschlossen — reine Architekturarbeit, keine Code-Änderungen.*