Kairo-Jinkendo/docs/product/Kairo_Plan_Mode_Design_v0.1.md

# Kairo — Plan-Modus Design v0.1

**Status:** PO-Arbeitsentwurf (Execution-Plan §6–7 PO 2026-07-12)  
**Stand:** 2026-07-12  
**Bezug:** `Kairo_PM_Frontend_UI_Concept_v0.1.md` §4.3, `ADP_AP1_10_Initiative_Archetypes_and_Entity_Field_System_v0.1.md`, `ADP_Execution_Plan_and_Work_Package_Dependencies_v0.1.md`  
**Auslöser:** Planen soll von Tab-Fragmenten zu durchgängiger Programmgestaltung werden — bis Struktur, Gates, Eingang, Arbeitspakete und Tasks

---

## 1. Leitfrage

**Wie soll das Programm aufgebaut sein — von der Vorhabens-Identität bis zur ausführbaren Granularität?**

Planen beantwortet **Struktur- und Zielfragen**. Es committet **keine Tagesausführung** (das ist Ausführen) und **kein Lagebild** (das ist Kontrolle).

---

## 2. Grundsatz: Vorhaben als Wurzel

```text
/plan?initiative={id}&project={optional}

Initiative (Wurzel — immer im Scope)
├── Profil          — Archetyp, Standard- + dynamische Felder
├── Struktur        — Project-Baum (rekursiv)
├── Zielzustände    — Gates / RoadmapItems (Liste + Graph)
├── Eingang         — Backlog (triage → convert)
└── Arbeit          — Actions (+ Tasks ab AP1.5d) im Plan-Kontext
```

**Flache Vorhaben:** Actions ohne `project_id` erscheinen als direkte Kinder der Initiative im Plan-Baum.

**Commit-Grenze Plan → Ist:**

| Objekt | In Plan | Commit-Aktion |
|--------|---------|---------------|
| BacklogItem | Ja | Convert → Action |
| Project / Gate | Ja | sofort „Struktur“ (kein separater Commit) |
| Action | Sichtbar | Anlage = committet |
| Task | Sichtbar (AP1.5d) | Anlage unter Action |

---

## 3. IA: Von Tabs zur Plan-Outline

### 3.1 Heute (AP1.9a)

```text
/plan/structure | /plan/gates | /plan/inbox   — drei lose Untertabs
```

### 3.2 Ziel (AP1.12)

**Eine Planungsseite** mit linker **Outline** (Baum) und rechtem **Kontextbereich** (Desktop) bzw. **Drill-down** (Mobile).

```text
┌──────────────────────────────────────────────────────────────┐
│ Modus: Planen    Scope: Portfolio › Vorhaben X › [Projekt Y] │
├──────────────────┬───────────────────────────────────────────┤
│ OUTLINE          │ KONTEXT                                   │
│ ▼ Vorhaben X     │  [Profil-Karte / Mini-Snapshot]           │
│   ▼ Struktur     │  oder                                     │
│     Phase 1      │  [Liste der Kinder des gewählten Knotens] │
│     Phase 2      │  oder                                     │
│   Zielzustände   │  [Graph-Ansicht Gates]                    │
│   Eingang (3)    │                                           │
│   Arbeit (12)    │                                           │
└──────────────────┴───────────────────────────────────────────┘
```

**Routen (evolutionär):**

| Route | Bedeutung |
|-------|-----------|
| `/plan` | Portfolio: „Vorhaben ohne Struktur“, „Gates ohne Kriterien“ (Einstieg) |
| `/plan?initiative=` | Outline für ein Vorhaben |
| `/plan?initiative=&node=structure\|gates\|inbox\|work` | Outline-Fokus (Query, kein Pflicht-Split) |
| `/gates/:id`, `/projects/:id` | Objekt-Modal / Deep Link (bestehend AP1.9) |

Untertabs `/plan/structure` etc. bleiben als **Deep-Link-Aliase** mit Redirect auf `/plan?initiative=&node=…` bis Entfernung in AP1.12.

---

## 4. Interaktion

### 4.1 Bearbeiten — Modal (verbindlich)

| Objekt | Trigger | Modal-Inhalt |
|--------|---------|----------------|
| Initiative | Outline „Profil“ / Stift-Icon | Standardfelder + EFS (AP1.10) |
| Project | Klick / Stift | Titel, Status, container_kind, Gate-Link, Parent |
| Gate | Klick / Stift | RoadmapItem + Kriterien (bestehend, polish) |
| Backlog | Klick | Triage-Felder, Gate-Link, Convert-Button |
| Action | Klick | ActionForm (bestehend) — oder Link zu `/actions/:id` |
| Task | Klick (AP1.5d) | TaskForm |

