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.

Vue d'ensemble

Les Developer Agents prennent les Tâches créées par les PM Agents (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, l'agent principal utilise l'outil spawn_agent de Codex pour lancer des sous-agents workers. Les sessions sont optionnelles dans le port Codex — l'observabilité multi-agents nécessite que l'agent principal crée manuellement des sessions et passe sessionUuid aux workers.

Outils

Cycle de vie de la Tâche :

Signalement du travail :

Critères d'acceptation :

Session (optionnel, géré par l'agent principal) :

Agent principal (lors de la coordination des workers pour l'observabilité) : appeler chorus_create_session avant de spawner les workers, passer l'sessionUuid retourné au worker via le message spawn_agent, et appeler chorus_session_checkout_task + chorus_close_session après la fin du worker. Workers : recevoir sessionUuid dans leur prompt initial et le passer à chorus_update_task et chorus_report_work pour l'attribution. Pas de session nécessaire : tout fonctionne toujours — statut de la tâche, rapports, commentaires — vous perdez juste l'attribution par worker dans l'UI.

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

Workflow

Étape 1 : S'enregistrer

chorus_checkin()

Consultez votre persona, les assignations actuelles et les comptages de travail en attente.

Étape 1.5 : Obtenir votre Session (port Codex : agent principal explicite)

Le port Codex ne crée pas automatiquement les sessions. Deux scénarios :

• Travail single-agent (agent principal) : ignorer complètement la session. Appeler les outils de tâche sans sessionUuid.
• Travail multi-agents (worker spawné via spawn_agent) : l'agent principal devrait avoir créé une session et passé sessionUuid dans votre prompt initial. L'utiliser pour chaque appel à chorus_update_task, chorus_report_work, chorus_session_checkin_task, chorus_session_checkout_task. Si l'agent principal a oublié de le passer et vous avez toujours besoin d'observabilité, vous POUVEZ appeler chorus_create_session vous-même — mais coordonnez avec l'agent principal pour éviter les doublons.

Étape 2 : Trouver du travail

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

Ou vérifiez les assignations existantes :

chorus_get_my_assignments()

Étape 3 : Réclamer une Tâche

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

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

Étape 4 : Rassembler le contexte

Chaque tâche et proposal inclut un champ commentCount — l'utiliser 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 en 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 en amont — votre travail s'appuie probablement sur le leur :

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

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

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

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

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

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

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

Flux de mise à jour des documents (mode OpenSpec) : si la description de la proposal 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 de spec avant de resoumettreé), charger la compétence openspec-aware à ~/.codex/skills/openspec-aware/SKILL.md et suivre §3.8 : modifier d'abord le fichier .md local, puis le mettre en miroir 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 harness MCP de Codex avec un champ content tapé à la main en mode OpenSpec. Le fichier local est la source de vérité ; le contenu tapé par l'agent dérive et brûle des tokens (openspec-aware §2 Règle 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 mettre en miroir chaque openspec/specs/<capability>/spec.md émis via §3.8.

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

Étape 5 : Commencer le travail

Avec session (optionnel) : d'abord s'enregistrer sur la tâche, puis marquer comme en cours :

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

Sans session (single-agent / 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 les informations détaillées du bloqueur. Utiliser 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. Inclure :

• Ce qui a été complété
• Fichiers créés ou modifiés
• Commits et PRs Git
• Statut actuel / travail restant
• Bloqueurs 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 du statut quand c'est terminé :

chorus_report_work({
  taskUuid: "<task-uuid>",
  report: "Toute l'implémentation terminée :\n- Fichiers : ...\n- PR : https://github.com/org/repo/pull/42\n- Tous les tests passent",
  status: "to_verify",
  sessionUuid: "<session-uuid>"
})

Étape 7 : Auto-vérifier les 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 n'est pas 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 à travailler jusqu'à pouvoir auto-vérifier comme passed. Utilisez failed seulement pour les critères optionnels qui sont hors du périmètre.

Étape 8 : Soumettre pour vérification

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

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

Puis soumettre :

chorus_submit_for_verify({
  taskUuid: "<task-uuid>",
  summary: "Implémenté la fonctionnalité d'authentification :\n- Ajouté les endpoints de connexion/déconnexion\n- Middleware JWT\n- Couverture de test de 95 %\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.

Review Agent : Après chorus_submit_for_verify, le hook PostToolUse du plugin Chorus injecte du contexte vous instruisant de spawner le sous-agent chorus-task-reviewer. Vous DEVEZ le spawner vous-même (il n'est PAS lancé automatiquement). Spawnez-le en montant la compétence chorus-task-reviewer de ce plugin dans un sous-agent par défaut :

spawn_agent(
  agent_type="default",
  items=[
    { type: "skill", name: "Chorus Task Reviewer", path: "chorus:chorus-task-reviewer" },
    { type: "text",  text: "Examiner la tâche Chorus <task-uuid>. Poster un commentaire VERDICT." }
  ]
)
wait_agent([reviewer_id]); close_agent(reviewer_id)

Pourquoi pas agent_type="chorus-task-reviewer" ? Codex 0.125 n'a que trois rôles intégrés (default / explorer / worker) ; les personas de review personnalisés sont chargés en montant la compétence. Le reviewer poste un commentaire VERDICT: sur la tâche.

Passerelle de code-review finale (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 proposal enracinée dans l'idée, la fonctionnalité est sur le point d'être expédiée — le hook PostToolUse injecte un rappel pour exécuter la passerelle de code-review au moment de l'expédition. Spawnez-la de la même manière, en montant chorus:chorus-code-reviewer et en passant l'ideaUuid + le numéro de tour ; elle examine le changement de code agrégé de l'Idée (intégration inter-tâches, architecture, sécurité, régression, couverture au niveau de la fonctionnalité) et poste un commentaire VERDICT: sur l'idée. PASS / PASS WITH NOTES → expédier ; FAIL → corriger via le workflow quick-dev ($quick-dev) : chorus_create_tasks avec proposalUuid défini à la proposal approuvée actuelle pour que les tâches de correction s'y attachent (ne pas réouvrir d'anciennes tâches), puis exécuter → vérifier et relancer la passerelle. Consultatif/comportemental, comme les autres reviewers. Exécutez-le avant tout rapport de fin d'idée.

Après que le reviewer se termine, lisez son VERDICT :

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

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

• VERDICT: PASS — Tous les AC vérifiés, aucun problème. 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 sont pas bloquantes).
• VERDICT: FAIL — BLOCKERs trouvés. NE PAS vérifier. Corrigez les BLOCKERs listés dans le commentaire du reviewer, puis resoumettez.

Si aucun nouveau commentaire VERDICT: n'apparaît après le retour du reviewer, il a épuisé son budget maxTurns avant de poster. Relancez-le UNE FOIS avec un indice de budget concis dans le prompt : « Restez dans le budget de tours. Ignorez la vérification approfondie. Récupérez la tâche/proposal/commentaires, exécutez seulement les tests principaux, et postez 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.

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

Si le reviewer 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ée dans le commentaire FAIL du reviewer.
3. Réenregistrez-vous, corrigez les problèmes, signalez les correctifs, resoumettez.

Étape 10 : Tâche complète

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

Étape 11 : Rapport de fin 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 dans chaque Proposal approuvée est maintenant done/closed) et que vous avez document:write, demander à l'utilisateur et appeler chorus_create_report sur acceptation. La description de l'outil contient le modèle de section. Ignorer sur refus — le hook PostToolUse rappellera à la prochaine exécution.

Session (Optionnel, port Codex)

Le port Codex est actuellement stateless — aucun hook ne crée automatiquement, ne maintient le contact ou ne ferme les sessions Chorus pour le moment. Codex supporte les hooks du plugin SubagentStart/SubagentStop, mais ce plugin ne les a pas connectés à la gestion automatique du cycle de vie des sessions Chorus. Traiter sessionUuid comme observabilité optionnelle par worker, non comme une exigence :

• Travail de développeur single-agent : ignorer complètement les outils de session. chorus_update_task / chorus_report_work / chorus_submit_for_verify fonctionnent tous sans sessionUuid.
• Team Lead orchestrant des workers via spawn_agent : appeler manuellement chorus_create_session avant le spawning, passer sessionUuid dans le message initial de chaque worker, et chorus_close_session après le retour de wait_agent. Voir la section Travailleurs multi-agents ci-dessous.

Travailleurs multi-agents (Codex spawn_agent)

Lors de l'exécution de plusieurs sous-agents en parallèle sur les tâches d'une proposal, l'agent principal joue le rôle de Team Lead. Le port Codex ne gère pas automatiquement les sessions — le Team Lead est responsable du cycle de vie de la session s'il est nécessaire d'avoir une observabilité par worker.

Architecture à deux couches

Workflow du Team Lead (avec sessions)

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

# 2. Pour chaque worker que vous avez l'intention de spawner, créer une session Chorus
session_a = chorus_create_session({ name: "frontend-worker" })
session_b = chorus_create_session({ name: "backend-worker" })

# 3. Spawner les workers, passer sessionUuid + taskUuid(s) dans le message
spawn_agent(
  agent_type="worker",
  message=f'''Vous êtes un worker développeur Chorus. Suivez la compétence $develop.

Votre sessionUuid : {session_a.uuid}
Vos tâche(s) : <task-uuid-1>, <task-uuid-2>
UUID du projet : <project-uuid>

Procédure : pour chaque tâche — chorus_session_checkin_task → chorus_update_task in_progress → implémenter → chorus_report_work → auto-vérifier AC → chorus_session_checkout_task → chorus_submit_for_verify. Signalez l'achèvement dans votre message final pour que l'agent principal puisse fermer votre session.''',
)

Workflow du Team Lead (sans sessions — plus simple)

Si l'observabilité par worker n'est pas requise, ignorer complètement les sessions :

spawn_agent(
  agent_type="worker",
  message='''Suivez la compétence $develop. Votre tâche : <task-uuid>. Ne PAS appeler chorus_create_session ou chorus_session_*. Juste claim/update/report/submit.''',
)

Le statut de la tâche, les rapports de travail, les commentaires, les auto-vérifications d'AC fonctionnent tous — vous perdez juste l'attribution « quel worker a fait quoi » dans l'UI.

Nettoyage de la session (responsabilité du Team Lead)

Jusqu'à ce que le plugin Codex connecte SubagentStop au nettoyage des sessions Chorus, le Team Lead doit fermer les sessions après la fin des workers :

# Après le retour du spawn_agent du worker_a :
chorus_session_checkout_task({ sessionUuid: session_a.uuid, taskUuid: "..." })   # au cas où le worker aurait oublié
chorus_close_session({ sessionUuid: session_a.uuid })

Alternativement, compter sur le TTL de session du backend Chorus pour faire expirer automatiquement les sessions inactives. C'est acceptable pour la plupart des cas.

Exécution par vagues

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

1. chorus_get_unblocked_tasks — trouver les tâches prêtes
2. Spawner les workers pour la Vague 1
3. Après le retour de chaque worker, vérifier sa tâche (chorus_admin_verify_task → done)
4. chorus_get_unblocked_tasks à nouveau — trouver les tâches nouvellement déverrouillées (Vague 2)
5. Répéter 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 Team Lead doit vérifier les tâches entre les vagues.

Tâches multiples par worker

Un seul worker peut travailler sur plusieurs tâches séquentiellement — les écrire dans son message spawn_agent dans l'ordre de dépendance, et faire boucler le worker sur elles.

Accès MCP pour les workers

Les sous-agents spawnés via spawn_agent héritent de la configuration MCP du parent. S'assurer que le serveur MCP chorus est déclaré dans ~/.codex/config.toml ou la .codex/config.toml du repo avec CHORUS_URL / CHORUS_API_KEY définis.

Dépannage

Bonnes pratiques de signalement du travail

Bon rapport (permet la continuité de la session) :

Implémenté le flux de réinitialisation du 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 un email avec un token
- Le token expire après 1 heure, à usage unique
- Limitation de débit : 3 requêtes/heure/email
- 12 nouveaux tests, tous passent

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

Astuces

• Lire d'abord les commentaires de la tâche — ils contiennent les rapports de travail précédents pour la continuité de la session
• Vérifier les dépendances en amont — lire les tâches dependsOn et leurs commentaires pour les interfaces/APIs
• Lire la proposal d'origine — comprendre la rationale de conception et le DAG de tâches
• Utiliser commentCount — ignorer la récupération des commentaires sur les entités avec un comptage de 0
• Signalez la progression fréquemment — inclure les chemins de fichiers, les commits et les PRs
• Écrivez des résumés détaillés de soumission — l'Admin en a besoin pour vérifier
• Si bloqué, ajouter un commentaire et considérer libérer la tâche
• Une tâche à la fois : terminer ou libérer avant de 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érer si :

• Vous ne pouvez pas la terminer (connaissance manquante, bloqué)
• Une tâche de priorité plus élevée a besoin d'attention
• Vous ne 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 soumission pour vérification, un Admin examine en utilisant /review
• Éveil humain « Yolo » : un éveil yolo_requested (l'humain a cliqué Yolo sur le panneau de détail de l'idée) signifie : piloter l'IDÉE ENTIÈRE jusqu'à terminée via la compétence yolo (le pipeline AI-DLC entièrement automatisé), pas seulement l'étape d'exécution — lire l'état actuel de l'idée et reprendre à partir de n'importe quelle phase dans laquelle elle se trouve. C'est adaptatif à l'étape, et cela ne doit jamais fusionner ou pousser une PR sans approbation humaine explicite.
• Pour l'aperçu de la plateforme et les outils partagés, voir /chorus