Développer une 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 sous-agents.

Aperçu

Les Agents Développeurs prennent les Tasks 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 (workers parallèles) avec observabilité complète basée sur les sessions.

Outils

Cycle de vie des Tasks :

Signalement du travail :

Critères d'acceptation :

Session (sous-agents uniquement — l'agent principal ignore ceux-ci) :

Sous-agents : passez toujours sessionUuid à chorus_update_task et chorus_report_work pour l'attribution. Agent principal / Team Lead : appelez ces outils sans sessionUuid — aucune session requise.

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

Workflow

Étape 1 : Se connecter

chorus_checkin()

Passez en revue votre persona, vos assignations actuelles et vos compteurs de travail en attente.

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

Ignorez si vous êtes l'agent principal ou Team Lead.

Si vous êtes un sous-agent (spawné via subagent_spawn), l'extension Chorus crée automatiquement votre session et l'injecte dans votre invite de 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érifier vos 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 — utilisez-le pour décider quelles entités ont des discussions utiles à lire.

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

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

   Prêtez 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. Vérifier 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>" })

   Recherchez : 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. Passez section: "documents" pour les docs de conception, ou section: "full" pour docs + brouillons de tâches.)

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>, le PRD / tech_design / spec Documents du projet sont des miroirs des fichiers sous openspec/changes/<slug>/. Pour mettre à jour un tel Document (p. ex. clarifier une AC, corriger un scénario de spec avant de resoummettre), chargez la skill openspec-aware à skills/openspec-aware/SKILL.md et suivez §3.8 : modifiez d'abord le fichier .md local, puis reflétez 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 tapé 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 reflétez 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 Document directement via l'outil MCP existant sans wrapper, sans étape de fichier local.

Étape 5 : Commencer à travailler

Sous-agent : connectez-vous d'abord à la tâche :

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

Puis marquez 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 infos de bloqueur détaillées. Utilisez chorus_get_unblocked_tasks pour trouver les tâches que vous pouvez démarrer 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 PRs
• 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 de statut quand 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 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 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 vous auto-vérifier comme passed. Utilisez failed uniquement pour les critères optionnels hors portée.

Étape 8 : Soumettre pour vérification

Sous-agents — déconnectez-vous d'abord :

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

Puis soumettez :

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 test 95%\n- Toutes les AC auto-vérifiées (3/3 passed)"
})

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

Agent Review : Après chorus_submit_for_verify, l'extension Chorus vous encourage à spawner chorus-task-reviewer — un agent d'examen indépendant et en lecture seule. Vous DEVEZ le spawner 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 continuer. Le reviewer poste un commentaire VERDICT sur la tâche.

Après la fin du reviewer, 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 — Toutes les AC vérifiées, aucun problème. Procédez à la vérification admin.
• VERDICT: PASS WITH NOTES — Toutes les AC vérifiées, 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 le retour du reviewer, il a épuisé son budget de tours avant de le poster. Respawnez-le UNE FOIS avec un indice budget concis dans l'invite : "Restez dans le budget de tours. Sautez la vérification approfondie. Récupérez task/proposal/comments, exécutez uniquement les tests essentiels et postez votre commentaire VERDICT dans les 12 premiers tours." Si la deuxième tentative ne produit toujours pas de VERDICT, vérifiez manuellement en utilisant la checklist et procédez.

Portail final d'examen de code (après la DERNIÈRE tâche de l'Idea vérifiée) : quand la tâche que vous venez de vérifier est la dernière tâche de sa proposal enracinée dans l'idea, la fonctionnalité est sur le point de sortir — l'extension vous encourage à spawner chorus-code-reviewer (gated par CHORUS_ENABLE_CODE_REVIEWER, défaut activé). Spawner-le vous-même via l'outil subagent bloquant, en passant le ideaUuid + numéro de round ; il examine le changement de code agrégé de l'Idea sur toutes ses tâches (intégration cross-task, architecture, sécurité, régression, couverture au niveau des features) et poste un commentaire VERDICT sur l'idea. PASS / PASS WITH NOTES → ship ; FAIL → corriger via /skill: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 les tâches vérifiées). Regroupez les petits BLOCKERs connexes par défaut ; divisez uniquement les corrections matériellement grandes ou indépendamment testables. Exigez l'auto-vérification AC, l'examen indépendant des tâches et la vérification admin pour chaque tâche de correction. Réexécutez l'examen agrégé uniquement après que chaque correction soit avec succès en done ; une correction échouée ou annulée arrête la boucle et escalade, borné par CHORUS_MAX_CODE_REVIEW_ROUNDS (env, défaut 3 ; 0 = illimité). Consultatif/comportemental, comme les autres reviewers. Exécutez-le avant tout rapport de fin d'idea.

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

