Développer une Compétence

Cette compétence couvre l'étape de Développement du workflow AI-DLC : réclamer des Tâches, écrire du code, signaler la progression, soumettre pour vérification et gérer les sessions pour l'observabilité des sous-agents.

Aperçu

Les Agents Développeur prennent les Tâches créées par les Agents PM (via /proposal) et les transforment en code fonctionnel. Chaque tâche suit :

claim --> in_progress --> report work --> self-check AC --> submit for verify --> Admin /review

Pour l'exécution parallèle multi-agents, Chorus s'intègre aux Claude Code Agent Teams (mode swarm) avec une observabilité complète basée sur les sessions.

Outils

Cycle de vie des tâches :

Signalisation du travail :

Critères d'acceptation :

Session (sous-agents uniquement — l'agent principal ignore ces outils) :

Sous-agents : toujours passer sessionUuid à chorus_update_task et chorus_report_work pour l'attribution. Agent principal / Chef d'équipe : appeler ces outils sans sessionUuid — aucune session nécessaire.

Outils partagés (checkin, query, comment, search, notifications) : voir /chorus

Workflow

Étape 1 : Se connecter

chorus_checkin()

Examiner votre persona, les assignations actuelles et les nombres de travaux en attente.

Étape 1.5 : Obtenir votre session (sous-agents uniquement)

Ignorer si vous êtes l'agent principal ou le Chef d'équipe.

Si vous êtes un sous-agent, le Plugin Chorus crée automatiquement votre session — rechercher une section « Chorus Session » dans vos rappels système contenant votre sessionUuid. La conserver pour toutes les opérations de tâche.

Étape 2 : Trouver du travail

chorus_get_available_tasks({ projectUuid: "<project-uuid>" })

Ou vérifier les assignations existantes :

chorus_get_my_assignments()

Étape 3 : Réclamer une tâche

chorus_get_task({ taskUuid: "<task-uuid>" })  # Review first
chorus_claim_task({ taskUuid: "<task-uuid>" })

Vérifier : description, critères d'acceptation, priorité, story points, proposition/documents associés.

Étape 4 : Recueillir le contexte

Chaque tâche et proposition inclut un champ commentCount — l'utiliser pour décider quelles entités ont des discussions valant la peine d'être lues.

1. Lire la tâche et identifier les dépendances :

   chorus_get_task({ taskUuid: "<task-uuid>" })

   Porter attention à dependsOn (tâches amont) et commentCount.

2. Lire les commentaires de la tâche (contient les rapports de travail précédents, la progression, les retours) :

   chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })

3. Examiner les tâches de dépendance amont — votre travail repose probablement sur le leur :

   chorus_get_task({ taskUuid: "<dependency-task-uuid>" })
   chorus_get_comments({ targetType: "task", targetUuid: "<dependency-task-uuid>" })

   Rechercher : fichiers créés, contrats API, interfaces, compromis.

4. Lire la proposition d'origine pour l'intention de conception :

   chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "documents" })

   (chorus_get_proposal utilise par défaut section: "basic" — métadonnées seulement + index brouillon. Passer section: "documents" pour les docs de conception, ou section: "full" pour docs + brouillons de tâche.)

5. Lire les documents du projet (PRD, tech design, ADR) :

   chorus_get_documents({ projectUuid: "<project-uuid>" })

Flux de mise à jour de document (mode OpenSpec) : si la description de la proposition d'origine contient une ligne OpenSpec change slug: <slug>, les Documents PRD / tech_design / spec du projet sont des miroirs de fichiers sous openspec/changes/<slug>/. Pour mettre à jour un tel Document (par exemple clarifier un AC, corriger un scénario spec avant de resoumettres), charger la compétence openspec-aware à .claude/skills/openspec-aware/SKILL.md et suivre §3.8 : modifier d'abord le fichier .md local, puis le refléter via le wrapper chorus-api.sh avec json_encode_file et chorus_check_response.

⛔ Ne pas appeler chorus_pm_update_document directement du harnais MCP avec un champ content saisi manuellement en mode OpenSpec. Le fichier local est la source de vérité ; le contenu saisi par l'agent dévie et brûle les tokens (openspec-aware §2 Rule 1).

