DevOtts/plan-it

Que fait plan-it ?

Prenez une demande floue → livrez un package de livraison prêt à être construit. C'est le chef d'orchestre de la planification : la moitié avant disciplinée du cycle de vie qui se termine exactement là où /build-it commence. Il effectue la découverte (recherche de la vérité terrain), la spécification (rédaction des documents de conception) et le découpage agile (PRD, épopées, tests, le contrat partagé) — puis passe la main.

  /plan-it  ─────────────►  docs/ + delivery/  ─────────────►  /build-it
  (découverte → spécification → plan)   (le package livrable)            (le construit)

Utilisable directement par un humain, et par tout agent conducteur orchestrateur qui reçoit une nouvelle demande et doit la transformer en package de livraison avant de dispatcher les travailleurs.

---

Les cinq règles non négociables (appliquez-les — ne vous contentez pas de les suggérer)

Ce sont les règles porteuses de charge, rétro-conçues à partir de chaque exécution réussie. Si vous en enfreignez une, la construction en aval dérive ou échoue silencieusement.

1. Gelez un CONTRAT partagé avant toute planification parallèle. Le CONTRAT fait loi : entités canoniques, schéma, API/interface, énumérations, carte dépôt/branche et la définition de « livré ». Les équipes écrivent en fonction de lui ; toute découverte transversale est réintégrée sous forme d'amendement daté (v1.0 → v1.1…). Pas de contrat gelé → pas d'équipes parallèles.

2. Regroupez TOUTE décision humaine en une seule porte. Ne pré-décidez rien d'irréversible (topologie du dépôt, hébergement, nom du produit, mode architectural, build-vs-buy). Présentez-les ensemble, chacune avec une recommandation jointe, et laissez l'humain répondre numéroté. Cette porte est l'endroit où l'humain injecte sa vision, et non pas simplement choisi des options — laissez de la place pour qu'il ajoute un concept que vous n'avez pas proposé. Verrouillez chaque réponse avec propriétaire + date.

3. Vérifiez la sortie de chaque agent sur le disque — « inactif ≠ livré ». Une équipe qui devient inactive ne signifie PAS qu'elle a écrit des fichiers. Après tout déploiement, vérifiez que les chemins réels existent et ne sont pas vides avant de continuer. Si une équipe a gardé sa sortie sous forme de message, dirigez-la vers Write vers le chemin absolu exact. Ne faites jamais confiance à un « fait ».

4. Fondez le plan sur le SYSTÈME EN DIRECT, pas sur le dépôt — avant de geler. Pour tout plan touchant un système en cours d'exécution, le dépôt est une hypothèse ; la réalité déployée est la vérité, et ils dérivent. Avant de geler le CONTRAT, vérifiez par rapport au système réel et écrivez les observations dedans (pas des suppositions dérivées du dépôt). Éprouvé au combat : dans un programme, CHAQUE correction en vol remontait à une hypothèse inférée du dépôt contredite par la réalité — identifiants canoniques incorrects (les manifestes avaient dérivé du catalogue déployé), une valeur de config présente mais pointant vers un hôte mort, des composants « à construire » déjà déployés, et un identifiant trouvé qui était le mauvais. Voir la porte d'ancrage en direct de la Phase 3 pour les vérifications concrètes.

