From 1ce20d8bdb8db54660de6ca00bc6d5ca0259ff24 Mon Sep 17 00:00:00 2001 From: Lars Date: Sat, 4 Jul 2026 19:08:55 +0200 Subject: [PATCH] Sprint-0-Spezifikationen ergaenzen, AP0.1-Setup-Luecken schliessen (Health, CI, ADR-Vorlage). Co-authored-by: Cursor --- .cursor/rules/kairo-architecture.mdc | 45 +- .gitea/workflows/deploy-dev.yml | 10 +- .gitea/workflows/deploy-prod.yml | 8 +- .gitea/workflows/test.yml | 54 +- .gitignore | 1 + README.md | 21 + docs/DEPLOYMENT.md | 4 +- ...ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md | 38 ++ ...undation_Minimum_Viable_Foundation_v0.2.md | 200 ++++++++ .../Kairo_Architecture_References_v0.1.md | 6 + .../Kairo_Sprint0_Principle_Gate_v0.1.md | 105 ++++ .../Jinkendo_Kairo_Product_Spec_v0.2.md | 448 +++++++++++++++++ ...nkendo_Kairo_04_Sprint0_Foundation_v0.3.md | 466 ++++++++++++++++++ ...nt0_AP0_1_Project_Setup_Assignment_v0.1.md | 167 +++++++ .../Sprint0_Vibe_Coder_Handover_v0.1.md | 112 +++++ infra/README.md | 7 + scripts/load/README.md | 2 +- scripts/load/k6-health-baseline.js | 4 +- 18 files changed, 1651 insertions(+), 47 deletions(-) create mode 100644 docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md create mode 100644 docs/architecture/Jinkendo_Foundation_Minimum_Viable_Foundation_v0.2.md create mode 100644 docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md create mode 100644 docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md create mode 100644 docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md create mode 100644 docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md create mode 100644 docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md create mode 100644 infra/README.md diff --git a/.cursor/rules/kairo-architecture.mdc b/.cursor/rules/kairo-architecture.mdc index 057eb77..cb0050d 100644 --- a/.cursor/rules/kairo-architecture.mdc +++ b/.cursor/rules/kairo-architecture.mdc @@ -1,18 +1,41 @@ +--- +description: Kairo Sprint-0 Architektur-Leitplanken und Dokumentenpriorität +globs: backend/**,frontend/**,docs/**,.gitea/** +alwaysApply: true +--- +# Kairo Architecture Rules + +Du arbeitest an **Jinkendo Kairo** (Sprint 0). Kairo ist mandantenfähig und Actor-first. + +## Dokumentenpriorität bei Konflikten + +1. `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md` +2. `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` +3. `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md` +4. `docs/reference/design-principles/alignment/*` +5. Mitai/Shinkan-Einzelprinzipien (nur Begründung, kein Scope) ## Reference design principles -Reference material lives in: +Referenzmaterial: -- docs/reference/design-principles/mitai/ -- docs/reference/design-principles/shinkan/ -- docs/reference/design-principles/alignment/ +- `docs/reference/design-principles/mitai/` +- `docs/reference/design-principles/shinkan/` +- `docs/reference/design-principles/alignment/` -These files explain why certain patterns exist. They are not implementation scope unless the Kairo Sprint-0 Principle Gate or an Architecture Decision explicitly pulls them into scope. +Nicht automatisch Implementierungs-Scope. Übernahme nur via Principle Gate oder Architecture Decision. -Conflict order: -1. Kairo_Sprint0_Principle_Gate_v0.1.md -2. Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md -3. Jinkendo_Kairo_Product_Spec_v0.2.md -4. Alignment documents -5. Mitai/Shinkan individual principle documents +## Harte Guardrails + +- Kein Single-User ohne Tenant +- User ≠ Actor; Agenten sind Actors +- Auth, Capability, Feature, Governance trennen +- Keine hardcodierten Rechte, Prompts oder Fachkonfiguration +- Nummerierte SQL-Migrationen; kein ad-hoc DDL in Routern +- Keine Mitai-/Shinkan-Domänenlogik kopieren +- Keine Vorhaben-/Projektlogik vor Sprint-0-Abschluss + +## Abweichungen + +Architecture Decision Proposal nach Vorlage in `docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md`. diff --git a/.gitea/workflows/deploy-dev.yml b/.gitea/workflows/deploy-dev.yml index a9af2a9..9554674 100644 --- a/.gitea/workflows/deploy-dev.yml +++ b/.gitea/workflows/deploy-dev.yml @@ -18,11 +18,15 @@ jobs: docker compose -f docker-compose.dev-env.yml build --no-cache docker compose -f docker-compose.dev-env.yml up -d sleep 5 - if ! curl -sf http://localhost:8097/api/version; then + if ! curl -sf http://localhost:8097/api/health; then echo "✗ DEV API nicht erreichbar — Backend-Logs (Migration/Startup):" docker compose -f docker-compose.dev-env.yml logs backend --tail 120 || true exit 1 fi - echo "✓ DEV API healthy" - curl -sf http://localhost:3097/api/version && echo "✓ DEV über Frontend-Nginx (wie Browser) healthy" + echo "✓ DEV API /api/health OK" + if docker compose -f docker-compose.dev-env.yml ps --status running 2>/dev/null | grep -q frontend; then + curl -sf http://localhost:3097/api/health && echo "✓ DEV über Frontend-Nginx healthy" + else + echo "(Frontend-Check übersprungen — optional in AP0.1)" + fi echo "=== Kairo DEV Deploy complete ===" diff --git a/.gitea/workflows/deploy-prod.yml b/.gitea/workflows/deploy-prod.yml index 51f6801..b5cef74 100644 --- a/.gitea/workflows/deploy-prod.yml +++ b/.gitea/workflows/deploy-prod.yml @@ -18,6 +18,10 @@ jobs: docker compose build --no-cache docker compose up -d sleep 5 - curl -sf http://localhost:8004/api/version && echo "✓ PROD API (direkt) healthy" - curl -sf http://localhost:3004/api/version && echo "✓ PROD API über Frontend-Nginx (wie Browser) healthy" + curl -sf http://localhost:8004/api/health && echo "✓ PROD API (direkt) /api/health OK" + if docker compose ps --status running 2>/dev/null | grep -q frontend; then + curl -sf http://localhost:3004/api/health && echo "✓ PROD über Frontend-Nginx healthy" + else + echo "(Frontend-Check übersprungen — optional in AP0.1)" + fi echo "=== Kairo PROD Deploy complete ===" diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index 67c864b..5be58b3 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -54,11 +54,9 @@ jobs: done docker compose -f "$COMPOSE_FILE" exec -T backend sh -lc " - pip install -r /app/requirements-dev.txt && + pip install -q pytest httpx 2>/dev/null || pip install -q -r /app/requirements-dev.txt && cd /app && - ACCESS_LAYER_STRICT=1 python scripts/check_access_layer_hints.py && - python scripts/security_release_checks.py && - ACCESS_LAYER_INTEGRATION=1 SKIP_DB_MIGRATE=1 python -m pytest tests -m 'not slow' -ra -vv --tb=short + python -m pytest tests -ra -vv --tb=short " lint-backend: @@ -103,12 +101,16 @@ jobs: fi cd "$APP_DIR/frontend" + if [ ! -f package.json ]; then + echo "Frontend noch nicht vorhanden — übersprungen (AP0.1 optional)" + exit 0 + fi npm install npm run build echo "✓ Frontend build OK" k6-health-baseline: - name: k6 /health Baseline + name: k6 /api/health Baseline if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }} runs-on: ubuntu-latest env: @@ -133,36 +135,36 @@ jobs: echo "→ k6 gegen Dev (${DEV_BASE})." fi - - name: Dev /health abwarten + - name: Dev /api/health abwarten if: ${{ steps.e2e.outputs.mode == 'dev' }} run: | BASE="${{ steps.e2e.outputs.base_url }}" - echo "Warte auf $BASE/health …" + echo "Warte auf $BASE/api/health …" for i in $(seq 1 90); do - if curl -sf "$BASE/health" >/dev/null 2>&1; then + if curl -sf "$BASE/api/health" >/dev/null 2>&1; then echo "Health OK (Versuch $i)" exit 0 fi sleep 2 done - echo "Timeout: Dev /health nicht erreichbar — Deploy / DNS / Firewall prüfen." - curl -v "$BASE/health" || true + echo "Timeout: Dev /api/health nicht erreichbar — Deploy / DNS / Firewall prüfen." + curl -v "$BASE/api/health" || true exit 1 - - name: Prod /health abwarten + - name: Prod /api/health abwarten if: ${{ steps.e2e.outputs.mode == 'prod' }} run: | BASE="${{ steps.e2e.outputs.base_url }}" - echo "Warte auf $BASE/health …" + echo "Warte auf $BASE/api/health …" for i in $(seq 1 60); do - if curl -sf "$BASE/health" >/dev/null 2>&1; then + if curl -sf "$BASE/api/health" >/dev/null 2>&1; then echo "Health OK (Versuch $i)" exit 0 fi sleep 5 done - echo "Timeout: Prod /health nicht erreichbar" - curl -v "$BASE/health" || true + echo "Timeout: Prod /api/health nicht erreichbar" + curl -v "$BASE/api/health" || true exit 1 - name: Install k6 @@ -181,7 +183,7 @@ jobs: sudo mv "/tmp/k6-${K6_VER}-linux-${K6_ARCH}/k6" /usr/local/bin/k6 k6 version - - name: k6 Health-Baseline (parallele /health) + - name: k6 Health-Baseline (parallele /api/health) env: BASE_URL: ${{ steps.e2e.outputs.base_url }} run: | @@ -220,36 +222,36 @@ jobs: echo "→ Deployte Dev-Umgebung (${DEV_BASE}). Secrets: E2E_DEV_TEST_EMAIL / E2E_DEV_TEST_PASSWORD." fi - - name: Dev /health abwarten + - name: Dev /api/health abwarten if: ${{ steps.e2e.outputs.mode == 'dev' }} run: | BASE="${{ steps.e2e.outputs.base_url }}" - echo "Warte auf $BASE/health …" + echo "Warte auf $BASE/api/health …" for i in $(seq 1 90); do - if curl -sf "$BASE/health" >/dev/null 2>&1; then + if curl -sf "$BASE/api/health" >/dev/null 2>&1; then echo "Health OK (Versuch $i)" exit 0 fi sleep 2 done - echo "Timeout: Dev /health nicht erreichbar — Deploy / DNS / Firewall prüfen." - curl -v "$BASE/health" || true + echo "Timeout: Dev /api/health nicht erreichbar — Deploy / DNS / Firewall prüfen." + curl -v "$BASE/api/health" || true exit 1 - - name: Prod /health abwarten + - name: Prod /api/health abwarten if: ${{ steps.e2e.outputs.mode == 'prod' }} run: | BASE="${{ steps.e2e.outputs.base_url }}" - echo "Warte auf $BASE/health …" + echo "Warte auf $BASE/api/health …" for i in $(seq 1 60); do - if curl -sf "$BASE/health" >/dev/null 2>&1; then + if curl -sf "$BASE/api/health" >/dev/null 2>&1; then echo "Health OK (Versuch $i)" exit 0 fi sleep 5 done - echo "Timeout: Prod /health nicht erreichbar" - curl -v "$BASE/health" || true + echo "Timeout: Prod /api/health nicht erreichbar" + curl -v "$BASE/api/health" || true exit 1 - name: Testnutzer registrieren (Dev, nur wenn möglich) diff --git a/.gitignore b/.gitignore index 06b8805..94060c3 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,7 @@ coverage/ # Temp tmp/ *.tmp +*_alt.md # Claude: nur ausgewählte Bereiche versionieren .claude/** diff --git a/README.md b/README.md index b12eb6c..c4b9323 100644 --- a/README.md +++ b/README.md @@ -63,3 +63,24 @@ docs/reference/design-principles/ Diese Dokumente sind Referenzen, kein direkter Sprint-Scope. Verbindlich ist nur, was über das Kairo Sprint-0 Principle Gate oder eine Architecture Decision übernommen wurde. + +## Deployment + +Auto-Deploy via Gitea Actions auf dem Raspberry Pi (Ports 3004/8004 Prod · 3097/8097 Dev). + +Details: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) + +## AP0.1 – Stand Projektgrundlage + +| Bereich | Status | +|---------|--------| +| Git + Gitea (`develop` / `main`) | erledigt | +| Docker Compose (Prod + Dev) | erledigt | +| Gitea Actions (Deploy + Test) | erledigt, an Kairo angepasst | +| Sprint-0-Spezifikationen | im Repo | +| Designprinzipien-Referenz | im Repo | +| Backend-Skeleton (FastAPI, Migrationen, Tests) | **offen** | +| Frontend minimal | optional, **offen** | +| README „Local Development“ | folgt mit Backend-Skeleton | + +Nächster Schritt: Rest von AP0.1 gemäß `docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md`. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 6ea4d67..f3238ff 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -105,8 +105,8 @@ Workflows unter `.gitea/workflows/`: Health-Checks nach Deploy: -- Dev: `curl http://localhost:8097/api/version` und `http://localhost:3097/api/version` -- Prod: `curl http://localhost:8004/api/version` und `http://localhost:3004/api/version` +- Dev: `curl http://localhost:8097/api/health` (Backend direkt); mit Frontend zusätzlich `http://localhost:3097/api/health` +- Prod: `curl http://localhost:8004/api/health` (Backend direkt); mit Frontend zusätzlich `http://localhost:3004/api/health` --- diff --git a/docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md b/docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md new file mode 100644 index 0000000..3c937a1 --- /dev/null +++ b/docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md @@ -0,0 +1,38 @@ +# Architecture Decision Proposal + +Status: Entwurf +Stand: YYYY-MM-DD +Autor: + +--- + +## Problem + +Was ist die konkrete Entscheidungssituation? + +## Betroffene Regel + +Welches verbindliche Dokument oder Prinzip (Gate, Foundation, Spec) ist betroffen? + +## Optionen + +| Option | Kurzbeschreibung | Pro | Contra | +|--------|------------------|-----|--------| +| A | | | | +| B | | | | + +## Empfehlung + +Welche Option und warum? + +## Risiko + +Was kann schiefgehen? + +## Rückbaubarkeit + +Wie lässt sich die Entscheidung rückgängig machen oder später verfeinern? + +## Auswirkung auf Sprint 0 + +Betrifft das den Sprint-0-Scope oder nur spätere Arbeitspakete? diff --git a/docs/architecture/Jinkendo_Foundation_Minimum_Viable_Foundation_v0.2.md b/docs/architecture/Jinkendo_Foundation_Minimum_Viable_Foundation_v0.2.md new file mode 100644 index 0000000..27a04c3 --- /dev/null +++ b/docs/architecture/Jinkendo_Foundation_Minimum_Viable_Foundation_v0.2.md @@ -0,0 +1,200 @@ +# Jinkendo Foundation +## Minimum Viable Foundation v0.2 + +Status: Arbeitsfassung +Stand: 2026-07-04 +Zweck: Minimale produktübergreifende Grundlage, soweit sie für Jinkendo Kairo Sprint 0 zwingend relevant ist. + +--- + +## 1. Zweck + +Diese Minimum Viable Foundation beschreibt nur die produktübergreifenden Prinzipien, die Kairo von Anfang an korrekt berücksichtigen muss. + +Sie ist keine vollständige Zielarchitektur der Jinkendo-Produktfamilie. + +Sie erzwingt keine Konvergenz von Mitai und Shinkan. + +Sie verhindert nur, dass Kairo grundlegende Plattformkonzepte falsch oder isoliert implementiert. + +--- + +## 2. Geltungsbereich + +Gilt für Kairo Sprint 0 und spätere neue Jinkendo-Produkte, soweit dieselben Prinzipien relevant sind. + +Nicht Gegenstand: + +- Umbau von Mitai +- Umbau von Shinkan +- zentrale Familienarchitektur +- Billing +- SSO +- vollständige Shared Packages + +--- + +## 3. Drift-Schutz + +Ein Prinzip wird nur Sprint-0-verbindlich, wenn alle drei Fragen mit „Ja“ beantwortet werden: + +1. Verhindert es später teures strukturelles Refactoring in Kairo? +2. Ist es für Sprint 0 zwingend erforderlich? +3. Kann es minimal umgesetzt werden, ohne Kairo zu überladen? + +Alles andere kommt ins Architektur-Backlog. + +--- + +## 4. Verbindliche Foundation-Prinzipien für Kairo Sprint 0 + +### F-01 Tenant-first + +Kairo ist mandantenfähig zu modellieren. + +Alle fachlichen Objekte benötigen Tenant-Bezug oder einen expliziten globalen Scope. + +### F-02 Actor-first + +Operative Verantwortung wird Actors zugeordnet. + +Actors können Menschen, KI-Agenten, Arbeitsgruppen oder externe Systeme sein. + +### F-03 TenantContext pro Request + +Jeder geschützte Request muss einen aufgelösten Kontext besitzen: + +- User +- Tenant +- Actor +- Rollen +- Capabilities + +### F-04 Auth, Capability, Feature und Governance trennen + +Kairo vermischt nicht: + +- Auth: Wer ist eingeloggt? +- Capability: Darf diese Funktion genutzt werden? +- Feature: Welche Produktfunktion ist betroffen? +- Governance: Darf dieses Objekt gesehen oder verändert werden? + +Feature-Limits und Billing werden nur vorbereitet, nicht in Sprint 0 vollständig gebaut. + +### F-05 Registry-first + +Neue steuerungsrelevante Funktionen registrieren sich an zentralen Registries. + +Mindestens: + +- Rights / Capability Registry +- Feature Registry +- Prompt Registry +- Configuration Registry + +### F-06 Prompts nicht hardcoden + +Produktive interne Prompts liegen nicht hart im Code. + +Sprint 0 benötigt: + +- Prompt Template +- Prompt Version +- Placeholder +- Kontextart +- Admin-Scope + +### F-07 Platzhalter kontrollieren + +Platzhalter sind typisiert, dokumentiert und werden validiert. + +Fehlende Pflichtplatzhalter führen zu kontrollierten Fehlern. + +### F-08 Keine hardcodierte fachliche Konfiguration + +Nicht hardcodieren: + +- Rollen +- Rechte +- Prompts +- fachliche Statuslisten +- Feature-Flags mit fachlicher Bedeutung +- Workflowparameter +- AI-Modellzuordnung + +Technische Defaults sind erlaubt, müssen aber dokumentiert und später überschreibbar sein. + +### F-09 Audit für Admin- und Agentenaktionen + +Administrative und agentenbezogene Aktionen müssen auditierbar sein. + +Sprint 0 benötigt ein einfaches AuditLog-Modell. + +### F-10 Nummerierte Migrationen und Fail-Fast-Startup + +Schemaänderungen laufen über nummerierte Migrationen. + +Fehlgeschlagene Migrationen dürfen den App-Start blockieren. + +--- + +## 5. Bewusst nicht Sprint-0-verbindlich + +Nicht in Sprint 0: + +- vollständige Entitlement-/Billing-Engine +- Usage-Zähler +- Tiers +- Pläne +- Coupons +- SSO +- vollständige Mitai Prompt Engine +- Shinkan Access Layer mit Vereinslogik +- Widget Dashboard +- Data Layer nach Mitai-Vorbild +- Import-Framework +- Media Assets +- Content Reports +- Maturity Models + +--- + +## 6. Referenzprinzipien + +### Aus Mitai relevant + +- Prompt Templates nicht hardcoden +- zentrale Prompt-Ausführung als Zielbild +- Registry-Muster +- Feature-Registry als Konzept +- Migration/Deploy-Standard +- Auth-Session-Basis + +### Aus Shinkan relevant + +- TenantContext +- Trennung von Portalrolle und fachlicher Rolle +- Rights Registry +- Capabilities vs. Features +- Entitlements-Snapshot als API-Idee +- schmale AI Prompt Runtime als Sprint-0-kompatibles Vorbild + +--- + +## 7. Kairo-spezifische Entscheidung + +Kairo übernimmt keine allgemeine Familienarchitektur. + +Kairo übernimmt nur: + +```text +Tenant + Actor + TenantContext +Capability Registry +Feature Registry minimal +Prompt Registry minimal +Placeholder validiert +Audit +Migration/Deploy +``` + +Alles andere ist späteres Architektur-Backlog. diff --git a/docs/architecture/Kairo_Architecture_References_v0.1.md b/docs/architecture/Kairo_Architecture_References_v0.1.md index 272637a..4cfd6a5 100644 --- a/docs/architecture/Kairo_Architecture_References_v0.1.md +++ b/docs/architecture/Kairo_Architecture_References_v0.1.md @@ -12,6 +12,12 @@ Stand: 2026-07-04 5. `docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md` 6. `CLAUDE.md` 7. `.cursor/rules/kairo-architecture.mdc` +8. `docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md` + +## Hilfsdokumente + +- `docs/architecture/ARCHITECTURE_DECISION_PROPOSAL_TEMPLATE.md` +- `infra/README.md` — Platzhalter für serverseitige Infra-Ergänzungen ## Referenzdokumente diff --git a/docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md b/docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md new file mode 100644 index 0000000..405d6df --- /dev/null +++ b/docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md @@ -0,0 +1,105 @@ +# Jinkendo Kairo +## Sprint-0 Principle Gate v0.1 + +Status: verbindlicher Scope-Filter für Sprint 0 +Stand: 2026-07-04 + +--- + +## 1. Zweck + +Dieses Dokument verhindert Drift. + +Es legt fest, welche Prinzipien aus Mitai/Shinkan/Family-Alignment für Kairo Sprint 0 verbindlich sind und welche ausdrücklich nicht umgesetzt werden. + +--- + +## 2. Entscheidungsregel + +Ein Prinzip ist nur dann Sprint-0-verbindlich, wenn alle drei Fragen mit Ja beantwortet werden: + +1. Verhindert es später teures strukturelles Refactoring? +2. Ist es für Sprint 0 zwingend erforderlich? +3. Kann es minimal umgesetzt werden, ohne Kairo zu überladen? + +--- + +## 3. Sprint-0-verbindliche Prinzipien + +| ID | Prinzip | Sprint-0-Konsequenz | +|---|---|---| +| G-01 | Tenant-first | Tenant ist Kernobjekt; keine Single-User-Architektur | +| G-02 | Actor-first | Assignments gehen an Actors, nicht direkt an User | +| G-03 | TenantContext pro Request | Auth-Kontext wird zentral aufgelöst | +| G-04 | Auth / Capability / Feature / Governance trennen | Keine Vermischung von Login, Rollen, Limits und Objektzugriff | +| G-05 | Rights Registry | Rechte/Capabilities werden registriert, nicht verstreut hardcodiert | +| G-06 | Feature Registry minimal | Features sind bekannt und benannt, auch wenn Limits später kommen | +| G-07 | Prompt Registry minimal | Prompts sind administrierbare Templates, nicht Code-Strings | +| G-08 | Platzhalter validieren | Pflichtplatzhalter dürfen nicht stillschweigend fehlen | +| G-09 | Config statt Hardcoding | Fachliche Konfiguration nicht im Code verdrahten | +| G-10 | Audit | Admin- und Agentenaktionen werden protokolliert | +| G-11 | Migration Standard | Nummerierte SQL-Migrationen + Tracking | +| G-12 | Fail-Fast Startup | App startet nicht mit fehlerhaftem Schema | + +--- + +## 4. Nur vorbereiten, nicht vollständig bauen + +| Thema | Sprint-0-Umfang | +|---|---| +| Entitlements | Minimaler `/me/entitlements` Snapshot: tenant, actor, roles, capabilities | +| Feature Limits | Datenmodell optional vorbereiten; keine Usage-Zähler | +| Prompt Engine | Templates, Versionen, Platzhalter; keine Workflows/Pipelines | +| Admin UI | Minimal prüfbar; keine ausgereifte Oberfläche | +| MCP | Schnittstellen später; keine MCP-Implementierung in Sprint 0 | +| AI Agenten | Actor Type Agent vorbereiten; keine vollständige Agentensteuerung | + +--- + +## 5. Explizit nicht Sprint 0 + +- Billing +- Tiers +- Pläne +- Coupons +- Usage-Zähler +- SSO +- Mitai Data Layer +- Mitai Widget Dashboard +- Universal Import +- Shinkan Exercise Catalog +- Shinkan Training Planning +- Shinkan Media Assets +- Shinkan Content Reports +- Shinkan Maturity Models +- vollständige Familien-Konvergenz +- Lebensmanager-/Seichō-Fachlogik + +--- + +## 6. Review-Regel + +Jeder neue Vorschlag im Sprint wird mit einer Kategorie versehen: + +```text +A – Sprint-0-verbindlich +B – Architektur-Backlog +C – Produktspezifisch / ignorieren +``` + +Nur Kategorie A darf in Sprint 0 umgesetzt werden. + +--- + +## 7. Abweichungsregel + +Ein Coding-Agent darf nicht eigenmächtig von diesem Gate abweichen. + +Bei notwendiger Abweichung erstellt er ein Architecture Decision Proposal mit: + +- Problem +- betroffene Regel +- vorgeschlagene Änderung +- Risiko +- Alternative +- Empfehlung diff --git a/docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md b/docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md new file mode 100644 index 0000000..308ff44 --- /dev/null +++ b/docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md @@ -0,0 +1,448 @@ +# Jinkendo Kairo +## Product Spec v0.2 + +Status: Arbeitsfassung +Stand: 2026-07-04 +Zweck: Konsolidierte Produktspezifikation für den Start des neuen Kairo-Repositories. + +--- + +## 1. Produktidentität + +**Jinkendo Kairo** ist der operative Program Director der Jinkendo-Produktfamilie. + +Kairo steuert Vorhaben, Programme, Projekte, Meilensteine, Maßnahmen, Backlogs, Reviews, Nachweise und die Zusammenarbeit von Menschen, Arbeitsgruppen und KI-Agenten. + +**Leitfrage:** + +> Welcher nächste Schritt bringt ein Vorhaben aktuell am wirkungsvollsten voran? + +--- + +## 2. Produktgrenze + +Kairo ist kein klassischer Projektmanager, keine reine ToDo-App und kein reines Softwareentwicklungstool. + +Kairo ist auch kein Lebenssinn-, Identitäts- oder Gesundheitsprodukt. + +### Kairo verantwortet + +- Vorhaben +- Programme +- Projekte +- Meilensteine +- Maßnahmen +- Backlog Items +- Nachweise +- Reviews +- Entscheidungen +- Blocker +- Actor-Zuweisungen +- Arbeitsgruppen +- KI-Agenten +- operative Priorisierung +- Umsetzungstransparenz + +### Kairo verantwortet nicht + +- persönliche Identität +- Lebensvisionen +- persönliche Entwicklungsmodelle +- Gesundheitsdaten +- Trainingsfachlogik +- Wissensmanagement +- Ernährungslogik +- Skill- oder Reifegradmodelle aus Shinkan + +Diese Domänen gehören zu anderen Jinkendo-Produkten wie mindnet, Mitai, Shinkan und perspektivisch Seichō. + +--- + +## 3. Abgrenzung zu Seichō + +**Seichō** verantwortet persönliche Entwicklung. + +**Kairo** verantwortet operative Umsetzung. + +Beispiel: + +- Seichō: „Ich möchte als Vater präsenter werden.“ +- Kairo: „Welche konkreten Vorhaben, Meilensteine und Maßnahmen setzen das um?“ + +Kairo darf persönliche Entwicklungsziele aus Seichō operativ unterstützen, aber nicht die persönliche Entwicklungslogik selbst übernehmen. + +--- + +## 4. Stable Core und Agile Edge + +### Stable Core + +Der Stable Core wird nur bewusst und selten geändert. + +Er umfasst: + +- Fachsprache +- Kernobjekte +- Produktgrenzen +- Actor-Modell +- Tenant-Modell +- Backlog-Modell +- Meilensteinmodell +- Rechte-/Capability-Grundmodell +- Prompt-/Registry-Grundmodell +- Änderungsregeln +- Agentenregeln + +### Agile Edge + +Der Agile Edge darf iterativ wachsen. + +Er umfasst: + +- UI +- Dashboards +- Reports +- MCP-Tools +- Integrationen +- Automationen +- Priorisierungsstrategien +- Visualisierungen +- Komfortfunktionen + +--- + +## 5. Ubiquitous Language + +| Begriff | Bedeutung | +|---|---| +| Vision | Langfristig gewünschter Zustand; primär außerhalb Kairo | +| Vorhaben | Aktiv verfolgte Veränderung oder angestrebtes Ergebnis | +| Programm | Bündel zusammengehöriger Projekte | +| Projekt | Zeitlich begrenzte Ergebniserzeugung | +| Meilenstein | Überprüfbarer Zielzustand, keine Aufgabe | +| Maßnahme | Kleinste operative Arbeitseinheit mit eindeutigem Ergebnis | +| Backlog Item | Noch nicht verbindlich priorisierter Handlungsbedarf | +| Review | Strukturierte Bewertung eines Scopes | +| Nachweis | Beleg für Fortschritt, Abschluss oder Entscheidung | +| Entscheidung | Festgehaltene Auswahl zwischen Optionen | +| Blocker | Hindernis, das Fortschritt verhindert oder stark erschwert | +| Actor | Mensch, KI-Agent, Arbeitsgruppe oder externes System | +| Assignment | Zuweisung einer Maßnahme an einen oder mehrere Actors | +| Tenant | Abgegrenzter Nutzungsraum, z. B. Person, Familie, Team, Organisation | +| TenantContext | Aufgelöster Request-Kontext mit User, Tenant, Actor, Rollen und Capabilities | +| Capability | Funktionale Erlaubnis: „Darf Actor X diese Funktion nutzen?“ | +| Feature | Registrierte Produktfunktion, optional später mit Limit/Kontingent | +| Governance | Objektbezogene Zugriffslogik: „Darf Actor X dieses Objekt sehen/ändern?“ | + +Neue Begriffe werden nur eingeführt, wenn bestehende Begriffe fachlich nicht ausreichen. + +--- + +## 6. Grundstruktur + +```text +Tenant + └── Actor + └── Vorhaben + ├── Programm + │ └── Projekt + │ ├── Meilenstein + │ ├── Maßnahme + │ └── Backlog Item + ├── Meilenstein + ├── Maßnahme + ├── Backlog Item + ├── Nachweis + └── Review +``` + +Nicht jedes Vorhaben benötigt Programme oder Projekte. + +Kleine Vorhaben können direkt Meilensteine, Maßnahmen und Backlog Items besitzen. + +--- + +## 7. Kernobjekte + +### Tenant + +Ein Tenant ist ein abgegrenzter Nutzungsraum. + +Beispiele: + +- persönlicher Arbeitsraum +- Familie +- Verein +- Team +- Organisation +- Projektverbund + +### User + +Ein User ist ein authentifizierter Account. + +Ein User kann Mitglied mehrerer Tenants sein. + +### Actor + +Ein Actor ist die operative Zurechnungseinheit. + +Actor Types: + +- Human +- Agent +- WorkingGroup +- ExternalSystem + +Alle Assignments erfolgen an Actors, nicht direkt an User. + +### Vorhaben + +Ein Vorhaben beschreibt eine aktiv verfolgte Veränderung oder ein angestrebtes Ergebnis. + +Es besitzt mindestens: + +- Titel +- Zielzustand +- Status +- Priorität +- verantwortliche Actors +- Bezug zu Maßnahmen, Meilensteinen, Backlog und Reviews + +### Programm + +Ein Programm bündelt zusammengehörige Projekte oder Vorhabenanteile. + +Programme sind optional. + +### Projekt + +Ein Projekt erzeugt ein konkretes Ergebnis innerhalb eines Vorhabens oder Programms. + +### Meilenstein + +Ein Meilenstein beschreibt einen überprüfbaren Zielzustand. + +Er ist keine Aufgabe. + +Mögliche Status: + +- geplant +- aktiv +- gefährdet +- erreicht +- verschoben +- verworfen + +### Maßnahme + +Eine Maßnahme ist die kleinste operative Arbeitseinheit. + +Mögliche Status: + +- offen +- bereit +- in Arbeit +- blockiert +- Review erforderlich +- erledigt +- verworfen + +### Backlog Item + +Backlog Items entstehen aus Ideen, Bugs, Risiken, Verbesserungen oder Agentenvorschlägen. + +Sie verpflichten nicht automatisch zur Umsetzung. + +### Nachweis + +Nachweise belegen Fortschritt oder Abschluss. + +Beispiele: + +- Commit +- Dokument +- Link +- Datei +- Messwert +- Foto +- Review-Ergebnis +- externe Bestätigung + +### Review + +Ein Review bewertet einen Scope und erzeugt ggf. Entscheidungen, Maßnahmen oder Backlog Items. + +### Blocker + +Ein Blocker verhindert oder gefährdet Fortschritt. + +Blocker müssen sichtbar, zugeordnet und reviewbar sein. + +--- + +## 8. Actor- und Assignment-Modell + +Actors können Menschen, KI-Agenten, Arbeitsgruppen oder externe Systeme sein. + +Unterstützte Assignment-Modi: + +- Exclusive: genau ein verantwortlicher Actor +- Collaborative: mehrere Actors arbeiten gemeinsam +- Pool: eine Arbeitsgruppe oder ein Pool kann übernehmen +- Proposed: Zuweisungsvorschlag, noch nicht angenommen +- Auction: Actors bewerben sich oder übernehmen bewusst + +Agenten sind keine Sonderfälle außerhalb des Modells. + +--- + +## 9. Multiuser und Mandantenfähigkeit + +Multiuser ist Kernfunktion, keine spätere Erweiterung. + +Kairo unterstützt: + +- private Vorhaben +- Familienvorhaben +- Teamvorhaben +- Organisationsvorhaben +- Arbeitsgruppen +- KI-Agenten innerhalb eines Tenants +- objektbezogene Sichtbarkeit und Bearbeitbarkeit + +Jede fachliche Entität ist tenantfähig zu modellieren. + +--- + +## 10. Rechte, Capabilities und Governance + +Kairo trennt: + +```text +Auth = Wer ist eingeloggt? +Capability = Darf Actor diese Funktion nutzen? +Feature = Welche Produktfunktion ist betroffen? +Governance = Darf Actor dieses konkrete Objekt sehen/ändern? +``` + +Feature-Limits, Usage-Zähler, Billing, Tiers und Pläne sind nicht Bestandteil von Sprint 0, werden aber im Modell nicht verbaut. + +--- + +## 11. Prompt- und AI-Grundmodell + +Kairo nutzt intern keine hardcodierten Produktionsprompts. + +Mindestmodell: + +- Prompt Templates in DB oder konfigurierbarer Persistenz +- Prompt Versions +- typisierte Platzhalter +- Kontextarten +- Adminbarkeit +- Preview/Testmöglichkeit später +- zentrale Prompt-Ausführung als Fassade + +Sprint 0 baut keine komplexe Workflow- oder Pipeline-Engine. + +--- + +## 12. Registry-Grundmodell + +Neue Funktionen registrieren sich an zentralen Steuerungsschichten. + +Mindestens vorgesehen: + +- Rights / Capability Registry +- Feature Registry +- Prompt Registry +- Configuration Registry +- Audit Events + +Ziel: keine verstreuten, unsichtbaren Sonderlogiken. + +--- + +## 13. Agentenregeln + +Agenten dürfen: + +- Kontext anfragen +- nächste Maßnahme abfragen +- Maßnahmen claimen +- Fortschritt melden +- Blocker melden +- Backlog Items vorschlagen +- Nachweise einreichen +- Reviews anfordern + +Agenten dürfen nicht ohne Freigabe: + +- strategische Ziele ändern +- Vorhaben löschen +- Meilensteine verschieben +- Rechte oder Rollen ändern +- Prompts produktiv ändern +- Admin-Konfiguration ändern +- private Daten anderer Actors auswerten + +--- + +## 14. Änderungsregime + +Änderungen werden klassifiziert als: + +| Ebene | Bedeutung | +|---|---| +| Operativ | Maßnahmen, Status, Nachweise, Kommentare | +| Taktisch | Prioritäten, Meilensteinzuschnitt, Assignment-Modus | +| Strategisch | Produktgrenze, Stable Core, grundlegende Ziele oder Rechte | + +Strategische Änderungen benötigen menschliche Freigabe. + +--- + +## 15. MVP-Zielbild + +Der MVP umfasst nach Sprint 0 schrittweise: + +- Tenant/User/Actor +- Vorhaben +- Projekte +- Meilensteine +- Maßnahmen +- Backlog +- Assignments +- Arbeitsgruppen +- Agentenstatus +- Reviews +- Nachweise +- Blocker +- Vorschlag der nächsten sinnvollen Maßnahme +- MCP-Minimalintegration für Coding-Agenten + +--- + +## 16. Nicht-Ziele des MVP + +Nicht Teil des MVP: + +- vollständige Mitai-Integration +- vollständige Shinkan-Integration +- vollständige mindnet-Integration +- vollständige Seichō-Integration +- vollständiges Billing +- zentrales SSO +- komplexe Prompt-Workflows +- KI-Autopilot für strategische Entscheidungen +- vollständiger Lebensmanager +- Gesundheits- oder Trainingsdomänenlogik + +--- + +## 17. Leitregel + +Kairo steuert Umsetzung. + +Sinn, Identität und persönliche Entwicklung verbleiben außerhalb seiner fachlichen Verantwortung. diff --git a/docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md b/docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md new file mode 100644 index 0000000..19f93fb --- /dev/null +++ b/docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md @@ -0,0 +1,466 @@ +# 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 diff --git a/docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md b/docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md new file mode 100644 index 0000000..c5f6a95 --- /dev/null +++ b/docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md @@ -0,0 +1,167 @@ +# Jinkendo Kairo +## Sprint 0 – AP0.1 Projektgrundlage v0.1 + +Status: erster ausführbarer Coding-Auftrag +Stand: 2026-07-04 + +--- + +## 1. Auftrag + +Erstelle die technische Projektgrundlage für Jinkendo Kairo. + +AP0.1 baut noch keine fachliche Kairo-Domäne. + +Ziel ist ein lauffähiges, testbares, migrationsfähiges Grundgerüst. + +--- + +## 2. Verbindliche Leitplanken + +Vor Umsetzung lesen: + +- `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md` +- `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md` +- `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` +- `CLAUDE.md` +- `.cursor/rules/kairo-architecture.mdc` + +--- + +## 3. Scope AP0.1 + +Erstelle: + +```text +backend/ +frontend/ optional minimal +infra/ +scripts/ +tests/ +``` + +Mindestumfang: + +- Backend-Skeleton +- FastAPI-App oder begründete Alternative +- Health Endpoint +- PostgreSQL-Anbindung +- Docker Compose lokal +- Migrationsverzeichnis +- Migration Runner +- `schema_migrations` Tracking +- erste Migration `001_init_core.sql` +- Testbasis +- README-Abschnitt „Local Development“ + +--- + +## 4. Nicht-Scope AP0.1 + +Nicht implementieren: + +- Tenant/User/Actor-Fachlogik über minimale Schema-Vorbereitung hinaus +- vollständige Auth +- Prompt Engine +- Feature Registry +- Capability Registry +- Vorhaben +- Projekte +- Maßnahmen +- Backlog +- MCP +- Billing +- UI-Komplexität + +--- + +## 5. Migrationsanforderungen + +Migrationen liegen unter: + +```text +backend/migrations/ +``` + +Namensschema: + +```text +001_init_core.sql +002_*.sql +003_*.sql +``` + +Pflicht: + +- `schema_migrations` Tracking +- lexikographische Ausführung +- bereits ausgeführte Migrationen überspringen +- Fehler blockiert App-Start oder Setup-Command +- keine ad-hoc DDL in Routern + +--- + +## 6. Health Endpoint + +Mindestendpoint: + +```text +GET /api/health +``` + +Antwortbeispiel: + +```json +{ + "status": "ok", + "app": "jinkendo-kairo", + "db": "ok" +} +``` + +--- + +## 7. Tests + +Mindestens: + +- App importierbar +- Health Endpoint antwortet +- Migration Runner erkennt Migrationen +- Migration Runner trägt ausgeführte Migration ein +- wiederholter Migration Run ist idempotent + +--- + +## 8. Akzeptanzkriterien + +AP0.1 ist abgeschlossen, wenn: + +- Projekt lokal startbar ist. +- Datenbank lokal startbar ist. +- Migrationen laufen. +- Health Endpoint funktioniert. +- Tests laufen. +- README beschreibt Setup. +- Keine fachliche Sprint-1-Logik wurde vorgezogen. +- Offene technische Entscheidungen sind dokumentiert. + +--- + +## 9. Erwarteter Abschlussbericht + +Der Coding-Agent liefert am Ende: + +```markdown +## Umgesetzt + +## Tests + +## Lokaler Start + +## Offene Fragen + +## Abweichungen von der Spezifikation + +## Empfehlung für AP0.2 +``` diff --git a/docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md b/docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md new file mode 100644 index 0000000..3c68574 --- /dev/null +++ b/docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md @@ -0,0 +1,112 @@ +# Jinkendo Kairo +## Sprint 0 – Vibe-Coder Handover v0.1 + +Status: Übergabedokument +Stand: 2026-07-04 + +--- + +## 1. Auftrag + +Baue nicht sofort den Program Director. + +Baue zuerst das Fundament, damit der Program Director später sauber entstehen kann. + +Sprint 0 ist erfolgreich, wenn Kairo technisch und fachlich vorbereitet ist für: + +- Mandanten +- Actors +- Rechte/Capabilities +- Prompts +- Platzhalter +- Konfiguration +- Audit +- spätere KI-Agenten + +--- + +## 2. Verbindliche Dokumente + +Lies in dieser Reihenfolge: + +1. `README.md` +2. `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md` +3. `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md` +4. `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` +5. `CLAUDE.md` +6. `.cursor/rules/kairo-architecture.mdc` + +--- + +## 3. Arbeitsprinzip + +Du darfst technische Details ausarbeiten. + +Du darfst keine fachlichen Architekturprinzipien ändern. + +Wenn eine Änderung notwendig erscheint, erstelle ein Architecture Decision Proposal. + +--- + +## 4. Harte Guardrails + +Nicht erlaubt: + +- Kairo als Single-User-App bauen +- Tenant weglassen +- Actor durch User ersetzen +- Agenten als Sonderlogik außerhalb Actor-Modell behandeln +- Rollen/Rechte hardcoden +- Prompts hardcoden +- Feature Registry weglassen +- Prompt Registry weglassen +- Placeholder-Validation weglassen +- Audit weglassen +- Vorhaben/Projektlogik vor Sprint-0-Abschluss implementieren +- Billing/Usage-Limits vorziehen +- Mitai- oder Shinkan-Domänenlogik kopieren + +--- + +## 5. Erwartete Arbeitsweise + +Für jedes Arbeitspaket: + +1. Kurzplan erstellen +2. Implementieren +3. Tests ergänzen +4. README oder relevante Doku aktualisieren +5. Abweichungen dokumentieren +6. Offene Fragen klar markieren + +--- + +## 6. Architecture Decision Proposal Format + +```markdown +# Architecture Decision Proposal + +## Problem + +## Betroffene Regel + +## Optionen + +## Empfehlung + +## Risiko + +## Rückbaubarkeit + +## Auswirkung auf Sprint 0 +``` + +--- + +## 7. AP0.1 zuerst + +Der erste Auftrag ist ausschließlich AP0.1 – Projektgrundlage. + +Kein Sprint-0-Gesamtbau. + +Kein Vorziehen von AP0.2–AP0.5 ohne Review. diff --git a/infra/README.md b/infra/README.md new file mode 100644 index 0000000..1132462 --- /dev/null +++ b/infra/README.md @@ -0,0 +1,7 @@ +# Infra + +Deployment- und Server-bezogene Ergänzungen (Reverse-Proxy-Snippets, NAS-Mount-Hinweise, Umgebungs-spezifische Notizen). + +**Hauptdoku:** [docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md) + +Aktuell leer — bewusst minimal in AP0.1. Docker Compose liegt im Repository-Root. diff --git a/scripts/load/README.md b/scripts/load/README.md index 1394019..c869b98 100644 --- a/scripts/load/README.md +++ b/scripts/load/README.md @@ -1,6 +1,6 @@ # k6 Load-Tests (Phase 0) -Parallele `/health`-Requests gegen Dev oder Prod. +Parallele `/api/health`-Requests gegen Dev oder Prod. ## Lokal / CI diff --git a/scripts/load/k6-health-baseline.js b/scripts/load/k6-health-baseline.js index 9324153..62e9dd1 100644 --- a/scripts/load/k6-health-baseline.js +++ b/scripts/load/k6-health-baseline.js @@ -1,5 +1,5 @@ /** - * Phase-0-Baseline: parallele GET /health (kein Auth). + * Phase-0-Baseline: parallele GET /api/health (kein Auth). * BASE_URL optional, z. B. https://dev.kairo.jinkendo.de */ import http from 'k6/http' @@ -25,7 +25,7 @@ export const options = { const BASE = (__ENV.BASE_URL || 'https://dev.kairo.jinkendo.de').replace(/\/$/, '') export function health() { - const res = http.get(`${BASE}/health`, { tags: { scenario: 'health' } }) + const res = http.get(`${BASE}/api/health`, { tags: { scenario: 'health' } }) check(res, { 'health 2xx': (r) => r.status >= 200 && r.status < 300, })