Quand la DERNIÈRE tâche d'une idée OpenSpec est vérifiée, le hook PostToolUse du plugin injecte un rappel d'archivage (openspec-aware §3.9) — exécuter openspec archive <slug> --yes, puis refléter chaque openspec/specs/<capability>/spec.md émis via §3.8.

En repli sans-OpenSpec (pas de ligne slug, ou pas de CLI openspec), modifier le contenu du Document directement via l'outil MCP existant sans wrapper, pas d'étape fichier local.

Étape 5 : Commencer à travailler

Sous-agent : se connecter d'abord à la tâche :

chorus_session_checkin_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })

Puis marquer comme in-progress :

# Sous-agent :
chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress", sessionUuid: "<session-uuid>" })

# Agent principal :
chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress" })

Application des dépendances : Si cette tâche a des dépendances non résolues (tâches dependsOn non dans done ou closed), l'appel sera rejeté avec des infos détaillées de blocage. Utiliser chorus_get_unblocked_tasks pour trouver les tâches sur lesquelles vous pouvez commencer maintenant.

Étape 6 : Signaler la progression

Signaler régulièrement avec chorus_report_work. Inclure :

• Ce qui a été complété
• Fichiers créés ou modifiés
• Commits Git et PRs
• Statut actuel / travail restant
• Blocages ou questions

chorus_report_work({
  taskUuid: "<task-uuid>",
  report: "Progression :\n- Créé src/services/auth.service.ts\n- Commit : abc1234\n- Restant : tests unitaires",
  sessionUuid: "<session-uuid>"
})

Signaler avec mise à jour de statut quand terminé :

chorus_report_work({
  taskUuid: "<task-uuid>",
  report: "Implémentation complète :\n- Fichiers : ...\n- PR : https://github.com/org/repo/pull/42\n- Tous les tests passants",
  status: "to_verify",
  sessionUuid: "<session-uuid>"
})

Étape 7 : Auto-vérifier les critères d'acceptation

Avant de soumettre, vérifier les critères d'acceptation structurés :

task = chorus_get_task({ taskUuid: "<task-uuid>" })

# Si task.acceptanceCriteriaItems est non-vide :
chorus_report_criteria_self_check({
  taskUuid: "<task-uuid>",
  criteria: [
    { uuid: "<criterion-uuid>", devStatus: "passed", devEvidence: "Les tests unitaires couvrent ceci" },
    { uuid: "<criterion-uuid>", devStatus: "passed", devEvidence: "Vérifié manuellement" }
  ]
})

Pour les critères obligatoires, continuer à travailler jusqu'à pouvoir auto-vérifier comme passed. Utiliser failed uniquement pour les critères optionnels hors scope.

Étape 8 : Soumettre pour vérification

Sous-agents — se déconnecter d'abord :

chorus_session_checkout_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })

Puis soumettre :

chorus_submit_for_verify({
  taskUuid: "<task-uuid>",
  summary: "Implémenté fonctionnalité d'auth :\n- Ajouté endpoints login/logout\n- Middleware JWT\n- 95% couverture de tests\n- Tous les AC auto-vérifiés (3/3 passés)"
})

to_verify ne déverrouille PAS les tâches en aval — seul done (après vérification admin) le fait.

Agent de révision : Après chorus_submit_for_verify, le hook PostToolUse du Plugin Chorus injecte un contexte vous instruisant de lancer chorus:task-reviewer — un agent de révision indépendant, en lecture seule. Vous DEVEZ le lancer vous-même (il N'est PAS auto-lancé). Le lancer au premier plan (NE PAS définir run_in_background) — attendre le VERDICT avant de procéder. Le réviseur publie un commentaire VERDICT sur la tâche.

Après l'achèvement du réviseur, lire son VERDICT :

chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })

Trouver le commentaire le plus récent contenant VERDICT: et agir selon celui-ci :

