# Kairo – Method Design Principles ## v0.1 – Designprinzipien für registrierbare Steuerungsmethoden **Status:** verbindlicher Architektur- und Methodendesign-Entwurf **Stand:** 2026-07-05 **Zweck:** Definition der Designprinzipien, nach denen Kairo-Methoden künftig entwickelt, registriert, erweitert und versioniert werden. --- ## 1. Ziel Kairo soll im Lauf der Zeit viele unterschiedliche Steuerungsmethoden unterstützen, ohne dass für jede Methode der komplette Codekern angepasst werden muss. Methoden sollen sich ähnlich wie Widgets an einem klaren Abstraktionslayer anmelden können. Die Architektur muss ermöglichen: ```text - neue Methoden hinzufügen - bestehende Methoden versionieren - methodenspezifische Steuerungsstrukturen erzeugen - methodenspezifische NextAction-Logik einhängen - methodenspezifische Review-/Evidence-Logik einhängen - später Method Profiles konfigurieren - später Workflow-Fragmente an Hooks binden - später Agent/LLM/Tool-Steps pro Methode erlauben ``` Gleichzeitig darf die Methodenarchitektur nicht beliebig und untestbar werden. --- ## 2. Grundprinzip Eine Kairo-Methode ist kein Label. Eine Kairo-Methode ist ein registriertes Steuerungspaket. Sie beschreibt: ```text - für welche Domains sie gilt - welche Scope Types sie steuern kann - welchen Standard Lifecycle sie nutzt oder erweitert - welche Steuerungsstrukturen sie benötigt - welche Hook Slugs sie unterstützt - welche Structure Builder sie bereitstellt - welche Signal Rules sie registriert - welche NextAction Strategy sie nutzt - welche Assignment / Waiting / Reminder / Escalation Strategy sie nutzt - welche Review- und Evidence-Policies gelten - welche Workflow-Fragmente später erlaubt sind - welche Node Types später erlaubt sind ``` --- ## 3. Method Registry als zentraler Erweiterungspunkt Alle Methoden registrieren sich in einer zentralen Method Registry. Zielbild: ```text backend/steering/methods/registry.py ``` Beispielhafte Registrierung: ```python register_method( MethodDefinition( method_key="maturity_progression", version="v1", label="Maturity Progression", supported_domains=["maturity_development", "personal_development"], supported_scope_types=["initiative", "roadmap_item", "action"], default_lifecycle="standard_development_lifecycle", required_structures=["roadmap", "roadmap_lanes", "roadmap_items", "backlog", "actions"], hook_slugs=[ "on_goal_captured", "on_structure_required", "on_maturity_path_required", "on_next_action_requested", "on_evidence_required", "on_review_due", "on_reassessment_required", ], structure_builders=[ "maturity_path_builder", "practice_backlog_builder", ], signal_rule_providers=[ "maturity_gap_attention_rules", "evidence_required_rules", ], next_action_strategy="maturity_next_action_strategy", assignment_strategy="default_actor_assignment_strategy", waiting_strategy="default_waiting_strategy", review_strategy="maturity_review_strategy", evidence_policy="maturity_evidence_policy", allowed_node_types=[ "human_task", "evidence_check", "review", "reflection", "llm_prompt", "agent_task", ], ) ) ``` --- ## 4. Built-in zuerst, konfigurierbar später Die Methodenarchitektur folgt einem Stufenmodell. ### Stufe 1 – Built-in Methods ```text - Methoden code-seitig definiert - klare Slugs - testbar - keine freie Nutzerkonfiguration ``` ### Stufe 2 – Built-in Method Profiles ```text - vordefinierte Profile pro Methode - z. B. "einfach", "evidence_strict", "review_driven" ``` ### Stufe 3 – Tenant Method Profiles ```text - tenant-spezifische Konfiguration - begrenzte Parameter - keine freie Ausführungslogik ``` ### Stufe 4 – Workflow Bindings an Hooks ```text - kleine Workflow-Fragmente an definierte Hooks - nur erlaubte Node Types - nur innerhalb Method Governance ``` ### Stufe 5 – Method Designer ```text - spätere UI - nur für fortgeschrittene Nutzung - Governance, Tests und Freigaben erforderlich ``` --- ## 5. Zentrale gemeinsame Strukturen Alle Methoden müssen auf gemeinsamen Kairo-Strukturen aufbauen. Gemeinsame Kernstrukturen: ```text SteeringContext Roadmap RoadmapLane RoadmapItem BacklogItem Action ActionAssignment Blocker Signal AttentionItem NextActionCandidate Evidence Review Decision Actor Capability AuditEvent ``` Eine Methode darf keine parallelen Kernmodelle erfinden. Beispiele: ```text Meilenstein = RoadmapItem(type = milestone) Reifegrad = RoadmapItem(type = maturity_stage) Feature = RoadmapItem(type = feature) Kapitel = RoadmapItem(type = chapter) Sprint-Grobplanung = RoadmapItem(type = work_cycle) ``` --- ## 6. Minimaler Standard Lifecycle Alle Methoden basieren auf einem gemeinsamen minimalen Lifecycle. ```text intake method_selection structure_setup planning action_selection assignment waiting result_intake validation review adaptation closure ``` Eine Methode darf: ```text - Schritte auslassen - Schritte spezialisieren - zusätzliche Hook Slugs ergänzen - eigene Structure Builder an bestimmten Schritten registrieren ``` Eine Methode darf nicht: ```text - Tenant-Sicherheit umgehen - eigene Actor-Logik außerhalb des Actor-Modells einführen - eigene Rechteprüfung außerhalb der Capability-Schicht einführen - persistente Kernobjekte ohne Service-/Audit-Schicht verändern ``` --- ## 7. Hook Slugs Hook Slugs sind stabile Einhängepunkte. Sie sind die Hauptabstraktion, über die Methoden erweitert werden. Beispiele: ```text on_goal_captured on_method_selection_required on_method_selected on_structure_required on_roadmap_required on_backlog_required on_wbs_required on_maturity_path_required on_content_structure_required on_plan_required on_dependency_analysis_required on_dod_definition_required on_next_action_requested on_assignment_required on_wait_started on_due_date_reached on_result_overdue on_reminder_required on_escalation_required on_result_received on_dod_check_required on_evidence_required on_quality_gate_required on_review_due on_reassessment_required on_reflection_required on_replan_required on_structure_update_required on_closure_requested ``` Hook Slugs müssen: ```text - eindeutig sein - versionierbar bleiben - fachlich benannt sein - in Method Definitions referenziert werden - in Signals als Ursache auftauchen können - später Workflow Bindings tragen können ``` --- ## 8. Structure Builder Structure Builder legen die methodenspezifische Steuerungsstruktur an. Beispiele: ```text roadmap_builder milestone_plan_builder feature_landscape_builder wbs_builder backlog_builder maturity_path_builder chapter_structure_builder cycle_structure_builder review_gate_builder routine_structure_builder ``` Ein Structure Builder darf: ```text - Roadmaps anlegen - RoadmapLanes anlegen - RoadmapItems anlegen - initiale BacklogItems vorschlagen oder erzeugen - methodenspezifische Startstruktur erzeugen ``` Ein Structure Builder darf nicht: ```text - ungeprüft produktive Actions erzeugen, wenn ein Gate vorgesehen ist - Actors ohne Assignment Strategy zuweisen - Tenant-Kontext aus Client Input übernehmen - Rechteprüfung umgehen ``` --- ## 9. Strategies Methoden nutzen austauschbare Strategies. Wichtige Strategy Interfaces: ```text NextActionStrategy AttentionRuleProvider AssignmentStrategy WaitingStrategy ReminderStrategy EscalationStrategy ResultIntakeStrategy EvidencePolicy ReviewStrategy ClosurePolicy ``` Diese Strategies sind zentrale Erweiterungspunkte. Sie verhindern, dass methodenspezifische Logik monolithisch in Services oder Data Layer wächst. --- ## 10. Signal Rules Signal Rules erzeugen AttentionItems und NextActionCandidates. Sie müssen erklären können: ```text - warum ein Signal erzeugt wurde - welcher Hook relevant ist - welche Methode/Domain beteiligt ist - welcher Scope betroffen ist - welche Datenquelle genutzt wurde - welche nächste Handlung empfohlen wird ``` Signal Rules müssen tenant-sicher sein und dürfen nicht quer über Tenants lesen. --- ## 11. Method Definition Contract Eine MethodDefinition sollte mindestens enthalten: ```text method_key version label description supported_domains supported_scope_types default_lifecycle required_structures allowed_structures hook_slugs structure_builders attention_rule_providers next_action_strategy assignment_strategy waiting_strategy reminder_strategy escalation_strategy result_intake_strategy review_strategy evidence_policy closure_policy allowed_workflow_fragments allowed_node_types default_configuration ``` --- ## 12. Method Versioning Methoden müssen versionierbar sein. Regeln: ```text - method_key bleibt stabil - version beschreibt fachliche/technische Methode - bestehende SteeringContexts referenzieren method_key + version - neue Versionen dürfen bestehende Kontexte nicht stillschweigend verändern - Migration oder Upgrade muss explizit sein ``` --- ## 13. Method Profiles Method Profiles sind spätere konkrete Konfigurationen. Sie dürfen Parameter anpassen, aber nicht den Kairo-Kern umgehen. Beispiele: ```text maturity_progression.basic maturity_progression.evidence_strict content_chapter_based.light_review product_milestone_driven.release_focused routine_control.escalation_strict ``` Ein Method Profile darf z. B. konfigurieren: ```text - welche Hooks aktiv sind - welche Review-Frequenz gilt - ob Evidence erforderlich ist - welche Reminder-Strategie gilt - welche Node Types erlaubt sind - ob Agent Steps erlaubt sind ``` Ein Method Profile darf nicht: ```text - beliebigen Code ausführen - Tenant-Sicherheit umgehen - Capabilities außer Kraft setzen - systemgeschützte Hooks überschreiben ``` --- ## 14. Methodenbeispiele ### 14.1 product_milestone_driven ```text Domain: - product_development - project Structures: - Roadmap - Feature Lane - Architecture Lane - Release Lane - Backlog - Actions - Blockers Primary Hooks: - on_goal_captured - on_roadmap_required - on_backlog_required - on_next_action_requested - on_review_due ``` ### 14.2 content_chapter_based ```text Domain: - content_development Structures: - Roadmap - Chapter Lane - Research Lane - Draft Lane - Review Lane - Backlog - Actions Primary Hooks: - on_content_structure_required - on_next_action_requested - on_review_due ``` ### 14.3 maturity_progression ```text Domain: - maturity_development - personal_development Structures: - Roadmap - Maturity Stage Lane - Capability Lane - Practice Lane - Evidence Lane - Reflection Lane Primary Hooks: - on_maturity_path_required - on_evidence_required - on_review_due - on_reassessment_required ``` ### 14.4 wbs_driven ```text Domain: - project - program Structures: - WBS Roadmap - Work Package Items - Dependencies - Backlog - Actions Primary Hooks: - on_wbs_required - on_dependency_analysis_required - on_next_action_requested ``` --- ## 15. Designprinzipien kurz ```text 1. Methoden sind registrierte Steuerungspakete, keine Labels. 2. Neue Methoden melden sich an einer Registry an. 3. Alle Methoden nutzen gemeinsame Kairo-Kernstrukturen. 4. Der Standard Lifecycle ist die gemeinsame Basis. 5. Erweiterung erfolgt über Hook Slugs, Structure Builder und Strategies. 6. Built-in Methods kommen vor freier Konfiguration. 7. Profiles konfigurieren, aber ersetzen nicht den Kern. 8. Signals müssen erklärbar und tenant-sicher sein. 9. Agenten und LLMs sind spätere Step Provider, nicht Methoden selbst. 10. Keine Methode darf Capabilities, TenantContext oder Actor-Modell umgehen. ``` --- ## 16. Konsequenz für die technische Zielarchitektur Die technische Zielarchitektur muss diese Methodendesign-Prinzipien als verbindlich übernehmen. Insbesondere muss sie definieren: ```text - Method Registry - Hook Registry - MethodDefinition Contract - Standard Lifecycle - Structure Builder Interfaces - Strategy Interfaces - Signal Rule Provider Interfaces - Method Versioning - Method Profiles als spätere Konfigurationsebene ```