60 ans de science de la collaboration humaine, traduits en architecture multi-agents IA.
60 years of human collaboration science, translated into multi-agent AI architecture.
🇫🇷 Français
🇬🇧 English
KORAL est un framework open-source d'orchestration multi-agents implémenté sous forme de skills (slash commands) pour Claude Code. Il traduit 60 ans de recherche en science de la collaboration humaine en patterns d'architecture IA concrets et réutilisables.
L'idée fondatrice est simple : les mêmes principes qui rendent les équipes humaines performantes — rôles différenciés, coordination structurée, mémoire collective, feedback continu — s'appliquent directement aux systèmes multi-agents IA.
Le Bag of Agents Problem est la première cause d'échec des systèmes multi-agents en production. Il se manifeste quand on lance plusieurs agents IA sans structure de coordination :
❌ Bag of Agents (sans KORAL) ✅ Équipe coordonnée (avec KORAL)
Agent A ──?──> ??? Coordinator ──> Architect (Plant)
Agent B ──?──> ??? │──> Coder (Implementer)
Agent C ──?──> ??? │──> Reviewer (Monitor Evaluator)
Agent D ──?──> ??? └──> Tester (Completer-Finisher)
│
Pas de rôles définis Rôles Belbin assignés
Pas de coordination Topologie Orchestrator
Pas de mémoire Mémoire transactive (Wegner)
Pas de qualité Evaluator-Optimizer loop
Résultat : chaos Résultat : livrable cohérent
| Métrique | Valeur | Source |
|---|---|---|
| Gain multi-agents vs single-agent | +90.2% | Anthropic, 2024 |
| Taux d'échec des pilotes multi-agents en production | 40-87% | Gartner / McKinsey, 2024-2025 |
| Performance rôles spécifiés vs généraux | 58% vs 36% | Li et al., "Camel", 2023 |
| Marché agents IA 2025 | $7.84B | Grand View Research |
| Marché agents IA 2030 (projection) | $52.62B | Grand View Research |
| Corrélation QI moyen et intelligence collective | r=0.15 (FAIBLE) | Woolley & Malone, 2010 |
| Impact de la diversité sur la performance | >2x | Woolley & Malone, 2010 |
Conclusion : Le multi-agent est l'avenir, mais sans méthodologie rigoureuse, le taux d'échec est catastrophique. KORAL comble ce fossé en appliquant des théories scientifiques validées.
KORAL intègre 7 théories scientifiques majeures et les 6 composable patterns d'Anthropic dans une architecture cohérente. Chaque théorie a été traduite en protocole exécutable.
Bruce Tuckman a identifié que toute équipe passe par des phases prévisibles. KORAL reproduit ce cycle à chaque exécution :
TUCKMAN LIFECYCLE — Cycle de vie d'équipe KORAL
================================================
Phase 1 Phase 2 Phase 3 Phase 4
FORMING STORMING NORMING PERFORMING
┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│ Init │───────>│Diver-│───────>│Conver│───────>│ Execution│
│ │ │gence │ │gence │ │ │
└──────┘ └──────┘ └──────┘ └──────────┘
│ │ │ │
v v v v
Contexte Exploration Consensus Production
partagé, indépendante, sur le plan, selon topologie,
rôles Belbin, débat MAD, standards, circuit breaker,
mission devil's synthèse métriques agiles
prompt advocate
Phase Humaine Équivalent IA (KORAL)
───────────── ────────────────────
Forming Context loading + agent initialization
Storming Divergent exploration / MAD debate
Norming Plan synthesis + standard setting
Performing Topology execution (pipeline/parallel/orchestrator)
Adjourning Memory persistence + metrics + cleanup
Détail des phases dans KORAL :
| Phase | Action humaine | Action KORAL | Durée typique |
|---|---|---|---|
| Forming | Se connaître, comprendre le projet | Chargement du contexte, assignation des rôles Belbin, partage de la mission | ~10% du run |
| Storming | Désaccords productifs, exploration | Débat multi-agents (DMAD), propositions indépendantes, devil's advocate | ~20% du run |
| Norming | Convergence, standards | Synthèse des propositions, plan d'exécution, normes de qualité | ~15% du run |
| Performing | Production à plein régime | Exécution selon la topologie choisie, circuit breaker actif | ~45% du run |
| Adjourning | Rétrospective, dissolution | Sauvegarde mémoire, métriques, rapport final | ~10% du run |
Meredith Belbin a identifié 9 rôles complémentaires qui, combinés, forment une équipe haute performance. KORAL assigne un rôle Belbin à chaque agent, ce qui détermine son comportement, sa température et son style de prompt.
BELBIN TEAM ROLES — Rôles d'équipe Belbin dans KORAL
=====================================================
┌─────────────────────────────────────────────────────────────┐
│ THINKING ROLES │
│ (Rôles de réflexion) │
│ │
│ ┌──────────┐ ┌───────────────────┐ ┌──────────────┐ │
│ │ PLANT │ │ MONITOR EVALUATOR │ │ SPECIALIST │ │
│ │ (PL) │ │ (ME) │ │ (SP) │ │
│ │ Créatif │ │ Analytique │ │ Expert │ │
│ │ T: 0.9 │ │ T: 0.3 │ │ T: 0.4 │ │
│ └──────────┘ └───────────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ACTION ROLES │
│ (Rôles d'action) │
│ │
│ ┌──────────┐ ┌───────────────────┐ ┌──────────────┐ │
│ │ SHAPER │ │ IMPLEMENTER │ │ COMPLETER- │ │
│ │ (SH) │ │ (IMP) │ │ FINISHER(CF) │ │
│ │Challenger│ │ Pratique │ │ Qualité │ │
│ │ T: 0.7 │ │ T: 0.4 │ │ T: 0.2 │ │
│ └──────────┘ └───────────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ PEOPLE ROLES │
│ (Rôles sociaux) │
│ │
│ ┌──────────┐ ┌───────────────────┐ ┌──────────────┐ │
│ │COORDINA- │ │ RESOURCE │ │ TEAM WORKER │ │
│ │TOR (CO) │ │ INVESTIGATOR (RI) │ │ (TW) │ │
│ │Délègue │ │ Explorateur │ │ Intégrateur │ │
│ │ T: 0.5 │ │ T: 0.6 │ │ T: 0.5 │ │
│ └──────────┘ └───────────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
T = Température recommandée pour l'agent IA
Mapping complet Belbin → Comportement IA :
| Rôle Belbin | Code | Prompt comportemental | Température | Usage IA |
|---|---|---|---|---|
| Plant | PL | "Innovateur créatif. Pense hors des sentiers battus. Propose des solutions non conventionnelles." | 0.9-1.0 | Brainstorming, architecture, idéation |
| Monitor Evaluator | ME | "Analyste critique. Évalue objectivement. Applique des grilles de scoring. Identifie faiblesses et risques." | 0.2-0.4 | Review, QA, audit, évaluation |
| Shaper | SH | "Challenger. Pousse l'équipe à s'améliorer. Questionne chaque hypothèse. Joue le devil's advocate." | 0.6-0.8 | Challenge, stress-test, red team |
| Coordinator | CO | "Coordinateur. Délègue les tâches. Synthétise les outputs. Assure l'alignement avec la mission." | 0.4-0.6 | Orchestration, synthèse, direction |
| Implementer | IMP | "Implémenteur pratique. Transforme les idées en actions concrètes. Produit du code/contenu production-ready." | 0.3-0.5 | Développement, rédaction, exécution |
| Completer-Finisher | CF | "Gardien de la qualité. Vérifie chaque détail. Assure la complétude. Lance les validations finales." | 0.1-0.3 | Tests, vérification, polish final |
| Specialist | SP | "Expert de domaine. Fournit une connaissance technique approfondie. Référence des sources fiables." | 0.3-0.5 | Expertise pointue, recherche, analyse |
| Resource Investigator | RI | "Explorateur. Cherche des informations externes. Trouve des ressources. Apporte des perspectives nouvelles." | 0.5-0.7 | Recherche web, veille, benchmark |
| Team Worker | TW | "Intégrateur. Assure la cohérence entre tous les outputs. Lisse les conflits. Harmonise le travail." | 0.4-0.6 | Cohésion, relecture croisée, merge |
J. Richard Hackman a démontré que la performance d'une équipe dépend de 5 conditions fondamentales. KORAL les vérifie obligatoirement avant chaque exécution via un pre-flight checklist :
HACKMAN PRE-FLIGHT CHECKLIST — Checklist pré-vol KORAL
======================================================
╔═══════════════════════════════════════════════════════════════╗
║ CONDITION VÉRIFICATION KORAL RÉSULTAT ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ [?] 1. REAL TEAM Agents définis avec : ║
║ (Équipe réelle) - Nom et rôle clairs ║
║ - Frontières définies ║
║ - Interdépendances explicites ║
║ ║
║ [?] 2. COMPELLING Mission prompt incluant : ║
║ DIRECTION - Objectif unique et clair ║
║ (Direction) - Critères de succès ║
║ - Livrables mesurables ║
║ ║
║ [?] 3. ENABLING Chaque agent dispose de : ║
║ STRUCTURE - Outils appropriés à son rôle ║
║ (Structure) - Formats I/O définis ║
║ - Protocoles de handoff ║
║ ║
║ [?] 4. SUPPORTIVE Contexte disponible : ║
║ CONTEXT - Fichiers projet accessibles ║
║ (Contexte) - Connaissances domaine fournies ║
║ - Historique runs précédents ║
║ ║
║ [?] 5. EXPERT Coaching en place : ║
║ COACHING - Agent orchestrateur configuré ║
║ (Coaching) - Chemin d'escalade vers humain ║
║ - Mécanismes de feedback ║
║ ║
╚═══════════════════════════════════════════════════════════════╝
Si une condition échoue : ARRÊT. L'exécution ne démarre pas.
Anita Woolley et Thomas Malone ont découvert un facteur "c" d'intelligence collective, analogue au facteur "g" de l'intelligence individuelle. Leur découverte cruciale :
La corrélation entre le QI moyen des membres et la performance collective est seulement r=0.15 (FAIBLE). Ce qui compte vraiment, c'est la diversité des profils et la qualité de la coordination.
WOOLLEY FACTOR "c" — Diversité > Intelligence individuelle
===========================================================
Performance collective
^
| * Équipe diverse
| * (Belbin mixte)
| *
| *
| * * * * *
| * * * Équipe homogène
| * (même rôle x4)
| *
| *
+────────────────────────────────────> Diversité des rôles
Facteurs clés de l'intelligence collective :
┌──────────────────────────────────────────────┐
│ 1. Diversité des rôles (Belbin) 40% │
│ 2. Diversité cognitive (température) 30% │
│ 3. Contribution équilibrée 20% │
│ 4. Sensibilité sociale (écoute) 10% │
└──────────────────────────────────────────────┘
Application dans KORAL :
- Chaque équipe doit couvrir au minimum 3 catégories Belbin différentes (Coordination, Exécution, Revue)
- Les températures varient selon les rôles (0.1 à 1.0)
- Aucun agent ne peut produire plus de 40% de l'output final
- Le facteur "c" est calculé et affiché via
/koral-monitor metrics
Daniel Wegner a théorisé que les groupes développent un Transactive Memory System — un système distribué où chaque membre sait "qui sait quoi". KORAL implémente ce concept via trois types de mémoire persistante :
TRANSACTIVE MEMORY SYSTEM — "Qui sait quoi ?"
================================================
┌─────────────────────────────────────────────────────────┐
│ TMS ROUTING TABLE │
│ .koral/memory/tms-routing.json │
├─────────────────────────────────────────────────────────┤
│ │
│ Domaine Agents experts │
│ ───────── ────────────── │
│ authentication --> [architect, security-specialist] │
│ frontend --> [ui-developer, designer] │
│ database --> [data-engineer, architect] │
│ testing --> [qa-engineer, reviewer] │
│ compliance --> [compliance-officer, risk-assessor] │
│ │
└─────────────────────────────────────────────────────────┘
| | |
v v v
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ EPISODIC │ │ SEMANTIC │ │ PROCEDURAL │
│ MEMORY │ │ MEMORY │ │ MEMORY │
│ │ │ │ │ │
│ Ce qui s'est │ │ Ce que l'on │ │ Comment on fait │
│ passé │ │ sait │ │ les choses │
│ │ │ │ │ │
│ - Outcomes │ │ - Faits │ │ - SOPs │
│ - Erreurs │ │ - Entités │ │ - Workflows │
│ - Lecons │ │ - Domaines │ │ - Best practices │
│ │ │ │ │ │
│ .koral/ │ │ .koral/ │ │ .koral/ │
│ memory/ │ │ memory/ │ │ memory/ │
│ episodic/ │ │ semantic/ │ │ procedural/ │
└──────────────┘ └──────────────┘ └──────────────────┘
Cycle de vie de la mémoire :
- Au démarrage : interrogation des 3 types de mémoire pour enrichir le contexte
- Pendant l'exécution : les agents lisent et écrivent dans la mémoire
- En fin de run : sauvegarde automatique de la mémoire épisodique, optionnelle pour sémantique/procédurale
James D. Thompson a classifié 3 types d'interdépendance organisationnelle. KORAL utilise cette théorie pour sélectionner automatiquement la topologie d'agents optimale :
THOMPSON INTERDEPENDENCE --> TOPOLOGY SELECTION
================================================
1. POOLED (Mutualisée)
Tâches indépendantes, partagent le résultat final
Agent A ──┐
Agent B ──┼──> Agrégation ──> Output final
Agent C ──┘
--> Topologie: PARALLEL
2. SEQUENTIAL (Séquentielle)
Sortie de A = entrée de B
Agent A ──> Agent B ──> Agent C ──> Output final
--> Topologie: PIPELINE
3. RECIPROCAL (Réciproque)
Feedback bidirectionnel entre agents
Agent A <──> Orchestrator <──> Agent B
|
Agent C
--> Topologie: ORCHESTRATOR ou DEBATE
Matrice de décision automatique :
| Interdépendance | Complexité | Topologie sélectionnée |
|---|---|---|
| Pooled | Toute | Parallelization |
| Sequential | Simple | Prompt-Chaining |
| Sequential | Moyenne/Complexe | Pipeline |
| Reciprocal | Simple/Moyenne | Orchestrator-Workers |
| Reciprocal | Complexe | Orchestrator + Debate |
Irving Janis a montré que le groupthink (pensée de groupe) mène à des décisions catastrophiques. KORAL implémente le Diversified Multi-Agent Debate (DMAD) pour prévenir la convergence prématurée :
DMAD PROTOCOL — Débat Multi-Agents Diversifié
===============================================
Round 0: ANALYSE INDEPENDANTE
┌────────┐ ┌────────┐ ┌────────┐
│Agent A │ │Agent B │ │Agent C │ Aucune visibilité croisée
│proposal│ │proposal│ │proposal│
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
v v v
Round 1: CROSS-REVIEW
┌────────┐ ┌────────┐ ┌────────┐
│A revue │ │B revue │ │C revue │ Critique structurée :
│output B│ │output C│ │output A│ Forces / Faiblesses /
└────┬───┘ └────┬───┘ └────┬───┘ Angles morts
│ │ │
v v v
Round 2: DEVIL'S ADVOCATE
┌────────────────────────────────┐
│ Agent Shaper argue CONTRE │ Identifie la meilleure
│ le consensus émergent │ contre-position
└────────────────┬──────────────┘
│
v
Round 3: SYNTHESE
┌────────────────────────────────┐
│ Agent Coordinator synthétise │ Adresse les contre-arguments
│ position finale │ Note les incertitudes
└────────────────────────────────┘
Les 6 patterns fondamentaux décrits par Anthropic pour construire des systèmes agents. KORAL les combine selon la configuration choisie :
Pattern 1 : Context-Augmentation
┌───────────┐ ┌──────────┐ ┌───────────┐
│ Fichiers │────>│ │ │ │
│ projet │ │ Context │────>│ Agent │
│ │ │ Assembly │ │ │
│ Mémoire │────>│ │ │ │
│ TMS │ │ │ │ │
└───────────┘ └──────────┘ └───────────┘
Enrichit le prompt de l'agent avec le contexte pertinent (fichiers, mémoire, résultats de recherche) avant exécution. Toujours appliqué en première étape.
Pattern 2 : Prompt-Chaining
┌─────────┐ Gate ┌─────────┐ Gate ┌─────────┐
│ Agent 1 │───[>=7?]──>│ Agent 2 │───[>=7?]──>│ Agent 3 │
│ │ | │ │ | │ │
└─────────┘ |retry └─────────┘ |retry └─────────┘
v v
Pipeline séquentiel avec gate de qualité entre chaque étape. Si le score est inférieur au seuil, retry avant de passer au suivant.
Pattern 3 : Parallelization
┌─────────┐
┌───>│ Agent A │───┐
│ └─────────┘ │
Task─┤ ┌─────────┐ ├──> Agrégation
│───>│ Agent B │───│
│ └─────────┘ │
└───>┌─────────┐───┘
│ Agent C │
└─────────┘
Mode Sectioning : sous-tâches différentes
Mode Voting : même tâche, résultats agrégés
Pattern 4 : Routing
┌──────────────┐
┌───>│ Spécialiste A│
┌────────┐ │ └──────────────┘
│Routeur │──┤ ┌──────────────┐
│ (TMS) │──┼───>│ Spécialiste B│
└────────┘ │ └──────────────┘
└───>┌──────────────┐
│ Spécialiste C│
└──────────────┘
Classification et routage vers l'agent spécialiste approprié. Utilise le TMS (Wegner) pour les décisions de routage.
Pattern 5 : Evaluator-Optimizer
┌──────────────┐ ┌──────────────┐
│ Generator │────>│ Evaluator │
│ Agent │<────│ Agent │
└──────────────┘ └──────────────┘
(produit) feedback (score)
Rubrique d'évaluation :
┌───────────────┬────────┬────────────┐
│ Critère │ Poids │ Seuil │
├───────────────┼────────┼────────────┤
│ Complétude │ 25% │ │
│ Précision │ 25% │ Score │
│ Clarté │ 20% │ global │
│ Actionabilité │ 15% │ >= 7.0 │
│ Cohérence │ 15% │ │
└───────────────┴────────┴────────────┘
Max 3 itérations (configurable, cap à 5)
Pattern 6 : Orchestrator-Workers
┌────────────────────┐
│ ORCHESTRATOR │
│ (Coordinator CO) │
│ Model: opus │
└──────┬─────────────┘
│
┌──────────┼──────────┐
│ │ │
v v v
┌──────────┐┌──────────┐┌──────────┐
│ Worker A ││ Worker B ││ Worker C │
│ (IMP) ││ (SP) ││ (CF) │
│ sonnet ││ sonnet ││ sonnet │
└──────────┘└──────────┘└──────────┘
Un orchestrateur central décompose la tâche, délègue aux workers, supervise et synthétise.
# 1. Cloner le dépôt
git clone https://github.com/FelixMining/KORAL.git
# 2. Copier les skills dans votre projet
cp -r KORAL/.claude/skills/koral* votre-projet/.claude/skills/
# 3. C'est tout ! Utilisez /koral dans votre projet# Créer un symlink vers les skills KORAL
ln -s /chemin/vers/KORAL/.claude/skills/koral votre-projet/.claude/skills/koral
ln -s /chemin/vers/KORAL/.claude/skills/koral-team votre-projet/.claude/skills/koral-team
ln -s /chemin/vers/KORAL/.claude/skills/koral-run votre-projet/.claude/skills/koral-run
ln -s /chemin/vers/KORAL/.claude/skills/koral-monitor votre-projet/.claude/skills/koral-monitor
ln -s /chemin/vers/KORAL/.claude/skills/koral-memory votre-projet/.claude/skills/koral-memory# Ajouter comme submodule
git submodule add https://github.com/FelixMining/KORAL.git .koral-framework
# Copier les skills
cp -r .koral-framework/.claude/skills/koral* .claude/skills/Téléchargez le ZIP depuis GitHub et copiez le dossier .claude/skills/ dans votre projet.
# Vérifier que les skills sont en place
ls .claude/skills/koral*/SKILL.md
# Résultat attendu :
# .claude/skills/koral/SKILL.md
# .claude/skills/koral-memory/SKILL.md
# .claude/skills/koral-monitor/SKILL.md
# .claude/skills/koral-run/SKILL.md
# .claude/skills/koral-team/SKILL.md- Claude Code : L'outil CLI officiel d'Anthropic
- Un projet existant : KORAL s'installe dans n'importe quel projet
- Aucune autre dépendance requise
Tapez simplement /koral sans argument pour lancer l'assistant guidé :
> /koral
╔═══════════════════════════════════════════════════╗
║ ██╗ ██╗ ██████╗ ██████╗ █████╗ ██╗ ║
║ ██║ ██╔╝██╔═══██╗██╔══██╗██╔══██╗██║ ║
║ █████╔╝ ██║ ██║██████╔╝███████║██║ ║
║ ██╔═██╗ ██║ ██║██╔══██╗██╔══██║██║ ║
║ ██║ ██╗╚██████╔╝██║ ██║██║ ██║███████╗ ║
║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝ ║
║ ║
║ Kernel d'Organisation pour Réseaux ║
║ d'Agents Logiques ║
║ ║
║ v1.0.0 — by Felix Lenci ║
╚═══════════════════════════════════════════════════╝
[FR] Framework d'orchestration multi-agents prêt.
[EN] Multi-agent orchestration framework ready.
Puis répondez aux 6 QCM :
- Secteur : Dev / Marketing / Research / Finance / Custom
- Tâche : Description libre
- Complexité : Simple / Medium / Complex / Auto-detect
- Topologie : Pipeline / Parallel / Orchestrator / Debate / Auto (Thompson)
- HITL : Autonomous / Checkpoints / Supervised
- Qualité : Standard / Evaluator-Optimizer / MAD-DMAD
Tapez /koral suivi d'une description de tâche :
> /koral create a REST API with authentication, database, and tests
KORAL Quick Analysis:
Task: Create a REST API with authentication, database, and tests
Sector: Dev (auto-detected)
Complexity: Complex (3 sub-domains detected)
Topology: Orchestrator (reciprocal interdependence)
Team: Dev Squad (4 agents)
Quality: Evaluator-Optimizer
Launch with this config? (yes/no/modify)
# Étape 1 : Créer une équipe
> /koral-team create
# Étape 2 : Lancer un run avec cette équipe
> /koral-run my-custom-team Implement the user dashboard feature
# Étape 3 : Monitorer en temps réel
> /koral-monitor
# Étape 4 : Consulter la mémoire collective
> /koral-memory
La commande principale est le point d'entrée du framework. Elle offre deux modes :
Wizard Mode (sans argument) :
- Affiche le banner KORAL
- Liste les sous-commandes disponibles
- Guide l'utilisateur à travers 6 QCM interactifs
- Présente un résumé de configuration pour validation
- Lance l'initialisation et l'exécution
Quick Mode (avec argument) :
- Analyse automatique de la description de tâche
- Détection du secteur par mots-clés
- Estimation de la complexité par comptage des sous-tâches
- Sélection de topologie via Thompson
- Proposition d'équipe pré-configurée
- Validation rapide avant lancement
Les 6 étapes QCM :
| Étape | Question | Options | Logique si "Auto" |
|---|---|---|---|
| 1/6 | Secteur | Dev, Marketing, Research, Finance, Custom | Détection par mots-clés |
| 2/6 | Tâche | Texte libre | — |
| 3/6 | Complexité | Simple, Medium, Complex, Auto | Analyse sous-tâches et interdépendances |
| 4/6 | Topologie | Pipeline, Parallel, Orchestrator, Debate, Auto | Théorie de Thompson |
| 5/6 | HITL | Autonomous, Checkpoints, Supervised | Basé sur complexité |
| 6/6 | Qualité | Standard, Evaluator-Optimizer, MAD/DMAD | Basé sur enjeux |
Le Team Manager permet de créer, lister, modifier et supprimer des configurations d'équipes multi-agents.
Sous-commandes disponibles :
| Commande | Description |
|---|---|
/koral-team create |
Assistant de création d'équipe (7 étapes) |
/koral-team list |
Lister toutes les équipes configurées |
/koral-team show <name> |
Afficher les détails d'une équipe |
/koral-team edit <name> |
Modifier une équipe existante |
/koral-team delete <name> |
Supprimer une équipe (avec confirmation) |
/koral-team templates |
Afficher les 4 templates pré-configurés |
Schéma de configuration d'un agent (JSON) :
{
"name": "agent-name",
"role": "Role Description",
"belbin_role": "PL|ME|SH|CO|IMP|CF|SP|RI|TW",
"system_prompt_template": "You are a {role} with expertise in {specialties}...",
"model": "opus|sonnet|haiku",
"tools": ["Read", "Edit", "Write", "Bash", "Grep", "Glob"],
"temperature_profile": "creative|analytical|balanced",
"specialties": ["domain1", "domain2"],
"max_retries": 3,
"timeout_ms": 300000
}Schéma de configuration d'une équipe (JSON) :
{
"name": "team-name",
"description": "Team description",
"version": "1.0.0",
"created_at": "ISO-8601",
"updated_at": "ISO-8601",
"agents": [ /* ... agent configs ... */ ],
"topology": "pipeline|parallel|orchestrator|debate",
"quality_mode": "standard|evaluator-optimizer|mad",
"hitl_level": "autonomous|checkpoints|supervised",
"circuit_breaker": {
"max_retries": 3,
"timeout_ms": 300000,
"fallback": "degrade|skip|escalate"
},
"memory_config": {
"episodic": true,
"semantic": true,
"procedural": true
}
}Règles de validation :
- Minimum 2 agents par équipe
- Pas de noms d'agents en double
- Topologie compatible avec le nombre d'agents (Orchestrator >= 3 agents, etc.)
- Couverture des 3 fonctions critiques : Coordonner, Exécuter, Revoir
Le Runner est le moteur d'exécution multi-agents. Il pilote le cycle de vie complet Tuckman.
Modes d'invocation :
| Syntaxe | Comportement |
|---|---|
/koral-run dev-squad Implement auth |
Charge l'équipe + lance la tâche |
/koral-run dev-squad |
Charge l'équipe, demande la tâche |
/koral-run |
Liste les équipes, demande le choix |
Cycle d'exécution complet :
/koral-run
│
v
┌──────────────────────┐
│ Pre-flight Hackman │──> Échec ? STOP
│ (5 conditions) │
└──────────┬───────────┘
│
v
┌──────────────────────┐
│ FORMING │
│ - Run directory │
│ - Mission prompt │
│ - Agent prompts │
│ - Context loading │
└──────────┬───────────┘
│ [HITL checkpoint si level >= 1]
v
┌──────────────────────┐
│ STORMING │
│ - MAD/DMAD debate │
│ - Independent │
│ proposals │
└──────────┬───────────┘
│
v
┌──────────────────────┐
│ NORMING │
│ - Synthesis │
│ - Execution plan │
│ - Task assignment │
│ - Dependency graph │
└──────────┬───────────┘
│ [HITL checkpoint si level >= 1]
v
┌──────────────────────┐
│ PERFORMING │
│ - Topology exec │
│ - Circuit breaker │
│ - Quality gates │
│ - Progress tracking │
└──────────┬───────────┘
│
v
┌──────────────────────┐
│ ADJOURNING │
│ - Final QA │
│ - Synthesis │
│ - Metrics │
│ - Memory save │
└──────────────────────┘
Les 4 topologies d'exécution :
Pipeline (Sequential)
Agent 1 ──[gate]──> Agent 2 ──[gate]──> Agent 3 ──> Output
│ │ │
v v v
output/ output/ output/
agent-1.md agent-2.md agent-3.md
Usage : Traitement en chaîne, transformation progressive
Exemple : Data -> Analysis -> Report -> Review
Parallel (Independent)
┌──> Agent A ──> output-a.md ──┐
│ │
Task ┼──> Agent B ──> output-b.md ──┼──> Coordinator ──> Final
│ │ (merge)
└──> Agent C ──> output-c.md ──┘
Usage : Sous-tâches indépendantes, recherche multi-source
Exemple : 3 researchers analysent 3 sources différentes
Orchestrator-Workers
┌────────────────────┐
│ ORCHESTRATOR │
│ (opus / CO) │
└──┬─────┬─────┬────┘
│ │ │
assign │ │ │ assign
v v v
┌────┐┌────┐┌────┐
│W-A ││W-B ││W-C │
│ ││ ││ │
└──┬─┘└──┬─┘└──┬─┘
│ │ │
report │ │ │ report
v v v
┌────────────────────┐
│ ORCHESTRATOR │
│ (synthesize) │
└────────────────────┘
Usage : Tâches complexes avec coordination centralisée
Exemple : Feature development (architect + coder + reviewer + tester)
Debate (Adversarial)
Round 1: Propositions indépendantes
┌────────┐ ┌────────┐ ┌────────┐
│ Prop A │ │ Prop B │ │ Prop C │
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
Round 2: Critiques croisées
┌────────┐ ┌────────┐ ┌────────┐
│A crit B│ │B crit C│ │C crit A│
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
Round 3: Révisions
┌────────┐ ┌────────┐ ┌────────┐
│Rev. A │ │Rev. B │ │Rev. C │
└────┬───┘ └────┬───┘ └────┬───┘
└───────────┼───────────┘
v
Judgment: Monitor Evaluator sélectionne/hybride
┌──────────────────────────────┐
│ Meilleure solution ou │
│ hybride optimal │
└──────────────────────────────┘
Usage : Décisions critiques, exploration de solutions
Exemple : Architecture decision, strategy choice
Circuit breaker :
| Paramètre | Défaut | Description |
|---|---|---|
max_retries_per_agent |
3 | Tentatives avant abandon |
timeout_per_action_ms |
120000 | Timeout par action (2 min) |
fallback_strategy |
degrade_gracefully |
Continuer malgré l'échec |
error_propagation |
isolate |
L'échec d'un agent n'arrête pas les autres |
Niveaux HITL :
| Niveau | Comportement | Cas d'usage |
|---|---|---|
| 0 - Autonomous | Aucune interruption | Tâches récurrentes, low-risk |
| 1 - Checkpoints | Pause après Forming, Norming, Performing | Workflows standards |
| 2 - Supervised | Pause avant chaque agent | High-stakes, compliance |
Le Monitor fournit un tableau de bord temps réel pour suivre les exécutions.
Sous-commandes :
| Commande | Description |
|---|---|
/koral-monitor |
Statut du dernier run |
/koral-monitor latest |
Idem |
/koral-monitor <run-id> |
Statut d'un run spécifique |
/koral-monitor history |
Historique de tous les runs |
/koral-monitor metrics |
Métriques agrégées inter-runs |
Dashboard principal :
╔═══════════════════════════════════════════════════╗
║ KORAL MONITOR — Run: 2026-03-18_14-30-00 ║
╠═══════════════════════════════════════════════════╣
║ Team: dev-squad ║
║ Task: Implement authentication module... ║
║ Phase: PERFORMING (4/4) ║
║ Status: IN PROGRESS ║
╠═══════════════════════════════════════════════════╣
║ AGENTS ║
║ ├── architect COMPLETED ║
║ ├── coder RUNNING... ║
║ ├── reviewer PENDING ║
║ └── tester PENDING ║
╠═══════════════════════════════════════════════════╣
║ METRICS ║
║ ├── Elapsed: 3m 42s ║
║ ├── Agents completed: 1/4 (25%) ║
║ ├── Estimated remaining: ~8m ║
║ └── Circuit breaker: 0 triggers ║
╚═══════════════════════════════════════════════════╝
Métriques agrégées (/koral-monitor metrics) :
- Velocity : tâches complétées par run (moyenne)
- Defect Rate : agents en échec / total agents
- Cycle Time : durée moyenne des runs
- Success Rate : runs complétés / total runs
- Woolley Factor "c" : score de diversité de l'équipe (0.0-1.0)
Le système de mémoire implémente le Transactive Memory System de Wegner.
Sous-commandes :
| Commande | Description |
|---|---|
/koral-memory |
Vue d'ensemble de la mémoire |
/koral-memory show [type] |
Afficher le contenu (episodic/semantic/procedural) |
/koral-memory search <query> |
Rechercher dans toute la mémoire |
/koral-memory add <type> <content> |
Ajouter une entrée mémoire |
/koral-memory clear <type> |
Effacer un type de mémoire (avec confirmation) |
/koral-memory export |
Exporter toute la mémoire en markdown |
Les 3 types de mémoire :
| Type | Stocke | Fichiers | Utilité |
|---|---|---|---|
| Episodic | Ce qui s'est passé | [date]_[run-id]_[topic].md |
Apprendre des expériences passées |
| Semantic | Ce que l'on sait | [domain]_[topic].md |
Enrichir le contexte des futurs runs |
| Procedural | Comment on fait | [category]_[procedure].md |
Réutiliser les workflows efficaces |
Règles de maintenance automatique :
- Entrée > 30 jours → marquée
[POTENTIALLY STALE] - Confiance "low" → marquée
[NEEDS VALIDATION] - Taux de succès < 50% → marquée
[REVIEW NEEDED] - Détection de doublons à l'ajout
votre-projet/
├── .claude/
│ └── skills/
│ ├── koral/ # Commande principale /koral
│ │ └── SKILL.md
│ ├── koral-team/ # Gestion d'équipes /koral-team
│ │ └── SKILL.md
│ ├── koral-run/ # Exécution /koral-run
│ │ └── SKILL.md
│ ├── koral-monitor/ # Monitoring /koral-monitor
│ │ └── SKILL.md
│ └── koral-memory/ # Mémoire /koral-memory
│ └── SKILL.md
│
└── .koral/ # Données runtime (créé automatiquement)
├── config.json # Configuration globale
├── teams/ # Configurations d'équipes
│ ├── dev-squad.json
│ ├── marketing-crew.json
│ └── custom-team.json
├── memory/ # Système de mémoire transactive
│ ├── episodic/ # Expériences passées
│ ├── semantic/ # Connaissances validées
│ ├── procedural/ # Procédures éprouvées
│ └── tms-routing.json # Table de routage "qui sait quoi"
├── runs/ # Historique des exécutions
│ └── 2026-03-18_14-30-00/
│ ├── state.json # État du run
│ ├── plan.json # Plan d'exécution
│ ├── metrics.json # Métriques du run
│ ├── errors.json # Journal d'erreurs
│ ├── outputs/ # Sorties des agents
│ │ ├── architect.md
│ │ ├── coder.md
│ │ ├── reviewer.md
│ │ ├── tester.md
│ │ └── final.md
│ └── logs/ # Logs détaillés
└── templates/ # Templates personnalisés
KORAL EXECUTION FLOW — Flux d'exécution complet
================================================
Utilisateur
│
│ /koral [task] ou /koral (wizard)
v
┌────────────────────┐
│ MODE SELECTION │
│ ┌──────────────┐ │
│ │ Quick Mode │ │──> Analyse automatique
│ │ Wizard Mode │ │──> 6 QCM interactifs
│ └──────────────┘ │
└─────────┬──────────┘
│
v
┌────────────────────┐
│ INITIALIZATION │
│ │
│ - mkdir .koral/ │
│ - config.json │
│ - team.json │
│ - run directory │
│ - state.json │
└─────────┬──────────┘
│
v
┌────────────────────┐ ┌───────────────────┐
│ HACKMAN │──✗──> │ STOP + diagnostic │
│ PRE-FLIGHT │ └───────────────────┘
│ (5 conditions) │
└─────────┬──────────┘
│ ✓
v
┌────────────────────┐
│ TUCKMAN CYCLE │
│ │
│ Forming ────┐ │
│ Storming ───┤ │ ──> Circuit Breaker actif
│ Norming ────┤ │ ──> HITL aux checkpoints
│ Performing ─┤ │ ──> Mémoire TMS consultée
│ Adjourning ─┘ │ ──> Métriques collectées
│ │
└─────────┬──────────┘
│
v
┌────────────────────┐
│ OUTPUT │
│ │
│ - final.md │
│ - metrics.json │
│ - memory update │
│ - state: done │
└────────────────────┘
TOPOLOGY 1: PIPELINE
====================
Interdépendance: Sequential (Thompson)
Cas d'usage: Data processing, transformation progressive
┌─────────┐ output ┌─────────┐ output ┌─────────┐
│ Agent 1 │──────────> │ Agent 2 │──────────> │ Agent 3 │
│ (RI) │ [gate] │ (SP) │ [gate] │ (CF) │
│ collect │ │ analyze │ │ finalize│
└─────────┘ └─────────┘ └─────────┘
Si gate fail: Si gate fail: Output final
retry x3 retry x3 sauvé dans
puis fallback puis fallback outputs/final.md
TOPOLOGY 2: PARALLEL
====================
Interdépendance: Pooled (Thompson)
Cas d'usage: Recherche multi-source, tâches indépendantes
┌──────────┐
┌──> │ Agent A │ ──> output-a.md ──┐
│ │ (RI) │ │
│ └──────────┘ │
Task ┤ ┌──────────┐ ├──> Coordinator
│──> │ Agent B │ ──> output-b.md ──┤ (merge)
│ │ (RI) │ │ ──> final.md
│ └──────────┘ │
└──> ┌──────────┐ │
│ Agent C │ ──> output-c.md ──┘
│ (ME) │
└──────────┘
TOPOLOGY 3: ORCHESTRATOR
========================
Interdépendance: Reciprocal (Thompson)
Cas d'usage: Feature dev, projets complexes coordonnés
┌───────────────────────────────┐
│ ORCHESTRATOR │
│ (CO / opus model) │
│ │
│ 1. Decompose task │
│ 2. Assign to workers │
│ 3. Monitor progress │
│ 4. Provide feedback │
│ 5. Synthesize results │
└───┬──────┬──────┬─────────────┘
│ │ │
assign │ │ │ assign
v v v
┌──────┐┌──────┐┌──────┐
│ W-A ││ W-B ││ W-C │
│(IMP) ││(SP) ││(CF) │
│sonnet││sonnet││sonnet│
└──┬───┘└──┬───┘└──┬───┘
│ │ │
report │ │ │ report
v v v
┌───────────────────────────────┐
│ ORCHESTRATOR │
│ (synthesize final) │
└───────────────────────────────┘
TOPOLOGY 4: DEBATE
==================
Interdépendance: Reciprocal + High stakes (Thompson + Janis)
Cas d'usage: Décisions critiques, choix d'architecture
Round 1 Round 2 Round 3 Judgment
┌─────┐ ┌─────┐ ┌─────┐ ┌──────────┐
│ A │──────>│A->B │──────>│ A' │──────>│ │
│prop.│ │crit.│ │rev. │ │ Monitor │
└─────┘ └─────┘ └─────┘ │ Evaluator│
┌─────┐ ┌─────┐ ┌─────┐ │ │
│ B │──────>│B->C │──────>│ B' │──────>│ Selects │
│prop.│ │crit.│ │rev. │ │ best or │
└─────┘ └─────┘ └─────┘ │ hybrid │
┌─────┐ ┌─────┐ ┌─────┐ │ │
│ C │──────>│C->A │──────>│ C' │──────>│ │
│prop.│ │crit.│ │rev. │ └──────────┘
└─────┘ └─────┘ └─────┘
MEMORY FLOW BETWEEN RUNS
========================
Run N Run N+1
┌─────────────────┐ ┌─────────────────┐
│ │ Persist │ │
│ PERFORMING │ │ FORMING │
│ - New facts │──> Semantic ──────> │ - Load facts │
│ - Errors │──> Episodic ──────> │ - Learn from │
│ - Workflows │──> Procedural ────> │ past errors │
│ │ │ - Reuse SOPs │
│ ADJOURNING │ │ │
│ - Metrics │──> TMS routing ───> │ - Route tasks │
│ - Agent perf │ update │ to experts │
│ │ │ │
└─────────────────┘ └─────────────────┘
TMS Routing Table Evolution:
┌────────────────────────────────────────┐
│ Run 1: { "auth": ["architect"] } │
│ Run 2: { "auth": ["architect", │
│ "security-spec"], │
│ "frontend": ["ui-dev"] } │
│ Run 3: { "auth": [...], │
│ "frontend": [...], │
│ "database": ["data-eng"] } │
└────────────────────────────────────────┘
La table s'enrichit à chaque exécution.
CIRCUIT BREAKER FLOW
====================
Agent Action
│
v
┌──────────┐
│ Execute │
│ │──> Success ──> Continue
└──────────┘
│
v (failure)
┌──────────┐
│ Retry 1 │ Adjust prompt: add specific instructions
│ │──> Success ──> Continue
└──────────┘
│
v (failure)
┌──────────┐
│ Retry 2 │ Simplify subtask scope
│ │──> Success ──> Continue
└──────────┘
│
v (failure)
┌──────────┐
│ Retry 3 │ Provide partial output template
│ │──> Success ──> Continue
└──────────┘
│
v (failure)
┌──────────────────────────────────────────┐
│ FALLBACK STRATEGY │
│ │
│ degrade ──> Continue sans cet agent, │
│ marquer le gap │
│ │
│ skip ──> Retirer la sous-tâche, │
│ rerouter dépendances │
│ │
│ escalate -> Pause + demande à │
│ l'humain: retry/skip/abort │
└──────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ DEV SQUAD — Full-stack Development │
│ Topology: Orchestrator | Quality: Eval-Opt │
├──────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ ARCHITECT │ Plant (PL) | opus │
│ │ Innovates │ Tools: Read, Grep, Glob │
│ │ designs │ T: 0.9 (creative) │
│ └──────┬───────┘ │
│ │ orchestrates │
│ ┌────┴────┬──────────┐ │
│ v v v │
│ ┌──────┐ ┌────────┐ ┌────────┐ │
│ │CODER │ │REVIEWER│ │TESTER │ │
│ │IMP │ │ME │ │CF │ │
│ │sonnet│ │sonnet │ │sonnet │ │
│ │T:0.4 │ │T:0.3 │ │T:0.2 │ │
│ └──────┘ └────────┘ └────────┘ │
│ │
│ Use cases: │
│ - Feature development │
│ - Refactoring │
│ - Bug fixing │
│ - Code migration │
└──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ MARKETING CREW — Content & Strategy │
│ Topology: Orchestrator | Quality: Eval-Opt │
├──────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ STRATEGIST │ Coordinator (CO) | opus │
│ │ Coordinates │ T: 0.5 (balanced) │
│ │ directs │ │
│ └──────┬───────┘ │
│ │ │
│ ┌────┴────┬──────────┐ │
│ v v v │
│ ┌──────┐ ┌────────┐ ┌──────────┐ │
│ │CREATE│ │ BRAND │ │ANALYTICS │ │
│ │PL │ │ ME │ │ SP │ │
│ │sonnet│ │ sonnet │ │ sonnet │ │
│ │T:0.9 │ │ T:0.3 │ │ T:0.4 │ │
│ └──────┘ └────────┘ └──────────┘ │
│ │
│ Use cases: │
│ - Campaign creation │
│ - Content strategy │
│ - Brand audit │
│ - Social media planning │
└──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ RESEARCH TEAM — Analysis & Investigation │
│ Topology: Parallel | Quality: MAD │
├──────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ PLANNER │ Coordinator (CO) | opus │
│ │ Plans & │ T: 0.5 (balanced) │
│ │ synthesizes │ │
│ └──────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ Independent │
│ │RESEARCHER-1 │ │RESEARCHER-2 │ parallel │
│ │RI | sonnet │ │RI | sonnet │ research │
│ │T:0.6 │ │T:0.6 │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ CRITIC │ │ SYNTHESIZER │ │
│ │ ME | sonnet │ │ CF | opus │ │
│ │ T:0.3 │ │ T:0.2 │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ Use cases: │
│ - Deep research / Literature review │
│ - Competitive analysis │
│ - Multi-source investigation │
│ - Technical comparison │
└──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ FINANCE UNIT — Financial Analysis & Compliance │
│ Topology: Pipeline | Quality: Eval-Opt │
├──────────────────────────────────────────────────┤
│ │
│ Stage 1 Stage 2 Stage 3 Stage 4
│ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐
│ │ DATA │────>│ANALYST │──>│ RISK │────>│COMPLIANCE│
│ │ RI │ │ SP │ │ ME │ │ CF │
│ │sonnet│ │ opus │ │sonnet│ │ sonnet │
│ │T:0.6 │ │ T:0.4 │ │T:0.3 │ │ T:0.2 │
│ └──────┘ └────────┘ └──────┘ └──────────┘
│ Collect Analyze Assess Verify
│ data numbers risks compliance
│ │
│ Use cases: │
│ - Financial reports │
│ - Risk analysis │
│ - Budget planning │
│ - Compliance audit │
│ - Investment analysis │
└──────────────────────────────────────────────────┘
Le fichier .koral/config.json contrôle le comportement global du framework :
{
"version": "1.0.0",
"created": "2026-03-18T14:30:00.000Z",
"last_run": "2026-03-18_14-30-00",
"default_hitl_level": 1,
"default_quality": "evaluator-optimizer",
"circuit_breaker": {
"max_retries_per_agent": 3,
"timeout_per_action_ms": 120000,
"fallback_strategy": "degrade_gracefully",
"error_propagation": "isolate"
},
"evaluator_optimizer": {
"threshold": 7.0,
"max_iterations": 3,
"rubric": {
"completeness": 0.25,
"accuracy": 0.25,
"clarity": 0.20,
"actionability": 0.15,
"consistency": 0.15
}
}
}| Aspect | Level 0 (Autonomous) | Level 1 (Checkpoints) | Level 2 (Supervised) |
|---|---|---|---|
| Forming | Auto | Validation config | Validation config |
| Storming | Auto | Auto | Approbation chaque output |
| Norming | Auto | Validation plan | Validation plan détaillée |
| Performing | Auto | Auto | Approbation chaque agent |
| Adjourning | Auto | Review final | Review final détaillé |
| Temps ajouté | 0% | +20-30% | +100-200% |
| Risque | Moyen | Faible | Très faible |
| Usage | Tâches répétitives | Standard | Compliance, high-stakes |
Pour créer un agent personnalisé, définissez ces champs :
- name : Identifiant unique (slug, ex:
security-auditor) - role : Description du rôle (ex: "Security Auditor")
- belbin_role : Choisir parmi les 9 rôles Belbin selon le comportement souhaité
- model :
opuspour les tâches complexes/coordination,sonnetpour l'exécution,haikupour les tâches rapides - tools : Sélectionner les outils nécessaires (Read, Edit, Write, Bash, Grep, Glob, Agent, WebSearch, WebFetch)
- temperature_profile :
creative(0.9),balanced(0.6),analytical(0.3) - specialties : Liste des domaines d'expertise
Exemple — Agent Security Auditor :
{
"name": "security-auditor",
"role": "Application Security Auditor",
"belbin_role": "ME",
"model": "opus",
"tools": ["Read", "Grep", "Glob", "Bash"],
"temperature_profile": "analytical",
"specialties": ["OWASP", "authentication", "encryption", "input-validation"],
"max_retries": 3,
"timeout_ms": 300000
}Un template est une configuration d'équipe réutilisable. Pour en créer un :
- Concevoir l'équipe en s'appuyant sur les rôles Belbin
- Vérifier la couverture des 3 fonctions critiques (Coordonner, Exécuter, Revoir)
- Choisir la topologie adaptée via Thompson
- Sauvegarder dans
.koral/templates/
Règle d'or : la diversité prime sur la taille. Une équipe de 3 agents aux rôles diversifiés surpassera une équipe de 6 agents aux rôles identiques.
| Scénario | max_retries | timeout_ms | fallback | error_propagation |
|---|---|---|---|---|
| Dev rapide | 2 | 60000 | degrade | isolate |
| Production standard | 3 | 120000 | degrade | isolate |
| Compliance critique | 5 | 300000 | escalate | halt |
| Expérimentation | 1 | 30000 | skip | isolate |
La mémoire peut être configurée par équipe :
{
"memory_config": {
"episodic": true,
"semantic": true,
"procedural": true
}
}- episodic: false → Pas de sauvegarde des expériences (utile pour les tests one-shot)
- semantic: false → Pas de persistance des connaissances (utile si le domaine change souvent)
- procedural: false → Pas de sauvegarde des workflows (utile pour l'exploration pure)
| # | Antipattern | Description | Solution KORAL |
|---|---|---|---|
| 1 | Bag of Agents | Agents non coordonnés, pas de structure | Topologies + Hackman checklist |
| 2 | Équipe homogène | Tous les agents avec le même rôle/température | Woolley diversity enforcement |
| 3 | Mission manquante | Pas d'objectif clair partagé | Hackman condition 2 (Compelling Direction) |
| 4 | Sur-ingénierie | Trop d'agents pour une tâche simple | Thompson analysis (utiliser single-agent si pooled) |
| 5 | Pas de quality gates | Outputs non vérifiés | Evaluator-Optimizer loop |
| 6 | Ignorer Thompson | Mauvaise topologie pour le type d'interdépendance | Auto-sélection Thompson |
| 7 | Echo chamber | Agents identiques qui convergent immédiatement | DMAD + devil's advocate |
| 8 | Pas de circuit breaker | Un agent en échec bloque tout | Circuit breaker avec fallback |
| 9 | Pas de mémoire | Chaque run repart de zéro | TMS (Wegner) avec 3 types de mémoire |
| 10 | Human bottleneck | HITL level 2 sur des tâches simples | Adapter le HITL à la complexité |
| 11 | Agent sprawl | Trop d'agents, coordination overhead | Limiter à 3-6 agents par équipe |
| 12 | Conditions Hackman manquantes | Lancement sans vérification | Pre-flight checklist obligatoire |
| 13 | Optimisation prématurée | Tuner l'équipe avant de tester | Commencer avec un template, itérer |
| 14 | Négliger l'Adjourning | Pas de rétrospective ni de sauvegarde | Phase Adjourning + mémoire auto |
Le multi-agent n'est pas toujours la meilleure solution. Préférez un single-agent quand :
- La tâche est simple et mono-domaine : un prompt bien conçu suffit
- La tâche prend < 5 minutes : l'overhead de coordination n'est pas justifié
- Le domaine est unique : pas besoin de perspectives multiples
- Les contraintes de temps sont très serrées : le multi-agent est plus lent
- Le résultat est factuel et non ambigu : pas de valeur ajoutée du débat
Règle pratique : si vous pouvez résoudre le problème avec un seul prompt bien structuré, ne lancez pas 4 agents pour le faire.
| Version | Features | Statut |
|---|---|---|
| v1.0.0 | 5 skills core (/koral, /koral-team, /koral-run, /koral-monitor, /koral-memory), 4 templates, 4 topologies, 3 quality modes, TMS, circuit breaker | Disponible |
| v1.1 | Custom topology builder, agent marketplace, partage de templates entre projets | Planifié |
| v1.2 | Intégration MCP server pour communication inter-agents, webhooks de notification | Planifié |
| v2.0 | Dashboard visuel web, monitoring WebSocket temps réel, interface graphique de composition d'équipes | Exploration |
| Future | Mémoire inter-projets, évolution d'équipes par algorithmes génétiques, benchmark automatique de configurations | Recherche |
Les contributions sont les bienvenues ! Voici comment participer :
- Utilisez les GitHub Issues pour signaler des bugs ou proposer des features
- Taguez vos issues :
bug,feature,documentation,question
- Fork le repository
- Créez une branche feature (
git checkout -b feature/my-feature) - Commitez vos changements (
git commit -m 'Add my feature') - Push vers la branche (
git push origin feature/my-feature) - Ouvrez une Pull Request
# Clone
git clone https://github.com/FelixMining/KORAL.git
cd KORAL
# Les skills sont dans .claude/skills/
# Éditez directement les fichiers SKILL.md
# Testez dans un projet
cp -r .claude/skills/koral* /path/to/test-project/.claude/skills/Ce projet suit le Contributor Covenant. Soyez respectueux, constructif et inclusif.
Ce projet est sous licence MIT. Voir le fichier LICENSE pour les détails.
MIT License
Copyright (c) 2025-2026 Felix Lenci
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Felix Lenci — felixlenci.com
- GitHub : @FelixMining
KORAL is an open-source multi-agent orchestration framework implemented as a set of skills (slash commands) for Claude Code. It translates 60 years of human collaboration science into concrete, reusable AI architecture patterns.
The founding principle is straightforward: the same factors that make human teams effective — differentiated roles, structured coordination, collective memory, continuous feedback — apply directly to multi-agent AI systems.
The Bag of Agents Problem is the leading cause of failure in production multi-agent systems. It occurs when multiple AI agents are launched without coordination structure:
Without KORAL (Bag of Agents) With KORAL (Coordinated Team)
Agent A --?--> ??? Coordinator --> Architect (Plant)
Agent B --?--> ??? |---> Coder (Implementer)
Agent C --?--> ??? |---> Reviewer (Monitor Eval)
Agent D --?--> ??? +---> Tester (Completer-Fin.)
No defined roles Belbin roles assigned
No coordination Orchestrator topology
No memory Transactive Memory (Wegner)
No quality control Evaluator-Optimizer loop
Result: chaos Result: coherent deliverable
| Metric | Value | Source |
|---|---|---|
| Multi-agent vs single-agent gain | +90.2% | Anthropic, 2024 |
| Multi-agent pilot failure rate in production | 40-87% | Gartner / McKinsey, 2024-2025 |
| Specified roles vs general roles performance | 58% vs 36% | Li et al., "Camel", 2023 |
| AI agents market 2025 | $7.84B | Grand View Research |
| AI agents market 2030 (projected) | $52.62B | Grand View Research |
| Average IQ correlation with collective intelligence | r=0.15 (WEAK) | Woolley & Malone, 2010 |
| Diversity impact on team performance | >2x | Woolley & Malone, 2010 |
Takeaway: Multi-agent is the future, but without rigorous methodology, failure rates are catastrophic. KORAL bridges this gap by applying validated scientific theories.
KORAL integrates 7 major scientific theories and Anthropic's 6 composable patterns into a coherent architecture. Each theory has been translated into an executable protocol.
Every KORAL execution cycles through Tuckman's phases:
| Phase | Human Activity | KORAL Equivalent |
|---|---|---|
| Forming | Getting acquainted, understanding goals | Context loading, Belbin role assignment, mission prompt |
| Storming | Productive disagreements, exploration | Multi-agent debate (DMAD), independent proposals |
| Norming | Convergence, setting standards | Proposal synthesis, execution plan, quality norms |
| Performing | Peak production | Topology execution with circuit breaker |
| Adjourning | Retrospective, dissolution | Memory persistence, metrics, final report |
Each KORAL agent is assigned a Belbin role that determines its behavior, temperature, and prompt style:
| Role | Code | AI Behavior | Temperature | Typical Use |
|---|---|---|---|---|
| Plant | PL | Creative innovator, unconventional solutions | 0.9-1.0 | Architecture, brainstorming |
| Monitor Evaluator | ME | Critical analyst, objective scoring | 0.2-0.4 | Code review, QA, audit |
| Shaper | SH | Challenger, devil's advocate | 0.6-0.8 | Stress-testing, red team |
| Coordinator | CO | Delegator, synthesizer | 0.4-0.6 | Orchestration, synthesis |
| Implementer | IMP | Practical executor, production-ready output | 0.3-0.5 | Development, writing |
| Completer-Finisher | CF | Quality guardian, detail checker | 0.1-0.3 | Testing, verification |
| Specialist | SP | Deep domain expert | 0.3-0.5 | Technical expertise |
| Resource Investigator | RI | Explorer, external information finder | 0.5-0.7 | Web search, benchmarks |
| Team Worker | TW | Integrator, consistency enforcer | 0.4-0.6 | Cross-referencing, cohesion |
KORAL runs a mandatory pre-flight checklist before every execution:
- Real Team — All agents defined with clear names, roles, and boundaries
- Compelling Direction — Single mission prompt with success criteria and deliverables
- Enabling Structure — Each agent has appropriate tools and defined I/O formats
- Supportive Context — Project files accessible, domain knowledge provided, memory consulted
- Expert Coaching — Orchestrator agent configured, HITL escalation path, feedback mechanisms
If any condition fails, execution halts with a diagnostic report.
Key finding: The correlation between average member IQ and collective performance is only r=0.15 (WEAK). What matters is diversity and coordination quality.
KORAL enforces diversity through:
- Different Belbin roles across the team
- Varied temperature settings per agent
- Mixed model tiers (opus for coordination, sonnet for execution)
- No single agent may produce >40% of the final output
- The "c" factor is computed and displayed via
/koral-monitor metrics
KORAL implements a "who knows what" routing system with three memory types:
| Memory Type | Stores | Purpose |
|---|---|---|
| Episodic | What happened — run outcomes, errors, lessons | Learn from past experiences |
| Semantic | What we know — validated facts, domain knowledge | Enrich future run context |
| Procedural | How we do things — SOPs, proven workflows | Reuse successful patterns |
A tms-routing.json file maps knowledge domains to expert agents, evolving with every run.
KORAL auto-selects the optimal agent topology based on Thompson's classification:
| Interdependence | Description | Selected Topology |
|---|---|---|
| Pooled | Tasks are independent, share final output | Parallelization |
| Sequential | Task B depends on Task A's output | Pipeline / Prompt-Chaining |
| Reciprocal | Tasks need bidirectional feedback | Orchestrator-Workers / Debate |
The Diversified Multi-Agent Debate (DMAD) protocol prevents premature consensus:
- Round 0: Each agent produces analysis independently (no cross-visibility)
- Round 1: Structured cross-review (strengths, weaknesses, blind spots)
- Round 2: Devil's advocate (Shaper agent) argues against the emerging consensus
- Round 3: Coordinator synthesizes all arguments into a final position
The six fundamental patterns for building agent workflows:
- Context-Augmentation — Enrich prompts with retrieved context before execution
- Prompt-Chaining — Sequential pipeline with quality gates between stages
- Parallelization — Multiple agents working independently (sectioning or voting)
- Routing — Classify and route to the appropriate specialist agent via TMS
- Evaluator-Optimizer — Generate, score against rubric, refine iteratively
- Orchestrator-Workers — Central coordinator delegates to workers, synthesizes results
# 1. Clone the repository
git clone https://github.com/FelixMining/KORAL.git
# 2. Copy skills to your project
cp -r KORAL/.claude/skills/koral* your-project/.claude/skills/
# 3. That's it! Use /koral in your project# Create symlinks to KORAL skills
ln -s /path/to/KORAL/.claude/skills/koral your-project/.claude/skills/koral
ln -s /path/to/KORAL/.claude/skills/koral-team your-project/.claude/skills/koral-team
ln -s /path/to/KORAL/.claude/skills/koral-run your-project/.claude/skills/koral-run
ln -s /path/to/KORAL/.claude/skills/koral-monitor your-project/.claude/skills/koral-monitor
ln -s /path/to/KORAL/.claude/skills/koral-memory your-project/.claude/skills/koral-memorygit submodule add https://github.com/FelixMining/KORAL.git .koral-framework
cp -r .koral-framework/.claude/skills/koral* .claude/skills/Download the ZIP from GitHub and copy the .claude/skills/ folder into your project.
- Claude Code: Anthropic's official CLI tool
- An existing project: KORAL installs into any project
- No other dependencies required
Type /koral with no arguments:
> /koral
[KORAL banner is displayed]
Then answer 6 interactive multiple-choice questions:
1. Sector (Dev / Marketing / Research / Finance / Custom)
2. Task description (free text)
3. Complexity (Simple / Medium / Complex / Auto-detect)
4. Topology (Pipeline / Parallel / Orchestrator / Debate / Auto)
5. HITL level (Autonomous / Checkpoints / Supervised)
6. Quality mode (Standard / Evaluator-Optimizer / MAD-DMAD)
Type /koral followed by a task description:
> /koral create a REST API with auth, database, and tests
KORAL auto-detects:
Sector: Dev | Complexity: Complex | Topology: Orchestrator
Team: Dev Squad (4 agents) | Quality: Evaluator-Optimizer
Launch? (yes/no/modify)
> /koral-team create # Create a custom team
> /koral-run my-team Do X # Execute with that team
> /koral-monitor # Monitor progress
> /koral-memory # Check collective memory
The entry point to the framework. Two modes:
- Wizard Mode (no args): Interactive 6-step QCM configuration
- Quick Mode (with task): Auto-analysis with one-click launch
| Sub-command | Description |
|---|---|
create |
7-step team creation wizard |
list |
List all configured teams |
show <name> |
Display team details |
edit <name> |
Modify an existing team |
delete <name> |
Delete a team (with confirmation) |
templates |
Display 4 pre-configured templates |
Validation rules enforce: minimum 2 agents, no duplicate names, topology compatibility, and critical function coverage (Coordinate, Execute, Review).
The multi-agent execution engine. Runs the complete Tuckman lifecycle:
- Pre-flight: Hackman 5 conditions checklist (mandatory)
- Forming: Context loading, agent initialization, mission prompt
- Storming: Divergent exploration, DMAD debate (if enabled)
- Norming: Plan synthesis, task assignment, dependency graph
- Performing: Topology execution with circuit breaker and quality gates
- Adjourning: Final QA, synthesis, metrics, memory persistence
Four topologies: Pipeline, Parallel, Orchestrator, Debate
Circuit breaker: configurable retries, timeouts, and fallback strategies (degrade/skip/escalate)
HITL levels: Autonomous (0), Checkpoints (1), Supervised (2)
| Sub-command | Description |
|---|---|
(no args) or latest |
Latest run dashboard |
<run-id> |
Specific run dashboard |
history |
All past runs table |
metrics |
Aggregated metrics: velocity, defect rate, cycle time, Woolley factor "c" |
| Sub-command | Description |
|---|---|
| (no args) | Memory overview with TMS routing table |
show [type] |
Display memory contents |
search <query> |
Search across all memory types |
add <type> <content> |
Add a memory entry |
clear <type> |
Clear a memory type (with confirmation) |
export |
Export all memory as consolidated markdown |
Automatic maintenance: stale entry detection (>30 days), low confidence warnings, failing procedure alerts, duplicate detection.
your-project/
├── .claude/
│ └── skills/
│ ├── koral/ # Main command /koral
│ ├── koral-team/ # Team management /koral-team
│ ├── koral-run/ # Execution engine /koral-run
│ ├── koral-monitor/ # Monitoring /koral-monitor
│ └── koral-memory/ # Memory system /koral-memory
│
└── .koral/ # Runtime data (auto-created)
├── config.json # Global configuration
├── teams/ # Team configurations (.json)
├── memory/
│ ├── episodic/ # Past experiences
│ ├── semantic/ # Validated knowledge
│ ├── procedural/ # Proven workflows
│ └── tms-routing.json # "Who knows what" routing
├── runs/
│ └── <timestamp>/
│ ├── state.json # Run state
│ ├── plan.json # Execution plan
│ ├── metrics.json # Run metrics
│ ├── errors.json # Error log
│ ├── outputs/ # Agent outputs + final.md
│ └── logs/ # Detailed logs
└── templates/ # Custom templates
User Input
|
v
Mode Selection (Wizard or Quick)
|
v
Initialization (.koral/ directory, config, team, run)
|
v
Hackman Pre-flight (5 conditions) --X--> STOP if fail
|
v
Tuckman Cycle:
Forming --> Storming --> Norming --> Performing --> Adjourning
| | | | |
Context load DMAD debate Plan Topology Memory
Agent init Devil's adv. Assignment execution Metrics
Mission prompt Dependency Circuit brk. Final QA
graph
|
v
Output (final.md + metrics.json + memory updates)
Circuit Breaker Flow:
- Agent action attempted
- On failure: Retry 1 (add specific instructions)
- On failure: Retry 2 (simplify subtask)
- On failure: Retry 3 (provide partial template)
- On exhaustion: Apply fallback strategy
degrade: Continue without failed agentskip: Remove subtask, reroute dependenciesescalate: Pause, ask human for guidance
Error propagation modes:
isolate(default): One agent's failure doesn't stop othershalt: Any failure stops the entire pipelineretry-then-halt: Retry exhausted, then halt
| Agent | Role | Belbin | Model |
|---|---|---|---|
| architect | Software Architect | Plant (PL) | opus |
| coder | Senior Developer | Implementer (IMP) | sonnet |
| reviewer | Code Reviewer | Monitor Evaluator (ME) | sonnet |
| tester | QA Engineer | Completer-Finisher (CF) | sonnet |
Topology: Orchestrator | Quality: Evaluator-Optimizer Best for: Feature development, refactoring, bug fixing, code migration
| Agent | Role | Belbin | Model |
|---|---|---|---|
| strategist | Marketing Strategist | Coordinator (CO) | opus |
| creator | Content Creator | Plant (PL) | sonnet |
| brand | Brand Guardian | Monitor Evaluator (ME) | sonnet |
| analytics | Data Analyst | Specialist (SP) | sonnet |
Topology: Orchestrator | Quality: Evaluator-Optimizer Best for: Campaign creation, content strategy, brand audit, social media planning
| Agent | Role | Belbin | Model |
|---|---|---|---|
| planner | Research Planner | Coordinator (CO) | opus |
| researcher-1 | Primary Researcher | Resource Investigator (RI) | sonnet |
| researcher-2 | Secondary Researcher | Resource Investigator (RI) | sonnet |
| critic | Critical Analyst | Monitor Evaluator (ME) | sonnet |
| synthesizer | Knowledge Synthesizer | Completer-Finisher (CF) | opus |
Topology: Parallel | Quality: MAD (Multi-Agent Debate) Best for: Deep research, competitive analysis, literature review, technical comparison
| Agent | Role | Belbin | Model |
|---|---|---|---|
| data | Data Collector | Resource Investigator (RI) | sonnet |
| analyst | Financial Analyst | Specialist (SP) | opus |
| risk | Risk Assessor | Monitor Evaluator (ME) | sonnet |
| compliance | Compliance Officer | Completer-Finisher (CF) | sonnet |
Topology: Pipeline | Quality: Evaluator-Optimizer Best for: Financial reports, risk analysis, budget planning, compliance audit
{
"version": "1.0.0",
"created": "ISO-8601",
"last_run": "run-id or null",
"default_hitl_level": 1,
"default_quality": "evaluator-optimizer",
"circuit_breaker": {
"max_retries_per_agent": 3,
"timeout_per_action_ms": 120000,
"fallback_strategy": "degrade_gracefully",
"error_propagation": "isolate"
},
"evaluator_optimizer": {
"threshold": 7.0,
"max_iterations": 3,
"rubric": {
"completeness": 0.25,
"accuracy": 0.25,
"clarity": 0.20,
"actionability": 0.15,
"consistency": 0.15
}
}
}| Aspect | Level 0 (Autonomous) | Level 1 (Checkpoints) | Level 2 (Supervised) |
|---|---|---|---|
| Forming | Auto | Validate config | Validate config |
| Storming | Auto | Auto | Approve each output |
| Norming | Auto | Approve plan | Detailed plan review |
| Performing | Auto | Auto | Approve each agent |
| Adjourning | Auto | Final review | Detailed final review |
| Time overhead | 0% | +20-30% | +100-200% |
| Risk level | Medium | Low | Very low |
| Best for | Repetitive tasks | Standard workflows | Compliance, high-stakes |
Define these fields for a custom agent:
- name: Unique slug identifier
- role: Role description
- belbin_role: One of PL, ME, SH, CO, IMP, CF, SP, RI, TW
- model:
opus(complex/coordination),sonnet(execution),haiku(fast) - tools: Array of available tools
- temperature_profile:
creative(0.9),balanced(0.6),analytical(0.3) - specialties: List of expertise domains
| Scenario | max_retries | timeout_ms | fallback | propagation |
|---|---|---|---|---|
| Fast dev | 2 | 60000 | degrade | isolate |
| Standard prod | 3 | 120000 | degrade | isolate |
| Critical compliance | 5 | 300000 | escalate | halt |
| Experimentation | 1 | 30000 | skip | isolate |
| # | Antipattern | Solution |
|---|---|---|
| 1 | Bag of Agents (no coordination) | Topologies + Hackman checklist |
| 2 | Homogeneous team (no diversity) | Woolley diversity enforcement |
| 3 | Missing mission prompt | Hackman condition 2 |
| 4 | Over-engineering (too many agents) | Thompson analysis |
| 5 | No quality gates | Evaluator-Optimizer loop |
| 6 | Ignoring Thompson's interdependence | Auto-topology selection |
| 7 | Echo chamber (identical agents) | DMAD + devil's advocate |
| 8 | Missing circuit breaker | Configurable resilience |
| 9 | No memory persistence | TMS with 3 memory types |
| 10 | Human bottleneck (excessive HITL) | Adapt HITL to complexity |
| 11 | Agent sprawl (too many agents) | Limit to 3-6 per team |
| 12 | Missing Hackman conditions | Mandatory pre-flight check |
| 13 | Premature optimization | Start with template, iterate |
| 14 | Neglecting Adjourning phase | Auto memory + metrics |
Use a single well-prompted agent when:
- The task is simple and single-domain
- The task takes less than 5 minutes
- A single domain is involved with no ambiguity
- Time constraints are very tight
- The expected output is factual and unambiguous
Rule of thumb: If one well-crafted prompt can solve it, don't spin up 4 agents.
| Version | Features | Status |
|---|---|---|
| v1.0.0 | 5 core skills, 4 templates, 4 topologies, 3 quality modes, TMS, circuit breaker | Available |
| v1.1 | Custom topology builder, agent marketplace, template sharing | Planned |
| v1.2 | MCP server integration for inter-agent communication, notification webhooks | Planned |
| v2.0 | Visual web dashboard, real-time WebSocket monitoring, graphical team composition | Exploration |
| Future | Cross-project memory, team evolution via genetic algorithms, auto-benchmark | Research |
Contributions are welcome!
- Use GitHub Issues for bugs, features, and questions
- Tag appropriately:
bug,feature,documentation,question
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Commit your changes
- Push and open a Pull Request
git clone https://github.com/FelixMining/KORAL.git
cd KORAL
# Skills are in .claude/skills/ — edit the SKILL.md files directly
# Test by copying to a project
cp -r .claude/skills/koral* /path/to/test-project/.claude/skills/This project follows the Contributor Covenant. Be respectful, constructive, and inclusive.
This project is licensed under the MIT License. See the LICENSE file for details.
Felix Lenci — felixlenci.com
- GitHub: @FelixMining
If you find KORAL useful, please consider giving it a star on GitHub!
KORAL v1.0.0
Kernel d'Organisation pour Reseaux d'Agents Logiques
Built with ❤️ by Felix Lenci