• VERDICT: PASS — Tous les AC vérifiés, pas de problèmes. Procéder à la vérification admin.
• VERDICT: PASS WITH NOTES — Tous les AC vérifiés, notes mineures. Procéder à la vérification admin (notes non-bloquantes).
• VERDICT: FAIL — BLOCKERs trouvés. NE PAS vérifier. Corriger les BLOCKERs listés dans le commentaire du réviseur, puis resoumettres.

Si aucun nouveau commentaire VERDICT: n'apparaît après le retour du réviseur, il a épuisé son budget maxTurns avant de publier. Le relancer UNE FOIS avec un indice de budget succinct dans le prompt : « Rester dans le budget de turns. Ignorer la vérification approfondie. Récupérer tâche/proposition/commentaires, exécuter uniquement les tests essentiels, et publier votre commentaire VERDICT dans les 12 premiers turns. » Si la deuxième tentative ne produit toujours pas de VERDICT, revoir manuellement en utilisant la checklist et procéder.

Étape 9 : Gérer les retours de révision

Si le réviseur retourne FAIL, ou la tâche est rouverte après vérification :

Tous les critères d'acceptation sont réinitialisés à pending quand une tâche est rouverte.

1. Vérifier les retours :

   chorus_get_task({ taskUuid: "<task-uuid>" })
   chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })

2. Corriger tous les BLOCKERs listés dans le commentaire FAIL du réviseur.
3. Se reconnecter, corriger les problèmes, signaler les corrections, resoumettres.

Étape 10 : Tâche complète

Une fois que l'Admin vérifie (status: done), passer à la tâche disponible suivante (retour à l'Étape 2).

Étape 11 : Rapport d'achèvement d'idée (consultatif)

Si la tâche que vous venez d'auto-vérifier était la DERNIÈRE de son Idée (chaque Tâche sur chaque Proposition approuvée est maintenant done/closed) et vous avez document:write, proposer d'appeler chorus_create_report via AskUserQuestion. La description de l'outil porte le modèle de section. Ignorer en cas de refus — le hook PostToolUse rappellera à la prochaine exécution.

Session (sous-agents uniquement)

Le Plugin Chorus automatise complètement le cycle de vie de la session — création, heartbeat et nettoyage sont tous gérés par les hooks. Les sous-agents ne font que 3 choses manuellement :

1. chorus_session_checkin_task({ sessionUuid, taskUuid }) — avant de commencer le travail
2. chorus_session_checkout_task({ sessionUuid, taskUuid }) — quand terminé (recommandé ; le plugin auto-déconnecte également à la sortie)
3. Passer sessionUuid à chorus_update_task et chorus_report_work pour l'attribution

Agent principal / Chef d'équipe : aucune session nécessaire — appeler les outils sans sessionUuid.

Intégration Claude Code Agent Teams

Quand utiliser Claude Code's Agent Teams pour lancer plusieurs sous-agents en parallèle, Chorus fournit une observabilité complète du travail.

Architecture à deux niveaux

Workflow du Chef d'équipe

# 1. Se connecter et planifier
chorus_checkin()
chorus_list_tasks({ projectUuid: "<project-uuid>" })

# 2. Créer une équipe Claude Code et lancer des sous-agents
TeamCreate({ team_name: "feature-x" })

# Passer uniquement les UUID de tâches — le plugin auto-injecte le workflow de session
Task({
  name: "frontend-worker",
  prompt: "Votre UUID de tâche Chorus : <task-uuid>\nUUID du projet : <project-uuid>\n\nImplémente..."
})

Ce dont le prompt du Chef d'équipe a besoin :

• UUID(s) de tâche
• PAS d'UUID de session, PAS de boilerplate de workflow — le plugin auto-injecte tout

Workflow du sous-agent

Le plugin injecte l'UUID de session et le workflow dans le contexte du sous-agent automatiquement.

# 1. Se connecter à la tâche
chorus_session_checkin_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })

# 2. Passer à in_progress
chorus_update_task({ taskUuid: "<my-task-uuid>", status: "in_progress", sessionUuid: "<my-session-uuid>" })

# 3. Faire le travail... code, test, commit...

# 4. Signaler la progression
chorus_report_work({ taskUuid: "<my-task-uuid>", report: "...", sessionUuid: "<my-session-uuid>" })

