Compétence Chorus

Chorus est une plateforme de collaboration pour les Agents IA, permettant à plusieurs Agents (PM, Développeur, Admin) et à des humains de collaborer sur une même plateforme.

Ceci est la compétence centrale — elle couvre la vue d'ensemble de la plateforme, les outils partagés et la configuration. Pour les flux de travail spécifiques à une étape, utilisez les compétences dédiées listées dans Routage des compétences ci-dessous.

Vue d'ensemble

Flux de travail AI-DLC

Chorus suit le flux de travail AI-DLC (Cycle de Vie du Développement IA) :

Idée --> Proposition --> [Document + Tâche] --> Exécuter --> Vérifier --> Fait
  ^         ^              ^                   ^          ^         ^
Humain   Agent PM     Agent PM           Agent Dev    Admin    Admin
crée     analyse      rédige PRD         code &       revue    ferme
         & planifie   & tâches           rapporte     & vérifie

Trois rôles

Permissions

La visibilité des outils de chaque agent est déterminée par un ensemble de permissions, pas uniquement par le libellé du rôle. Chorus dispose de 5 ressources (idea, proposal, document, task, project) × 3 actions (read, write, admin) = 15 permissions. Chaque outil MCP contrôlé par permission déclare une permission requise unique (voir docs/MCP_TOOLS.md pour la table complète).

Les présets de rôle correspondent à des ensembles de permissions :

Les permissions personnalisées sont également supportées : lors de la création d'un agent, vous pouvez choisir un preset ET/OU ajouter des permissions individuelles. L'ensemble de permissions effectif est l'union. Les outils en lecture seule et de découverte (chorus_get_*, chorus_list_*, chorus_checkin, chorus_search*, commentaires, réponses d'élaboration, sessions, chorus_create_tasks, chorus_update_task) sont toujours disponibles — ils ne sont pas contrôlés par permission.

Note : posséder task:write accorde la visibilité des outils, non pas l'autorité inconditionnelle. Les gardes au niveau du gestionnaire appliquent toujours que seul l'assigné de la tâche peut exécuter les transitions opérationnelles comme chorus_submit_for_verify ou chorus_report_work. Un agent PM ayant task:write (via le preset) ne peut pas opérer sur une tâche qu'il n'a pas réclamée ou à laquelle il n'a pas été assigné.

Outils communs (tous les rôles)

Tous les rôles d'Agent peuvent utiliser les outils suivants pour interroger les informations et collaborer.

Checkin

La réponse du checkin inclut les informations du propriétaire/principal pour l'agent :

• agent.owner : { uuid, name, email } ou null — l'utilisateur humain propriétaire de cet agent
• Utilisez les infos du propriétaire pour savoir qui @mentionner pour les confirmations et approbations

Filtrage par projet

Les résultats peuvent être filtrés par projet(s) à l'aide d'en-têtes HTTP optionnels sur le serveur MCP Chorus. Ajoutez-les au bloc [mcp_servers.chorus.http_headers] dans ~/.codex/config.toml :

Comportement :

• Pas d'en-tête : Retourne tous les projets (par défaut, rétrocompatible)
• X-Chorus-Project : Retourne uniquement le(s) projet(s) spécifié(s)
• X-Chorus-Project-Group : Retourne tous les projets du groupe
• Priorité : X-Chorus-Project-Group prend la priorité si les deux en-têtes sont fournis

Outils affectés : chorus_checkin, chorus_get_my_assignments

Exemple (~/.codex/config.toml) :

[mcp_servers.chorus]
url = "<BASE_URL>/api/mcp"

[mcp_servers.chorus.http_headers]
Authorization = "Bearer cho_xxx"
X-Chorus-Project = "project-uuid-1,project-uuid-2"

Session (optionnel, port Codex)

Le port Codex est actuellement sans état : il ne crée pas automatiquement, ne maintient pas ou ne ferme pas les sessions Chorus. Codex supporte maintenant les hooks de plugin SubagentStart / SubagentStop, mais le plugin Chorus Codex ne les a pas encore intégrés à la gestion automatique du cycle de vie des sessions. Les sessions sont une tenue de registres optionnelle que vous pouvez utiliser lors de l'exécution de plusieurs workers en parallèle :

• Travail d'un seul agent — ignorez complètement les outils de session. L'état des tâches, les commentaires et les rapports de travail fonctionnent tous sans sessionUuid.
• Travail multi-agent via spawn_agent — le Team Lead appelle manuellement chorus_create_session avant de lancer les workers, passe sessionUuid dans le message initial de chaque worker, et appelle chorus_close_session après le retour de wait_agent.

Voir $develop pour le pattern multi-worker.

Groupes de projets

Les projets peuvent être organisés en Groupes de projets — un regroupement à un seul niveau qui vous permet de catégoriser les projets connexes ensemble.

Projet et Activité

Idées

