Orchestration multi-agents avancée

# Séquentiel : chaque agent dépend du précédent
> Étape 1 : Utilise l'agent planner pour planifier le refactoring
> Étape 2 : Utilise l'agent tdd-guide pour implémenter selon le plan
> Étape 3 : Utilise l'agent code-reviewer pour valider le code
> Étape 4 : Utilise l'agent doc-updater pour mettre à jour la doc

# Parallèle : les agents travaillent en même temps
> Lance en parallèle :
> - Agent security-reviewer : audite le module auth
> - Agent code-reviewer : review le module API
> - Agent e2e-runner : teste le parcours utilisateur
> Puis synthétise les résultats des trois agents.

# Conceptuellement, Claude Code fait :
# 1. Lance 3 subagents en parallèle (run_in_background: true)
# 2. Attend que les 3 aient terminé
# 3. Consolide les résultats dans un rapport unique

# Pipeline complet de release
> Exécute ce pipeline :
>
> Phase 1 (parallèle) :
>   - Agent tdd-guide : vérifie que tous les tests passent
>   - Agent security-reviewer : audit de sécurité
>
> Phase 2 (séquentiel, après Phase 1) :
>   - Agent code-reviewer : review finale du code
>
> Phase 3 (parallèle, après Phase 2) :
>   - Agent doc-updater : mise à jour de la documentation
>   - Agent e2e-runner : tests end-to-end
>
> Phase 4 (séquentiel, après Phase 3) :
>   - Prépare le tag de release et le changelog

# Split-role : perspectives multiples sur un même problème
> Analyse cette PR sous 4 angles différents :
>
> Agent 1 (factuel) : Vérifie que le code fait ce que la PR dit
> Agent 2 (senior) : Évalue la qualité et la maintenabilité
> Agent 3 (sécurité) : Cherche les failles de sécurité
> Agent 4 (consistance) : Vérifie la cohérence avec le reste du codebase
>
> Puis synthétise les 4 analyses en un rapport consolidé.

# Stratégie 1 : Via les fichiers
L'agent A écrit ses résultats dans un fichier.
L'agent B lit ce fichier au début de sa mission.

# Stratégie 2 : Via le prompt
L'agent orchestrateur résume le résultat de l'agent A
et l'inclut dans le prompt de l'agent B.

# Stratégie 3 : Via Git
L'agent A commite ses changements.
L'agent B travaille sur la même branche et voit les modifications.

# Conceptuellement, Claude Code crée des worktrees isolés :

# Agent 1 travaille dans /tmp/worktree-security
git worktree add /tmp/worktree-security main

# Agent 2 travaille dans /tmp/worktree-tests
git worktree add /tmp/worktree-tests main

# Agent 3 travaille dans /tmp/worktree-docs
git worktree add /tmp/worktree-docs main

# Chaque agent modifie ses fichiers sans affecter les autres
# À la fin, les changements sont fusionnés

# Sans background : séquentiel forcé
# Agent A travaille... (60 secondes)
# Agent B travaille... (60 secondes)
# Total : 120 secondes

# Avec background : parallèle
# Agent A travaille en background... (60 secondes)
# Agent B travaille en background... (60 secondes)
# Total : 60 secondes (les deux en parallèle)

# BON : Résultats concis
"L'audit de sécurité a trouvé 3 problèmes :
1 CRITICAL (CSRF manquant), 2 MEDIUM (rate limiting)."

# MAUVAIS : Résultats verbeux
"J'ai analysé chaque fichier un par un. D'abord auth.ts,
qui contient 342 lignes de code. La ligne 42 est
intéressante parce que..." (500 lignes de rapport)

# MAUVAIS : Chevauchement
Agent 1 : "Review le code et vérifie la sécurité"
Agent 2 : "Vérifie la sécurité et la qualité du code"
# → Les deux font de la sécurité = duplication

# BON : Responsabilités distinctes
Agent 1 : "Review la qualité du code (lisibilité, patterns, tests)"
Agent 2 : "Audit de sécurité uniquement (injection, XSS, secrets)"
# → Chacun son domaine, pas de chevauchement

## Critères de succès pour l'agent de tests
- Tous les tests passent (exit code 0)
- Couverture de code > 80%
- Aucun test flaky (relancer 3 fois si un test échoue)
- Rapport de couverture généré dans /coverage

# Plan de fallback
Si l'agent security-reviewer trouve un problème CRITICAL :
  → Arrêter le pipeline
  → Notifier le développeur avec le détail du problème
  → Ne PAS continuer vers la review ou la release

Si l'agent e2e-runner échoue sur un test :
  → Relancer le test 2 fois (peut être un flaky test)
  → Si toujours en échec, signaler et continuer

> Exécute un pipeline de release pour la version 2.3.0 :
>
> 1. PLANIFICATION (séquentiel)
>    - Utilise l'agent planner pour lister tous les changements
>      depuis le dernier tag
>
> 2. VÉRIFICATIONS (parallèle)
>    - Agent tdd-guide : tous les tests passent, couverture 80%+
>    - Agent security-reviewer : audit de sécurité complet
>    - Agent refactor-cleaner : pas de code mort introduit
>
> 3. REVIEW (split-role)
>    - Perspective qualité : code propre et maintenable
>    - Perspective performance : pas de régressions
>    - Perspective consistance : cohérent avec le codebase
>
> 4. DOCUMENTATION (parallèle)
>    - Agent doc-updater : mise à jour de la doc technique
>    - Génère le changelog depuis le dernier tag
>
> 5. RELEASE (séquentiel)
>    - Si tout est vert : crée le tag v2.3.0
>    - Génère les release notes
>
> Si une étape CRITIQUE échoue, arrête tout et donne-moi
> un rapport détaillé du problème.

