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.

```text
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:

```text
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:

```text
GET /api/me/entitlements
```

Mindestantwort:

```json
{
  "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