diff --git a/docs/architecture/KAIRO-ARCH-01_Completion_Report_v0.1.md b/docs/architecture/KAIRO-ARCH-01_Completion_Report_v0.1.md new file mode 100644 index 0000000..dbadbe1 --- /dev/null +++ b/docs/architecture/KAIRO-ARCH-01_Completion_Report_v0.1.md @@ -0,0 +1,166 @@ +# 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.* diff --git a/docs/architecture/Kairo_Core_Model_Decision_v0.2.md b/docs/architecture/Kairo_Core_Model_Decision_v0.2.md new file mode 100644 index 0000000..fa2a118 --- /dev/null +++ b/docs/architecture/Kairo_Core_Model_Decision_v0.2.md @@ -0,0 +1,642 @@ +# Kairo – Core Model Decision +## v0.2 – Adaptive Steering Core mit methodengeführten Steuerungsworkflows + +**Status:** fachliche Architekturentscheidung +**Stand:** 2026-07-05 +**Ersetzt / präzisiert:** `Kairo_Universal_Steering_Engine_Decision_v0.1.md` und `Kairo_Steering_Engine_Roadmap_Discussion_v0.1.md` in Bezug auf den fachlichen Produktkern +**Zweck:** Präzisierung des Kairo-Kerns vor der technischen Zielarchitektur + +--- + +## 1. Anlass der Präzisierung + +In der bisherigen Diskussion wurde Kairo teilweise als universelle Steuerungs- und Workflow-Engine beschrieben. + +Diese Beschreibung war in der Tendenz richtig, aber noch missverständlich. + +Der Begriff „Workflow Engine“ kann technisch verstanden werden als: + +```text +Trigger → Nodes → Transitions → Runs → Step Results +``` + +Das wäre für Kairo als Produktkern zu eng und zugleich zu technisch. + +Der Nutzer meint mit „Workflow“ jedoch nicht primär eine technische Automatisierungsruntime, sondern den **fachlichen Steuerungsablauf**, nach dem ein steuerbarer Kontext aufgebaut, geführt, überprüft und weiterentwickelt wird. + +Beispielhafter Steuerungsablauf: + +```text +Ziel erfassen +→ Name / Scope definieren +→ Basismethode wählen +→ Steuerungsstruktur gemäß Methode anlegen +→ Roadmap / Backlog / WBS / Reifegradpfad / Kapitelstruktur erzeugen +→ Next Best Action ableiten +→ Actor zuweisen +→ auf Ergebnis warten +→ erinnern / eskalieren / prüfen +→ Ergebnis zurückführen +→ nächste Steuerungsentscheidung treffen +``` + +Dieser Ablauf ist tatsächlich fachlicher Kern von Kairo. + +--- + +## 2. Zentrale Entscheidung + +Kairo ist im Kern **keine freie Workflow-Plattform**. + +Kairo ist im Kern eine: + +```text +Adaptive Development Steering Platform +``` + +mit einem: + +```text +Method-driven Adaptive Steering Core +``` + +Deutsch: + +```text +methodengeführter adaptiver Steuerungskern +``` + +Dieser Kern führt steuerbare Kontexte über methodenspezifische Steuerungsabläufe. + +--- + +## 3. Was ist der Adaptive Steering Core? + +Der Adaptive Steering Core beantwortet dauerhaft: + +```text +Was wird gesteuert? +Was ist das Ziel? +Welche Methode gilt? +Welche Steuerungsstruktur braucht diese Methode? +Welche Roadmap / WBS / Backlog / Reifegradstruktur / Kapitelstruktur ist anzulegen? +Was ist der aktuelle Zustand? +Was fehlt? +Was blockiert? +Was braucht Aufmerksamkeit? +Was ist die nächste wirksame Aktion? +Wer oder welcher Agent soll handeln? +Worauf wartet Kairo? +Wann muss erinnert, eskaliert, geprüft oder neu geplant werden? +Welche Ergebnisse, Nachweise, Entscheidungen oder Reviews müssen zurückgeführt werden? +``` + +--- + +## 4. Abgrenzung zur technischen Workflow Runtime + +Es gibt drei Ebenen: + +```text +1. Steering Method + = fachliche Logik, wie ein Kontext geführt wird + +2. Steering Workflow + = methodenspezifischer Steuerungsablauf über definierte Lifecycle- und Hook-Schritte + +3. Workflow Runtime + = technische Maschine, die später Schritte, Zustände, Trigger, Wait States, Agentenaufrufe und Ergebnisse ausführt +``` + +Die technische Workflow Runtime ist wichtig, aber nicht identisch mit dem Produktkern. + +Der Produktkern ist der methodengeführte Steuerungsablauf. + +--- + +## 5. Zielmodell + +```text +Steerable Object + → Steering Context + → Steering Method + → Standard Lifecycle / Method Lifecycle + → Hook Slugs + → Structure Builder + → Signal Rules + → NextAction Strategy + → Assignment Strategy + → Waiting / Reminder / Escalation Strategy + → Result Intake + → Review / Adaptation + → optionale Workflow-Fragmente + → optionale Human / Agent / LLM / Tool Steps +``` + +--- + +## 6. Minimaler Standard Lifecycle + +Kairo benötigt einen minimalen Standard Lifecycle, der von Methoden genutzt, erweitert oder spezialisiert werden kann. + +Dieser Standard Lifecycle ist nicht als starrer Projektprozess zu verstehen, sondern als generische Steuerungslogik. + +```text +intake +method_selection +structure_setup +planning +action_selection +assignment +waiting +result_intake +validation +review +adaptation +closure +``` + +### 6.1 Intake + +Ziel, Name, Kontext und initialer Scope werden erfasst. + +Typische Hooks: + +```text +on_goal_captured +on_scope_named +on_initial_context_created +``` + +### 6.2 Method Selection + +Eine Basismethode wird gewählt oder vorgeschlagen. + +Typische Hooks: + +```text +on_method_selection_required +on_method_selected +on_method_profile_required +``` + +### 6.3 Structure Setup + +Gemäß Methode wird die Steuerungsstruktur angelegt. + +Beispiele: + +```text +Backlog +WBS +Roadmap / Meilensteinplan +Reifegradpfad +Kapitelstruktur +Feature Landscape +WorkCycles +Review Gates +``` + +Typische Hooks: + +```text +on_structure_required +on_roadmap_required +on_backlog_required +on_wbs_required +on_maturity_path_required +on_content_structure_required +on_cycle_structure_required +``` + +### 6.4 Planning + +Die nächste steuerbare Planungsebene wird konkretisiert. + +Typische Hooks: + +```text +on_plan_required +on_dependency_analysis_required +on_dod_definition_required +on_evidence_policy_required +``` + +### 6.5 Action Selection + +Kairo leitet Next Best Actions oder NextActionCandidates ab. + +Typische Hooks: + +```text +on_next_action_requested +on_attention_scan_requested +``` + +### 6.6 Assignment + +Ein Actor wird zugewiesen. + +Actors können sein: + +```text +human +agent +working_group +external_system +``` + +Typische Hooks: + +```text +on_assignment_required +on_actor_selection_required +``` + +### 6.7 Waiting + +Kairo wartet auf Ergebnis, Termin, Rückmeldung, externes Ereignis oder Statusänderung. + +Typische Hooks: + +```text +on_wait_started +on_due_date_reached +on_result_overdue +on_reminder_required +on_escalation_required +``` + +### 6.8 Result Intake + +Ein Ergebnis wird zurückgeführt. + +Typische Hooks: + +```text +on_result_received +on_actor_update_received +on_agent_result_received +``` + +### 6.9 Validation + +Ergebnis, DoD, Evidence oder Qualität werden geprüft. + +Typische Hooks: + +```text +on_dod_check_required +on_evidence_required +on_quality_gate_required +``` + +### 6.10 Review + +Ein Review, Assessment oder eine Reflexion wird ausgelöst. + +Typische Hooks: + +```text +on_review_due +on_reassessment_required +on_reflection_required +``` + +### 6.11 Adaptation + +Kairo entscheidet über Nachsteuerung. + +Typische Hooks: + +```text +on_replan_required +on_structure_update_required +on_method_adjustment_required +``` + +### 6.12 Closure + +Ein Kontext, RoadmapItem, WorkCycle, Review oder Action wird abgeschlossen. + +Typische Hooks: + +```text +on_closure_requested +on_close_allowed +on_archive_required +``` + +--- + +## 7. Methodengeführte Steuerungsworkflows + +Jede Methode definiert, wie der Standard Lifecycle genutzt wird. + +Eine Methode kann: + +```text +- Lifecycle-Schritte aktivieren/deaktivieren +- eigene Hook Slugs ergänzen +- bestimmte Steuerungsstrukturen verlangen +- bestimmte Structure Builder bereitstellen +- NextAction-Strategien definieren +- Review-/Evidence-Policies definieren +- Assignment-/Waiting-Strategien definieren +- erlaubte Workflow-Fragmente an Hooks registrieren +``` + +Beispiel: + +```text +Methode: maturity_progression + +nutzt: +- intake +- method_selection +- structure_setup +- action_selection +- assignment +- waiting +- result_intake +- validation +- review +- adaptation + +Structure Builder: +- Roadmap Lane: Reifegradstufen +- Roadmap Lane: Fähigkeiten +- Roadmap Lane: Praxis +- Roadmap Lane: Evidence +- Roadmap Lane: Reflexion + +NextAction Strategy: +- aktuellen Reifegrad bewerten +- Zielreifegrad definieren +- Gap identifizieren +- Praxisaufgabe auswählen +- Evidence sammeln +- Review durchführen +``` + +--- + +## 8. Keine beliebige freie Workflow-Konfiguration als Startpunkt + +Kairo soll langfristig konfigurierbar sein, aber nicht durch beliebige Nutzer-Workflows beliebig werden. + +Entscheidung: + +```text +Initial keine frei modellierbaren Methoden durch Nutzer. +``` + +Stattdessen: + +```text +- Built-in Methods mit method_key / slug +- definierte Hook Slugs +- definierte Structure Builder +- definierte Rule Provider +- definierte Signal Generatoren +- definierte NextAction Strategies +- definierte erlaubte Workflow-Fragmente +- später Method Profiles und konfigurierbare Bindings +``` + +--- + +## 9. Rollen der technischen Komponenten + +### 9.1 Method Registry + +Zentrales Register, in dem Methoden angemeldet werden. + +Ähnlich einem Widget-System. + +Eine Methode muss sich registrieren mit: + +```text +method_key +version +supported_domains +supported_scope_types +default_lifecycle +required_structures +allowed_structures +hook_slugs +structure_builders +signal_rules +next_action_strategy +assignment_strategy +waiting_strategy +review_strategy +evidence_policy +allowed_workflow_fragments +allowed_node_types +``` + +### 9.2 Hook Registry + +Register bekannter Hook Slugs. + +Sie dient zur Stabilisierung der Einhängepunkte. + +### 9.3 Structure Builder + +Ein Structure Builder legt methodenspezifische Steuerungsstrukturen an. + +Beispiele: + +```text +Roadmap Builder +Backlog Builder +WBS Builder +Maturity Path Builder +Chapter Structure Builder +Cycle Builder +Review Gate Builder +``` + +### 9.4 Signal Engine + +Erzeugt Attention, NextActionCandidate und später weitere Signals. + +### 9.5 Strategy Interfaces + +Methoden liefern oder referenzieren Strategien: + +```text +NextActionStrategy +AssignmentStrategy +WaitingStrategy +ReminderStrategy +EscalationStrategy +ReviewStrategy +EvidencePolicy +ClosurePolicy +``` + +### 9.6 Workflow Fragment Layer + +An Hooks können später kleinere Workflow-Fragmente eingehängt werden. + +Diese sind nicht beliebig global, sondern methoden- und hookgebunden. + +--- + +## 10. Beispiele für Methoden + +### 10.1 Produktentwicklung / Softwareentwicklung + +```text +method_key: product_milestone_driven +domain: product_development +default_lifecycle: standard_development_lifecycle + +Structures: +- Roadmap +- Feature Landscape +- Architecture Lane +- Release Lane +- Backlog +- Actions +- Blockers + +NextAction Strategy: +- wenn Roadmap fehlt → Roadmap anlegen +- wenn Feature ohne Backlog → BacklogItem erzeugen +- wenn accepted BacklogItem ohne Action → Action erstellen +- wenn Action blockiert → Blocker klären +- wenn Release at_risk → Review / Replan +``` + +### 10.2 Buchentwicklung + +```text +method_key: content_chapter_based +domain: content_development + +Structures: +- Roadmap Lane: Buchstruktur +- Roadmap Lane: Kapitel +- Roadmap Lane: Recherche +- Roadmap Lane: Review +- Backlog für Themen / Lücken / Recherchefragen +- Actions für Schreib- und Reviewaufgaben + +NextAction Strategy: +- Konzept klären +- Kapitelstruktur anlegen +- nächstes Kapitel auswählen +- Recherchebedarf erzeugen +- Draft schreiben +- Review durchführen +``` + +### 10.3 Persönliche Reifegradentwicklung + +```text +method_key: maturity_progression +domain: maturity_development + +Structures: +- Roadmap Lane: Reifegradstufen +- Roadmap Lane: Fähigkeiten +- Roadmap Lane: Praxis +- Roadmap Lane: Evidence +- Roadmap Lane: Reflexion + +NextAction Strategy: +- aktuellen Reifegrad bewerten +- Zielreifegrad definieren +- Gap identifizieren +- Übung/Praxis auswählen +- Evidence sammeln +- Review/Reassessment durchführen +``` + +### 10.4 Routine Control + +```text +method_key: recurring_control +domain: routine_operations + +Structures: +- Routine Definition +- Run Schedule +- Checklist +- Exceptions +- Review + +NextAction Strategy: +- nächster Run fällig +- Run verpasst +- Exception klären +- Routine anpassen +``` + +--- + +## 11. Konsequenz für die Zielarchitektur + +Die technische Zielarchitektur soll nicht als freie Workflow Engine beginnen. + +Sie soll den folgenden Kern entwerfen: + +```text +Target Architecture for Method-driven Adaptive Steering Core +``` + +Darin enthalten: + +```text +- Standard Lifecycle +- Method Registry +- Hook Registry +- Structure Builder Layer +- Strategy Interfaces +- Signal Engine +- NextAction Engine +- Assignment / Waiting / Reminder / Escalation Layer +- Result Intake +- Review / Adaptation Layer +- Workflow Fragment Model +- Agent / LLM / Tool Provider Integration +``` + +--- + +## 12. Kernaussage + +Kairo ist nicht einfach: + +```text +Roadmap Tool +Projektmanagement Tool +Workflow Engine +Agentenplattform +``` + +Kairo ist: + +```text +eine adaptive, methodengeführte Entwicklungs- und Steuerungsplattform. +``` + +Der Kern ist: + +```text +Adaptive Steering Core +``` + +mit: + +```text +methodengeführten Steuerungsworkflows +definierten Hook Slugs +registrierbaren Methoden +zentralen gemeinsamen Strukturen +später konfigurierbaren Method Profiles +``` + diff --git a/docs/architecture/Kairo_Method_Design_Principles_v0.1.md b/docs/architecture/Kairo_Method_Design_Principles_v0.1.md new file mode 100644 index 0000000..7e0eb8b --- /dev/null +++ b/docs/architecture/Kairo_Method_Design_Principles_v0.1.md @@ -0,0 +1,590 @@ +# Kairo – Method Design Principles +## v0.1 – Designprinzipien für registrierbare Steuerungsmethoden + +**Status:** verbindlicher Architektur- und Methodendesign-Entwurf +**Stand:** 2026-07-05 +**Zweck:** Definition der Designprinzipien, nach denen Kairo-Methoden künftig entwickelt, registriert, erweitert und versioniert werden. + +--- + +## 1. Ziel + +Kairo soll im Lauf der Zeit viele unterschiedliche Steuerungsmethoden unterstützen, ohne dass für jede Methode der komplette Codekern angepasst werden muss. + +Methoden sollen sich ähnlich wie Widgets an einem klaren Abstraktionslayer anmelden können. + +Die Architektur muss ermöglichen: + +```text +- neue Methoden hinzufügen +- bestehende Methoden versionieren +- methodenspezifische Steuerungsstrukturen erzeugen +- methodenspezifische NextAction-Logik einhängen +- methodenspezifische Review-/Evidence-Logik einhängen +- später Method Profiles konfigurieren +- später Workflow-Fragmente an Hooks binden +- später Agent/LLM/Tool-Steps pro Methode erlauben +``` + +Gleichzeitig darf die Methodenarchitektur nicht beliebig und untestbar werden. + +--- + +## 2. Grundprinzip + +Eine Kairo-Methode ist kein Label. + +Eine Kairo-Methode ist ein registriertes Steuerungspaket. + +Sie beschreibt: + +```text +- für welche Domains sie gilt +- welche Scope Types sie steuern kann +- welchen Standard Lifecycle sie nutzt oder erweitert +- welche Steuerungsstrukturen sie benötigt +- welche Hook Slugs sie unterstützt +- welche Structure Builder sie bereitstellt +- welche Signal Rules sie registriert +- welche NextAction Strategy sie nutzt +- welche Assignment / Waiting / Reminder / Escalation Strategy sie nutzt +- welche Review- und Evidence-Policies gelten +- welche Workflow-Fragmente später erlaubt sind +- welche Node Types später erlaubt sind +``` + +--- + +## 3. Method Registry als zentraler Erweiterungspunkt + +Alle Methoden registrieren sich in einer zentralen Method Registry. + +Zielbild: + +```text +backend/steering/methods/registry.py +``` + +Beispielhafte Registrierung: + +```python +register_method( + MethodDefinition( + method_key="maturity_progression", + version="v1", + label="Maturity Progression", + supported_domains=["maturity_development", "personal_development"], + supported_scope_types=["initiative", "roadmap_item", "action"], + default_lifecycle="standard_development_lifecycle", + required_structures=["roadmap", "roadmap_lanes", "roadmap_items", "backlog", "actions"], + hook_slugs=[ + "on_goal_captured", + "on_structure_required", + "on_maturity_path_required", + "on_next_action_requested", + "on_evidence_required", + "on_review_due", + "on_reassessment_required", + ], + structure_builders=[ + "maturity_path_builder", + "practice_backlog_builder", + ], + signal_rule_providers=[ + "maturity_gap_attention_rules", + "evidence_required_rules", + ], + next_action_strategy="maturity_next_action_strategy", + assignment_strategy="default_actor_assignment_strategy", + waiting_strategy="default_waiting_strategy", + review_strategy="maturity_review_strategy", + evidence_policy="maturity_evidence_policy", + allowed_node_types=[ + "human_task", + "evidence_check", + "review", + "reflection", + "llm_prompt", + "agent_task", + ], + ) +) +``` + +--- + +## 4. Built-in zuerst, konfigurierbar später + +Die Methodenarchitektur folgt einem Stufenmodell. + +### Stufe 1 – Built-in Methods + +```text +- Methoden code-seitig definiert +- klare Slugs +- testbar +- keine freie Nutzerkonfiguration +``` + +### Stufe 2 – Built-in Method Profiles + +```text +- vordefinierte Profile pro Methode +- z. B. "einfach", "evidence_strict", "review_driven" +``` + +### Stufe 3 – Tenant Method Profiles + +```text +- tenant-spezifische Konfiguration +- begrenzte Parameter +- keine freie Ausführungslogik +``` + +### Stufe 4 – Workflow Bindings an Hooks + +```text +- kleine Workflow-Fragmente an definierte Hooks +- nur erlaubte Node Types +- nur innerhalb Method Governance +``` + +### Stufe 5 – Method Designer + +```text +- spätere UI +- nur für fortgeschrittene Nutzung +- Governance, Tests und Freigaben erforderlich +``` + +--- + +## 5. Zentrale gemeinsame Strukturen + +Alle Methoden müssen auf gemeinsamen Kairo-Strukturen aufbauen. + +Gemeinsame Kernstrukturen: + +```text +SteeringContext +Roadmap +RoadmapLane +RoadmapItem +BacklogItem +Action +ActionAssignment +Blocker +Signal +AttentionItem +NextActionCandidate +Evidence +Review +Decision +Actor +Capability +AuditEvent +``` + +Eine Methode darf keine parallelen Kernmodelle erfinden. + +Beispiele: + +```text +Meilenstein = RoadmapItem(type = milestone) +Reifegrad = RoadmapItem(type = maturity_stage) +Feature = RoadmapItem(type = feature) +Kapitel = RoadmapItem(type = chapter) +Sprint-Grobplanung = RoadmapItem(type = work_cycle) +``` + +--- + +## 6. Minimaler Standard Lifecycle + +Alle Methoden basieren auf einem gemeinsamen minimalen Lifecycle. + +```text +intake +method_selection +structure_setup +planning +action_selection +assignment +waiting +result_intake +validation +review +adaptation +closure +``` + +Eine Methode darf: + +```text +- Schritte auslassen +- Schritte spezialisieren +- zusätzliche Hook Slugs ergänzen +- eigene Structure Builder an bestimmten Schritten registrieren +``` + +Eine Methode darf nicht: + +```text +- Tenant-Sicherheit umgehen +- eigene Actor-Logik außerhalb des Actor-Modells einführen +- eigene Rechteprüfung außerhalb der Capability-Schicht einführen +- persistente Kernobjekte ohne Service-/Audit-Schicht verändern +``` + +--- + +## 7. Hook Slugs + +Hook Slugs sind stabile Einhängepunkte. + +Sie sind die Hauptabstraktion, über die Methoden erweitert werden. + +Beispiele: + +```text +on_goal_captured +on_method_selection_required +on_method_selected +on_structure_required +on_roadmap_required +on_backlog_required +on_wbs_required +on_maturity_path_required +on_content_structure_required +on_plan_required +on_dependency_analysis_required +on_dod_definition_required +on_next_action_requested +on_assignment_required +on_wait_started +on_due_date_reached +on_result_overdue +on_reminder_required +on_escalation_required +on_result_received +on_dod_check_required +on_evidence_required +on_quality_gate_required +on_review_due +on_reassessment_required +on_reflection_required +on_replan_required +on_structure_update_required +on_closure_requested +``` + +Hook Slugs müssen: + +```text +- eindeutig sein +- versionierbar bleiben +- fachlich benannt sein +- in Method Definitions referenziert werden +- in Signals als Ursache auftauchen können +- später Workflow Bindings tragen können +``` + +--- + +## 8. Structure Builder + +Structure Builder legen die methodenspezifische Steuerungsstruktur an. + +Beispiele: + +```text +roadmap_builder +milestone_plan_builder +feature_landscape_builder +wbs_builder +backlog_builder +maturity_path_builder +chapter_structure_builder +cycle_structure_builder +review_gate_builder +routine_structure_builder +``` + +Ein Structure Builder darf: + +```text +- Roadmaps anlegen +- RoadmapLanes anlegen +- RoadmapItems anlegen +- initiale BacklogItems vorschlagen oder erzeugen +- methodenspezifische Startstruktur erzeugen +``` + +Ein Structure Builder darf nicht: + +```text +- ungeprüft produktive Actions erzeugen, wenn ein Gate vorgesehen ist +- Actors ohne Assignment Strategy zuweisen +- Tenant-Kontext aus Client Input übernehmen +- Rechteprüfung umgehen +``` + +--- + +## 9. Strategies + +Methoden nutzen austauschbare Strategies. + +Wichtige Strategy Interfaces: + +```text +NextActionStrategy +AttentionRuleProvider +AssignmentStrategy +WaitingStrategy +ReminderStrategy +EscalationStrategy +ResultIntakeStrategy +EvidencePolicy +ReviewStrategy +ClosurePolicy +``` + +Diese Strategies sind zentrale Erweiterungspunkte. + +Sie verhindern, dass methodenspezifische Logik monolithisch in Services oder Data Layer wächst. + +--- + +## 10. Signal Rules + +Signal Rules erzeugen AttentionItems und NextActionCandidates. + +Sie müssen erklären können: + +```text +- warum ein Signal erzeugt wurde +- welcher Hook relevant ist +- welche Methode/Domain beteiligt ist +- welcher Scope betroffen ist +- welche Datenquelle genutzt wurde +- welche nächste Handlung empfohlen wird +``` + +Signal Rules müssen tenant-sicher sein und dürfen nicht quer über Tenants lesen. + +--- + +## 11. Method Definition Contract + +Eine MethodDefinition sollte mindestens enthalten: + +```text +method_key +version +label +description +supported_domains +supported_scope_types +default_lifecycle +required_structures +allowed_structures +hook_slugs +structure_builders +attention_rule_providers +next_action_strategy +assignment_strategy +waiting_strategy +reminder_strategy +escalation_strategy +result_intake_strategy +review_strategy +evidence_policy +closure_policy +allowed_workflow_fragments +allowed_node_types +default_configuration +``` + +--- + +## 12. Method Versioning + +Methoden müssen versionierbar sein. + +Regeln: + +```text +- method_key bleibt stabil +- version beschreibt fachliche/technische Methode +- bestehende SteeringContexts referenzieren method_key + version +- neue Versionen dürfen bestehende Kontexte nicht stillschweigend verändern +- Migration oder Upgrade muss explizit sein +``` + +--- + +## 13. Method Profiles + +Method Profiles sind spätere konkrete Konfigurationen. + +Sie dürfen Parameter anpassen, aber nicht den Kairo-Kern umgehen. + +Beispiele: + +```text +maturity_progression.basic +maturity_progression.evidence_strict +content_chapter_based.light_review +product_milestone_driven.release_focused +routine_control.escalation_strict +``` + +Ein Method Profile darf z. B. konfigurieren: + +```text +- welche Hooks aktiv sind +- welche Review-Frequenz gilt +- ob Evidence erforderlich ist +- welche Reminder-Strategie gilt +- welche Node Types erlaubt sind +- ob Agent Steps erlaubt sind +``` + +Ein Method Profile darf nicht: + +```text +- beliebigen Code ausführen +- Tenant-Sicherheit umgehen +- Capabilities außer Kraft setzen +- systemgeschützte Hooks überschreiben +``` + +--- + +## 14. Methodenbeispiele + +### 14.1 product_milestone_driven + +```text +Domain: +- product_development +- project + +Structures: +- Roadmap +- Feature Lane +- Architecture Lane +- Release Lane +- Backlog +- Actions +- Blockers + +Primary Hooks: +- on_goal_captured +- on_roadmap_required +- on_backlog_required +- on_next_action_requested +- on_review_due +``` + +### 14.2 content_chapter_based + +```text +Domain: +- content_development + +Structures: +- Roadmap +- Chapter Lane +- Research Lane +- Draft Lane +- Review Lane +- Backlog +- Actions + +Primary Hooks: +- on_content_structure_required +- on_next_action_requested +- on_review_due +``` + +### 14.3 maturity_progression + +```text +Domain: +- maturity_development +- personal_development + +Structures: +- Roadmap +- Maturity Stage Lane +- Capability Lane +- Practice Lane +- Evidence Lane +- Reflection Lane + +Primary Hooks: +- on_maturity_path_required +- on_evidence_required +- on_review_due +- on_reassessment_required +``` + +### 14.4 wbs_driven + +```text +Domain: +- project +- program + +Structures: +- WBS Roadmap +- Work Package Items +- Dependencies +- Backlog +- Actions + +Primary Hooks: +- on_wbs_required +- on_dependency_analysis_required +- on_next_action_requested +``` + +--- + +## 15. Designprinzipien kurz + +```text +1. Methoden sind registrierte Steuerungspakete, keine Labels. +2. Neue Methoden melden sich an einer Registry an. +3. Alle Methoden nutzen gemeinsame Kairo-Kernstrukturen. +4. Der Standard Lifecycle ist die gemeinsame Basis. +5. Erweiterung erfolgt über Hook Slugs, Structure Builder und Strategies. +6. Built-in Methods kommen vor freier Konfiguration. +7. Profiles konfigurieren, aber ersetzen nicht den Kern. +8. Signals müssen erklärbar und tenant-sicher sein. +9. Agenten und LLMs sind spätere Step Provider, nicht Methoden selbst. +10. Keine Methode darf Capabilities, TenantContext oder Actor-Modell umgehen. +``` + +--- + +## 16. Konsequenz für die technische Zielarchitektur + +Die technische Zielarchitektur muss diese Methodendesign-Prinzipien als verbindlich übernehmen. + +Insbesondere muss sie definieren: + +```text +- Method Registry +- Hook Registry +- MethodDefinition Contract +- Standard Lifecycle +- Structure Builder Interfaces +- Strategy Interfaces +- Signal Rule Provider Interfaces +- Method Versioning +- Method Profiles als spätere Konfigurationsebene +``` + diff --git a/docs/architecture/Kairo_Target_Architecture_Assignment_Method_Driven_Adaptive_Steering_Core_v0.2.md b/docs/architecture/Kairo_Target_Architecture_Assignment_Method_Driven_Adaptive_Steering_Core_v0.2.md new file mode 100644 index 0000000..3be2d63 --- /dev/null +++ b/docs/architecture/Kairo_Target_Architecture_Assignment_Method_Driven_Adaptive_Steering_Core_v0.2.md @@ -0,0 +1,387 @@ +# KAIRO-ARCH-01 – Zielarchitektur für den methodengeführten adaptiven Steuerungskern +## v0.2 – schlanker Architekturauftrag + +**Status:** Auftrag an Coding-/Architektur-Agent +**Ziel:** technische Zielarchitektur, keine Implementierung +**Wichtig:** Dieser Auftrag ersetzt die überdetaillierte Fassung `v0.1` als führenden Prompt. + +--- + +## 1. Kontext + +Kairo soll langfristig keine einfache Aufgaben-, Projekt- oder Roadmap-App sein. + +Kairo soll eine adaptive, methodengeführte Entwicklungs- und Steuerungsplattform werden. + +Der bisherige Slice `Initiative → Action` ist als technischer Startpunkt gültig, aber als Zielarchitektur zu flach. + +Kairo soll unterschiedliche Arten von Entwicklungen steuern können, z. B.: + +- Software- und Produktentwicklung +- Buchentwicklung +- Programm- und Initiativensteuerung +- persönliche Entwicklung +- Reifegradentwicklung +- Routinen / Betrieb +- Review- und Auditkontexte +- später auch KI-/Agenten-gestützte Steuerung + +--- + +## 2. Verbindliche fachliche Grundlagen + +Lies zuerst: + +```text +docs/architecture/Kairo_Core_Model_Decision_v0.2.md +docs/architecture/Kairo_Method_Design_Principles_v0.1.md +``` + +Berücksichtige zusätzlich den bestehenden Produkt- und Architekturstand im Repo, insbesondere: + +```text +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 +``` + +Falls Dokumente fehlen, liste sie im Abschlussbericht auf und arbeite mit den vorhandenen Grundlagen weiter. + +--- + +## 3. Ziel dieses Auftrags + +Erarbeite eine technische Zielarchitektur für Kairo als: + +```text +Method-driven Adaptive Steering Platform +``` + +Es geht ausdrücklich nicht um die nächste Implementierung, nicht um AP0.8 und nicht um MVP-Minimierung. + +Es geht um den technischen Nordstern: + +```text +Wie muss Kairo grundsätzlich aufgebaut sein, damit unterschiedliche Steuerungsmethoden langfristig ergänzt, weiterentwickelt, konfiguriert und ausgeführt werden können, ohne den Core ständig umzubauen? +``` + +--- + +## 4. Fachliche Kernanforderung + +Die Zielarchitektur muss erklären, wie Kairo diesen methodengeführten Steuerungsablauf unterstützt: + +```text +1. Ziel / Entwicklungsabsicht erfassen +2. Name, Scope und Kontext definieren +3. passende Basismethode wählen oder vorschlagen +4. gemäß Methode eine Steuerungsstruktur erzeugen + - z. B. Roadmap, Backlog, WBS, Reifegradpfad, Kapitelstruktur, WorkCycles +5. Next Best Action ableiten +6. Actor zuweisen + - human, agent, working_group oder external_system +7. auf Ergebnis, Rückmeldung, Termin oder Ereignis warten +8. erinnern, eskalieren oder nachsteuern +9. Ergebnis zurückführen +10. prüfen, reviewen, adaptieren oder abschließen +``` + +Dieser Ablauf ist als methodengeführter Steuerungsworkflow zu verstehen, nicht als freie generische Automatisierungsplattform. + +--- + +## 5. Kritische Leitfrage + +Prüfe und beantworte kritisch: + +```text +Soll Kairo im Kern eine freie Workflow Engine sein, +oder ein methodengeführter adaptiver Steuerungskern, +an den später Workflow-Fragmente, Agenten, LLMs und Tools angebunden werden können? +``` + +Die fachliche Präferenz lautet: + +```text +Kairo soll kein freier Workflow-Baukasten sein. +Kairo soll einen methodengeführten Steuerungskern haben. +Methoden sollen sich wie registrierbare Erweiterungen anmelden können. +Hooks sind stabile Einhängepunkte. +Workflow-Fragmente, Agenten, LLMs und Tools werden später an diese Hooks gebunden. +``` + +Bestätige diese Präferenz nur, wenn sie aus Sicht der bestehenden Codebase und Architektur tragfähig ist. Falls eine bessere Zielarchitektur naheliegt, beschreibe und begründe sie. + +--- + +## 6. Erwartete Architekturfragen + +Entwickle eine Zielarchitektur zu folgenden Fragen. + +### 6.1 Core-Verantwortung + +Was ist der stabile Kairo-Core? + +Welche Verantwortung gehört in den Core, welche in Methoden, welche in spätere Workflow-/Agenten-/Provider-Schichten? + +### 6.2 Methoden-Erweiterbarkeit + +Wie können neue Methoden ergänzt werden, ohne den Core jedes Mal umzubauen? + +Berücksichtige fachlich: + +```text +Method Registry +Method Definition +Method Versioning +Method Profiles +Hook Slugs +Structure Builder +Strategies +Signal Rules +``` + +Du musst diese Begriffe nicht exakt übernehmen, wenn die bestehende Architektur eine bessere Lösung nahelegt. Wichtig ist die Fähigkeit: Methoden müssen registrierbar, versionierbar, testbar und später begrenzt konfigurierbar sein. + +### 6.3 Gemeinsame Kernstrukturen + +Welche zentralen Strukturen brauchen alle oder die meisten Methoden? + +Zu prüfen sind insbesondere: + +```text +Steering Context +Roadmap / Roadmap Items +Backlog +Actions / Assignments +Blocker +Signals / Attention / NextAction +Evidence +Reviews +Decisions +Waiting / Reminder / Escalation +``` + +Entscheide, welche davon Core-Strukturen sind und welche methodenspezifisch bleiben sollten. + +### 6.4 Minimaler Standard Lifecycle + +Prüfe, ob ein minimaler Standard Lifecycle als gemeinsame Basis sinnvoll ist. + +Fachlicher Vorschlag: + +```text +intake +method_selection +structure_setup +planning +action_selection +assignment +waiting +result_intake +validation +review +adaptation +closure +``` + +Bewerte: + +```text +Ist dieser Lifecycle als Basismodell tragfähig? +Welche Teile gehören in den Core? +Welche Teile sollten Methoden überschreiben oder spezialisieren können? +Wie lassen sich Softwareentwicklung, Buchentwicklung und Reifegradentwicklung damit abbilden? +``` + +### 6.5 Hooks und Steuerungsabläufe + +Wie sollten Hooks technisch modelliert werden? + +Hooks sollen stabile Einhängepunkte sein, z. B.: + +```text +on_goal_captured +on_method_selected +on_structure_required +on_next_action_requested +on_assignment_required +on_wait_started +on_result_received +on_evidence_required +on_review_due +on_replan_required +on_closure_requested +``` + +Prüfe: + +```text +Soll es eine Hook Registry geben? +Wie werden Hooks versioniert? +Wie registrieren Methoden Logik an Hooks? +Wie werden spätere Workflow-Fragmente angebunden? +Wie bleibt das testbar und erklärbar? +``` + +### 6.6 Structure Builder + +Methoden müssen unterschiedliche Steuerungsstrukturen erzeugen können: + +```text +Roadmap / Meilensteinplan +Backlog +WBS +Reifegradpfad +Kapitelstruktur +Feature Landscape +WorkCycles +Review Gates +``` + +Entwirf eine Architektur, wie solche Structure Builder methodenspezifisch, aber core-kompatibel eingebunden werden können. + +### 6.7 Signals und Next Best Action + +Kairo muss methodenspezifisch ableiten können: + +```text +Was braucht Aufmerksamkeit? +Was ist der nächste wirksame Schritt? +``` + +Beschreibe die Zielarchitektur für: + +```text +Attention +NextActionCandidates +Signal Rules +methodenspezifische Strategien +Erklärbarkeit +Ranking / Priorisierung später +``` + +### 6.8 Assignment, Waiting, Reminder und Escalation + +Der Steuerungskern darf nicht bei „Action erzeugt“ enden. + +Er muss abbilden können: + +```text +Actor zuweisen +auf Ergebnis warten +Fälligkeit überwachen +erinnern +eskalieren +externe Ereignisse oder Agentenergebnisse aufnehmen +``` + +Beschreibe, welche Architektur dafür langfristig nötig ist. + +### 6.9 Workflow-Fragmente und spätere Runtime + +Beschreibe die Rolle einer späteren technischen Workflow Runtime. + +Wichtig: + +```text +Die Runtime soll methodengeführte Steuerungsabläufe unterstützen. +Sie soll nicht als beliebiger freier Workflow-Baukasten den Kairo-Core ersetzen. +``` + +Kläre: + +```text +Was ist Core-Logik? +Was ist Methode? +Was ist Hook? +Was ist Workflow-Fragment? +Was ist spätere Runtime? +Wie werden LLM-/Agent-/Tool-Steps angebunden? +``` + +### 6.10 Agenten, LLMs und Tools + +Kairo soll später Agenten, LLMs und Tools nutzen können. + +Kläre: + +```text +Bleibt Kairo Steering Authority? +Sind Agenten Provider oder eigenständige Steuerungsinstanzen? +Wie werden Agenten als Actors eingebunden? +Wie werden Ergebnisse zurückgeführt? +Wie werden Freigaben, Audit und Fehler behandelt? +``` + +--- + +## 7. Erwartetes Ergebnis + +Erstelle ein Architektur-Dokument: + +```text +docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md +``` + +Das Dokument soll eine konsistente Zielarchitektur darstellen, keine bloße Checkliste. + +Es soll mindestens enthalten: + +```markdown +# Kairo Target Architecture – Method-driven Adaptive Steering Core v0.1 + +## 1. Executive Summary +## 2. Fachliches Zielbild +## 3. Bewertung: Workflow Engine vs. methodengeführter Steuerungskern +## 4. Zielarchitektur im Überblick +## 5. Core-Verantwortung und Abgrenzung +## 6. Methodenarchitektur und Erweiterbarkeit +## 7. Standard Lifecycle und Hooks +## 8. Structure Builder +## 9. Gemeinsame Kernstrukturen +## 10. Roadmap, Backlog, Action und Blocker +## 11. Signals, Attention und Next Best Action +## 12. Assignment, Waiting, Reminder und Escalation +## 13. Workflow-Fragmente und spätere Runtime +## 14. Agenten-, LLM- und Tool-Integration +## 15. Datenmodell-Zielbild +## 16. Modul-/Schichten-Zielbild +## 17. Security, Tenant, Actor, Governance und Audit +## 18. Architekturentscheidungen +## 19. Risiken und offene Fragen +## 20. Empfohlene nächste Schritte +``` + +--- + +## 8. Abschlussbericht + +Liefere zusätzlich einen Abschlussbericht: + +```markdown +# KAIRO-ARCH-01 – Abschlussbericht + +## 1. Erstellte Dateien +## 2. Wichtigste Architekturentscheidungen +## 3. Kritische Bewertung der fachlichen Annahmen +## 4. Empfohlene Zielarchitektur +## 5. Was gegenüber der bisherigen Architektur geändert werden sollte +## 6. Risiken +## 7. Offene Entscheidungen +## 8. Empfehlung für den nächsten Schritt +``` + +--- + +## 9. Arbeitsregel + +Nicht vorschnell implementierungsnah werden. + +Nutze deine Kenntnis der bestehenden Codebase und Architektur. + +Wenn die fachlichen Vorgaben mit der bestehenden technischen Architektur kollidieren, benenne das ausdrücklich und schlage eine bessere Lösung vor. + +Es geht um eine tragfähige Zielarchitektur, nicht um das Abarbeiten einer überdetaillierten Vorgabenliste. diff --git a/docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md b/docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md new file mode 100644 index 0000000..bec294c --- /dev/null +++ b/docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md @@ -0,0 +1,1003 @@ +# Kairo Target Architecture – Method-driven Adaptive Steering Core v0.1 + +**Status:** Zielarchitektur (Nordstern) +**Stand:** 2026-07-05 +**Auftrag:** KAIRO-ARCH-01 (`Kairo_Target_Architecture_Assignment_Method_Driven_Adaptive_Steering_Core_v0.2.md`) +**Grundlagen:** `Kairo_Core_Model_Decision_v0.2.md`, `Kairo_Method_Design_Principles_v0.1.md`, Canonical Operating Model, Tenant-Invarianten, Codebase AP0.7 + +--- + +## 1. Executive Summary + +Kairo ist langfristig **keine freie Workflow-Engine** und **kein To-do-Tool**. Kairo ist eine **methodengeführte adaptive Entwicklungs- und Steuerungsplattform** mit einem stabilen **Adaptive Steering Core**. + +Der Core beantwortet dauerhaft die Leitfrage: + +> Welcher nächste Schritt bringt ein Vorhaben aktuell am wirkungsvollsten voran? + +Die technische Zielarchitektur trennt drei Ebenen: + +| Ebene | Rolle | +|-------|-------| +| **Steering Method** | Fachliche Logik, wie ein steuerbarer Kontext geführt wird | +| **Steering Workflow** | Methodenspezifischer Steuerungsablauf über Lifecycle- und Hook-Schritte | +| **Workflow Runtime** | Spätere technische Maschine für Wait States, Agentenaufrufe, Tool-Steps | + +Der **Ist-Stand (AP0.7)** liefert eine tragfähige Foundation: Tenant/Actor/Capabilities, Registry-Muster, Data Layer, Audit. Der Fachkern ist noch flach (`Initiative → Action → Assignment`). Der methodengeführte Steuerungskern existiert als Architekturentscheidung, noch nicht als Code. + +**Kernentscheidung:** Methoden registrieren sich als Steuerungspakete an einer **Method Registry**. Der Core stellt gemeinsame Strukturen, Standard Lifecycle, Hook Slugs und Strategy-Interfaces bereit. Methoden liefern Structure Builder, Signal Rules und Strategien. Workflow-Fragmente, Agenten und LLMs werden **später** an stabile Hooks gebunden — nicht als Ersatz für den Core. + +**Empfohlener Weg:** Zuerst Operating-Model-Entitäten und Attention-Schicht (AP0.8 ff.), dann schrittweise Einführung der `backend/steering/`-Schicht — ohne vorzeitige Workflow-Runtime oder KI-Ausbau. + +--- + +## 2. Fachliches Zielbild + +Kairo soll unterschiedliche Arten von Entwicklung und Steuerung tragen können: + +- Software- und Produktentwicklung +- Buchentwicklung +- Programm- und Initiativensteuerung +- persönliche Entwicklung +- Reifegradentwicklung +- Routinen / Betrieb +- Review- und Auditkontexte +- später KI-/Agenten-gestützte Steuerung + +Der methodengeführte Steuerungsablauf: + +```text +1. Ziel / Entwicklungsabsicht erfassen +2. Name, Scope und Kontext definieren +3. passende Basismethode wählen oder vorschlagen +4. gemäß Methode Steuerungsstruktur erzeugen + (Roadmap, Backlog, WBS, Reifegradpfad, Kapitelstruktur, WorkCycles) +5. Next Best Action ableiten +6. Actor zuweisen (human, agent, working_group, external_system) +7. auf Ergebnis, Rückmeldung, Termin oder Ereignis warten +8. erinnern, eskalieren oder nachsteuern +9. Ergebnis zurückführen +10. prüfen, reviewen, adaptieren oder abschließen +``` + +Dieser Ablauf ist **fachlicher Produktkern**, nicht beliebige Automatisierung. Er mappt auf das kanonische Operating Model (Capture → Triage → Structure → Commit → Execute → Verify → Review → Adapt → Next Action), wird aber technisch über **Lifecycle + Hooks + Methoden** modelliert — nicht über frei konfigurierbare Node-Graphen. + +**Steerable Object:** Ein steuerbarer Kontext beginnt typischerweise als **Initiative** (Vorhaben) und wird durch einen **SteeringContext** methodengeführt. Project, Milestone, BacklogItem, Action usw. sind Strukturen innerhalb dieses Kontexts — keine parallelen Welten pro Methode. + +--- + +## 3. Bewertung: Workflow Engine vs. methodengeführter Steuerungskern + +### 3.1 Kritische Leitfrage + +**Soll Kairo im Kern eine freie Workflow Engine sein, oder ein methodengeführter adaptiver Steuerungskern?** + +**Antwort: methodengeführter Steuerungskern** — bestätigt und aus Codebase-Sicht tragfähig. + +### 3.2 Begründung + +| Kriterium | Freie Workflow Engine | Methodengeführter Steuerungskern | +|-----------|----------------------|-----------------------------------| +| Produktidentität | Generische Automatisierung | Program Director, methodengeführt | +| Erklärbarkeit | Runs/Nodes schwer fachlich zu erklären | Hooks + Methoden + Signals erklärbar | +| Testbarkeit | Kombinatorische Explosion | Registrierte Methoden, deterministische Rules (AP0.8-Vorbild) | +| Tenant/Actor-Sicherheit | Risiko ad-hoc-Logik in Nodes | Capabilities + Services bleiben zentral | +| Bestehende Codebase | Prompt-Registry hat `workflow`-Modus — **eingefroren** | Registry-Muster (Capabilities, Features) bereits etabliert | +| MVP-Roadmap | Würde Operating Model überspringen | AP0.8–AP0.10 bauen Strukturen vor Runtime | + +Die vorhandene Prompt-Infrastruktur (`execution_mode: workflow`) ist technische Vorleistung (AP0.4), **kein Produktkern**. Product Direction verbietet weiteren Prompt/KI/MCP-Ausbau, bis der Operating-Model-MVP trägt. + +### 3.3 Abgrenzung + +```text +NICHT Kern: Trigger → beliebige Nodes → freie Transitions → Runs +KERN: Steerable Object → Method → Lifecycle → Hooks → Strategies → gemeinsame Strukturen +SPÄTER: Hook-gebundene Workflow-Fragmente → Human/Agent/LLM/Tool Steps +``` + +--- + +## 4. Zielarchitektur im Überblick + +```mermaid +flowchart TB + subgraph ui [Presentation Layer] + Views[View Registry] + Widgets[Widget Registry] + end + + subgraph api [API Layer] + Routers[Thin Routers] + end + + subgraph steering [Steering Core — Ziel] + SC[SteeringContext Service] + LC[Lifecycle Orchestrator] + MR[Method Registry] + HR[Hook Registry] + SE[Signal Engine] + NAE[NextAction Engine] + end + + subgraph methods [Method Packages] + MD[Method Definitions] + SB[Structure Builders] + SR[Signal Rule Providers] + ST[Strategies] + end + + subgraph domain [Domain Layer] + SVC[Domain Services — Write] + DL[Data Layer — Read] + end + + subgraph foundation [Foundation] + TC[TenantContext] + ACT[Actors] + CAP[Capabilities] + AUD[Audit] + end + + subgraph runtime [Spätere Runtime] + WF[Workflow Fragments] + AG[Agent/LLM/Tool Providers] + end + + ui --> Routers + Routers --> TC + Routers --> CAP + Routers --> SVC + Routers --> DL + Routers --> steering + + SC --> MR + LC --> HR + LC --> MR + SE --> SR + NAE --> ST + MR --> MD + MD --> SB + MD --> SR + MD --> ST + + SB --> SVC + ST --> SVC + SE --> DL + NAE --> DL + + HR -.-> WF + WF -.-> AG + + SVC --> foundation + DL --> foundation + steering --> foundation +``` + +**Schichtenprinzip:** + +- **Router:** HTTP, Auth, Capability-Gate, Delegation — keine Aggregations-SQL, keine Steuerungslogik +- **Steering Core:** Lifecycle, Methoden-Auflösung, Hook-Dispatch, Signal-/NextAction-Orchestrierung +- **Domain Services:** Persistenz, Validierung, Audit für Kernobjekte +- **Data Layer:** Read Models (Workspace, Attention, NextActionCandidates) +- **Method Packages:** Registrierte Erweiterungen — keine parallelen Domänenmodelle + +--- + +## 5. Core-Verantwortung und Abgrenzung + +### 5.1 Stabiler Kairo-Core + +Der Core ist **mandantenfähig, actor-first und registry-first**. Er umfasst: + +| Verantwortung | Core | Methode | Spätere Runtime | +|---------------|------|---------|-----------------| +| TenantContext, Auth, Sessions | ✓ | — | — | +| Actors (human/agent/working_group/external_system) | ✓ | — | — | +| Capabilities, Entitlements, Audit | ✓ | — | — | +| Gemeinsame persistente Strukturen | ✓ | nutzt | liest/schreibt via Services | +| SteeringContext (method_key, version, lifecycle_state) | ✓ | referenziert | — | +| Standard Lifecycle (Zustandsmodell) | ✓ | erweitert/skippt Schritte | — | +| Hook Registry (stabile Slugs) | ✓ | bindet Handler | bindet Fragmente | +| Method Registry (Definition Contract) | ✓ | registriert | — | +| Hook Dispatch / Lifecycle Orchestrator | ✓ | liefert Logik | führt Steps aus | +| Signal Engine (Attention, NextAction) | ✓ | liefert Rules/Strategies | — | +| Domain Services (CRUD, Invarianten) | ✓ | ruft via Builder/Strategy | — | +| Data Layer (Read Models) | ✓ | speist Rules | — | +| Structure Builder **Interface** | ✓ | implementiert | — | +| Strategy **Interfaces** | ✓ | implementiert | — | +| Workflow-Fragment-Ausführung | — | erlaubt Typen | ✓ | +| LLM/Agent/Tool-Aufrufe | — | erlaubt Node Types | ✓ | +| Freie Nutzer-Workflow-Definition | — | — | ✗ (nicht Ziel) | + +### 5.2 Was nicht in den Core gehört + +- Methodenspezifische Fachlogik (z. B. Reifegrad-Gap-Berechnung) +- Konkrete Structure-Layouts (Kapitel vs. Feature Landscape) +- LLM-Prompt-Inhalte und Agent-Verhalten +- Beliebige Workflow-Graphen +- Analytics, BI, externe PM-Tools + +### 5.3 Alignment mit Ist-Codebase + +Bestehende Module bleiben Core-Bestandteil: + +- `tenant_context.py`, `capabilities.py`, `entitlements.py` +- `rights_registry.py` + `*_registrations/` +- `services/` für Domain-Writes +- `data_layer/` für Read-Aggregation +- `services/audit.py` + +Neu (Ziel): `backend/steering/` als Erweiterungsschicht — **ohne** Umbau der Foundation. + +--- + +## 6. Methodenarchitektur und Erweiterbarkeit + +### 6.1 Method Registry + +Analog zum etablierten Registry-Muster (`rights_registry`, `feature_registry`): + +```text +backend/steering/methods/registry.py +backend/steering/methods/registrations/ # built-in methods +``` + +**Registrierung beim Import → optional Sync nach DB (später für Profiles).** + +Stufe 1 (Ziel): In-Memory-Registry, code-seitige Built-in Methods, voll testbar. + +### 6.2 MethodDefinition Contract + +Mindestinhalt (aus Method Design Principles, hier technisch präzisiert): + +```python +@dataclass(frozen=True) +class MethodDefinition: + method_key: str # stabil, z. B. "product_milestone_driven" + version: str # z. B. "v1" + label: str + description: str + supported_domains: tuple[str, ...] + supported_scope_types: tuple[str, ...] # initiative, roadmap_item, action, ... + default_lifecycle: str # Referenz auf Lifecycle-Profil + lifecycle_steps: tuple[str, ...] # aktivierte Schritte des Standard Lifecycle + required_structures: tuple[str, ...] + allowed_structures: tuple[str, ...] + hook_slugs: tuple[str, ...] + structure_builder_keys: tuple[str, ...] + attention_rule_provider_keys: tuple[str, ...] + next_action_strategy_key: str + assignment_strategy_key: str + waiting_strategy_key: str + reminder_strategy_key: str | None + escalation_strategy_key: str | None + result_intake_strategy_key: str | None + review_strategy_key: str | None + evidence_policy_key: str | None + closure_policy_key: str | None + allowed_workflow_fragment_keys: tuple[str, ...] + allowed_node_types: tuple[str, ...] + default_configuration: dict | None +``` + +### 6.3 Method Versioning + +- `method_key` bleibt stabil über Versionen hinweg +- `SteeringContext` speichert `method_key` + `method_version` bei Bindung +- Upgrade = explizite Migration/Admin-Aktion, nie stillschweigend +- Alte Versionen bleiben ausführbar, solange Kontexte sie referenzieren + +### 6.4 Method Profiles (später) + +Stufenmodell (verbindlich): + +1. **Built-in Methods** — code-definiert, keine Nutzerkonfiguration +2. **Built-in Method Profiles** — vordefinierte Varianten (`maturity_progression.evidence_strict`) +3. **Tenant Method Profiles** — begrenzte Parameter, keine freie Logik +4. **Workflow Bindings an Hooks** — kleine Fragmente, erlaubte Node Types +5. **Method Designer UI** — Governance, Tests, Freigabe + +Profiles dürfen Parameter setzen (Review-Frequenz, Evidence-Pflicht), aber **keine** Capabilities, Tenant-Sicherheit oder Hook-Semantik außer Kraft setzen. + +### 6.5 Erweiterbarkeit ohne Core-Umbau + +Neue Methode = neues Paket: + +```text +backend/steering/methods/registrations/content_chapter_based.py + → register_method(MethodDefinition(...)) + → register_structure_builder(...) + → register_attention_rules(...) + → register_strategy(...) +``` + +Core ändert sich nur, wenn neue **Hook Slugs** oder **Kernstrukturen** fachlich nötig werden — selten und per Architecture Decision. + +--- + +## 7. Standard Lifecycle und Hooks + +### 7.1 Minimaler Standard Lifecycle + +Als **generische Steuerungslogik**, nicht als starrer Projektprozess: + +```text +intake → method_selection → structure_setup → planning → action_selection + → assignment → waiting → result_intake → validation → review → adaptation → closure +``` + +**Bewertung: tragfähig als Basismodell.** + +| Lifecycle-Schritt | Core-Verantwortung | Methoden-Spezialisierung | +|-------------------|-------------------|--------------------------| +| intake | SteeringContext anlegen, Ziel/Scope persistieren | Zusätzliche Hooks (`on_scope_named`) | +| method_selection | Method Registry abfragen, Vorschlag | Domain-Filter, Profile-Auswahl | +| structure_setup | Hook dispatch, Builder aufrufen | Welche Builder, welche Lanes | +| planning | Lifecycle-Transition, Audit | DoD/Evidence-Policies | +| action_selection | Signal Engine, NextAction | Strategy ersetzt Default-Rules | +| assignment | Assignment Service, Actor-Validierung | Assignment Strategy | +| waiting | Waiting State, Timers (später) | Waiting/Reminder/Escalation Strategy | +| result_intake | Result-Events entgegennehmen | Intake Strategy | +| validation | Evidence/DoD Checks | Evidence Policy | +| review | Review-Objekt anstoßen | Review Strategy | +| adaptation | Replan-Hooks | Structure Update, Method Adjustment | +| closure | Closure Policy, Archivierung | Scope-spezifische Abschlussregeln | + +Methoden **dürfen** Schritte auslassen (z. B. `routine_control` überspringt `planning` oft). Methoden **dürfen nicht** Tenant-/Actor-/Capability-Invarianten umgehen. + +### 7.2 Abbildung Beispiel-Domains + +| Domain | Aktive Lifecycle-Schritte | Typische Hooks | +|--------|--------------------------|----------------| +| Softwareentwicklung | intake → structure → action_selection → assignment → waiting → validation → review → adaptation | `on_roadmap_required`, `on_backlog_required`, `on_next_action_requested` | +| Buchentwicklung | intake → structure → planning → action_selection → assignment → waiting → review | `on_content_structure_required`, `on_review_due` | +| Reifegradentwicklung | intake → structure → action_selection → assignment → waiting → validation → review → adaptation | `on_maturity_path_required`, `on_evidence_required`, `on_reassessment_required` | + +### 7.3 Hook Registry + +```text +backend/steering/hooks/registry.py +``` + +**Hook Slugs** sind stabile, fachlich benannte Einhängepunkte: + +```text +on_goal_captured +on_method_selected +on_structure_required +on_roadmap_required / on_backlog_required / on_wbs_required / ... +on_next_action_requested +on_assignment_required +on_wait_started +on_due_date_reached / on_reminder_required / on_escalation_required +on_result_received +on_evidence_required +on_review_due +on_replan_required +on_closure_requested +``` + +**Technisches Modell:** + +```python +@dataclass(frozen=True) +class HookDefinition: + slug: str + lifecycle_step: str + description: str + since_version: str # Hook-Registry-Version + deprecated: bool = False + superseded_by: str | None = None + +@dataclass +class HookHandler: + hook_slug: str + method_key: str + priority: int + handler: Callable[[HookContext], HookResult] +``` + +**Hook Registry:** zentrale Liste aller **erlaubten** Slugs (Core). Methoden deklarieren unterstützte Slugs in `MethodDefinition`; Handler registrieren sich pro Methode. + +**Versionierung:** Hook Slugs ändern Semantik nicht leichtfertig. Breaking Changes → neuer Slug + Deprecation. `HookContext` enthält Schema-Version. + +**Testbarkeit:** Hook Handler sind pure Functions / kleine Klassen mit injizierbarem Context; Unit-Tests pro Methode und Hook. + +**Workflow-Fragmente (später):** Fragment registriert sich als Handler an einem Hook; Core dispatcht; Runtime führt Steps aus; Ergebnis zurück als `HookResult`. + +--- + +## 8. Structure Builder + +### 8.1 Konzept + +Structure Builder erzeugen **methodenspezifische Steuerungsstrukturen** aus gemeinsamen Kernobjekten. + +```python +class StructureBuilder(Protocol): + builder_key: str + + def build( + self, + ctx: TenantContext, + steering: SteeringContext, + spec: StructureBuildSpec, + ) -> StructureBuildResult: ... +``` + +### 8.2 Builder-Typen (Zielkatalog) + +| Builder Key | Erzeugt | Beispiel-Methode | +|-------------|---------|------------------| +| `roadmap_builder` | Roadmap + Lanes | generisch | +| `milestone_plan_builder` | RoadmapItems (milestone) | product_milestone_driven | +| `feature_landscape_builder` | RoadmapItems (feature) | product_milestone_driven | +| `backlog_builder` | initiale BacklogItems | mehrere | +| `wbs_builder` | hierarchische RoadmapItems | wbs_driven | +| `maturity_path_builder` | Reifegrad-Lanes + Stages | maturity_progression | +| `chapter_structure_builder` | Kapitel-Lanes | content_chapter_based | +| `cycle_structure_builder` | WorkCycles | recurring_control | +| `review_gate_builder` | Review-Punkte | review_driven | + +### 8.3 Einbindung + +1. Lifecycle erreicht `structure_setup` +2. Orchestrator feuert Hook `on_structure_required` +3. Methode liefert benötigte Builder Keys +4. Core ruft Builder sequentiell/idempotent auf +5. Builder nutzen **Domain Services** (nicht raw SQL) — Audit, Tenant, Capabilities +6. Ergebnis: Struktur-IDs + Metadaten im SteeringContext + +### 8.4 Guardrails + +Builder dürfen **nicht**: + +- TenantContext aus Client-Body übernehmen +- Actions mit Assignment umgehen, wenn Gate vorgesehen +- Capabilities umgehen +- parallele Tabellen erfinden (Milestone = RoadmapItem mit `item_type`) + +--- + +## 9. Gemeinsame Kernstrukturen + +### 9.1 Core vs. methodenspezifisch + +| Struktur | Core | Anmerkung | +|----------|------|-----------| +| **SteeringContext** | ✓ Core | Bindung Initiative ↔ Methode ↔ Lifecycle | +| **Initiative** | ✓ Core | Steerable Object / Vorhaben | +| **Project** | ✓ Core (optional) | Unterstruktur, nicht in MVP-Minimum | +| **Roadmap** | ✓ Core | Container für Lanes/Items | +| **RoadmapLane** | ✓ Core | methodengeführt, typisiert | +| **RoadmapItem** | ✓ Core | milestone, feature, chapter, maturity_stage, work_cycle, … | +| **BacklogItem** | ✓ Core | Triage vor Commit | +| **Action** | ✓ Core | operative Maßnahme | +| **ActionAssignment** | ✓ Core | Zuweisung an Actor(s) | +| **Blocker** | ✓ Core | eigenes Objekt, nicht nur Status | +| **Evidence** | ✓ Core | Nachweis | +| **Decision** | ✓ Core | dokumentierte Wahl | +| **Review** | ✓ Core | strukturierte Bewertung | +| **RecurringElement** | ✓ Core | Routinen | +| **AttentionItem** | ✓ Core (Read Model) | Data Layer, nicht persistent | +| **NextActionCandidate** | ✓ Core (Read Model) | Data Layer | +| **Signal** | ✓ Core (intern) | erklärbare Ursache für Attention/NextAction | +| **WaitingState** | ✓ Core | wartet auf Ergebnis/Termin/Ereignis | +| **Reminder / Escalation** | ✓ Core (Event/Read) | zunächst regelbasiert | +| WBS-Dependency-Graph | methodenspezifisch | als RoadmapItem-Metadaten/Relations | +| Kapitel-Recherche-Queue | methodenspezifisch | BacklogItem-Typen/Tags | +| Reifegrad-Rubric | methodenspezifisch | Config/Profile, nicht eigenes Objektmodell | + +**Prinzip:** Meilenstein, Feature, Kapitel, Reifegradstufe = **RoadmapItem** mit `item_type` — keine parallelen Tabellen pro Methode. + +### 9.2 SteeringContext (Ziel-Entity) + +```text +steering_contexts ( + id, tenant_id, initiative_id, + method_key, method_version, method_profile_key NULL, + lifecycle_state, -- aktueller Standard-Lifecycle-Schritt + lifecycle_metadata JSONB, -- methodenspezifische Zusatzdaten + structure_snapshot JSONB NULL, -- optional: referenzierte Struktur-IDs + created_at, updated_at +) +``` + +Initiative bleibt das Nutzer-sichtbare Vorhaben; SteeringContext ist die **methodische Bindung**. + +--- + +## 10. Roadmap, Backlog, Action und Blocker + +### 10.1 Rollen im Steuerungsmodell + +```text +BacklogItem = noch nicht committeter Handlungsbedarf (Triage) +Action = committete operative Maßnahme +Blocker = Hindernis, das Fortschritt verhindert +Roadmap/RoadmapItem = Struktur und überprüfbare Zielpunkte +Assignment = Verantwortung an Actor +``` + +### 10.2 Typischer Flow (product_milestone_driven) + +```text +Initiative + Methode + → Roadmap mit Release/Feature Lanes + → BacklogItems für Ideen/Risiken + → accepted BacklogItem → convert → Action + → Action Assignment → Execute → Waiting + → Blocker melden → Attention + → Evidence → Review → Adapt +``` + +### 10.3 Ist → Ziel + +| Objekt | Ist (AP0.7) | Nächster Schritt | Ziel | +|--------|-------------|------------------|------| +| Initiative | ✓ | — | + SteeringContext | +| Action | ✓ | — | + erweiterte Status (ready, review_required) | +| Assignment | ✓ (action only) | — | ggf. generisches Assignment später | +| Blocker | nur `status=blocked` | **AP0.8b** | eigenes Objekt | +| BacklogItem | — | **AP0.8c** | eigene Tabelle | +| Milestone | — | **AP0.8d** | RoadmapItem oder eigene Tabelle als Zwischenschritt* | +| Roadmap | — | AP0.9+ | generisches Modell | + +\* **Architekturentscheidung empfohlen:** AP0.8 führt `milestones` als eigene Tabelle ein (MVP-Pragmatismus). Zielarchitektur: schrittweise Konsolidierung zu `roadmap_items` ohne Datenverlust — Migration mit `item_type=milestone`. + +### 10.4 Blocker und Action-Status + +Blocker ist **eigenes Objekt**; `action.status=blocked` bleibt kompatibler Ableitungs-/Anzeigestatus. Attention-Regeln berücksichtigen beides (AP0.8). + +--- + +## 11. Signals, Attention und Next Best Action + +### 11.1 Architektur + +```text +Signal Rule Providers (methodenregistriert) + ↓ +Signal Engine (Core) + ↓ +AttentionItem / NextActionCandidate (Read Models, Data Layer) + ↓ +API: GET /api/workspace/attention, /next-actions + ↓ +AttentionWidget (Frontend Registry) +``` + +### 11.2 Signal Rule Contract + +```python +class AttentionRuleProvider(Protocol): + provider_key: str + method_keys: tuple[str, ...] # leer = globale Regeln + + def evaluate(self, ctx: TenantContext, scope: SignalScope) -> list[Signal]: ... +``` + +Jedes **Signal** enthält Erklärbarkeit: + +```text +reason_code, severity, hook_slug (optional), method_key, scope_type, scope_id, +data_source, recommended_action (optional) +``` + +### 11.3 NextActionStrategy + +Methoden liefern **NextActionStrategy** für methodenspezifische Ableitung: + +- product: „Backlog accepted ohne Action → convert“ +- content: „nächstes Kapitel ohne Draft → Schreib-Action“ +- maturity: „Gap zwischen Ist- und Zielreife → Praxis-Action“ + +**Default-Strategy (Core):** regelbasiert wie Canonical Model §7 — AP0.8 implementiert die erste Instanz **ohne** Method Registry, als globaler Rule Provider. Später Refactor in `steering/signals/default_rules.py`. + +### 11.4 Ranking / Priorisierung + +Stufe 1: deterministische Regeln + feste Severity-Reihenfolge +Stufe 2: methodenspezifische Gewichtung via Profile +Stufe 3: KI-Ranking nur als **Provider**, nicht als Steuerungsautorität + +### 11.5 Data Layer + +```text +backend/data_layer/attention.py # AP0.8a — erste Instanz +backend/steering/signals/engine.py # Ziel — orchestriert Provider +``` + +Read-only, tenant-scoped, keine Client-Aggregation (Tenant-Invariante #10). + +--- + +## 12. Assignment, Waiting, Reminder und Escalation + +Steuerung endet nicht bei „Action erzeugt“. + +### 12.1 Assignment + +- **Heute:** `action_assignments` (M:N Action ↔ Actor) +- **Ziel:** Assignment Strategy wählt Actor(s) — human default, später Agent/Working Group +- **Core:** Validierung `_actor_in_tenant()`, Audit, Capability `kairo.action.manage` +- **Generisches Assignment** (an Milestone, Review, …): spätere Erweiterung mit `assignable_type` + `assignable_id` + +### 12.2 Waiting + +```text +waiting_states ( + id, tenant_id, steering_context_id, + wait_kind, -- result, due_date, external_event, agent_run, review + scope_type, scope_id, + started_at, due_at NULL, + status, -- active, fulfilled, cancelled, escalated + metadata JSONB +) +``` + +Lifecycle-Schritt `waiting` + Hook `on_wait_started`. Fulfillment via `on_result_received`, Statusänderung, Termin, Agent-Callback. + +### 12.3 Reminder und Escalation + +Stufe 1 (regelbasiert, AP0.9+): + +- Attention-Regeln für überfällige Elemente (wenn `due_at` existiert) +- `on_reminder_required`, `on_escalation_required` Hooks + +Stufe 2: + +- ReminderStrategy / EscalationStrategy pro Methode +- Eskalation erzeugt Attention + optional neue Action/Review + +Stufe 3: + +- Scheduler/Worker (Infrastruktur) triggert Hook-Dispatch — **nicht** im Request-Pfad + +### 12.4 Externe Ereignisse und Agentenergebnisse + +```text +result_intake_events ( + id, tenant_id, actor_id NULL, + scope_type, scope_id, + event_kind, payload JSONB, + received_at, processed_at +) +``` + +`ResultIntakeStrategy` validiert, mapped auf Domain-Updates, feuert Lifecycle-Transition. + +--- + +## 13. Workflow-Fragmente und spätere Runtime + +### 13.1 Begriffsabgrenzung + +| Begriff | Definition | +|---------|------------| +| **Core-Logik** | Lifecycle, Hooks, Registry, Domain Services, Signals | +| **Methode** | Registriertes Steuerungspaket mit Builders/Strategies/Rules | +| **Hook** | Stabiler Einhängepunkt im Lifecycle | +| **Workflow-Fragment** | Kleiner, hook-gebundener Step-Graph mit erlaubten Node Types | +| **Runtime** | Technische Ausführungsmaschine für Fragmente (Wait, Retry, Agent Call) | + +### 13.2 Rolle der Runtime + +Die Runtime **unterstützt** methodengeführte Abläufe. Sie **ersetzt nicht** den Core. + +```text +Hook on_evidence_required + → Methode erlaubt Fragment "evidence_check_v1" + → Runtime führt aus: human_task → evidence_check → optional llm_prompt + → Ergebnis → Result Intake → Lifecycle weiter +``` + +### 13.3 Governance + +- Fragmente nur an deklarierte Hooks der Methode +- `allowed_node_types` in MethodDefinition +- Keine freien Trigger ohne SteeringContext +- Audit für jeden Step-Run + +### 13.4 Bezug zu Prompt Registry (AP0.4) + +`prompt_definitions.execution_mode = workflow` bleibt Infrastruktur. Ziel: Prompt-/Pipeline-Steps als **Node Types** in Fragmenten — erst nach Operating Model MVP und Method Registry. + +--- + +## 14. Agenten-, LLM- und Tool-Integration + +### 14.1 Steering Authority + +**Kairo bleibt Steering Authority.** Agenten sind **Actors** und **Provider**, keine eigenständigen Steuerungsinstanzen. + +| Aktion | Agent darf | Nur mit Freigabe | +|--------|-----------|------------------| +| Status/Fortschritt melden | ✓ | — | +| Backlog vorschlagen, Evidence einreichen | ✓ | — | +| Blocker melden, Review anfordern | ✓ | — | +| Next Action **empfehlen** | ✓ | — | +| Ziele/Meilensteine/Rechte ändern | ✗ | menschliche Freigabe | +| Strategische Priorität ändern | ✗ | menschliche Freigabe | + +### 14.2 Agenten als Actors + +Bereits im Modell (`actors.actor_type = agent`). Assignment an Agent-Actors wie an Humans — über dieselbe Assignment Strategy Schicht. + +### 14.3 LLM/Tool Steps + +Spätere Node Types: `llm_prompt`, `agent_task`, `tool_call`, `human_task`, `evidence_check`, `review`. + +Ausführung in Runtime; Ergebnis via `on_agent_result_received` → Result Intake. + +### 14.4 Audit und Fehler + +- Jeder Agent-Run: Audit + `prompt_execution_logs` (bestehend) +- Fehler → Blocker oder Attention, kein stilles Scheitern +- Capability-Gates vor jedem Write + +--- + +## 15. Datenmodell-Zielbild + +### 15.1 Foundation (bestehend, Schema 002–005) + +Unverändert: `users`, `tenants`, `actors`, `sessions`, `capabilities`, `features`, `prompt_*`, `configuration_entries`, `audit_log`. + +### 15.2 Domain — Phasenplan + +**Phase A (AP0.8 — Operating Model Extension I):** + +```text +blockers, backlog_items, milestones ++ data_layer/attention.py +``` + +**Phase B (AP0.9 — Operating Model Extension II):** + +```text +evidence, decisions, reviews, recurring_elements ++ optional due_at auf actions/initiatives ++ erweiterte action statuses +``` + +**Phase C (Steering Core — AP1.x):** + +```text +steering_contexts +roadmaps, roadmap_lanes, roadmap_items # milestones migrieren/konsolidieren +waiting_states, result_intake_events +method_profiles (tenant-scoped config) +``` + +**Phase D (Runtime — später):** + +```text +workflow_fragments, workflow_runs, workflow_step_results +``` + +### 15.3 Tenant-Invarianten + +Alle neuen Tabellen: `tenant_id NOT NULL`, Queries aus TenantContext, Cross-Tenant → 404. Steering-Metadaten (`method_key`, `lifecycle_state`) tenant-scoped. + +### 15.4 ER-Zielbild (vereinfacht) + +```mermaid +erDiagram + TENANT ||--o{ INITIATIVE : owns + TENANT ||--o{ ACTOR : owns + INITIATIVE ||--o| STEERING_CONTEXT : guided_by + INITIATIVE ||--o{ ROADMAP : has + ROADMAP ||--o{ ROADMAP_LANE : contains + ROADMAP_LANE ||--o{ ROADMAP_ITEM : contains + INITIATIVE ||--o{ BACKLOG_ITEM : has + INITIATIVE ||--o{ ACTION : has + INITIATIVE ||--o{ BLOCKER : has + ACTION ||--o{ ACTION_ASSIGNMENT : has + ACTOR ||--o{ ACTION_ASSIGNMENT : assigned + INITIATIVE ||--o{ REVIEW : has + INITIATIVE ||--o{ EVIDENCE : has + STEERING_CONTEXT ||--o{ WAITING_STATE : tracks +``` + +--- + +## 16. Modul-/Schichten-Zielbild + +### 16.1 Backend-Zielstruktur + +```text +backend/ + main.py, tenant_context.py, capabilities.py, auth.py + routers/ # dünn, HTTP + services/ # Domain Write + initiatives.py, actions.py, blockers.py, backlog.py, ... + steering_context.py # neu + data_layer/ # Domain Read + workspace.py, attention.py, next_actions.py, ... + steering/ # NEU — Steuerungskern + lifecycle/ + orchestrator.py + states.py + hooks/ + registry.py + dispatch.py + methods/ + registry.py + definition.py + registrations/ + product_milestone_driven.py + content_chapter_based.py + maturity_progression.py + structures/ + registry.py + builders/ + signals/ + engine.py + default_rules.py + strategies/ + registry.py + next_action.py + assignment.py + waiting.py + rights_registrations/ + feature_registrations/ + migrations/ +``` + +### 16.2 Frontend-Zielstruktur + +```text +frontend/src/ + registry/ + widgetRegistry.js # Attention, Structure-Gaps, ... + viewRegistry.js + pages/ + WorkspacePage.jsx # Steuerungsfragen sichtbar + InitiativeDetailPage # Backlog, Blocker, Milestones, Method + widgets/ + AttentionWidget.jsx # AP0.8a +``` + +Kein Backend-Widget-Registry in Sprint 0 — clientseitige Registry mit Capability-Gating bleibt. + +### 16.3 Abhängigkeitsregeln + +```text +routers → services | data_layer | steering (read paths) +steering → services (writes), data_layer (reads) +steering ↛ routers +methods/registrations → steering (registries only) +services ↛ steering (keine zirkuläre Kopplung — steering orchestrates, services persist) +``` + +--- + +## 17. Security, Tenant, Actor, Governance und Audit + +### 17.1 Tenant-First + +Alle Steering-Operationen laufen über `TenantContext`. Methoden und Builder erhalten Context, nie rohe Client-Tenant-IDs. + +### 17.2 Actor-First + +Assignments an `actor_id`. Human Actor via Session aufgelöst. Agenten gleichberechtigt als Assignees, nicht als Bypass. + +### 17.3 Capabilities + +Neue Module registry-first: + +```text +kairo.steering.read / manage +kairo.attention.read # AP0.8 +kairo.blocker.read / manage # AP0.8 +kairo.backlog.read / manage +kairo.milestone.read / manage +kairo.method.read # später: Methodenauswahl einsehen +``` + +Modus `probe` → `enforce` wie heute. + +### 17.4 Governance + +- Methoden nur via Code-Registry (Stufe 1–2) +- Tenant Profiles: Admin-Capability + Audit +- Workflow-Fragmente: explizite Allowlist pro Methode +- Agent-Writes: dieselben Capabilities wie Human + +### 17.5 Audit + +Bestehendes `audit_log` erweitern um: + +```text +steering.method_selected, steering.lifecycle_transition, +steering.structure_built, blocker.*, backlog.*, attention.* (optional) +``` + +Später: `actor_id` in Audit (AP0.7 zurückgestellt — bei Steering relevant, dann nachziehen). + +--- + +## 18. Architekturentscheidungen + +| ID | Entscheidung | Begründung | +|----|--------------|------------| +| AD-TA-01 | Methodengeführter Steuerungskern statt freier Workflow Engine | Produktidentität, Erklärbarkeit, Testbarkeit | +| AD-TA-02 | Registry-Muster für Methoden, Hooks, Builder, Strategies | Konsistenz mit AP0.5 Rights/Features; Erweiterbarkeit | +| AD-TA-03 | Standard Lifecycle als gemeinsame Basis | Domains abbildbar; Methoden skip/specialize | +| AD-TA-04 | Hook Slugs als primärer Erweiterungspunkt | Stabile API zwischen Core, Methoden, Runtime | +| AD-TA-05 | RoadmapItem als generisches Strukturelement | Keine parallelen Modelle pro Methode | +| AD-TA-06 | Attention/NextAction als Read Models im Data Layer | Canonical Model §8; keine Client-Logik | +| AD-TA-07 | Built-in Methods zuerst, Profiles später | Method Design Principles Stufe 1–3 | +| AD-TA-08 | AP0.8 Milestone-Tabelle als MVP-Brücke | Pragmatismus; Konsolidierung zu RoadmapItem geplant | +| AD-TA-09 | Prompt/Workflow-Runtime eingefroren bis OM-MVP | Product Reset, Principle Gate | +| AD-TA-10 | Kairo bleibt Steering Authority | Agenten als Actors/Provider | + +--- + +## 19. Risiken und offene Fragen + +### 19.1 Risiken + +| Risiko | Auswirkung | Mitigation | +|--------|------------|------------| +| Zu frühe Workflow-Runtime | Core-Verwässerung | AP0.8–0.10 zuerst; Runtime erst nach Method Registry | +| Milestone vs. RoadmapItem Doppelmodell | Migration-Komplexität | Explizite Konsolidierung in Phase C | +| Steering-Schicht zu früh | Over-Engineering | Attention global starten (AP0.8), Registry schrittweise | +| Methoden-Explosion | Untestbare Vielfalt | Built-in only; Review-Gate für neue Methoden | +| Agenten ohne Governance | Falsche Autorität | Capability + Freigabe-Matrix (Canonical §11) | +| Lifecycle zu abstrakt | Nutzer versteht Zustand nicht | UI zeigt fachliche Labels, nicht nur lifecycle_state | + +### 19.2 Offene Fragen + +1. **Wann** `steering_contexts` einführen — mit AP0.9 oder eigener AP1.0? +2. **Generisches Assignment** — Scope und Zeitpunkt? +3. **Roadmap-Konsolidierung** — Big-Bang-Migration oder parallel betreiben? +4. **Methodenauswahl UI** — wie minimal im MVP? +5. **Scheduler-Infrastruktur** für Waiting/Reminder — Worker-Prozess oder DB-Polling? +6. **Audit `actor_id`** — Nachzug vor Agent-Integration? + +--- + +## 20. Empfohlene nächste Schritte + +Diese Zielarchitektur ist **kein Implementierungsauftrag**. Empfohlene Reihenfolge: + +### 20.1 Kurzfristig (MVP-Pfad) + +1. **AP0.8 freigeben und umsetzen** — Attention, Blocker, BacklogItem, Milestone (Operating Model Extension I) +2. **AP0.9** — Evidence, Decision, Review, RecurringElement; Due Dates; Action-Status-Erweiterung +3. **AP0.10** — Validierungs-Testvorhaben mit realem Steuerungsszenario + +### 20.2 Mittelfristig (Steering Core) + +4. **`backend/steering/` Skeleton** — Method Registry, Hook Registry, Definition Contracts (ohne Runtime) +5. **SteeringContext** — Tabelle + Service; Initiative optional mit Default-Methode `generic_operating` +6. **Refactor Attention** — globaler Default Rule Provider → Signal Engine mit Provider-Interface +7. **Erste Built-in Method** — `product_milestone_driven` als Referenzimplementierung +8. **Roadmap-Modell** — Einführung + Milestone-Migration + +### 20.3 Langfristig + +9. Method Profiles (tenant-scoped) +10. Waiting States + Reminder/Escalation +11. Workflow-Fragment-Layer + Runtime +12. Agent/LLM Node Types unter Governance + +### 20.4 Architecture Decisions vor Implementierung + +- ADP: Milestone → RoadmapItem Konsolidierung +- ADP: SteeringContext Einführungszeitpunkt +- ADP: Scheduler-Strategie für Waiting/Reminder + +--- + +## Referenzen + +- `docs/architecture/Kairo_Core_Model_Decision_v0.2.md` +- `docs/architecture/Kairo_Method_Design_Principles_v0.1.md` +- `docs/product/Kairo_Canonical_Operating_Model_v0.1.md` +- `docs/product/Kairo_Product_Definition_and_MVP_Reset_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` +- `docs/sprints/Sprint0_AP0_8_Assignment_v0.1.md` diff --git a/docs/architecture/Kairo_Universal_Steering_Engine_Decision_v0.1.md b/docs/architecture/Kairo_Universal_Steering_Engine_Decision_v0.1.md new file mode 100644 index 0000000..97264ad --- /dev/null +++ b/docs/architecture/Kairo_Universal_Steering_Engine_Decision_v0.1.md @@ -0,0 +1,1655 @@ +# Kairo – Universal Steering Engine Decision +## v0.1 – Fachliche Entscheidung zu Steuerungsengine, Roadmap, Methoden, Workflow-Nodes und Agenten-Einbindung + +**Status:** Entscheidungs- und Spezifikationsentwurf +**Stand:** 2026-07-05 +**Kontext:** Nach AP0.7, nach Product Reset, vor Überarbeitung von AP0.8 +**Ziel:** Verbindliche fachliche Grundlage für die spätere universelle Steuerungsengine von Kairo, ohne AP0.8 technisch zu überladen. + +--- + +## 1. Zweck dieses Dokuments + +Dieses Dokument verdichtet die bisherige fachliche Diskussion zu einer entscheidungsfähigen Spezifikation. + +Es beantwortet insbesondere: + +1. Welche Verantwortung hat Kairo selbst? +2. Welche Verantwortung kann an externe Agentensysteme ausgelagert werden? +3. Wie werden unterschiedliche Entwicklungs- und Umsetzungsmethoden fachlich modelliert? +4. Wie hängen Steering Domains, Lifecycle Models, Methoden, Profile, Roadmaps, Hooks, Workflows, Nodes und Signals zusammen? +5. Wie bleibt Kairo universell erweiterbar, ohne sofort zu komplex zu werden? +6. Was muss AP0.8 vorbereiten? +7. Was darf AP0.8 ausdrücklich noch nicht bauen? + +--- + +## 2. Ausgangslage + +AP0.7 hat wesentliche technische Grundlagen geschaffen: + +- Tenant Hardening +- Tenant-Invarianten +- Cross-Tenant-Tests +- Actor Directory +- echter ActorSelect +- Data Layer Minimum +- Workspace Summary +- zentrale Workspace-Read-Endpunkte +- AP0.6b UX/PWA bleibt erhalten + +Gleichzeitig ist fachlich klar geworden: + +```text +Initiative / Vorhaben + → Action / Maßnahme +``` + +ist als technischer Startpunkt akzeptabel, aber als Produktmodell für Kairo zu flach. + +Kairo soll kein Aufgabenmanager sein, sondern ein operativer Program Director und langfristig eine universell erweiterbare Steuerungsplattform für Entwicklungen. + +--- + +## 3. Leitentscheidung + +Kairo baut langfristig eine **fachliche Steuerungsengine**. + +Diese Engine muss unterschiedliche Entwicklungs- und Umsetzungskontexte tragen können: + +- Software- und Produktentwicklung +- Buchentwicklung +- Programmarbeit +- Projektarbeit +- persönliche Entwicklung +- Reifegradentwicklung +- Lernpfade +- Routinen +- Reviews / Audits +- Betrieb / Wartung +- Agentenläufe + +Die Engine darf jedoch nicht sofort als beliebige freie Workflow-Plattform gebaut werden. + +Leitentscheidung: + +> Kairo bleibt System of Record und Steering Authority. +> Externe oder integrierte Agentensysteme können ausführende Step Provider sein. +> Die fachliche Steuerung, der Kontext, die Signale, die Roadmap, die Nachvollziehbarkeit und die Verantwortungslogik bleiben in Kairo. + +--- + +## 4. Was Kairo selbst verantwortet + +Kairo verantwortet dauerhaft: + +```text +- steuerbare Objekte und ihre Beziehungen +- Roadmaps und Entwicklungsziele +- Backlog, Actions, Blocker, Reviews, Evidence und Decisions +- Steering Contexts +- Method Definitions und Method Profiles +- Lifecycle Models und Hook Points +- Signale wie Attention, NextAction, EvidenceRequired, DecisionRequired +- Auditierbarkeit und Nachvollziehbarkeit +- Tenant- und Actor-Sicherheit +- Auswahl und Beauftragung von Human-/Agent-/Tool-Steps +- Rückführung von Ergebnissen in das Kairo-Modell +``` + +Kairo muss also immer wissen: + +- Was wird gesteuert? +- Warum wird etwas vorgeschlagen? +- Wer oder was ist verantwortlich? +- Welche Methode gilt? +- Welche Roadmap- oder Entwicklungslogik liegt zugrunde? +- Welcher Workflow oder Hook hat ein Signal erzeugt? +- Welches Ergebnis wurde zurückgeführt? + +--- + +## 5. Was externe Agentensysteme übernehmen dürfen + +Externe oder integrierte Agentensysteme dürfen später einzelne Schritte ausführen, z. B.: + +```text +- Text analysieren +- Vorschläge generieren +- WBS-Vorschläge erzeugen +- Abhängigkeiten identifizieren +- Backlog Items vorschlagen +- NextActionCandidates vorschlagen +- DoD prüfen +- Evidence auswerten +- Dokumente zusammenfassen +- Recherche durchführen +- Tool Calls ausführen +``` + +Sie dürfen aber nicht ohne Kairo-Kontrolle: + +```text +- führendes Steuerungssystem werden +- Tenant-/Actor-Kontext umgehen +- Roadmap oder Methode eigenständig überschreiben +- strategische Prioritäten ändern +- Daten ohne Audit verändern +- Rechte oder Capabilities ändern +- produktive Änderungen ohne vorgesehenes Gate ausführen +``` + +Agentensysteme sind aus Sicht von Kairo: + +```text +ausführende Provider +``` + +nicht: + +```text +führende Steuerungsinstanz +``` + +--- + +## 6. Komplexitätsbremse + +Die Architektur wird in drei Ebenen geschnitten. + +### Ebene 1 – Signals und Read Models + +Kurzfristig und MVP-nah. + +```text +- Attention +- NextActionCandidate +- EvidenceRequired +- DecisionRequired +- BlockerSignal +- ReviewDue +``` + +Diese Ebene liefert Produktnutzen ohne vollständige Workflow Runtime. + +### Ebene 2 – Hook-basierte Workflows + +Mittelfristig. + +```text +- feste Hook Points +- definierte Node-Typen +- Workflow Definitions +- Workflow Bindings +- einfache Workflow Runtime +``` + +Diese Ebene erlaubt methodenspezifische Abläufe, aber noch keine beliebige offene Plattform. + +### Ebene 3 – konfigurierbare Methoden und Agenten + +Langfristig. + +```text +- Method Profiles +- tenant-konfigurierbare Regeln +- LLM-/Tool-/Agent-Steps +- externe Agentensysteme +- Method Designer +- Workflow Designer +``` + +AP0.8 darf maximal Ebene 1 aktiv implementieren und Ebene 2/3 fachlich vorbereiten. + +--- + +## 7. Kernmodell der universellen Steuerung + +Das fachliche Zielmodell lautet: + +```text +Steerable Object + → Steering Context + → Steering Domain + → Lifecycle Model + → Steering Method + → Method Profile + → Hook Points + → Rules / Workflow Bindings + → Workflow Nodes + → Signals / Results + → Roadmap / Backlog / Action / Evidence / Review +``` + +Dieses Modell ist bewusst mehrschichtig. + +Es verhindert, dass alles auf eine einzige Projektlogik oder eine einzige Aufgabenlogik reduziert wird. + +--- + +## 8. Steerable Object + +Ein Steerable Object ist jedes Objekt, für das Kairo Steuerungslogik anwenden kann. + +Mögliche Scope Types: + +```text +program +initiative +project +roadmap +roadmap_item +backlog_item +action +blocker +review +evidence +decision +recurring_element +work_cycle +agent_run +custom +``` + +Nicht alle Scope Types müssen in AP0.8 aktiv unterstützt werden. + +AP0.8 sollte mindestens vorbereiten: + +```text +initiative +roadmap_item +backlog_item +action +blocker +``` + +--- + +## 9. Steering Domain + +Eine Steering Domain beschreibt die fachliche Domäne der Steuerung. + +Initiale Domains: + +```text +program +project +product_development +content_development +personal_development +maturity_development +routine_operations +audit_review +agent_execution +custom +``` + +### 9.1 Beispiele + +#### Software-/Produktentwicklung + +```text +Domain: product_development +typische Roadmap-Lanes: +- Feature Landscape +- Architecture Evolution +- Releases +- Technical Debt +- Validation +``` + +#### Buchentwicklung + +```text +Domain: content_development +typische Roadmap-Lanes: +- Buchstruktur +- Kapitel +- Recherche +- Drafts +- Review +- Veröffentlichung +``` + +#### Persönliche Fähigkeitsentwicklung + +```text +Domain: maturity_development +typische Roadmap-Lanes: +- Reifegradstufen +- Fähigkeiten +- Praxis / Übungen +- Evidence +- Reflexion +- Assessments +``` + +#### Programmsteuerung + +```text +Domain: program +typische Roadmap-Lanes: +- strategische Ziele +- Initiativen +- Abhängigkeiten +- Ressourcen +- Risiken +- Benefits +``` + +--- + +## 10. Lifecycle Model + +Ein Lifecycle Model beschreibt die typischen Phasen einer Domain. + +### 10.1 Project / Initiative Lifecycle + +```text +intake +clarify +structure +plan +execute +monitor +review +adapt +close +``` + +### 10.2 Program Lifecycle + +```text +define_intent +establish_structure +prioritize_initiatives +coordinate_dependencies +allocate_capacity +monitor_benefits +resolve_conflicts +review_outcomes +rebalance +close +``` + +### 10.3 Maturity Development Lifecycle + +```text +assess_current_level +define_target_maturity +identify_gaps +select_intervention +practice +collect_evidence +reflect +adjust_challenge +reassess +``` + +### 10.4 Content Development Lifecycle + +```text +define_concept +structure_content +research +draft +review +revise +prepare_publication +publish +maintain +``` + +### 10.5 Routine Operations Lifecycle + +```text +define_routine +schedule_next_run +execute_run +capture_exception +verify_completion +review_quality +adjust_routine +repeat +``` + +AP0.8 muss diese Lifecycles noch nicht technisch als vollständige State Machines implementieren. + +Aber die Begriffe und Hook Points müssen fachlich vorbereitet sein. + +--- + +## 11. Steering Context + +Ein Steering Context verbindet ein Steerable Object mit Domain, Lifecycle und Methode. + +Konzeptionell: + +```text +Steering Context + - tenant_id + - scope_type + - scope_id + - steering_domain + - lifecycle_model + - steering_method + - method_profile_id optional + - method_version + - configuration_json + - inherits_from_parent + - is_active +``` + +Mögliche Tabelle: + +```sql +steering_contexts ( + id UUID PRIMARY KEY, + tenant_id UUID NOT NULL, + + scope_type VARCHAR(64) NOT NULL, + scope_id UUID NOT NULL, + + steering_domain VARCHAR(64) NOT NULL, + lifecycle_model VARCHAR(64) NOT NULL, + steering_method VARCHAR(128) NOT NULL, + method_profile_id UUID NULL, + method_version VARCHAR(32) NOT NULL DEFAULT 'v1', + + configuration_json JSONB NOT NULL DEFAULT '{}'::jsonb, + + inherits_from_parent BOOLEAN NOT NULL DEFAULT TRUE, + is_active BOOLEAN NOT NULL DEFAULT TRUE, + + created_at TIMESTAMP NOT NULL, + updated_at TIMESTAMP NOT NULL +) +``` + +### 11.1 Vererbung + +Standardregel: + +> Untergeordnete Objekte erben den Steering Context ihres Parents, sofern sie keinen eigenen Context besitzen. + +Beispiele: + +```text +Produktentwicklung Kairo + Initiative: product_development / milestone_driven + RoadmapItem "Feature Landscape": geerbt + BacklogItem "Attention DTO definieren": geerbt + Action "Endpoint bauen": simple task + +Buchentwicklung + Initiative: content_development / chapter_based + RoadmapItem "Kapitel 3": content_draft + Action "Rohfassung schreiben": writing_task + +Persönliche Entwicklung + Initiative: maturity_development / maturity_progression + RoadmapItem "Reifegrad Beweglichkeit 2": maturity_stage + Action "Dehnroutine durchführen": routine_task +``` + +--- + +## 12. Steering Method + +Eine Steering Method beschreibt, nach welcher Logik gesteuert wird. + +Beispiele: + +```text +simple +milestone_driven +kanban +cycle_based +chapter_based +maturity_progression +habit_based +review_driven +audit_driven +recurring_control +agent_controlled +hybrid +``` + +Eine Methode definiert fachlich: + +```text +- unterstützte Domains +- unterstützte Scope Types +- typische Roadmap-Lanes +- typische RoadmapItem-Typen +- relevante Hook Points +- erlaubte oder empfohlene Node-Typen +- relevante Signals +- Fortschrittslogik +- Reviewlogik +- Evidence-Anforderungen +- NextAction-Logik +``` + +--- + +## 13. Method Definition + +Eine Method Definition ist die systemische Beschreibung einer Methode. + +Kurzfristig kann sie code-first sein. + +Langfristig kann sie als DB-Definition oder konfigurierbares Profil existieren. + +Mögliche Struktur: + +```json +{ + "method_key": "maturity_progression", + "version": "v1", + "label": "Reifegradentwicklung", + "supported_domains": ["maturity_development", "personal_development"], + "supported_scope_types": ["initiative", "roadmap_item", "action"], + "default_lifecycle_model": "maturity_lifecycle", + "roadmap_lane_types": ["maturity_stages", "capabilities", "practice", "evidence", "reflection"], + "roadmap_item_types": ["maturity_stage", "capability", "learning_step", "review_gate"], + "hook_points": ["on_evidence_required", "on_review_due", "on_next_action_requested"], + "signal_types": ["attention", "next_action", "evidence_required", "review_due"], + "node_types": ["human_task", "evidence_check", "review", "llm_prompt"], + "maturity": "basic" +} +``` + +--- + +## 14. Method Profile + +Ein Method Profile ist eine konkrete konfigurierte Ausprägung einer Methode. + +Beispiele: + +```text +cycle_based: + Zwei-Wochen-Zyklus mit Reviewpflicht + +maturity_progression: + Vierstufiges Reifegradmodell mit Evidence und Reflexion + +content_development: + Buchentwicklung mit Kapitelstruktur, Recherche, Review und Revision + +recurring_control: + Monatliche Wartungsroutine mit Eskalation bei verpasstem Durchlauf +``` + +Method Profiles brauchen langfristig: + +```text +- tenant_id optional +- method_key +- version +- name +- configuration_json +- allowed_node_types +- enabled_hooks +- default_workflows +- evidence_policy +- review_policy +- approval_policy +``` + +AP0.8 muss Method Profiles noch nicht vollständig implementieren. + +Aber die Architektur muss sie vorsehen. + +--- + +## 15. Development Roadmap + +Jede größere Entwicklung braucht eine grobe Roadmap. + +Die Roadmap ist nicht gleich Backlog und nicht gleich Maßnahmenliste. + +```text +RoadmapItem = Entwicklungsziel / Orientierung / geplanter Entwicklungsschritt +BacklogItem = konkreter möglicher Handlungsbedarf +Action = freigegebene operative Maßnahme +``` + +### 15.1 Roadmap-Struktur + +```text +Steerable Object + → Roadmap + → Roadmap Lane + → Roadmap Item + → BacklogItem + → Action +``` + +### 15.2 Warum Roadmap universell sein muss + +Eine Softwareentwicklung braucht z. B.: + +```text +- Feature Landscape +- Architekturentwicklung +- Releases +- technische Schulden +- Validierung +``` + +Eine Buchentwicklung braucht: + +```text +- Buchstruktur +- Kapitel +- Recherche +- Drafts +- Review +- Veröffentlichung +``` + +Eine persönliche Entwicklung braucht: + +```text +- Reifegradstufen +- Fähigkeiten +- Übungs-/Praxislinien +- Evidence +- Reflexion +- Assessments +``` + +Deshalb darf Roadmap nicht nur aus Milestones bestehen. + +--- + +## 16. Roadmap-Datenmodell + +### 16.1 roadmaps + +```sql +roadmaps ( + id UUID PRIMARY KEY, + tenant_id UUID NOT NULL, + scope_type VARCHAR(64) NOT NULL, + scope_id UUID NOT NULL, + title VARCHAR(255) NOT NULL, + roadmap_type VARCHAR(64) NOT NULL, + status VARCHAR(32) NOT NULL, + created_at TIMESTAMP NOT NULL, + updated_at TIMESTAMP NOT NULL +) +``` + +`roadmap_type`: + +```text +product +program +project +content +personal_development +maturity +operations +learning +custom +``` + +### 16.2 roadmap_lanes + +```sql +roadmap_lanes ( + id UUID PRIMARY KEY, + tenant_id UUID NOT NULL, + roadmap_id UUID NOT NULL, + title VARCHAR(255) NOT NULL, + lane_type VARCHAR(64) NOT NULL, + sort_order INTEGER NOT NULL DEFAULT 0, + created_at TIMESTAMP NOT NULL, + updated_at TIMESTAMP NOT NULL +) +``` + +`lane_type`: + +```text +milestones +features +maturity_stages +capabilities +chapters +research +cycles +releases +learning_path +architecture +risks +dependencies +custom +``` + +### 16.3 roadmap_items + +```sql +roadmap_items ( + id UUID PRIMARY KEY, + tenant_id UUID NOT NULL, + roadmap_id UUID NOT NULL, + lane_id UUID NULL, + parent_item_id UUID NULL, + title VARCHAR(255) NOT NULL, + description TEXT DEFAULT '', + item_type VARCHAR(64) NOT NULL, + status VARCHAR(32) NOT NULL, + target_date DATE NULL, + sort_order INTEGER NOT NULL DEFAULT 0, + metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb, + created_at TIMESTAMP NOT NULL, + updated_at TIMESTAMP NOT NULL +) +``` + +`item_type`: + +```text +milestone +maturity_stage +feature +capability +phase +release +chapter +research_topic +work_cycle +learning_step +review_gate +decision_gate +architecture_step +dependency +risk_reduction +custom +``` + +--- + +## 17. Milestone-Entscheidung + +Milestone soll nicht als isoliertes Primärobjekt starten. + +Entscheidung: + +```text +Milestone = RoadmapItem(type = milestone) +``` + +Begründung: + +- Meilensteine sind nur eine RoadmapItem-Art. +- Reifegrade, Features, Kapitel, Releases und Lernschritte brauchen dieselbe Roadmap-Struktur. +- Eine separate Milestone-Tabelle würde später zu Parallelmodellen führen. +- RoadmapItems erlauben universellere Entwicklungspfade. + +--- + +## 18. Backlog und Action + +### 18.1 BacklogItem + +Ein BacklogItem ist ein möglicher Handlungsbedarf. + +Beispiele: + +```text +- Idee +- Risiko +- Vorschlag +- Research-Frage +- Feature-Slice +- Reifegrad-Lücke +- Kapitelbedarf +- Verbesserungsbedarf +``` + +Ein BacklogItem ist noch keine freigegebene Maßnahme. + +### 18.2 Action + +Eine Action ist eine freigegebene operative Maßnahme. + +Sie ist konkret, statusfähig und zuweisbar. + +### 18.3 Beziehungen + +BacklogItems und Actions können auf RoadmapItems einzahlen. + +Mögliche Felder: + +```text +backlog_items.roadmap_item_id NULL +actions.roadmap_item_id NULL +``` + +Langfristig kann ein generisches Relationsmodell folgen. + +--- + +## 19. Blocker + +Ein Blocker ist ein eigenes Steuerungsobjekt. + +Er kann sich beziehen auf: + +```text +- Initiative +- RoadmapItem +- BacklogItem +- Action +- WorkCycle +- Review +``` + +AP0.8 sollte mindestens ermöglichen: + +```text +blockers.initiative_id +blockers.action_id NULL +blockers.roadmap_item_id NULL +``` + +Ein Blocker ist nicht nur `action.status = blocked`. + +`action.status = blocked` bleibt ein kompatibler operativer Status, aber der Blocker als Objekt trägt Kontext, Ursache und Steuerungslogik. + +--- + +## 20. Signals + +Signals sind erste sichtbare Ergebnisse der Steuerungsengine. + +### 20.1 Signal Types + +```text +attention +next_action +review_due +evidence_required +escalation +blocker_signal +progress_signal +risk_signal +decision_required +dependency_signal +dod_signal +workflow_trigger +``` + +AP0.8 soll aktiv liefern: + +```text +attention +next_action +``` + +Weitere Signal Types werden fachlich vorbereitet. + +### 20.2 AttentionItem + +Ein AttentionItem sagt: + +> Dieser Steuerungspunkt braucht Aufmerksamkeit. + +Beispiele: + +```text +- offene Blocker +- blockierte Actions +- RoadmapItem at_risk +- BacklogItem accepted ohne Action +- RoadmapItem planned ohne BacklogItems +- Initiative ohne nächste Maßnahme +``` + +### 20.3 NextActionCandidate + +Ein NextActionCandidate sagt: + +> Dies ist eine sinnvolle nächste Handlung. + +Beispiele: + +```text +- BacklogItem in Action umwandeln +- Blocker klären +- RoadmapItem strukturieren +- WBS erstellen +- Evidence sammeln +- Review durchführen +- Dependency analysieren +- DoD definieren +``` + +--- + +## 21. Workflow Engine – Zielbild + +Die spätere Workflow Engine sollte nicht als beliebige freie Automatisierungsplattform starten. + +Sie sollte fachlich über Hooks und Nodes strukturiert werden. + +```text +Hook Point + → Workflow Binding + → Workflow Definition + → Workflow Node + → Signal / State Change / Task / Result +``` + +--- + +## 22. Hook Points + +Hook Points sind fachlich stabile Einhängepunkte. + +Initiale Hook-Kategorien: + +```text +intake +structure +planning +execution +monitoring +review +adaptation +closure +``` + +Beispiele: + +```text +on_intake_created +on_scope_clarification_needed +on_structure_required +on_wbs_required +on_plan_commit_required +on_dependency_analysis_required +on_next_action_requested +on_execution_started +on_progress_updated +on_blocker_created +on_status_changed +on_dod_definition_required +on_dod_check_required +on_evidence_required +on_review_due +on_replan_required +on_closure_requested +``` + +AP0.8 muss Hooks noch nicht als ausführbare Workflows implementieren. + +Aber Attention/NextAction sollte bereits `hook_key` oder `reason_code` nutzen, damit die spätere Einhängung möglich bleibt. + +--- + +## 23. Workflow Node Types + +Die spätere Workflow Engine braucht unterschiedliche Node-Typen. + +Initiale fachliche Node-Taxonomie: + +### 23.1 Signal Nodes + +```text +signal_listener +signal_emitter +attention_generator +next_action_generator +``` + +Zweck: + +- Signale wahrnehmen +- Signale erzeugen +- Attention Items erzeugen +- NextActionCandidates erzeugen + +### 23.2 Rule Nodes + +```text +rule_evaluator +condition_check +policy_check +``` + +Zweck: + +- Regeln prüfen +- Bedingungen auswerten +- Policies anwenden + +### 23.3 Human Nodes + +```text +human_task +approval +decision_gate +review +reflection +``` + +Zweck: + +- menschliche Arbeit +- Freigabe +- Entscheidung +- Review +- Reflexion + +### 23.4 AI / Agent Nodes + +```text +llm_prompt +agent_task +agent_review +agent_plan +agent_analysis +``` + +Zweck: + +- LLM-Aufruf +- Agentenauftrag +- Agenten-Review +- Plan-/Analysevorschlag + +### 23.5 Tool Nodes + +```text +tool_call +mcp_call +external_api_call +document_lookup +repository_lookup +``` + +Zweck: + +- Werkzeuge ausführen +- externe Systeme anbinden +- Dokumente oder Repos durchsuchen + +### 23.6 State Nodes + +```text +state_transition +status_update +assignment_update +roadmap_update +backlog_update +``` + +Zweck: + +- Zustände ändern +- Objekte aktualisieren +- Assignments setzen +- Roadmap/Backlog fortschreiben + +### 23.7 Validation Nodes + +```text +evidence_check +dod_check +dependency_analysis +risk_check +quality_gate +``` + +Zweck: + +- Nachweise prüfen +- Definition of Done prüfen +- Abhängigkeiten analysieren +- Risiken prüfen +- Qualitätsgate durchführen + +### 23.8 Notification Nodes + +```text +notification +reminder +escalation +``` + +Zweck: + +- informieren +- erinnern +- eskalieren + +--- + +## 24. Node-Kontrakt + +Jeder Node-Typ braucht langfristig einen klaren Vertrag. + +Mindestens: + +```text +- node_type +- purpose +- allowed_inputs +- outputs +- side_effects +- actor_responsibility +- tenant_context_required +- capability_required +- audit_required +- failure_behavior +- retry_policy optional +- human_approval_required optional +``` + +AP0.8 muss diesen Kontrakt nicht technisch vollständig bauen. + +Aber die Node-Taxonomie muss fachlich dokumentiert sein. + +--- + +## 25. Agentensysteme und KI-Steuerung + +### 25.1 Grundentscheidung + +Kairo sollte keine vollständige eigene Agentenplattform bauen. + +Kairo sollte Agentensysteme als Provider anbinden können. + +```text +Kairo: + - entscheidet Kontext + - wählt Methode/Hook/Workflow + - erzeugt Auftrag + - prüft Rückgabe + - speichert Ergebnis + - erzeugt Signal / Action / Evidence + +Agentensystem: + - führt Analyse oder Task aus + - erzeugt Vorschlag oder Ergebnis + - liefert strukturierte Antwort zurück +``` + +### 25.2 Agenten sind Actors + +Agenten bleiben im Kairo-Modell Actors. + +Das ist wichtig für: + +- Verantwortlichkeit +- Audit +- Assignments +- Sichtbarkeit +- Tenant-Kontext + +### 25.3 Agenten führen Steps aus, aber steuern nicht autonom Kairo + +Agenten dürfen nicht ohne Gate: + +- Roadmaps verändern +- Actions löschen +- strategische Priorität ändern +- Steering Method ändern +- Workflow Definitions ändern +- Rechte ändern + +--- + +## 26. AP0.4 Prompt Registry + +AP0.4 ist als Prompt-/Workflow-Vorleistung vorhanden. + +Im neuen Zielbild wird AP0.4 eingeordnet als: + +```text +Prompt Registry + → später verwendbar für Node-Typ `llm_prompt` +``` + +AP0.4 soll aktuell nicht weiter als Produktfeature ausgebaut werden. + +Es bleibt eingefroren, bis die Method-/Workflow-Schicht fachlich und strukturell steht. + +--- + +## 27. Welche Methoden sollen fachlich möglich sein? + +### 27.1 Produktentwicklung + +```text +Domain: product_development +Lifecycle: product/project hybrid +Methoden: +- milestone_driven +- cycle_based +- kanban +- hybrid +Roadmap: +- features +- architecture +- releases +- validation +- risks +``` + +### 27.2 Buchentwicklung + +```text +Domain: content_development +Lifecycle: content_development_lifecycle +Methoden: +- chapter_based +- draft_review +- research_driven +Roadmap: +- chapters +- research topics +- drafts +- reviews +- publication steps +``` + +### 27.3 Persönliche Reifegradentwicklung + +```text +Domain: maturity_development +Lifecycle: maturity_lifecycle +Methoden: +- maturity_progression +- habit_based +- coaching_cycle +Roadmap: +- maturity stages +- capabilities +- practices +- evidence +- reflection +``` + +### 27.4 Programmsteuerung + +```text +Domain: program +Lifecycle: program_lifecycle +Methoden: +- portfolio_coordination +- dependency_management +- benefit_realization +Roadmap: +- strategic outcomes +- initiatives +- dependencies +- resources +- benefits +``` + +### 27.5 Routinen/Betrieb + +```text +Domain: routine_operations +Lifecycle: routine_lifecycle +Methoden: +- recurring_control +- checklist_based +- exception_driven +Roadmap: +- routines +- cycles +- checks +- exceptions +``` + +--- + +## 28. AP0.8 – Konsequenz + +Der bestehende AP0.8-Entwurf muss vor Umsetzung überarbeitet werden. + +Der bisherige Entwurf mit: + +```text +Attention +Blocker +BacklogItem +Milestone +``` + +ist fachlich nicht falsch, aber zu eng. + +Neuer AP0.8-Titel: + +```text +AP0.8 – Steering & Development Roadmap Foundation +``` + +AP0.8 soll nicht die vollständige Engine bauen, aber die tragfähige Grundlage schaffen. + +--- + +## 29. AP0.8 Soll-Scope + +### Teil 0 – Engine Decision dokumentieren + +Dieses Dokument oder eine verdichtete Fassung ins Repo übernehmen. + +### Teil 1 – Steering Context Foundation + +Implementieren oder zumindest als Migration vorbereiten: + +```text +steering_contexts +``` + +Minimal aktiv: + +```text +scope_type = initiative +scope_type = roadmap_item +scope_type = action optional +``` + +### Teil 2 – Roadmap Foundation + +Implementieren: + +```text +roadmaps +roadmap_lanes +roadmap_items +``` + +Milestone wird RoadmapItem. + +### Teil 3 – BacklogItem + +Implementieren: + +```text +backlog_items +``` + +Mit optionalem Bezug: + +```text +roadmap_item_id +``` + +### Teil 4 – Blocker + +Implementieren: + +```text +blockers +``` + +Mit optionalem Bezug: + +```text +action_id +roadmap_item_id +``` + +### Teil 5 – Signals + +Implementieren: + +```text +AttentionItem als Read Model +NextActionCandidate als Read Model +``` + +Regelbasiert, ohne KI. + +### Teil 6 – UI minimal + +Im Vorhaben-Detail: + +```text +Roadmap +Backlog +Blocker +Attention +``` + +Keine große Designer-UI. + +--- + +## 30. AP0.8 Nicht-Scope + +Nicht bauen: + +```text +- vollständige Workflow Runtime +- Workflow Designer +- Method Designer +- tenant-konfigurierbare Method Profiles +- vollständige Node Execution Engine +- LLM-Step-Ausführung +- Agentenlaufsteuerung +- MCP +- WBS-Generator +- Dependency Engine +- DoD Engine +- vollständige Evidence-/Review-Engine +- Kanban Board +- Sprint Board +- Burndown +- Velocity +- Gantt +- Kalenderintegration +``` + +--- + +## 31. AP0.8 Muss aber vorbereiten + +AP0.8 muss fachlich und strukturell vorbereiten: + +```text +- Hook Points +- Signal Types +- RoadmapItem-Typen +- Steering Domains +- Lifecycle Models +- Method Keys +- spätere Workflow Node Types +- spätere Agent Provider +- spätere LLM Prompt Steps +- spätere Tool/MCP Steps +``` + +--- + +## 32. Komplexitätsregel für Implementierung + +Bei jeder Implementierungsentscheidung gilt: + +```text +Baue nur, was für AP0.8 sichtbar nutzbar oder strukturell notwendig ist. +Dokumentiere, was später kommt. +Verbaue spätere Workflow-/Method-/Agent-Fähigkeit nicht. +``` + +Das bedeutet: + +- Roadmap Foundation ja +- Backlog/Blocker ja +- Attention/NextAction ja +- Workflow Runtime nein +- KI-Ausführung nein +- Method Designer nein + +--- + +## 33. Offene AP0.8-Entscheidungen + +Vor finalem AP0.8-Prompt zu entscheiden: + +1. Wird `steering_contexts` in AP0.8 wirklich implementiert oder nur dokumentiert? +2. Wird `actions.roadmap_item_id` direkt ergänzt? +3. Wird `backlog_items.roadmap_item_id` direkt ergänzt? +4. Wird `blockers.roadmap_item_id` direkt ergänzt? +5. Welche `roadmap_item.status`-Werte gelten initial? +6. Welche `roadmap_item.item_type`-Werte gelten initial? +7. Welche `roadmap_type`-Werte gelten initial? +8. Welche minimalen UI-Elemente reichen? +9. Wird AP0.8 in einem großen Auftrag oder in AP0.8a/b/c umgesetzt? +10. Welche Capabilities werden eingeführt? + +--- + +## 34. Empfohlene Initialwerte + +### 34.1 roadmap_item.status + +```text +planned +active +at_risk +completed +moved +discarded +``` + +### 34.2 roadmap_item.item_type + +```text +milestone +maturity_stage +feature +capability +phase +release +chapter +research_topic +work_cycle +learning_step +review_gate +decision_gate +architecture_step +dependency +risk_reduction +custom +``` + +### 34.3 roadmap_type + +```text +product +program +project +content +personal_development +maturity +operations +learning +custom +``` + +### 34.4 steering_domain + +```text +program +project +product_development +content_development +personal_development +maturity_development +routine_operations +audit_review +agent_execution +custom +``` + +### 34.5 lifecycle_model + +```text +project_lifecycle +program_lifecycle +product_development_lifecycle +content_development_lifecycle +maturity_lifecycle +routine_lifecycle +review_lifecycle +agent_run_lifecycle +custom_lifecycle +``` + +--- + +## 35. Zusammenfassung der Entscheidung + +Kairo soll langfristig sehr unterschiedliche Entwicklungen steuern können: + +```text +- Softwareprodukt +- Buch +- persönliche Fähigkeit +- Reifegradziel +- Programm +- Routine +- Review/Audit +- Agentenarbeit +``` + +Dafür reicht weder eine einfache Aufgabenliste noch eine rein projektzentrierte Lifecycle-Logik. + +Die zentrale Architekturentscheidung lautet: + +```text +Kairo baut eine universelle fachliche Steuerungsengine mit: +- Steerable Objects +- Steering Contexts +- Steering Domains +- Lifecycle Models +- Steering Methods +- Method Profiles +- Development Roadmaps +- Hook Points +- Signals +- später Workflow Nodes +- später Agent-/LLM-/Tool-Steps +``` + +Aber: + +```text +AP0.8 baut nur die erste tragfähige Foundation: +- Steering Context vorbereiten +- Roadmap Foundation +- Backlog +- Blocker +- Attention / NextAction als erste Signals +``` + +Damit bleibt Kairo universell erweiterbar, ohne sofort eine unbeherrschbare Workflow-/Agentenplattform zu werden. + +--- + +## 36. Nächster Schritt + +Auf Basis dieses Dokuments sollte der bestehende AP0.8-Entwurf ersetzt oder deutlich überarbeitet werden. + +Empfohlenes Folgeartefakt: + +```text +Sprint0_AP0_8_Assignment_v0.2.md +``` + +Empfohlener Titel: + +```text +AP0.8 – Steering & Development Roadmap Foundation +```