Compétence Chorus

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

Ceci est la compétence principale — elle couvre l'aperçu de la plateforme, les outils partagés et la configuration. Pour les workflows spécifiques à chaque étape, utilisez les compétences dédiées listées dans Routage des compétences ci-dessous.

Aperçu

Workflow AI-DLC

Chorus suit le workflow AI-DLC (AI Development Life Cycle) :

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 &         examine   ferme
        & planifie      & tâches           rapporte       & vérifie

Trois rôles

Permissions

La visibilité des outils de chaque agent est gouvernée par un ensemble de permissions, non pas seulement par l'étiquette de rôle. Chorus a 5 ressources (idea, proposal, document, task, project) × 3 actions (read, write, admin) = 15 permissions. Chaque outil MCP protégé par permission déclare une seule permission requise (voir docs/MCP_TOOLS.md pour le tableau complet).

Les présets de rôle se mappent à 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 de 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 protégés par permission.

Remarque : posséder task:write accorde la visibilité des outils, non pas une autorité inconditionnelle. Les gardes au niveau du gestionnaire appliquent toujours que seul l'assignataire de la tâche peut exécuter les transitions opérationnelles comme chorus_submit_for_verify ou chorus_report_work. Un agent PM qui se trouve avoir task:write (via le preset) ne peut pas opérer sur une tâche qu'il n'a pas réclamée ou pour 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 de checkin inclut les informations de propriétaire/maître pour l'agent :

• agent.owner: { uuid, name, email } ou null — l'utilisateur humain qui possè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) en utilisant des en-têtes HTTP optionnels dans votre configuration .mcp.json :

Comportement :

• Aucun en-tête : Retourne tous les projets (par défaut, compatible avec les versions antérieures)
• 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 a la priorité si les deux en-têtes sont fournis

Outils affectés : chorus_checkin, chorus_get_my_assignments

Exemple .mcp.json (Pi découvre cela automatiquement via pi-mcp-adapter ; aucun programme d'installation nécessaire) :

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "http://localhost:8637/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_xxx",
        "X-Chorus-Project": "project-uuid-1,project-uuid-2"
      }
    }
  }
}

Session (sous-agents uniquement)

L'extension Chorus Pi automatise entièrement le cycle de vie de la session. Quand vous lancez un worker via subagent_spawn, l'extension crée automatiquement une session Chorus et la mappe à l'agentId ; quand vous subagent_manage close l'agent, elle ferme la session. Les sous-agents n'ont besoin que de :

1. chorus_session_checkin_task — avant de commencer à travailler sur une tâche
2. chorus_session_checkout_task — quand vous avez terminé une tâche
3. Passer sessionUuid à chorus_update_task et chorus_report_work

Agent principal / Chef d'équipe : aucune session requise — appelez les outils sans sessionUuid. Voir /skill:develop pour les détails.

Les sous-agents examinateurs (chorus-proposal-reviewer, chorus-task-reviewer, chorus-code-reviewer) ne reçoivent pas de session Chorus — ils sont en lecture seule et postent un commentaire VERDICT unique.

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é de fin d'idée persisté comme un document de type="report" créé via chorus_create_report (protégé par document:write). La description du paramètre content porte le modèle à trois sections (## Summary / ## Decisions / ## Follow-ups) — lisez-le là. /skill:yolo en écrit un obligatoirement ; /skill:develop l'offre de manière consultative lors de la dernière vérification de tâche ; l'extension fait un nudge si aucun des deux n'a été déclenché.

Références

Une référence est un lien de preuve externe de première classe (docs / repo / issue_pr / paper_blog) attaché à une idée / proposition / tâche via chorus_add_reference, ou en ligne à la création via le paramètre references[] sur chorus_pm_create_idea / chorus_pm_create_proposal / chorus_create_tasks. Les références se relisent en ligne via les outils chorus_get_*.

Faites-en un réflexe : dès que vous rencontrez un lien externe qui est une preuve de ce sur quoi vous travaillez — un problème/PR de précédent, une implémentation de référence, une documentation officielle, un article/blog — attachez-le, et préférez attacher en ligne à la création plutôt qu'après coup. Voir /skill:idea (Étape 4.4) pour les critères de sélection de type et un exemple travaillé.

