From 84d912b8ba76e47452bc82fb32108e860ef735f4 Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 27 Jul 2026 15:59:28 +0200 Subject: [PATCH] docs(AP-BP-0): Vorhaben-Template/Blueprint Konzeption und Scope Lock Co-authored-by: Cursor --- .../ADP_Template_Blueprint_Scope_Lock_v0.1.md | 77 +++ .../ADP_Vorhaben_Template_Blueprint_v0.1.md | 616 ++++++++++++++++++ ...mplate_Blueprint_Conception_Prompt_v0.1.md | 227 +++++++ 3 files changed, 920 insertions(+) create mode 100644 docs/architecture/ADP_Template_Blueprint_Scope_Lock_v0.1.md create mode 100644 docs/architecture/ADP_Vorhaben_Template_Blueprint_v0.1.md create mode 100644 docs/architecture/AP_BP_0_Template_Blueprint_Conception_Prompt_v0.1.md diff --git a/docs/architecture/ADP_Template_Blueprint_Scope_Lock_v0.1.md b/docs/architecture/ADP_Template_Blueprint_Scope_Lock_v0.1.md new file mode 100644 index 0000000..f6a8970 --- /dev/null +++ b/docs/architecture/ADP_Template_Blueprint_Scope_Lock_v0.1.md @@ -0,0 +1,77 @@ +# ADP — Template / Blueprint Scope Lock v0.1 + +**Status:** Entwurf — gilt ab PO-Freigabe von `ADP_Vorhaben_Template_Blueprint_v0.1.md` +**Stand:** 2026-07-27 +**Bezug:** `ADP_Vorhaben_Template_Blueprint_v0.1.md` §13, `ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md`, `Kairo_MVP_Definition_v0.3.md` §3 + +--- + +## Geltungsbereich + +Dieses Scope Lock gilt für **alle Implementierungs-APs AP-BP-1 bis AP-BP-5**. AP-BP-6 (Designer) erfordert eigenes Scope-Lock-Update. + +--- + +## Phase 1 (BP-1 … BP-4) — explizit **nicht** bauen + +| # | Verboten | Begründung | +|---|----------|------------| +| SL-1 | **Blueprint-Designer** (visueller Editor, Drag-Drop) | BP-6; Over-Engineering | +| SL-2 | **YAML/JSON-Import** für Tenant-Blueprints | BP-6 | +| SL-3 | **Produktive KI/Prompt-Ausführung** aus Blueprint-Bindings | AP2.1 Freeze; SK-13 | +| SL-4 | **Agent-Ranker** (`agent_v1`) aktiviert durch Template | BP-5 nach AP2.1 Go | +| SL-5 | **MCP / Workflow-Fragmente** an Blueprint gebunden | Schicht 4 eingefroren | +| SL-6 | **Neue steering_elements** durch Blueprint-Aktivierung | Nur Method Registry | +| SL-7 | **method_key- oder archetype_key-Override** via Blueprint | Natur bleibt Archetyp | +| SL-8 | **Neue OM-Tabellen** pro Blueprint-Typ | Scope Lock OM | +| SL-9 | **Steuerungslogik** in Blueprint-Resolver, Routern, React-Pages | SK-01, SK-03 | +| SL-10 | **Archetyp-Ifs** (`blueprint_key === '…'`) in Pages | Composition + Context | +| SL-11 | **Auto-Upgrade** materialisierter Struktur bei Blueprint-Version | O-5 offen; v1 verboten | +| SL-12 | **Tenant-Custom-Field-Schema** im Blueprint erfinden | EFS-ADP Phase 2 | +| SL-13 | **User-Scope Blueprints** (`scope_type=user`) | BP-6 Kandidat | +| SL-14 | **Vollständiger Structure Builder** getriggert durch Blueprint | Deferred MVP | +| SL-15 | **Projekt-Blueprints** (`entity_type=project`) | AP1.10 Phase 2 | +| SL-16 | **Neue Composition-Provider-Kinds** ohne ADP UX Composition | Open/Closed FE | +| SL-17 | **Portfolio-weite** Blueprint-Copy (Cockpit) | Initiative-scoped only | +| SL-18 | **Hardcodierter Prompt-Text** in `bindings_json` | Prompt-Registry only | + +--- + +## Phase 1 — **erlaubt** (nach ADP-Freigabe) + +| # | Erlaubt | Phase | +|---|---------|-------| +| E-1 | Tabelle `blueprints` + System-Seed-Migration aus `method_profiles/registry.py` | BP-1 | +| E-2 | `GET /api/blueprints` list/get; Alias `method-profiles` | BP-1 | +| E-3 | Operating Context: `blueprint_key`, `blueprint_bindings` (read-only slice) | BP-1 | +| E-4 | Anlage-Dialog: Blueprint wählen | BP-2 | +| E-5 | `apply_starter_kit` liest `starter_kit` aus Blueprint | BP-2 | +| E-6 | EFS `field_defaults` bei Anlage | BP-2 | +| E-7 | Tenant-Fork System-Blueprint → `scope_type=tenant`, `status=draft` | BP-3 | +| E-8 | PATCH Tenant-Blueprint (Presets, Copy) mit Capability-Gate | BP-3 | +| E-9 | Merge Copy in `resolveSteeringComposition` + `PROPOSAL_UI_CONFIG` | BP-4 | +| E-10 | Backlog-Vocabulary-Override aus Blueprint | BP-4 | +| E-11 | `prompt_refs` **speichern** und in API exposieren (ohne Ausführung) | BP-4 | + +--- + +## Abhängigkeiten — nicht vorher starten + +| AP | Blocker | +|----|---------| +| BP-2 (Materialisierung) | AP2.2a Starter-Kit-Pipeline stabil | +| BP-4 (Composition) | UX Composition Kernel MVP (AP-UX-1) | +| BP-5 (Prompt/Agent) | **AP2.1 Go** + Principle Gate Prompts | +| BP-3 (Tenant-Fork) | Tenant-Invariants; Capability `kairo.blueprint.manage` definiert | + +--- + +## Abnahme Scope Lock + +- [ ] PO bestätigt: BP-1…4 ohne SL-1…18 +- [ ] Kein Agent startet BP-5 ohne explizite AP2.1-Freigabe +- [ ] Truth Table aktualisieren bei BP-1 Lieferung + +--- + +*Kurz-Scope-Lock — Detailkonzept in `ADP_Vorhaben_Template_Blueprint_v0.1.md`.* diff --git a/docs/architecture/ADP_Vorhaben_Template_Blueprint_v0.1.md b/docs/architecture/ADP_Vorhaben_Template_Blueprint_v0.1.md new file mode 100644 index 0000000..9650d66 --- /dev/null +++ b/docs/architecture/ADP_Vorhaben_Template_Blueprint_v0.1.md @@ -0,0 +1,616 @@ +# ADP — Vorhaben-Template / Blueprint v0.1 (AP-BP-0) + +**Status:** Konzeptionsentwurf — PO-Freigabe ausstehend +**Stand:** 2026-07-27 +**Autor:** Architektur (AP-BP-0 Konzeptionsauftrag) +**Bezug:** `AP_BP_0_Template_Blueprint_Conception_Prompt_v0.1.md`, `Kairo_Vision_and_Product_Direction_v0.2.md`, `Kairo_Canonical_Operating_Model_v0.2.md`, `Kairo_MVP_Definition_v0.3.md`, `Kairo_Archetype_Decision_Lock_Interview_2026-07-25.md`, `ADP_Archetype_and_Method_Catalog_v0.2.md`, `Kairo_Steering_Method_Kernel_v0.1.md`, `ADP_AP2_4_Steering_Elements_and_Method_Contract_v0.1.md`, `ADP_Steering_Kernel_Coding_Rules_v0.1.md`, `ADP_UX_Composition_Kernel_v0.1.md`, `ADP_AP1_10_Initiative_Archetypes_and_Entity_Field_System_v0.1.md`, `Kairo_Method_Design_Principles_v0.1.md`, `Kairo_MVP_Execution_Plan_v0.2.md` +**Ersetzt nicht:** Plugin-ADPs AP2.3/AP2.4, Steering Kernel Coding Rules, UX Composition Kernel +**Begleitdokument:** `ADP_Template_Blueprint_Scope_Lock_v0.1.md` + +--- + +## 1. Problem & Nordstern + +### 1.1 Ausgangslage + +Kairo hat nach AP2.3/AP2.4 eine saubere Trennung **Archetyp (Schicht 2) ↔ Methode (Schicht 1)** und einen zentralen **Steering Kernel** (`evaluate_steering()`). Für konkrete Vorhabenarten — Karate Kumite, Kairo-Entwicklung, Buch schreiben — fehlt jedoch eine **implementierbare Schicht 3**, die: + +- bei Anlage **sinnvolle Startstruktur** liefert (Starter-Kits AP2.2a), +- **domänenspezifische Felder, Labels und Copy** parametrisiert, +- **tenant-/nutzer-konfigurierbar** ist, ohne neue Archetypen zu erfinden, +- und **keine Steuerungslogik** dupliziert. + +Heute existieren **dünne Code-Seeds** in `backend/method_profiles/registry.py` (`method_profile_key`) mit Metadaten und `seed_hints`, aber **ohne** profil-differenzierte Materialisierung in der UI, ohne Copy-Bindings und ohne tenant-scoped Persistenz. + +### 1.2 Nordstern + +> **Blueprint** = konkrete Vorlage **auf** einem Archetyp für einen **bestimmten Aufgabentyp**. +> Blueprint **parametrisiert und präsentiert** — es **ersetzt keine Methode** und **erfindet keine Steuerungslogik**. + +Kairo bleibt **Program Director** (Vision v0.2, MVP v0.3 §1). Die Leitfrage bleibt: + +> Welcher nächste Schritt bringt dieses Vorhaben **jetzt** am wirksamsten voran — und **warum**? + +Blueprints helfen dem Nutzer, **schneller in methodengerechte Struktur** zu kommen und **passende Sprache** zu sehen — ohne Todo-Explosion (MVP v0.3 §7) und ohne versteckte Archetypen. + +### 1.3 Warum nach MVP Stufe A — nicht davor blockierend + +| Aspekt | Begründung | +|--------|------------| +| AP2.1 Validation | Stufe A muss Steuerung **ohne** Blueprint-Tiefe beweisen | +| AP2.2a Starter-Kits | Liefern **generische** Archetyp-Struktur — Blueprint **verfeinert** dieselbe Pipeline | +| Konzept jetzt | Migrationspfad von Code-Seeds → DB; Bindings-Matrix; Guardrails **vor** Implementierung | +| Implementierung BP-1+ | **Nach** ADP-Freigabe; parallel zu AP2.2c/e möglich — PO entscheidet Minimal-Slice | + +--- + +## 2. Begriffe + +| Begriff | Definition | Abgrenzung | +|---------|------------|------------| +| **Blueprint** (`blueprint_key`) | Versionierte, scope-gebundene Vorlage **auf** einem Archetyp. Bindet Felder, Presets, Copy, Composition-Config, Prompt-Refs — **nicht** Steuerungsalgorithmus. | ≠ Archetyp; ≠ Methode | +| **Vorhaben-Template** | Product-Sprache für Blueprint; synonym im PO-Kontext | Technischer Key: `blueprint_key` | +| **Archetyp** | Schicht 2: Natur, `om_capabilities`, Default-Methode (Empfehlung), EFS-Basis, `ui_profile` (Nav/Routen/Outline) | Ändert sich **nicht** durch Blueprint | +| **Methode** | Schicht 1: Steuerungsplugin im Kernel — `steering_elements`, Strategien, Proposals, Attention | Blueprint darf **keine** Methode ersetzen | +| **Ausprägung** (historisch) | Katalog v0.2 §2.0 Schicht-3-Label für `method_profile_key` | **Wird durch Blueprint ersetzt** (Rename + Superset, siehe §4.4) | +| **Method Profile** (Ist-Code) | Code-Seed in `method_profiles/registry.py` | **Legacy-Anker** → migriert zu System-Blueprint | +| **Preset** | Deklarativer Seed-Block innerhalb eines Blueprints (Starter-Kit-Definition, Recurring-Vorlage, Gate-Namen) | Wird bei Instanziierung **materialisiert** (OM-Objekte) | +| **Seed** | System-definierter Initialwert (Code oder DB), nicht tenant-editierbar im MVP | Blueprint **referenziert** Seeds; Tenant-Kopie darf Presets überschreiben (BP-3+) | +| **Structure Builder** (voll) | Hook-getriebene **Tiefenstruktur** via Method Registry (`on_structure_required`, Builder-Registry) | **Deferred** (MVP Execution Plan); Blueprint **liefert** leichte Presets, **triggert nicht** vollen Builder | +| **Starter-Kit** | AP2.2a: idempotente Materialisierung bei Anlage (`apply_starter_kit`) | Blueprint **liefert** Kit-Definition; Fallback = Archetyp-Default-Kit | +| **Instanziierung** | Vorhaben-Anlage: Blueprint wählen → Presets materialisieren, Referenzen setzen | `initiatives.blueprint_key` + `steering_context.lifecycle_metadata` | +| **Materialisiert** | Kopie in OM (RoadmapItems, Projects, BacklogItems, …) — danach **unabhängig** editierbar | | +| **Referenz** | Bleibt am Vorhaben: `blueprint_key`, `blueprint_version`, Prompt-Refs, Composition-Overrides | Änderung am Blueprint **propagiert nicht** rückwirkend auf materialisierte OM-Objekte (v1) | + +### 2.1 Entscheidungs-Lock: Archetyp ≠ Template + +PO 2026-07-25 (Decision-Lock §7): Template ändert die **Natur** eines Vorhabens nicht. Wesentliche Merkmale (Plan/Ist-Vertrag, Default-Methode-Empfehlung, OM-Capabilities) bleiben am Archetyp; Blueprint liefert **Konkretisierung** (Felder, Darstellung, Presets, Copy). + +--- + +## 3. Schichtenmodell (erweitert) + +### 3.1 Fünf Schichten + Blueprint-Position + +```text +┌──────────────────────────────────────────────────────────────────────────┐ +│ Schicht 4 — Integrationen & Agenten (eingefroren bis AP2.1 Go) │ +│ MCP, Vibe-Coder, Gitea — Hook Slugs, Operational API │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Schicht 3 — Blueprint (Vorhaben-Template / Ausprägung) │ +│ blueprint_key, bindings_json — Felder, Presets, Copy, Composition, │ +│ Prompt-Refs; Scope: system | tenant | user │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Schicht 2 — Archetyp (entity_archetypes + EFS + ui_profile) │ +│ Natur, om_capabilities, Default-Methode, Nav/Routen/Plan-Outline │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Schicht 1 — Methode (Method Registry + Steering Kernel) │ +│ steering_elements, data_slices, Strategien, Proposals, Attention │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Schicht 0 — Framework (OM, TenantContext, Audit, Capabilities) │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +**Katalog v0.2 §2.0 Mapping:** Schicht 3 hieß „Ausprägung (Method Profile)“. Dieses ADP **benennt** sie verbindlich **Blueprint** und erweitert den Vertrag. + +### 3.2 Auflösungskette zur Laufzeit + +```text +Initiative (archetype_key, blueprint_key?) + │ + ▼ +SteeringContext (method_key, lifecycle_metadata) + │ + ├──► Archetyp-Registry ──► ui_profile, om_capabilities, EFS-Basis + ├──► Method Registry ──► steering_elements, data_slices, graph_profile + └──► Blueprint-Resolver ──► bindings (Copy, Presets-Metadaten, Composition-Overrides) + │ + ▼ + GET /initiatives/:id/operating-context + (bestehend + blueprint-Binding-Slice) + │ + ▼ + evaluate_steering() ──► Snapshot (read_models, proposals, agent_slots) + │ + ▼ + resolveSteeringComposition() ──► UI-Slots + Provider (UX Composition Kernel) +``` + +**Regel:** Blueprint-Resolver läuft **neben** Operating Context — **nicht** im Kernel. Kernel liest höchstens **parametrisierte** Werte aus Operating Context (z. B. `proposal_rankers`, `agent_slot_config`) — nie Blueprint-Ifs. + +### 3.3 Kompatibilitätsmatrix (Blueprint ↔ Archetyp ↔ Methode) + +```text +compatible(blueprint, initiative) := + blueprint.initiative_archetype_key = initiative.archetype_key + AND blueprint.method_key = steering_context.method_key + OR blueprint.method_key IS NULL -- „any compatible primary“ + AND blueprint.method_key ∈ compatible_methods(archetype) + AND blueprint.scope erlaubt für Tenant/User +``` + +| Kardinalität | Regel | +|--------------|-------| +| Archetyp → Blueprint | **1:n** — mehrere Blueprints pro Archetyp (Kumite, Spagat, … auf A1) | +| Blueprint → Archetyp | **1:1** — kein Multi-Archetyp-Blueprint | +| Blueprint → Methode | **1:1** optional fix; `NULL` = Default-Methode des Archetyps | +| Vorhaben → Blueprint | **0:1** — optional; ohne Blueprint = Archetyp-Default-Starter | +| Modifier (`agile_iteration`) | Über Blueprint-Flag `composition_hints.agile_iteration` — **kein** eigener Blueprint-Typ | + +--- + +## 4. Template-Metamodell + +### 4.1 Entität `blueprint` (Ziel-Schema) + +Persistenz Zielbild: Tabelle `blueprints` (tenant-scoped für Kopien; `tenant_id NULL` = System). Bis BP-1: Code-Seeds analog `method_profiles/registry.py`. + +| Feld | Typ | Pflicht | Beschreibung | +|------|-----|---------|--------------| +| `blueprint_key` | string (stable slug) | ja | z. B. `maturity.karate_kumite` | +| `version` | semver / int | ja | Monotonic; Published-Version immutable | +| `label` | string | ja | UI-Anzeige (darf Archetyp-Label übersteuern) | +| `description` | text | nein | Kurzbeschreibung für Auswahl-Dialog | +| `initiative_archetype_key` | string | ja | Bindung Schicht 2 | +| `method_key` | string \| null | nein | Fixierte Primary-Methode; null = Archetyp-Default | +| `scope_type` | enum | ja | `system` \| `tenant` \| `user` | +| `scope_tenant_id` | uuid \| null | bedingt | Pflicht bei tenant/user | +| `scope_user_id` | uuid \| null | bedingt | Pflicht bei user | +| `parent_blueprint_key` | string \| null | nein | Vererbung (Tenant-Kopie von System-Blueprint) | +| `status` | enum | ja | `draft` \| `published` \| `deprecated` | +| `bindings_json` | jsonb | ja | Siehe §4.2 | +| `created_at`, `updated_at`, `published_at` | timestamp | ja | Audit | +| `is_system` | bool | ja | System-Blueprints nicht löschbar | + +**Initiative-Referenz:** + +| Feld auf `initiatives` / `steering_context` | Beschreibung | +|---------------------------------------------|--------------| +| `blueprint_key` | Gewählter Blueprint bei Anlage | +| `blueprint_version` | Eingefrorene Version bei Instanziierung | +| `method_profile_key` | **Deprecated-Alias** bis Migrationsende (BP-1) | + +### 4.2 `bindings_json` — Top-Level-Struktur + +Implementierbarer JSON-Vertrag (Auszug): + +```json +{ + "efs": { + "field_defaults": { "discipline": "Karate" }, + "field_overrides": [], + "tenant_field_extensions_allowed": false + }, + "starter_kit": { + "kit_key": "maturity.karate_kumite.v1", + "items": [ + { "kind": "project", "title": "Kumite", "sort_order": 1 }, + { "kind": "maturity_stage", "title": "Stufe 1 — Basis", "status": "active" } + ] + }, + "composition": { + "steering_element_copy": { + "gate_fulfillment": { "horizon_label": "Release-Horizont Kairo" } + }, + "provider_overrides": [ + { "provider_key": "steering.critical_path", "order": 5, "props": {} } + ], + "proposal_ui": { + "intake_triage": { "lead": "Product-Issues triagieren — nicht alles committen." } + } + }, + "steering_presentation": { + "attention_labels": {}, + "agent_slot_copy": {}, + "backlog_vocabulary": { "backlog_item": "Issue" }, + "journey_event_labels": {}, + "graph_labels": {}, + "plan_outline_hints": [] + }, + "prompt_refs": [ + { + "prompt_key": "kairo.product.triage_hint", + "context_kind": "initiative_snapshot", + "placeholder_bindings": { "product_name": "efs.product_vision" } + } + ], + "composition_hints": { + "agile_iteration": true, + "default_actor_setup": "po_plus_vibe_coder" + }, + "ranker_params": { + "intake_triage": { "stale_days_weight": 1.2 } + }, + "guidance": "Eingang triagieren, dann committete Actions — optional Sprint." +} +``` + +**Nicht in bindings_json:** `method_key`-Override auf inkompatiblen Archetyp, Lifecycle-States, neue `steering_elements`, Router-Logik, React-Komponenten-Keys ohne Provider-Registry. + +### 4.3 Lifecycle (draft / published / deprecated) + +| Status | Bedeutung | +|--------|-----------| +| `draft` | Editierbar; nicht in Anlage-Dialog für Endnutzer | +| `published` | Wählbar bei Anlage; Version frozen | +| `deprecated` | Nicht wählbar; bestehende Referenzen bleiben gültig | + +**Versionierung:** Neues `published` = neue `version`; laufende Initiativen behalten `blueprint_version` bei Instanziierung. Kein Auto-Upgrade materialisierter Struktur (v1). + +### 4.4 Method Profile → Blueprint (Rename + Superset) + +**Empfehlung:** + +| Aspekt | Entscheidung | +|--------|--------------| +| Konzept | **Superset** — Blueprint enthält alles, was `method_profile` heute kann, plus Bindings-Matrix | +| Technischer Key | **`blueprint_key`** — `method_profile_key` wird **Alias** in API/Snapshot bis BP-2 abgeschlossen | +| Modul | `backend/method_profiles/` → `backend/blueprints/` (BP-1); Re-Export für Kompatibilität | +| Decision-Lock D1 | `content.book_writing` bindet an **`initiative.linear_project`**, nicht `initiative.content_project` | + +--- + +## 5. Bindings-Matrix + +Legende: + +| Spalte | Bedeutung | +|--------|-----------| +| **Template darf** | Blueprint darf Wert setzen/übersteuern (Präsentation, Defaults, Presets) | +| **Nur System** | Nur `scope_type=system` Blueprints; Tenant/User-Kopien eingeschränkt | +| **Kernel bleibt Owner** | Logik, Algorithmus, Aktivierung — nicht durch Template ersetzbar | +| **Phase** | Erste Implementierungsphase | + +| Bindbares Artefakt | Template darf | Nur System | Kernel bleibt Owner | Phase | +|--------------------|---------------|------------|---------------------|-------| +| **EFS-Felddefinitionen** (Schema) | Nein — nur Archetyp-Registry + Tenant-EFS-Override (AP1.10 Phase 2) | Archetyp-Seeds | EFS-Validierungsservice | — | +| **EFS-Default-Werte** | Ja — `bindings.efs.field_defaults` | System-Blueprints | Validierung gegen `field_definitions` | BP-2 | +| **EFS-Label-Overrides** (Anzeige) | Ja — `field_overrides[].label` | — | Feldtyp/Required | BP-3 | +| **Tenant-nutzerdefinierte Felder** | Flag `tenant_field_extensions_allowed`; keine Schema-Erfindung im Template | Governance-Policy | Tenant-Invariants | BP-3+ | +| **Standardspalten** (`vision`, `goal`, …) | Default-Vorschläge bei Anlage | — | Initiative-Service | BP-2 | +| **Starter-Kit / Struktur-Presets** | Ja — vollständige `starter_kit.items[]` | System-Blueprints für Referenz-Portfolio | `apply_starter_kit` Idempotenz-Regeln | BP-2 | +| **Recurring-Presets** | Ja — als Starter-Items `kind: recurring` | — | Recurring-Service, AP2.0e Cadence-Logik | BP-2 | +| **steering_element UI-Copy** | Ja — Labels/Hints/Empfehlungstexte | — | **Aktivierung** via Methode `steering_elements` | BP-4 | +| **steering_element Sichtbarkeit** | Nein — nur über Methode + `data_slices` | — | `resolve_effective_steering_elements()` | — | +| **Composition-Provider** (Slot, order) | Ja — `order`, `props`, optionales Ausblenden via `enabled: false` | Neue Provider-Kinds | Provider-Registry + Match-Regeln | BP-4 | +| **Proposal-UI-Config** (`gate_next_actions`, `intake_triage`, `sprint_commit`) | Ja — `title`, `lead`, `acceptLabel` | — | Proposal-**Generierung** im Kernel | BP-4 | +| **Proposal-Ranker-Parameter** | Ja — `ranker_params.{proposal_key}` numerische Gewichte | Grenzen via Method Contract | Ranker-Implementierung, SK-05 | BP-5 | +| **Attention-Labels / Severity-Hints** | Ja — Präsentations-Copy für bekannte `attention_code` | — | Attention-**Auslösung** (Contributors) | BP-4 | +| **Agent-Slot-Copy** | Ja — Titel/Hinweis pro `slot_key` | — | Slot-**Existenz** + `agent_slot_config` | BP-5 | +| **Prompt-Referenzen** (key, context_kind, Platzhalter) | Ja — `prompt_refs[]` | Prompt-Inhalt in Prompt-Registry | Ausführung, Audit, Principle Gate | BP-5 | +| **Graph-/Gate-Labels** | Ja — Achsen-/Knoten-Labels, Gate-Titel-Vorschläge | — | Graph-Berechnung, Gate-Fulfillment | BP-4 | +| **Plan-Outline-Hints** | Ja — empfohlene Outline-Reihenfolge, Sektions-Titel | — | Archetyp `ui_profile.planOutline` Basis | BP-4 | +| **Backlog-Vocabulary-Profil** | Ja — Begriffe (`backlog_item` → „Issue“) | — | `resolve_backlog_vocabulary()` Logik | BP-4 | +| **Journey-Event-Typ-Labels** | Ja — Darstellungslabels für Event-Typen | — | Journey-Event-Erzeugung | BP-4 | +| **method_key** | Nein | — | SteeringContext + Kompatibilitätsprüfung | — | +| **archetype_key** | Nein | — | Initiative | — | +| **steering_elements (Aktivierung)** | Nein | — | Method Registry | — | +| **Next-Action-Algorithmus** | Nein | — | `evaluate_steering()` | — | +| **Lifecycle-Override** | Nein | — | Lifecycle-Orchestrator | — | +| **Neue OM-Tabellen / Entitätstypen** | Nein | — | Scope Lock | — | +| **Neue Provider-Kinds (UX)** | Nein | ADP UX Composition | Composition Kernel | — | +| **Archetyp-Ifs in Pages** | Verboten | — | `hasSteeringElement`, Operating Context | — | + +--- + +## 6. Steuerungs-Grenze + +### 6.1 Was bei Archetyp + Methode bleibt + +| Verantwortung | Owner | +|---------------|-------| +| Natur, Plan/Ist-Vertrag | Archetyp | +| `steering_elements`, Proposals, Read Models, Attention | Methode + Kernel | +| Next Work, Ranking, `reason_code` | `evaluate_steering()` | +| Komposition `agile_iteration` | Method Registry (`composes_with`) | +| `data_slices` | Schnittmenge Archetyp ∩ Methode | +| Gate-Fulfillment, Planning Debt | Provider in `steering/proposals/`, `steering/read_models/` | + +### 6.2 SK-Regeln (verbindlich) + +| Regel | Konsequenz für Blueprint | +|-------|--------------------------| +| **SK-01** | Kein Blueprint-Zweig in `evaluate_steering()` | +| **SK-03** | Keine Steuerungsheuristik in Blueprint-Resolver | +| **SK-04** | UI bindet an Proposal-Keys — Blueprint ändert nur Copy/Parameter | +| **SK-05** | Ranker-Parameter nur Gewichte/Schwellen — keine „Bug-zuerst“-Policy im Template | +| **SK-10–12** | Frontend: Composition + `PROPOSAL_UI_CONFIG` Merge aus Operating Context | +| **SK-13–14** | Prompt-Inhalt nie im Blueprint-JSON — nur `prompt_key`-Referenz | + +### 6.3 Anti-Patterns (explizit) + +| Verboten | Konsequenz | +|----------|------------| +| Template als versteckter Archetyp | Neuer `archetype_key` nur via Archetyp-Registry + ADP | +| Todo-Wand durch Template-Listen | Presets ≠ 200 materialisierte Actions; Starter-Kit-Limits | +| Parallele Steuerung in Blueprint-Resolver | Ein Spine: Kernel | +| `if blueprint_key === '…'` in Pages | Nur Composition/Context | +| Template überschreibt `method_key` auf inkompatibel | Validierung bei Anlage | + +--- + +## 7. EFS & nutzerdefinierte Felder + +### 7.1 Feldquellen (Priorität) + +```text +1. Archetyp field_definitions (system, EFS) +2. Tenant-Overrides auf field_definitions (AP1.10 Phase 2 — tenant-scoped) +3. Blueprint field_defaults + label overrides (Schicht 3) +4. Initiative field_values (Instanz) +``` + +### 7.2 Grenzen + +| Thema | Regel | +|-------|-------| +| **Schema-Erfindung** | Blueprint darf **keine** neuen `field_key` ohne Archetyp/EFS-ADP einführen | +| **Tenant-Custom-Fields** | Eigene ADP-Erweiterung; Blueprint kann `tenant_field_extensions_allowed: true` setzen — **nicht** MVP BP-1/2 | +| **Validierung** | PATCH `/fields` validiert gegen effektive Definition — Blueprint-Defaults bei Anlage, danach normal | +| **Steering-Nutzung** | Dynamische Felder in Heuristiken nur mit ADP — Standardspalten + explizite Platzhalter-Bindings | +| **Search/Hot Path** | Nur `searchable=true` Felder; Blueprint-Defaults schreiben `field_values` | + +### 7.3 Tenant-Invariants + +- Alle Blueprint-Kopien: `tenant_id NOT NULL` +- User-Scope: zusätzlich `scope_user_id`; Capability `kairo.blueprint.manage_own` +- System-Blueprints: read-only für Tenants; Kopie erzeugt `scope_type=tenant` + +--- + +## 8. UX / Composition + +### 8.1 Template → UI-Slots + +UX Composition Kernel (ADP UX v0.1) bleibt **Owner** der Slot-/Provider-Registry. Blueprint liefert **Overrides**: + +```text +resolveSteeringComposition( + operatingContext, // enthält blueprint_bindings + steeringSnapshot, + ... +) + → merge PROPOSAL_UI_CONFIG with blueprint.composition.proposal_ui + → merge steeringElementRegistry labels with blueprint.composition.steering_element_copy + → apply provider_overrides (order, props, enabled) +``` + +### 8.2 Verboten + +- Neue `kind`-Werte in `compositionProviders.js` ohne ADP +- Archetyp-Ifs zur Panel-Aktivierung +- Blueprint-spezifische React-Pages + +### 8.3 Cockpit / Portfolio + +Blueprint-Bindings gelten **initiative-scoped**. Portfolio-Aggregation (`GET /workspace/steering`) nutzt **keine** Blueprint-Copy — nur Kernel-Output. + +--- + +## 9. Impulse, Proposals, Attention + +| Aspekt | Blueprint | Kernel | +|--------|-----------|--------| +| Proposal **Existenz** | — | Provider + `steering_elements` | +| Proposal **summary** in DTO | — | Ranker/Provider | +| UI **title/lead/acceptLabel** | Ja | — | +| **reason_code** → Label-Mapping | Erweiterung `proposalReasonLabel`-Map | Codes stabil | +| Attention **Auslösung** | — | Contributors | +| Attention **Anzeige-Text** | Ja (`attention_labels`) | — | +| Programm-**Impulse** (B2a) | Copy für Impulse-Typen | Nested Context Kernel | + +**Ranker-Parameterisierung:** Blueprint liefert `ranker_params` → Operating Context → Kernel liest bei Ranker-Aufruf. Keine neuen Ranker-Keys im Template ohne Registry-Eintrag. + +--- + +## 10. KI / Prompts + +### 10.1 Binding-Modell + +```text +Blueprint.prompt_refs[]: + prompt_key → Eintrag in prompt_definitions (Foundation) + context_kind → initiative_snapshot | operating_context | agent_slot_payload + placeholder_bindings → { "product_name": "efs.product_vision" | "snapshot.method_key" } +``` + +### 10.2 Governance + +| Regel | Detail | +|-------|--------| +| Freeze | **Keine produktive KI-Ausführung** bis AP2.1 Go — BP-5 Implementierung, nicht BP-1 | +| SK-13 | Kein Prompt-Text in Blueprint, UI, Router | +| Audit | Ausführung über bestehende `prompt_execution_logs` | +| Agent-Slots | SK-17: Slots deklarativ; Prompt-Ref optional an Slot | + +--- + +## 11. Structure Builder — Abgrenzung + +| Aspekt | Starter-Kit / Blueprint | Structure Builder (voll) | +|--------|-------------------------|---------------------------| +| **Wann** | Bei Initiative-Anlage | Hook `on_structure_required` / Lifecycle Schlitz 3 | +| **Tiefe** | 5–15 Seed-Objekte, Guidance | Tiefen-WBS, Feature-Landschaft, Graph-Generierung | +| **Owner** | Blueprint `starter_kit` + `apply_starter_kit` | Method Registry Builder | +| **MVP** | **Ja** (AP2.2a + BP-2) | **Deferred** | +| **Beziehung** | Blueprint **kann** `structure_builder_hint` setzen — triggert später optional Builder | Builder liest Hint, nicht Blueprint-If | + +**Regel:** Blueprint **ersetzt** Structure Builder nicht. Bei BP-6+ Designer kann Tenant Presets erweitern — bleibt unter Builder-Hook-Governance. + +--- + +## 12. Persistenz-Zielbild + +### 12.1 Tabellen (Phase C Erweiterung Target Architecture §15) + +```text +blueprints ( + id, blueprint_key, version, label, description, + initiative_archetype_key, method_key, + scope_type, tenant_id, user_id, + parent_blueprint_key, status, bindings_json, + is_system, created_at, updated_at, published_at +) + +initiatives.blueprint_key -- nullable +initiatives.blueprint_version -- nullable, gesetzt bei Anlage +steering_context.lifecycle_metadata.blueprint_key -- Spiegel / Legacy method_profile_key +``` + +**Indizes:** `(tenant_id, initiative_archetype_key, status)`, `(blueprint_key, version)` unique. + +### 12.2 Code-Seeds → DB (BP-1) + +1. Inhalt von `METHOD_PROFILES` nach `blueprints` migrieren (System, `published`) +2. `bindings_json` minimal: `guidance`, `starter_kit` aus erweiterten Seeds, `composition_hints` +3. API: `GET /api/blueprints?archetype_key=…` ersetzt erweitert `GET /steering/method-profiles` +4. Alias: `method_profile_key` ↔ `blueprint_key` (identische Werte in v1) + +--- + +## 13. Migrationspfad — Phasenplan AP-BP-1…n + +| Phase | Ziel | Deliverables | Abhängigkeit | Nicht in Phase | +|-------|------|--------------|--------------|----------------| +| **BP-0** | Konzeption | Dieses ADP + Scope Lock | — | Code | +| **BP-1** | Read-only System-Blueprints | DB-Tabelle + Seed-Migration; API list/get; Operating Context `blueprint_key`; Alias `method_profile_key` | ADP frei | Anlage-Materialisierung, Tenant-Kopien | +| **BP-2** | Anlage: Template wählen + materialisierte Presets | Anlage-Dialog Blueprint-Auswahl; `apply_starter_kit` aus Blueprint; EFS-Defaults; `blueprint_version` speichern | AP2.2a+, BP-1 | Copy-Bindings, Designer | +| **BP-3** | Tenant-Kopie + editierbare Felder/Presets | Fork System→Tenant; PATCH bindings (draft); Capability-Gate | Tenant-Invariants, BP-2 | Prompt-Ausführung | +| **BP-4** | Composition + Copy-Bindings | Merge in `resolveSteeringComposition`; Backlog-Vocabulary; Proposal/Attention-Copy | UX Kernel MVP, BP-1 | KI-Produktion | +| **BP-5** | Prompt/Agent-Bindings | `prompt_refs` Auflösung; Agent-Slot-Copy; `ranker_params` | **AP2.1 Go**, BP-4 | Designer | +| **BP-6** | Designer / Import | Visueller Blueprint-Editor; YAML-Import; Versionierung UI | BP-3, PO-Priorität | — | + +### 13.1 Parallelität zu MVP Stufe A + +```text +AP2.1 Validation (Stufe A Abschluss) ──┐ +AP2.2c / AP1.9d ──┼── parallel möglich, nicht blockiert durch BP-0 +BP-1 (Read-only Seeds) ──┘ nach ADP-Freigabe; PO entscheidet Minimal-Slice + +BP-2+ sollte AP2.2a Starter-Kit-Pipeline nutzen — nicht ersetzen. +BP-5 explizit nach AP2.1 Go — KI/Prompt eingefroren. +``` + +### 13.2 Was **nicht** vor AP2.1 Go + +- Produktive Prompt-Ausführung aus Blueprint +- Agent-Ranker (`agent_v1`) Parameter aus Template +- MCP/Workflow-Fragmente an Blueprint gebunden + +--- + +## 14. Referenz-Blueprints (Beispiele — keine Vollimplementierung) + +### 14.1 `product.kairo_dev` + +| Attribut | Wert | +|----------|------| +| Archetyp | `initiative.product` | +| Methode | `continuous_product` | +| Komposition | `agile_iteration` via `composition_hints` | +| EFS-Defaults | `product_vision`, `primary_repo_or_system` (Platzhalter) | +| Starter-Kit | Gates „Orientierung“, „Nächster Release-Horizont“; Projects „Entwicklung“, „Betrieb“; Sample-Backlog „Idea“ | +| Composition | `gate_fulfillment`-Horizont-Copy; Sprint-Hinweis wenn `work_cycle_scope` aktiv | +| Proposals | `intake_triage.lead` product-spezifisch | +| Prompt-Ref (BP-5) | `kairo.product.triage_hint` | +| Backlog-Vocabulary | `backlog_item` → „Issue“ | +| **Nicht** | Eigene Next-Action-Strategie; kein erzwungenes `critical_path`; kein Archetyp-Wechsel | + +**Differenzierung zu Generic Product:** Labels, Gate-Namen, Issue-Vokabular, PO+Vibe-Coder-Hint — **gleiche** `steering_elements` wie `continuous_product`. + +### 14.2 `maturity.karate_kumite` + +| Attribut | Wert | +|----------|------| +| Archetyp | `initiative.maturity_journey` | +| Methode | `maturity_progression` | +| EFS-Defaults | `discipline` = „Karate“ | +| Starter-Kit | 8 Projects (Fähigkeiten) × Stufen-Presets (5–7 `maturity_stage` pro Skill — **Struktur-Seed**, nicht 200 Tasks); Recurring „Training“ | +| Journey-Labels | Kumite-spezifische Event-Darstellung | +| Graph | `graph_prerequisites: true` — Labels only; Kanten manuell/separater Graph-Setup | +| **Nicht** | Stufenwechsel-Logik im Template — bleibt Kernel + AP2.0e; keine neuen OM-Typen | + +**Differenzierung zu Generic A1:** Disziplin-Feld, 8-Skill-Raster, Kumite-Vokabular — **gleiche** Methode `maturity_progression`. + +### 14.3 `content.book_writing` + +| Attribut | Wert | +|----------|------| +| Archetyp | **`initiative.linear_project`** (Decision-Lock D1 — kein `content_project`) | +| Methode | `sequential_dependency` (+ optional `agile_iteration`) | +| EFS-Defaults | `word_goal`, `genre` | +| Starter-Kit | Kapitel als `milestone`/`chapter`-RoadmapItems; Review-Gate-Presets; Project „Manuskript“ | +| Composition | `gate_next_actions.lead` schreib-orientiert | +| Plan-Outline-Hints | Kapitel → Review → Revision | +| **Nicht** | Eigene Kapitel-Steuerungsmethode; `chapter_based_progression` nur wenn Methode explizit gewählt und kompatibel | + +**Hinweis Migration:** Ist-Seed `content.book_writing` in `method_profiles/registry.py` referenziert noch `initiative.content_project` — bei BP-1 auf Decision-Lock korrigieren. + +--- + +## 15. Abnahme & PO-Freigabe + +### 15.1 Qualitätskriterien (AP-BP-0 Prompt) + +- [x] Entwickler kann aus §4.2 + §5 ableiten, welche JSON-Felder ein Blueprint hat +- [x] Laufzeit-Auflösung neben Operating Context dokumentiert (§3.2) +- [x] Mindestens zwei Referenz-Blueprints differenzierbar ohne neues Steering (§14.1, §14.2) +- [x] Anti-Patterns MVP v0.3 §3 und SK-Regeln adressiert (§6.3) +- [x] Migrationspfad `method_profiles/registry.py` dokumentiert (§12.2, §4.4) +- [x] KI/Designer als Phasen, nicht MVP-Blocker (§13, BP-5/6) +- [x] Konflikte Katalog v0.2 / Decision-Lock markiert (§14.3, §16) + +### 15.2 PO-Freigabe-Checkliste + +- [ ] Blueprint vs. Method Profile Rename akzeptiert +- [ ] Bindings-Matrix Scope für BP-1…4 bestätigt +- [ ] Referenz-Blueprints (Kumite, Kairo Dev, Buch) als System-Seeds freigegeben +- [ ] Parallelität BP-1 vs. AP2.1 explizit entschieden +- [ ] Tenant-Custom-Fields-Grenze (BP-3 vs. EFS Phase 2) entschieden + +--- + +## 16. Offene Entscheidungen (PO) + +| # | Frage | Optionen | Empfehlung | +|---|-------|----------|------------| +| **O-1** | Minimal-Slice: BP-1 vor AP2.1? | A) BP-1 parallel B) BP-1 nach AP2.1 Go | A — read-only, risikoarm | +| **O-2** | API-Key: sofort `blueprint_key` oder Alias-Phase? | A) Dual-Key 6 Monate B) Hard cut | A — Dual-Key | +| **O-3** | User-Scope Blueprints (`scope_type=user`)? | A) BP-3 B) BP-6 C) Nie | B — erst mit Designer | +| **O-4** | Tenant darf System-Blueprint `bindings_json` überschreiben oder nur Fork? | A) Fork only B) Overlay | A — Fork only (Audit, Versionierung) | +| **O-5** | Materialisierte Presets bei Blueprint-Version-Upgrade? | A) Nie auto B) Opt-in Migration C) Nur Copy | A für v1 | +| **O-6** | `content.book_writing`: Methode `sequential_dependency` oder `chapter_based_progression`? | Decision-Lock: A2 + Profil | `sequential_dependency` Default; `chapter_based_progression` wenn PO als kompatible Methode freigibt | +| **O-7** | Blueprint-Auswahl Pflicht bei Anlage? | A) Optional B) Pflicht wenn >1 | A — Optional mit Empfehlung | +| **O-8** | Projekt-Blueprints (Phase 2 AP1.10)? | A) Initiative only v1 B) Project später | A — Initiative only v1 | +| **O-9** | Ranker-Parameter: Allowlist pro Proposal-Key? | A) Ja B) Freies JSON | A — Allowlist in Method Contract | +| **O-10** | Katalog v0.3: Schicht-3-Label „Blueprint“ statt „Ausprägung“? | A) Ja B) Beide | A | + +--- + +## 17. Konfliktauflösung + +| Konflikt | Auflösung | +|----------|-----------| +| Katalog v0.2 D1 `content_project` vs. Decision-Lock A2+Profil | **Decision-Lock führt** — Blueprint `content.book_writing` auf `linear_project` | +| Katalog v0.2 „Ausprägung“ vs. PO „Template“ | **Blueprint** = offizieller Name; Ausprägung historisch | +| `method_profile_key` in API/Snapshot | Alias bis BP-2 abgeschlossen | +| UX Composition: Provider-Props aus Blueprint vs. Registry | Registry definiert Kind; Blueprint nur `props`/`order`/`enabled` | +| AP2.4: `agile_iteration` über Profil | **`composition_hints.agile_iteration`** im Blueprint — kein separates Profil-Objekt | + +--- + +## 18. Referenzen + +| Artefakt | Pfad | +|----------|------| +| Konzeptions-Prompt | `docs/architecture/AP_BP_0_Template_Blueprint_Conception_Prompt_v0.1.md` | +| Scope Lock | `docs/architecture/ADP_Template_Blueprint_Scope_Lock_v0.1.md` | +| Method Profiles (Ist) | `backend/method_profiles/registry.py` | +| Starter-Kits | `backend/services/archetype_starter_kit.py` | +| Operating Context | `backend/services/operating_context.py` | +| UX Composition | `frontend/src/composition/` | +| Proposal UI Config | `frontend/src/utils/steeringProposals.js` | + +--- + +*AP-BP-0 Ergebnis — kein Code. Implementierung erst nach PO-Freigabe dieses ADP.* diff --git a/docs/architecture/AP_BP_0_Template_Blueprint_Conception_Prompt_v0.1.md b/docs/architecture/AP_BP_0_Template_Blueprint_Conception_Prompt_v0.1.md new file mode 100644 index 0000000..8abd666 --- /dev/null +++ b/docs/architecture/AP_BP_0_Template_Blueprint_Conception_Prompt_v0.1.md @@ -0,0 +1,227 @@ +# AP-BP-0 — Konzeptions-Prompt: Vorhaben-Template / Blueprint-Architektur + +**Status:** Arbeitsauftrag für Konzeptionsphase (kein Implementierungs-AP) +**Stand:** 2026-07-27 +**Ziel-Deliverable:** `ADP_Vorhaben_Template_Blueprint_v0.1.md` (+ optional Scope-Lock-ADP) +**Nicht-Ziel:** Code, Migrationen, UI-Implementierung — erst nach PO-Freigabe des ADP + +--- + +## Rolle des Agents + +Du bist **Architekt:in für Jinkendo Kairo**. Deine Aufgabe ist eine **implementierbare, guardrail-konforme Konzeption** für die Schicht **Vorhaben-Template / Blueprint** — nicht ein generisches Template-Engine-Design und kein zweites Operating Model. + +Kairo ist **Program Director**, kein To-do-Tool. Steuerung läuft zentral über `backend/steering/` (`evaluate_steering()`). Templates **parametrisieren und präsentieren**, sie **ersetzen keine Methode** und **erfinden keine neue Steuerungslogik**. + +--- + +## PO-Vorgabe (verbindlich) + +> Steuerung bleibt **Archetyp- und Steuerungstyp-spezifisch**. +> Templates liefern später einen **Blueprint für einen bestimmten Aufgabentyp**: individuelle Felder, Prompts für KI-Auswertungen, Empfehlungen/Impulse, grafische Darstellungen, nutzerdefinierte Felder, Presets — **tenant-/nutzer-konfigurierbar in weiten Teilen**. + +**Archetyp ≠ Template** (Decision-Lock 2026-07-25): Template ändert die **Natur** eines Vorhabens nicht. + +--- + +## Pflichtlektüre (in dieser Reihenfolge) + +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_MVP_Definition_v0.3.md` — §2 Schichtenmodell, §7 Anti-Todo-Wand +4. `docs/architecture/ADP_Archetype_and_Method_Catalog_v0.2.md` — §2.0 Vier Schichten, §2.2 Ausprägung +5. `docs/product/Kairo_Archetype_Decision_Lock_Interview_2026-07-25.md` — §7 Archetyp ≠ Vorhaben-Template +6. `docs/architecture/Kairo_Steering_Method_Kernel_v0.1.md` — §10 Beziehung zu Archetypen und Templates +7. `docs/architecture/ADP_AP2_4_Steering_Elements_and_Method_Contract_v0.1.md` +8. `docs/architecture/ADP_Steering_Kernel_Coding_Rules_v0.1.md` (SK-01…SK-19) +9. `docs/architecture/ADP_UX_Composition_Kernel_v0.1.md` — Frontend-Spiegel, UI-Slots +10. `docs/architecture/ADP_AP1_10_Initiative_Archetypes_and_Entity_Field_System_v0.1.md` — EFS +11. `docs/architecture/Kairo_Method_Design_Principles_v0.1.md` — §8 Structure Builder (Abgrenzung) +12. `docs/product/Kairo_MVP_Execution_Plan_v0.2.md` — Starter-Kits statt voller Structure Builder + +**Ist-Code (Referenz, nicht blind kopieren):** + +- `backend/method_profiles/registry.py` — heutige Code-Seeds (Schicht-3-Anker) +- `backend/services/archetype_starter_kit.py` — AP2.2a Starter-Kits +- `backend/services/operating_context.py` — Laufzeit-Auflösung +- `frontend/src/composition/` — UX Composition Kernel (Provider, Slots) +- `frontend/src/registry/steeringElementRegistry.js` + +--- + +## Kontext: Was heute existiert (Baseline) + +| Baustein | Stand | Rolle | +|----------|-------|-------| +| Archetyp-Registry + EFS | ✓ | Schicht 2 — Natur, Default-Methode, Felder | +| Method Registry + Kernel v0.4 | ✓ | Schicht 1 — Steuerung | +| `method_profile_key` (4 Code-Seeds) | ◐ | Schicht-3-Anker; API + Metadata; **kein** profil-differenziertes Starter-Kit in UI | +| Starter-Kits AP2.2a | ✓ | Leichte Startstruktur; Ersatz für MVP-Structure-Builder | +| UX Composition Kernel | ✓ MVP | UI-Slots/Provider aus `steering_elements` + Kernel-Proposals | +| Structure Builder (voll) | ✗ deferred | Zielbild in Method Design Principles | +| Tenant-Template-Designer | ✗ | Zielbild Target Architecture §15 | +| KI/Prompt produktiv | ✗ eingefroren | bis AP2.1 Go; Prompt-Registry existiert Foundation-seitig | + +**Wichtig:** Das Konzept muss den **Migrationspfad** von Code-Seeds → tenant-scoped Blueprints beschreiben, ohne MVP Stufe A zu blockieren. + +--- + +## Leitfragen der Konzeption + +1. **Was ist ein Blueprint/Template formal?** (Entität, Version, Scope: system / tenant / user, Vererbung) +2. **Was darf ein Template binden?** (Felder, EFS-Overrides, Starter-Presets, UI-Copy, Composition-Provider-Config, Prompt-Ref-IDs, Impuls-Texte, Graph-Labels, …) +3. **Was darf ein Template explizit NICHT?** (Next-Action-Algorithmus, Lifecycle-Override, neue OM-Tabellen, Archetyp-Ifs in Pages, Router-Steuerung) +4. **Wie hängt Template an Archetyp + Methode?** (Kompatibilitätsmatrix; ein Template pro Aufgabentyp; mehrere Templates pro Archetyp?) +5. **Wie unterscheidet sich Template von Ausprägung (`method_profile_key`) und von Structure Builder?** +6. **Wie nutzt der UX Composition Kernel Template-Config?** (Provider-Props, Copy, Sichtbarkeit — nicht neue Provider-Kinds ohne ADP) +7. **Wie nutzt der Steering Kernel Template-Config?** (Proposal-Copy, Ranker-Parameter, Attention-Schwellen — über Registry, nicht Hardcode) +8. **Wie werden KI-Prompts gebunden?** (Platzhalter-Registry, Template → prompt_key + context_kind; Audit; kein Prompt im React) +9. **Nutzerdefinierte Felder:** EFS-Erweiterung tenant-scoped vs. Template-scoped — Grenzen, Validierung, Governance +10. **Instanziierung:** Bei Vorhaben-Anlage — Template wählen → was wird materialisiert vs. was bleibt Referenz? +11. **Konfiguration durch User:** Was ist MVP-nah (Kopie + Felder editieren) vs. post-MVP (Designer, Import)? +12. **Anti-Patterns:** Template als versteckter Archetyp; Todo-Wand durch Template-Listen; parallele Steuerung + +--- + +## Gewünschte Deliverables + +### 1. Hauptdokument: `ADP_Vorhaben_Template_Blueprint_v0.1.md` + +Mindestens diese Abschnitte: + +| § | Inhalt | +|---|--------| +| 1 Problem & Nordstern | Warum Blueprint nach MVP Stufe A; Bezug Program Director | +| 2 Begriffe | Blueprint, Template, Ausprägung, Preset, Seed, Structure Builder — **eindeutige Abgrenzung** | +| 3 Schichtenmodell (erweitert) | Schicht 0–4 + wo Blueprint sitzt; Diagramm | +| 4 Template-Metamodell | Felder, Relationen, Lifecycle (draft/published/deprecated) | +| 5 Bindings-Matrix | Zeilen = bindbare Artefakte; Spalten = erlaubt / parametrisierbar / verboten / Phase | +| 6 Steuerungs-Grenze | Was bleibt bei Archetyp+Methode; SK-Regeln; `evaluate_steering()` single spine | +| 7 EFS & nutzerdefinierte Felder | Feldquellen, Validierung, Tenant-Invariants | +| 8 UX / Composition | Template → UI-Slots, Provider-Props, Labels; kein Archetyp-If | +| 9 Impulse, Proposals, Attention | Template-Copy vs. Kernel-Logik; Ranker-Parameterisierung | +| 10 KI / Prompts | Binding-Modell; Governance; Freeze bis AP2.1 | +| 11 Structure Builder | Abgrenzung: wann Template seedet vs. Builder hook | +| 12 Persistenz-Zielbild | Code-Seeds → DB-Tabellen (Referenz Target Architecture §15) | +| 13 Migrationspfad | AP-BP-1…n Phasen; was **nicht** vor AP2.1 Go | +| 14 Referenz-Blueprints | Kumite, Kairo Dev, Buch — als **Beispiele**, nicht als Vollimplementierung | +| 15 Abnahme & PO-Freigabe | Checkliste | +| 16 Offene Entscheidungen | Explizit markieren, nicht wegdesignen | + +### 2. Optional: `ADP_Template_Blueprint_Scope_Lock_v0.1.md` + +Kurzes Scope-Lock-Dokument: Was in Phase 1 **nicht** gebaut wird. + +### 3. Bindings-Matrix (Pflicht-Artefakt) + +Tabelle mindestens für: + +- EFS-Felddefinitionen & Default-Werte +- Starter-Kit / Struktur-Presets +- `steering_element` UI-Copy & Sichtbarkeit +- Composition-Provider (Slot, order, embedded props) +- Proposal-UI-Config (`gate_next_actions`, `intake_triage`, …) +- Attention-Labels / Severity-Hints +- Agent-Slot-Copy +- Prompt-Referenzen (key, context_kind, Platzhalter) +- Graph-/Gate-Labels, Plan-Outline-Hints +- Backlog-Vocabulary-Profil +- Journey-Event-Typ-Labels (Darstellung) + +Pro Zeile: **Template darf** | **nur System** | **Kernel bleibt Owner** + +### 4. Phasenplan AP-BP-1…n + +| Phase | Ziel | Abhängigkeit | +|-------|------|--------------| +| BP-1 | Read-only System-Blueprints (Seed-Migration) | ADP frei | +| BP-2 | Anlage: Template wählen + materialisierte Presets | AP2.2a+ | +| BP-3 | Tenant-Kopie + editierbare Felder/Presets | Tenant-Invariants | +| BP-4 | Composition + Copy-Bindings | UX Kernel | +| BP-5 | Prompt/Agent-Bindings | AP2.1 Go | +| BP-6 | Designer / Import | optional spät | + +--- + +## Harte Guardrails (nicht verhandelbar) + +- Keine Steuerungslogik in Templates, Routern oder React-Pages +- Keine Archetyp-Ifs zur Aktivierung von Panels — nur `steering_elements`, Proposals, Capabilities, Template-Config +- Keine neuen OM-Tabellen pro Template-Typ ohne ADP + Scope Lock +- Keine hardcodierten Prompts in UI oder Backend-Routern +- User ≠ Actor; Tenant-scoped; Auth/Capability/Governance getrennt +- Template darf **nicht** `method_key` oder Archetyp-Natur überschreiben (nur kompatible Ausprägung innerhalb des Archetyps) +- MVP Stufe A (AP2.1) **nicht** als Blocker für Konzept — Implementierung BP-1+ **nach** AP2.1 unless explizit PO-Minimal-Slice + +--- + +## Explizite Abgrenzungen (im Konzept klären) + +| Konzept | Abgrenzung zu Blueprint | +|---------|-------------------------| +| **Archetyp** | Natur, OM-Capabilities, Default-Methode, Plan/Ist-Vertrag | +| **Methode** | Steuerungsplugin im Kernel | +| **Method Profile (heute)** | Dünner Seed-Anker — Blueprint **superset** oder **Rename**? Begründen. | +| **Starter-Kit** | Materialisierung bei Anlage — Blueprint **liefert** Kit-Definition? | +| **Structure Builder** | Hook-getriebene Tiefenstruktur — Blueprint **triggert** oder **ersetzt**? | +| **UX Composition Provider** | Renderer — Blueprint **konfiguriert**, erfindet keine neue Kind-Logik | +| **Referenz-Ausprägung (Kumite, Kairo Dev)** | Erste System-Blueprints | + +--- + +## Qualitätskriterien für das Konzept + +Das ADP ist **freigabefähig**, wenn: + +- [ ] Ein Entwickler aus §4 + Bindings-Matrix ableiten kann, **welche JSON/YAML-Felder** ein Blueprint hat +- [ ] Klar ist, **wo** Template zur Laufzeit aufgelöst wird (neben Operating Context) +- [ ] Mindestens **zwei Referenz-Blueprints** (Kumite, Kairo Dev) durch das Modell **differenzierbar** beschrieben sind — ohne neues Steering-Verhalten +- [ ] Anti-Patterns aus MVP v0.3 §3 und Method Kernel SK-Regeln **explizit** adressiert sind +- [ ] Migrationspfad von `method_profiles/registry.py` dokumentiert ist +- [ ] Kein Scope Creep: KI-Produktion, MCP, Designer als **Phasen**, nicht MVP-Blocker +- [ ] Konflikte mit ADP Catalog v0.2 / UX Composition v0.1 **aufgelöst oder als Offen markiert** + +--- + +## Arbeitsmodus + +1. **Nur lesen** — kein Code, keine Migration, kein UI-Patch +2. **Zuerst** Begriffe + Bindings-Matrix + Steuerungs-Grenze — dann Persistenz +3. **Diagramme:** Schichtenmodell + Auflösungskette (Template + Operating Context → Snapshot → Composition) +4. **Offene PO-Fragen** gesammelt am Ende — nicht still entscheiden +5. Output-Sprache: **Deutsch** +6. Format: Markdown unter `docs/architecture/` +7. Bei Widerspruch gilt: Vision v0.2 → COM v0.2 → MVP v0.3 → dieses Prompt-Dokument + +--- + +## Referenz-Beispiel (Zielbild, nicht implementieren) + +**Blueprint `product.kairo_dev`** auf Archetyp `initiative.product` + Methode `continuous_product`: + +- EFS: `product_vision`, `primary_repo_or_system` vorbelegt +- Starter: Orientierungs-Gates, Projects Entwicklung/Betrieb, Sample-Backlog „Idea“ +- Composition: `gate_fulfillment`-Horizont-Copy, Sprint-Hinweis wenn `work_cycle_scope` +- Proposals: `intake_triage`-Lead-Text product-spezifisch +- Prompt-Ref (später): `kairo.product.triage_hint` — Platzhalter aus Snapshot +- **Nicht:** eigene Next-Action-Strategie, kein `critical_path` + +**Blueprint `maturity.karate_kumite`** auf A1: + +- EFS: `discipline` = Karate +- Starter: 8 Skills × Stufen-Presets (Struktur-Seed, nicht 200 Tasks) +- Recurring-Presets pro Stufe (Verweis AP2.0e) +- Journey-Labels kumite-spezifisch +- **Nicht:** Stufenwechsel-Logik im Template — bleibt Kernel/AP2.0e + +--- + +## Was nach der Konzeption passiert (nicht Teil dieses Prompts) + +- PO-Freigabe ADP +- Dann erst: MVP-Stufe-A-Abschluss (AP2.2c, AP1.9d, AP2.1) **parallel oder vor** BP-1 — PO entscheidet +- Implementierung AP-BP-1+ gemäß Phasenplan + +--- + +*Dieses Dokument ist der **Prompt/Arbeitsauftrag** für AP-BP-0. Ergebnis = ADP v0.1, kein Code.*