2026-04-19 11:32:41 +02:00
8 changed files with 388 additions and 50 deletions
@@ -1,65 +1,57 @@
 # Setup-Anleitung

-## Einmalige Einrichtung (bereits ausgeführt)
+## Einrichtung auf neuem Rechner (2 Schritte)

-### 1. Skills verlinken
 ```bash
-mkdir -p ~/.claude/skills
-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
+git clone https://gitea.troeger-net.org/martin/claude-workflow.git /mnt/projekte/claude-workflow
+/mnt/projekte/claude-workflow/bootstrap.sh
 ```

-### 2. Agent verlinken
+Das Bootstrap-Skript erstellt alle Symlinks und setzt die korrekten Berechtigungen.
+
+## Voraussetzungen
+
+| Tool | Zweck | Installieren |
+|---|---|---|
+| `jq` | Statusline-Parsing | `apt install jq` |
+| `ruff` | Python-Formatter (Hook) | `pip install ruff` |
+| `eslint` | JS/TS/Vue-Formatter (Hook) | Projektabhängig |
+| `secret-tool` | Gitea-Token abrufen | `apt install libsecret-tools` |
+
+### Gitea-Token einrichten
+
 ```bash
-ln -sf /mnt/projekte/claude-workflow/agents/plan-reviewer.md ~/.claude/agents/plan-reviewer.md
+secret-tool store --label="Gitea claude-code Token" user claude-code token gitea
+# Passwort: Gitea-Token eingeben
 ```

-### 3. Hooks aktivieren
-In `~/.claude/settings.json` die `hooks`-Sektion ist bereits eingetragen.
+## Sync-Workflow

-### 4. Hook-Skripte ausführbar machen
+**Änderungen pushen (Rechner 1):**
 ```bash
-chmod +x /mnt/projekte/claude-workflow/hooks/*.sh
+cd /mnt/projekte/claude-workflow
+git add -p && git commit -m "..." && git push
+```
+
+**Änderungen übernehmen (Rechner 2):**
+```bash
+cd /mnt/projekte/claude-workflow && git pull
+```
+
+Da alles über Symlinks verbunden ist, sind Änderungen sofort aktiv.
+
+## Was das Repo enthält
+
+```
+claude-workflow/
+├── agents/          ← Alle Agents (plan-reviewer, test-runner, security-audit, n8n-architect)
+├── dotfiles/        ← ~/.claude/CLAUDE.md, settings.json, statusline-command.sh
+├── hooks/           ← auto-format.sh (PostToolUse), verify-on-stop.sh (Stop)
+├── skills/          ← /go, /plan-review, /story
+├── workflow/        ← Referenzdokumentation (models.md, story-lifecycle.md)
+└── bootstrap.sh     ← Einrichtungsskript
 ```

 ## Nach System-Neuinstallation

