From 6cf17810cdf9d696124fa72f5eada5597a8fb421 Mon Sep 17 00:00:00 2001
From: Christian Mueller <christian@cynfo.com>
Date: Sat, 21 Mar 2026 00:12:58 +0100
Subject: [PATCH] feat: add doc-gen skill and feedback loops for all agents

- New /doc-gen skill: generates INSTALL.md, DEPLOY.md, CHANGELOG.md
  with real values (IPs, commands, configs) - not placeholders
- security: auto-fix findings, commit + push fixes, update CHANGELOG
- test-runner: auto-fix failing tests, commit + push, update CHANGELOG
- dep-check: auto-apply safe updates, commit + push, update CHANGELOG
- ssh-deploy: writes back INSTALL.md + DEPLOY.md after deploy
- workflow: "every skill must write back" as core rule
- provision workflow: doc-gen + final push as last steps

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/dep-check.md   |  24 +++++++
 .claude/skills/doc-gen.md     | 128 ++++++++++++++++++++++++++++++++++
 .claude/skills/security.md    |  32 +++++++--
 .claude/skills/ssh-deploy.md  |  23 ++++++
 .claude/skills/test-runner.md |  24 +++++++
 .claude/skills/workflow.md    |  18 ++++-
 CLAUDE.md                     |   1 +
 7 files changed, 243 insertions(+), 7 deletions(-)
 create mode 100644 .claude/skills/doc-gen.md