**Regel (UI Concept P4):** Kein dauerhaftes Inline-Formular in der Outline.

### 4.2 Reihenfolge

| Plattform | Mechanismus | Gilt für |
|-----------|-------------|----------|
| Desktop (≥1024px) | Drag & Drop innerhalb gleicher Elternebene | Projects, Backlog (sort_order), Gates (optional Phase 2) |
| Mobile / Touch | ↑ / ↓ Buttons pro Zeile | gleich |

**API:** `PATCH` mit `sort_order` oder dediziertes `POST …/reorder` — idempotent, tenant-scoped.

### 4.3 Anlegen

„+“ am **elterlichen Knoten** in der Outline (nicht globaler FAB ohne Kontext).

---

## 5. Zielzustände — Graph (Plan-Modell, kein Workflow)

### 5.0 Abgrenzung (verbindlich)

Der **Zielzustands-Graph** modelliert **Soll-Struktur** — welche überprüfbaren Zielpunkte es gibt und wie sie **logisch zusammenhängen** (sequenziell, parallel, optional, blockierend).

Er ist **kein Workflow**:

| Zielzustands-Graph (Kairo) | Workflow (Mitai Prompt Engine — **nicht** Kairo-Scope) |
|----------------------------|--------------------------------------------------------|
| RoadmapItem = Quality Gate / Meilenstein / Reifegrad | Prompt-/Pipeline-Knoten |
| Kanten = Plan-Abhängigkeiten zwischen Gates | Ausführungs-/Verzweigungslogik |
| Verify = Kriterien + Evidence/Review | LLM-Aufruf, Aggregation, Join |
| Lesbar in **Planen** und **Kontrolle** (Plan vs. Ist) | Admin-Konfiguration für KI |
| Änderung am Plan = bewusste **Planungsentscheidung** (+ Audit) | Laufzeit-Orchestrierung |

**Mitai `WorkflowEditorPage`:** nur **UI-Pattern-Referenz** (Canvas, Zoom, Pan, Snap) für ein künftiges **Zielzustands-Modellierungswerkzeug** — **keine** Übernahme von Workflow-Semantik, Prompt-Knoten oder Runtime.

**Guardrail:** In Docs, UI und Code nicht „Workflow-Graph“, „Gate-Workflow“ oder „Graph-Workflow“ sagen — korrekt: **Zielzustands-Graph**, **Gate-Map**, **Plan-Graph**.

### 5.1 Zwei Ansichten (Liste | Graph)

| Ansicht | Wann | UI |
|---------|------|-----|
| **Liste** | Flache Vorhaben, wenige Gates | `RoadmapPlanSection` (evolviert) |
| **Graph** | Komplexe Abhängigkeiten, Parallel-Gates | **GateMapView** / später **Zielzustands-Designer** |

Umschalter: „Liste | Graph“ im Knoten Zielzustände — Default **Liste** wenn ≤5 Gates, sonst letzter User-Choice (localStorage pro Initiative).

### 5.2 Graph-UI — Mitai-Pattern, Kairo-Semantik

**Referenz (Pattern only):** Mitai Workflow-Editor — Canvas, Zoom, Pan, Snap-to-grid.

**Kairo-Scope (Zielzustands-Modell, kein Workflow):**

| Element | Semantik |
|---------|----------|
| Knoten | RoadmapItem (Gate, Meilenstein, Reifegrad) |
| Kanten | `roadmap_item_dependencies` → später `edge_kind` + `parallel_group` (AP1.4d) |
| Joint / Split (später) | **Plan-Topologie** — parallele Stränge, Join-Gates, optionale Äste — **nicht** Runtime-Verzweigung |
| Kein | Lifecycle-Workflow, Prompt-Knoten, Mitai-Domäne, Ausführungs-Engine |

**Heute (AP1.13a/b — MVP-Zwischenstand):** read-only Auto-Layout + Kanten auf Gate-Detail; **kein** grafischer Designer, **keine** Joint-Knoten, **kein** Parallel-Join-Modell (→ AP1.4d + Modellierungswerkzeug).

**Phase 2 — Zielzustands-Modellierungswerkzeug (PO):**

