Skill 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 le skill principal — il couvre l'aperçu de la plateforme, les outils partagés et la configuration. Pour les workflows spécifiques à un stage, utilisez les skills dédiés listés dans Skill Routing ci-dessous.

⚠️ Espace de noms des outils sous OpenClaw. Les outils Chorus sont exposés par le serveur MCP Chorus connecté, et OpenClaw préfixe les outils sourced par MCP avec un préfixe chorus__. Partout où ce skill (ou tout skill Chorus) écrit un nom d'outil brut comme chorus_get_task, le nom réellement appelable dans votre session OpenClaw est chorus__chorus_get_task (ex. chorus_checkin → chorus__chorus_checkin, chorus_submit_for_verify → chorus__chorus_submit_for_verify). Les noms bruts sont conservés dans la doc pour la lisibilité et la parité avec la référence des outils Chorus ; prépendez chorus__ quand vous les invoquez réellement. Cette règle unique s'applique à chaque skill Chorus — elle n'est pas répétée dans chacun.

Aperçu

Workflow AI-DLC

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

Idée --> Proposition --> [Document + Task] --> Exécution --> Vérification --> Fait
 ^         ^              ^                      ^              ^            ^
Humain    Agent PM    Agent PM           Agent Dev         Admin       Admin
crée      analyse      rédige PRD        code &           examine     ferme
          & planifie   & tasks           rapporte         & vérifie

Trois Rôles

Permissions

La visibilité des outils pour chaque agent est pilotée par un ensemble de permissions, pas seulement par le libellé 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 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 read-only 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 protégés par permission.

Note: posséder task:write accorde la visibilité de l'outil, pas l'autorité inconditionnelle. Les gardes au niveau du handler garantissent toujours que seul l'assigné de la task 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 task 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. (Rappel : prépendez chorus__ quand vous invoquez — voir la note d'espace de noms ci-dessus.)

Checkin

La réponse checkin inclut les informations 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 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 le tableau projectUuids dans la configuration du plugin (voir Setup ci-dessous).

Comportement:

• Tableau vide (par défaut): Retourne tous les projets
• Un ou plusieurs UUID: Retourne seulement les projets correspondants et leurs événements

Outils affectés: chorus_checkin, chorus_get_my_assignments

Session (Sub-Agents Uniquement)

Contrairement au plugin Claude Code (qui automatise complètement le cycle de vie de la session via des hooks), OpenClaw n'exécute pas les hooks Claude Code SubagentStart / heartbeat / cleanup. La gestion des sessions est donc manuelle sur OpenClaw. Voir /develop pour le protocole de session manuelle complet. En bref, un sub-agent doit:

1. chorus_create_session — créer sa propre session une fois, près du début (ou réutiliser un sessionUuid injecté si l'hôte en a fourni un)
2. chorus_session_checkin_task — avant de commencer à travailler sur une task
3. Passer sessionUuid à chorus_update_task et chorus_report_work
4. chorus_session_checkout_task — quand terminé avec une task
5. chorus_close_session — quand le sub-agent finit (aucun hook ne le ferme pour vous)

Agent principal / Team Lead: pas de session nécessaire — appelez les outils sans sessionUuid.

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 résumé court de fin d'Idée persisted comme Document de type="report" créé via chorus_create_report (protégé par document:write). La description de l'outil porte le modèle de section — lisez-la là-bas. /yolo en écrit un obligatoirement ; /develop l'offre de façon consultative sur la dernière vérification de task.

Propositions

Tasks

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 cible
• content: Contenu du commentaire (Markdown)

Élaboration

@Mentions

Utilisez @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. Chercher : 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 /idea)
• Création/mise à jour de proposition — notifier les parties prenantes lors de la soumission
• Soumission de task — notifier PM/propriétaire pour les décisions importantes
• Problèmes bloquants — notifier la personne concernée pour une 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 de types d'entités à chercher (défaut : tous les types)

Notifications

Workflow recommandé:

1. chorus_checkin() — vérifier notifications.unreadCount
2. Si > 0, appelez chorus_get_notifications() — marque automatiquement comme lues
3. Pour jeter un œil 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 Chorus (ex. https://chorus.example.com/settings)
2. Cliquer sur Create API Key
3. Entrer le nom de l'Agent, puis soit:
   • Choisir un préset de rôle (Développeur / PM / Admin) — recommandé pour le cas courant
   • Ou choisir un préset 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é une seule fois)

Notes de sécurité:

• Chaque Agent devrait avoir sa propre Clé API avec les permissions minimales requises
• Les présets sont le chemin le plus rapide ; les permissions personnalisées vous permettent de concéder étroitement (ex. un agent dev qui a aussi besoin de idea:write pour signaler les bugs)
• Les Clés API ne doivent pas être commises au contrôle de version

2. Configuration du Plugin

Le plugin OpenClaw Chorus enregistre automatiquement le serveur MCP Chorus (streamable-http + Bearer) à partir de votre configuration du plugin. Fichier de config: ~/.openclaw/openclaw.json.