diff --git a/.claude/skills/dep-check.md b/.claude/skills/dep-check.md
index ceadc18..25c9648 100644
--- a/.claude/skills/dep-check.md
+++ b/.claude/skills/dep-check.md
@@ -67,6 +67,30 @@ du -sh node_modules/   # Grobe Größe
 3. Beobachten: ...
 ```
 
+## NACH CHECK - AUTOMATISCHER FEEDBACK-LOOP
+
+### 1. Sichere Updates SOFORT durchführen
+```bash
+npm audit fix
+npm test   # verifizieren dass nichts kaputt ist
+```
+
+### 2. Fixes committen und pushen
+```bash
+git add package.json package-lock.json
+git commit -m "security: update vulnerable dependencies"
+git push origin main
+```
+
+### 3. Dokumentation aktualisieren
+CHANGELOG.md ergänzen:
+```markdown
+## [Datum] - Dependency-Updates
+### Sicherheit
+- <Package> aktualisiert von <alt> auf <neu> (CVE-XXXX)
+```
+Dann committen und pushen.
+
 ## REGELN
 - Vor Updates immer `package-lock.json` committen (Rollback-Möglichkeit)
 - Nach Updates: `npm test` ausführen
diff --git a/.claude/skills/doc-gen.md b/.claude/skills/doc-gen.md
new file mode 100644
index 0000000..271f37d
--- /dev/null
+++ b/.claude/skills/doc-gen.md
@@ -0,0 +1,128 @@
+---
+name: doc-gen
+description: Projektdokumentation und Installationsanleitung automatisch generieren und aktuell halten
+user_invocable: true
+---
+
+Du bist der Dokumentations-Agent. Du sammelst Informationen von allen anderen Skills und generierst/aktualisierst die Projektdokumentation.
+
+## PFLICHT-DOKUMENTE
+
+Jedes Projekt MUSS folgende Dateien im Root haben:
+
+### 1. INSTALL.md - Komplette Installationsanleitung
+```markdown
+# Installation - <Projektname>
+
+## Voraussetzungen
+- Proxmox-Server mit API-Zugang (falls LXC)
+- SSH-Key für Serverzugang
+- Gitea-Account auf git.cynfo.net
+
+## LXC-Container erstellen (Proxmox)
+<Automatisch ausgefüllt: VMID, Hostname, IP, Ressourcen>
+
+### Schritt 1: Container anlegen
+<Exakter pct create Befehl mit allen Parametern>
+
+### Schritt 2: Basis-Pakete installieren
+<Exakte apt install Befehle>
+
+### Schritt 3: Node.js / Docker installieren
+<Exakte Installationsbefehle mit Versionen>
+
+### Schritt 4: Deploy-User einrichten
+<Exakte Befehle>
+
+### Schritt 5: Firewall konfigurieren
+<ufw Befehle>
+
+## Anwendung deployen
+
+### Schritt 1: Repository klonen
+git clone <GITEA_URL>/<USER>/<REPO>.git /var/www/app
+
+### Schritt 2: Dependencies installieren
+cd /var/www/app && npm ci --production
+
+### Schritt 3: Environment konfigurieren
+cp .env.example .env
+<Liste aller zu setzenden Variablen mit Beschreibung>
+
+### Schritt 4: Build & Start
+npm run build
+pm2 start dist/index.js --name <app>
+
+### Schritt 5: Nginx Reverse-Proxy
+<Exakte nginx config>
+
+## Verifizierung
+curl http://<LXC_IP>/health
+curl http://<LXC_IP>/api/health
+
+## Bekannte Konfigurationen
+<Tabelle: Was | Wert | Hinweis>
+- LXC VMID: <id>
+- LXC IP: <ip>
+- Node.js: 22.x
+- PM2 App-Name: <name>
+- Ports: Frontend 3000, Backend 4000, Nginx 80
+```
+
+### 2. DEPLOY.md - Deployment-Anleitung für Updates
+```markdown
+# Deployment - <Projektname>
+
+## Update deployen
+ssh deploy@<IP> "cd /var/www/app && git pull origin main && npm ci --production && npm run build && pm2 restart app"
+
+## Rollback
+ssh deploy@<IP> "cd /var/www/app && git checkout <commit> && npm ci --production && npm run build && pm2 restart app"
+
+## Docker-Update (falls Docker)
+ssh deploy@<IP> "cd /var/www/app && git pull origin main && docker compose down && docker compose up -d --build"
+```
+
+### 3. CHANGELOG.md - Was wurde geändert
+```markdown
+# Changelog
+
+## [Datum] - <Version/Beschreibung>
+### Hinzugefügt
+- ...
+### Geändert
+- ...
+### Behoben
+- ...
+### Sicherheit
+- ...
+```
+
+## WANN DOKUMENTATION AKTUALISIEREN
+
+JEDER Skill MUSS nach seiner Ausführung dem doc-gen seine Ergebnisse melden:
+
+| Skill | Schreibt in Doku |
+|-------|-----------------|
+| `/proxmox-lxc` | INSTALL.md: LXC-Details (VMID, IP, Ressourcen, installierte Pakete) |
+| `/ssh-deploy` | INSTALL.md: Deploy-Befehle, DEPLOY.md: Update-Anleitung |
+| `/security` | CHANGELOG.md: Gefundene & behobene Security-Issues |
+| `/test-runner` | CHANGELOG.md: Test-Ergebnisse, Coverage |
+| `/code-gen` | CHANGELOG.md: Neue Features/Fixes |
+| `/docker-build` | INSTALL.md: Docker-Setup-Anleitung |
+| `/dep-check` | CHANGELOG.md: Dependency-Updates |
+
+## REGELN
+
+1. **Immer konkret**: Keine Platzhalter, sondern echte IPs, Ports, Befehle
+2. **Copy-Paste-fähig**: Jeder Befehl muss 1:1 ausführbar sein
+3. **Versioniert**: Dokumentation wird mit committet und gepusht
+4. **Aktuell**: Nach JEDER Änderung am System die Doku updaten
+5. **INSTALL.md = Wahrheit**: Wenn jemand das Projekt clont und INSTALL.md folgt, MUSS die App laufen
+
+## NACH DOKU-UPDATE
+```
+git add INSTALL.md DEPLOY.md CHANGELOG.md
+git commit -m "docs: update documentation after <was passiert ist>"
+git push origin main
+```
diff --git a/.claude/skills/security.md b/.claude/skills/security.md
index f8602bf..a77ecd7 100644
--- a/.claude/skills/security.md
+++ b/.claude/skills/security.md
@@ -54,7 +54,31 @@ Schweregrade: KRITISCH / HOCH / MITTEL / NIEDRIG
 - Grep nach Secret-Patterns im gesamten Projekt
 - `.env` Dateien prüfen ob in `.gitignore`
 
-## NACH ANALYSE
-- Zusammenfassung mit Statistik
-- Kritische Issues zuerst beheben
-- Fix-Vorschläge mit Code-Beispielen
+## NACH ANALYSE - AUTOMATISCHER FEEDBACK-LOOP
+
+### 1. Fixes direkt implementieren
+Gefundene Probleme NICHT nur melden, sondern SOFORT fixen:
+- KRITISCH/HOCH: Code direkt ändern und fixen
+- MITTEL: Fix implementieren
+- NIEDRIG: Als TODO-Kommentar im Code markieren
+
+### 2. Fixes committen und pushen
+```bash
+git add <geänderte-dateien>
+git commit -m "security: fix <OWASP-Kategorie> in <Datei>"
+git push origin main
+```
+
+### 3. Dokumentation aktualisieren
+CHANGELOG.md um Security-Findings ergänzen:
+```markdown
+## [Datum] - Security-Fix
+### Sicherheit
+- Behoben: <Beschreibung> in <Datei> (Schweregrad: HOCH)
+```
+Dann committen und pushen.
+
+### 4. Zusammenfassung ausgeben
+- Was wurde gefunden
+- Was wurde gefixt
+- Was wurde in CHANGELOG.md dokumentiert
diff --git a/.claude/skills/ssh-deploy.md b/.claude/skills/ssh-deploy.md
index ef9dec4..0aa82b2 100644
--- a/.claude/skills/ssh-deploy.md
+++ b/.claude/skills/ssh-deploy.md
@@ -115,6 +115,29 @@ ssh ... "curl -sf http://localhost:3000/health"
 - **Git**: `git checkout <vorheriger-commit>` auf dem Server
 - **Docker**: `docker compose down && git checkout <commit> && docker compose up -d --build`
 
+## NACH DEPLOY - DOKUMENTATION AKTUALISIEREN
+
+### INSTALL.md aktualisieren
+Nach jedem erfolgreichen Deploy die INSTALL.md mit den echten Werten füllen:
+- Server-IP, VMID, Hostname
+- Installierte Pakete und Versionen
+- Exakte Befehle die ausgeführt wurden
+- Nginx-Konfiguration
+- PM2/Docker Service-Name
+
+### DEPLOY.md aktualisieren
+Den exakten One-Liner für zukünftige Updates eintragen:
+```bash
+ssh deploy@<ECHTE-IP> "cd /var/www/app && git pull origin main && npm ci --production && npm run build && pm2 restart <APP-NAME>"
+```
+
+### Committen und Pushen
+```bash
+git add INSTALL.md DEPLOY.md
+git commit -m "docs: update install/deploy documentation"
+git push origin main
+```
+
 ## SICHERHEIT
 - SSH-Key niemals im Repository
 - Git-Credentials auf dem Server: `chmod 600 ~/.git-credentials`
diff --git a/.claude/skills/test-runner.md b/.claude/skills/test-runner.md
index 7aecb82..9300680 100644
--- a/.claude/skills/test-runner.md
+++ b/.claude/skills/test-runner.md
@@ -90,3 +90,27 @@ describe('GET /api/resource', () => {
 - Keine Test-Abhängigkeiten untereinander
 - Mocks für externe Services
 - Cleanup nach Tests (afterEach)
+
+## NACH TESTS - AUTOMATISCHER FEEDBACK-LOOP
+
+### Bei fehlgeschlagenen Tests
+1. Bug im Code identifizieren und SOFORT fixen
+2. Tests erneut ausführen bis grün
+3. Fix committen und pushen:
+```bash
+git add <geänderte-dateien>
+git commit -m "fix: <was behoben wurde>"
+git push origin main
+```
+
+### Dokumentation aktualisieren
+CHANGELOG.md um Test-Ergebnisse ergänzen:
+```markdown
+## [Datum]
+### Behoben
+- <Bug-Beschreibung> (gefunden durch Tests)
+### Tests
+- Coverage: <X>% (Ziel: 80%)
+- Neue Tests: <Anzahl>
+```
+Dann committen und pushen.
diff --git a/.claude/skills/workflow.md b/.claude/skills/workflow.md
index 8f000c7..06ebdcc 100644
--- a/.claude/skills/workflow.md
+++ b/.claude/skills/workflow.md
@@ -17,6 +17,7 @@ Du bist der Workflow-Orchestrator. Du koordinierst alle verfügbaren Skills für
 - `/log-analyzer` - Logs analysieren
 - `/dep-check` - Dependencies prüfen
 - `/proxmox-lxc` - Proxmox LXC-Container erstellen & verwalten
+- `/doc-gen` - Dokumentation generieren (INSTALL.md, DEPLOY.md, CHANGELOG.md)
 
 ## STANDARD-WORKFLOWS
 
@@ -72,6 +73,8 @@ Du bist der Workflow-Orchestrator. Du koordinierst alle verfügbaren Skills für
 4. [ssh-deploy]     → git clone $GITEA_URL/$USER/$REPO auf LXC
 5. [ssh-deploy]     → npm ci, build, Service starten
 6. [log-analyzer]   → Health-Check & Logs prüfen
+7. [doc-gen]        → INSTALL.md + DEPLOY.md mit echten Werten generieren
+8. [git-push]       → Dokumentation committen und pushen
 ```
 
 ## QUALITÄTS-GATES