- Drag-Drop-Designer für Gates, Kanten, Parallelgruppen, Joins  
- Bearbeitung nur im **Plan**-Kontext (Modal/Designer — nicht Inline-CRUD-Wand in der Outline)  
- Verify / Kriterien / Evidence weiterhin auf Gate-Detail — nicht im Graph als CRUD-Omnibus

### 5.3 Plan-Graph vs. Ist — parallel betrachten (Zielbild)

**Problem (mehrfach in Kairo erlebt):** Wenn Plan und Ist in **demselben mutable Objekt** verschmelzen (Status-Dropdown, Freitext-DoD, Graph = nur aktueller Stand), ist **nicht nachvollziehbar**, was geplant war, was tatsächlich passiert ist und wann der Plan angepasst wurde.

**Regel:**

| Schicht | Inhalt | Änderbarkeit |
|---------|--------|--------------|
| **Plan-Graph (Soll)** | Knoten, Kanten, Kriterien-**Definition**, Parallel-/Join-Topologie | Planung; Revision mit Audit/Decision |
| **Ist-Overlay** | Gate-Status (`reached`/`moved`/…), Kriterien-**Status**, Evidence, Journey-Events | Ausführung, Review, Verify, Reopen |
| **Historie** | Plan-Revisionen, Ist-Ereignisse, Abweichungen Plan↔Ist | append-only / audit |

**Review-Ablauf (Kontrolle / Journey — Ziel):**

```text
1. Plan-Graph und Ist-Overlay **parallel** anzeigen (nicht eins collapsed)
2. Abweichungen sichtbar: Gate erreicht aber Kriterium waived; optionaler Ast nicht genommen; Plan-Kante obsolet
3. Entscheidung: Plan anpassen (Zielzustand revidieren) — mit Begründung — ODER Ist dokumentieren (Decision/moved/discarded)
4. Plan-Graph **ordentlich** nachziehen — nicht stillschweigend den Ist-Stand als neuen Plan überschreiben
```

**Technische Folge (spätere Pakete):**

- AP1.4d: Graph Engine Read Models (`blocked`, `ready`, `fulfillment_ratio`) aus **Plan-Kanten** + **Ist-Status**  
- AP1.4e+: Methodenprofile (Erfüllungsgrad vs. hartes `reached`)  
- **AP1.14 (vorgeschlagen):** Plan-Snapshot / Plan-Revision + Ist-Overlay in UI (Kontrolle: „Plan | Ist | Diff“); Graph-Designer Phase 2

**Heute:** Ein Graph, Status am selben Knoten — **Ist vermischt mit Plan**. Truth Table: ◐. Das ist **bewusster MVP-Zwischenstand**, kein Zielbild.

### 5.4 Backend

Baut auf AP1.4d (Graph Engine read models) auf — UI AP1.13 **nach** 4d oder parallel wenn read APIs vorhanden.

---

## 6. Progressive Planung — aufsteigende Granularität

Planen ist **kein einmaliger Vollplan**. Je nach Archetyp existieren unterschiedlich viele Ebenen; die **nächste Ebene** wird erst relevant, wenn der aktuelle Horizont **aktiv** ist und der Unterplan noch **leer** ist (rollende Planung).

### 6.1 Drei Planungsdimensionen (verbindlich)

| Dimension | Frage | OM / UI |
|-----------|--------|---------|
| **A — Ziel-Horizont** | Was muss erreicht sein? | `RoadmapItem`, Gate-Graph — §5, Zielzustands-Designer |
| **B — Struktur** | Wo hängt die Arbeit? | Project-Baum — Outline „Struktur“ |
| **C — Durchführung** | In welcher Reihenfolge committen wir APs? | `Action` + `action_dependencies` — Outline „Arbeit“ §6.3 |
| **D — Zeitbox** (optional) | Was in dieser Iteration/Woche? | `work_cycle` (AP2.0f), Recurring — nicht Gate-Microplan |

**PO-Regel:** Dimension **A** ≠ **C**. AP-Abhängigkeiten (z. B. „Foundation vor Feature“) gehören in **C**, nicht in den Gate-Designer.

### 6.2 Planungsebenen (Referenzleiter)