Documents

Rapports

Un rapport est un court résumé d'achèvement d'idée persisté en tant que Document type="report" à la fin de l'Idée, rédigé via chorus_create_report (contrôlé par document:write). La description de l'outil contient le modèle de section — lisez-la là. $yolo en rédige un obligatoirement ; $develop l'offre de façon consultative à la dernière vérification de tâche ; un hook post-vérification le rappelle si aucun n'a été déclenché.

Propositions

Tâches

Filtrage par proposition — chorus_list_tasks, chorus_get_available_tasks et chorus_get_unblocked_tasks acceptent tous un paramètre optionnel proposalUuids (tableau de chaînes UUID de proposition).

Assignations

Commentaires

Paramètres pour chorus_add_comment :

• targetType : "idea" / "proposal" / "task" / "document"
• targetUuid : UUID de la cible
• content : Contenu du commentaire (Markdown)

Élaboration

@Mentions

Utilisez les @mentions pour notifier des utilisateurs ou agents spécifiques. Syntaxe de mention : @[DisplayName](type:uuid) où type est user ou agent.

Flux de travail de mention :

1. Recherche : chorus_search_mentionables({ query: "yifei" })
2. Écriture : @[Yifei](user:uuid-here) dans votre contenu
3. Les utilisateurs/agents mentionnés reçoivent automatiquement une notification

Quand @mentionner :

• Achèvement de l'élaboration — confirmer la compréhension avec celui qui a répondu avant de valider (voir /idea)
• Création/mise à jour de proposition — notifier les parties prenantes lors de la soumission
• Soumission de tâche — notifier le PM/propriétaire pour les décisions importantes
• Problèmes bloquants — notifier la personne pertinente pour les entrées humaines

Recherche

Paramètres :

• query : Chaîne de requête de recherche
• scope : "global" (par défaut) / "group" / "project"
• scopeUuid : UUID du groupe de projets (quand scope=group) ou UUID du projet (quand scope=project)
• entityTypes : Tableau de types d'entités à rechercher (par défaut : tous les types)

Notifications

Flux de travail recommandé :

1. chorus_checkin() — vérifier notifications.unreadCount
2. Si > 0, appeler chorus_get_notifications() — marque automatiquement comme lues
3. Pour consulter sans marquer : chorus_get_notifications({ autoMarkRead: false })

Configuration

1. Obtenir une clé API

Les clés API doivent être créées manuellement par l'utilisateur dans l'interface Web de Chorus.

Demander à l'utilisateur de :

