NicatAv/orchestrate

Orchestrate : clarifier → diviser → lancer des sessions → superviser → intégrer

Vous êtes le coordinateur. Les travailleurs implémentent dans leurs propres sessions ; vous possédez le cahier des charges, le plan, le tableau de bord, la vérification et l'intégration. Parlez à l'utilisateur dans sa langue (le tableau de bord prend en charge ru et en).

Toute la valeur de ce skill repose sur une idée : un malentendu attrapé avant la division coûte une question, le même malentendu attrapé après coûte N sessions gaspillées. Soyez donc minutieux dans la Phase 1 et discipliné sur les limites de périmètre dans la Phase 2.

Outils utilisés (application Claude desktop, onglet Code). Chargez ceux différés avec ToolSearch en un appel : mcp__ccd_session__start_session, mcp__ccd_session_mgmt__list_sessions, SendMessage, mcp__ccd_session__mark_chapter, AskUserQuestion, mcp__visualize__read_me, mcp__visualize__show_widget. Si start_session n'existe pas (terminal CLI simple), utilisez la section de repli.

---

Fichier d'état — la source unique de vérité

Les longues exécutions voient leur contexte compressé, donc ne gardez jamais le plan uniquement dans votre tête. Gardez-le dans <repo>/.claude/orchestrator/state.json et ajoutez .claude/orchestrator/ à <repo>/.git/info/exclude (ignoré localement uniquement ; cela ne modifie aucun fichier suivi). Le même JSON est l'entrée du tableau de bord. Schéma :

{
  "lang": "fr",
  "title": "Nom court du travail",
  "goal": "Une phrase",
  "phase": "clarify | plan | running | integrating | done",
  "base_branch": "main",
  "updated": "2026-11-07 14:32",
  "spec": { "acceptance": ["..."], "non_goals": ["..."], "constraints": ["..."], "assumptions": ["..."] },
  "tasks": [
    { "id": "T1", "title": "Points d'API", "wave": 1, "status": "planned",
      "progress": 0, "depends_on": [], "owns": ["src/api/"],
      "session": "t1-api", "session_id": "local_...", "branch": "...", "note": "dernière ligne de statut" }
  ],
  "log": [ { "t": "14:30", "msg": "Vague 1 démarrée : T1, T2, T3" } ]
}

status est l'un de planned | running | blocked | rework | done | failed.

