# Claude Kontext — Clowdex

Dieses Projekt nutzt Clowdex, ein umfassendes Workflow-System für Claude Code.
Lies immer zuerst `.claude/memory.md` bevor du handelst.

## Schnellstart
- `/start` — Arbeit beginnen
- `/sync` — Zwischendurch Kontext auffrischen
- `/end-day` — Arbeitstag beenden
- `/audit` — Qualität der letzten Arbeit prüfen
- `/flush` — Kontext sicher leeren und frisch fortfahren
- `/unstick` — Wenn du feststeckst
- `/retro` — Sprint-Retrospektive
- `/system-audit` — Tiefenprüfung der Infrastruktur

## Wichtige Dateien
- Memory: `.claude/memory.md` (aktueller Kontext — zuerst lesen)
- Wissensdatenbank: `.claude/knowledge-base.md` (systemweite Regeln — vor jeder Aufgabe lesen)
- Aufgabenboard: `Task Board.md`
- Notizblock: `Scratchpad.md` (schnelle Notizen, verarbeitet bei /sync, geleert bei /end-day)
- Tagesnotizen: `Daily Notes/` (automatisch erstellt durch /start)
- Wissensvorschläge: `.claude/knowledge-nominations.md` (Lernkandidaten — Sentinel prüft)
- Befehlsindex: `.claude/command-index.md` (alle Befehle mit Auslösern und Tools)

## Systemarchitektur
- **Agenten** (`.claude/agents/`): Spezialisierte Sub-Agenten mit persistentem Memory
  - `sentinel` — Qualitätskontrolle. Prüft Arbeit, befördert Wissen, schlägt SOP-Änderungen vor
  - `pathfinder` — Hilft bei Blockaden. Ursachenanalyse und frische Lösungsansätze
  - `decoder` — Übersetzt kryptische Fehlermeldungen in konkrete Fixes. Mustererkennung über Sessions hinweg
  - `mirror` — Bringt dich dazu, das eigentliche Problem zu formulieren. Sokratisches Debugging
  - `scribe` — Schreibt PR-Beschreibungen, Commit-Messages und Changelogs aus Diffs
  - `compass` — Erkennt Scope-Creep. „Du wolltest X machen, aber jetzt machst du Y"
  - `ledger` — Verfolgt technische Schulden. Katalogisiert Abkürzungen, empfiehlt Rückzahlung
  - `scout` — Lernt neue Codebases schnell. Architektur-Maps, Identifikation wichtiger Dateien
  - `historian` — Gräbt aus, warum Code existiert. Git Blame + Kontextrekonstruktion
- **Befehle** (`.claude/commands/`): Workflow-Rituale und Werkzeuge
- **Hooks** (`.claude/hooks/`): Deterministische Sicherheitsmaßnahmen (Logging, Validierung)
- **Logs** (`.claude/logs/`): Prüfprotokoll + Vorfallslog — automatisch durch Hooks befüllt
- **Skills** (`.claude/skills/`): Fachwissen, bei Bedarf geladen

## Memory-Architektur (6 Stufen)
1. **memory.md** — Aktiver Session-Kontext (was du gerade machst)
2. **Agent Memory** (`.claude/agent-memory/`) — Persistentes Wissen pro Agent über Sessions hinweg
3. **Wissensdatenbank** (`.claude/knowledge-base.md`) — Systemweite Regeln (durch Sentinel geprüft)
4. **Wissensvorschläge** (`.claude/knowledge-nominations.md`) — Pipeline für Lernkandidaten
5. **MCP Knowledge Graph** — Strukturierte Entitäten und Relationen (falls Memory-MCP aktiviert)
6. **Tagesnotizen** — Chronologische Session-Historie und Übergabeprotokolle

## Befehlsnutzung

Alle Agenten können Systembefehle aufrufen. Lies `.claude/command-index.md` für den vollständigen Katalog.

- **Selbst ausführen**: Wenn du die nötigen Tools hast, lies `.claude/commands/{name}.md` und folge der Anleitung direkt.
- **Empfehlen**: Wenn dir Tools fehlen, gib `RECOMMEND: /command [args] — [reason]` an den Orchestrator aus.
- Agenten sollten Befehle proaktiv aufrufen, wenn die Auslösebedingungen zutreffen.

## Schnellzugriff — Wo du was findest

