claudient 0.1.0

package/guides/agent-orchestration.md

@@ -0,0 +1,231 @@
+# Agent Orchestration Guide
+
+How to delegate, parallelize, and specialize work using Claude Code's subagent system.
+
+---
+
+## What Subagents Are
+
+A subagent is a separate Claude instance spawned by the parent session to handle a specific, bounded task. It gets:
+- A fresh context window (no session history)
+- A specific tool subset (if configured)
+- A model selection (can differ from the parent)
+- A prompt you write explicitly
+
+The parent session continues. When the subagent finishes, it returns a result. The parent uses that result and moves on.
+
+Subagents are not magic — they are a specific tool for specific problems. Used correctly, they reduce context bloat, enable parallelism, and allow model specialization. Used incorrectly, they add overhead for no benefit.
+
+---
+
+## When to Use a Subagent
+
+Use a subagent when the task has **clear inputs** and **clear outputs** and is **independent of the current session state**.
+
+**Good candidates:**
+- Reviewing 10 files for security issues — self-contained, read-only, repeatable
+- Running a specific search across the codebase to locate a pattern
+- Generating boilerplate for a new module given a spec
+- Analyzing a log file and returning a summary
+- Writing tests for a function given its signature and behaviour description
+
+**Bad candidates:**
+- Tasks that require the full session context to do correctly
+- Tasks where the output will immediately change what the parent session does next (just do it inline)
+- Tasks that need back-and-forth — subagents are one-shot
+- Anything where the overhead of spawning + prompting exceeds the work itself
+
+---
+
+## 1. Delegation Pattern
+
+The simplest pattern: the parent identifies a bounded task and hands it off.
+
+**Structure:**
+```
+Parent session:
+  → Identifies task (e.g., "find all places where we use the deprecated API")
+  → Writes a self-contained prompt
+  → Spawns subagent with that prompt + relevant file paths
+  → Subagent returns findings
+  → Parent uses findings to continue
+```
+
+**Key rule:** The subagent prompt must be self-contained. It has no access to what the parent session has been doing. Brief it like a colleague who just walked into the room — include the context they need, nothing more.
+
+**What to include in the subagent prompt:**
+- What you're trying to accomplish and why
+- The specific files or directories to look at
+- What format you want the result in
+- Any constraints or decisions already made
+
+**What NOT to include:**
+- The entire session history (defeats the purpose)
+- Information the subagent doesn't need
+- Open-ended questions (subagents are one-shot — make the task precise)
+
+---
+
+## 2. Parallelization Pattern
+
+Multiple subagents running simultaneously on independent tasks. This is the highest-leverage use of the subagent system.
+
+**When to parallelize:**
+- You need the same operation applied to many files/modules (review, lint, test generation)
+- Two genuinely independent tasks that both need to complete before you can proceed
+- Research tasks that cover different areas (e.g., "search for auth patterns" + "search for error handling patterns" simultaneously)
+
+**Using git worktrees for parallel code changes:**
+```bash
+git worktree add ../feature-branch-a feature-a
+git worktree add ../feature-branch-b feature-b
+```
+
+Each subagent works in its own worktree — they can't conflict. The parent merges the results.
+
+**Parallelization anti-patterns:**
+- Parallelizing tasks that share state (both agents write to the same file — conflict)
+- Spawning more agents than you have independent tasks (overhead without benefit)
+- Parallel tasks where one depends on the output of the other (run sequentially instead)
+
+---
+
+## 3. Specialization Pattern (cavecrew)
+
+Match the subagent's model and tool set to the nature of the task. Not every subagent needs Opus. Not every subagent needs all tools.
+
+Inspired by the **cavecrew** pattern (source: [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)):
+
+| Role | Model | Tools | Use when |
+|---|---|---|---|
+| Investigator | Haiku 4.5 | Read, Bash (grep/find only) | Locating things in the codebase — read-only, fast |
+| Builder | Sonnet 4.6 | Read, Edit, Write, Bash | Making surgical 1–2 file changes |
+| Reviewer | Haiku 4.5 | Read | Reviewing a diff or a set of files for issues |
+| Orchestrator | Opus 4.7 | All | Complex multi-step coordination, architecture decisions |
+
+This pattern saves ~60% tokens compared to using Opus for every subagent task.
+
+**Practical example:**
+```
+Parent (Sonnet): "Find all API endpoints that don't validate auth."
+→ Investigator (Haiku): Searches the codebase. Returns list of 6 files + line numbers.
+Parent (Sonnet): Reviews the list, decides which ones are real issues.
+→ Builder (Sonnet): Fixes each real issue, one at a time.
+→ Reviewer (Haiku): Confirms the fix looks correct before the parent moves on.
+```
+
+---
+
+## 4. Context Handoff Pattern
+
+When a session has accumulated significant context and you need to hand work off to a new agent without losing what was learned.
+
+**Pre-handoff checklist:**
+1. Save the current task state to `.claude/memory/session-state.md`
+2. Document decisions made during the session
+3. List files modified and why
+4. Write the handoff prompt explicitly — include everything the next agent needs
+
+**Handoff prompt structure:**
+```
+## Context
+[What this project does, briefly]
+[What we were working on]
+[Decisions made during this session]
+
+## Files modified
+[List with brief reason for each change]
+
+## Current state
+[What's done, what's not done, what's blocking]
+
+## Your task
+[Specific, bounded task for the new agent]
+
+## Constraints
+[Decisions that were made and should not be revisited]
+```
+
+This is the same pattern used by the `handoff` skill in mattpocock/skills.
+
+---
+
+## 5. Hard vs Soft Dependencies
+
+When orchestrating multiple agents or skills, some downstream tasks require upstream setup to work correctly. Others degrade gracefully.
+
+**Hard dependency:** The downstream task explicitly fails without the upstream setup.
+- Example: A skill that posts to GitHub Issues requires the issue tracker to be configured. If it's not, it should halt and tell the user to run the setup skill first.
+- Signal this explicitly in the skill: "This skill requires setup — run `/setup` first if you haven't."
+
+**Soft dependency:** The downstream task works but produces lower-quality output without upstream setup.
+- Example: A code review skill that uses domain terminology from `CONTEXT.md`. Without `CONTEXT.md`, it still reviews code — just less precisely.
+- Don't halt. Don't require setup. Degrade gracefully and note the gap.
+
+Design your agent workflows to be honest about which dependencies are hard and which are soft.
+
+---
+
+## 6. Scope Control for Subagents
+
+Every subagent should have an explicit scope limit. Without one, the subagent may take actions that conflict with the parent session or exceed what was intended.
+
+**What to include in every subagent prompt:**
+```
+## Scope
+- Read: yes
+- Write/Edit: [specific files only OR no]
+- Shell commands: [specific commands allowed OR none]
+- Network: [yes/no]
+
+## Do not
+- Do not modify files outside [directory]
+- Do not make git commits
+- Do not install packages
+```
+
+This is especially important for builder-type subagents with write access.
+
+---
+
+## 7. Returning Results from Subagents
+
+Subagents communicate back to the parent in two ways:
+1. **Return message** — the final text response. Good for short structured results.
+2. **Files** — the subagent writes its findings/output to a file. The parent reads it. Better for larger outputs that need to survive compaction.
+
+**Prefer files for:**
+- Lists of findings that the parent will iterate over
+- Generated code that the parent will review
+- Reports that will be referenced multiple times
+
+**Prefer return messages for:**
+- Simple yes/no answers
+- Short structured data (a JSON object, a list of 3–5 items)
+- Status reports ("task complete, 3 files modified: X, Y, Z")
+
+---
+
+## Quick Reference
+
+| Goal | Pattern |
+|---|---|
+| Bounded, self-contained task | Delegation |
+| Same task on many files | Parallelization |
+| Read-only search/locate | Investigator (Haiku) |
+| Surgical code change | Builder (Sonnet) |
+| Diff/file review | Reviewer (Haiku) |
+| Complex multi-step coordination | Orchestrator (Opus) |
+| Session handoff | Context Handoff pattern |
+| Task requires prior setup | Hard dependency — halt + instruct |
+| Task works better with setup | Soft dependency — degrade gracefully |
+| Large subagent output | Write to file, parent reads it |
+| Small structured result | Return message |
+
+---
+
+## Work With Us
+
+Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products with developer communities and deliver B2B AI solutions. If you're designing multi-agent systems, autonomous workflows, or production-grade Claude Code orchestration — we've built this in production and can help you do the same.
+
+**[uitbreiden.com](https://uitbreiden.com/)**

package/guides/de/agent-orchestration.md

@@ -0,0 +1,174 @@
+# Leitfaden zur Agentenorchestrierung
+
+Wie man Arbeit mit dem Unter-Agenten-System von Claude Code delegiert, parallelisiert und spezialisiert.
+
+---
+
+## Was Unter-Agenten sind
+
+Ein Unter-Agent ist eine separate Claude-Instanz, die von der Elternsitzung gestartet wird, um eine spezifische, begrenzte Aufgabe zu erledigen. Er erhält:
+- Ein frisches Kontextfenster (kein Sitzungsverlauf)
+- Einen spezifischen Tool-Subset (wenn konfiguriert)
+- Eine Modellauswahl (kann vom Elternteil abweichen)
+- Einen Prompt, den Sie explizit schreiben
+
+Unter-Agenten sind keine Magie — sie sind ein spezifisches Werkzeug für spezifische Probleme.
+
+---
+
+## Wann einen Unter-Agenten verwenden
+
+Verwenden Sie einen Unter-Agenten, wenn die Aufgabe **klare Eingaben** und **klare Ausgaben** hat und **unabhängig vom aktuellen Sitzungszustand** ist.
+
+**Gute Kandidaten:**
+- 10 Dateien auf Sicherheitsprobleme überprüfen
+- Eine spezifische Suche in der Codebasis durchführen
+- Boilerplate für ein neues Modul generieren
+- Eine Logdatei analysieren und eine Zusammenfassung zurückgeben
+
+**Schlechte Kandidaten:**
+- Aufgaben, die den vollständigen Sitzungskontext erfordern
+- Aufgaben, die Hin-und-Her erfordern — Unter-Agenten sind einmalig
+- Aufgaben, bei denen der Start-Overhead die Arbeit übersteigt
+
+---
+
+## 1. Delegationsmuster
+
+Die Elternsitzung identifiziert eine begrenzte Aufgabe und übergibt sie.
+
+**Schlüsselregel:** Der Unter-Agenten-Prompt muss eigenständig sein. Er hat keinen Zugang dazu, was die Elternsitzung getan hat. Briefen Sie ihn wie einen Kollegen, der gerade den Raum betreten hat.
+
+**Was in den Unter-Agenten-Prompt einzuschließen ist:**
+- Was Sie zu erreichen versuchen und warum
+- Die spezifischen Dateien oder Verzeichnisse
+- Das gewünschte Ergebnisformat
+- Bereits getroffene Entscheidungen
+
+---
+
+## 2. Parallelisierungsmuster
+
+Mehrere Unter-Agenten laufen gleichzeitig an unabhängigen Aufgaben.
+
+**Wann parallelisieren:**
+- Dieselbe Operation auf viele Dateien/Module angewendet werden soll
+- Zwei wirklich unabhängige Aufgaben beide abgeschlossen werden müssen
+- Forschungsaufgaben verschiedene Bereiche abdecken
+
+**Git-Worktrees für parallele Code-Änderungen:**
+```bash
+git worktree add ../feature-branch-a feature-a
+git worktree add ../feature-branch-b feature-b
+```
+
+**Parallelisierungs-Anti-Muster:**
+- Parallelisieren von Aufgaben, die Zustand teilen (Schreibkonflikte)
+- Parallele Aufgaben, bei denen eine von der Ausgabe der anderen abhängt
+
+---
+
+## 3. Spezialisierungsmuster (cavecrew)
+
+Passen Sie Modell und Tools des Unter-Agenten an die Natur der Aufgabe an. Inspiriert vom **cavecrew**-Muster (Quelle: [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)) — spart ~60% Tokens im Vergleich zur Verwendung von Opus für jeden Unter-Agenten.
+
+| Rolle | Modell | Tools | Verwenden wenn |
+|---|---|---|---|
+| Ermittler | Haiku 4.5 | Read, Bash (nur grep/find) | Dinge in der Codebasis lokalisieren — nur lesen, schnell |
+| Ersteller | Sonnet 4.6 | Read, Edit, Write, Bash | Chirurgische 1–2 Datei-Änderungen |
+| Prüfer | Haiku 4.5 | Read | Einen Diff oder eine Dateigruppe prüfen |
+| Orchestrator | Opus 4.7 | Alle | Komplexe mehrstufige Koordination, Architekturentscheidungen |
+
+---
+
+## 4. Kontextübergabemuster
+
+Wenn eine Sitzung bedeutenden Kontext angesammelt hat und Sie die Arbeit an einen neuen Agenten übergeben müssen.
+
+**Struktur des Übergabe-Prompts:**
+```
+## Context
+[Was dieses Projekt macht, kurz]
+[Woran wir gearbeitet haben]
+[In dieser Sitzung getroffene Entscheidungen]
+
+## Files modified
+[Liste mit kurzem Grund für jede Änderung]
+
+## Current state
+[Was erledigt, was nicht, was blockiert]
+
+## Your task
+[Spezifische, begrenzte Aufgabe für den neuen Agenten]
+
+## Constraints
+[Getroffene Entscheidungen, die nicht neu diskutiert werden sollen]
+```
+
+---
+
+## 5. Harte vs. weiche Abhängigkeiten
+
+**Harte Abhängigkeit:** Die nachgelagerte Aufgabe schlägt ohne die vorgelagerte Einrichtung explizit fehl.
+- Signalisieren Sie dies explizit: "Diese Skill erfordert Einrichtung — führen Sie zuerst `/setup` aus."
+
+**Weiche Abhängigkeit:** Die Aufgabe funktioniert, produziert aber ohne Einrichtung eine Ausgabe geringerer Qualität.
+- Nicht anhalten. Elegant degradieren und die Lücke notieren.
+
+---
+
+## 6. Umfangskontrolle für Unter-Agenten
+
+Jeder Unter-Agent sollte ein explizites Umfangslimit haben.
+
+**In jeden Unter-Agenten-Prompt einschließen:**
+```
+## Scope
+- Read: yes
+- Write/Edit: [nur spezifische Dateien ODER nein]
+- Shell commands: [spezifische erlaubte Befehle ODER keine]
+- Network: [ja/nein]
+
+## Do not
+- Do not modify files outside [directory]
+- Do not make git commits
+- Do not install packages
+```
+
+---
+
+## 7. Ergebnisse von Unter-Agenten zurückgeben
+
+**Dateien bevorzugen für:**
+- Ergebnislisten, über die der Elternteil iterieren wird
+- Generierten Code, den der Elternteil prüfen wird
+- Mehrfach referenzierte Berichte
+
+**Rückgabemeldungen bevorzugen für:**
+- Einfache Ja/Nein-Antworten
+- Kurze strukturierte Daten
+- Statusberichte
+
+---
+
+## Schnellreferenz
+
+| Ziel | Muster |
+|---|---|
+| Begrenzte, eigenständige Aufgabe | Delegation |
+| Gleiche Aufgabe auf vielen Dateien | Parallelisierung |
+| Schreibgeschützte Suche/Lokalisierung | Ermittler (Haiku) |
+| Chirurgische Code-Änderung | Ersteller (Sonnet) |
+| Diff/Datei-Prüfung | Prüfer (Haiku) |
+| Komplexe mehrstufige Koordination | Orchestrator (Opus) |
+| Sitzungsübergabe | Kontextübergabemuster |
+| Große Unter-Agenten-Ausgabe | In Datei schreiben, Elternteil liest |
+| Kurzes strukturiertes Ergebnis | Rückgabemeldung |
+
+---
+
+## Arbeiten Sie mit uns
+
+Claudient wird unterstützt von [Uitbreiden](https://uitbreiden.com/) — wir entwickeln KI-Produkte mit Entwickler-Communities und liefern B2B-KI-Lösungen. Wenn Sie Multi-Agenten-Systeme, autonome Workflows oder Claude Code-Orchestrierung in Produktionsqualität entwerfen — wir haben das in der Produktion gebaut und können Ihnen helfen.
+
+**[uitbreiden.com](https://uitbreiden.com/)**

package/guides/de/getting-started.md

@@ -0,0 +1,164 @@
+# Erste Schritte mit Claudient
+
+Dieser Leitfaden bringt Sie in weniger als 10 Minuten von null zu einer funktionierenden Claude Code-Umgebung mit Ihrer ersten Skill, Ihrem ersten Agenten und Ihrem ersten Hook.
+
+---
+
+## Voraussetzungen
+
+- [Claude Code](https://claude.ai/code) installiert und authentifiziert
+- Ein Projektverzeichnis, an dem Sie aktiv arbeiten
+
+---
+
+## Schritt 1 — Claudient klonen
+
+```bash
+git clone https://github.com/Claudient/Claudient.git ~/Claudient
+```
+
+Sie haben jetzt die vollständige Bibliothek lokal. Es wird nichts automatisch ausgeführt — Sie wählen aus, was Sie benötigen.
+
+---
+
+## Schritt 2 — Das `.claude/`-Verzeichnis Ihres Projekts einrichten
+
+Claude Code sucht nach Konfiguration in `.claude/` im Projektstammverzeichnis.
+
+```bash
+mkdir -p your-project/.claude/skills
+mkdir -p your-project/.claude/hooks
+```
+
+Ihre Projektstruktur sollte wie folgt aussehen:
+
+```
+your-project/
+├── .claude/
+│   ├── skills/        ← Skills kommen hierher (aktueller Standard)
+│   ├── hooks/         ← Hook-Skripte kommen hierher
+│   └── settings.json  ← Hook-Konfiguration kommt hierher
+├── CLAUDE.md          ← Regeln kommen hierher
+└── src/
+```
+
+---
+
+## Schritt 3 — Ihre erste Skill hinzufügen
+
+Skills sind Slash-Befehle. Kopieren Sie eine beliebige `.md`-Datei aus `skills/` in `.claude/skills/`:
+
+```bash
+# Beispiel: FastAPI-Skill hinzufügen
+cp ~/Claudient/skills/backend/python/fastapi.md your-project/.claude/skills/
+```
+
+Öffnen Sie jetzt Claude Code in Ihrem Projekt und tippen Sie `/fastapi` — die Skill wird aktiviert.
+
+> **Hinweis:** `.claude/commands/` funktioniert weiterhin (veralteter Pfad), aber `.claude/skills/` ist der aktuelle Standard. Wenn beide existieren, haben Skills Vorrang.
+
+**So wählen Sie eine Skill aus:**
+- Durchsuchen Sie `skills/` nach Kategorie
+- Lesen Sie den Abschnitt "When to activate" am Anfang jeder Datei
+- Wenn sie zu Ihrer aktuellen Aufgabe passt, kopieren Sie sie hinein
+
+---
+
+## Schritt 4 — Eine Regel hinzufügen
+
+Regeln befinden sich in `CLAUDE.md` im Projektstammverzeichnis. Claude liest diese Datei zu Beginn jeder Sitzung.
+
+```bash
+# Einen gemeinsamen Regelsatz in die CLAUDE.md Ihres Projekts kopieren
+cat ~/Claudient/rules/common/coding-style.md >> your-project/CLAUDE.md
+```
+
+Oder öffnen Sie `rules/common/` und kopieren Sie manuell die für Ihr Projekt relevanten Abschnitte.
+
+---
+
+## Schritt 5 — Ihren ersten Hook hinzufügen
+
+Hooks werden automatisch bei Claude Code-Ereignissen ausgeführt. Sie befinden sich in `.claude/settings.json`.
+
+Erstellen oder öffnen Sie `.claude/settings.json` in Ihrem Projekt:
+
+```json
+{
+  "hooks": {}
+}
+```
+
+Kopieren Sie einen Hook aus `hooks/` — jede Hook-Datei enthält das genaue JSON zum Einfügen. Zum Beispiel der Kostenverfolgung-Hook:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cost-tracker.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Dann kopieren Sie das zugehörige Skript:
+
+```bash
+cp ~/Claudient/hooks/lifecycle/cost-tracker.sh your-project/.claude/hooks/
+chmod +x your-project/.claude/hooks/cost-tracker.sh
+```
+
+---
+
+## Schritt 6 — (Optional) Einen Agenten hinzufügen
+
+Agenten sind Unter-Agenten-Definitionen, die Sie in Ihren Claude-Sitzungen referenzieren. Sie erfordern kein Kopieren von Dateien — Sie rufen sie über `subagent_type` in einem Agent-Tool-Aufruf auf.
+
+Durchsuchen Sie `agents/`, um zu verstehen, was verfügbar ist. Wenn Sie möchten, dass Claude eine Aufgabe an einen Spezialisten delegiert (z.B. einen Sicherheitsprüfer, einen Datenbankspezialisten), referenzieren Sie die Agentendefinition, um zu verstehen, was er erwartet und was er zurückgibt.
+
+---
+
+## Was als nächstes zu tun ist
+
+| Ziel | Wo nachschlagen |
+|---|---|
+| Eine eigene Skill schreiben | [guides/skill-authoring.md](skill-authoring.md) |
+| Token-Kosten reduzieren | [guides/token-optimization.md](token-optimization.md) |
+| Speicher und Sitzungszustand verstehen | [guides/memory-management.md](memory-management.md) |
+| Claude Code-Setup absichern | [guides/security.md](security.md) |
+| Mehrstufige automatisierte Workflows erstellen | [guides/agent-orchestration.md](agent-orchestration.md) |
+| Qualität mit Hooks automatisieren | [guides/hooks-cookbook.md](hooks-cookbook.md) |
+
+---
+
+## Fehlerbehebung
+
+**Skill erscheint nicht als Slash-Befehl**
+— Prüfen Sie, ob die Datei in `.claude/skills/` ist (oder `.claude/commands/` für den alten Pfad)
+— Prüfen Sie, ob die Dateiendung `.md` ist
+— Starten Sie Claude Code neu
+
+**Hook wird nicht ausgelöst**
+— Überprüfen Sie, ob der Ereignisname exakt übereinstimmt: `PreToolUse`, `PostToolUse`, `PreCompact`, `Notification`
+— Prüfen Sie, ob der Skriptpfad relativ zum Projektstamm ist
+— Prüfen Sie, ob das Skript ausführbar ist (`chmod +x`)
+
+**CLAUDE.md wird nicht gelesen**
+— Sie muss im Projektstammverzeichnis liegen (auf gleicher Ebene wie `src/`, `package.json`, etc.)
+— Starten Sie die Claude Code-Sitzung nach dem Bearbeiten neu
+
+---
+
+## Arbeiten Sie mit uns
+
+Claudient wird unterstützt von [Uitbreiden](https://uitbreiden.com/) — wir entwickeln KI-Produkte mit Entwickler-Communities und liefern B2B-KI-Lösungen. Wenn Sie etwas Ernsthaftes mit Claude Code aufbauen und Expertenunterstützung, einen technischen Partner oder einfach Teil der Community sein möchten — kommen Sie zu uns.
+
+**[uitbreiden.com](https://uitbreiden.com/)**