Orchestration d'Équipe d'Agents pour Dépôt (Meta-Project Team Orchestration)
Skill autonome pour composer, auditer et optimiser une équipe d'agents spécialisés adaptée au projet.
Le skill analyse la structure du dépôt, identifie les spécialisations nécessaires (Gestionnaire GitHub, DevOps, QA, UI/UX, Sécurité, Analyste Produit, Juridique, Juge de Consensus, etc.), matérialise des profils isolés dans .agents/team/, et établit des protocoles de coordination stricts (validation humaine, passations supervisées par l'utilisateur, notes immuables, arbitrage basé sur des preuves).
Quand invoquer le skill
- L'utilisateur demande : "assembler une équipe d'agents", "doter le projet de rôles", "configurer les rôles des agents", "auditer l'activité de l'équipe", "passer en revue les rôles de l'équipe", "mettre à jour la composition de l'équipe d'agents".
- De nouvelles couches technologiques majeures sont introduites dans le projet (Docker, CI/CD, UI mobile, base de données, intégrations de paiement externes) nécessitant une gouvernance dédiée.
Étapes d'exécution
Phase 1 : Analyse Rapide du Dépôt (Inspection des Marqueurs)
Avant de définir les rôles, l'agent doit inspecter les marqueurs clés du projet :
- Infrastructure d'hébergement et CI : Présence du répertoire
.github/, workflows, modèles de pull request, modèles d'issue. - Licences et gouvernance open source : Présence de
LICENSE, droits d'auteur,CONTRIBUTING.md, manifestes de dépendances. - Conteneurisation et orchestration :
Dockerfile,docker-compose*.yml,k8s/,helm/. - Infrastructure de test : Répertoire
tests/,pytest.ini,vitest.config.*, fixtures de test. - Sécurité et données sensibles : Répertoires
auth/,security/, gestion des tokens, gestion des sessions, logique de chiffrement. - Interface utilisateur et design : Modules frontend, HTML/CSS, dispositions de clavier de bot, assets, tokens de design.
- Passeport actuel du projet : Lecture de
AGENTS.mdet des fragments.agents/project_knowledge/(si déjà initialisés). - Stacks secondaires / polyglottes : Sous-répertoires contenant des fichiers sources compilés ou dans d'autres langages (par ex.
.cpp,.c,.h,.rs,.go,.swiftdansclient/,native/,core/,desktop/).
Phase 2 : Dimensionnement Adaptatif à l'Échelle et Matrice de Compétences Ouverte
Avant de proposer des rôles, l'agent doit évaluer l'échelle du dépôt et synthétiser une équipe minimale suffisante.
1. Dimensionnement du Dépôt et Synthèse des Rôles
L'agent estime le volume de la base de code (LOC, profondeur des dossiers, diversité technologique) :
-
Dépôt Micro / Petit (<10k lignes, développeur solo, 1–2 stacks principales) : Synthétiser 2–3 rôles combinés en regroupant des blocs de compétences de la matrice dans des profils unifiés.
- Trio Compact Canonique :
agent-dev-lead: Combine l'analyse des demandes, la décomposition des tâches et l'implémentation générale du code (agent-intake-dispatcher+agent-general-worker).agent-quality-guardian: Combine l'intégrité du passeport/de la connaissance, les suites de tests unitaires et l'audit de code mort (agent-meta-guardian+agent-qa-engineer+agent-deep-auditor).agent-github-steward: Hygiène Git, commits conventionnels, parité Code-README et CI/CD.
- Trio Compact Canonique :
-
Dépôt Moyen (10k–50k lignes, petite équipe, plusieurs services) : Déployer 3 à 5 rôles dédiés adaptés aux composants clés.
-
Dépôt Grand / Entreprise (>50k lignes, monorepos, microservices) : Déployer 6+ rôles granulaires avec une séparation stricte des préoccupations.
-
Règle d'Isolation des Stacks Polyglottes (Pas de Regroupements Toxiques) : Interdire strictement le regroupement de stacks secondaires compilées ou spécialisées (C/C++, Rust, Go, GUI native) dans
agent-general-workersans compétences dédiées. Lorsqu'une stack polyglotte est détectée, soit synthétiser un rôle dédié (par ex.agent-native-desktopavec compilateurs natifs et chaînes d'outils), soit mapper explicitement les répertoires natifs en Zone Rouge avec un déclencheur de Passation obligatoire. -
Règle de Dispatcheur Obligatoire (Pas de Chaos Multi-Rôle) : Lors du déploiement de 3 rôles spécialisés ou plus, le déploiement d'un dispatcheur d'entrée (
agent-intake-dispatcherou un dispatcheur intégré dansagent-dev-lead) est strictement obligatoire. Interdire de laisser l'utilisateur avec un ensemble non routé de plusieurs rôles isolés sans point d'entrée unique.
2. Catalogue de Compétences Ouvert (Matrice des Rôles)
[!IMPORTANT] Le tableau ci-dessous est un Catalogue de Compétences Ouvert, pas une énumération fermée immuable. Les agents ont une autonomie totale pour synthétiser des rôles combinés ou inventer des rôles personnalisés spécifiques au domaine (par ex.,
agent-solana-smart-contracts,agent-3d-designer,agent-data-pipeline) correspondant à l'architecture réelle du dépôt.
| Catégorie | Bloc de Compétence / Rôle | Marqueurs du Dépôt | Compétences Spécialisées | Limites de Responsabilité |
|---|---|---|---|---|
| Rôle de Base | agent-general-worker(Travailleur Généraliste / Généraliste) | Tout projet (rôle par défaut fondamental) | clean-codecode-reviewersystematic-debugging + compétences stack | Vert : implémentation de fonctionnalités, scripts, tests, corrections de bugs.Jaune : modification des contrats API et dépendances.Rouge : actions destructrices et modules de domaine spécialisés sans Passation. |
| Orchestration | agent-intake-dispatcher(Dispatcheur d'Entrée) | Tout projet avec 2+ rôles | prompt-engineeringbrainstorming | Vert : décomposition des demandes, préparation des prompts, exécution rapide.Rouge : modification directe du code source du projet. |
| Orchestration | agent-meta-guardian(Gardien du Méta-Projet) | Présence de structure meta-project | clean-codecode-reviewer | Vert : audit du passeport, télémétrie des rôles, maintenance de la base de connaissances.Jaune : archivage des rôles inactifs.Rouge : suppression de la base de connaissances sans confirmation utilisateur. |
| Orchestration | agent-consensus-judge(Arbitre & Juge de Consensus) | Projets avec décisions contestées | architecture-decision-recordsapi-design-principles | Vert : comparaison d'arguments, vérification empirique par tests.Jaune : rédaction d'ADR.Rouge : prise de décision sans preuve empirique. |
| Orchestration | agent-deep-auditor(Auditeur Approfondi du Dépôt) | Base de code mature (>500 lignes) | systematic-debuggingcode-reviewer | Vert : génération de rapports d'audit, détection de code mort, vérification de l'intégrité des liens/ancre.Jaune : enregistrement des constatations dans les observations.Rouge : refactorisations destructrices, suppression autonome de fichiers. |
| Produit & Business | agent-product-roaster(Analyste Produit & Évaluateur) | Services produit, startups | search_webbrainstorming | Vert : analyse concurrentielle, tests de résistance des hypothèses.Rouge : modification de la logique métier sans spécifications. |
| Produit & Business | agent-creative-director(Directeur Créatif) | Composants UI, web, thèmes, icônes | image-generatorcss-tokens | Vert : génération de palettes de couleurs, icônes, bannières.Jaune : édition des styles globaux.Rouge : remplacement de l'identité de marque sans confirmation. |
| Produit & Business | agent-ui-ux-engineer(Ingénieur UI/UX) | Frontend, bots, interfaces | semantic-htmlcss-coderui-ux-invariants | Vert : mise en page des composants, états FSM.Jaune : modifications de la navigation entre écrans.Rouge : suppression des confirmations pour des actions destructrices. |
| Produit & Business | agent-legal-compliance(Auditeur Juridique & Conformité) | LICENSE, dépôts publics | Audit SPDX/SBOM | Vert : audit des licences des dépendances.Jaune : mise à jour de NOTICE et des droits d'auteur dans les en-têtes.Rouge : modification de la licence du dépôt. |
| Ingénierie | agent-github-steward(Gourou GitHub & Capitaine des Releases) | .github/, dépôts distants git | github-managementgithub-actions-creatorclean-codecode-reviewer | Vert : hygiène Git, commits conventionnels, gestion des branches, triage des issues, brouillons de release.Jaune : vérification de la parité Code-README (s'assurer que les instructions/CLI du README correspondent au code réel), réglage CI/CD.Rouge : force-push, fusion dans main sans révision, modification des secrets. |
| Ingénierie | agent-devops-infra(Architecte Infrastructure) | Dockerfile, docker-compose* | docker-expertkubernetes-architectbash-linux | Vert : conteneurs de développement, linting de configuration.Jaune : optimisation de builds multi-étapes.Rouge : secrets de production, .env*, k8s en production. |
| Ingénierie | agent-qa-engineer(Ingénieur Fiabilité & QA) | tests/, frameworks de test | test-driven-developmentverification-before-completion | Vert : écriture de tests unitaires/d'intégration, vérification des exécutions de tests.Jaune : configuration des exécuteurs de test et assertions de contrat.Rouge : désactivation des tests dans CI. |
| Ingénierie | agent-tech-writer(Rédacteur Technique) | docs/, OpenAPI, Swagger | mermaid-diagram-specialistopenapigoogle-style-guide | Vert : documentation des fonctions, README, diagrammes.Jaune : édition des spécifications API.Rouge : publication de documentation non révisée. |
Phase 3 : Audit de l'Équipe Existante (Élagage des Rôles & Nettoyage)
Si le répertoire .agents/team/ existe déjà :
- Parcourir tous les dossiers :
.agents/team/*/profile.md. - Inspecter le tableau
Journal d'Appel des Rôles (Télémétrie)dans chaque profil. - Identifier les rôles inactifs ou obsolètes :
- Le rôle a été initialisé, mais le journal ne contient qu'une entrée initiale et aucune invocation réelle n'a eu lieu depuis >30 jours.
- La stack technologique sous-jacente du rôle a été complètement supprimée du projet (par ex., Docker a été décommissionné, mais
agent-devops-infraest resté).
- Compiler une liste de candidats à l'archivage dans
.agents/team/archive/<role_id>/. - Interdiction de suppression autonome : L'archivage des rôles nécessite l'approbation explicite de l'utilisateur !
Phase 4 : Dialogue et Alignement avec l'Utilisateur
Générer une proposition consultative concise pour l'utilisateur :
- Marqueurs détectés : Lister les composants du projet identifiés.
- Rôles recommandés à activer : Travailleur de base (
agent-general-worker) + 2–4 rôles de domaine les plus critiques correspondant aux marqueurs détectés avec de brèves justifications. - Candidats à l'archivage : (si des rôles inactifs existent).
- Invite d'approbation : "Approuvez-vous la mise en place des rôles suivants : [...] ?"
Phase 5 : Matérialisation des Profils et Enregistrement dans le Passeport
Après confirmation de l'utilisateur, effectuer l'écriture de production :
- Créer des répertoires pour chaque rôle approuvé :
.agents/team/<role_id>/. - Structurer
.agents/team/<role_id>/profile.mden utilisant le modèle de référencetemplates/team/profile.md(ou le modèle intégré ci-dessous) :- Remplir l'ID du rôle, le périmètre, les déclencheurs d'invocation, les compétences actives et les permissions de frontière.
- Initialiser le tableau de télémétrie avec la date actuelle.
- Créer un fichier de notes privé :
.agents/team/<role_id>/notes.mden utilisant le modèle de référencetemplates/team/notes.md(ou le modèle intégré ci-dessous). - Générer le prompt système initial prêt à l'emploi
.agents/team/<role_id>/system_prompt.mden utilisanttemplates/team/system_prompt.md(ou le modèle intégré ci-dessous) :- Remplir le nom du rôle, l'objectif, la pile de compétences et les permissions de frontière canoniques (Vert / Jaune / Rouge).
- Enregistrer les rôles dans la racine
AGENTS.mdsous la section :## 6. Équipe d'Agents du Projet (.agents/team/) - [{{TITRE_DU_RÔLE}}](.agents/team/{{ID_DU_RÔLE}}/profile.md) — {{PÉRIMÈTRE_DU_RÔLE}} (invoqué par : {{DÉCLENCHEURS_DU_RÔLE}}) - Générer et afficher un tableau compact de lancement rapide pour l'utilisateur sans surcharger le chat avec un long texte de prompt :
| Rôle | Objectif | Chemin du Prompt Système | Mots-clés Déclencheurs | | :--- | :--- | :--- | :--- | | `agent-qa-engineer` | Tests & vérification | `.agents/team/agent-qa-engineer/system_prompt.md` | "exécuter les tests", "vérifier la validation" |
Phase 6 : Règles d'Engagement de l'Équipe
Chaque agent de l'équipe doit adhérer aux principes de coordination fondamentaux :
- Passivité Pilotée par l'Utilisateur : Les agents n'effectuent jamais d'actions en arrière-plan sans instructions explicites de l'utilisateur.
- Passations Supervisées par l'Utilisateur : Les agents ne transfèrent pas le contrôle directement entre eux en contournant l'utilisateur. Si une tâche nécessite un autre domaine, l'agent renvoie un paquet de passation structuré à l'utilisateur :
### Paquet de Passation de Tâche : [agent-A -> agent-B] - Objectif initial : <ce qui a été demandé> - Travail effectué : <liste des fichiers touchés> - Limite de passation : <pourquoi l'agent actuel s'est arrêté> - Prompt recommandé pour agent-B : <texte du prompt prêt à l'emploi> - Limite de Chaîne de Passation : Maximum de 2 passations consécutives (sauts = 2). À la 3e étape, le contrôle doit revenir à l'humain.
- Inviolabilité des Annotations de Fichiers Partagés : Interdiction de modifier les notes des autres dans
tasks.md,observations.mdetarchitecture.md. Seul son propre statut/tâches peuvent être mis à jour. En cas de conflit, présenter une description claire du compromis à l'utilisateur. - Propriété Exclusive de
notes.md: Seul le propriétaire du rôle peut modifier.agents/team/<role>/notes.md. - Arbitrage Basé sur des Preuves :
agent-consensus-judgerend des verdicts strictement basés sur les résultats de tests, les mesures de référence et les spécifications officielles. - Délégation de Sous-Agents Parallèles (
dispatching-parallel-agents) : Lors du traitement de charges de travail répétitives, parallèles ou multi-répertoires par lots (par ex. migrations multi-fichiers, génération de plusieurs suites de tests, linting/audits en masse), les agents principaux DOIVENT invoquer le skilldispatching-parallel-agents. L'agent parent partitionne la charge de travail entre des sous-agents transitoires par répertoires ou tâches non chevauchants, en transmettant les invariants du projet depuisAGENTS.mdet les limites des rôles. L'agent parent coordonne l'achèvement, exécute des tests d'intégrité et renvoie un rapport consolidé à l'utilisateur sans alourdir l'humain avec des passations intermédiaires de sous-agents. - Coupe-Circuit (Arrêt du Travail à la 2e Itération) : Si une correction de bug nécessite une 2e modification consécutive dans le même module ou produit une régression secondaire dans le code adjacent, cesser d'écrire du code. Prendre du recul, tracer le cycle de vie complet des données de l'origine au consommateur, identifier la cause racine architecturale et présenter une analyse systémique avant de proposer un nouveau diff.
- Audit de l'État Cible : Avant de modifier des modules non triviaux dans les zones Jaune ou Rouge, déterminer : État