| Du brauchst... | Prüfe zuerst | Dann |
|---|---|---|
| Was mache ich gerade? | `memory.md` → Now | Task Board → Today |
| Wie geht ein Verfahren? | `.claude/commands/` oder `.claude/skills/` | CLAUDE.md |
| Eine Regel oder Erkenntnis | `knowledge-base.md` | Agent Memory |
| Was an einem bestimmten Tag passiert ist | `Daily Notes/MMDDYY.md` | Prüfprotokoll |
| Was früher schiefgelaufen ist | `knowledge-base.md` → Hard Rules | Agent Memory → Known Patterns |
| Welche Befehle es gibt | `.claude/command-index.md` | `.claude/commands/{name}.md` |

## Session-Zustand

Sessions haben begrenzten Kontext. Aufwendige Operationen verbrauchen ihn schnell.

**Automatisches Sicherheitsnetz (Hooks):**
- `PreCompact`-Hook sichert den Zustand vor der Auto-Komprimierung
- `SessionStart(compact)`-Hook stellt den Kontext nach der Komprimierung wieder her
- `SessionStart(user)`-Hook setzt veraltete Gate-Dateien bei jeder neuen Session zurück

**Validierungschecks (PreToolUse Write|Edit — harte Blockaden):**
- **knowledge-base.md**: Jeder Eintrag braucht `[Source:]`-Herkunft, max 200 Zeilen, kein TBD/TODO
- **memory.md**: Max 100 Zeilen (nur Write)
- **settings.json**: Muss valides JSON sein (defektes JSON bricht alle Hooks)
- **Agent-Definitionen** (`.claude/agents/*.md`): Kein TBD/TODO — Anweisungen müssen definitiv sein
- **Ohne Gate** (iterativ): Daily Notes, Scratchpad, Templates, Logs, Commands, Skills

**Selbstüberwachung (weiche Signale — Claudes Verantwortung):**
- Nach ~30+ Tool-Aufrufen oder 3+ großen Datei-Lesevorgängen: `/flush` proaktiv ausführen
- Bei „compacting conversation"-Warnung: `/flush` sofort ausführen
- Bei Qualitätsverlust (Wiederholungen, übersehene Details): `/flush` ausführen
- Nach Abschluss einer mehrstufigen Aufgabe: `/flush` vor der nächsten unzusammenhängenden Aufgabe erwägen
- Beim Wechsel zwischen Aufgabenbereichen: Grenze anerkennen, `/flush` bei großen Wechseln bevorzugen

**So funktioniert /flush:** Destilliert den Session-Zustand in memory.md + Tagesnotiz-Übergabe und bewahrt Suchpfade. Setzt dann automatisch fort, indem der komprimierte Kontext neu geladen und die nächste Aktion ausgeführt wird. Nahtlos für den Nutzer.

## Wartung
- memory.md kompakt halten (<100 Zeilen)
- Veraltete Einträge konsequent entfernen
- Done-Liste freitags leeren
- Vorfallslog bei /sync und /end-day prüfen
- Sentinel schlägt SOP-Änderungen vor — Nutzer genehmigt vor Übernahme

---

## PROJEKTABLAUF-PROTOKOLL (Verbindlich)

Du folgst bei JEDEM Projekt diesem 7-Phasen-Protokoll.
Du darfst KEINE Phase überspringen.
Du prüfst vor jedem Phasenwechsel die Exit-Kriterien der aktuellen Phase.
Wenn Exit-Kriterien nicht erfüllt sind, bleibst du in der Phase und kommunizierst was fehlt.

### Aktueller Projektstatus (wird von dir gepflegt)
```
PHASE:         [ ] 1-Scope  [ ] 2-Architektur  [ ] 3-Entwicklung
               [ ] 4-QA     [ ] 5-Security     [ ] 6-Deployment  [ ] 7-Doku
AKTUELLE PHASE: ___
LETZTER SCHRITT: ___
OFFEN: ___
```

---

### PHASE 1 — Scope & Setup
**Trigger:** Neues Projekt wird gestartet oder `/project-start` wird aufgerufen.

