Multi Agent Pipeline.fr

Pipeline multi-agents

Le cœur de WorkPilot AI est un pipeline d'agents qui coopèrent pour transformer une spec en code validé. Ce document explique précisément ce que chaque agent fait et comment ils s'articulent.

---

🗺 Vue d'ensemble

┌─────────────┐   ┌─────────┐   ┌──────────────┐   ┌──────────┐   ┌─────────────┐
│ Spec Review │──▶│ Planner │──▶│    Coder     │──▶│QA Review │──▶│  Prêt à     │
│  (humain)   │   │         │   │ (+ subagents)│   │          │   │  fusionner  │
└─────────────┘   └─────────┘   └──────────────┘   └──────────┘   └─────────────┘
                                                         │
                                                   échecs critères
                                                         │
                                                         ▼
                                                   ┌──────────┐
                                                   │ QA Fixer │───┐
                                                   └──────────┘   │
                                                         ▲        │
                                                         └────────┘
                                                    jusqu'à succès
                                                 ou 50 itérations max

Chaque étape est exécutée dans un worktree git isolé — votre branche principale est intouchée tant que vous n'approuvez pas la fusion.

---

1️⃣ Planner

Prompt : apps/backend/prompts/planner.md Rôle : transformer la spec en un plan d'implémentation exécutable.

Ce qu'il fait

1. Lit la spec complète (spec.md, requirements.json, context.json)
2. Évalue la complexité réelle vs. annoncée
3. Décompose en phases ordonnées avec dépendances
4. Identifie les sous-tâches parallélisables
5. Assigne un modèle et un budget de réflexion à chaque phase
6. Écrit implementation_plan.json

Sortie type

{
  "phases": [
    {
      "id": 1,
      "goal": "Créer le handler /health",
      "model": "claude-sonnet-4-6",
      "thinking_budget": 8000,
      "depends_on": [],
      "parallel": false
    },
    {
      "id": 2,
      "goal": "Écrire les tests unitaires et d'intégration",
      "model": "claude-sonnet-4-6",
      "thinking_budget": 5000,
      "depends_on": [1],
      "parallel": true,
      "subtasks": 2
    }
  ]
}

---

2️⃣ Coder

Prompt : apps/backend/prompts/coder.md (+ coder_recovery.md) Rôle : implémenter chaque phase du plan.

Ce qu'il fait

1. Charge le contexte de la phase courante (fichiers, historique mémoire)
2. Génère le code (création, modification, suppression)
3. Exécute les commandes build/test dans le worktree
4. En cas d'erreur, récupère automatiquement (script coder_recovery.md)
5. Peut spawner des sous-agents parallèles pour les tâches indépendantes
6. Commit à chaque fin de phase avec un message sémantique

Sous-agents parallèles

Exemple : la phase « générer les tests » peut lancer 3 sous-agents :

• Un pour les tests unitaires
• Un pour les tests d'intégration
• Un pour les tests E2E

Le Coder principal consolide ensuite les résultats.

Outils typiques

• read_file, edit_file, create_file, delete_file
• bash (allowlist dynamique)
• semantic_search (via grepai)
• run_tests, run_build

---

3️⃣ QA Reviewer

Prompt : apps/backend/prompts/qa_reviewer.md Rôle : valider que l'implémentation satisfait tous les critères d'acceptation.

Ce qu'il fait

1. Lit les critères d'acceptation de la spec
2. Un par un, vérifie chaque critère :
   • Exécute les tests appropriés
   • Inspecte les fichiers modifiés
   • Teste les endpoints / features manuellement via outils
3. Écrit un rapport détaillé (qa_report.md)
4. Si tout passe → statut APPROVED
5. Sinon → génère un QA_FIX_REQUEST.md listant les problèmes

Types de vérifications

Type	Outil
Tests unitaires	pytest, vitest, jest
Tests d'intégration	Commandes du projet
Tests E2E	Playwright, Cypress, Electron MCP
Lint / Typecheck	biome, ruff, tsc, eslint
Comportement fonctionnel	Curl, Chrome DevTools MCP
Accessibilité	Axe-core via MCP

---

4️⃣ QA Fixer

Prompt : apps/backend/prompts/qa_fixer.md Rôle : corriger les problèmes listés par le QA Reviewer.

Ce qu'il fait

1. Lit QA_FIX_REQUEST.md et le rapport
2. Isole chaque problème
3. Applique un correctif minimal ciblé
4. Relance la batterie de tests localement
5. Rend la main au QA Reviewer qui vérifie à nouveau

Boucle de validation

QA Reviewer ──► APPROVED? ──[oui]──► FIN
                   │
                  [non]
                   ▼
              QA Fixer ──► Retour au Reviewer
              
Maximum : 50 itérations

Si le max est atteint → la tâche passe en Human Review avec un rapport détaillé : souvent le signe d'un critère d'acceptation mal spécifié.

---

🔁 Interruptions et reprises

Le pipeline est reprenable à tout moment :

• Chaque phase est checkpointée dans le spec directory
• Si le process est tué (crash, Ctrl+C, rate limit)…
• …il suffit de relancer : python run.py --spec 001 reprend au dernier checkpoint

Pour pauser intentionnellement :

touch .workpilot/specs/001-name/PAUSE
echo "Ajout de ma note" > .workpilot/specs/001-name/HUMAN_INPUT.md

---

🌐 Parallélisme

WorkPilot AI exploite le parallélisme à plusieurs niveaux :

Niveau	Parallélisme
Inter-specs	Plusieurs tâches peuvent tourner en parallèle (worktrees distincts)
Inter-phases	Les phases marquées parallel: true peuvent tourner en même temps
Intra-phase	Le Coder peut lancer jusqu'à max_workers=3 sous-agents par défaut
Inter-agents IA	Le Planner peut utiliser Opus, le Coder Sonnet, le QA Haiku…

Limite UI : 12 terminaux d'agents simultanés (configurable).

---

🎚 Contrôle des modèles par phase

Vous pouvez configurer un modèle et un budget de réflexion différents pour chaque type d'agent :

from phase_config import get_phase_model, get_phase_thinking_budget

model = get_phase_model(spec_dir, "coding", cli_model=None)
thinking = get_phase_thinking_budget(spec_dir, "coding", cli_thinking=None)

Cas d'usage : utiliser un modèle coûteux (Opus) uniquement pour la phase critique (QA Review sur feature complexe) et un modèle moins cher (Haiku) pour la génération de boilerplate.

---

🔀 Fusion finale

Une fois toute la boucle QA passée, l'utilisateur a trois options :

Action	Effet
Merge to main	Fusion sémantique du worktree dans la branche par défaut
Create PR	Pousse la branche sur le remote et crée une PR GitHub/GitLab
Discard	Supprime le worktree, rien n'est modifié sur main

Le moteur de fusion sémantique IA gère les conflits en comprenant l'intention de chaque changement (cf. apps/backend/merge/).

---

📊 Journalisation complète

Toutes les étapes sont tracées dans logs/workflow.log avec :

• Trace IDs pour corréler les événements d'une spec
• Durées par phase et par agent
• Consommation de tokens
• Commandes exécutées et leur retour
• Raisonnement (chain-of-thought) des agents

Le Workflow Logger permet aussi de voir les traces actives :

from core.workflow_logger import workflow_logger
active = workflow_logger.get_active_traces()

---

Prochaine étape

➡️ Agents spécialisés — Test Generator, Refactorer, Migration…