# Leader : l'agent orchestrateur
> Tu coordonnes 3 workers pour la feature "export CSV".
> Décompose la tâche et assigne chaque partie.

# Worker 1 : Backend
# → Implémente l'endpoint /api/export
# Worker 2 : Frontend
# → Ajoute le bouton d'export dans l'UI
# Worker 3 : Tests
# → Écrit les tests E2E du parcours export

# Agent Teams en mode peer-to-peer
# Chaque agent travaille et signale quand il a fini
# Les autres agents réagissent aux changements

# Agent développeur : code → signale "code prêt"
# Agent testeur : détecte "code prêt" → écrit les tests
# Agent reviewer : détecte "tests écrits" → review le tout

# .github/workflows/agent-review.yml
name: Agent Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Agent Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --print --max-turns 15 \
            "Fais une review complète de cette PR.
             Analyse le diff avec git diff origin/main...HEAD.
             Produis un rapport avec les problèmes par sévérité.
             Si tu trouves un CRITICAL, termine par EXIT_CODE=1."

# .gitlab-ci.yml
agent-security-audit:
  stage: review
  image: node:20-alpine
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude --print --max-turns 10 \
        "Audit de sécurité sur le diff de cette MR.
         Cherche : injections SQL, XSS, secrets en dur,
         dépendances vulnérables. Format JSON."
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

// scripts/ci-review.ts
import { claude } from "@anthropic-ai/claude-code-sdk";

async function ciReview() {
  // Phase 1 : Security
  const security = await claude({
    prompt: "Audit de sécurité du diff par rapport à main",
    options: { maxTurns: 10, allowedTools: ["Bash", "Read", "Grep"] },
  });

  // Phase 2 : Tests
  const tests = await claude({
    prompt: "Vérifie que la couverture de tests est > 80%",
    options: { maxTurns: 8, allowedTools: ["Bash", "Read"] },
  });

  // Résultat consolidé
  const hasCritical = security.text.includes("CRITICAL");
  const lowCoverage = tests.text.includes("< 80%");

  if (hasCritical || lowCoverage) {
    console.error("Review échouée :");
    if (hasCritical) console.error("- Problème de sécurité CRITICAL");
    if (lowCoverage) console.error("- Couverture insuffisante");
    process.exit(1);
  }

  console.log("Review OK");
}

ciReview();

# Pre-commit Quality Check

Tu es un reviewer de code rigoureux. Avant chaque commit, vérifie les points suivants.

## Étapes

1. Lance les tests : `npm test`
   - Si un test échoue, arrête-toi et explique le problème
2. Vérifie le lint : `npm run lint`
   - Liste les erreurs par fichier et sévérité
3. Vérifie les types TypeScript : `npm run type-check`
4. Analyse le diff (`git diff --staged`) et cherche :
   - Secrets ou tokens en dur
   - `console.log` oubliés
   - Imports non utilisés

## Format de sortie

Pour chaque problème trouvé :
- **Fichier** : chemin
- **Type** : TEST / LINT / TYPE / SECURITE
- **Sévérité** : BLOQUANT / AVERTISSEMENT
- **Description** : ce qui ne va pas

Si tout est propre : "Prêt à committer."

# Utilisation
/user:pre-commit

# Code Reviewer Agent

## Rôle
Tu es un reviewer de code senior. Tu travailles de manière autonome pour
vérifier la qualité du code avant commit. Tu peux corriger les problèmes
mineurs (lint auto-fixable, imports non utilisés) sans demander confirmation.

## Outils disponibles
- Bash (exécution de commandes)
- Read / Edit (lecture et correction de fichiers)
- Grep (recherche dans le code)

## Instructions

1. Récupère le diff staged : `git diff --staged`
2. Lance les tests : `npm test -- --passWithNoTests`
3. Lance le lint avec auto-fix : `npm run lint -- --fix`
4. Vérifie les types : `npm run type-check`
5. Cherche les patterns problématiques dans les fichiers modifiés :
   - Regex secrets : `(api_key|password|token)\s*=\s*['"][^'"]+['"]`
   - `console\.log` dans les fichiers non-test
6. Si des problèmes BLOQUANTS subsistent, liste-les avec leurs solutions.
   Sinon, confirme que le code est prêt.

## Contraintes
- Ne committe jamais toi-même
- Ne modifie que les fichiers déjà dans le diff staged
- Rapport concis : une ligne par problème maximum

# L'agent est invoqué automatiquement par Claude quand le contexte s'y prête,
# ou explicitement :
> Utilise l'agent code-reviewer sur le diff en cours

# Standards de qualité du projet

## Règles TypeScript

- Pas de `any` explicite. Utiliser `unknown` si le type est vraiment inconnu.
- Les interfaces préfixées `I` sont interdites (convention : `type` ou interface sans préfixe).
- Chaque fonction publique doit avoir une JSDoc minimale (description + `@param` + `@returns`).

## Règles de tests

- Couverture minimum : 80% sur les branches.
- Un fichier `utils/format.ts` doit avoir un fichier `utils/format.test.ts` correspondant.
- Les mocks sont dans `__mocks__/`, jamais inline dans les tests.

## Sécurité

- Aucune clé API ne doit apparaître dans le code (utiliser les variables d'environnement).
- Les endpoints API doivent valider leurs inputs avec Zod avant traitement.
- Pas de `dangerouslySetInnerHTML` sans revue explicite.

## Commit message

Format : `type(scope): description` (Conventional Commits).
Types valides : feat, fix, docs, chore, refactor, test, perf.

# Invocation directe pour un avis
/project:code-quality

# Ou utilisé comme référence dans un prompt d'agent
> En suivant les standards définis dans le skill code-quality,
> vérifie ce fichier : src/api/users.ts