Kairo-Jinkendo/docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md

Jinkendo Kairo

Dokument 04 – Sprint 0 Foundation v0.3

Status: ausführbares Sprint-0-Arbeitspaket
Stand: 2026-07-04
Zweck: Vibe-Coder-fähiger Sprint-0-Scope für das neue Kairo-Repository.

---

1. Sprintziel

Sprint 0 schafft das technische und fachliche Fundament für Kairo.

Nach Sprint 0 existiert noch kein vollständiger Program Director.

Aber die Anwendung besitzt die notwendige Plattformstruktur, damit spätere Fachfunktionen nicht falsch aufgebaut werden.

---

2. Sprint-Leitfrage

Ist Kairo von Anfang an mandantenfähig, actor-basiert, registry-basiert, promptfähig, auditierbar und nicht hardcoded?

---

3. Verbindliche Leitdokumente

1. Jinkendo_Kairo_Product_Spec_v0.2.md
2. Jinkendo_Foundation_Minimum_Viable_Foundation_v0.2.md
3. Kairo_Sprint0_Principle_Gate_v0.1.md
4. CLAUDE.md
5. .cursor/rules/kairo-architecture.mdc

---

4. Scope

Sprint 0 umfasst:

• Repository und Grundarchitektur
• lokale Entwicklungsumgebung
• Datenbank und Migrationen
• Tenant-Modell
• User-Grundmodell
• Actor-Modell
• TenantMembership
• TenantContext
• Rollen-/Capability-Grundmodell
• Rights / Capability Registry
• minimale Feature Registry
• minimale Prompt Registry
• Prompt Templates
• Prompt Versions
• Placeholder-Modell
• Configuration-Grundmodell
• AuditLog
• minimaler /api/me/entitlements Snapshot
• minimale Admin-Prüfbarkeit
• technische Tests

---

5. Nicht-Scope

Nicht Teil von Sprint 0:

• Vorhabenverwaltung
• Projekte
• Meilensteine
• Maßnahmen
• Backlog
• MCP-Server
• Program-Director-Logik
• komplexe AI-Workflows
• Prompt-Pipelines
• Billing
• SSO
• Usage-Zähler
• Mitai-/Shinkan-Integration
• Seichō-Lebensmanagerlogik
• produktionsreifes Designsystem
• mobile App

---

6. Empfohlener Technologie-Start

Diese Empfehlung ist pragmatisch und darf durch ein Architecture Decision Proposal angepasst werden.

Backend: FastAPI
Frontend: React oder Next.js
DB: PostgreSQL
Migration: nummerierte SQL-Dateien + schema_migrations
Deployment lokal: Docker Compose
Auth Sprint 0: einfache serverseitige Session oder vorbereitete Auth-Fassade

Wichtig: Die Technologieentscheidung darf die Architekturprinzipien nicht verletzen.

---

7. Kernobjekte Sprint 0

Tenant

• id
• name
• slug
• status
• created_at
• updated_at

User

• id
• email
• display_name
• status
• created_at
• updated_at

TenantMembership

• id
• tenant_id
• user_id
• roles
• status

Actor

• id
• tenant_id
• actor_type
• display_name
• linked_user_id optional
• status
• capabilities optional

Actor Types:

• Human
• Agent
• WorkingGroup
• ExternalSystem

Role

• id
• tenant_id optional
• key
• name
• description
• scope
• status

Capability

• id
• key
• module
• description
• status

Feature

• id
• key
• module
• description
• status

PromptTemplate

• id
• tenant_id optional
• feature_key optional
• key
• name
• purpose
• context_kind
• status
• active_version_id

PromptVersion

• id
• prompt_template_id
• version
• body
• created_by
• created_at
• changelog

Placeholder

• id
• key
• type
• description
• required
• source
• context_kind optional

ConfigurationEntry

• id
• tenant_id optional
• key
• value
• scope
• description

AuditLog

• id
• tenant_id optional
• actor_id optional
• action
• entity_type
• entity_id
• timestamp
• metadata

---

8. Minimaler TenantContext

Jeder geschützte Request soll perspektivisch auflösen:

user_id
tenant_id
actor_id
global_roles
tenant_roles
capabilities

Sprint 0 darf dies technisch minimal umsetzen, aber die Fassade muss vorhanden sein.

---

9. Minimaler Entitlements Snapshot

Endpoint:

GET /api/me/entitlements

Mindestantwort:

{
  "tenant": {
    "tenant_id": "...",
    "name": "..."
  },
  "actor": {
    "actor_id": "...",
    "actor_type": "Human"
  },
  "roles": [],
  "capabilities": {},
  "features": {},
  "enforcement": {
    "capabilities": "probe",
    "features": "probe"
  }
}

Keine Billing-/Usage-Logik in Sprint 0.

---

10. Arbeitspakete

AP0.1 – Projektgrundlage

• Repo-Struktur
• Backend-Grundgerüst
• Frontend-Grundgerüst optional
• Docker Compose
• PostgreSQL
• Migration Runner
• Health Endpoint
• Testbasis

AP0.2 – Tenant, User, Actor