**Du führst aus (in dieser Reihenfolge):**
1. Frage den Nutzer: Projektname, Projekttyp (SaaS-App / n8n-Workflow / Python-Script / Static-Website), DSGVO-relevant (ja/nein)
2. Kopiere das Base Project: `cp -r ~/C-Stone\ Cloud/Claude\ Code/projekte/Base\ Project ~/C-Stone\ Cloud/Claude\ Code/projekte/[PROJEKTNAME]`
3. Führe `rag_query` aus mit: "Gibt es ähnliche Projekte oder Vorlagen für [PROJEKTNAME]?"
4. Lege GitHub-Repo an: `gh repo create c-stone-[projektname] --private --source=. --push`
5. Befülle `Task Board.md` mit mindestens 5 konkreten Tickets aus dem Scope
6. Aktualisiere `memory.md`: Projektname, Typ, DSGVO-Status, Startdatum
7. Trage in Projektstatus oben ein: PHASE = 1-Scope ✅, wechsle zu Phase 2

**Exit-Kriterien (alle müssen erfüllt sein):**
- [ ] Projektordner unter `projekte/[NAME]/` vorhanden
- [ ] GitHub-Repo angelegt, initialer Push erfolgt
- [ ] DSGVO-Anforderung in memory.md dokumentiert
- [ ] Task Board hat ≥ 5 Tickets
- [ ] RAG-Query ausgeführt, Ergebnis in Scratchpad.md notiert

---

### PHASE 2 — Architektur
**Trigger:** Phase 1 Exit-Kriterien erfüllt.

**Stack-Entscheidung (automatisch nach Projekttyp):**
- SaaS-App → FastAPI + PostgreSQL + Redis + React/Vite + Docker Compose + Traefik
- n8n-Workflow → n8n Webhook + Flask Microservice + SeaTable
- Python-Script → Python 3 + boto3 (Bedrock Frankfurt) + openpyxl wenn Excel
- Static-Website → HTML5 + CSS3 + Vanilla JS, kein Backend

**Du führst aus:**
1. Erstelle Ordnerstruktur passend zum Stack
2. Erstelle `docker-compose.yml` mit Traefik-Labels für `[projekt].c-stone-dev.com`
3. Erstelle `.env.example` (alle Keys als Platzhalter, NIE echte Werte)
4. Erstelle `.gitignore` (muss enthalten: `.env`, `.env.*`, `*.pem`, `node_modules/`, `__pycache__/`, `.DS_Store`)
5. Erstelle `.nextcloudignore` (muss enthalten: `node_modules/`, `__pycache__/`, `.env`, `*.db`, `venv/`)
6. Entwirf Datenbankschema in `docs/schema.md` (bei SaaS-Apps)
7. Notiere Architekturentscheidungen in `knowledge-base.md` des Projekts
8. Initialer Commit: `git add -A && git commit -m "chore: Projektstruktur und Architektur"`

**Exit-Kriterien:**
- [ ] Ordnerstruktur angelegt
- [ ] docker-compose.yml vorhanden mit Traefik-Labels
- [ ] .gitignore und .nextcloudignore vorhanden und vollständig
- [ ] .env.example vorhanden (keine echten Werte)
- [ ] Architektur in knowledge-base.md dokumentiert
- [ ] Commit "chore: Projektstruktur" auf GitHub

---

### PHASE 3 — Entwicklung (Iterativ)

**Tool-Wahl (du empfiehlst dem Nutzer aktiv das richtige Tool):**

| Aufgabe | Tool | Modell |
|---|---|---|
| Tab-Autocomplete, einzelne Zeilen | Continue.dev | qwen2.5-coder:14b |
| Einzelne Funktion, Snippet (≤ 2 Dateien) | Continue.dev | devstral:24b / qwen3:30b |
| Ordnerstruktur, Boilerplate (≥ 3 Dateien) | Cline | devstral:24b (lokal) |
| Feature über mehrere Dateien | Cline | Qwen3 235B (Bedrock) |
| Tests schreiben + ausführen + fixen | Cline | Devstral 123B (Bedrock) |
| Refactoring über gesamte Codebase | Cline | Qwen3 235B (Bedrock) |
| SSH Hetzner, Docker, Playwright, RAG-Query | Claude Code | Claude Sonnet 4.6 |

**Du führst aus (pro Feature-Zyklus):**
1. Feature-Branch anlegen: `git checkout -b feature/[beschreibung]`
2. Empfehle dem Nutzer das passende Tool für diese Aufgabe
3. Nach Implementierung: Lokal testen
4. Atomic Commit mit Conventional-Commit-Message (`feat:` / `fix:` / `refactor:` / `test:` / `security:` / `docs:` / `chore:`)
5. Nach 3–4h: `/sync` aufrufen
6. Bei Blockade: `/unstick` aufrufen

**Sicherheitsregel:** NIEMALS echte Credentials in Dateien · NIEMALS .env committen · IMMER .gitignore prüfen

