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 avec les sous-agents Pi (travailleurs parallèles) avec une observabilité complète basée sur les sessions.

Outils

Cycle de vie de la tâche :

Signalement de travail :

Critères d'acceptation :

Session (sous-agents uniquement — l'agent principal saute 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 requise.

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

Workflow

Étape 1 : S'enregistrer

chorus_checkin()

Vérifiez votre persona, les affectations actuelles et le nombre de travaux en attente.

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

Ignorez cette étape si vous êtes l'agent principal ou Chef d'équipe.

Si vous êtes un sous-agent (généré via subagent_spawn), l'extension Chorus crée automatiquement votre session et l'injecte dans la demande de votre tâche — recherchez une section --- Chorus session (auto-injected) --- contenant votre Session UUID. Conservez-le pour toutes les opérations de tâche.

Étape 2 : Trouver du travail

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

Ou vérifiez les affectations existantes :

chorus_get_my_assignments()

Étape 3 : Réclamer une tâche

chorus_get_task({ taskUuid: "<task-uuid>" })  # Vérifier d'abord
chorus_claim_task({ taskUuid: "<task-uuid>" })

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

Étape 4 : Rassembler le contexte

Chaque tâche et proposition inclut un champ commentCount — utilisez-le pour décider quelles entités ont des discussions qui valent la peine d'être lues.

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

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

   Faites 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 s'en inspire probablement :

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

   Recherchez : 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 par défaut à section: "basic" — juste les métadonnées + un index de brouillon. Passez section: "documents" pour les documents de conception, ou section: "full" pour les documents + brouillons de tâches.)

5. Lire les documents du projet (PRD, conception technique, 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 ex. clarifier un AC, corriger un scénario de spec avant de soumettre à nouveau), chargez la compétence openspec-aware à skills/openspec-aware/SKILL.md et suivez §3.8 : modifiez d'abord le fichier .md local, puis miroitez via le wrapper chorus-mcp-call.sh avec json_encode_file et chorus_check_response.

⛔ Ne pas appeler chorus_pm_update_document directement depuis le harnais MCP avec un champ content tapé à la main en mode OpenSpec. Le fichier local est la source de vérité ; le contenu typé par l'agent dérive et consomme des tokens (openspec-aware §2 Rule 1).

Quand la DERNIÈRE tâche d'une idée OpenSpec est vérifiée, l'extension injecte un rappel d'archive (openspec-aware §3.9) — exécutez openspec archive <slug> --yes, puis miroitez chaque openspec/specs/<capability>/spec.md émis via §3.8.

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

Étape 5 : Commencer le travail

Sous-agent : s'enregistrer d'abord auprès de la tâche :

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

Puis marquer comme en cours :

# 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 (les tâches dependsOn ne sont pas en done ou closed), l'appel sera rejeté avec des informations détaillées sur les blocages. Utilisez chorus_get_unblocked_tasks pour trouver les tâches que vous pouvez commencer maintenant.

Étape 6 : Signaler la progression

Signalez périodiquement avec chorus_report_work. Incluez :

• Ce qui a été complété
• Fichiers créés ou modifiés
• Commits Git et PR
• 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>"
})

Signalez avec mise à jour de statut quand c'est terminé :

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

Étape 7 : Auto-vérification des critères d'acceptation

Avant de soumettre, vérifiez 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, continuez le travail jusqu'à pouvoir vous auto-vérifier comme passed. N'utilisez failed que pour les critères optionnels qui sont hors de portée.

Étape 8 : Soumettre pour vérification

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

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

Puis soumettre :

chorus_submit_for_verify({
  taskUuid: "<task-uuid>",
  summary: "Fonctionnalité d'authentification implémentée :\n- Ajouté endpoints login/logout\n- Middleware JWT\n- Couverture de tests 95%\n- Tous les AC auto-vérifiés (3/3 réussis)"
})

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