• Tenant
• User
• Membership
• Actor
• WorkingGroup Actor
• Agent Actor
• Seed für lokalen Admin

AP0.3 – Auth, TenantContext, Capabilities

• einfache Auth-Fassade
• TenantContext-Fassade
• Role
• Capability
• Rights Registry
• zentrale Capability-Prüfung

AP0.4 – Prompt, Feature, Config Registry

• Feature Registry
• PromptTemplate
• PromptVersion
• Placeholder
• ConfigurationEntry
• einfaches Prompt Rendering mit Placeholder Validation

AP0.5 – Audit und minimale Admin-Prüfbarkeit

• AuditLog
• Audit bei Admin-/Registry-/Prompt-Änderungen
• minimale Admin-Routen oder Admin-Seite
• /api/me/entitlements

---

11. User Stories

S0-01 – Projektgrundlage

Als Entwickler möchte ich eine lauffähige Projektstruktur, damit Kairo iterativ erweitert werden kann.

Akzeptanzkriterien:

• Projekt kann lokal gestartet werden.
• Datenbank läuft lokal.
• Migrationen laufen reproduzierbar.
• Health Endpoint antwortet.
• Tests können ausgeführt werden.

S0-02 – Tenant anlegen

Als Platform Admin möchte ich Tenants verwalten, damit abgegrenzte Nutzungsräume entstehen.

Akzeptanzkriterien:

• Tenant kann angelegt werden.
• Tenant kann deaktiviert werden.
• Tenant besitzt eindeutigen Slug.
• Fachliche Entitäten können Tenant-Bezug herstellen.

S0-03 – User und Membership

Als Tenant Admin möchte ich User einem Tenant zuordnen.

Akzeptanzkriterien:

• User kann mehreren Tenants angehören.
• Membership besitzt Rollen.
• Deaktivierte Membership verliert Zugriff.

S0-04 – Actor-Modell

Als System möchte ich Menschen, Agenten und Arbeitsgruppen einheitlich als Actors behandeln.

Akzeptanzkriterien:

• Human Actor kann mit User verknüpft werden.
• Agent Actor kann ohne User existieren.
• WorkingGroup Actor kann angelegt werden.
• Actor ist tenantbezogen.

S0-05 – Capability Registry

Als Entwickler möchte ich Capabilities registrieren, damit Rechte nicht verstreut hardcodiert werden.

Akzeptanzkriterien:

• Capability kann registriert werden.
• Capability besitzt Key, Modul und Beschreibung.
• Registry kann in DB synchronisiert oder persistiert werden.
• Fehlende Capability führt zu kontrolliertem Fehler.

S0-06 – Prompt Registry

Als Superadmin möchte ich Prompt Templates administrieren können.

Akzeptanzkriterien:

• Prompt Template kann angelegt werden.
• Prompt Version kann angelegt werden.
• Aktive Version ist bestimmbar.
• Template kann gerendert werden.
• Pflichtplatzhalter werden validiert.

S0-07 – Audit

Als Betreiber möchte ich kritische Aktionen nachvollziehen können.

Akzeptanzkriterien:

• Änderungen an Tenant, Role, Capability, Feature, Prompt und Config erzeugen Audit Events.
• Audit Event enthält Actor, Tenant, Aktion, Entity und Zeitpunkt.

S0-08 – Entitlements Snapshot

Als Frontend möchte ich einen Berechtigungssnapshot laden.

Akzeptanzkriterien:

• /api/me/entitlements liefert Tenant, Actor, Rollen, Capabilities und Features.
• Keine UI muss Rollenlogik selbst ableiten.

---

12. Definition of Done Sprint 0

Sprint 0 gilt als abgeschlossen, wenn:

• Anwendung lokal lauffähig ist.
• Migrationen funktionieren.
• Tenant/User/Actor/Membership implementiert sind.
• TenantContext-Fassade existiert.
• Capability Registry existiert.
• Feature Registry minimal existiert.
• PromptTemplate/PromptVersion/Placeholder existieren.
• Prompt Rendering validiert Pflichtplatzhalter.
• AuditLog existiert.
• /api/me/entitlements existiert.
• Es gibt Tests für die Kernmodelle.
• README, CLAUDE.md und Cursor-Regel sind aktuell.
• Keine fachlichen Prompts, Rollen oder Rechte sind verstreut hardcodiert.

---

13. Verbotene Vereinfachungen

Ein Coding-Agent darf nicht:

• Tenant entfernen
• Actor durch reines User-Modell ersetzen
• Capabilities durch Ad-hoc-Rollenchecks ersetzen
• Prompts hardcoden
• Placeholder-Validation weglassen
• Feature Registry weglassen
• AuditLog weglassen
• Vorhaben/Projektlogik in Sprint 0 vorziehen
• Billing/Usage-Limits in Sprint 0 ausbauen
• Shinkan-Club-Logik oder Mitai-Tier-Logik kopieren

---

14. Übergang zu Sprint 1

Sprint 1 startet erst, wenn Sprint 0 das Fundament trägt.

Sprint 1 baut dann:

• Vorhaben
• Programme optional
• Projekte
• erste Übersicht
• Statusmodell
• Basis-Governance für Vorhaben