```text
Ebene 0   Initiative / Vorhaben     — Methode, Archetyp, Profil
Ebene 1   Ziel-Horizont             — Gates, Phasen grob (optional)
Ebene 2   Struktur                  — Phase / Stream / Project-Baum (optional)
Ebene 3   Durchführungsplan         — Arbeitspakete + Kanten (rollend unter aktivem Gate)
Ebene 4   Zeitbox                   — Sprint / Woche / Monat (optional, archetypabhängig)
Ebene 5   Ausführung                — Tasks / ToDos unter Action
```

**Minimal-Vorhaben** (`generic_operating`): oft nur Ebene 0 → 3 → 5 (Vorhaben → Actions → Tasks).  
**Product-Programm** (Kairo-Jinkendo): 1 (G1–G8 grob) + 3 + optional 4 + 5.  
**Persönliches Rhythmus-Vorhaben**: eher Ebene 4 zeitgetrieben (Woche/Monat) statt WBS-Tiefe.

### 6.3 Planungsschritte — auto vs. explizites ToDo

Meta-Arbeit (Struktur anlegen, WPs schätzen, Deps klären) wird archetypgesteuert ausgelöst:

| Modus | Mechanismus | Beispiel |
|-------|-------------|----------|
| **auto** | Structure Builder + Hook (`on_plan_required`, `on_wbs_required`) | Kumite-Pfad seeden |
| **explicit** | Committetes AP mit `action_kind=planning` | „G6 Durchführungsplan detaillieren“ |
| **skip** | Ebene entfällt | Generic ohne Gate-Graph |

**Planning Debt:** Wenn Gate aktiv und Durchführungsplan leer → Attention (AP1.16d), kein stiller Leerzustand.

### 6.4 Outline-Knoten „Arbeit“ — Durchführungsplan (Dimension C)

| Aspekt | Regel |
|--------|--------|
| Scope | Actions unter Initiative / Project / **aktivem Gate-Horizont** |
| Reihenfolge | `sort_order` (Fallback) + `action_dependencies` (requires/blocks) |
| Anzeige | Liste + optional Kanten-Ansicht; `ready` / `blocked` Badges |
| Bearbeitung | Modal (ActionForm); Kanten auf Detail oder Mini-Graph in Kontext |
| **Nicht** | Gate-Topologie, Verify-Kriterien, Join-Knoten |

**Plan-Baum „Arbeit“ (heute AP1.12d):** committete Actions + Tasks; **AP1.16c** ergänzt Vorgänger und blocked/ready.

---

## 7. Ebenen bis Workpackage & Task (OM-Referenz)

| Ebene | Typ | Plan-Outline-Knoten | Tiefe |
|-------|-----|---------------------|-------|
| 0 | Initiative | Wurzel | 1 |
| 1 | RoadmapItem (Gate) | Zielzustände (Graph/Liste) | parallel; grob |
| 2 | Project | rekursiv | max. 5 (bestehend) |
| 3 | BacklogItem | Eingang | flach unter Initiative |
| 4 | Action | Arbeit / Durchführungsplan | unter Project, Gate oder Initiative |
| 5 | Task | (AP1.5d) | unter Action, UI max. ~3 |

**Filter „Arbeit“:** optional nur „unter gewähltem Project“ / „unter aktivem Gate“ (`?project=`, Gate-Scope aus Kontrolle).

---

## 8. Scope-Breadcrumb (AP1.9b — Zuverlässigkeit)

**Problem:** Klick auf Vorhaben im Breadcrumb führt immer nach `/control/status` — in Planen falsch.

**Regel:** Mittlerer Breadcrumb-Klick ist **modus-sensitiv**:

| Aktiver Modus | Klick „Vorhaben X“ |
|---------------|-------------------|
| `/plan/*` | `/plan?initiative=X` |
| `/control/*` | `/control/status?initiative=X` |
| `/work/*` | `/work/today?initiative=X` |
| Objekt-Route | passender Modus aus Objekttyp (`/projects/` → Plan, `/actions/` → Work) |

Portfolio-Klick: Scope leeren, Modus beibehalten.

**Technik:** `ProgramScopeBar` liest `useLocation` + Modus-Registry; kein hardcoded `/control/status`.

---

## 9. Implementierungspakete