Agent Review : Après chorus_submit_for_verify, l'extension Chorus vous pousse à générer chorus-task-reviewer — un agent d'examen indépendant en lecture seule. Vous DEVEZ le générer vous-même (il n'est PAS auto-lancé). Utilisez l'outil subagent bloquant (il attend le VERDICT et le retourne) — attendez le VERDICT avant de procéder. L'examinateur publie un commentaire VERDICT sur la tâche.

Après l'examen, lisez son VERDICT :

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

Trouvez le commentaire le plus récent contenant VERDICT: et agissez en conséquence :

• VERDICT: PASS — Tous les AC vérifiés, pas de problèmes. Procédez à la vérification admin.
• VERDICT: PASS WITH NOTES — Tous les AC vérifiés, notes mineures. Procédez à la vérification admin (les notes ne bloquent pas).
• VERDICT: FAIL — BLOCKERs trouvés. NE PAS vérifier. Corrigez les BLOCKERs listés dans le commentaire de l'examinateur, puis resoumettez.

Si aucun nouveau commentaire VERDICT: n'apparaît après le retour de l'examinateur, il a épuisé son budget de tours avant de publier. Relancez-le UNE FOIS avec un indice de budget concis dans la demande : "Restez dans le budget de tours. Ignorez la vérification profonde. Récupérez la tâche/la proposition/les commentaires, exécutez uniquement les tests principaux, et publiez votre commentaire VERDICT dans les 12 premiers tours." Si la deuxième tentative ne produit toujours pas de VERDICT, examinez manuellement à l'aide de la checklist et procédez.

Passerelle d'examen de code final (après vérification de la DERNIÈRE tâche de l'Idée) : quand la tâche que vous venez de vérifier est la dernière tâche de sa proposition enracinée dans l'idée, la fonctionnalité est sur le point d'être livrée — l'extension vous pousse à générer chorus-code-reviewer (contrôlé par CHORUS_ENABLE_CODE_REVIEWER, activé par défaut). Générez-le vous-même via l'outil subagent bloquant, en passant ideaUuid + numéro de round ; il examine le changement de code agrégé de l'Idée sur toutes ses tâches (intégration inter-tâches, architecture, sécurité, régression, couverture au niveau des fonctionnalités) et publie un commentaire VERDICT sur l'idée. PASS / PASS WITH NOTES → livrer ; FAIL → corriger via /skill:quick-dev (chorus_create_tasks avec proposalUuid défini à la proposition approuvée actuelle pour que les tâches de correction s'y attachent — NE PAS rouvrir les tâches vérifiées), puis relancer la passerelle, limitée par CHORUS_MAX_CODE_REVIEW_ROUNDS (env, défaut 3 ; 0 = illimité). Consultatif/comportemental, comme les autres examinateurs. Exécutez-le avant tout rapport d'achèvement d'idée.

Étape 9 : Gérer les retours d'examen

Si l'examinateur retourne FAIL, ou si la tâche est rouverte après vérification :

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

1. Vérifiez les retours :

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

2. Corrigez chaque BLOCKER listé dans le commentaire FAIL de l'examinateur.
3. Ré-enregistrez-vous, corrigez les problèmes, signalez les corrections, resoumettez.

Étape 10 : Tâche terminée

Une fois qu'Admin vérifie (statut : done), passez à la prochaine tâche disponible (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, proposez d'appeler chorus_create_report via AskUserQuestion. La description du paramètre content porte le modèle de section. Ignorez en cas de refus — l'extension vous rappellera à la prochaine exécution.

Session (sous-agents uniquement)

L'extension Chorus automatise complètement le cycle de vie des sessions — la création (sur subagent_spawn, via injection de tâche tool_call) et le nettoyage (sur subagent_manage close) sont gérés par l'extension. Les sous-agents font manuellement seulement 3 choses :

1. chorus_session_checkin_task({ sessionUuid, taskUuid }) — avant de commencer le travail
2. chorus_session_checkout_task({ sessionUuid, taskUuid }) — quand c'est terminé (recommandé ; le plugin se désenregistre aussi automatiquement à la sortie)
3. Passer sessionUuid à chorus_update_task et chorus_report_work pour l'attribution

Agent principal / Chef d'équipe : aucune session requise — appelez les outils sans sessionUuid.

Intégration des sous-agents parallèles

Quand vous utilisez les sous-agents Pi (pi-subagents) pour exécuter plusieurs sous-agents en parallèle, Chorus fournit une observabilité complète du travail. L'extension chorus-pi automatise le cycle de vie des sessions : quand vous subagent_spawn un travailleur, elle crée une session Chorus et injecte l'UUID de session + le workflow dans la tâche du travailleur ; quand vous subagent_manage close l'agent, elle ferme la session.

Architecture à deux niveaux

Workflow du Chef d'équipe

# 1. S'enregistrer et planifier
chorus_checkin()
chorus_list_tasks({ projectUuid: "<project-uuid>" })

# 2. Générer des sous-agents (async — retourne immédiatement avec un agentId)
# Passez uniquement les UUID de tâches — l'extension chorus-pi injecte automatiquement l'UUID
# de session + le workflow dans la tâche du travailleur.
subagent_spawn({
  agent: "worker",
  task: "Votre UUID de tâche Chorus : <task-uuid>\nUUID du projet : <project-uuid>\n\nImplémentez..."
})
# → retourne agentId (sa_<uuid>) ; conservez-le pour fermer l'agent plus tard.

Ce que la demande du Chef d'équipe doit contenir :

• UUID(s) de tâche
• PAS d'UUID de session, PAS de boilerplate de workflow — l'extension injecte tout automatiquement
• L'agentId retourné par subagent_spawn (nécessaire pour subagent_manage close plus tard)

Workflow du sous-agent

L'extension injecte automatiquement l'UUID de session + le workflow dans la tâche du sous-agent (au moment tool_call, avant le démarrage du sous-processus). Le sous-agent lit le Session UUID: de la demande de sa tâche et suit les étapes injectées :

# 1. S'enregistrer auprès de la tâche (sessionUuid vient de la tâche auto-injectée)
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ésenregistrer et soumettre
chorus_session_checkout_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })
chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })

# 6. (Optionnel) notifier le chef d'équipe via mailbox — vous avez besoin de son agentId
subagent_mailbox({ action: "send", agentId: "<team-lead-agentId>", message: "Tâche terminée" })

# NE PAS appeler chorus_close_session — l'extension la ferme quand le
# chef d'équipe exécute subagent_manage({ action: "close", agentId: "<my-agentId>" })

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 vague (recommandée) :

1. chorus_get_unblocked_tasks — trouver les tâches prêtes
2. subagent_spawn des travailleurs pour Wave 1 (async ; conservez les agentIds)
3. Attendre to_verify (sondez chorus_list_tasks ou lisez les messages d'achèvement async), puis vérifiez chaque tâche (chorus_admin_verify_task → done)
4. subagent_manage close chaque travailleur terminé (libère son slot + ferme sa session Chorus)
5. chorus_get_unblocked_tasks — trouver les tâches nouvellement déverrouillées (Wave 2)
6. Répétez jusqu'à ce que toutes les tâches soient terminées

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. Souvenez-vous aussi de subagent_manage close les travailleurs terminés — Pi limite les sous-agents concurrents et completed ne libère pas le slot.

Plusieurs tâches par sous-agent

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

subagent_spawn({
  agent: "worker",
  task: "Vos tâches Chorus (travaillez 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 niveau utilisateur (~/.pi/agent/mcp.json). L'injection de session de l'extension chorus-pi fonctionne quand même, car elle appelle chorus sur sa propre extraction MCP-over-HTTP (pas la passerelle du sous-agent).

Dépannage

Bonnes pratiques de rapport de travail

Bon rapport (permet la continuité des sessions) :

Flux de réinitialisation de mot de passe implémenté :

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 un email avec un jeton
- Le jeton expire après 1 heure, utilisation unique
- Limitation de débit : 3 demandes/heure/email
- 12 nouveaux tests, tous réussis

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

Mauvais rapport : Terminé.

Conseils

• Lisez d'abord les commentaires de la tâche — ils contiennent les rapports de travail précédents pour la continuité des sessions
• Vérifiez les dépendances amont — lisez les tâches dependsOn et leurs commentaires pour les interfaces/API
• Lisez la proposition d'origine — comprenez la justification de la conception et le DAG des tâches
• Utilisez commentCount — ignorez la récupération de commentaires sur les entités avec le compte 0
• Signalez la progression fréquemment — incluez les chemins de fichiers, les commits et les PR
• Écrivez des résumés de soumission détaillés — Admin en a besoin pour vérifier
• Si vous êtes bloqué, ajoutez un commentaire et envisagez de libérer la tâche
• Une tâche à la fois : terminez ou libérez avant d'en réclamer une autre
• Utilisez des noms significatifs pour les sous-agents — ils deviennent des noms de session Chorus

Quand libérer une tâche

Libérez si :

• Vous ne pouvez pas la terminer (connaissances manquantes, bloquée)
• Une tâche plus prioritaire a besoin d'attention
• Vous ne la terminerez pas 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 la soumission pour vérification, un Admin examine en utilisant /review
• Wake "Start Development" humain : un wake start_development (l'humain a cliqué sur Start Development sur le panneau détail d'idée) signifie : réclamer et exécuter TOUTES les tâches restantes de la proposition approuvée de l'idée dans l'ordre de dépendance — bouclez ce workflow jusqu'à ce qu'aucune tâche réclamable ne reste, laissant to_verify et les tâches d'autres sessions intactes.
• Wake "Yolo" humain : un wake yolo_requested (l'humain a cliqué sur Yolo sur le panneau détail d'idée) signifie : conduire l'ENTIÈRE idée à done via la compétence yolo (le pipeline AI-DLC entièrement automatique), pas seulement l'étape d'exécution — lisez l'état actuel de l'idée et reprenez à partir de la phase où elle se trouve. Contrairement à start_development, il est adaptatif aux étapes, et il ne doit jamais fusionner ou pousser une PR sans approbation humaine explicite.
• Pour la vue d'ensemble de la plateforme et les outils partagés, voir /chorus