Compétence Plan-Doc-Do-Follow
Planifier → Documenter → Faire → Suivre
Correspond à l'intention → première route gagnante → lire routes/a-b.md (route a/b) → la suivre → appliquer les Invariants Globaux + Modèle de Statuts. Charger uniquement la route nécessaire, ses modèles, ses sous-agents — jamais tout.
Routes
Planification
| Intention | Route | Paramètres |
|---|---|---|
| Extraire les epics de la vision produit | plan/proj | |
| Valider les epics avec les parties prenantes | plan/proj-review | |
| Créer le PRD d'épique et son suivi | plan/epic | E{n} |
| Valider la spécification ou l'architecture d'épique | plan/epic-review | E{n} {prd |
| Concevoir l'architecture d'épique | plan/epic-arch | E{n} |
| Créer le PRD de fonctionnalité | plan/feat | E{n} F{n} |
| Valider la spécification ou l'architecture de fonctionnalité | plan/feat-review | E{n} F{n} {prd |
| Architecture de fonctionnalité (exception uniquement) | plan/feat-arch | E{n} F{n} |
| Découper la fonctionnalité en tâches | plan/tasks | E{n} F{n} |
| Changement de périmètre — ajouter/mettre à jour une fonctionnalité ou un épique, même implémenté | plan/change | description |
| Migrer les docs projet v2 vers v3 (en une fois) | plan/migrate |
Exécution
| Intention | Route | Paramètres |
|---|---|---|
| Configurer l'outillage d'économie de tokens (LSP, filtres, économie, agents natifs) | do/init | |
| Exécuter une tâche | do/task | E{n} F{n} T{n} |
| Exécuter toutes les tâches d'une fonctionnalité, vérifier en ligne | do/all-tasks | E{n} F{n} |
| Vérifier le travail terminé (chemin tâche par tâche) | do/verify | E{n} F{n} |
| Recalculer et réparer tous les statuts | do/sync-status | |
| Mémoriser les bonnes pratiques | do/memorize |
Invariants Globaux (toutes routes)
- Vérification d'esprit : s'aligner avec
docs/product.md; Esprit Produit (haut dedocs/project-status.md) textuellement dans chaque route de planification + briefing du relecteur - Volonté de l'utilisateur :
docs/decisions.mdcontraignant ; écart = question, jamais application silencieuse - Métier d'abord : relecture de spécification avant la phase suivante
- Vérification architecture : s'aligner avec
docs/global_architecture.md+docs/technical-stack.md - Un fait, un fichier : le statut/le fait a un fichier propriétaire (Modèle de Statuts) ; les autres lient, ne copient jamais
- Langue du public : humain/métier = phrases complètes, pas d'abréviations non expliquées ; agent = style Document (caveman concis)
- Pas d'échafaudage vide : supprimer les sections de modèles inutilisées ; jamais "N/A" ni espaces réservés
- Pas de supposition : ambiguïté bloquante → demander d'abord ; étiqueter bloquant / important / mineur
- Traçabilité : chaque doc référence le parent ; histoires ↔ exigences ↔ tâches ↔ tests liés
- Docs globaux vivants :
docs/data-model.md,docs/ui-map.md,docs/decisions.mdmis à jour dans le même changement qui les affecte — jamais "plus tard" - Hiérarchisation des modèles :
plan/*+ relecteurs = modèle fort ; chaque tâcheplan/tasksexécutable par un modèle plus faible sans ouvrir le PRD - Synchronisation des statuts : toute route modifiant un statut se termine par la procédure de Synchronisation des Statuts
- Format de passage : résumé court · progrès actuel · commande suivante exacte · questions ouvertes
- Sous-agents cadrés : uniquement les entrées de leurs listes de définition
- État d'esprit par route : adopter la ligne d'état d'esprit de la route
- Délibération interne : les échanges du critique ne finissent jamais dans les docs/passages — l'humain voit le résultat final + ce qu'il faut valider
- Économie partout : Économie de Travail sur chaque route et sous-agent
Modèle de Statuts
⚪ TODO · 🟡 SPEC spécifié · 🟣 PLAN tâches générées · 🔵 DEV en cours · 🟢 DONE terminé et vérifié
Propriété — source unique de vérité
| Fait | Fichier propriétaire (UN endroit écrit) |
|---|---|
| Statut de tâche | feat-tasks.md — Tableau Résumé des Tâches |
| Statut et progression de fonctionnalité | epic-status.md — Tableau des Fonctionnalités |
| Statut et progression d'épique | docs/project-status.md — Tableau Feuille de Route des Épiques |
| Progression du projet | docs/project-status.md — Section Progression |
Pas de feat-status.md. Sections par tâche : pas de ligne de statut. Mermaid = décoratif, régénéré à partir des tableaux propriétaires, jamais source de vérité.
Règles de dérivation
- Fonctionnalité : pas de
feat-prd.md→ ⚪ · PRD existe → 🟡 ·feat-tasks.mdexiste, aucune tâche au-delà de TODO → 🟣 · toute tâche DEV/DONE → 🔵 · 🟢 uniquement via les portes de vérification (do/verify, ou phase finale dedo/all-tasks). Tâches ajoutées à une fonctionnalité 🟢 → revenir à 🔵 - Épique : pas de
epic-prd.md→ ⚪ · PRD existe → 🟡 · toutes les fonctionnalités ≥ 🟣 → 🟣 · toute fonctionnalité 🔵/🟢 (pas toutes 🟢) → 🔵 · toutes 🟢 → 🟢 - Projet : même agrégation sur les épiques
- Progression : tâches terminées / tâches totales (0 si aucune), sommée au niveau épique et projet
Procédure de Synchronisation des Statuts
Fin de toute route modifiant un statut (autonome : do/sync-status, tous les épiques) :
- Lire les Tableaux Résumé des Tâches de(s) fonctionnalité(s) affectée(s)
- Recalculer chaque statut + progression de fonctionnalité ; mettre à jour la ligne dans
epic-status.md - Recalculer chaque épique affecté ; mettre à jour sa ligne, sa section Progression, son camembert dans
docs/project-status.md. La Synchronisation des Statuts n'écrit jamais de journal des modifications — seuls les événements nommés par la règle stricte du journal des modifications (style Document), écrits par la route qui a produit le jalon - Signaler la dérive (stocké ≠ dérivé) dans le passage
Déterministe et idempotent
Sous-agents
Définitions dans subagents/ — un fichier par agent (format : subagents/README.md). Invoquer : lire le fichier → assembler exactement les entrées listées (les relecteurs reçoivent toujours l'Esprit Produit) → lancer avec le corps du fichier comme prompt système
Profil économique
Lire Économie du sous-agent : dans la section Outillage du fichier d'instructions du dépôt (do/init l'écrit). Manquant → équilibré
| Profil | Comportement |
|---|---|
strict | En ligne d'abord · éclaireur presque toujours en ligne · plafonds question/outil/retour appliqués · les critiques se lancent toujours |
équilibré | En ligne d'abord comme écrit ci-dessous · plafonds appliqués · avertissement léger si >5 questions éclaireur |
qualité | Barrière de coût uniquement consultative · les plafonds s'appliquent toujours à l'utilisation d'outil par l'éclaireur et à la taille de retour |
Avant tout lancement (en ligne d'abord)
Exécuter dans l'ordre — première correspondance gagnante → ne pas lancer :
- Faits déjà dans le contexte principal → travailler en ligne
- Répondable par le principal en ≤5 appels Grep/Glob/Lire (ou LSP) → en ligne (utiliser la liste de vérification scout-lite dans
subagents/repo-scout.md) - Le briefing approcherait la taille de la réponse attendue → en ligne
- Résultats probablement cosmétiques / liste de contrôle mécanique sur une petite surface → en ligne (identique à la barrière de coût actuelle)
- Sinon lancer
repo-scout supplémentaire (sous strict / équilibré) : lancer uniquement si ≥3 questions falsifiables et la recherche couvre ≥2 zones que le principal n'a pas ouvertes, ou le contexte principal est déjà volumineux et l'isolation clairement moins coûteuse. Sinon scout-lite en ligne
Lors du lancement :
- Injection d'outillage : le briefing inclut un bloc Outillage d'une ligne du fichier d'instructions du dépôt (préfixe de filtre CLI, préférence LSP, profil économique) — le sous-agent doit l'obéir
- Briefing précis : questions/vérifications exactes · normes utilisées pour le travail · hors périmètre · pour l'éclaireur, chemins/globs de départ lorsque la zone est connue · ≤5 questions par vague d'éclaireur (
équilibré/strict; diviser ou mettre en ligne le reste) - Placer la barre d'avance : avant l'ébauche, lire les questions de révision du critique ; ébaucher pour réussir du premier coup
- Plafond de retour : éclaireur ≤15 lignes · critiques ≤25 lignes · le principal ne garde que les faits nécessaires — jamais coller les vidages d'éclaireur dans les docs
Résultats du critique : appliquer s'ils changent le comportement, le contrat ou la décision humaine ; laisser tomber silencieusement les résultats futiles/cosmétiques. Avis de jugement rejeté → question de décision pour l'humain. Convergence : une exécution par doc ; au plus une nouvelle exécution après un remaniement substantiel des résultats bloquants, limitée à ceux-ci — la nouvelle exécution n'accepte que les bloquants ; jamais de troisième exécution. Ne jamais signaler l'échange (Invariant 16)
| Sous-agent | Type | Appelé par | Quand |
|---|---|---|---|
repo-scout | recherche | plan/epic-arch, plan/feat, plan/feat-arch, plan/change | le plan doit s'appuyer sur le code existant |
prd-critic | relecteur | plan/epic, plan/feat | toujours |
arch-critic | relecteur | plan/epic-arch, plan/feat-arch | toujours |
perf-critic-backend / -frontend | relecteur | routes d'architecture, portes de vérification | uniquement lorsque les critères de déclenchement (haut de leurs fichiers) se déclenchent |
task-checker | relecteur | plan/tasks | après auto-relecture ; max deux exécutions |
feature-coder | exécuteur | do/all-tasks | un par tâche parallélisable par vague |
ui-consistency-reviewer | relecteur | portes de vérification | fonctionnalités UI, surface non triviale |
doc-coherence-reviewer | relecteur | portes de vérification · plan/change · plan/migrate | achèvement d'épique · après changement · après migration |
Les portes de vérification (+ leurs sous-agents) s'exécutent dans do/verify ou en ligne comme phase finale de do/all-tasks
UX révision humaine
Conclusions, pas de processus. Vérifications mécaniques auto-vérifiées → une ligne de résumé. "Décisions nécessitant votre validation" : ≤10 déclarations en phrases simples + questions ouvertes étiquetées bloquant/important/mineur. Décisions validées → docs/decisions.md. Réponses des parties prenantes textuellement — jamais paraphraser, jamais redemander (si ambigu, demander uniquement clarification)
Économie de Travail (Invariant 17)
Économie d'entrée
- Préférer la navigation LSP/sémantique aux lectures de fichiers entiers ; plages de lignes ciblées
- Préférer Grep/Glob/LSP à Shell pour la recherche de code — Shell uniquement lorsque nécessaire
- Sortie CLI longue (tests, builds, git, gestionnaires de paquets) via un filtre déclaré dans le dépôt (ex.
rtk,snip) —do/initle configure ; si Shell utilisé sans hook actif, préfixer manuellement - Ne jamais relire ce qui est dans le contexte ; ne jamais charger un doc "par sécurité"
- Obéir au profil économique + en ligne d'abord avant de lancer (Sous-agents)
Style de sortie (principal et sous-agents)
- Caveman concis (même barre que les docs orientés agents) : pas de préambule, pas de redemande, pas de résumé final, pas de remplissage/d'atermoiement
- Code, commandes, chemins, erreurs : octet exact — jamais paraphraser
- Changements de code sous forme de diffs ou d'éditions ciblées — jamais de listages de fichiers entiers sauf demande
- Réponses de recherche ≤10 lignes sauf profondeur demandée ; les retours des sous-agents obéissent au plafond de retour
- Passage (Invariant 13) = uniquement bloc de clôture : ≤5 lignes
Implémentation minimale (routes do et feature-coder)
Comprendre complètement, s'arrêter au premier barreau qui tient :
- N'a pas besoin d'exister → sauter (YAGNI)
- Déjà dans la base de code → réutiliser
- La bibliothèque standard le fait → l'utiliser
- Fonctionnalité native de la plateforme → l'utiliser
- Dépendance installée → l'utiliser
- Une seule ligne suffit → une ligne
- Alors seulement écrire le minimum qui fonctionne
Ne jamais couper : validation de limite de confiance, gestion de perte de données, sécurité, accessibilité
Style Document
Deux publics — choisir par objectif du fichier, pas par humeur de route
Humain / métier (prose complète) — PRDs (epic-prd.md, feat-prd.md), docs/product.md, Esprit Produit, corps de révision humaine (*-review.md sections de décision), docs centrés utilisateur (developer-setup, onboarding, READMEs humains). Phrases complètes. Lisible par les parties prenantes. Pas d'abréviations non expliquées
Orientation agent (caveman concis) — manuels de compétence (SKILL.md, routes/, subagents/, commentaires de modèles), feat-tasks.md, epic-arch.md / feat-arch.md, tableaux/notes de statuts, docs techniques vivants (data-model.md, ui-map.md, decisions.md), docs/patterns/*. Inspiré par caveman intégral :
- Faits et ordres uniquement — supprimer articles/remplissage/atermoiement quand le sens est clair ; fragments acceptés
- Synonymes courts ; motif
[chose] [action] [raison]·[prochaine étape] - Pas d'abréviations inventées (
cfg/impl/fn) ; acronymes techniques connus acceptés (DB/API/HTTP) - Chemins, symboles, code, commandes, chaînes d'erreur : exacts
- Ne jamais supprimer
ne pas/jamais/non/uniquement/sauf - Pas de point final avant saut de ligne (points en milieu de ligne dans les phrases multi-clauses restent)
- Décisions et faits uniquement — jamais de processus ("le relecteur a suggéré…", "après discussion…")
- Justifier uniquement lorsque l'agent futur a besoin du pourquoi (compromis, coupe de périmètre) : ≤2 lignes courtes
- Clarté automatique : prose plus complète pour les avertissements de sécurité, les étapes irréversibles ou les fragments qui risquent une mauvaise lecture de l'ordre/de la négation — puis reprendre concis
Règle stricte du journal des modifications : une ligne {date} : {fait}, ≤25 mots. Éligibles uniquement — projet : épique terminé, changement de périmètre majeur, migration ; épique : fonctionnalité vérifiée 🟢, changement de périmètre. Tout le reste (tâches générées, PRD rédigé/approuvé, vagues, synchronisations, réparations de dérive) = aucune entrée. Jamais : échanges de critiques (Invariant 16), listes de tâches, résultats de portes, nombres de progression, commandes Suivant :. Entrées existantes verbeuses = héritage, jamais précédent — écrire uniquement la ligne éligible, ou rien
Organisation des Fichiers
docs/
├── product.md (entrée : vision produit)
├── global_architecture.md (entrée : aperçu architecture)
├── technical-stack.md (entrée : décisions technologiques)
├── project-status.md (propriétaire : Esprit Produit, statuts épiques, progression)
├── project-review.md
├── decisions.md (vivant : décisions utilisateur contraignantes, une ligne chacune)
├── data-model.md (vivant : schéma global des données, le cas échéant)
├── ui-map.md (vivant : carte de navigation globale, si UI)
├── design-guidelines.md (vivant : conventions de style UI, si UI)
├── patterns/{nom-du-modèle}.md (de do/memorize)
└── epics/e{n}-{nom-d-épique}/ (slug ex. e2-orm-discovery)
├── epic-brief.md (plan/proj)
├── epic-prd.md (plan/epic)
├── epic-status.md (propriétaire : statuts fonctionnalités)
├── epic-arch.md (plan/epic-arch)
├── epic-review.md (plan/epic-review)
└── f{n}-{nom-de-fonctionnalité}/ (enfant direct — pas de niveau features/)
├── feat-prd.md (plan/feat ; a Points d'Entrée + Delta Architecture)
├── feat-arch.md (plan/feat-arch — exceptions uniquement)
├── feat-tasks.md (propriétaire : statuts tâches)
└── feat-review.md (plan/feat-review)
Intégration plateforme
Conventions de dépôt, précédence : CLAUDE.md · AGENTS.md · .github/copilot-instructions.md · .cursor/rules/ · .github/instructions/. do/memorize écrit dans le(s) fichier(s) réellement présent(s)
Modèles
Dans templates/ — les noms correspondent aux fichiers de sortie