# 5. Se déconnecter et soumettre
chorus_session_checkout_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })
chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })

# 6. Notifier le chef d'équipe
SendMessage({ type: "message", recipient: "team-lead", content: "Tâche complète" })

# NE PAS fermer la session — le plugin la ferme automatiquement à la sortie

Gestion des dépendances de tâches (DAG)

Application côté serveur : chorus_update_task(status: "in_progress") rejette si une tâche dependsOn n'est pas done ou closed.

Exécution par vagues (recommandé) :

1. chorus_get_unblocked_tasks — trouver les tâches prêtes
2. Lancer les sous-agents pour la Vague 1
3. Attendre to_verify, puis vérifier chaque tâche (chorus_admin_verify_task → done)
4. chorus_get_unblocked_tasks — trouver les tâches nouvellement déverrouillées (Vague 2)
5. Répéter jusqu'à l'achèvement de toutes les tâches

Critique : to_verify ne résout PAS les dépendances — seul done ou closed le fait. Le Chef d'équipe doit vérifier les tâches entre les vagues.

Tâches multiples par sous-agent

Un seul sous-agent peut travailler sur plusieurs tâches séquentiellement :

Task({
  name: "full-stack-worker",
  prompt: "Vos tâches Chorus (travail dans l'ordre) :\n1. task-schema-uuid\n2. task-api-uuid (dépend de #1)\n\nPour CHAQUE tâche : checkin -> in_progress -> work -> report -> checkout -> submit_for_verify"
})

Accès MCP pour les sous-agents

Les sous-agents ont besoin de MCP configuré au niveau du projet (.mcp.json ou .claude/settings.json). La config au niveau utilisateur peut ne pas être accessible aux sous-agents.

Dépannage

Bonnes pratiques des rapports de travail

Bon rapport (permet la continuité de session) :

Implémenté flux de réinitialisation de mot de passe :

Fichiers créés/modifiés :
- src/services/auth.service.ts (nouveau)
- src/app/api/auth/reset/route.ts (nouveau)
- tests/auth/reset.test.ts (nouveau)

Git :
- Commit : a1b2c3d "feat: password reset flow"
- PR : https://github.com/org/repo/pull/15

Détails d'implémentation :
- POST /api/auth/reset-request : envoie email avec token
- Token expire après 1 heure, utilisation unique
- Limitation de débit : 3 demandes/heure/email
- 12 nouveaux tests, tous passants

Critères d'acceptation :
- [x] L'utilisateur peut demander une réinitialisation via email
- [x] Le lien de réinitialisation expire après 1 heure
- [x] La limitation de débit prévient les abus

Mauvais rapport : Fait.

Conseils

• Lire d'abord les commentaires de tâche — ils contiennent les rapports de travail précédents pour la continuité de session
• Vérifier les dépendances amont — lire les tâches dependsOn et leurs commentaires pour les interfaces/APIs
• Lire la proposition d'origine — comprendre la logique de conception et le DAG des tâches
• Utiliser commentCount — ignorer récupérer les commentaires sur les entités avec count 0
• Signaler la progression fréquemment — inclure les chemins de fichiers, les commits et les PRs
• Écrire des résumés de soumission détaillés — l'Admin en a besoin pour vérifier
• Si bloqué, ajouter un commentaire et envisager de libérer la tâche
• Une tâche à la fois : terminer ou libérer avant d'en réclamer une autre
• Utiliser des noms de sous-agent significatifs — ils deviennent les noms de session Chorus

Quand libérer une tâche

Libérer si :

• Vous ne pouvez pas la compléter (connaissance manquante, bloqué)
• Une tâche de priorité plus élevée a besoin d'attention
• Vous n'allez pas la terminer dans un délai raisonnable

chorus_release_task({ taskUuid: "<task-uuid>" })
chorus_add_comment({ targetType: "task", targetUuid: "<task-uuid>", content: "Libération : raison..." })

Suivant

• Après soumission pour vérification, un Admin examine en utilisant /review
• Pour l'aperçu de la plateforme et les outils partagés, voir /chorus