Chorus Develop Skill

Cette skill couvre l'étape de Développement du workflow AI-DLC : réclamer des Tasks, écrire du code, signaler la progression, soumettre pour vérification et gérer les sessions pour l'observabilité des subagents.

Aperçu

Les Developer Agents prennent les Tasks créées par les PM Agents (via /chorus-proposal) et les transforment en code fonctionnel. Chaque task suit :

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

Pour l'exécution parallèle multi-agents, l'agent principal chorus lance des subagents Kiro (jusqu'à 4 concurrents) avec une observabilité complète basée sur les sessions.

Tools

Task Lifecycle:

Work Reporting:

Acceptance Criteria:

Session (subagents uniquement — l'agent principal saute ces étapes):

Subagents : toujours passer sessionUuid à chorus_update_task et chorus_report_work pour l'attribution. Agent principal : appeler ces tools sans sessionUuid — aucune session nécessaire.

Tools partagés (checkin, query, comment, search, notifications) : voir le doc steering chorus.

Workflow

Step 1: Check In

chorus_checkin()

Consultez votre persona, vos affectations actuelles et vos counts de travail en attente. (Sur l'agent principal chorus, le hook agentSpawn a déjà exécuté checkin dans votre contexte de démarrage.)

Step 1.5: Get Your Session (Subagents Only)

Passez cette étape si vous êtes l'agent principal.

Si vous êtes un subagent qui reprend une task, créez/attachez une session pour l'observabilité. Quand l'agent principal vous lance, il transmet votre sessionUuid dans le prompt — conservez-le pour toutes les opérations de task. Si vous avez été lancé sans session, créez-en une pour vous-même et utilisez son uuid.

Step 2: Find Work

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

Ou vérifiez les affectations existantes :

chorus_get_my_assignments()

Step 3: Claim a Task

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

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

Step 4: Gather Context

Chaque task et proposal inclut un champ commentCount — utilisez-le pour décider quelles entités ont des discussions utiles à lire.

1. Lire la task et identifier les dépendances :

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

   Portez attention à dependsOn (tasks en amont) et commentCount.

2. Lire les commentaires de la task (contient les rapports de travail précédents, progression, feedback) :

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

3. Passer en revue les tasks 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 par défaut section: "basic" — juste metadata + un index de draft. Passez section: "documents" pour les docs de conception, ou section: "full" pour docs + drafts de task.)

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 proposal d'origine contient une ligne OpenSpec change slug: <slug>, les Documents PRD / tech_design / spec du projet sont des mirrors de fichiers sous openspec/changes/<slug>/. Pour mettre à jour un tel Document (par ex. clarifier un AC, corriger un scénario de spec avant resoumission), chargez la skill /chorus-openspec-aware et suivez §3.8 : modifiez d'abord le fichier .md local, puis mirror via le wrapper chorus-api.sh avec json_encode_file et chorus_check_response.

⛔ Ne pas appeler chorus_pm_update_document directement depuis le harness MCP 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 consomme des tokens (/chorus-openspec-aware §2 Rule 1).

Quand la DERNIÈRE task d'une idée OpenSpec est vérifiée, lancez le flux archive (/chorus-openspec-aware §3.9) — openspec archive <slug> --yes, puis mirror chaque openspec/specs/<capability>/spec.md émis via §3.8.

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

Step 5: Start Working

Subagent : d'abord enregistrez-vous à la task :

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

Puis marquez comme in_progress :

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

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

Enforcement des dépendances : Si cette task a des dépendances non résolues (tasks dependsOn pas en done ou closed), l'appel sera rejeté avec des infos détaillées de blocker. Utilisez chorus_get_unblocked_tasks pour trouver des tasks que vous pouvez commencer maintenant.

Step 6: Report Progress

Signalez régulièrement avec chorus_report_work. Incluez :

• Ce qui a été complété
• Les fichiers créés ou modifiés
• Les commits Git et PRs
• Le statut actuel / travail restant
• Les blockers 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 complété :

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 passent",
  status: "to_verify",
  sessionUuid: "<session-uuid>"
})

Step 7: Self-Check Acceptance Criteria

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 requis, continuez à travailler jusqu'à pouvoir auto-vérifier comme passed. Utilisez failed seulement pour les critères optionnels hors scope.

Step 8: Submit for Verification

Subagents — d'abord désinscrire-vous :

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