Propositions

Tâches

Filtrage par proposition — chorus_list_tasks, chorus_get_available_tasks, et chorus_get_unblocked_tasks acceptent tous un paramètre proposalUuids optionnel (tableau de chaînes d'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 des agents spécifiques. Syntaxe de mention : @[DisplayName](type:uuid) où type est user ou agent.

Workflow de mention :

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

Quand @mentionner :

• Fin d'élaboration — confirmer la compréhension avec le répondeur avant de valider (voir /skill: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 de blocage — notifier la personne pertinente pour une entrée humaine

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 des types d'entités à rechercher (par défaut : tous les types)

Préférez chorus_search pour la découverte, y compris la recherche exacte par UUID. Utilisez les outils de liste paginés uniquement pour parcourir, puis appelez l'outil get de ressource unique correspondant pour les détails complets.

Notifications

Workflow recommandé :

1. chorus_checkin() — vérifier notifications.unreadCount
2. Si > 0, appelez chorus_get_notifications() — marque automatiquement comme lues
3. Pour regarder 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 Chorus.

Demandez à l'utilisateur de :

1. Ouvrir la page des paramètres de Chorus (par exemple, 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 (Developer / 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 devrait avoir sa propre clé API avec les permissions minimales requises
• Les presets sont le chemin le plus rapide ; les permissions personnalisées vous permettent d'accorder de manière étroite (par exemple, un agent dev qui a aussi besoin de idea:write pour signaler des bugs)
• Les clés API ne doivent pas être validées au contrôle de version

2. Configuration du serveur MCP

Pi découvre automatiquement les serveurs MCP via pi-mcp-adapter. Aucun programme d'installation n'est requis — placez un fichier .mcp.json à la racine du projet (ou ~/.pi/agent/mcp.json globalement) :

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "<BASE_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Exportez ensuite les mêmes valeurs comme variables d'environnement pour les appels de checkin/session propres de l'extension :

export CHORUS_URL=http://localhost:8637
export CHORUS_API_KEY=cho_your_key

Redémarrez Pi après la configuration (/reload ou une nouvelle session).

3. Vérifier la connexion

chorus_checkin()

Si cela échoue, vérifiez : clé API correcte (préfixe cho_) ? URL accessible ? Pi 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 tout le monde ; les outils protégés affichés ici nécessitent les permissions listées.

5. Examiner la configuration de l'agent examinateur

L'extension inclut trois agents examinateurs indépendants. Après la soumission de la proposition, la vérification de la tâche, ou la vérification de la dernière tâche d'une proposition enracinée dans une idée, l'extension vous nudge pour lancer l'examinateur via subagent_spawn. Vous devez le lancer manuellement — il n'est PAS lancé automatiquement. Tous sont activés par défaut.

Pour désactiver, exportez la variable d'environnement comme false ; pour régler le plafond de boucle du portail d'examen de code, définissez CHORUS_MAX_CODE_REVIEW_ROUNDS :

export CHORUS_ENABLE_PROPOSAL_REVIEWER=false
export CHORUS_ENABLE_TASK_REVIEWER=false
export CHORUS_ENABLE_CODE_REVIEWER=false
export CHORUS_MAX_CODE_REVIEW_ROUNDS=5   # 0 = illimité

Une fois activés, les examinateurs s'exécutent en tant que sous-agents en lecture seule et postent 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 d'examen de code en particulier est comportemental (il ne change pas le statut stocké de l'idée). En cas d'échec d'examen de code, corrigez-le via le workflow /skill:quick-dev : chorus_create_tasks avec proposalUuid défini sur la proposition approuvée actuelle pour que les tâches de correction s'y attachent. Groupez les petits BLOCKERs connexes en une seule tâche cohésive par défaut ; divisez-les uniquement pour les corrections matériellement grandes ou indépendamment testables. Chaque tâche de correction doit vérifier elle-même ses critères d'acceptation et réussir la vérification de tâche indépendante plus la vérification de l'admin. Réexécutez le portail uniquement après que chaque tâche de correction soit avec succès done ; s'il y a une tâche de correction échouée ou annulée, arrêtez et escaladez à la place. Désactiver réduit l'utilisation des tokens mais supprime le portail de qualité indépendant.

6. Activer le mode OpenSpec (optionnel)

Chemin piloté par spécification opt-in : /skill:proposal, /skill:develop, et /skill:yolo écrivent proposal.md / design.md / deltas spec sur disque et les reflètent dans les brouillons Chorus. Entièrement optionnel — l'authoring libre fonctionne sans cela. S'active uniquement quand tous les trois sont vrais : CHORUS_OPENSPEC_MODE ≠ off, un répertoire openspec/ existe à la racine du projet, et la CLI openspec est sur PATH. L'extension détecte cela à session_start et le rapporte dans le contexte injecté.

Quand l'utilisateur le souhaite activé (par exemple, ils ont exécuté /skill:chorus enable openspec après la bannière (OpenSpec off — …)), activez-le réellement pour eux — exécutez les étapes manquantes, ne les décrivez pas simplement :

npm i -g @fission-ai/openspec       # 1. installer la CLI si elle n'est pas sur PATH (globale, pur Node)
openspec init                        # 2. scaffolder openspec/ (interactif ; choisissez votre tooling d'éditeur)

Le signal OpenSpec est lu une seule fois au démarrage de la session, il ne peut donc pas basculer en session — après le succès des étapes, dites à l'utilisateur de redémarrer la session ; la bannière lit alors (OpenSpec Enabled) et les compétences d'étape incorporent automatiquement la compétence openspec-aware.

Pour l'éteindre, définissez CHORUS_OPENSPEC_MODE=off — la bannière lit alors une neutre (OpenSpec off).

Règles d'exécution

1. Toujours faire le checkin d'abord — Appelez chorus_checkin() au démarrage de la session (l'extension le fait automatiquement et injecte le résultat)
2. Les sessions sont automatiques — L'extension crée, fait les heartbeats, et ferme les sessions sur subagent_spawn / subagent_manage close. N'appelez jamais chorus_create_session ou chorus_close_session vous-même.
3. Le checkin de session est pour sous-agent uniquement — Les sous-agents appellent chorus_session_checkin_task / chorus_session_checkout_task et passent sessionUuid. L'agent principal ignore complètement les outils de session.
4. Restez dans votre rôle — N'utilisez que les outils disponibles pour votre rôle
5. Rapportez la progression — Utilisez chorus_report_work ou chorus_add_comment
6. Suivez le cycle de vie — Les idées passent par les propositions aux tâches ; ne sautez pas d'étapes
7. Configurez le DAG de dépendance des tâches — Utilisez dependsOnDraftUuids dans les brouillons de tâche pour exprimer l'ordre d'exécution
8. Vérifiez avant de réclamer — Vérifiez les éléments disponibles avant de réclamer
9. Documentez les décisions — Ajoutez des commentaires expliquant votre raisonnement
10. Respectez le processus d'examen — Soumettez le travail pour vérification ; ne supposez pas que c'est fait tant que l'admin ne le vérifie pas
11. Utilisez toujours AskUserQuestion pour l'interaction humaine — NE JAMAIS afficher les questions en texte brut ; utilisez les boutons radio interactifs (l'outil ask_user_question)
12. Fermer les sous-agents après utilisation — Pi limite les sous-agents concurrents ; après qu'un examinateur/worker termine, appelez subagent_manage close pour libérer l'emplacement. completed ne le libère pas.

Référence du cycle de vie des statuts

Flux de statut de l'idée

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

Flux de statut de la tâche

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

Flux de statut de la 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 principale d'aperçu. Pour les workflows spécifiques à chaque étape, utilisez :

Premiers pas

1. L'extension appelle automatiquement chorus_checkin() au démarrage de la session et injecte votre rôle et assignations
2. Basé sur votre rôle, utilisez la compétence appropriée :
   • Auto complet → /skill:yolo — donnez une invite, l'agent gère tout (nécessite les permissions du preset Admin : write sur chaque ressource + approuver/vérifier les bits admin)
   • Agent PM → /skill:idea puis /skill:proposal
   • Agent Développeur → /skill:develop
   • Agent Admin → /skill:review (a aussi accès à tous les outils PM et Developer)