1. Ouvrir la page des paramètres Chorus (par ex. http://localhost:8637/settings)
2. Cliquer sur Create API Key
3. Entrer le nom de l'Agent, puis soit :
   • Choisir un preset de rôle (Développeur / PM / Admin) — recommandé pour le cas courant
   • Ou choisir un preset et ajouter/supprimer des permissions individuelles (5 ressources × 3 actions = 15 permissions) pour obtenir un ensemble personnalisé précis
4. Cliquer sur créer et copier immédiatement la clé (affichée une seule fois)

Notes de sécurité :

• Chaque Agent doit avoir sa propre clé API avec les permissions minimales requises
• Les présets constituent le chemin le plus rapide ; les permissions personnalisées vous permettent d'accorder de manière restrictive (par ex. un agent dev qui a aussi besoin de idea:write pour signaler des bugs)
• Les clés API ne doivent pas être validées dans le contrôle de version

2. Configuration du serveur MCP

Codex CLI lit la configuration MCP depuis ~/.codex/config.toml (global) ou <repo>/.codex/config.toml (par projet). Ajoutez :

[mcp_servers.chorus]
url = "<BASE_URL>/api/mcp"

[mcp_servers.chorus.http_headers]
Authorization = "Bearer <your-api-key>"

Le transport est déduit de la clé url — il n'y a pas de champ type = "http" dans le schéma MCP de Codex. La clé du tableau d'en-têtes est http_headers, pas headers. Chemin plus facile : exécutez curl -sSL https://raw.githubusercontent.com/Chorus-AIDLC/Chorus/main/public/install-codex.sh | bash et il écrira ce bloc pour vous (plus le wrapper de hook).

Redémarrez Codex CLI après la configuration.

3. Vérifier la connexion

chorus_checkin()

Si cela échoue, vérifiez : la clé API est-elle correcte (préfixe cho_) ? L'URL est-elle accessible ? Codex CLI a-t-il été redémarré ?

4. Accès aux outils par preset

Le tableau ci-dessous montre la disponibilité des outils par défaut pour chaque preset (sans permissions personnalisées). Les outils en lecture seule sont disponibles pour tous ; les outils contrôlés affichés ici nécessitent les permissions listées.

5. Vérifier la configuration de l'Agent

Le plugin inclut trois agents de review indépendants. Après la soumission d'une proposition, la vérification d'une tâche, ou la vérification de la dernière tâche d'une proposition basée sur une idée, un hook PostToolUse injecte un contexte instruisant l'agent principal de lancer le reviewer. L'agent principal doit le lancer manuellement — ce n'est PAS lancé automatiquement. Tous sont activés par défaut.

Pour désactiver dans le port Codex, ouvrez /hooks et désactivez le hook PostToolUse du plugin Chorus correspondant, ou désactivez le plugin chorus@chorus-plugins entier dans ~/.codex/config.toml. Alternativement, l'agent principal peut simplement ignorer le additionalContext que le hook injecte et sauter le lancement du reviewer.

Quand ils sont activés, les reviewers s'exécutent en tant que sous-agents en lecture seule et publient un commentaire VERDICT sur la proposition/tâche/idée. Trois résultats possibles : PASS (aucun problème), PASS WITH NOTES (notes mineures non bloquantes), ou FAIL (BLOCKERs trouvés). Les résultats sont consultatifs — ils ne bloquent pas l'approbation, la vérification ou la livraison ; le portail de code-review en particulier est comportemental (il ne modifie pas le statut stocké de l'Idée). En cas d'échec de la code-review, corrigez-le via le flux quick-dev ($quick-dev) : chorus_create_tasks avec proposalUuid défini à la proposition approuvée actuelle pour que les tâches de correction s'y attachent, puis exécutez → vérifiez et relancez le portail. La désactivation réduit l'utilisation de tokens mais supprime le portail de qualité indépendant.

Règles d'exécution

1. Toujours vérifier d'abord — Appeler chorus_checkin() au démarrage de la session
2. Les sessions sont optionnelles (port Codex) — Le port Codex ne crée pas automatiquement les sessions. Travail d'un seul agent : ignorez complètement les outils de session. Travail multi-agent via spawn_agent : l'agent principal appelle chorus_create_session avant de lancer les workers, passe sessionUuid dans le message initial du worker, et appelle chorus_close_session après le retour du worker. L'état des tâches, les rapports de travail et les commentaires fonctionnent tous sans session — les sessions ne font qu'ajouter l'observabilité par worker.
3. Rester dans votre rôle — N'utilisez que les outils disponibles pour votre rôle
4. Rapporter la progression — Utilisez chorus_report_work ou chorus_add_comment
5. Suivre le cycle de vie — Les Idées circulent via les Propositions aux Tâches ; ne sautez pas les étapes
6. Configurer le DAG de dépendance des tâches — Utilisez dependsOnDraftUuids dans les brouillons de tâche pour exprimer l'ordre d'exécution
7. Vérifier avant de réclamer — Vérifier les articles disponibles avant de les réclamer
8. Documenter les décisions — Ajouter des commentaires expliquant votre raisonnement
9. Respecter le processus de review — Soumettre le travail pour vérification ; ne supposez pas que c'est fait jusqu'à ce que l'Admin vérifie
10. Questions interactives — Pour les confirmations/choix, envoyez une question en texte brut ; Codex ne livre actuellement pas d'outil bouton radio structuré en mode par défaut
11. Vérifier les tâches de sous-agent (chef d'équipe admin) — Après le retour d'un worker lancé via spawn_agent, vérifiez si sa tâche est to_verify et montez la compétence de reviewer dans un sous-agent par défaut : spawn_agent(agent_type="default", items=[{type:"skill", path:"chorus:chorus-task-reviewer"}, {type:"text", text:"Review task <uuid>."}]). Codex 0.125 ne livre que trois rôles intégrés (default / explorer / worker) ; les agent_types personnalisés sont rejetés. Les tâches en to_verify ne débloquent PAS les aval — seul done le fait.

Référence du cycle de vie des statuts

Flux de statut d'Idée

open --> elaborating --> proposal_created --> completed
  \                                            /
   \--> closed <------------------------------/

Flux de statut de Tâche

open --> assigned --> in_progress --> to_verify --> done
  \                                                 /
   \--> closed <-----------------------------------/
         ^                    |
         |                    v
         +--- (reopen) -- in_progress

Flux de statut de Proposition

draft --> pending --> approved
                 \-> rejected --> revised --> pending ...
approved --> draft  (via revoke — cascade-closes tasks, deletes documents)

Routage des compétences

Ceci est la compétence d'aperçu central. Pour les flux de travail spécifiques à une étape, utilisez :

Démarrage

1. Appeler chorus_checkin() pour connaître votre rôle et vos assignations
2. En fonction de votre rôle, utilisez la compétence appropriée :
   • Auto complet → $yolo — donner un prompt, l'agent gère tout (nécessite les permissions du preset Admin : écriture sur chaque ressource + bits admin d'approbation/vérification)
   • Agent PM → /idea puis /proposal
   • Agent Développeur → /develop
   • Agent Admin → /review (a également accès à tous les outils PM et Développeur)