Ajoutez la configuration du plugin Chorus sous plugins.entries.chorus-openclaw-plugin.config:

{
  "plugins": {
    "entries": {
      "chorus-openclaw-plugin": {
        "enabled": true,
        "config": {
          "chorusUrl": "https://chorus.example.com",
          "apiKey": "cho_your_api_key_here",
          "projectUuids": [],
          "autoStart": true
        }
      }
    }
  }
}

Champs de configuration:

Une fois enregistré, chaque outil Chorus est accessible comme chorus__<tool_name> (le préfixe chorus__ vient de l'id du serveur MCP ; voir la note d'espace de noms en haut de ce skill).

3. Vérifier la Connexion

Après la configuration, le plugin se connecte et enregistre le serveur MCP automatiquement. Vérifiez en appelant:

chorus__chorus_checkin()

Si cela échoue, vérifiez : Clé API correcte (préfixe cho_)? URL accessible? Plugin activé dans la config? Serveur MCP affiché comme connecté dans OpenClaw?

4. Accès aux Outils par Preset

Le tableau ci-dessous montre la disponibilité par défaut des outils pour chaque preset (pas de permissions personnalisées). Les outils read-only sont disponibles pour tout le monde ; les outils protégés affichés ici nécessitent les permissions listées.

5. Consulter les Skills

Le plugin embarque trois skills de revue indépendants : /proposal-reviewer, /task-reviewer et /code-reviewer. Ils sont read-only et se terminent en postant un commentaire VERDICT: (PASS / PASS WITH NOTES / FAIL) sur la proposition/task/idée. /code-reviewer est la porte finale de ship-time : après vérification de la dernière task d'une Idée il examine le changement de code agrégé de l'Idée (la feature complète sur toutes ses tasks) et poste son VERDICT sur l'idée.

Comment s'exécute la revue sur OpenClaw. Il n'y a pas de hook PostToolUse pour injecter un rappel « spawn le reviewer » après la soumission, et OpenClaw n'a pas les définitions d'agent typées du style Claude Code. À la place, les skills proposal/develop/yolo mettent l'étape de revue inline : l'agent orchestrateur utilise l'outil OpenClaw sessions_spawn pour spawner un sub-agent et lui indique (dans la task de spawn) d'exécuter le skill /proposal-reviewer, /task-reviewer ou /code-reviewer contre l'entité (en passant le ideaUuid pour la revue de code), puis attends le VERDICT (poll subagents / sessions_yield). Les sub-agents spawnés héritent des skills du plugin, donc ces slash-commands leur sont disponibles. Si sessions_spawn est indisponible (spawning désactivé par politique), exécutez la revue vous-même comme une passe read-only focalisée suivant la procédure du skill reviewer et enregistrez le VERDICT via chorus_add_comment. Voir le skill du stage pertinent pour la procédure exacte.

Les résultats sont consultatifs — ils ne bloquent pas durement l'approbation, la vérification ou le ship (la porte de code-review est comportementale — elle ne change pas le statut stocké de l'Idée), mais vous devriez agir sur un FAIL en corrigeant les BLOCKERs listés avant de procéder. Pour un FAIL de code-review, corrigez-le via le workflow quick-dev (/quick-dev) : chorus_create_tasks avec proposalUuid défini à la proposition approuvée actuelle pour que les tasks de fix s'y attachent (ne rouvrez pas les anciennes tasks), puis exécutez → vérifiez et relancez.

Modèle Piloté par Événement SSE (Hôte Daemon Bidirectionnel)

Le plugin OpenClaw Chorus exécute un service en arrière-plan qui maintient une connexion Server-Sent Events (SSE) au serveur Chorus. C'est un hôte daemon entièrement bidirectionnel, au même niveau que le daemon CLI Chorus : ce n'est pas juste un récepteur de notifications qui réveille l'agent — il enregistre aussi une identité de connexion, rapporte son cycle de vie d'exécution au serveur, et accepte des commandes de contrôle inverse (interrupt / resume / livrer un tour d'instruction) pour qu'un humain dans l'interface Chorus puisse observer et diriger une exécution en vol. Au lieu de faire du polling, l'agent est notifié dès que quelque chose a besoin de son attention, et le serveur a toujours une vue live et contrôlable de ce que cet hôte exécute.

Entrant : les notifications réveillent l'agent

1. Le plugin se connecte au point de terminaison SSE Chorus en utilisant la Clé API configurée
2. Quand un événement de notification arrive, le plugin récupère les détails complets de la notification
3. Si projectUuids est configuré, les événements des autres projets sont filtrés
4. Le plugin résout la généalogie de l'événement et l'achemine vers l'agent (une exécution d'agent intégré en processus) avec des instructions riches en contexte
5. Si autoStart est activé, certains événements (comme task_assigned) font une réclamation automatique avant de réveiller l'agent

Identité de connexion (connection_registered)