**Exit-Kriterien:**
- [ ] Alle Features aus Task Board implementiert
- [ ] Code läuft lokal in Docker ohne Fehler
- [ ] Keine ERROR-Logs in `docker logs`
- [ ] Alle Commits auf GitHub gepusht

---

### PHASE 4 — QA & Testing

1. `pytest tests/ -v` — 0 Fehler
2. `docker compose build --no-cache && docker compose up -d`
3. Playwright E2E: Happy Path, Screenshots 1440px + 375px
4. Swagger unter `http://localhost:8000/docs` erreichbar?
5. DSGVO: Logs anonym? AWS Region = `eu-central-1`?
6. `/audit`

**Exit-Kriterien:** pytest grün · Docker "Up" · Playwright grün · /audit OK · DSGVO geprüft

---

### PHASE 5 — Security Gate (PFLICHT, nicht überspringbar)

1. Secrets-Scan: `git grep -rn "AWS_ACCESS\|AWS_SECRET\|PASSWORD\|SECRET_KEY\|TOKEN\|api_key" --include="*.py" --include="*.js" --include="*.ts" -- ':!.env.example'`
2. Staged-Files: `git diff --cached --name-only | grep -i "\.env\|credentials\|secret\|key"`
3. .env in .nextcloudignore?
4. Auth: alle Endpunkte außer `/health` + `/docs` hinter `Depends(get_current_user)`?
5. slowapi auf kritischen Endpunkten?
6. `pip-audit` + `npm audit`
7. `grep -r "eu-central-1\|eu-north-1" backend/ --include="*.py"`

**Bei EINEM Fehler: KEIN Deployment.**

**Exit-Kriterien:** Secrets 0 · .env ausgeschlossen · Auth OK · keine kritischen CVEs · DSGVO-Region bestätigt

---

### PHASE 6 — Deployment auf Hetzner

1. Finaler Push + Tag
2. `ssh root@n8n.c-stone-dev.com`
3. Repo klonen/pullen, .env manuell anlegen
4. `docker compose build --no-cache && docker compose up -d`
5. `docker exec [PROJEKTNAME]-backend-1 alembic upgrade head`
6. 5 Minuten Logs beobachten
7. Playwright E2E gegen `https://[projekt].c-stone-dev.com`

**Exit-Kriterien:** alle services "Up" · HTTPS erreichbar · E2E grün · 5min Logs OK · Git-Tag gesetzt

---

### PHASE 7 — Dokumentation & Wissenstransfer

1. README.md aktualisieren
2. `cp README.md ~/cstone-rag/inbox/[PROJEKTNAME]-readme.md`
3. knowledge-base.md ≥ 3 Einträge
4. `/retro` + `/end-day`
5. Neues Projekt in C-Stone-Setup-Public.html eintragen

**Exit-Kriterien:** README vollständig · RAG befüllt · knowledge-base ≥ 3 · /retro ausgeführt

---

## VERHALTEN BEI PHASENÜBERGÄNGEN

Abschluss: `✅ PHASE [N] ABGESCHLOSSEN — Wechsle zu PHASE [N+1]: [Name] — Erste Aktion: [...]`

Nicht abgeschlossen: `⏸ PHASE [N] NOCH NICHT ABGESCHLOSSEN — Fehlend: [...] — Ich behebe jetzt: [...]`

Überspringen-Anfrage: `⚠️ Fehlende Checks: [...] — Bist du sicher? Antworte mit "ja, überspringen"`

---

## DSGVO-REGEL: GITHUB & EXTERNE DIENSTE (Nicht verhandelbar)

GitHub (MCP + CLI + gh) NUR für technische Inhalte — NIEMALS für:
- Kundennamen, E-Mail-Adressen, Telefonnummern realer Personen
- Inhalte aus Kundengesprächen oder Beratungssessions
- Daten aus SeaTable (CRM, Leads, Kontakte)

**Begründung:** GitHub läuft auf US-Servern (Microsoft) — DSGVO Art. 44 ff.

**Prüfpflicht:** Vor jedem GitHub-Befehl auf Personenbezug prüfen. Bei Unsicherheit:
`⛔ DSGVO-CHECK: "[Text]" — Formulierung anpassen oder nur lokal speichern.`

**Bedrock-Region:** Nur eu-central-1 (Frankfurt) oder eu-north-1 (Stockholm). Niemals US-Regionen.