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.

Ceci est le skill fondamental — il couvre l'aperçu de la plateforme, les outils partagés et la configuration. Pour les workflows spécifiques aux étapes, 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) :

Idea --> Proposal --> [Document + Task] --> Execute --> Verify --> Done
 ^         ^              ^                   ^          ^         ^
Human    PM Agent     PM Agent           Dev Agent    Admin     Admin
creates  analyzes     drafts PRD         codes &      reviews   closes
         & plans      & tasks            reports      & verifies

Trois rôles

Permissions

La visibilité des outils de chaque agent est déterminée par un ensemble de permissions, non par le label du rôle seul. Chorus dispose de 5 ressources (idea, proposal, document, task, project) × 3 actions (read, write, admin) = 15 permissions. Chaque MCP tool avec gate de permission déclare une seule permission requise (voir docs/MCP_TOOLS.md pour le tableau complet).

Les presets 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 découverte (chorus_get_*, chorus_list_*, chorus_checkin, chorus_search*, comments, elaboration answers, sessions, chorus_create_tasks, chorus_update_task) sont toujours disponibles — ils ne sont pas soumis à un gate de permission.

Note : posséder task:write accorde la visibilité des tools, non l'autorité inconditionnelle. Les gardes au niveau du handler 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 qui possède task:write (via le preset) ne peut pas opérer sur une tâche qu'il n'a pas claimée ou à laquelle il n'a pas été assigné.

Common Tools (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 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 l'info 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 (par défaut, rétro-compatible)
• X-Chorus-Project : Retourne seulement 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

Tools affectés : chorus_checkin, chorus_get_my_assignments

Exemple .mcp.json (Pi auto-découvre ceci via pi-mcp-adapter ; aucun installer requis) :

{
  "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 seulement)

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

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

Agent principal / Team Lead : aucune session requise — appelez les tools sans sessionUuid. Voir /skill:develop pour plus de détails.

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

Project Groups

Les projets peuvent être organisés en Project Groups — un regroupement de niveau unique qui vous permet de catégoriser les projets connexes ensemble.

Project & Activity

Ideas

Documents

Reports

Un report est un court résumé d'achèvement d'idea persisté en tant que document type="report" à la fin d'une idea, créé via chorus_create_report (gatée sur document:write). La description du paramètre content porte le template à trois sections (## Summary / ## Decisions / ## Follow-ups) — lisez-le là. /skill:yolo en écrit un obligatoirement ; /skill:develop l'offre de manière consultatif à la dernière vérification de tâche ; l'extension pousse si aucun ne s'est déclenché.

References

Une reference est un lien de preuve externe de première classe (docs / repo / issue_pr / paper_blog) attaché à une idea / proposal / task via chorus_add_reference, ou inline à la création via le paramètre references[] sur chorus_pm_create_idea / chorus_pm_create_proposal / chorus_create_tasks. Les references se relisent inline via les tools chorus_get_*.

Que ce soit un réflexe : dès que vous rencontrez un lien externe qui est une preuve de ce sur quoi vous travaillez — un issue/PR de précédent, une implémentation de référence, des docs officielles, un paper/blog — attachez-le, et préférez attacher inline à la création plutôt qu'après coup. Voir /skill:idea (Étape 4.4) pour les critères de sélection des types et un exemple travaillé.

Proposals

Tasks

Filtrage par proposal — 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 proposal).

Assignments

Comments

Paramètres pour chorus_add_comment:

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

Elaboration

@Mentions

Utilisez @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. 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 faire une @mention:

• Achèvement de l'élaboration — confirmer la compréhension avec le répondant avant validation (voir /skill:idea)
• Création/mise à jour de proposal — notifier les parties prenantes lors de la soumission
• Soumission de tâche — notifier PM/propriétaire pour les décisions significatives
• Problèmes de blocage — notifier la personne pertinente pour des entrées humaines

Search

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

Workflow recommandé:

1. chorus_checkin() — vérifier notifications.unreadCount
2. Si > 0, appeler chorus_get_notifications() — marque automatiquement comme lues
3. Pour jeter un coup d'œil sans marquer : chorus_get_notifications({ autoMarkRead: false })

Configuration

1. Obtenir une API Key

Les API Keys 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 ex. http://localhost:8637/settings)
2. Cliquer sur Create API Key
3. Entrer le nom de l'agent, puis soit :
   • Choisir un role preset (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 créer et copier immédiatement la clé (affichée une seule fois)

Notes de sécurité:

• Chaque agent doit disposer de sa propre API Key avec les permissions minimales requises
• Les presets sont le chemin le plus rapide ; les permissions personnalisées vous permettent d'accorder étroitement (ex. un dev agent qui a aussi besoin de idea:write pour signaler des bugs)
• Les API Keys ne doivent pas être validées dans le contrôle de version

2. Configuration du MCP Server

Pi auto-découvre les MCP servers via pi-mcp-adapter. Aucun installer n'est requis — placez un .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>"
      }
    }
  }
}