```text
AP1.9b   Scope-Breadcrumb modus-sensitiv; Scope-Sync bei Deep Links härten
AP1.12a  Plan-Outline Shell (Desktop Split / Mobile Drill-down)
AP1.12b  Modal-Edit für Project, Backlog, Initiative-Profil (Standardfelder)
AP1.12c  Reorder: sort_order API + DnD (Desktop) + ↑↓ (Mobile)
AP1.12d  Outline-Knoten „Arbeit“ (Actions listen, Link zu Detail)
AP1.16a  action_dependencies, actions.sort_order, action_kind
AP1.16b  execution_engine (ready/blocked/critical_path)
AP1.16c  Plan-Outline: AP-Kanten, blocked/ready (nicht Gate-Designer)
AP1.16d  planning_levels / planning_mode; Planning Debt Attention
AP1.13a  GateMapView read-only (Layout aus Dependencies)
AP1.13b  Kanten-CRUD auf Gate-Detail (kein Designer)
AP1.4d    Graph Engine: parallel_group, edge_kind, blocked/ready (Gates)
AP1.14    Plan-Snapshot / Ist-Overlay / Plan-Revision ✓
AP1.15    Zielzustands-Modellierungswerkzeug (Designer, Mitai-Pattern)
AP1.15a   Designer MVP (Pan/Zoom, Kanten, Layout)
AP1.15b   Designer UX (Drag-Kanten, Gate anlegen, Klick-Panel)
AP1.15c   Join/Branch-Topologie (parallel_group, optional_branch, Engine) — deferred
AP1.5d   Tasks in Outline-Knoten „Arbeit“
AP1.10   Archetyp + EFS für Initiative-Profil-Modal (parallel ab 10a)
AP2.0f   work_cycle — Zeitbox-Ebene (nach Execution-Graph sinnvoll kombinierbar)
```

**Empfohlene Reihenfolge:**

```text
9b → 12a → 12b → 10a/10c (Profil) → 12c → 12d → 16a → 16b → 16c → 2.0d → 5d → 13a → 13b
```

---

## 10. Nicht-Ziele (Scope Lock)

- Kein Sprint-/Capacity-Planning in Planen (später Team-Modus-Erweiterung)
- Kein Inline-CRUD aller Gates in der Outline-Liste
- Kein Mitai-Workflow-Clone (**auch kein „Workflow-Graph“** — nur Zielzustands-Graph)
- Kein Plan=Ist-Collapse (Status/Freitext ersetzt nicht Plan-Revision + Ist-Historie)
- Kein AP-Dependency-Graph im Zielzustands-Designer (→ AP1.16c in Outline „Arbeit“)
- Kein Micro-Gate pro Foundation-AP (→ Action-Graph unter grobem Gate)

- Kein Steering pro Project-Ebene (ADP Recursive Containers)

---

## 11. Erfolgskriterien (PO)

1. PO kann ein Vorhaben wählen und **in einer Ansicht** Struktur, Gates, Eingang und Arbeit sehen.  
2. Bearbeitung läuft **nur im Modal** — Outline bleibt übersichtlich.  
3. Project-Reihenfolge per DnD (Desktop) änderbar.  
4. Gates mit Abhängigkeiten im **Zielzustands-Graph** darstellbar (AP1.13); Designer + Plan/Ist-Parallelität folgen (AP1.4d, AP1.14+).  
5. Breadcrumb-Klick auf Vorhaben bleibt im Modus Planen.  
6. Unter aktivem Gate: Durchführungsplan mit Vorgängern planbar — ohne Gate-Graph zu verfeinern (AP1.16).  
7. Planning Debt sichtbar, wenn nächste Planungsebene fehlt (AP1.16d).

---

## 12. PO-Freigabe

- [ ] Outline statt drei Tabs (AP1.12) angenommen  
- [ ] Modal-Edit + DnD/↑↓ OK  
- [ ] GateMap / Zielzustands-Designer (Mitai-**Pattern** only) Scope OK  
- [ ] Plan-Graph vs. Ist-Overlay parallel (AP1.14) OK  
- [ ] AP1.9b Breadcrumb-Regel OK  
- [x] Progressive Planung + Execution-Graph getrennt vom Gate-Graph (§6, AP1.16) — PO 2026-07-12

---

## Referenzen

- `docs/architecture/ADP_Execution_Plan_and_Work_Package_Dependencies_v0.1.md`  
- `docs/architecture/ADP_AP1_10_Initiative_Archetypes_and_Entity_Field_System_v0.1.md`  
- `docs/architecture/ADP_AP1_9_PM_Work_Modes_Frontend_IA_v0.1.md`  
- `docs/reference/design-principles/mitai/PROMPT_ENGINE_DESIGN_PRINCIPLES.md` (WorkflowEditor-Referenz)