Skill Chorus

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

Il s'agit du skill principal — il couvre l'aperçu de la plateforme, les outils partagés et la configuration. Pour les workflows spécifiques à une étape, utilisez les skills dédiés listés dans Skill Routing ci-dessous.

Aperçu

Workflow AI-DLC

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

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

Trois rôles

Permissions

La visibilité des outils de chaque agent est déterminée par un ensemble de permissions, et non par le label de rôle seul. Chorus a 5 ressources (idea, proposal, document, task, project) × 3 actions (read, write, admin) = 15 permissions. Chaque outil MCP gated déclare une seule permission requise (voir docs/MCP_TOOLS.md pour la table complète).

Les presets de rôles sont associés à des ensembles de permissions :

Les permissions personnalisées sont aussi 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 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 gated par permission.

Note : posséder task:write accorde la visibilité des outils, pas l'autorité inconditionnelle. Les gardes au niveau du handler imposent que seul l'assigné de la tâche puisse 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 claim 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 des informations et collaborer.

Checkin

La réponse de checkin inclut les informations de propriétaire/master 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 :

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

Outils affectés : chorus_checkin, chorus_get_my_assignments

Exemple .mcp.json :

{
  "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 (Sub-Agents uniquement)

Le Plugin Chorus automatise complètement le cycle de vie de la session. Les sub-agents doivent uniquement :

1. chorus_session_checkin_task — avant de commencer le travail sur une tâche
2. chorus_session_checkout_task — quand ils ont terminé une tâche
3. Passer sessionUuid à chorus_update_task et chorus_report_work

Agent principal / Team Lead : aucune session nécessaire — appeler les outils sans sessionUuid. Voir /develop pour les détails.

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 & Activité

Idées

Documents

Rapports

Un rapport est un court résumé d'accomplissement d'idée persisté comme un Document type="report" à la fin d'une Idée, rédigé via chorus_create_report (gated sur document:write). La description de l'outil porte le template de section — lisez-le là. /yolo en écrit un obligatoirement ; /develop l'offre de façon consultative sur la vérification de la dernière tâche ; un hook PostToolUse rappelle si aucun n'a tiré.

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 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.

Workflow 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 :

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

Recherche

Paramètres :

• query : Chaîne de requête de recherche
• scope : "global" (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 (défaut : tous les types)

Notifications

Workflow recommandé :

1. chorus_checkin() — vérifier notifications.unreadCount
2. Si > 0, appeler chorus_get_notifications() — marque automatiquement comme lu
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 de Chorus.

Demandez à l'utilisateur de :

1. Ouvrir la page des paramètres de 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 (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 de concéder étroitement (par ex. un agent dev qui a aussi besoin de idea:write pour déposer des bugs)
• Les clés API ne doivent pas être commises dans le contrôle de version

2. Configuration du serveur MCP

Fichier de configuration : .mcp.json à la racine du projet (ou globalement à ~/.claude/.mcp.json).

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

Redémarrez Claude Code 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 ? Claude Code a-t-il été redémarré ?

4. Accès aux outils par preset

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

5. Réviser la configuration de l'Agent

Le plugin inclut trois agents de révision 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 enracinée dans une idée, un hook PostToolUse injecte un contexte pour instruire l'agent principal de générer le réviseur. L'agent principal doit le générer manuellement — il n'est PAS auto-lancé. Tous sont activés par défaut.

Pour désactiver, reconfigurez le plugin via les paramètres /plugin ou modifiez manuellement ~/.claude/settings.json :

{
  "pluginConfigs": {
    "chorus@chorus-plugins": {
      "options": {
        "enableProposalReviewer": false,
        "enableTaskReviewer": false,
        "enableCodeReviewer": false
      }
    }
  }
}

Quand activés, les réviseurs tournent comme des sub-agents en lecture seule et postent un commentaire VERDICT sur la proposition/tâche/idée. Trois résultats possibles : PASS (pas de problèmes), 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 ; la portail de révision de code en particulier est comportemental (il ne change pas le statut stocké de l'Idée). Sur une révision de code FAIL, corrigez-la via le workflow /chorus:quick-dev : chorus_create_tasks avec proposalUuid défini sur la proposition approuvée actuelle pour que les tâches de correction s'attachent à elle, puis exécutez → vérifiez et relancez la portail. Désactiver réduit l'utilisation de tokens mais supprime la portail de qualité indépendante.

Règles d'exécution

1. Toujours checker en premier — Appelez chorus_checkin() au démarrage de la session
2. Les sessions sont automatiques — Le Plugin Chorus crée, maintient et ferme les sessions. N'appelez jamais chorus_create_session ou chorus_close_session.
3. Le checkin de session est sub-agent uniquement — Les sub-agents appelent 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 — Utilisez uniquement les outils disponibles à 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 les étapes
7. Configurez le DAG de dépendance de tâche — Utilisez dependsOnDraftUuids dans les brouillons de tâche pour exprimer l'ordre d'exécution
8. Vérifiez avant de clamer — Vérifiez les éléments disponibles avant de les clamer
9. Documentez les décisions — Ajoutez des commentaires expliquant votre raisonnement
10. Respectez le processus de révision — Soumettez le travail pour vérification ; ne supposez pas que c'est terminé jusqu'à ce que l'Admin vérifie
11. Utilisez toujours AskUserQuestion pour l'interaction humaine — N'AFFICHEZ JAMAIS les questions en texte brut ; utilisez des boutons radio interactifs
12. Vérifiez les tâches des sub-agents (admin team lead) — Quand SubagentStop notifie qu'une tâche est to_verify, examinez et vérifiez. Les tâches en to_verify NE débloquent PAS les tâches en aval — seul done le fait.

Référence du cycle de vie des statuts

Flux de statut des Idées

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

Flux de statut des Tâches

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

Flux de statut des Propositions

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

Skill Routing

Il s'agit du skill principal d'aperçu. Pour les workflows spécifiques à une étape, utilisez :

Prise en main

1. Appelez chorus_checkin() pour connaître votre rôle et vos assignations
2. En fonction de votre rôle, utilisez le skill approprié :
   • Auto complet → /yolo — donner une demande, l'agent gère tout (nécessite des permissions de preset Admin : écriture sur chaque ressource + bits admin approuver/vérifier)
   • Agent PM → /idea puis /proposal
   • Agent Developer → /develop
   • Agent Admin → /review (a aussi accès à tous les outils PM et Developer)