Juste après la poignée de main SSE, le serveur assigne à ce flux une DaemonConnection et rapporte son connectionUuid via un événement de données connection_registered. Le plugin capture cet uuid (le rafraîchissant à chaque reconnexion, pour qu'un flux recyclé ne porte jamais une identité périmée) et l'utilise comme l'unique source de vérité pour « quelle connexion suis-je ». Cette identité est ce qui rend la connexion adressable : elle apparaît dans l'interface Connexions d'Agent Chorus, étend le canal de contrôle inverse, et estampille chaque rapport sortant ci-dessous.

Sortant : le daemon rapporte son cycle de vie au serveur

Pendant qu'une exécution réveillée s'exécute, le plugin rapporte en retour sur la surface REST /api/daemon/* (agnostique à l'hôte, les mêmes formes de payload que le daemon CLI envoie) pour que l'activité de la connexion soit observable dans l'interface en temps réel :

Les rapports sont fire-and-forget et ne crashent jamais l'exécution : une défaillance réseau/non-2xx est loggée avec sa cause et remontée comme un résultat de défaillance structuré, jamais silencieusement avalée.

Canal de contrôle inverse (interrupt / resume / deliver_turn)

Le serveur publie les commandes de contrôle sur un canal control:{connectionUuid} et les redirige comme événements SSE de type:"control". Ce sont des chemins forked loin du chemin d'éveil — un événement de contrôle ne peut jamais spawner une nouvelle exécution d'agent pour lui-même. Le plugin agit sur une commande seulement après une double vérification : (1) le targetConnectionUuid de la commande correspond à l'uuid propre de cette connexion (un uuid périmé/recyclé ou une commande d'une autre connexion est ignoré et loggé), et (2) pour interrupt, cet hôte tient réellement une exécution d'agent intégré en cours d'exécution pour cette entité.

Backfill en reconnexion

Après une interruption SSE, le plugin re-tire (1) les notifications non lues manquées pendant l'interruption et (2) les tours en attente non lancés de cette connexion depuis la table de tours (le filet de sécurité pour un ping deliver_turn perdu tandis que déconnecté). Les deux sources partagent un ensemble vu, pour qu'un tour soit exécuté au plus une fois sur la livraison live et le backfill.

Types d'Événement

Chaque événement inclut l'UUID de l'entité, l'UUID du projet et les infos d'acteur pour que l'agent puisse immédiatement agir sans lookups supplémentaires.

Règles d'Exécution

1. Toujours d'abord faire le checkin — Appelez chorus_checkin() au démarrage de la session
2. Les sessions sont manuelles sur OpenClaw — OpenClaw n'exécute pas les hooks de session Claude Code. Les sub-agents créent leur propre session (chorus_create_session), font checkin/checkout par task, passent sessionUuid et la ferment à la sortie. L'agent principal saute les outils de session. Voir /develop.
3. Le session checkin est sub-agent uniquement — Les sub-agents appelent chorus_session_checkin_task / chorus_session_checkout_task et passent sessionUuid. L'agent principal saute complètement les outils de session.
4. Restez dans votre rôle — Utilisez seulement 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 Tasks ; ne sautez pas les étapes
7. Configurer le DAG de dépendance de task — Utilisez dependsOnDraftUuids dans les brouillons de task pour exprimer l'ordre d'exécution
8. Vérifier avant de réclamer — Vérifiez les éléments disponibles avant de réclamer
9. Documenter les décisions — Ajoutez des commentaires expliquant votre raisonnement
10. Respectez le processus de revue — Soumettez le travail pour vérification ; ne supposez pas qu'il est terminé jusqu'à ce qu'Admin le vérifie
11. Les questions d'élaboration sont du texte brut sur OpenClaw — OpenClaw n'a pas de primitive AskUserQuestion. Présentez les questions d'élaboration comme des prompts en texte brut et collectez les réponses en texte libre (voir /idea). Dans /yolo l'agent se répond automatiquement sans aucune interaction utilisateur.
12. Vérifier les tasks du sub-agent (team lead admin) — Quand un sub-agent rapporte qu'une task est to_verify, examinez et vérifiez. Les tasks en to_verify ne débloquent PAS les tasks en aval — seul done le fait.

Référence du Cycle de Vie du Statut

Flux de Statut d'Idée

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

Flux de Statut de Task

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)

Skill Routing

Ceci est le skill de vue d'ensemble principal. Pour les workflows spécifiques à un stage, utilisez:

Démarrage

1. Appelez chorus_checkin() pour connaître votre rôle et assignations
2. Basé sur votre rôle, utilisez le skill approprié:
   • Full Auto → /yolo — donnez un prompt, l'agent gère tout (nécessite les permissions du preset Admin : write sur chaque ressource + bits admin approve/verify)
   • Agent PM → /idea puis /proposal
   • Agent Développeur → /develop
   • Agent Admin → /review (a aussi accès à tous les outils PM et Développeur)