metalicjames/teamwork

Orchestration Multi-Agents Teamwork (/teamwork)

Teamwork coordonne une équipe collaborative de sous-agents spécialisés à contexte frais pour réaliser de grands projets de génie logiciel, des migrations multi-fichiers, des simulations systèmes, des critiques rigoureuses de documents et des preuves mathématiques.

Au lieu de surcharger un seul contexte de conversation ou de permettre à un agent implémenteur de s'autocertifier un travail incomplet, Teamwork divise chaque exécution en deux phases strictes :

1. Phase 1 : Cadrage et Spécification de la Tâche (Entretien de Cadrage) — Clarifie le périmètre, définit des exigences observables (quoi, pas comment), établit une vérification indépendante par programme ou par grille d'évaluation, mappe les restrictions de raccourcis à un Mode d'Intégrité (development, demo, benchmark), définit le répertoire de travail du projet et produit un artefact de prompt révisable (prompt_draft.md) nécessitant une approbation explicite de l'utilisateur.
2. Phase 2 : Exécution Autonome (Passages de Relais Structurés et Portes Adversaires) — Une fois approuvé, Project Sentinel enregistre ORIGINAL_REQUEST.md, exécute des vérifications de dépendances avant vol, achemine vers l'Orchestrateur spécialisé pour la voie d'exécution choisie, coordonne les Explorateurs et Travailleurs parallèles avec une propriété de fichier exclusive et un isolement de l'espace de travail par agent, impose des portes de vérification indépendantes (Critique, Contestataire, Auditeur) à chaque étape, et bloque la finalisation jusqu'à ce qu'un Auditeur de Victoire de bout en bout (VICTORY CONFIRMED) soit passé.

---

Délégation Multi-Harnais et Mappage d'Outils

Teamwork est indépendant du harnais. Mappez chaque action abstraite ci-dessous aux outils natifs de votre harnais d'agent actuel (voir references/harness-delegation.md pour tous les détails) :

