diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..834c136
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Zweck
+
+Dieses Repository enthält die globale Claude-Code-Workflow-Konfiguration für alle Projekte von Martin Tröger. Es definiert Skills, Agenten, Hooks und Dokumentation — kein ausführbarer Anwendungscode.
+
+## Workflow-Weiterentwicklung
+
+Beim Aktualisieren dieses Workflows immer zuerst die externe Best-Practice-Referenz konsultieren und auf relevante Neuerungen prüfen:
+
+**https://github.com/shanraisshan/claude-code-best-practice**
+
+Vorgehen: URL via `WebFetch` abrufen → mit aktuellem Workflow vergleichen → Abweichungen bewerten → bei Bedarf anpassen.
+
+## Struktur
+
+```
+workflow/        ← Referenzdokumentation (täglich lesen)
+  README.md      ← Schnellreferenz: Welcher Befehl für welche Phase
+  models.md      ← Modell-Strategie + Kostenmatrix
+  story-lifecycle.md ← Story-Phasen im Detail
+skills/          ← Slash-Commands (Symlinks nach ~/.claude/skills/)
+agents/          ← Agenten-Definitionen (Symlinks nach ~/.claude/agents/)
+hooks/           ← Shell-Hooks (durch settings.json registriert)
+SETUP.md         ← Einrichtung nach System-Neuinstallation
+```
+
+## Aktivierung (nach Neuinstallation)
+
+```bash
+# Skills und Agent verlinken
+ln -sf /mnt/projekte/claude-workflow/skills/go.md ~/.claude/skills/go.md
+ln -sf /mnt/projekte/claude-workflow/skills/plan-review.md ~/.claude/skills/plan-review.md
+ln -sf /mnt/projekte/claude-workflow/skills/story.md ~/.claude/skills/story.md
+ln -sf /mnt/projekte/claude-workflow/agents/plan-reviewer.md ~/.claude/agents/plan-reviewer.md
+
+# Hook-Skripte ausführbar machen
+chmod +x /mnt/projekte/claude-workflow/hooks/*.sh
+```
+
+Die `hooks`-Sektion in `~/.claude/settings.json` manuell eintragen (siehe `SETUP.md`).
+
+## Story-Lifecycle
+
+```
+Research → Plan (Opus) → /plan-review → Implement (Sonnet) → /go → Security-Audit
+```
+
+Kurzbefehl für den gesamten Ablauf: `/story`
+
+| Phase | Befehl | Modell |
+|---|---|---|
+| Planung | `EnterPlanMode` | Opus 4.7 |
+| Plan-Review | `/plan-review` | Opus 4.7 (Subagent) |
+| Implementierung | direkt | Sonnet 4.6 |
+| Test + Simplify + PR | `/go` | Haiku / Sonnet (Subagenten) |
+| Security-Audit | `security-audit`-Agent | Opus 4.7 |
+
+## Skills
+
+| Befehl | Datei | Beschreibung |
+|---|---|---|
+| `/go` | `skills/go.md` | test-runner → code-simplifier → Gitea-PR |
+| `/plan-review` | `skills/plan-review.md` | Startet plan-reviewer-Agent (Opus, fork) |
+| `/story` | `skills/story.md` | Voller Lifecycle von Research bis PR |
+
+## Agenten
+
+| Agent | Modell | Tools | Rolle |
+|---|---|---|---|
+| `plan-reviewer` | Opus 4.7 | Read, Glob, Grep | Prüft Pläne auf Vollständigkeit, Risiken, fehlende Tests |
+| `test-runner` | Sonnet | alle | Tests ausführen, Coverage prüfen |
+| `security-audit` | Sonnet | alle | OWASP-Analyse, Security-Tests schreiben |
+| `n8n-architect` | Sonnet | alle | n8n-Workflow-Design und Refactoring |
+
+## Hooks
+
+| Event | Trigger | Skript | Aktion |
+|---|---|---|---|
+| `PostToolUse` | Edit / Write | `hooks/auto-format.sh` | `ruff` (Python) oder `eslint --fix` (JS/TS/Vue) |
+| `Stop` | Session-Ende | `hooks/verify-on-stop.sh` | Uncommittete Änderungen anzeigen |
+
+`auto-format.sh` liest den Dateipfad aus `$CLAUDE_TOOL_INPUT_FILE_PATH` und erkennt den Typ anhand der Dateiendung.
+
+## Modell-Strategie
+
+- **Opus 4.7**: Planung, Plan-Review, Security-Audit — überall wo Fehlentscheidungen teuer sind
+- **Sonnet 4.6**: Implementierung, Refactoring, Bug-Fixes (Standard)
+- **Haiku 4.5**: Tests, Lint, Format, PR-Beschreibung
+
+`/fast` aktiviert Opus 4.7 mit schnellerer Ausgabe — sinnvoll bei langen Implementierungen.
+
+## Kontext-Management
+
+- **< 200k Tokens**: Normal weiterarbeiten
+- **200–350k Tokens**: `/compact "aktueller Stand: [Hinweis]"` ausführen
+- **> 350k Tokens**: Neue Session, isolierte Subagenten bevorzugen
+
+## Gitea-Integration
+
+- Instanz: `https://gitea.troeger-net.org`
+- Token für `/go`-Skill: `$(secret-tool lookup user claude-code token gitea)`
+- MCP-Server `gitea` muss aktiv sein (Binary: `~/go/bin/gitea-mcp`)