claudient 0.1.0

package/guides/fr/agent-orchestration.md

@@ -0,0 +1,174 @@
+# Guide d'orchestration des agents
+
+Comment déléguer, paralléliser et spécialiser le travail avec le système de sous-agents de Claude Code.
+
+---
+
+## Ce que sont les sous-agents
+
+Un sous-agent est une instance Claude séparée lancée par la session parente pour gérer une tâche spécifique et délimitée. Il obtient :
+- Une fenêtre de contexte fraîche (pas d'historique de session)
+- Un sous-ensemble d'outils spécifique (si configuré)
+- Une sélection de modèle (peut différer du parent)
+- Un prompt que vous écrivez explicitement
+
+Les sous-agents ne sont pas magiques — ce sont des outils spécifiques pour des problèmes spécifiques.
+
+---
+
+## Quand utiliser un sous-agent
+
+Utilisez un sous-agent quand la tâche a des **entrées claires** et des **sorties claires** et est **indépendante de l'état de session actuel**.
+
+**Bons candidats :**
+- Réviser 10 fichiers pour des problèmes de sécurité
+- Effectuer une recherche spécifique dans le code pour localiser un pattern
+- Générer du code standard pour un nouveau module selon une spécification
+- Analyser un fichier journal et retourner un résumé
+
+**Mauvais candidats :**
+- Tâches nécessitant le contexte complet de la session
+- Tâches nécessitant des échanges — les sous-agents sont en une seule passe
+- Tâches où le coût de lancement dépasse le travail lui-même
+
+---
+
+## 1. Pattern de délégation
+
+La session parente identifie une tâche délimitée et la confie au sous-agent.
+
+**Règle clé :** Le prompt du sous-agent doit être autonome. Il n'a pas accès à ce que la session parente a fait. Briefez-le comme un collègue qui vient d'entrer dans la pièce.
+
+**Ce qu'il faut inclure dans le prompt du sous-agent :**
+- Ce que vous essayez d'accomplir et pourquoi
+- Les fichiers ou répertoires spécifiques à examiner
+- Le format de résultat souhaité
+- Les contraintes ou décisions déjà prises
+
+---
+
+## 2. Pattern de parallélisation
+
+Plusieurs sous-agents s'exécutant simultanément sur des tâches indépendantes.
+
+**Quand paralléliser :**
+- La même opération doit être appliquée à de nombreux fichiers/modules
+- Deux tâches genuinement indépendantes doivent toutes deux être complétées
+- Des tâches de recherche couvrant différentes zones simultanément
+
+**Utiliser git worktrees pour des modifications de code parallèles :**
+```bash
+git worktree add ../feature-branch-a feature-a
+git worktree add ../feature-branch-b feature-b
+```
+
+**Anti-patterns de parallélisation :**
+- Paralléliser des tâches qui partagent l'état (conflit d'écriture)
+- Tâches parallèles où l'une dépend de la sortie de l'autre
+
+---
+
+## 3. Pattern de spécialisation (cavecrew)
+
+Adaptez le modèle et les outils du sous-agent à la nature de la tâche. Inspiré du pattern **cavecrew** (source : [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)) — économise ~60% de tokens par rapport à l'utilisation d'Opus pour chaque sous-agent.
+
+| Rôle | Modèle | Outils | Utiliser quand |
+|---|---|---|---|
+| Investigateur | Haiku 4.5 | Read, Bash (grep/find seulement) | Localiser des choses dans le code — lecture seule, rapide |
+| Constructeur | Sonnet 4.6 | Read, Edit, Write, Bash | Modifications chirurgicales 1–2 fichiers |
+| Réviseur | Haiku 4.5 | Read | Réviser un diff ou un ensemble de fichiers |
+| Orchestrateur | Opus 4.7 | Tous | Coordination multi-étapes complexe, décisions d'architecture |
+
+---
+
+## 4. Pattern de transfert de contexte
+
+Quand une session a accumulé un contexte significatif et que vous devez transférer le travail à un nouvel agent.
+
+**Structure du prompt de transfert :**
+```
+## Context
+[Ce que fait ce projet, brièvement]
+[Sur quoi nous travaillions]
+[Décisions prises pendant cette session]
+
+## Files modified
+[Liste avec la raison de chaque modification]
+
+## Current state
+[Ce qui est fait, pas fait, ce qui bloque]
+
+## Your task
+[Tâche spécifique et délimitée pour le nouvel agent]
+
+## Constraints
+[Décisions prises qui ne doivent pas être remises en question]
+```
+
+---
+
+## 5. Dépendances fortes vs faibles
+
+**Dépendance forte :** La tâche échoue explicitement sans la configuration en amont.
+- Signalez cela explicitement : "Cette compétence nécessite une configuration — exécutez `/setup` d'abord."
+
+**Dépendance faible :** La tâche fonctionne mais produit une sortie de moindre qualité sans la configuration.
+- Ne bloquez pas. Dégradez gracieusement et notez l'écart.
+
+---
+
+## 6. Contrôle de portée pour les sous-agents
+
+Chaque sous-agent doit avoir une limite de portée explicite.
+
+**À inclure dans chaque prompt de sous-agent :**
+```
+## Scope
+- Read: yes
+- Write/Edit: [fichiers spécifiques seulement OU non]
+- Shell commands: [commandes spécifiques autorisées OU aucune]
+- Network: [oui/non]
+
+## Do not
+- Do not modify files outside [directory]
+- Do not make git commits
+- Do not install packages
+```
+
+---
+
+## 7. Retourner les résultats des sous-agents
+
+**Préférez les fichiers pour :**
+- Listes de résultats sur lesquelles le parent va itérer
+- Code généré que le parent va réviser
+- Rapports référencés plusieurs fois
+
+**Préférez les messages de retour pour :**
+- Réponses oui/non simples
+- Données structurées courtes
+- Rapports de statut
+
+---
+
+## Référence rapide
+
+| Objectif | Pattern |
+|---|---|
+| Tâche délimitée et autonome | Délégation |
+| Même tâche sur plusieurs fichiers | Parallélisation |
+| Recherche/localisation lecture seule | Investigateur (Haiku) |
+| Modification de code chirurgicale | Constructeur (Sonnet) |
+| Révision de diff/fichier | Réviseur (Haiku) |
+| Coordination multi-étapes complexe | Orchestrateur (Opus) |
+| Transfert de session | Pattern de transfert de contexte |
+| Grande sortie de sous-agent | Écrire dans un fichier, le parent le lit |
+| Résultat structuré court | Message de retour |
+
+---
+
+## Travaillez avec nous
+
+Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA avec des communautés de développeurs et livrons des solutions IA B2B. Si vous concevez des systèmes multi-agents, des workflows autonomes ou une orchestration Claude Code de qualité production — nous l'avons construit en production et pouvons vous aider.
+
+**[uitbreiden.com](https://uitbreiden.com/)**

package/guides/fr/getting-started.md

@@ -0,0 +1,164 @@
+# Premiers pas avec Claudient
+
+Ce guide vous amène de zéro à un environnement Claude Code fonctionnel avec votre première compétence, votre premier agent et votre premier hook — en moins de 10 minutes.
+
+---
+
+## Prérequis
+
+- [Claude Code](https://claude.ai/code) installé et authentifié
+- Un répertoire de projet sur lequel vous travaillez activement
+
+---
+
+## Étape 1 — Cloner Claudient
+
+```bash
+git clone https://github.com/Claudient/Claudient.git ~/Claudient
+```
+
+Vous disposez maintenant de la bibliothèque complète en local. Rien ne s'exécute automatiquement — vous choisissez ce dont vous avez besoin.
+
+---
+
+## Étape 2 — Configurer le répertoire `.claude/` de votre projet
+
+Claude Code recherche la configuration dans `.claude/` à la racine de votre projet.
+
+```bash
+mkdir -p your-project/.claude/skills
+mkdir -p your-project/.claude/hooks
+```
+
+La structure de votre projet devrait ressembler à ceci :
+
+```
+your-project/
+├── .claude/
+│   ├── skills/        ← les compétences vont ici (standard actuel)
+│   ├── hooks/         ← les scripts de hooks vont ici
+│   └── settings.json  ← la configuration des hooks va ici
+├── CLAUDE.md          ← les règles vont ici
+└── src/
+```
+
+---
+
+## Étape 3 — Ajouter votre première compétence
+
+Les compétences sont des commandes slash. Copiez n'importe quel fichier `.md` depuis `skills/` dans `.claude/skills/` :
+
+```bash
+# Exemple : ajouter la compétence FastAPI
+cp ~/Claudient/skills/backend/python/fastapi.md your-project/.claude/skills/
+```
+
+Ouvrez maintenant Claude Code dans votre projet et tapez `/fastapi` — la compétence s'active.
+
+> **Note :** `.claude/commands/` fonctionne toujours (chemin hérité) mais `.claude/skills/` est le standard actuel. Quand les deux existent, les compétences ont la priorité.
+
+**Comment choisir une compétence :**
+- Parcourez `skills/` par catégorie
+- Lisez la section "When to activate" en haut de chaque fichier
+- Si elle correspond à votre tâche actuelle, copiez-la
+
+---
+
+## Étape 4 — Ajouter une règle
+
+Les règles se trouvent dans `CLAUDE.md` à la racine de votre projet. Claude lit ce fichier au début de chaque session.
+
+```bash
+# Copier un ensemble de règles communes dans le CLAUDE.md de votre projet
+cat ~/Claudient/rules/common/coding-style.md >> your-project/CLAUDE.md
+```
+
+Ou ouvrez `rules/common/` et copiez manuellement les sections pertinentes pour votre projet.
+
+---
+
+## Étape 5 — Ajouter votre premier hook
+
+Les hooks s'exécutent automatiquement sur les événements Claude Code. Ils résident dans `.claude/settings.json`.
+
+Créez ou ouvrez `.claude/settings.json` dans votre projet :
+
+```json
+{
+  "hooks": {}
+}
+```
+
+Copiez un hook depuis `hooks/` — chaque fichier hook contient le JSON exact à coller. Par exemple, le hook de suivi des coûts :
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cost-tracker.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Puis copiez le script correspondant :
+
+```bash
+cp ~/Claudient/hooks/lifecycle/cost-tracker.sh your-project/.claude/hooks/
+chmod +x your-project/.claude/hooks/cost-tracker.sh
+```
+
+---
+
+## Étape 6 — (Optionnel) Ajouter un agent
+
+Les agents sont des définitions de sous-agents que vous référencez dans vos sessions Claude. Ils ne nécessitent pas de copie de fichier — vous les appelez par `subagent_type` dans un appel à l'outil Agent.
+
+Parcourez `agents/` pour comprendre ce qui est disponible. Quand vous souhaitez que Claude délègue une tâche à un spécialiste (par exemple, un réviseur de sécurité, un spécialiste base de données), référencez la définition de l'agent pour comprendre ce qu'il attend et ce qu'il retourne.
+
+---
+
+## Que faire ensuite
+
+| Objectif | Où chercher |
+|---|---|
+| Écrire votre propre compétence | [guides/skill-authoring.md](skill-authoring.md) |
+| Réduire les coûts en tokens | [guides/token-optimization.md](token-optimization.md) |
+| Comprendre la mémoire et l'état de session | [guides/memory-management.md](memory-management.md) |
+| Sécuriser votre configuration Claude Code | [guides/security.md](security.md) |
+| Construire des workflows automatisés multi-étapes | [guides/agent-orchestration.md](agent-orchestration.md) |
+| Automatiser la qualité avec les hooks | [guides/hooks-cookbook.md](hooks-cookbook.md) |
+
+---
+
+## Dépannage
+
+**La compétence n'apparaît pas comme commande slash**
+— Vérifiez que le fichier est dans `.claude/skills/` (ou `.claude/commands/` pour l'ancien chemin)
+— Vérifiez que l'extension du fichier est `.md`
+— Redémarrez Claude Code
+
+**Le hook ne se déclenche pas**
+— Vérifiez que le nom de l'événement correspond exactement : `PreToolUse`, `PostToolUse`, `PreCompact`, `Notification`
+— Vérifiez que le chemin du script est relatif à la racine du projet
+— Vérifiez que le script est exécutable (`chmod +x`)
+
+**CLAUDE.md n'est pas lu**
+— Il doit se trouver à la racine du projet (au même niveau que `src/`, `package.json`, etc.)
+— Redémarrez la session Claude Code après l'avoir modifié
+
+---
+
+## Travaillez avec nous
+
+Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA avec des communautés de développeurs et livrons des solutions IA B2B. Si vous construisez quelque chose de sérieux avec Claude Code et souhaitez une aide experte, un partenaire technique, ou simplement faire partie de la communauté — venez nous trouver.
+
+**[uitbreiden.com](https://uitbreiden.com/)**

package/guides/fr/hooks-cookbook.md

@@ -0,0 +1,227 @@
+# Livre de recettes des hooks
+
+Patterns de hooks réels et prêts à l'emploi pour automatiser la qualité, la sécurité et l'observabilité dans Claude Code.
+
+---
+
+## Fondamentaux des hooks
+
+Les hooks sont des scripts shell ou des commandes que Claude Code exécute automatiquement en réponse à des événements. Ils s'exécutent en dehors du contexte de Claude — ce sont de vrais processus shell, pas des instructions Claude.
+
+**Événements de hook :**
+| Événement | Quand il se déclenche |
+|---|---|
+| `SessionStart` | Quand une session Claude Code commence |
+| `PreToolUse` | Avant l'exécution de tout appel d'outil |
+| `PostToolUse` | Après la fin d'un appel d'outil |
+| `PreCompact` | Avant le déclenchement de la compaction de contexte |
+| `PostCompact` | Après la compaction de contexte |
+| `Stop` | Quand Claude finit de répondre |
+| `Notification` | Quand Claude envoie une notification bureau |
+
+**Structure de base d'un hook :**
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolName",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/votre-script.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Codes de sortie :** `0` = autoriser, `1` = avertir (Claude voit la sortie mais continue), `2` = bloquer (l'appel d'outil est annulé).
+
+---
+
+## Recette 1 — Auto-formatage Prettier à l'écriture
+
+Formate automatiquement les fichiers après que Claude les écrit ou les modifie.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --write ${tool_input.file_path}",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Recette 2 — Bloquer les commandes shell dangereuses
+
+**.claude/hooks/block-dangerous.sh :**
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))")
+
+BLOCKED_PATTERNS=("rm -rf" "sudo " "| bash" "| sh" "git push --force" "git reset --hard")
+
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qi "$pattern"; then
+    echo "BLOQUÉ : la commande correspond au pattern dangereux '$pattern'" >&2
+    exit 2
+  fi
+done
+
+exit 0
+```
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh", "timeout": 5 }]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Recette 3 — Journal d'audit pour chaque appel d'outil
+
+**.claude/hooks/audit-log.sh :**
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name','unknown'))" 2>/dev/null)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+LOG_FILE="${CLAUDE_PROJECT_DIR}/.claude/logs/audit.log"
+mkdir -p "$(dirname "$LOG_FILE")"
+echo "${TIMESTAMP} | ${TOOL_NAME}" >> "$LOG_FILE"
+```
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-log.sh", "async": true }] }
+    ]
+  }
+}
+```
+
+---
+
+## Recette 4 — Sauvegarde de session avant compaction
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-compact-save.sh" }] }
+    ]
+  }
+}
+```
+
+Associez avec une instruction CLAUDE.md : "Quand PreCompact se déclenche, résumez : tâche actuelle, fichiers modifiés, décisions ouvertes, prochaines étapes — ajoutez à `.claude/memory/session-state.md`."
+
+---
+
+## Recette 5 — Suivi des coûts
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cost-tracker.sh", "async": true }] }
+    ]
+  }
+}
+```
+
+---
+
+## Recette 6 — Vérification de types TypeScript à l'édition
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "bash -c 'echo \"${tool_input.file_path}\" | grep -q \"\\.tsx\\?$\" && npx tsc --noEmit 2>&1 | head -20 || true'", "async": false, "timeout": 30 }]
+      }
+    ]
+  }
+}
+```
+
+Définissez `async: false` pour que Claude voie les erreurs de types et puisse les corriger immédiatement.
+
+---
+
+## Recette 7 — Rappel avant git push
+
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))" 2>/dev/null)
+if echo "$COMMAND" | grep -q "git push"; then
+  echo "⚠️  Sur le point de pousser vers le distant. Confirmez que c'est intentionnel." >&2
+  exit 1
+fi
+exit 0
+```
+
+---
+
+## Recette 8 — Chargeur de contexte au démarrage de session
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh" }] }
+    ]
+  }
+}
+```
+
+---
+
+## Dépannage des hooks
+
+**Le hook ne se déclenche pas :**
+- Vérifiez que le nom de l'événement est exact : `PreToolUse`, `PostToolUse`, `SessionStart`, `PreCompact`
+- Vérifiez que le script est exécutable : `chmod +x .claude/hooks/votre-script.sh`
+- Vérifiez que le chemin utilise correctement `${CLAUDE_PROJECT_DIR}`
+
+**Tester un hook manuellement :**
+```bash
+echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | bash .claude/hooks/votre-script.sh
+```
+
+---
+
+## Travaillez avec nous
+
+Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA avec des communautés de développeurs et livrons des solutions IA B2B. Si vous avez besoin de systèmes de hooks personnalisés, de portes qualité automatisées ou d'automatisation Claude Code de qualité production pour votre équipe — nous le construisons pour des clients.
+
+**[uitbreiden.com](https://uitbreiden.com/)**