From 8c3180266287ae4835fbc4ae3e5a602a24c686db Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 5 Jul 2026 18:06:26 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Vision=20v0.2=20und=20Dokumentations-?= =?UTF-8?q?=C3=9Cberarbeitung=20Welle=201?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Führendes Zielbild: Workspace-Portfolio, Initiative-Übersicht vs. Unterseiten, Vibe-Coder-Schnittstelle, Next-Action-Widget auf beiden Ebenen, Portfolio-Priorität und situativer Steuerungskontext. Canonical OM v0.2, Truth Table, Revision Program; v0.1-Docs mit Superseded-Banner; CLAUDE.md und Cursor-Rules aktualisiert. --- .cursor/rules/kairo-architecture.mdc | 57 ++- CLAUDE.md | 96 ++-- .../Kairo_System_Target_State_v0.1.md | 2 + .../DOCUMENTATION_REVISION_PROGRAM_v0.2.md | 197 ++++++++ .../Kairo_Canonical_Operating_Model_v0.1.md | 2 + .../Kairo_Canonical_Operating_Model_v0.2.md | 301 ++++++++++++ .../Kairo_Corrected_MVP_Roadmap_v0.1.md | 2 + .../Kairo_Implementation_Truth_Table_v0.1.md | 141 ++++++ .../Kairo_MVP_Usability_Recovery_Plan_v0.1.md | 2 + ...o_Product_Definition_and_MVP_Reset_v0.1.md | 2 + ...Kairo_Vision_and_Product_Direction_v0.2.md | 443 ++++++++++++++++++ 11 files changed, 1169 insertions(+), 76 deletions(-) create mode 100644 docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md create mode 100644 docs/product/Kairo_Canonical_Operating_Model_v0.2.md create mode 100644 docs/product/Kairo_Implementation_Truth_Table_v0.1.md create mode 100644 docs/product/Kairo_Vision_and_Product_Direction_v0.2.md diff --git a/.cursor/rules/kairo-architecture.mdc b/.cursor/rules/kairo-architecture.mdc index f1b9e1e..435806a 100644 --- a/.cursor/rules/kairo-architecture.mdc +++ b/.cursor/rules/kairo-architecture.mdc @@ -1,46 +1,45 @@ --- -description: Kairo Sprint-0 Architektur-Leitplanken und Dokumentenpriorität +description: Kairo Architektur-Leitplanken und Dokumentenpriorität globs: backend/**,frontend/**,docs/**,.gitea/** alwaysApply: true --- # Kairo Architecture Rules -Du arbeitest an **Jinkendo Kairo** (Sprint 0). Kairo ist mandantenfähig und Actor-first. +Du arbeitest an **Jinkendo Kairo**. Kairo ist mandantenfähig und Actor-first. -## Kairo Product Reset +## Führende Product-Dokumente (ab 2026-07-05) -Before implementing new functionality, preserve the canonical operating model: -Initiative, Project optional, Milestone, BacklogItem, Action, Assignment, Blocker, Decision, Evidence, Review, RecurringElement, AttentionItem, NextActionCandidate. +1. `docs/product/Kairo_Vision_and_Product_Direction_v0.2.md` +2. `docs/product/Kairo_Canonical_Operating_Model_v0.2.md` +3. `docs/product/Kairo_Implementation_Truth_Table_v0.1.md` + +## Product Vision + +Kairo ist Program Director — nicht To-do-Tool, nicht CRUD-Omnibus. + +- **Plan:** Roadmap / RoadmapItem (Gates, Meilensteine, Reifegrade) +- **Ist:** committete Actions (Arbeitspakete), später Tasks +- **IA:** Workspace (Ausführung), Initiative-Unterseiten (Steuerung, Ausführung, Plan, Eingang, Journey) +- **Bearbeitung:** Modal oder Objekt-Detail — nicht Inline-CRUD auf Übersichtsseiten Do not reduce Kairo to Initiative → Action. -Do not continue prompt/AI/workflow/MCP work before the operating model MVP is restored. - -Führende Product-Dokumente: `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md`, `Kairo_Canonical_Operating_Model_v0.1.md`, `Kairo_Corrected_MVP_Roadmap_v0.1.md`. +Do not expand InitiativeDetail as all-in-one CRUD wall. +Do not continue prompt/AI/workflow/MCP before Plan/Ist and Gates are modeled. ## Dokumentenpriorität bei Konflikten -1. `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md` -2. `docs/product/Kairo_Canonical_Operating_Model_v0.1.md` -3. `docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md` -4. `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md` -5. `docs/architecture/Kairo_Current_State_Gap_Analysis_AP0.1_AP0.6b_v0.1.md` -6. `docs/architecture/CLAUDE_Product_Direction_Addendum_v0.1.md` -7. `docs/architecture/Kairo_Tenant_Invariants_v0.1.md` -8. `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md` -9. `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` -10. `docs/reference/design-principles/alignment/*` -11. Mitai/Shinkan-Einzelprinzipien (nur Begründung, kein Scope) +1. Vision & Product Direction v0.2 +2. Canonical Operating Model v0.2 +3. Implementation Truth Table +4. System Target State, ADPs (Scope Lock) +5. Tenant Invariants, Principle Gate +6. Product Spec v0.2 (Referenz) +7. Sprint History (Completion Reports — nicht als Zielbild) ## Reference design principles -Referenzmaterial: - -- `docs/reference/design-principles/mitai/` -- `docs/reference/design-principles/shinkan/` -- `docs/reference/design-principles/alignment/` - -Nicht automatisch Implementierungs-Scope. Übernahme nur via Principle Gate oder Architecture Decision. +Referenzmaterial unter `docs/reference/design-principles/`. Nicht automatisch Scope. ## Harte Guardrails @@ -50,9 +49,9 @@ Nicht automatisch Implementierungs-Scope. Übernahme nur via Principle Gate oder - Keine hardcodierten Rechte, Prompts oder Fachkonfiguration - Nummerierte SQL-Migrationen; kein ad-hoc DDL in Routern - Keine Mitai-/Shinkan-Domänenlogik kopieren -- Kairo nicht auf Initiative → Action reduzieren -- Keine Prompt-/KI-/Workflow-/MCP-Erweiterung vor Operating-Model-MVP +- Keine parallele Steuerungslogik außerhalb `backend/steering/` +- Keine neuen OM-Tabellen ohne ADP (Scope Lock bis RoadmapItem-ADP) ## Abweichungen -Architecture Decision Proposal nach Vorlage in `docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md`. +Architecture Decision Proposal nach `docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md`. diff --git a/CLAUDE.md b/CLAUDE.md index 056cd9d..07d99fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,17 +12,25 @@ Welcher nächste Schritt bringt ein Vorhaben aktuell am wirkungsvollsten voran? ## 1. Aktueller Entwicklungsstand -Sprint 0 — Foundation und erster technischer Slice abgeschlossen (AP0.1–AP0.7, AP0.6b). +Foundation AP0.1–AP0.7 abgeschlossen. Operating Model AP0.8–AP0.10, Steering AP1.0–AP1.1b technisch geliefert. -Bereits vorhanden: +**Technisch vorhanden:** - Tenant, User, Actor, TenantContext, Auth, Capabilities -- Feature / Prompt / Config Registry -- Vorhaben / Maßnahmen (technischer Startpunkt, nicht Zielmodell) -- Workspace-GUI, Data Layer Minimum, Actor Directory -- Tenant-Invarianten, Product Reset (AP0.R1) +- OM-Entitäten (Backlog, Blocker, Milestone-Brücke, Evidence, Decision, Review, Recurring) +- `backend/steering/` (Lifecycle, Snapshot, Method Registry minimal) +- Workspace-GUI, Data Layer, Actor Directory -Nächster Fokus: MVP-Fachkern entlang des **Canonical Operating Models** — nicht weitere Foundation ohne Produktbezug. +**Produktlich fehlt (Vision):** + +- Getrennte IA (Ausführung / Plan / Eingang / Journey) — nicht Omnibus-InitiativeDetail +- RoadmapItem / Quality Gates — Milestone heute nur CRUD +- Plan vs. Ist, Abhängigkeiten, Task-Hierarchie +- Modal/Detail-Bearbeitung statt Inline-CRUD + +**Ist-Stand:** `docs/product/Kairo_Implementation_Truth_Table_v0.1.md` + +Nächster Fokus: **Dokumentations-Konsolidierung (Welle 2)**, dann **IA-Skeleton (AP1.2c)** und **RoadmapItem/Gates (AP1.4 + ADP)** — nicht weiteres Layout-Patching auf InitiativeDetail. --- @@ -30,34 +38,33 @@ Nächster Fokus: MVP-Fachkern entlang des **Canonical Operating Models** — nic Lies bei Projektstart in dieser Reihenfolge: -1. `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md` -2. `docs/product/Kairo_Canonical_Operating_Model_v0.1.md` -3. `docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md` -4. `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md` -5. `docs/architecture/Kairo_Current_State_Gap_Analysis_AP0.1_AP0.6b_v0.1.md` -6. `docs/architecture/CLAUDE_Product_Direction_Addendum_v0.1.md` +1. `docs/product/Kairo_Vision_and_Product_Direction_v0.2.md` +2. `docs/product/Kairo_Canonical_Operating_Model_v0.2.md` +3. `docs/product/Kairo_Implementation_Truth_Table_v0.1.md` +4. `docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md` +5. `docs/architecture/Kairo_System_Target_State_v0.1.md` +6. `docs/architecture/ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md` 7. `docs/architecture/Kairo_Tenant_Invariants_v0.1.md` 8. `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md` -9. `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` -10. `docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md` -11. `docs/architecture/Kairo_Architecture_References_v0.1.md` -12. `.cursor/rules/kairo-architecture.mdc` +9. `.cursor/rules/kairo-architecture.mdc` + +Historisch / Referenz (nicht führend bei Konflikt): + +- `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md` → superseded by Vision v0.2 +- `docs/product/Kairo_Canonical_Operating_Model_v0.1.md` → superseded by v0.2 +- `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md` — Referenz +- Sprint Completion Reports — historisch Bei Konflikten gilt folgende Auslegungsreihenfolge: -1. Product & MVP Reset -2. Canonical Operating Model -3. Corrected MVP Roadmap -4. ursprüngliche Product Spec -5. Current State & Gap Analysis -6. Product Direction Addendum -7. Tenant Invariants -8. Sprint-0 Principle Gate -9. Sprint-0 Foundation -10. Architecture References -11. Mitai/Shinkan Designprinzipien und Referenzcode - -Die frühere Product Spec bleibt gültige Grundlage, wird aber durch Reset und Operating Model konkretisiert. +1. Vision & Product Direction v0.2 +2. Canonical Operating Model v0.2 +3. Implementation Truth Table +4. System Target State / ADPs +5. Tenant Invariants, Principle Gate +6. Product Spec v0.2 (Referenz) +7. Sprint History +8. Mitai/Shinkan Designprinzipien (Referenz, kein Scope) --- @@ -69,23 +76,15 @@ Der aktuelle Vorhaben-/Maßnahmen-Slice ist nur ein technischer Startpunkt. Kairo ist ein operativer Program Director. -Das kanonische Operating Model umfasst: +Das kanonische Operating Model umfasst (Zielbild): -- Initiative / Vorhaben -- Project optional -- Milestone -- BacklogItem -- Action -- Assignment to Actor -- Blocker -- Decision -- Evidence -- Review -- RecurringElement -- AttentionItem -- NextActionCandidate +- Initiative / Programm, Project optional +- **Roadmap / RoadmapItem** (Gates, Meilensteine, Reifegrade) — Plan-Struktur +- BacklogItem (Eingang) → Action (Arbeitspaket) → Task (später) — Ist-Struktur +- Assignment, Blocker, Evidence, Decision, Review, RecurringElement +- AttentionItem, NextActionCandidate (Read Models via `backend/steering/`) -Neue Implementierungsaufträge müssen die Program-Director-Vision stützen oder eine konkret dokumentierte Umbaufalle verhindern. +**UI-Regel:** Workspace = Portfolio aller Initiativen. Initiative-Übersicht = operative Steuerung (Alltag). Pflege/Anlage auf Unterseiten. Vibe-Coder über Operational Actor Interface (API). Prompt-/KI-/Workflow-/MCP-Themen bleiben eingefroren, bis der MVP-Fachkern entlang des Operating Models trägt. @@ -143,6 +142,9 @@ Mitai/Shinkan-Prinzipien dürfen Kairo nicht überstimmen. ## 6. Nicht tun - Kairo auf `Initiative → Action` reduzieren oder als To-do-Tool behandeln +- InitiativeDetail weiter als Omnibus-CRUD-Seite ausbauen (Layout-Patches) +- Inline-Listenformulare als Haupt-Bearbeitungs-Pattern einführen +- Meilensteine als Status-Dropdown ohne Gate-Verifikation behandeln - Prompt-/KI-/Workflow-/MCP-Arbeit vor Operating-Model-MVP - keine Mitai-Domänenlogik kopieren - keine Shinkan-Domänenlogik kopieren @@ -163,6 +165,6 @@ Bei notwendiger Abweichung erstelle ein Architecture Decision Proposal. ## 8. Nächste Entwicklungsschritte -Siehe `docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md` und Abschlussberichte AP0.7 / AP0.R1. +Siehe `docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md` und Vision v0.2. -Foundation AP0.1–AP0.7 ist abgeschlossen. **Strategiewechsel (2026-07-05):** AP1.0 Steering Foundation als nächstes Code-Paket — siehe `docs/architecture/ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md`. AP0.10c eingefroren. Keine parallele Steuerungslogik außerhalb `backend/steering/`. +Foundation AP0.1–AP1.1b technisch weit. **Produkt:** IA + RoadmapItem/Gates vor weiterem UI-Polish. Scope Lock: `ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md`. diff --git a/docs/architecture/Kairo_System_Target_State_v0.1.md b/docs/architecture/Kairo_System_Target_State_v0.1.md index 38d71f1..2c1d6da 100644 --- a/docs/architecture/Kairo_System_Target_State_v0.1.md +++ b/docs/architecture/Kairo_System_Target_State_v0.1.md @@ -1,6 +1,8 @@ # Kairo – System Target State ## v0.1 – Zielzustand des angedachten Gesamtsystems +> **Hinweis (2026-07-05):** Beschreibt das **Zielbild**, nicht den Implementierungsstand. Ist-Stand: [`Kairo_Implementation_Truth_Table_v0.1.md`](../product/Kairo_Implementation_Truth_Table_v0.1.md). v0.2 wird explizite Implementierungs-Marker pro Kapitel ergänzen. + **Status:** konsolidiertes Zielbild / Nordstern-Dokument **Stand:** 2026-07-05 **Zweck:** Beschreibung des angedachten späteren Zielzustands von Kairo als System, unabhängig von konkreten Implementierungsschnitten. diff --git a/docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md b/docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md new file mode 100644 index 0000000..ca6b1a0 --- /dev/null +++ b/docs/product/DOCUMENTATION_REVISION_PROGRAM_v0.2.md @@ -0,0 +1,197 @@ +# Kairo — Documentation Revision Program v0.2 + +**Status:** aktives Überarbeitungsprogramm +**Stand:** 2026-07-05 +**Auslöser:** Product Owner: Zielbild-Dokumente unzureichend, falsch oder irreführend; große Distanz zur Vision nach AP1.1b + +--- + +## 1. Ziel des Programms + +Alle Produkt- und Architektur-Dokumente so überarbeiten, dass: + +1. **Vision, Zielbild und Ist-Stand** klar getrennt sind +2. Kein Dokument so tut, als wäre **RoadmapItem / Gates / Plan-Ist** schon produktiv +3. Implementierungs-Agenten **nicht** wieder flache CRUD-UI als MVP verkaufen +4. Die **Product Owner Vision** (IA, Gates, Hierarchie, Journey) führend ist +5. Historische Sprint-Docs **archiviert** bleiben, aber nicht mehr irreführen + +--- + +## 2. Diagnose — warum die Distanz zur Vision so groß wirkt + +### 2.1 Dokumenten-Drift + +| Problem | Beispiel | +|---------|----------| +| **Zielbild ohne Ist-Kennzeichnung** | Target State beschreibt RoadmapItem; UI zeigt `milestones`-CRUD | +| **MVP-Roadmap suggeriert Nähe zum Ziel** | AP0.8 „Milestone minimal“ las sich wie „Meilenstein fertig“ | +| **Usability Recovery optimierte falsche Fläche** | AP1.1b verbesserte InitiativeDetail statt IA zu spalten | +| **Mehrere konkurrierende „führende“ Docs** | Product Reset, Spec, Canonical OM, Target State, Recovery Plan | +| **Completion Reports = Erfolg** | Technisch grün, produktlich nicht visionstauglich | +| **Begriffe inkonsistent** | Maßnahme = Action = Projekt? Unklar | + +### 2.2 Implementierungs-Drift + +```text +Dokumentiert: Initiative → Project → Roadmap → Backlog → Action → Task +Implementiert: Initiative → [parallel CRUD-Sektionen] → Action +``` + +### 2.3 Irreführende Erfolgssignale + +- Steering Snapshot v2 wirkt wie „Steuerung fertig“ +- Meilenstein-Formular mit `goal_description` wirkt wie „Gate-Modell“ +- Canonical OM listet Objekte, die **existieren**, aber **nicht ihre Rolle im Plan/Ist** erfüllen + +--- + +## 3. Neue Dokumenten-Schichten + +```text +Schicht A — Vision & Product Direction ← Product Owner Wahrheit +Schicht B — Canonical Operating Model ← Fachliches Regelwerk +Schicht C — Target State / Architecture ← Technisches Nordstern-Zielbild +Schicht D — Implementation Truth Table ← Was existiert wirklich (living doc) +Schicht E — Roadmap & Assignments ← Nächste Pakete, ehrlich priorisiert +Schicht F — Sprint History ← Completion Reports (historisch, banner) +Schicht G — Reference / Design Principles ← Nicht automatisch Scope +``` + +**Regel:** Schicht A–D vor jeder größeren Implementierung lesen. Schicht F nie als Zielbild missverstehen. + +--- + +## 4. Dokumenten-Inventar & Revisionsstatus + +### 4.1 Schicht A — Vision (neu / überarbeitet) + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `Kairo_Vision_and_Product_Direction_v0.2.md` | ✓ **neu, führend** | Pflege bei PO-Feedback | +| `Kairo_Product_Definition_and_MVP_Reset_v0.1.md` | ⚠ veraltet | → v0.2 oder Superseded-Banner; Inhalte in Vision v0.2 | +| `Jinkendo_Kairo_Product_Spec_v0.2.md` | ⚠ Referenz | Banner: Spec ≠ Ist; Konflikt → Vision v0.2 | +| `Kairo_MVP_Usability_Recovery_Plan_v0.1.md` | ⚠ teilweise falsch | → v0.2: IA-first, kein InitiativeDetail-Patching | + +### 4.2 Schicht B — Operating Model + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `Kairo_Canonical_Operating_Model_v0.1.md` | ⚠ unvollständig | → **v0.2**: Plan/Ist, Gates, IA, Hierarchie | +| `Kairo_Canonical_Operating_Model_v0.2.md` | ✓ neu | Pflege synchron zu Vision | + +### 4.3 Schicht C — Architecture / Target State + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `Kairo_System_Target_State_v0.1.md` | ✓ inhaltlich gut | → v0.2: explizite „Not implemented“-Markers pro § | +| `Kairo_Universal_Steering_Engine_Decision_v0.1.md` | ✓ Referenz | Cross-Ref zu Vision; kein MVP-Scope | +| `Kairo_Target_Architecture_Method_Driven_..._v0.1.md` | ✓ Referenz | Phase C klar markieren | +| `Kairo_Method_Design_Principles_v0.1.md` | ✓ Referenz | — | +| `Kairo_Core_Model_Decision_v0.2.md` | ✓ Referenz | — | +| `ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md` | ✓ gültig | Ergänzen: IA-Scope-Lock bis RoadmapItem-ADP | +| `Kairo_Operating_Model_Steering_Bridge_v0.1.md` | prüfen | Mit v0.2 OM abgleichen | +| `Kairo_Current_State_Gap_Analysis_AP0.1_AP0.6b_v0.1.md` | ⚠ veraltet | → **v0.2** bis AP1.1b | + +### 4.4 Schicht D — Truth Table + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `Kairo_Implementation_Truth_Table_v0.1.md` | ✓ **neu** | Bei jedem AP aktualisieren | + +### 4.5 Schicht E — Roadmap + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `Kairo_Corrected_MVP_Roadmap_v0.1.md` | ⚠ irreführend | → **v0.2**: ehrliche Phasen DOC/IA/Gates/Hierarchie | +| Sprint Assignments AP1.x | historisch + aktiv | Neue Assignments referenzieren Vision v0.2 | + +### 4.6 Schicht F — Sprint History + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `Sprint0_AP0_*_Completion_Report_*.md` | historisch | Standard-Banner oben | +| `Sprint1_AP1_*_Assignment_*.md` | teils aktiv | AP1.1b als „UX patch, not vision“ einordnen | + +### 4.7 Agenten-Konfiguration + +| Dokument | Status | Aktion | +|----------|--------|--------| +| `CLAUDE.md` | ⚠ veraltet | Lesereihenfolge → Vision v0.2 | +| `.cursor/rules/kairo-architecture.mdc` | ⚠ veraltet | Doc-Priorität + Stop CRUD-Wand | +| `Kairo_Architecture_References_v0.1.md` | ⚠ veraltet | → v0.2 | + +--- + +## 5. Revisions-Wellen + +### Welle 1 — Anker (2026-07-05) ✓ gestartet + +- [x] `Kairo_Vision_and_Product_Direction_v0.2.md` +- [x] `DOCUMENTATION_REVISION_PROGRAM_v0.2.md` (dieses Dokument) +- [x] `Kairo_Canonical_Operating_Model_v0.2.md` +- [x] `Kairo_Implementation_Truth_Table_v0.1.md` +- [x] Superseded-Banner auf v0.1-Kern docs +- [x] `CLAUDE.md` + `.cursor/rules` aktualisieren + +### Welle 2 — Zielbild präzisieren + +- [ ] `Kairo_System_Target_State_v0.2.md` — pro Kapitel: Status `target | partial | not_started` +- [ ] `Kairo_Corrected_MVP_Roadmap_v0.2.md` +- [ ] `Kairo_MVP_Usability_Recovery_Plan_v0.2.md` +- [ ] ADP: `RoadmapItem_and_Quality_Gate_Model_v0.1.md` (neu) +- [ ] ADP: `Operational_Actor_Interface_Vibe_Coder_v0.1.md` (neu — API-Spec) +- [ ] `Sprint0_Vibe_Coder_Handover_v0.2.md` — IA + Operational Interface + +### Welle 3 — Architektur-Konsolidierung + +- [ ] Target Architecture / Universal Steering Engine — Duplikate reduzieren, ein Master-Index +- [ ] `Kairo_Operating_Model_Steering_Bridge_v0.2.md` +- [ ] Method Design Principles — explizite MVP-Abgrenzung + +### Welle 4 — Sprint & Handover + +- [ ] `Sprint0_Vibe_Coder_Handover_v0.2.md` +- [ ] Completion Reports: archiv-Banner +- [ ] README.md — ehrlicher Produktstand + +--- + +## 6. Standard-Banner für superseded Dokumente + +Am Anfang superseded v0.1-Dateien einfügen: + +```markdown +> **⚠ Superseded (2026-07-05):** Dieses Dokument ist nicht mehr führend. +> Verwende stattdessen `[Neues Dokument](pfad)`. +> Inhalt bleibt als historische Referenz erhalten. +``` + +--- + +## 7. Qualitätskriterien für überarbeitete Docs + +Jedes Kern-Dokument muss enthalten: + +1. **Status** (führend | Referenz | historisch | superseded) +2. **Stand** und **Ersetzt**-Hinweis +3. Explizite **Nicht-Scope**-Abschnitte +4. Wo relevant: **Ist vs. Ziel**-Tabelle +5. Verweis auf **Truth Table** für Implementierungsstand +6. Keine Formulierung, die CRUD-Listen als Steuerung verkauft + +--- + +## 8. Product Owner Review-Gates + +Vor Abschluss Welle 2: + +- [ ] PO bestätigt: Begrifflichkeit (Arbeitspaket, Gate, Plan/Ist) stimmt +- [ ] PO bestätigt: IA-Zielbild (§7 Vision) stimmt +- [ ] PO bestätigt: Roadmap-Reihenfolge (IA vor Gate-Schema) stimmt + +Erst danach: **AP1.2c** (IA-Skeleton) implementieren. + +--- + +*Führendes Vision-Dokument: `Kairo_Vision_and_Product_Direction_v0.2.md`* diff --git a/docs/product/Kairo_Canonical_Operating_Model_v0.1.md b/docs/product/Kairo_Canonical_Operating_Model_v0.1.md index 51db013..a23ffe8 100644 --- a/docs/product/Kairo_Canonical_Operating_Model_v0.1.md +++ b/docs/product/Kairo_Canonical_Operating_Model_v0.1.md @@ -1,6 +1,8 @@ # Jinkendo Kairo ## Canonical Operating Model v0.1 +> **⚠ Superseded (2026-07-05):** Nicht mehr führend. Verwende [`Kairo_Canonical_Operating_Model_v0.2.md`](Kairo_Canonical_Operating_Model_v0.2.md) und [`Kairo_Vision_and_Product_Direction_v0.2.md`](Kairo_Vision_and_Product_Direction_v0.2.md). + Status: kanonisches Produktmodell Stand: 2026-07-05 diff --git a/docs/product/Kairo_Canonical_Operating_Model_v0.2.md b/docs/product/Kairo_Canonical_Operating_Model_v0.2.md new file mode 100644 index 0000000..82366c2 --- /dev/null +++ b/docs/product/Kairo_Canonical_Operating_Model_v0.2.md @@ -0,0 +1,301 @@ +# Jinkendo Kairo +## Canonical Operating Model v0.2 + +**Status:** kanonisches Fachmodell +**Stand:** 2026-07-05 +**Ersetzt:** `Kairo_Canonical_Operating_Model_v0.1.md` bei Konflikten +**Führende Vision:** `Kairo_Vision_and_Product_Direction_v0.2.md` + +--- + +## 1. Zweck + +Dieses Dokument definiert das **kanonische Operating Model** — inklusive Plan/Ist-Trennung, Quality Gates und Navigationsprinzipien. + +Es verhindert: + +- Reduktion auf `Initiative → Action` +- Meilensteine als Task-Listen +- CRUD-Omnibus-Seiten als Steuerungs-UI +- Verwechslung von **implementiertem** und **zielbildlichem** Stand + +**Implementierungsstand:** `Kairo_Implementation_Truth_Table_v0.1.md` + +--- + +## 2. Leitfrage + +> Welcher nächste Schritt bringt diesen steuerbaren Kontext jetzt am wirksamsten voran? + +Gilt auf **Ausführungs-Ebene** (Workspace, Next Action) und **Programm-Ebene** (Plan, Gates, Abweichungen). + +--- + +## 3. Operating Cycle + +Unverändert im Kern: + +```text +Capture → Triage → Structure → Commit → Execute → Verify → Review → Adapt → Next Action +``` + +**Neu in v0.2 — klare Zuordnung:** + +| Phase | Primäre Objekte | Primäre UI-Fläche | +|-------|-----------------|-------------------| +| Capture | BacklogItem, Blocker (Meldeeingang) | Eingang | +| Triage | BacklogItem | Eingang | +| Structure | RoadmapItem, Project | Plan | +| Commit | Action (+ Assignment) | Ausführung | +| Execute | Action, Task (später) | Ausführung / Workspace | +| Verify | Evidence | Objekt-Detail | +| Review | Review | Nachvollziehbarkeit | +| Adapt | Decision, RoadmapItem-Änderung | Plan + Nachvollziehbarkeit | +| Next Action | NextActionCandidate | Workspace + Steuerung | + +--- + +## 4. Objektmodell (Ziel) + +```text +Tenant + └── Actor + └── Initiative (Programm) + ├── Project optional + ├── Roadmap + │ └── RoadmapItem (milestone | maturity_stage | feature | review_gate | …) + │ └── Dependencies → andere RoadmapItems + ├── BacklogItem ──zahlt ein auf──► RoadmapItem + ├── Action (Arbeitspaket / committete operative Einheit) + │ ├── Task optional (später) + │ ├── ActionAssignment + │ ├── Blocker + │ └── Evidence + ├── Decision (Plan-Abweichung, Scope, Priorität) + ├── Review + ├── RecurringElement + └── AttentionItem / NextActionCandidate (Read Models) +``` + +### 4.1 MVP-Brücke (aktuell implementiert — nicht Ziel) + +```text +Initiative + ├── milestones (eigene Tabelle — ersetzbar durch RoadmapItem) + ├── backlog_items, actions, blockers, evidence, decisions, reviews, recurring + └── steering_context (Lifecycle, Method) +``` + +Die Brücke ist **technisch nutzbar**, **fachlich unzureichend** für Gates und Plan/Ist. + +--- + +## 5. Plan-Struktur vs. Ist-Struktur + +### Plan (Roadmap) + +- Entwicklungsrichtung und **überprüfbare Zielpunkte** +- RoadmapItems mit DoD, Abhängigkeiten, Terminen +- Kann sequenziell, parallel oder gemischt sein + +### Ist (Operativ) + +- Committete **Actions** mit Status, Assignments, Blockern, Evidence +- Entsteht durch **Commit** aus Backlog — nicht durch Roadmap-Deklaration allein + +### Abweichung + +- **Decision** dokumentiert: Plan ignoriert, verschoben, ersetzt +- Journey/Timeline zeigt Abweichungen über die Zeit + +--- + +## 6. Objektdefinitionen (erweitert) + +### Initiative + +Aktives Vorhaben / Programm mit Zielzustand, Lifecycle, Steuerungsmethode. + +### Project + +Optionale Unterstruktur — z. B. Stream, Teilprojekt, Release-Track. + +### RoadmapItem + +**Geplanter** Entwicklungsschritt oder **Quality Gate**. + +Typen (Auswahl): `milestone`, `maturity_stage`, `feature`, `review_gate`, `chapter`, `work_cycle`, … + +**Pflicht im Zielbild (nicht heute):** + +- prüfbare Kriterien (DoD) +- optional Abhängigkeiten +- Verifikation vor Status `reached` + +### Milestone (Product-Begriff) + += RoadmapItem mit Gate-Charakter. **Kein Task.** + +### BacklogItem + +Noch **nicht committeter** Handlungsbedarf. Kann auf RoadmapItem einzahlen. + +### Action (Product: Arbeitspaket) + +**Freigegebene** operative Einheit. Im heutigen UI „Maßnahme“. + +Im Zielbild oft **Projekt- oder Paket-Ebene**, nicht atomare Aufgabe. + +### Task (geplant) + +Kleinste ausführbare Einheit unter Action — methodenabhängig (WBS). + +### Blocker / Evidence / Decision / Review + +Wie v0.1; Evidence und Review sind **Gate-Verifikation** wesentlich. + +### NextActionCandidate / AttentionItem + +Read Models — keine parallele Steuerungslogik außerhalb `backend/steering/`. + +--- + +## 7. Quality Gate — Mindestanforderungen + +Ein Gate (Meilenstein) ist erst **modellgerecht**, wenn: + +| # | Anforderung | +|---|-------------| +| 1 | DoD / prüfbare Kriterien definiert | +| 2 | Abhängigkeiten zu anderen Gates modelliert (sequenziell oder parallel) | +| 3 | `reached` nur mit Evidence und/oder Review — nicht per Dropdown | +| 4 | `moved` / `discarded` erzeugt Decision-Spur | +| 5 | Actions/BacklogItems können dem Gate zugeordnet werden | + +**Heute:** nur (1) teilweise als Freitext `goal_description` — Rest fehlt. + +--- + +## 8. UI-Prinzipien (verbindlich) + +### 8.1 Drei Ebenen + +| Ebene | Zweck | CRUD | +|-------|-------|------| +| **Workspace** | Alle Initiativen — Portfolio-Überblick | nein | +| **Initiative-Übersicht** | Operative Steuerung eines Vorhabens — **reicht im Alltag** | nein (nur Steuerung + Navigation) | +| **Unterseiten** | Plan, Ausführung, Eingang, Journey, Objekt-Details | ja (Anlage, Pflege, Bearbeitung) | + +Heutige `InitiativeDetailPage` vermischt Übersicht und Pflege — **Anti-Pattern**. + +### 8.2 Getrennte Hauptflächen (Unterseiten) + +- **Plan** — Roadmap, Gates, Abhängigkeiten +- **Ausführung** — Arbeitspakete-Hub, Zuweisungen +- **Eingang** — Backlog, Triage +- **Nachvollziehbarkeit** — Decisions, Reviews, Journey + +### 8.3 Bearbeitungs-Pattern + +Anlegen/Bearbeiten in **Modal** oder **Objekt-Detail-Route** — nicht als Inline-Listenformular auf Übersichtsseiten (weder Workspace noch Initiative-Übersicht). + +### 8.4 Steuerungsfragen pro Ebene + +**Workspace:** Welches Vorhaben braucht Aufmerksamkeit? Wo stehe ich insgesamt? + +**Initiative-Übersicht:** Wo steht dieses Programm — und was ist hier als Nächstes dran? Was blockiert? + +**Unterseiten:** Wie pflege/plane ich Struktur und Inhalte? + +### 8.5 Operational Actor Interface (Vibe-Coder) + +Agenten-Actors nutzen dieselbe fachliche API wie die UI — Capability-gated, auditiert: + +- Kontext/Snapshot lesen +- Next Action anfragen +- Status, Blocker, Evidence, Decision-Unterlagen ablegen +- Backlog/Gates **vorschlagen**, nicht heimlich committen oder schließen + +Spec: Vision v0.2 §7.5; Implementierung AP1.7 nach IA-Skeleton. + +--- + +## 9. Statusmodelle + +Wie v0.1 für implementierte Objekte. + +**RoadmapItem** (Ziel — aus Target State): + +- planned, active, at_risk, reached, moved, discarded + +Gate-Übergang `→ reached` nur über Verify-Pfad. + +--- + +## 10. Next Action / Attention Logic + +Regeln aus v0.1 bleiben; ergänzt: + +10. Gates `at_risk` oder überfällig sichtbar machen +11. Plan-Ist-Abweichung ohne Decision sichtbar machen (später) +12. Unverknüpfte BacklogItems zu aktivem Gate sichtbar machen (später) + +Implementierung: `backend/steering/` — keine parallelen Heuristiken. + +--- + +## 11. Data Layer + +Read-orientierte Steuerungs-Sichten: + +```text +data_layer.workspace +data_layer.initiatives +data_layer.initiative_snapshot (Graph: actions + linked context) +data_layer.attention +data_layer.actors +``` + +Geplant: `roadmap`, `journey`, `plan_ist_delta` + +--- + +## 12. MVP-Nutzbarkeit (neu definiert) + +Kairo ist **MVP-nah in der Vision**, wenn ein Nutzer **ohne CRUD-Wand**: + +1. Auf dem **Workspace** in ≤30s die nächste Arbeit findet +2. Pro Vorhaben **Steuerung**, **Ausführung**, **Plan** getrennt navigiert +3. Ein **Gate** mit DoD und Verifikation durchspielt (Plan → Commit → Verify → reached) +4. Eine **Decision** als Plan-Abweichung dokumentiert und in der Journey sieht +5. Blocker und Next Actions **am richtigen Objekt** sieht + +**Nicht MVP-nah:** Alle OM-Tabellen als parallele Listen auf einer Seite. + +--- + +## 13. Agenten-Regel + +Wie v0.1. Zusätzlich: + +Agenten (inkl. **Vibe-Coder**) sind **Actors** mit definierter **Operational Actor Interface** (Vision §7.5): + +- dürfen Kontext lesen, Next Action anfragen, Status/Evidence/Blocker/Decision-Unterlagen ablegen +- dürfen RoadmapItems und Backlog **vorschlagen** +- dürfen **nicht** heimlich committen, Gates ohne Verify schließen oder strategische Steuerung ändern + +UI-Unterseiten und Agent-API müssen **fachlich äquivalent** bleiben. + +--- + +## 14. Auslegungsreihenfolge + +1. `Kairo_Vision_and_Product_Direction_v0.2.md` +2. Dieses Dokument (v0.2) +3. `Kairo_System_Target_State_v0.1.md` / v0.2 +4. ADPs (Scope Lock, RoadmapItem) +5. Product Spec v0.2 (Referenz) + +--- + +*v0.1 bleibt als historische Referenz erhalten.* diff --git a/docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md b/docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md index e84424e..cb22d58 100644 --- a/docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md +++ b/docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md @@ -1,6 +1,8 @@ # Jinkendo Kairo ## Corrected MVP Roadmap v0.1 +> **⚠ Superseded (2026-07-05):** Roadmap wird in Welle 2 als v0.2 überarbeitet. Bis dahin: [`Kairo_Vision_and_Product_Direction_v0.2.md`](Kairo_Vision_and_Product_Direction_v0.2.md) §11 und [`DOCUMENTATION_REVISION_PROGRAM_v0.2.md`](DOCUMENTATION_REVISION_PROGRAM_v0.2.md). + Status: korrigierte Roadmap nach Product Reset Stand: 2026-07-05 diff --git a/docs/product/Kairo_Implementation_Truth_Table_v0.1.md b/docs/product/Kairo_Implementation_Truth_Table_v0.1.md new file mode 100644 index 0000000..8802462 --- /dev/null +++ b/docs/product/Kairo_Implementation_Truth_Table_v0.1.md @@ -0,0 +1,141 @@ +# Kairo — Implementation Truth Table v0.1 + +**Status:** living document — bei jedem AP aktualisieren +**Stand:** 2026-07-05 (nach AP1.1b) +**Zweck:** Ehrliche Trennung von **implementiert**, **teilweise**, **nur API/Schema**, **nur Dokumentiert** + +Verhindert, dass Zielbild-Dokumente als Ist-Stand gelesen werden. + +--- + +## Legende + +| Symbol | Bedeutung | +|--------|-----------| +| ✓ | Nutzbar im Alltag (GUI + API) | +| ◐ | Backend/API/Schema, GUI unzureichend oder falsch platziert | +| ○ | Nur Schema oder Stub | +| ✗ | Nicht vorhanden | +| 📄 | Nur in Architektur-Docs beschrieben | + +--- + +## Foundation + +| Element | Stand | Anmerkung | +|---------|-------|-----------| +| Tenant / Membership | ✓ | | +| User ≠ Actor | ✓ | | +| Actor Directory | ✓ | human, agent, working_group, external_system | +| Capabilities | ✓ | Keine Objekt-Sichtbarkeit | +| Auth / Session | ✓ | | +| Audit (Auth/Admin) | ◐ | Nicht für alle OM-Events | +| Migrationen nummeriert | ✓ | Schema 009 | + +--- + +## Operating Model — Persistenz + +| Element | Stand | Anmerkung | +|---------|-------|-----------| +| Initiative | ✓ | | +| Project | ○ | Schema/API teils; **keine GUI** | +| Action | ✓ | UI-Label „Maßnahme“ | +| ActionAssignment | ✓ | | +| BacklogItem | ✓ | | +| Blocker | ✓ | `action_id` optional | +| Milestone | ◐ | Tabelle MVP-Brücke; kein Gate | +| Evidence | ✓ | | +| Decision | ✓ | | +| Review | ✓ | | +| RecurringElement | ✓ | | +| Task (unter Action) | ✗ | | +| Roadmap | ✗ | 📄 Target State | +| RoadmapItem | ✗ | 📄; Milestone soll hierhin | +| RoadmapItem Dependencies | ✗ | | +| Plan-Ist-Verknüpfung | ✗ | Backlog/Action → Gate | + +--- + +## Steering + +| Element | Stand | Anmerkung | +|---------|-------|-----------| +| steering_contexts (009) | ✓ | Lifecycle, method_key | +| backend/steering/ lifecycle | ✓ | | +| Signal Engine | ◐ | Regeln begrenzt | +| Method Registry | ◐ | generic_operating, product_milestone_driven | +| NextActionCandidate | ◐ | API + Widget; nicht konfigurierbar auf beiden Ebenen | +| Portfolio-Priorität (Initiativen) | ✗ | | +| Situativer Steuerungskontext (Next Action) | ✗ | 📄 Vision §7.6 | +| AttentionItem | ◐ | | +| Initiative Steering Snapshot | ✓ | Graph für Actions + linked | +| operating_phase | ◐ | deprecated flag; noch im Snapshot | +| Hook Orchestrator | ✗ | AP1.3 geplant | +| Structure Builder | ✗ | 📄 | +| DoD Engine | ✗ | 📄 | + +--- + +## UI / Information Architecture + +| Sicht | Stand | Anmerkung | +|-------|-------|-----------| +| Workspace (Portfolio aller Initiativen) | ◐ | Widgets; keine Initiative-Kacheln mit Steuerungssignal | +| Initiative-Übersicht (operative Steuerung) | ✗ | Heute: Omnibus InitiativeDetail | +| Initiative Unterseiten (Plan, Inbox, …) | ✗ | | +| Operational Actor Interface (Vibe-Coder) | ✗ | Actors `agent` in DB; keine Agent-API | +| Action Detail-Seite | ✗ | | +| Gate Detail-Seite | ✗ | | +| Modal-Bearbeitung | ✗ | Inline-Formulare überall | +| Admin-UI | ✗ | | + +--- + +## Milestone / Gate — Soll vs. Ist + +| Gate-Anforderung (Vision) | Ist | +|---------------------------|-----| +| DoD / prüfbare Kriterien | ◐ `goal_description` Freitext, kein Kriterienmodell | +| Zieltermin | ◐ `target_date` | +| Abhängigkeiten | ✗ | +| parallel vs. sequenziell | ✗ | +| Verify vor `reached` | ✗ Status-Dropdown | +| Decision bei `moved` | ✗ | +| Quality-Gate-Semantik | ✗ | + +--- + +## Terminologie im UI + +| Vision | UI heute | +|--------|----------| +| Arbeitspaket | Maßnahme | +| Quality Gate | Meilenstein (CRUD) | +| Programm | Vorhaben | +| Plan | (nicht sichtbar) | + +--- + +## Dokumente vs. Realität + +| Risiko | Mitigation | +|--------|------------| +| Target State liest sich wie fertig | Truth Table + Vision v0.2 | +| Completion Reports = Vision erreicht | Banner „technisch, nicht produktlich“ | +| Usability Recovery → mehr InitiativeDetail | Recovery Plan v0.2 → IA-first | + +--- + +## Nächste erwartete Änderungen (nach DOC-Programm) + +| AP | Erwartete Truth-Table-Änderung | +|----|--------------------------------| +| AP1.2c | IA-Routen ◐→✓, Modal-Pattern ◐ | +| AP1.4 | RoadmapItem ○→◐, Gate Verify ◐ | +| AP1.5 | Task ○, Project GUI ◐ | +| AP1.8 | Portfolio-Priorität ○, situativer Kontext ○ | + +--- + +*Aktualisieren bei: jedem Merge auf develop mit produktrelevantem AP.* diff --git a/docs/product/Kairo_MVP_Usability_Recovery_Plan_v0.1.md b/docs/product/Kairo_MVP_Usability_Recovery_Plan_v0.1.md index 2c4c7c3..8c1f08c 100644 --- a/docs/product/Kairo_MVP_Usability_Recovery_Plan_v0.1.md +++ b/docs/product/Kairo_MVP_Usability_Recovery_Plan_v0.1.md @@ -1,5 +1,7 @@ # Kairo — MVP Usability Recovery Plan +> **⚠ Teilweise superseded (2026-07-05):** Strategie InitiativeDetail-Patching und AP-Reihenfolge → [`Kairo_Vision_and_Product_Direction_v0.2.md`](Kairo_Vision_and_Product_Direction_v0.2.md) und [`DOCUMENTATION_REVISION_PROGRAM_v0.2.md`](DOCUMENTATION_REVISION_PROGRAM_v0.2.md). Welle 2 liefert Recovery Plan v0.2. + **Status:** Planungsdokument (Product Direction) **Stand:** 2026-07-05 **Auslöser:** AP0.8–0.10 liefern Entitäten, aber **keinen täglich nutzbaren Steuerungswert** — schlechter als To-do-/PM-Tools für den Alltag. diff --git a/docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md b/docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md index 1424f35..6edba2e 100644 --- a/docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md +++ b/docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md @@ -1,6 +1,8 @@ # Jinkendo Kairo ## Product Definition & MVP Reset v0.1 +> **⚠ Superseded (2026-07-05):** Produktvision und Leitlinien → [`Kairo_Vision_and_Product_Direction_v0.2.md`](Kairo_Vision_and_Product_Direction_v0.2.md). Fachmodell → [`Kairo_Canonical_Operating_Model_v0.2.md`](Kairo_Canonical_Operating_Model_v0.2.md). + Status: Steuerungsdokument / kanonischer Reset Stand: 2026-07-05 Zweck: Wiederherstellung der ursprünglichen Kairo-Produktlinie nach AP0.1–AP0.6b diff --git a/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md b/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md new file mode 100644 index 0000000..80cba44 --- /dev/null +++ b/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md @@ -0,0 +1,443 @@ +# Jinkendo Kairo +## Vision & Product Direction v0.2 + +**Status:** führendes Produkt-Zielbild (Nordstern) +**Stand:** 2026-07-05 +**Ersetzt als Leitdokument:** Product Reset v0.1 (teilweise), Product Spec v0.2 (Auslegung), Usability Recovery Plan v0.1 (Strategie) + +--- + +## 1. Warum dieses Dokument existiert + +Nach AP0.7–AP1.1b ist die technische Foundation tragfähig, aber das **Produkterlebnis weicht stark von der Vision ab**. + +Typische Symptome: + +- Alles auf einer Seite: anlegen, bearbeiten, einsehen — wie eine CRUD-Admin-Oberfläche +- **Maßnahme** als einzige operative Ebene — zu grob für Programme und Projekte +- **Meilenstein** als Listeneintrag mit Titel und Status — kein Quality Gate, kein prüfbarer Zustand +- Keine Trennung von **Plan** (Roadmap) und **Ist** (committete Arbeit) +- Keine Planung von **Zuordnungen** und **Abhängigkeiten** +- Keine **Reise-Sicht** (Entscheidungen, Abweichungen, Nachweise über die Zeit) + +Dieses Dokument fasst die **Product Owner Vision** zusammen und ist ab sofort **führend für Produktentscheidungen und Dokumentations-Überarbeitung**. + +Technische Zielarchitektur-Dokumente (`Kairo_System_Target_State`, Universal Steering Engine) beschreiben viel Richtiges — wurden aber **vorschnell durch flache MVP-UI ersetzt**, die so tut, als wäre das Ziel schon erreicht. + +--- + +## 2. Produktidentität (unverändert, aber schärfer formuliert) + +**Kairo** ist der operative **Program Director** der Jinkendo-Produktfamilie. + +Kairo steuert **Entwicklungen** — nicht nur Aufgabenlisten. + +**Leitfrage:** + +> Welcher nächste Schritt bringt diesen steuerbaren Kontext jetzt am wirksamsten voran? + +Kairo beantwortet diese Frage auf **Ausführungs-Ebene** (Heute, Next Action, Blocker) und auf **Programm-Ebene** (Plan, Gates, Abweichungen, Entscheidungen). + +--- + +## 3. Was Kairo nicht ist + +| Kairo ist nicht | Warum | +|-----------------|-------| +| To-do-App / Task-Manager | Speichert Aufgaben, aber nicht Entwicklungssteuerung | +| CRUD-Oberfläche über Listen | Listen ohne Plan/Ist-Trennung und ohne Gates | +| Einseitiges Vorhaben-Detail | Alles anlegen + alles sehen auf einer Seite | +| Roadmap-Tool ohne Ist-Bezug | Plan ohne committete Arbeit und Verifikation | +| PM-Tool mit Gantt als Kern | Gantt kann später kommen; Kern ist Steuerungsantwort | + +**Historischer Fehler:** `Initiative → Action` als sichtbares Hauptmodell. Das war ein **technischer Startpunkt**, wurde aber fälschlich als MVP-Zielbild behandelt. + +--- + +## 4. Begrifflichkeit — Product Language + +Einheitliche Sprache im Produkt (Deutsch) und im Modell (Englisch): + +| Product (DE) | Modell (EN) | Rolle | +|--------------|-------------|-------| +| Vorhaben / Programm | Initiative | Steuerbarer Kontext mit Ziel und Methode | +| Projekt (optional) | Project | Teilstruktur innerhalb eines Vorhabens | +| **Plan / Roadmap** | Roadmap → RoadmapItem | Geplante Entwicklungsstruktur — **Orientierung und Prüfpunkte** | +| Quality Gate / Meilenstein | RoadmapItem (`type=milestone`, `review_gate`, …) | **Überprüfbarer** Zielpunkt — kein Task | +| Reifegrad / Fähigkeitsstufe | RoadmapItem (`type=maturity_stage`) | Oft **parallel** erreichbar | +| Eingang | BacklogItem | Noch nicht committeter Handlungsbedarf | +| **Arbeitspaket** (interim: „Maßnahme“) | Action | **Freigegebene** operative Einheit | +| Aufgabe (später) | Task / Sub-Action | Kleinste ausführbare Einheit unter einem Arbeitspaket | +| Zuweisung | ActionAssignment | Actor-first | +| Hindernis | Blocker | Stoppt oder gefährdet Fortschritt | +| Nachweis | Evidence | Beleg für Fortschritt / Gate | +| Entscheidung | Decision | Dokumentiert Plan-Abweichung, Priorität, Scope | +| Review | Review | Strukturierte Bewertung | +| Nächster Schritt (Read Model) | NextActionCandidate | Ableitung aus Zustand + Methode | + +### Wichtige Korrektur: „Maßnahme“ + +Im heutigen UI heißt `Action` **Maßnahme**. Das ist **zu grob** für die Vision: + +- Wenn das **Vorhaben ein Programm** ist, entspricht die operative Einheit eher einem **Projekt** oder **Arbeitspaket**. +- Darunter kommen **Aufgaben** (Hierarchie — methodenabhängig, z. B. WBS). + +**Übergang:** UI darf „Maßnahme“ vorübergehend behalten, Dokumentation und Roadmap sprechen von **Arbeitspaket** (`Action` interim) und planen **Task-Ebene** explizit ein. + +--- + +## 5. Plan-Struktur vs. Ist-Struktur + +Zentrale Unterscheidung — fehlt im heutigen Produkt vollständig: + +```text +PLAN (Roadmap) IST (Operativ) +───────────────── ───────────────── +RoadmapItem: Meilenstein/Gate Action: committete Arbeit + ├─ DoD / Kriterien ├─ Status, Assignments + ├─ Abhängigkeiten ├─ Blocker, Evidence + ├─ Zieltermin └─ Reviews + └─ parallel | sequenziell + │ + │ BacklogItem zahlt ein auf Plan + ▼ +Decision: Plan geändert / ignoriert / verschoben +``` + +**Roadmap** = entwicklungsbezogener Plan, gegen den geprüft wird. + +**Plan ist nicht bindend ohne Commit:** Entscheidungen können den Plan umgehen, verschieben oder neu definieren — **mit Nachvollziehbarkeit** (Decision + ggf. Audit). + +**Ist** = was tatsächlich committet und ausgeführt wird (`Action` + Nachweise). + +--- + +## 6. Meilenstein = Quality Gate (nicht Listeneintrag) + +Ein Meilenstein im Sinne der Vision ist ein **Quality Gate**: + +| Dimension | Anforderung | +|-----------|-------------| +| Definition | Titel, Ziel, **Definition of Done** (prüfbare Kriterien) | +| Typ | sequenziell · parallel · optional (z. B. Reifegrade) | +| Abhängigkeiten | `requires` / `blocks` zu anderen RoadmapItems | +| Verifikation | Erreichen nur mit Evidence und/oder Review — nicht per Status-Dropdown | +| Abweichung | `moved` / `discarded` → **Decision** mit Begründung | +| Bezug zur Arbeit | BacklogItems und Actions **zahlen ein** auf ein Gate | + +**Heute:** Tabelle `milestones` mit Titel, optionalem Text, Status — **MVP-Brücke**, kein Gate-Modell. + +**Ziel:** `RoadmapItem` mit `item_type` (milestone, review_gate, maturity_stage, …) — siehe `Kairo_System_Target_State` §12–13. + +--- + +## 7. Information Architecture (Ziel-Navigation) + +Kairo hat **drei Ebenen** — nicht eine Omnibus-Seite pro Vorhaben. + +```text +Workspace → Portfolio: alle Initiativen im Überblick + └── Initiative-Übersicht → Operative Steuerung dieses Vorhabens (reicht im Alltag) + └── Unterseiten → Pflege, Planung, Anlage, Objekt-Details +``` + +```mermaid +flowchart TB + WS[Workspace — alle Initiativen] + IO[Initiative-Übersicht — operative Steuerung] + PL[Unterseite Plan] + EX[Unterseite Ausführung] + IN[Unterseite Eingang] + JO[Unterseite Journey] + API[Operational Actor Interface — Vibe-Coder] + + WS -->|Vorhaben wählen| IO + IO --> PL + IO --> EX + IO --> IN + IO --> JO + API -.->|gleiche Fachlogik| IO + API -.-> EX +``` + +**Grundregel:** Übersichtsseiten **entscheiden und navigieren**. Anlegen, Bearbeiten und Pflege liegen auf **Unterseiten** (oder Modal), nicht als Inline-CRUD auf der Übersicht. + +--- + +### 7.1 Workspace — Portfolio über alle Initiativen + +**Rolle:** Einstieg in Kairo; **Querschnitt** über alle aktiven Vorhaben. + +Typischer Inhalt: + +- Kacheln/Liste aller Initiativen mit Lifecycle, Methode, Kurzsignal (blockiert, Gate at risk, …) +- Initiativen-übergreifende **Attention** (wo brennt es?) +- **Next-Action-Widget** (konfigurierbar) — siehe §7.6 +- Filter/Sortierung: aktiv / pausiert / **Portfolio-Priorität** / Initiativtyp / meine Beteiligung + +**Nicht auf dem Workspace:** + +- Planung eines einzelnen Vorhabens (Roadmap pflegen) +- Backlog anlegen, Gates definieren, Entscheidungen dokumentieren +- Objekt-CRUD für ein spezifisches Vorhaben + +Klick auf ein Vorhaben → **Initiative-Übersicht** (nicht direkt in eine Pflege-Unterseite). + +--- + +### 7.2 Initiative-Übersicht — operative Steuerung (Alltag genügt) + +**Rolle:** **Steuerungs-Antwort** für dieses eine Vorhaben. Für die operative Führung im Alltag soll **diese Seite ausreichen** — ohne durch Pflege-Listen scrollen zu müssen. + +Typischer Inhalt (lesend + wenige Steuerungsaktionen): + +- Leitfrage-Antwort: Snapshot (Lifecycle, Methode, Signale) +- **Next-Action-Widget** (konfigurierbar, Scope = dieses Vorhaben) — siehe §7.6 +- **Roadblocker** / blockierte Arbeitspakete (aggregiert) +- **Meilenstein-Horizont** / Gates at risk +- Kurzüberblick: offene Arbeitspakete, unverknüpfte Blocker (Hinweis → Unterseite) +- Navigation zu Unterseiten: Plan, Ausführung, Eingang, Nachvollziehbarkeit + +Erlaubt auf der Übersicht: + +- Methode wählen, Lifecycle-relevante **Steuerungs**-Aktionen (später, über Hooks) +- **Navigieren** zu Detail und Pflege + +**Nicht auf der Initiative-Übersicht:** + +- Listen mit Inline-Formularen zum Anlegen von Backlog, Gates, Evidence, … +- Vollständige CRUD-Wände aller OM-Entypen + +→ Das ist der Ersatz für die heutige `InitiativeDetailPage` als Omnibus. + +--- + +### 7.3 Unterseiten — Pflege, Planung, Anlage + +Alles, was **Inhalte pflegt oder neu anlegt**, liegt hier: + +| Route (Beispiel) | Zweck | Typische Aktionen | +|------------------|-------|-------------------| +| `/initiatives/:id/plan` | Roadmap, Gates, Abhängigkeiten | Gate anlegen, DoD pflegen, Reihenfolge | +| `/initiatives/:id/execution` | Arbeitspakete (Hub) | Paket anlegen, Status, Zuweisung | +| `/initiatives/:id/inbox` | Backlog, Triage | Erfassen, triagieren, in Arbeitspaket überführen | +| `/initiatives/:id/decisions` | Entscheidungen | Decision anlegen, Belege verknüpfen | +| `/initiatives/:id/journey` | Reise / Timeline | lesend; Drill-down zu Events | +| `/initiatives/:id/actions/:actionId` | Arbeitspaket-Detail | Blocker, Evidence, Reviews am Objekt | +| `/initiatives/:id/gates/:gateId` | Gate-Detail | DoD, Verify, Abhängigkeiten | + +**Bearbeitung:** Modal (klein) oder **eigene Seite** (komplex) — nie als dauerhaftes Inline-Formular auf der Übersicht. + +--- + +### 7.4 Planung von Zuordnungen und Abhängigkeiten + +Primär auf **Plan-Unterseite**; in der Übersicht nur **Auswirkung** sichtbar (z. B. Gate blockiert, Abhängigkeit unerfüllt). + +Minimum vor KI/Methode: + +- Abhängigkeitsgraph zwischen RoadmapItems +- Zuordnung Backlog/Action → RoadmapItem +- Actor-Zuweisung an Action (bereits API vorhanden) + +--- + +### 7.5 Operational Actor Interface (Vibe-Coder & Agenten) + +**Vibe-Coder** (und später andere Agenten-Actors) arbeiten **nicht** über Ad-hoc-Prompts in der UI, sondern über eine **definierte operative Schnittstelle** — dieselbe fachliche Logik wie für Menschen, maschinenlesbar. + +Agenten sind **Actors** (`actor_type=agent`). Keine Sonderdomäne. + +#### Geplante Fähigkeiten der Schnittstelle + +| Operation | Beschreibung | Human-Äquivalent | +|-----------|--------------|------------------| +| **Kontext lesen** | Steering Snapshot, Lifecycle, Methode für Initiative | Initiative-Übersicht | +| **Nächste Aufgabe anfragen** | NextActionCandidate für diesen Actor in Initiative/Kontext | „Was ist dran?“ | +| **Status melden** | Action-Status, Fortschritt, Kommentar/Evidence-Anstoß | Arbeitspaket aktualisieren | +| **Blocker melden** | Blocker an Action oder Initiative | Blocker erfassen | +| **Nachweis ablegen** | Evidence an Action/Gate | Verify vorbereiten | +| **Entscheidungsunterlage ablegen** | Dokument/Evidence + Decision-Vorschlag oder Review-Request | Decision vorbereiten | +| **Backlog vorschlagen** | BacklogItem vorschlagen (nicht auto-committen) | Eingang | +| **Gate-Status nicht schließen** | `reached` nur über Verify-Pfad — Agent schlägt vor, Mensch/System prüft | Quality Gate | + +#### Architekturprinzipien + +1. **API-first:** REST (später optional MCP-Adapter) — keine UI-spezifische Sonderlogik +2. **Capability-gated:** gleiche Rechte wie Human-Actors (`kairo.action.manage`, …) +3. **Tenant-scoped:** jeder Call über TenantContext + Actor-Identität +4. **Auditiert:** Agentenaktionen nachvollziehbar (wer, was, wann, auf welches Objekt) +5. **Steering-konform:** Next Action und Status über `backend/steering/` — keine parallele Agent-Heuristik +6. **UI spiegelt API:** Was Vibe-Coder per API tun, muss auf Unterseiten für Menschen equivalent möglich sein + +#### Explizit nicht (bis Gate-Modell + IA stehen) + +- Freie LLM-Workflows in Produktivpfad +- Agent darf Plan/Gates/Prioritäten ohne Freigabe ändern +- Prompt-Registry als Agent-Steuerung missbrauchen + +**Implementierung:** eigenes Paket **AP1.7** (nach IA-Skeleton + Actor-Auth für Agenten) — Schnittstellen-Spec als ADP ableiten. + +--- + +### 7.6 Next Action, Portfolio-Priorität & situativer Kontext + +#### Next-Action-Widget (konfigurierbar) + +Das **Next-Action-Widget** erscheint voraussichtlich auf **beiden** Übersichtsseiten — mit unterschiedlichem **Scope**, konfigurierbar pro Nutzer/Layout: + +| Seite | Widget-Scope | Typische Filter | +|-------|----------------|-----------------| +| **Workspace** | Portfolio — über **alle** Initiativen | Initiativtyp, Portfolio-Prio, mir zugewiesen, überfällig | +| **Initiative-Übersicht** | **Nur dieses** Vorhaben | Actor, Gate-Bezug, Dringlichkeit innerhalb des Programms | + +Konfiguration (Zielbild): + +- Widget-Registry / Layout (bereits Foundation aus AP0.6 — ausbauen) +- Sortierung und Filter pro Widget-Instanz +- Gleiche Datenquelle: `NextActionCandidate` via `backend/steering/` — keine parallele Logik + +**Klärung (PO):** Beide Ebenen brauchen „Was ist als Nächstes dran?“ — Workspace quer, Initiative fokussiert. + +#### Portfolio-Priorität (Initiativen-Ebene) + +Priorisierung betrifft das **gesamte Portfolio**, nicht nur einzelne Arbeitspakete: + +- Initiativen tragen eine **Portfolio-Priorität** (relativ zueinander) +- Steuerung: welches Vorhaben bekommt Aufmerksamkeit, wenn Kapazität knapp ist +- Next-Action auf dem Workspace berücksichtigt Portfolio-Prio **und** operative Dringlichkeit (überfällig, blockiert, Gate at risk) + +**Noch nicht modelliert** — aufnehmen in Roadmap v0.2 / ADP (Feld auf Initiative oder separates Portfolio-Steuerungsobjekt). + +#### Situativer Steuerungskontext (später) + +Next Action soll nicht nur nach Priorität und Fälligkeit ranken, sondern nach **passendem Kontext**: + +> Beispiel: *„Ich bin gerade im Urlaub / nicht zuhause — was kann ich hier sinnvoll als Nächstes tun?“* + +**Nicht:** Urlaubsplanung oder Reiseprodukt. + +**Sondern:** Aufgaben, die zum **aktuellen Situationskontext** passen — z. B. wichtige aber ortsunabhängige Arbeit, persönliche Entwicklung, lesen/reviewen, Dinge die ohne Werkstatt/Meeting gehen. + +Konzeptuelle Bausteine (Zielbild, Phase C+): + +- **Situationskontext** des Actors (manuell gewählt oder gemeldet: „unterwegs“, „fokus block“, „nur kurze Slots“) +- Metadaten an BacklogItem/Action: `context_tags` oder methodenabhängige **Eignungsmerkmale** (ort, Dauer, Energie, Abhängigkeit von Tools) +- Next-Action-Strategie filtert/rankt nach Kontext + Portfolio-Prio + Initiativtyp +- Methoden können eigene Kontextregeln mitbringen (später über Method Registry) + +**Implementierung:** nach Gate-Modell und Portfolio-Priorität — nicht vor AP1.4. In Steering-Strategien erweiterbar (`next_action` packages unter `backend/steering/`). + +--- + +## 8. Journey / Reise-Sicht + +Für ein Projekt/Vorhaben soll die **gesamte Reise** sichtbar werden: + +```text +Timeline / Journey + ├── Plan-Änderungen (Decisions) + ├── Gates erreicht / verschoben + ├── Blocker entstanden / gelöst + ├── Reviews + ├── Evidence-Meilensteine + └── Methoden- / Lifecycle-Wechsel +``` + +Das ist **kein Audit-Log-Rohdump**, sondern eine **steuerungsrelevante Narrative**. + +--- + +## 9. Methoden & KI (Reihenfolge) + +1. **Regelbasierte** Steuerung (Lifecycle, Signals, Next Action) — AP1.0 begonnen +2. **Struktur & Gates** (RoadmapItem, Plan/Ist, IA) — **vor** weiterem UI-Polish +3. **Method Registry** — welche Builder/Hooks für welchen Kontext +4. **KI-Unterstützung** — Planung, Zuordnung, Abhängigkeiten vorschlagen — **nach** Gate-Modell + +Prompt/KI/MCP bleiben **eingefroren**, bis Plan/Ist und Gates tragfähig modelliert und in der UI navigierbar sind. + +--- + +## 10. Ehrlicher Implementierungsstand (Kurz) + +| Visionselement | Stand | +|----------------|-------| +| Tenant, Actor, Capabilities | ✓ produktionsnah | +| Initiative, Action, Assignment | ✓ flach | +| Backlog, Blocker, Evidence, Decision, Review | ✓ CRUD + APIs | +| Steering Foundation (Lifecycle, Snapshot) | ✓ Skeleton | +| Method Registry | ✓ minimal | +| Workspace Next Action / Heute | ✓ Widget-Ebene | +| **Portfolio-Priorität (Initiativen)** | ✗ | +| **Next-Action-Widget konfigurierbar (Workspace + Initiative)** | ◐ Widget-Registry; fest eingebaut | +| **Getrennte IA (Workspace → Initiative → Unterseiten)** | ✗ | +| **Operational Actor Interface (Vibe-Coder API)** | ✗ | +| **Situativer Steuerungskontext** | ✗ | +| **Modal/Detail-Bearbeitung** | ✗ | +| **Roadmap / RoadmapItem** | ✗ | +| **Gate mit DoD & Verifikation** | ✗ | +| **Abhängigkeiten** | ✗ | +| **Plan vs. Ist** | ✗ | +| **Task-Hierarchie unter Action** | ✗ | +| **Journey-Sicht** | ✗ | +| Project (optional im OM) | Schema/API teils, **GUI fehlt** | + +Details: `Kairo_Implementation_Truth_Table_v0.1.md` + +--- + +## 11. Konsequenz für Implementierung + +**Stop-Kriterium für weitere „InitiativeDetail-Refactors“:** + +Kein weiteres Layout-Patching auf der Omnibus-Seite, bevor: + +1. IA-Zielbild (dieses Dokument §7) in Routing umgesetzt ist +2. ADP für RoadmapItem / Gate-Modell freigegeben ist +3. Bearbeitungs-Pattern (Modal/Detail) etabliert ist + +**Nächste sinnvolle Produktpakete** (nach Dokumentations-Überarbeitung): + +| Paket | Inhalt | +|-------|--------| +| **DOC-1** | Dokumenten konsolidieren (dieses Programm) | +| **AP1.2** | Signals konsolidieren, `operating_phase` entfernen | +| **AP1.2c** | IA-Skeleton: Workspace-Portfolio, Initiative-Übersicht (read), Unterseiten-Routing, Modal-Pattern | +| **AP1.4 + ADP** | Milestone → RoadmapItem, Gate-Modell, Dependencies | +| **AP1.7** | Operational Actor Interface (Vibe-Coder API) | +| **AP1.8** | Portfolio-Priorität + situativer Kontext in Next-Action-Strategien | +| **AP1.5** | Hierarchie: Project, Task unter Action | +| **AP1.6** | Plan/Ist-Views, Journey | + +--- + +## 12. Verbindliche Dokumenten-Hierarchie (neu) + +Bei Konflikten ab 2026-07-05: + +1. **Dieses Dokument** — Vision & Product Direction v0.2 +2. `Kairo_Canonical_Operating_Model_v0.2.md` +3. `Kairo_System_Target_State_v0.1.md` (bis v0.2) — technisches Nordstern-Zielbild +4. `Kairo_Implementation_Truth_Table_v0.1.md` — was wirklich existiert +5. `Kairo_Corrected_MVP_Roadmap_v0.2.md` (in Arbeit) +6. Architecture ADPs (Scope Lock, RoadmapItem, …) +7. Sprint Assignments / Completion Reports (historisch) +8. Product Spec v0.2 (Referenz, nicht führend bei Konflikt) + +--- + +## 13. Product Owner Leitplanken + +Entscheidungen an diesem Dokument prüfen: + +1. Beantwortet die Änderung die **Leitfrage** auf der richtigen **Ebene** (Ausführung vs. Plan)? +2. Trennt sie **Plan** und **Ist**? +3. Ist ein Meilenstein **prüfbar** — oder nur ein Statusfeld? +4. Passiert Bearbeitung in **Modal/Detail** — oder wächst wieder eine CRUD-Wand? +5. Wird die **Reise** nachvollziehbar — oder nur der aktuelle Zustand? +6. Verhindert sie Scope-Creep in Richtung To-do-Tool? + +--- + +*Verwandt: `DOCUMENTATION_REVISION_PROGRAM_v0.2.md`, `Kairo_Canonical_Operating_Model_v0.2.md`, `Kairo_Implementation_Truth_Table_v0.1.md`*