@@ -91,7 +94,16 @@ Du bist der Workflow-Orchestrator. Du koordinierst alle verfügbaren Skills für
 - [ ] Alle Deploy-Gates
 - [ ] E2E-Tests auf Staging bestanden (falls vorhanden)
 
+## GRUNDREGEL: JEDER SKILL SCHREIBT ZURÜCK
+
+Kein Skill darf "still" beenden. Nach jeder Ausführung:
+1. **Fehler gefunden?** → Sofort fixen, committen, pushen
+2. **System verändert?** → INSTALL.md / DEPLOY.md aktualisieren
+3. **Etwas Wichtiges passiert?** → CHANGELOG.md ergänzen
+4. **Alles committen und pushen** → Doku ist immer aktuell im Git
+
 ## FEHLERBEHANDLUNG
-- Test-Fehler → Fix implementieren → Erneut testen → Loop bis grün
-- Security-Issue → Sicherheitsfix → Re-Check
-- Deploy-Fehler → Logs analysieren → Rollback falls nötig
+- Test-Fehler → Fix implementieren → Erneut testen → Loop bis grün → Commit + Push
+- Security-Issue → Sicherheitsfix → Re-Check → Commit + Push
+- Deploy-Fehler → Logs analysieren → Fix → Commit + Push → Erneut deployen
+- **IMMER**: CHANGELOG.md aktualisieren mit was passiert ist
diff --git a/CLAUDE.md b/CLAUDE.md
index cfc72f6..4514e9f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -23,6 +23,7 @@ Dieses Verzeichnis in neue Projekte klonen/kopieren um sofort alle Agenten verf
 | Log-Analyzer | `/log-analyzer` | Remote-Logs holen und analysieren |
 | Dep-Check | `/dep-check` | Dependencies auf Vulnerabilities prüfen |
 | Proxmox-LXC | `/proxmox-lxc` | LXC-Container auf Proxmox erstellen & verwalten |
+| Doc-Generator | `/doc-gen` | INSTALL.md, DEPLOY.md, CHANGELOG.md generieren |
 | Workflow | `/workflow` | Alle Skills orchestrieren (Feature, Bugfix, Release) |
 
 ## Workflow-Beispiele