Puis soumettez :

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

to_verify NE débloque PAS les tasks en aval — seul done (après vérification admin) le fait.

Review Subagent : Après chorus_submit_for_verify, le hook postToolUse de l'agent principal chorus injecte une nudge vous instruisant de lancer chorus-task-reviewer — un subagent de review indépendant et en lecture seule (tools: ["read", "@chorus"]). Vous DEVEZ le lancer vous-même (ce n'est PAS auto-lancé). Lancez-le au premier plan — attendez le VERDICT avant de continuer. Le reviewer poste un commentaire VERDICT sur la task.

Après que le reviewer soit terminé, lisez son VERDICT :

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

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

• 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 bloquent pas).
• VERDICT: FAIL — BLOCKERs trouvés. NE VÉRIFIEZ PAS. Corrigez les BLOCKERs listés dans le commentaire du reviewer, puis resoumettez.

Si aucun nouveau commentaire VERDICT: n'apparaît après que le reviewer revienne, il a épuisé son budget de tours avant de poster. Relancez-le UNE FOIS avec un hint de budget concis dans le prompt : "Restez dans le budget de tours. Sautez la vérification approfondie. Récupérez task/proposal/commentaires, demandez les preuves d'exécution du développeur, et postez votre commentaire VERDICT dans les 12 premiers tours." Si la deuxième tentative ne produit toujours pas de VERDICT, examinez manuellement en utilisant la checklist et procédez.

Passerelle de review de code final (après vérification de la DERNIÈRE task de l'Idée) : quand la task que vous venez de vérifier est la dernière task de sa proposal enracinée dans une Idée, la fonctionnalité est sur le point d'être livrée — le hook postToolUse injecte un rappel de lancer le subagent chorus-code-reviewer. Lancez-le vous-même au premier plan, en passant ideaUuid + numéro de round ; il examine le changement de code agrégé de l'Idée sur toutes ses tasks (intégration inter-task, architecture, sécurité, régression, couverture au niveau fonctionnalité) et poste un commentaire VERDICT sur l'idée. PASS / PASS WITH NOTES → livrer ; FAIL → corriger via /chorus-quick-dev (chorus_create_tasks avec proposalUuid défini sur la proposal approuvée actuelle pour que les fix tasks s'y rattachent — NE réouvrez PAS les tasks vérifiées), puis relancez la passerelle. Consultatif/comportemental, comme les autres reviewers. Lancez-le avant tout rapport de complètion d'idée.

Step 9: Handle Review Feedback

Si le reviewer revient avec FAIL, ou la task est réouverte après vérification :

Tous les critères d'acceptation sont réinitialisés à pending quand une task est réouverte.

1. Vérifiez le feedback :

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

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

Step 10: Task Complete

Une fois que l'Admin vérifie (status: done), passez à la prochaine task disponible (retour à Step 2).

Step 11: Idea Completion Report (consultatif)

Si la task que vous venez d'auto-vérifier était la DERNIÈRE de son Idée (toutes les Tasks de toutes les Proposals approuvées sont maintenant done/closed) et vous avez document:write, proposez d'appeler chorus_create_report (demandez à l'utilisateur d'abord avec une question interactive claire). La description du tool contient le template de section. Ignorez sur refus.

Session (Subagents Only)

Les hooks de cycle de vie de l'agent principal chorus automatisent la propre session de l'agent principal (checkin sur agentSpawn, heartbeat/checkout sur stop). Un subagent qui reprend une task fait trois choses manuellement :

1. chorus_session_checkin_task({ sessionUuid, taskUuid }) — avant de commencer le travail
2. chorus_session_checkout_task({ sessionUuid, taskUuid }) — quand c'est fini
3. Passer sessionUuid à chorus_update_task et chorus_report_work pour l'attribution

Agent principal : aucune session nécessaire — appeler les tools sans sessionUuid.

Kiro Subagents Integration (exécution parallèle)

Quand vous (l'agent principal chorus) voulez exécuter plusieurs tasks en parallèle, lancez des subagents Kiro — jusqu'à 4 concurrents. Chorus fournit une observabilité complète du travail sur eux.

Two-Layer Architecture

Orchestrator (agent principal) Workflow

# 1. Enregistrement et planification
chorus_checkin()
chorus_list_tasks({ projectUuid: "<project-uuid>" })

# 2. Lancez un subagent par task prête (jusqu'à 4 concurrents). Vous avez `subagent`
#    dans vos tools, donc vous pouvez dispatcher par nom/description. Donnez à chaque subagent:
#      - son UUID de task Chorus + l'UUID du projet
#      - un sessionUuid frais à passer à ses opérations de task (pour l'attribution)
#      - l'instruction de suivre le workflow /chorus-develop

Ce que le prompt de l'orchestrator pour chaque subagent a besoin :

• UUID(s) de Task + UUID du Projet
• Un sessionUuid pour que ce subagent utilise sur chorus_update_task / chorus_report_work
• L'instruction : suivez /chorus-develop (claim -> in_progress -> develop -> report -> self-check AC -> checkout -> submit_for_verify)

Subagent Workflow

# 1. Enregistrement à la task
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. Travail... code, test, commit...

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

# 5. Désinscription et soumission
chorus_session_checkout_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })
chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })

# 6. Signaler au orchestrator (les subagents Kiro retournent un résumé au lanceur)

Handling Task Dependencies (DAG)

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

Exécution par wave (recommandée) :

1. chorus_get_unblocked_tasks — trouvez les tasks prêtes
2. Lancez des subagents pour Wave 1 (max 4 concurrents)
3. Attendez to_verify, puis vérifiez chaque task (chorus_admin_verify_task → done)
4. chorus_get_unblocked_tasks — trouvez les tasks nouvellement débloquées (Wave 2)
5. Répétez jusqu'à ce que toutes les tasks soient faites

Critique : to_verify NE résout PAS les dépendances — seuls done ou closed le font. L'orchestrator doit vérifier les tasks entre les waves.

MCP Access for Subagents

Le serveur MCP chorus est tiré via includeMcpJson: true sur l'agent principal chorus. Un subagent dispatché a besoin du serveur @chorus dans sa propre portée de tools aussi (soit c'est un agent chorus* qui inclut le serveur, soit vous passez la config MCP dont il a besoin). Assurez-vous que CHORUS_URL + CHORUS_API_KEY sont exportés dans l'environnement où Kiro a été lancé.

Troubleshooting

Work Report Best Practices

Bon rapport (active la continuité de session) :

Implémenté le 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
- Le token expire après 1 heure, usage unique
- Rate limiting: 3 requêtes/heure/email
- 12 nouveaux tests, tous passants

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] Rate limiting prévient les abus

Mauvais rapport : Fini.

Tips

• Lire d'abord les commentaires de task — ils contiennent les rapports de travail précédents pour la continuité de session
• Vérifier les dépendances en amont — lire les tasks dependsOn et leurs commentaires pour les interfaces/APIs
• Lire la proposal d'origine — comprendre la rationale de conception et le DAG de task
• Utiliser commentCount — ignorer les fetch de commentaires sur les entités avec count 0
• Signaler la progression fréquemment — inclure les chemins de fichiers, commits et 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 task
• Une task à la fois (par subagent) : terminez ou libérez avant de réclamer une autre
• Utiliser des noms de subagent significatifs — ils deviennent des noms de session Chorus

When to Release a Task

Libérez si :

• Vous ne pouvez pas la compléter (connaissance manquante, bloqué)
• Une task plus prioritaire a besoin d'attention
• Vous ne l'achèverez pas dans un délai raisonnable

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

Next

• Après soumission pour vérification, un Admin examine en utilisant /chorus-review
• Human "Start Development" wake : un wake start_development (l'humain a cliqué Start Development sur le panneau de détail d'idée) signifie : réclamer et exécuter TOUTES les tasks restantes de la proposal approuvée de l'idée dans l'ordre de dépendance — bouclez ce workflow jusqu'à ce qu'aucune task claimable ne reste, laissant les tasks to_verify et dans d'autres sessions intactes.
• Human "Yolo" wake : un wake yolo_requested (l'humain a cliqué Yolo sur le panneau de détail d'idée) signifie : diriger l'ENSEMBLE de l'idée vers done via la skill /chorus-yolo (le pipeline complet AI-DLC full-auto), pas juste l'étape d'exécution — lire l'état actuel de l'idée et reprendre depuis la phase actuelle. Contrairement à start_development, c'est adaptatif au stade, et il ne doit jamais merger ou pusher une PR sans approbation humaine explicite.
• Pour la vue d'ensemble de la plateforme et les tools partagés, voir le doc steering chorus.