Opération Abstraite	Harnais Natif / Outil	Claude Code / Cowork	Codex / ChatGPT Work	Cursor / omp / Autres Harnais
Générer un Sous-Agent Frais	invoke_subagent (avec TypeName, Role, Prompt)	Agent (Task) outil	spawn_agent (fork_context: false ou fork_turns: "none")	outil task / sous-agent natif (contexte propre)
Définir un Sous-Agent Personnalisé	define_subagent (ou agents/*.md)	./skills/ ou agents/*.md	Le sous-agent à usage général lit agents/*.md	Charger agents/*.md ou passer le chemin du fichier persona dans le prompt
Envoyer un Message / Réveiller un Sous-Agent	send_message	Reprendre/envoyer un nouvel Agent avec l'état de l'artefact	send_message / wait	Passer l'état d'artefact mis à jour à un nouveau sous-agent
Question Structurée à l'Utilisateur	ask_question	AskUserQuestion (ou chat simple)	Outil de question structurée (ou chat simple)	Outil de question structurée ou question en texte simple
Vérification Périodique de l'Avancement	schedule (CronExpression)	Vérifier entre les envois d'étapes	Vérifier entre les envois d'étapes	Vérifier entre les envois d'étapes

Résolution des Personas Sous-Agents : Tous les personas des sous-agents Teamwork sont définis dans agents/<nom-persona>.md (relatif à ce répertoire de compétence ou à la racine du plugin ../../agents/<nom-persona>.md).

• Si votre harnais enregistre des sous-agents nommés à partir de agents/, invoquez le sous-agent par son name de frontmatter (par exemple, teamwork-sentinel, teamwork-interviewer, teamwork-orchestrator, teamwork-swe-light, teamwork-doc-orchestrator, teamwork-proof-orchestrator, teamwork-colosseum, teamwork-explorer, teamwork-worker, teamwork-critic, teamwork-challenger, teamwork-auditor, teamwork-victory-auditor, teamwork-dependency-auditor).
• Si votre harnais n'enregistre pas de sous-agents nommés, enregistrez-les dynamiquement à l'exécution (par exemple, via define_subagent) ou générez un sous-agent à contexte frais à usage général et demandez-lui de lire agents/<nom-persona>.md comme son persona système avant de commencer sa tâche.
• Si votre harnais ne peut pas imbriquer des sous-agents (sous-agents générant des sous-agents), l'agent principal agit à la fois comme Sentinel et Orchestrateur, envoyant les Explorateurs, Travailleurs, Critiques, Contestataires, Auditeurs et l'Auditeur de Victoire directement comme sous-agents plats de profondeur 1 tout en préservant tous les passages d'artefacts et les limites de contexte frais.

---

Voies d'Exécution et Table de Routage

Teamwork sélectionne automatiquement l'architecture d'équipe, la profondeur de vérification et le rôle d'orchestrateur en fonction du travail décrit dans le prompt approuvé (voir references/orchestration-patterns.md) :

Voie d'Exécution	Persona Orchestrateur	Idéal Pour	Déclencheur / Signal d'Opt-In	Audit de Dépendances Avant Vol ?	Audit Final de Victoire
1. Modèle Projet (Génie Logiciel Général Distribué)	teamwork-orchestrator (agents/teamwork-orchestrator.md)	Génie logiciel multi-fichiers, refactoring à grande échelle, simulation système et développement à partir de zéro.	Par défaut (sélectionné automatiquement pour les tâches multi-composants ou multi-fichiers).	Oui (teamwork-dependency-auditor)	teamwork-victory-auditor
2. Génie Logiciel Léger (Affinage Séquentiel)	teamwork-swe-light (agents/teamwork-swe-light.md)	Un changement autonome — une correction de bogue localisée, une petite fonctionnalité ou un refactoring contenu (4 Règles Strictes).	Signal explicite dans le prompt (par exemple, "garde-le petit", "garde-le ciblé", "exécute-le comme un changement contenu").	Oui (teamwork-dependency-auditor)	teamwork-victory-auditor
3. Révision de Document (document_review)	teamwork-doc-orchestrator (agents/teamwork-doc-orchestrator.md)	Critique multi-angle, arbres de révision RSA, et synthèse d'articles, RFC et documents de conception.	Demandes de révision (par exemple, "révise cet article", "critique ce document de conception").	Non	teamwork-victory-auditor (mode Révision de Document)
4. Mathématiques / Preuve (proof)	teamwork-proof-orchestrator (agents/teamwork-proof-orchestrator.md)	Résolution de problèmes mathématiques, dérivations de lemmes en 5 phases et démonstration de théorèmes.	Prompts mathématiques (par exemple, "prouve le théorème X", "dérive et vérifie les bornes mathématiques").	Optionnel (si CAS/Lean/Python nécessaire)	Vérificateur de preuve intégré au pipeline + teamwork-victory-auditor
5. Mathématiques / Preuve — Grande Équipe (colosseum)	teamwork-colosseum (agents/teamwork-colosseum.md)	Réseaux de tournois à grande échelle pour les conjectures difficiles, la recherche de contre-exemples et l'optimisation combinatoire.	Signal d'échelle explicite (par exemple, "Utilise une très grande équipe d'agents").	Optionnel (si des outils de calcul sont nécessaires)	teamwork-victory-auditor (mode Preuve/Colosseum)

---

Modes d'Intégrité

Teamwork applique un des trois modes d'intégrité internes pour aligner la rigueur de vérification avec les exigences du projet. Pendant l'entretien de la Phase 1, demandez à l'utilisateur quels raccourcis doivent être interdits (sans exposer les noms de mode interne dans la question) et mappez sa réponse au mode correspondant dans l'artefact de prompt :

Mode d'Intégrité	Objectif	Pratiques Autorisées	Limites Opérationnelles / Raccourcis Interdits	Application par l'Auditeur
development (Par défaut)	Itération rapide	Réutilisation de code, bibliothèques tierces et frameworks préconstruits autorisés.	Fabriquer des sorties, retourner des implémentations façade/souche, ou simuler/contrefaire la réussite des tests.	Signale les sorties fabriquées, les réussites de tests simulées/contrefaites et les souches non implémentées.
demo	Présentation reproductible	Bibliothèques standard et utilitaires généraux autorisés ; la logique principale doit être réellement implémentée.	Toutes les interdictions de development plus : copier la logique principale à partir de l'open source, déléguer le travail principal à des outils/binaires externes, et lire le code source des tests / oracles pour rétro-ingénierer le comportement attendu.	Audite les importations, les appels de sous-processus et l'accès git/fichiers pour s'assurer que la logique principale est originale et que les oracles de test n'ont pas été rétro-ingéniérés.
benchmark	Évaluation approfondie	Implémentation entièrement indépendante, à partir de zéro, en utilisant uniquement la bibliothèque standard du langage.	Toutes les interdictions de demo plus : utiliser des bibliothèques tierces ou des frameworks externes pour l'implémentation.	Rigueur maximale : rejette toute dépendance non standard, toute délégation externe, tout oracle, et valide les sorties d'exécution de vérité terrain avec un veto binaire.

---

Phase 1 : Cadrage et Spécification de la Tâche (Entretien de Cadrage)

Avant de générer l'équipe d'exécution, alignez-vous avec l'utilisateur sur ce qui doit être construit et comment cela sera vérifié indépendamment. Lisez references/interview-protocol.md pour tous les détails et cas limites.

Principe Fondamental : Définir les Objectifs et les Invariants Observables, Pas la Mécanique Interne

Ne prescrivez pas de hiérarchies de classes internes, de répartitions de fichiers ou d'algorithmes d'implémentation dans l'artefact de prompt, sauf si l'utilisateur les exige explicitement. Sur-contraindre comment empêche les Explorateurs et les Travailleurs de s'adapter aux contraintes réelles de la base de code ; sous-spécifier la vérification permet aux agents de s'autocertifier un travail incomplet.

Le Protocole de Cadrage en 9 Étapes

1. Étape 1 — Prise en Charge & Triage :
   • Inspectez la demande initiale /teamwork de l'utilisateur et tous les fichiers référencés dans l'espace de travail. Prenez en charge le paramètre [skip-interview] pour passer directement à la Phase 2 ; enregistrez les paramètres entre crochets non reconnus comme ignorés.
   • Identifiez ce qui est déjà clair vs. ce qui manque dans les catégories : (a) Périmètre & Objectif, (b) Opt-ins de Voie d'Exécution, (c) Limites Opérationnelles / Mode d'Intégrité, (d) Vérification & Critères d'Acceptation, et (e) Répertoire de Travail.
   • Respectez la concentration de l'utilisateur : Minimisez les allers-retours avec l'utilisateur en regroupant toutes les demandes nécessaires dans un seul questionnaire ciblé (ou au maximum deux dans des domaines très multifacettes). Utilisez ask_question lorsque les choix sont discrets, ou des questions numérotées claires dans le chat.
2. Étape 2 — Périmètre, Objectif & Opt-ins de Voie d'Exécution :
   • Clarifiez l'objectif du livrable : showcase / demo, production, eval / benchmark, ou exploration / research.
   • Capturez les opt-ins explicites (par exemple "garde-le petit et ciblé" ou "Utilise une très grande équipe d'agents") dans la phrase d'ouverture de l'artefact de prompt.
3. Étape 3 — Restrictions de Raccourcis & Mappage du Mode d'Intégrité :
   • Suscitez les contraintes de l'utilisateur sur la copie open source, la délégation CLI externe, l'observation des oracles et les bibliothèques tierces.
   • Mappez à development, demo, ou benchmark.
4. Étape 4 — Exigences (R1, R2, ...) :
   • Rédigez des blocs d'exigences modulaires décrivant le comportement observable, les entrées/sorties, les invariants et les contraintes — ce que le livrable doit faire, pas comment le coder.
5. Étape 5 — Vérification Indépendante & Tests sur Deux Pistes :
   • Les agents logiciels autonomes ont tendance à revendiquer prématurément l'achèvement en l'absence de vérification exécutable externe. Établissez des critères d'acceptation sans ambiguïté, basés sur des tests automatisés reproductibles qui s'exécutent de manière fiable et résistent aux simulations de réussite.
   • Pour les projets de génie logiciel de voie générale, exigez l'Architecture de Test sur Deux Pistes, où une suite de tests indépendante satisfait la formule de niveau minimum : $$\text{Total Minimum de Tests} \ge 11N + \max\left(5, \left\lfloor \frac{N}{2} \right\rfloor\right)$$
6. Étape 6 — Critères d'Acceptation :
   • Convertissez les vérifications de contrôle en éléments - [ ] cochables, groupés par catégorie sous ## Critères d'Acceptation.
7. Étape 7 — Contraintes d'Infrastructure (Conditionnel) :
   • Spécifiez les limites d'API/système de fichiers contrôlées uniquement en cas de contraintes de bac à sable ou de tâches externes.
8. Étape 8 — Répertoire de Travail du Projet :
   • Base de code existante : utilisez le répertoire existant (ne demandez pas). Nouveau projet : demandez, par défaut à ~/teamwork_projects/<nom_du_projet>.
9. Étape 9 — Assembler, Valider et Demander l'Approbation :
   • Écrivez prompt_draft.md en utilisant le schéma standard et présentez le texte complet directement à l'utilisateur dans le chat.
   • Présentez la voie anticipée : "Exécution anticipée via la voie d'ingénierie générale multi-étapes ; veuillez indiquer si vous préférez un changement unique et léger."
   • ARRÊTEZ-VOUS et attendez l'approbation explicite de l'utilisateur avant de commencer la Phase 2.

---

Phase 2 : Exécution Autonome (Protocole Sentinel & Orchestrateur)

Une fois que l'utilisateur a explicitement approuvé l'artefact de prompt, passez immédiatement en mode PROJECT SENTINEL. Lisez references/orchestration-patterns.md, references/verification-gates.md et references/operational-protocols.md.

Responsabilités Principales du Sentinel

En tant que Sentinel (agents/teamwork-sentinel.md), vous êtes le gardien permanent du projet de plus haut niveau. Vous NE DEVEZ PAS écrire de code de production, déboguer des détails d'implémentation ou prendre des décisions techniques de bas niveau vous-même — gardez votre contexte ultra-léger pour superviser l'ensemble du cycle de vie du projet.

Responsabilité 1 : Ingestion de Base & Persistance de la Demande

1. Assurez-vous que le Répertoire de travail cible existe (par exemple, mkdir -p <working_dir>/.teamwork/scratch).
2. Écrivez l'artefact de prompt approuvé textuellement dans <working_dir>/ORIGINAL_REQUEST.md (vérité de terrain immuable).
3. Initialisez <working_dir>/BRIEFING.md pour suivre la voie d'exécution active, les ID des sous-agents, l'étape actuelle et les invariants d'état.

Responsabilité 2 : Surveillance Autonome de la Santé et de l'Avancement

1. Planifiez un moniteur périodique non intrusif via schedule (ou des transitions de tour) pour scanner <working_dir>/PROGRESS.md et suivre les battements de cœur de vivacité (Dernière visite : [horodatage]).
2. Fournissez des résumés d'avancement concis et factuels à l'utilisateur sans déverser les journaux bruts dans le chat.

Responsabilité 3 : Audit de l'Environnement & Routage de la Voie d'Exécution

1. Sélectionnez la voie d'exécution à partir de la Table des Voies d'Exécution et de Routage.
2. Audit de Dépendances Avant Vol (Bloquant) :
   • Pour les exécutions de génie logiciel général, génie logiciel léger ou mathématiques nécessitant des chaînes d'outils locales, générez teamwork-dependency-auditor (agents/teamwork-dependency-auditor.md).
   • Sur READY : Générez l'Orchestrateur de la voie désignée.
   • Sur MISSING