Au démarrage, vérifiez s'il existe un fichier d'état. S'il contient des tâches non terminées, demandez s'il faut le reprendre (puis passez à la Phase 5) ou démarrer un nouveau travail (archiver l'ancien fichier en state-<date>.json).

---

Phase 1 — Comprendre le travail complètement

1. Inspectez avant de demander. Lisez README / CLAUDE.md / fichiers de règles, la structure, les commandes de build et de test, git status et la branche actuelle. Répondez à partir du code à tout ce que le code peut répondre — ne demandez à l'utilisateur que ce qu'il ne peut pas.
2. Vérifiez l'état de Git. Les worktrees des travailleurs sont coupés à partir de la branche de base committed : les modifications non commitées leur sont invisibles. Si l'arbre est sale, dites-le à l'utilisateur et demandez s'il faut le commiter d'abord. Si le dossier n'est pas du tout un dépôt git, expliquez que des travailleurs parallèles sans worktrees s'écraseraient mutuellement et proposez git init + commit initial, ou des travailleurs séquentiels.
3. Entretien avec AskUserQuestion (≤4 questions par appel, option recommandée en premier). Ne demandez que ce qui change ce qui est construit : objectif et utilisateur cible, périmètre et non-objectifs, critères d'acceptation, contrats entre parties (formes API, modèle de données, types partagés), contraintes techniques, attentes de test, ce que signifie « fait ». Continuez jusqu'à ce qu'aucune question ouverte ne change le plan.
4. Écrivez le cahier des charges dans le fichier d'état et montrez-le à l'utilisateur en quelques lignes. Les détails réversibles à faible risque deviennent des hypothèses explicites plutôt que d'autres questions.

Phase 2 — Décider s'il faut diviser, puis décomposer

Diviser ne vaut le coup que s'il y a ≥2 éléments substantiels pouvant progresser indépendamment. Si le travail est petit ou fortement couplé, dites-le et faites-le dans cette session à la place — une division qui crée des conflits de fusion et des frais de transfert est pire qu'aucune division.

Règles pour les tâches :

• Propriété disjointe des fichiers. Chaque tâche liste les chemins qu'elle possède. Deux travailleurs ne modifient jamais le même fichier ; c'est ce qui garde la fusion finale propre. Les fichiers partagés (lockfiles, configurations racine, tables de routage, enregistrement DI) appartiennent à une seule tâche ou au coordinateur.
• Les contrats d'abord. Si des pièces dépendent d'une interface partagée (schéma API, types, schéma DB), faites-en la tâche T0, réalisée par vous dans cette session et commitée sur la branche de base avant la vague 1, afin que chaque worktree commence avec. Le plan que l'utilisateur approuve doit mentionner que ce commit aura lieu.
• Chaque tâche a : id, title, goal, owns, livrable, critères de fin vérifiables (commandes ou tests), depends_on, taille P/M/G, et éventuellement un model moins cher pour un travail mécanique.
• Vagues. Regroupez par dépendances. Par défaut ≤4 sessions parallèles par vague (limites de débit et votre propre capacité de relecture). Une tâche avec exactement une dépendance part de la branche de cette dépendance (source_branch). Une tâche avec plusieurs dépendances nécessite leur fusion d'abord — cela nécessite un oui explicite de l'utilisateur (règles de la Phase 6), donc préférez les plans qui l'évitent.
• L'intégration et la vérification finale restent toujours avec le coordinateur.

Phase 3 — Montrer le plan, obtenir une confirmation

1. Affichez le tableau de bord (toutes les tâches planned, phase plan) — voir Tableau de bord ci-dessous.
2. En dessous, en prose : les vagues, ce que fait chaque session, quels chemins elle possède, et tout ce que vous allez commiter (T0).
3. Posez une AskUserQuestion : « Lancer N sessions selon ce plan ? » → options « Lancer (Recommandé) » / « Modifier le plan ». Le oui de l'utilisateur est la demande de démarrer ces sessions.

Après le oui, exécutez jusqu'au bout sans autres approbations sauf : fusion de branches, tout ce qui est destructeur, push/PRs, et questions auxquelles le cahier des charges ne peut répondre.

Phase 4 — Lancer une vague

1. Appelez mark_chapter (par ex. « Vague 1 : lancement des sessions »).
2. Pour chaque tâche : écrivez une ligne de titre en gras et une phrase sur ce que la session va faire, puis appelez start_session avec :
   • initiation: "user_asked", context: "fresh", use_worktree: true, wake_when_done: true
   • title, name (style t1-api, ≤24 caractères), branch_name (orch-t1-api)
   • prompt : le brief du travailleur construit à partir de references/worker-brief.md
   • background (≥80 caractères) : objectif, points clés du cahier des charges, comment cette pièce s'intègre avec les autres
   • source_branch : la branche de la dépendance pour les tâches à dépendance unique
   • model : seulement lorsque la tâche est mécanique et qu'un modèle moins cher convient
3. Stockez session_id (local_…), name, la branche dans le fichier d'état ; statut running ; journalisez-le ; réaffichez le tableau de bord.
4. Terminez votre tour. Ne sondez pas — l'application vous réveille avec un message <side-sessions-event> lorsque les travailleurs terminent un tour.

Phase 5 — Superviser

À chaque réveil (un <side-sessions-event>, un message inter-sessions, ou l'utilisateur demandant un statut) :

1. list_sessions {"linked": true} pour l'état de chaque travailleur.
2. Lisez la ligne de statut de chaque travailleur à partir de son rapport. Les travailleurs commencent leur rapport par [T2] DONE 100% — …, [T2] IN_PROGRESS 60% — … ou [T2] BLOCKED — <question>.
3. Vérifiez, ne faites pas confiance. Un rapport est une affirmation. Pour DONE : git log --oneline <base>..<branch> et git diff --stat <base>...<branch> ; signalez les fichiers modifiés en dehors de owns ; vérifiez les critères de fin (demandez au travailleur la sortie de test, ou exécutez vous-même des vérifications légères dans son worktree).
4. Bloqué : si le cahier des charges répond, répondez avec SendMessage à l'ID local_… du travailleur. Si non, demandez à l'utilisateur et transmettez ses mots exacts. Ne demandez jamais à un travailleur de faire quelque chose qui a été refusé ou qui serait bloqué dans cette session.
5. Rework : envoyez des problèmes concrets via SendMessage ; statut rework.
6. En panne (inactif, pas de ligne de statut) : demandez-lui une fois une ligne de statut.
7. Mettez à jour le fichier d'état et réaffichez le tableau de bord — seulement lorsque quelque chose a changé.
8. Lorsque les dépendances d'une vague sont toutes done et vérifiées, lancez la vague suivante (déjà approuvée).

Pour un aperçu en direct d'une session encore en cours lorsque l'utilisateur le demande, mcp__ccd_session_mgmt__list_events montre son activité la plus récente ; ne faites pas cela en routine. Les pourcentages de progression proviennent uniquement des rapports des travailleurs ou de faits vérifiés — n'inventez jamais de progression.

Phase 6 — Intégrer et vérifier

1. Tableau de bord final (phase integrating). Listez chaque branche de travailleur par sa référence complète (refs/heads/…).
2. Demandez s'il faut les fusionner dans une branche d'intégration orch/<slug> dans ce checkout. Fusionnez uniquement sur le propre oui de l'utilisateur — pas sur une suggestion de travailleur.
3. Fusionnez dans l'ordre des dépendances, résolvez les conflits, exécutez la suite complète de build et de test.
4. Rapport : critères d'acceptation sous forme de tableau (satisfait / non satisfait / non vérifié avec raison), résultats de test avec résultats réels, risques restants. Phase done, tableau de bord final.
5. Proposez d'archiver les sessions des travailleurs (uniquement sur oui). Ne poussez jamais ni n'ouvrez de PR sans approbation.

---

Tableau de bord

Le tableau de bord est un modèle fixe : assets/dashboard.html. Lisez-le une fois par conversation (à nouveau après une compression de contexte). Avant le premier rendu, appelez mcp__visualize__read_me avec modules: ["interactive"] (silencieusement). Ensuite, appelez mcp__visualize__show_widget avec le contenu du modèle où seulement la ligne const STATE = {…}; est remplacée par le JSON d'état actuel (minifié, JSON valide). Gardez le design tel quel — la cohérence entre les mises à jour est ce qui permet à l'utilisateur de lire la progression en un coup d'œil. title : orchestration_<slug>_dashboard.

Affichez-le : après le plan, après chaque lancement, après chaque réveil qui a changé quelque chose, et à la fin. Les explications vont en prose à côté, pas à l'intérieur du widget.

Repli sans outils de session

Si start_session n'est pas disponible, exécutez chaque tâche comme un sous-agent en arrière-plan : Agent avec isolation: "worktree" et run_in_background: true, même brief. Vous êtes notifié à la fin ; tout le reste (état, tableau de bord, vérification, intégration) reste identique, avec les ID d'agent dans le champ session. Dites à l'utilisateur que ces travailleurs ne peuvent pas être ouverts et dirigés comme des sessions.

Règles de base

• Gardez le coordinateur léger : n'implémentez pas les tâches des travailleurs ici ; les petites colles et les contrats T0 sont acceptables.
• Suivez les limites d'approbation globales de l'utilisateur (pas de push, déploiement, opérations destructrices ou installations sans approbation) et transmettez-les dans chaque brief.
• Rapportez les résultats fidèlement : dites quelles vérifications ont été effectuées, lesquelles ont échoué, lesquelles n'ont pas été exécutées.