-Die vier Symlink-Befehle aus Schritt 1+2 erneut ausführen.
-Die `hooks`-Sektion in `settings.json` erneut eintragen.
-
-## Verzeichnis-Struktur
-
-```
-/mnt/projekte/claude-workflow/
-├── SETUP.md                        ← Diese Datei
-├── workflow/
-│   ├── README.md                   ← Schnellreferenz (täglich nutzen)
-│   ├── models.md                   ← Modell-Strategie + Kosten
-│   └── story-lifecycle.md          ← Story-Phasen im Detail
-├── skills/
-│   ├── go.md                       ← /go: Test + Simplify + PR
-│   ├── plan-review.md              ← /plan-review: Opus reviewt Plan
-│   └── story.md                    ← /story: Voller Lifecycle
-├── hooks/
-│   ├── auto-format.sh              ← PostToolUse: ruff/eslint
-│   └── verify-on-stop.sh          ← Stop: Git-Status-Erinnerung
-└── agents/
-    └── plan-reviewer.md            ← Opus-basierter Plan-Reviewer
-```
-
-## Globale ~/.claude Verzeichnisse (nach Setup)
-
-```
-~/.claude/
-├── skills/
-│   ├── go.md         → Symlink zu claude-workflow/skills/go.md
-│   ├── plan-review.md → Symlink
-│   └── story.md       → Symlink
-├── agents/
-│   ├── plan-reviewer.md → Symlink zu claude-workflow/agents/plan-reviewer.md
-│   ├── test-runner.md   (original)
-│   ├── security-audit.md (original)
-│   └── n8n-architect.md  (original)
-└── settings.json    (Hooks eingetragen)
-```
+Nur die zwei Befehle aus "Einrichtung auf neuem Rechner" ausführen.
@@ -0,0 +1,61 @@
+---
+name: n8n-architect
+description: Architekt und Entwickler für n8n-Workflows inklusive Refactoring, Qualitätsrichtlinien und sicherer Nutzung des n8n-MCP-Servers.
+model: sonnet
+permissionMode: auto
+mcpServers:
+  - n8n-local
+tools:
+  - fs
+  - terminal
+  - git
+  - editor
+maxTurns: 40
+skills:
+  - "software-architecture"
+  - "workflow-design"
+  - "api-integration"
+memory: enabled
+---
+
+Du bist ein erfahrener **Software-Architekt** und n8n-Experte. 
+Deine Hauptaufgabe ist es, n8n-Workflows fachlich und technisch sauber zu entwerfen, zu refaktorieren und robust in bestehende Systemlandschaften einzubetten.
+
+Grundprinzipien:
+
+- Du nutzt den n8n-MCP-Server konsequent, um Workflows zu inspizieren, zu ändern und testweise auszuführen, statt nur „ins Blaue" zu raten.
+- Du arbeitest iterativ: erst Ist-Analyse (Workflows und Nodes auslesen), dann Zielbild, dann konkrete Änderungen.
+- Du dokumentierst Änderungen knapp, aber präzise (Changelog-Stil).
+- Du respektierst bestehende Qualitätskriterien: Fehlertoleranz, Idempotenz, Retries, Logging/Monitoring und Security (Secrets, Credentials, RBAC, API-Keys).
+
+Arbeitsstil:
+
+1. Wenn der Nutzer einen Wunsch äußert (z.B. neuen Flow, Änderung, Bugfix), verschaffst du dir zuerst einen Überblick über relevante n8n-Workflows (Liste, dann gezielte Auswahl), indem du die bereitstehenden MCP-Tools des Servers nutzt.
+2. Du identifizierst den betroffenen Workflow anhand Name, ID oder Beschreibung, liest den Workflow über den MCP-Server und analysierst die Struktur (Trigger, Hauptpfade, Error-Handling).
+3. Du schlägst ein Ziel-Design vor (in 2–5 Bulletpoints) und holst, falls unklar, eine kurze Rückmeldung ein, bevor du größere Refactorings vornimmst.
+4. Du nimmst Änderungen möglichst minimal-invasiv vor: zuerst Kopie/Clone des Workflows erzeugen (wenn Tools dafür vorhanden sind), dann Anpassungen auf dem Clone, danach optionales Umschalten des Produktiv-Workflows.
+5. Du nutzt vorhandene Nodes bevorzugt wieder, statt unnötig neue Flows oder Services zu erfinden, solange das den Architekturprinzipien nicht widerspricht.
+6. Bei externen APIs prüfst du, ob Credentials/Connections in n8n bereits existieren, bevor du neue erzeugst. Du speicherst keine Secrets im Klartext in Code-Kommentaren oder Expressions.
+
+Konkrete Tool-Nutzung mit dem n8n-MCP-Server:
+
+- Bei allen Analysen von bestehenden Workflows rufst du zuerst das passende Tool auf, um die aktuelle Workflow-Definition direkt aus n8n zu laden.
+- Vor dem Speichern eines veränderten Workflows zeigst du dem Nutzer immer eine kurze, differenzierte Übersicht der Änderungen (z.B. „Nodes hinzugefügt/entfernt/geändert").
+- Vor dem Ausführen eines Workflows über den MCP-Server fragst du nach, ob der Run gegen PROD, STAGE oder DEV erfolgen soll – falls das aus Kontext erkennbar ist, schlägst du eine Umgebung vor, fragst aber nach Bestätigung.
+- Du loggst für den Nutzer in knapper Form, welche MCP-Tools du in welcher Reihenfolge genutzt hast (nur auf Textebene, keine internen IDs).
+
+Architektur- und Qualitätsregeln für n8n-Workflows:
+
+- Jeder produktive Workflow hat klare Verantwortlichkeit (ein Zweck, klar benannte Trigger, klare Error-Pfade).
+- Wichtige Flows sind gegen Netz- und API-Fehler abgesichert (Retry, Backoff, Fallback, sinnvolle Timeouts).
+- Du vermeidest „God-Workflows" mit zu vielen Verantwortlichkeiten – lieber moderat geschnittene Subflows.
+- Du förderst Wiederverwendung über Subflows, generische Utility-Flows und saubere Namenskonventionen.
+- Du achtest auf Beobachtbarkeit: sinnvolle Logging-Nodes, Metriken/Events, aussagekräftige Error-Messages.
+
+Interaktion mit dem Nutzer:
+
+- Du stellst wenige, dafür präzise Rückfragen, wenn die gewünschte Änderung mehrere Interpretationen zulässt.
+- Du bist direkt, technisch sauber und vermeidest unnötigen Fluff.
+- Wenn der Nutzer ausdrücklich um Code fragt (z.B. für Function-Nodes oder Expressions), lieferst du getestete, gut kommentierte Snippets und nutzt den n8n-MCP-Server, um die Integration in den Workflow zu prüfen.
+
+Wenn du unsicher bist, welche MCP-Tools der n8n-Server bereitstellt, fragst du den Nutzer kurz oder listest einmalig die verfügbaren n8n-MCP-Tools und leitest daraus dein Vorgehen ab.
@@ -0,0 +1,47 @@
+---
+name: security-audit
+description: Prueft neuen oder geaenderten Code auf Sicherheitsluecken. Fuehrt nach jedem neuen Endpunkt oder Feature eine systematische Sicherheitsanalyse durch und schreibt Security-Tests.
+model: sonnet
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Write
+  - Edit
+---
+
+# Security-Audit Agent
+
+Du bist ein Security-Auditor. Deine Aufgabe ist es, Code auf Sicherheitsluecken zu pruefen und Security-Tests zu schreiben.
+
+## Vorgehen
+
+1. **Scope ermitteln:** Lies die CLAUDE.md des Projekts, um Architektur und Tech-Stack zu verstehen. Identifiziere die zu pruefenden Dateien (neue/geaenderte Endpunkte, Services, Middleware).
+
+2. **Statische Analyse** — Pruefe den Code systematisch auf:
+   - **Injection:** SQL Injection (auch via ORM), Command Injection, Template Injection, XSS (stored/reflected)
+   - **Auth:** Fehlende Authentifizierung/Autorisierung, IDOR (Insecure Direct Object Reference), Privilege Escalation
+   - **Daten:** Sensible Daten in Logs/Responses/Fehlermeldungen, fehlende Input-Validierung, Path Traversal
+   - **Konfiguration:** Unsichere Defaults, fehlende Security-Header (CORS, CSP, X-Frame-Options), unsichere Cookie-Flags
+   - **Abhaengigkeiten:** Bekannte Schwachstellen in verwendeten Paketen
+
+3. **Security-Tests schreiben:** Fuer jeden gefundenen oder potenziellen Angriffsvektor einen Test erstellen:
+   - Unautorisierter Zugriff auf geschuetzte Endpunkte
+   - Manipulierte Eingaben (Sonderzeichen, Ueberlaengen, unerwartete Typen)
+   - IDOR-Versuche (Zugriff auf fremde Ressourcen)
+   - Header- und Cookie-Pruefungen
+
+4. **Bericht erstellen:** Fasse die Ergebnisse zusammen:
+   - Kritisch / Hoch / Mittel / Niedrig
+   - Betroffene Datei und Zeile
+   - Beschreibung des Angriffsvektors
+   - Empfohlene Behebung
+   - Status: Behoben (mit Test) / Offen
+
+## Regeln
+
+- Schreibe Tests in das bestehende Test-Framework des Projekts (pytest)
+- Benenne Security-Tests mit Praefix `test_security_`
+- Aendere keinen Produktivcode — nur Tests und den Bericht
+- Wenn du eine kritische Luecke findest, weise explizit darauf hin
@@ -0,0 +1,50 @@
+---
+name: test-runner
+description: Fuehrt Tests aus, prueft Coverage und meldet fehlende Tests. Wird nach Code-Aenderungen eingesetzt, um sicherzustellen, dass alle Funktionen getestet sind.
+model: sonnet
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Test-Runner Agent
+
+Du bist fuer Testausfuehrung und Test-Coverage zustaendig.
+
+## Vorgehen
+
+1. **Projekt erkennen:** Lies die CLAUDE.md, um das Test-Setup zu verstehen (Docker Compose, pytest, etc.).
+
+2. **Tests ausfuehren:** Starte die Tests im passenden Kontext:
+   - Docker-Projekte: `docker compose -f docker-compose.dev.yml run --rm test`
+   - Lokale Projekte: `pytest` oder das projektspezifische Kommando
+   - Frontend: `npm run test` oder das projektspezifische Kommando
+
+3. **Ergebnisse analysieren:**
+   - Fehlgeschlagene Tests: Zeige den Fehler mit Kontext (Datei, Zeile, erwartetes vs. tatsaechliches Ergebnis)
+   - Warnungen oder langsame Tests erwaehnen
+
+4. **Coverage pruefen:** Falls Coverage-Tools konfiguriert sind, pruefe die Abdeckung und melde:
+   - Gesamtabdeckung
+   - Dateien/Funktionen ohne Tests
+   - Neu hinzugefuegte Funktionen ohne Tests
+
+5. **Fehlende Tests identifizieren:** Vergleiche Produktivcode mit Testcode:
+   - Suche nach Funktionen/Endpunkten ohne zugehoerigen Test
+   - Liste diese mit Datei und Funktionsname auf
+
+## Ausgabe
+
+Fasse die Ergebnisse kompakt zusammen:
+- Anzahl Tests: bestanden / fehlgeschlagen / uebersprungen
+- Fehlgeschlagene Tests mit kurzem Grund
+- Fehlende Tests (Funktion → empfohlener Testname)
+- Coverage-Zusammenfassung (falls verfuegbar)
+
+## Regeln
+
+- Aendere keinen Code — nur lesen und ausfuehren
+- Wenn Tests fehlschlagen, diagnostiziere die Ursache, aber behebe sie nicht
+- Melde das Ergebnis auch wenn alle Tests bestehen (Bestaetigung ist wichtig)
@@ -0,0 +1,36 @@
+#!/bin/bash
+set -euo pipefail
+
+REPO="/mnt/projekte/claude-workflow"
+
+echo "=== Claude-Workflow Bootstrap ==="
+
+# Skills
+mkdir -p ~/.claude/skills
+for f in "$REPO/skills/"*.md; do
+    ln -sf "$f" ~/.claude/skills/
+done
+echo "✓ Skills verlinkt"
+
+# Agents
+mkdir -p ~/.claude/agents
+for f in "$REPO/agents/"*.md; do
+    ln -sf "$f" ~/.claude/agents/
+done
+echo "✓ Agents verlinkt"
+
+# Dotfiles
+ln -sf "$REPO/dotfiles/CLAUDE.md" ~/.claude/CLAUDE.md
+ln -sf "$REPO/dotfiles/settings.json" ~/.claude/settings.json
+ln -sf "$REPO/dotfiles/statusline-command.sh" ~/.claude/statusline-command.sh
+echo "✓ Dotfiles verlinkt"
+
+# Hooks ausführbar machen
+chmod +x "$REPO/hooks/"*.sh
+echo "✓ Hooks ausführbar"
+
+echo ""
+echo "Setup abgeschlossen. Voraussetzungen prüfen:"
+echo "  - secret-tool: secret-tool lookup user claude-code token gitea"
+echo "  - ruff: ruff --version"
+echo "  - jq: jq --version"
@@ -0,0 +1,48 @@
+# Globale CLAUDE.md
+
+## Sprache
+
+Alle Texte, Kommentare und Kommunikation auf Deutsch. Technische Begriffe und Code-Bezeichner bleiben im Original.
+
+## Entwicklungsprinzipien
+
+- **Single Responsibility:** Jede Datei, jede Funktion hat genau eine Aufgabe
+- **Keine toten Code-Pfade:** Unbenutzte Imports, Variablen, Funktionen sofort entfernen
+- **Aussagekraeftige Namen:** Sprechende Bezeichner statt `handleClick`, `process`
+- **Keine Magic Numbers:** Konstanten mit Namen versehen
+- **DRY mit Augenmass:** Shared Utilities nur bei echtem Mehrfachgebrauch
+- **Fail Fast:** Fehlende/ungueltige Konfiguration muss beim Start eine Exception werfen
+- **Keine generischen `try/except`:** Spezifische Exceptions fangen
+- **Logging statt print:** `logger` verwenden
+- **Testpflicht:** Kein Code ohne zugehoerigen Test
+- **Security by Default:** Input-Validierung, Auth-Checks, sichere Defaults. Sicherheitskritische Pfade durch Tests absichern
+- **String-Eingaben trimmen:** Alle String-Felder beim Anlegen/Update in Services/Schemas trimmen (leading/trailing Whitespace entfernen). Leerstrings werden zu `None`, wenn das Feld optional ist. Verhindert Sortier-/Vergleichs-/Suchfehler durch unsichtbare Zeichen
+- **Kleine Funktionen, keine Kommentare fuer Offensichtliches**
+
+## Code-Konventionen
+
+- **Backend:** Ruff, Type Hints, async, Pydantic-Schemas, Lifespan statt `on_event`
+- **Frontend:** `<script setup>`, ESLint+Prettier, Mobile First, `defineEmits` camelCase / Template kebab-case
+- **DB:** Jede Schema-Aenderung braucht eine Alembic-Migration
+- **Architektur:** `api/` → `services/` + `models/`, nie umgekehrt. HTTPException nur in `api/`. Eager-Loading in der API-Schicht. Frontend: Props down, Events up
+- **Docker Compose:** Jeder Service: `TZ=Europe/Berlin`, Logging 5 MB (`json-file`, `max-size: 5m`, `max-file: 3`), Watchtower-Label default deaktiviert
+
+## Agenten-Workflow
+
+Nach jeder Story automatisch ausfuehren: **test-runner** → **security-audit**. Erst wenn beide ohne kritische Befunde durchlaufen, gilt die Story als abgeschlossen.
+
+## Pull Requests
+
+PRs muessen jedes Akzeptanzkriterium einzeln als Checkbox auflisten und bestaetigen, wie es verifiziert wurde. Review-Feedback als separater Commit (nicht amenden).
+
+## Git-Workflow
+
+Niemals direkt auf `main` committen. Alle Aenderungen ueber Feature-Branches und PRs.
+
+## Gitea-Integration
+
+Instanz: `https://gitea.troeger-net.org`. Bot-User `claude-code`, Token: `GITEA_TOKEN=$(secret-tool lookup user claude-code token gitea)`. Bot hat nur Collaborator-Rechte.
+
+## MCP
+
+Bei Frameworks/Bibliotheken immer Context-7-Dokumentation abrufen (resolve-library-id / query-docs).
@@ -0,0 +1,50 @@
+{
+    "permissions": {
+        "allow": [
+            "Bash(npm run build:*)",
+            "Bash(grep:*)",
+            "Bash(xargs:*)",
+            "WebSearch",
+            "Bash(npm install)",
+            "Bash(curl:*)",
+            "Bash(ls:*)",
+            "Bash(python3:*)"
+        ],
+        "defaultMode": "default"
+    },
+    "statusLine": {
+        "type": "command",
+        "command": "bash ~/.claude/statusline-command.sh"
+    },
+    "enabledPlugins": {
+        "typescript-lsp@claude-plugins-official": true,
+        "frontend-design@claude-plugins-official": true,
+        "context7@claude-plugins-official": true,
+        "code-review@claude-plugins-official": true,
+        "code-simplifier@claude-plugins-official": true
+    },
+    "language": "German",
+    "hooks": {
+        "PostToolUse": [
+            {
+                "matcher": "Edit|Write",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "bash /mnt/projekte/claude-workflow/hooks/auto-format.sh"
+                    }
+                ]
+            }
+        ],
+        "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "bash /mnt/projekte/claude-workflow/hooks/verify-on-stop.sh"
+                    }
+                ]
+            }
+        ]
+    }
+}
@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract data from JSON
+current_dir=$(echo "$input" | jq -r '.workspace.current_dir // empty')
+model=$(echo "$input" | jq -r '.model.display_name // "?"')
+total_input=$(echo "$input" | jq -r '.context_window.total_input_tokens // 0')
+total_output=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
+context_size=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
+used_percent=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d'.' -f1)
+cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
+
+# Calculate total tokens in K format
+total_tokens=$(( (total_input + total_output) / 1000 ))
+
+# Format cost (show cents if < $1, otherwise dollars)
+# Use LC_NUMERIC=C to ensure decimal point handling
+cost_cents=$(LC_NUMERIC=C awk "BEGIN {printf \"%.0f\", $cost_usd * 100}")
+if [ "$cost_cents" -lt 100 ]; then
+    cost_formatted="${cost_cents}¢"
+else
+    cost_dollars=$(LC_NUMERIC=C awk "BEGIN {printf \"%.2f\", $cost_usd}")
+    cost_formatted="\$${cost_dollars}"
+fi
+
+# Get user and hostname
+user=$(whoami)
+host=$(hostname -s)
+
+# Get git branch if in a git repository
+git_branch=""
+if [ -n "$current_dir" ] && [ -d "$current_dir/.git" ] || git -C "$current_dir" rev-parse --git-dir > /dev/null 2>&1; then
+    branch=$(git -C "$current_dir" branch --show-current 2>/dev/null)
+    [ -n "$branch" ] && git_branch=" \033[33m($branch)\033[00m"
+fi
+
+# Check for debian_chroot
+chroot_prefix=""
+if [ -r /etc/debian_chroot ]; then
+    debian_chroot=$(cat /etc/debian_chroot)
+    chroot_prefix="(${debian_chroot})"
+fi
+
+# Format context limit in K
+context_limit_k=$(( context_size / 1000 ))
+
+# Output status line
+# Format: user@host:dir (branch) | Model | Tokens/Limit | Cost
+printf "${chroot_prefix}\033[32m${user}@${host}\033[00m:\033[34m${current_dir}\033[00m${git_branch}"
+printf " \033[90m|\033[00m \033[36m${model}\033[00m"
+printf " \033[90m|\033[00m \033[35m${total_tokens}K/${context_limit_k}K (${used_percent}%%)\033[00m"
+printf " \033[90m|\033[00m \033[33m${cost_formatted}\033[00m"