Si le reviewer retourne FAIL, ou si la tâche est réouverte après vérification :

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

1. Vérifiez les retours :

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

2. Corrigez tous les BLOCKERs listés dans le commentaire FAIL du reviewer.
3. Reconnectez-vous, corrigez les problèmes, signalez les corrections, resoumettez.

Étape 10 : Tâche complétée

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

Étape 11 : Rapport de fin d'Idea (consultatif)

Si la tâche que vous venez d'auto-vérifier était la DERNIÈRE d'une Idea (chaque Task sur chaque Proposal approuvée est maintenant en done/closed) et vous avez document:write, proposez d'appeler chorus_create_report via AskUserQuestion. La description du paramètre content porte le template de section. Ignorez en cas de refus — l'extension le rappellera au prochain run.

Session (Sous-agents uniquement)

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

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

Agent principal / Team Lead : aucune session requise — appelez les outils sans sessionUuid.

Intégration de sous-agents parallèles

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

Architecture à deux niveaux

Workflow du Team Lead

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

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

Ce que l'invite du Team Lead doit contenir :

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

Workflow du sous-agent

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

# 1. Se connecter à 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é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. (Optionnel) notifier le team lead via mailbox — vous avez besoin de son agentId
subagent_mailbox({ action: "send", agentId: "<team-lead-agentId>", message: "Task complete" })

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

Gérer les 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 en done ou closed.

Exécution par vagues (recommandée) :

1. chorus_get_unblocked_tasks — trouver les tâches prêtes
2. subagent_spawn workers pour la Vague 1 (asynchrone ; conservez les agentIds)
3. Attendez to_verify (interrogez chorus_list_tasks ou lisez les messages d'achèvement asynchrone), puis vérifiez chaque tâche (chorus_admin_verify_task → done)
4. subagent_manage close chaque worker terminé (libère son slot + ferme sa session Chorus)
5. chorus_get_unblocked_tasks — trouver les nouvelles tâches débloquées (Vague 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 Team Lead doit vérifier les tâches entre les vagues. Rappelez-vous aussi de subagent_manage close les workers terminés — Pi limite les sous-agents concurrents et completed ne libère pas le slot.

Plusieurs tâches par sous-agent

Un seul 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 indépendamment, car elle appelle chorus sur sa propre fetch MCP-over-HTTP (pas la passerelle du sous-agent).

Dépannage

Bonnes pratiques de signalement du travail

Bon rapport (permet la continuité de session) :

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

Mauvais rapport : Terminé.

Conseils

• Lire d'abord les commentaires de la tâche — ils contiennent les rapports de travail précédents pour la continuité de session
• Vérifier les dépendances en amont — lisez les tâches dependsOn et leurs commentaires pour les interfaces/APIs
• Lire la proposal d'origine — comprendre la rationale de conception et le DAG des tâches
• Utiliser commentCount — ignorez la récupération de commentaires sur les entités avec un count de 0
• Signalez la progression fréquemment — incluez les chemins de fichiers, commits et PRs
• Écrivez des résumés de soumission détaillés — l'Admin en a besoin pour vérifier
• Si bloqué, ajoutez un commentaire et envisagez de libérer la tâche
• Une tâche à la fois : terminez ou libérez avant de réclamer une autre
• Utilisez des noms de sous-agents significatifs — 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é)
• Une tâche de priorité plus élevée a besoin d'attention
• Vous ne finirez 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 révise en utilisant /review
• Wake humain "Start Development" : un wake start_development (l'humain a cliqué Start Development sur le panneau détail-idea) signifie : réclamer et exécuter TOUTES les tâches restantes de la proposal approuvée de l'idea dans l'ordre des dépendances — bouclez ce workflow jusqu'à ce qu'aucune tâche claimable ne reste, laissant to_verify et les tâches d'autres sessions intouches.
• Wake humain "Yolo" : un wake yolo_requested (l'humain a cliqué Yolo sur le panneau détail-idea) signifie : piloter l'ENTIÈRE idea jusqu'au done via la skill yolo (le pipeline AI-DLC complètement automatique), pas seulement l'étape d'exécution — lire l'état actuel de l'idea et reprendre à partir de n'importe quelle phase elle est dedans. Contrairement à start_development elle est adaptive par étape, et elle ne doit jamais merger ou pusher une PR sans approbation humaine explicite.
• Pour l'aperçu de la plateforme et les outils partagés, voir /chorus