5. Exécutez la machine, pas la prose. Le flux de contrôle du pipeline vit dans machine.json (le diagramme d'états explicite), pas dans ce document — cette prose explique la machine. À l'invocation, lisez ou initialisez .plan-it/state.json (dans le projet cible) et reprenez à partir de son state ; écrivez-le à chaque transition. À chaque transition gardée, exécutez la sous-commande mappée du garde (node scripts/gate-check.mjs <check> …) et n'avancez jamais sur un code de sortie non nul — corrigez, réexécutez, puis transitionnez. Si Node est indisponible, effectuez les mêmes vérifications manuellement et enregistrez-les dans le fichier d'état (dégradez, ne cassez jamais). Protocole complet : references/machine.md.

---

Le cœur déterministe (v2) — pourquoi une machine

Le flux de contrôle écrit en prose (« faites l'étape 1, ne sautez jamais la porte ») est ce que la littérature sur le déterminisme appelle le flux de contrôle en prose : il repose sur la discipline du modèle dans un contexte long et sujet au résumé, et parfois le modèle ne le suivra pas. v2 inverse cela à la bonne altitude — non-déterminisme aux bords, déterminisme au cœur :

• machine.json — Diagramme d'états compatible XState v5 du pipeline : 15 états, les trois portes humaines (meta.gate + meta.human), les transitions gardées, et une boucle AMENDMENT sur parallelPlanning. Collez-le dans stately.ai/viz pour le voir.
• .plan-it/state.json — l'exécution persistée : état courant, approbations de porte (propriétaire + date), version du contrat, registre des artefacts vérifiés, historique. C'est ce qui permet à une exécution de survivre à un crash ou à une nouvelle session.
• scripts/gate-check.mjs — les gardes en codes de sortie : verify (Règle 3, inactif ≠ livré), freeze (Règle 1, pas de contrat → pas d'équipes), handoff (la moitié mécanisable des playbooks §F), state (Règle 2, portes enregistrées), adversary (Règle 6 / D4 — profondeur de mode de défaillance : une machine modélisée doit couvrir-ou-renoncer aux cinq classes de cascade ; N/A pour les workflows linéaires). Les transitions LINT_CLEAN et ADVERSARY_CLEAN (verify → adversaryGate → handoff) sont gardées par les deux dernières.

Les phases floues — découverte, synthèse, rédaction de spécifications, jugement — restent LLM-au-nœud (marquées llmAtTheNode dans la machine). Ne les formalisez pas ; la modélisation n'est pas une cérémonie seulement lorsqu'elle remplace la confusion. Détails, schéma du fichier d'état et protocole de reprise : references/machine.md.

Application stricte (v2.1, installations de plugin sur Claude Code uniquement) : un hook PreToolUse (scripts/hooks/planit-guard.mjs) refuse les appels Write/Edit sur les livrables PRD/épopée tant que le contrat de l'exécution n'est pas gelé — la Règle 1 cesse d'être une instruction et devient quelque chose que le harnais refuse. Fonctionne en mode dégradé : il ne touche jamais au travail non lié à plan-it. Les installations de skill uniquement comptent sur la discipline de la Règle 5.

---

Le Contrat de Test — le différenciateur qualité (rendez-le non négociable)

La seule chose qui améliore le plus la qualité du code livré : chaque PRD/épopée se termine en générant son propre contrat de test — jusqu'à ~20 cas d'utilisation/scénarios concrets qui stressent l'implémentation — et la fonctionnalité n'est PAS « terminée » tant que 100% d'entre eux ne passent pas. L'agent de construction ne peut pas simplement livrer la fonctionnalité ; il doit satisfaire le contrat, et /iterate jusqu'au vert.

Il s'agit d'une discipline nommée et éprouvée : Specification by Example (Gojko Adzic) + ATDD/BDD pour le code (les exemples concrets deviennent des tests d'acceptation exécutables et une documentation vivante), et Eval-Driven Development pour les skills/fonctionnalités LLM (enregistrez les golden avec les sorties attendues, itérez jusqu'à ce qu'elles passent). Rédiger les cas au moment de la planification est tout l'intérêt — ils deviennent un contrat contraignant, et non une réflexion après coup.

Règles du Contrat de Test :

1. Rédigé au moment de la planification — la DERNIÈRE étape de la rédaction de chaque épopée/PRD est son contrat de test. Les sorties attendues sont enregistrées maintenant (« conçu en premier ; sorties attendues enregistrées »), et non découvertes en cours de construction.
2. Jusqu'à ~20 cas de haute qualité par fonctionnalité — assez pour stresser le comportement réel + les cas limites ; pas des milliers de cas superficiels (la qualité > la quantité — le volume automatique = « slop », selon la littérature d'évaluation). Tirez les cas des modes de défaillance réels/probables. Règle de comptage par forme : les programmes multi-équipes de grande forme-1 tiennent un minimum de ≥10 cas par épopée (chaque épopée est une grosse fonctionnalité) ; les petites formes (skill/fonctionnalité unique, S/M) rédigent ~20 cas au total dans le package (quelques-uns par épopée). Ne faites jamais les deux en même temps — choisissez par forme pour qu'un évaluateur ne signale pas un petit package correct comme sous-testé.
3. Contraignant — DoD = 100% du contrat passe ; jusqu'à ce moment, /iterate. Pas de livraison partielle ; pas de VÉRIFIÉ-sur-un-mock (un cas [REEL] dont la cible est inaccessible → IMPLÉMENTÉ-NON-VÉRIFIÉ, jamais un faux vert).
4. Choisissez les types de test par implémentation (un ou plusieurs parmi unitaire / e2e / cas d'utilisation / stress) :

Implémentation	Types de test	Comment
CRUD / API REST	cas d'utilisation (heureux + limites) + e2e	exécutez chaque scénario via API et via UI avec Chrome CDP (chrome-cdp-control) ; testez unitairement la logique
Skill / prompt / fonction LLM	cas d'utilisation avec sortie attendue	exécutez-le, comparez le réel vs attendu — correspondance exacte pour les sorties fermées, rubrique / LLM-en-tant-que-juge pour les sorties ouvertes (make-eval, promptfoo, DeepEval G-Eval)
Agent / avec état / multi-étapes	scénarios de stress + cas d'utilisation	six axes : asynchrone, fan-out, escalade, porte humaine, récursion, garde de cycle (Setup/Attendu/Passe)
Logique pure / bibliothèque	unitaire + basé sur les propriétés	cas énumérés + invariants
Pipeline de données / migration	valeur dorée + e2e	valeurs attendues calculées à la main ; idempotence/rollback
Tout ce qui a une surface de charge/abus	stress / adversarial	concurrence, débit, entrée malformée, équipe rouge

5. Chemin d'exécution : /full-qa exécute le contrat, /iterate le boucle à 100%, chrome-cdp-control pilote les scénarios UI. Le contrat est le pont de plan-it → build-it : la Définition de Fini de /build-it = ce contrat.

Grammaires et format d'en-tête du contrat : references/formats.md (le bloc Contrat de Test + §4–5).

---

Posture d'autonomie (guidée avec des bouffées autonomes)

Effectuez la recherche et la rédaction de manière autonome avec un effort élevé, mais arrêtez-vous à trois portes :

Porte	Quand	Ce que vous demandez
G1 — Périmètre	après l'accueil (Phase 2)	confirmez le dimensionnement (fonctionnalité vs programme) + le DoD numéroté avant de brûler de l'effort
G2 — Décisions	après la rédaction des spécifications (Phase 7)	les décisions regroupées « que vous seul pouvez prendre », chacune avec une recommandation
G3 — Livraison	avant le découpage agile (Phase 8)	« les spécifications semblent alignées — procéder aux PRD/épopées ? »

Tout entre les portes s'exécute sans surveillance. Recommandez /effort xhigh au début (vous ne pouvez pas le définir vous-même — dites à l'utilisateur d'exécuter /effort xhigh s'il ne l'a pas fait).

---

Phase 0 — Accueil

Machine d'abord (Règle 5) : si .plan-it/state.json existe dans le projet cible, exécutez node scripts/gate-check.mjs state .plan-it/state.json et reprenez à partir de l'état affiché — ne redémarrez pas les phases déjà dans history. S'il n'existe pas, créez-le maintenant dans l'état intake (schéma dans references/machine.md) et maintenez-le à jour à chaque transition pour le reste de l'exécution.

Acceptez la demande sous quelque forme qu'elle arrive : un brain-dump, une transcription collée, une liste de souhaits, ou une ligne unique. Attendez-vous à des pointeurs, pas à du contenu — noms de sessions (/read-chat "<name>"), chemins de dépôts, dossiers de documents. Votre travail est d'aller chercher la vérité terrain, pas de vous la faire donner.

Capturez au préalable :

• La vision brute dans les propres mots de l'utilisateur (vous la citerez dans 02 §1).
• Les pointeurs vers les sessions / dépôts / documents précédents à rechercher.
• Le cas d'utilisation (détection automatique — cela détermine la forme du package à la Porte G1) :
  • nouvelle application unique, greenfield · fonctionnalité sur un gros dépôt existant · programme multi-sous-systèmes from-scratch · plateforme multi-applications (nombreux PRD) · refactorisation / migration / dette · pic de recherche (pas de construction encore) · automatisation PM/tableau · documenter/auditer un système déjà construit.
• Méthode de recherche : par défaut, équipes Claude parallèles en xhigh.

Si la demande est vraiment un paragraphe flou sans pointeurs et un dépôt existant, c'est correct — le pré-ancrage (Phase 3) trouvera les cibles.

---

Phase 1 — Verrouillage du DoD

Reformez la prose floue en une Définition de Fini numérotée et individuellement vérifiable + une courte liste d'hypothèses énoncées. C'est votre contrat avec l'utilisateur pour le travail de planification lui-même. Exemple de forme :

DoD pour cette exécution de planification :
  1. Document des constats de vérité terrain (chaque affirmation → chemin:ligne ou tableau)
  2. Document de vision + architecture qui résout chaque constat/contradiction
  3. Contrat de données/interface
  4. … (taille automatique — voir Phase 2)
  N. Passation : contrat gelé, PRD+épopées avec ≥10 tests chacun, prompt de lancement
Hypothèses : <liste>

---

Phase 2 — Gouverneur de périmètre et de forme ⏸ PORTE G1

Choisissez la taille (combien) et la forme (quelle forme) avant de dépenser de l'effort. Confirmez les deux avec l'utilisateur.

La taille met à l'échelle le nombre d'artefacts :

Signal	Taille
Fonctionnalité unique, 1 sous-système	S
Multi-fonctionnalité / nouveau sous-système, 1–2 dépôts	M
Programme from-scratch / nombreux sous-systèmes	L

La forme est choisie par cas d'utilisation (définitions complètes + tableau cas d'utilisation→forme dans references/templates.md PARTIE D) :

1. Multi-doc + delivery/ (référence) — programme from-scratch, équipes parallèles.
2. PRD-fichier-unique-comme-tout — application unique greenfield ; CONTRAT intégré en tant que règles-G.
3. Recherche → architecture-verrouillée → PRD-maître+phase — fonctionnalité sur un gros dépôt existant.
4. implementation/<name>/ avec PRD-NN numérotés — plateforme multi-applications, nombreux PRD.
5. Catalogue de travaux de refactorisation/dette — brownfield sur place. (+ modes pic-de-recherche, tableau-exécutable et rétro-documentation — voir PARTIE D.)

Mêmes phases — seul le nombre d'artefacts et la forme changent. Ne donnez pas à une fonctionnalité une organisation de 4 équipes ; ne donnez pas à une refactorisation brownfield un document de vision greenfield. Présentez la taille + la forme choisies + le DoD numéroté et obtenez un oui avant de continuer. Sur oui, enregistrez G1 = {approved, owner, date} plus la taille/forme choisies dans .plan-it/state.json — la transition G1_APPROVED est gardée par gateRecorded.

---

Phase 3 — Pré-ancrage

Avant tout déploiement, localisez les cibles exactes afin que les agents reçoivent des chemins précis, pas des instructions vagues :

• Résolvez les sessions pointeur avec un skill de lecture de session (/read-chat ou similaire) s'il en est installé un ; sinon, demandez la transcription ou le résumé pertinent.
• ls/grep les dépôts nommés ; trouvez les docs/, les fichiers de schéma, les points d'entrée.
• Lisez le cache chaud/l'index du wiki si le dépôt est câblé au vault (selon son CLAUDE.md).

Sortie : une liste de {sous-système → chemins exacts à lire} qui alimente les équipes de recherche.

Porte d'ancrage en direct (règle 4) — quand le plan touche un système EN COURS D'EXÉCUTION

Le dépôt vous dit ce qui devrait être vrai ; le système en direct vous dit ce qui est. Faites-le avant le gel de la Phase 8, et écrivez les constats dans le CONTRAT comme faits observés :

• Accessibilité de la configuration, pas présence. Pour chaque levier d'environnement/config dont dépend le plan (URLs de base, hôtes API, feature flags), frappez-le — ne vous contentez pas de confirmer qu'il est défini. Une valeur peut être définie sur un hôte mort et passer une vérification « existe-t-il » tout en cassant silencieusement la production.
• Registre en direct / identifiants canoniques. Du...