Puis exportez les mêmes valeurs en variables env pour les appels checkin/session de l'extension :

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

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

3. Vérifier la connexion

chorus_checkin()

Si ça échoue, vérifiez : API Key correcte (préfixe cho_) ? URL accessible ? Pi redémarré ?

4. Accès aux tools par preset

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

5. Examiner la configuration de l'agent

L'extension inclut trois agents reviewers indépendants. Après la soumission de la proposal, la vérification de la tâche, ou la vérification du dernier travail d'une proposal enracinée dans une idea, l'extension vous pousse à lancer le reviewer via subagent_spawn. Vous devez le lancer manuellement — il ne s'auto-lance PAS. Tous sont activés par défaut.

Pour désactiver, exportez la variable env comme false ; pour régler le cap de la boucle de la passerelle code-review, 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é

Quand activé, les reviewers tournent comme des sub-agents en lecture seule et postent un commentaire VERDICT sur la proposal/task/idea. 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 passerelle code-review en particulier est comportementale (elle ne change pas le statut stocké de l'idea). Sur un FAIL code-review, corrigez via le workflow /skill:quick-dev : chorus_create_tasks avec proposalUuid défini à la proposal approuvée actuelle pour que les tâches de correction s'attachent à elle, puis exécutez → vérifiez et relancez la passerelle. Désactiver réduit l'utilisation de tokens mais supprime la passerelle de qualité indépendante.

6. Activer OpenSpec Mode (Optionnel)

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

Quand l'utilisateur la veut activée (ex. il a exécuté /skill:chorus enable openspec après la bannière (OpenSpec off — …)), activez-la vraiment pour lui — exécutez les étapes manquantes, ne les décrivez pas simplement :

npm i -g @fission-ai/openspec       # 1. installer le CLI s'il n'est pas sur PATH (global, 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, donc il ne peut pas basculer en cours de session — après que les étapes réussissent, dites à l'utilisateur de redémarrer la session ; la bannière lit alors (OpenSpec Enabled) et les stage skills plient dans le skill openspec-aware automatiquement.

Pour le désactiver, définissez CHORUS_OPENSPEC_MODE=off — la bannière lit alors un neutre (OpenSpec off).

Règles d'exécution

1. Toujours vérifier 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, heartbeat, et ferme les sessions sur subagent_spawn / subagent_manage close. Ne jamais appeler chorus_create_session ou chorus_close_session vous-même.
3. Session checkin est sub-agent seulement — Les sub-agents appellent chorus_session_checkin_task / chorus_session_checkout_task et passent sessionUuid. L'agent principal ignore entièrement les session tools.
4. Restez dans votre rôle — Utilisez seulement les tools disponibles pour votre rôle
5. Rapportez la progression — Utilisez chorus_report_work ou chorus_add_comment
6. Suivez le cycle de vie — Les ideas s'écoulent via proposals aux tasks ; ne sautez pas d'é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 claim — Vérifiez les items disponibles avant de les claim
9. Documentez les décisions — Ajoutez des commentaires expliquant votre raisonnement
10. Respectez le processus de review — Soumettez le travail pour vérification ; ne présumez pas qu'il est fait jusqu'à ce que l'Admin le vérifie
11. Toujours utiliser AskUserQuestion pour l'interaction humaine — NE JAMAIS afficher les questions en texte brut ; utilisez les boutons radio interactifs (le tool ask_user_question)
12. Fermez les sub-agents après utilisation — Pi limite les sub-agents concurrents ; après qu'un reviewer/worker finisse, appelez subagent_manage close pour libérer le slot. completed ne le libère pas.

Référence du cycle de vie du statut

Flux de statut d'idea

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 proposal

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

Skill Routing

Ceci est le skill aperçu fondamental. Pour les workflows spécifiques aux étapes, utilisez :

Démarrage

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 le skill approprié :
   • Full Auto → /skill:yolo — donnez un prompt, l'agent gère tout (nécessite les permissions de preset Admin : write sur chaque ressource + bits admin d'approbation/vérification)
   • Agent PM → /skill:idea puis /skill:proposal
   • Agent Developer → /skill:develop
   • Agent Admin → /skill:review (a également accès à tous les PM et Developer tools)