picmakpro/vibeflow-os/planning-core

vf-planning — Socle de planning & documentation universel

Mission : poser et maintenir le tronc commun `.planning/` d'un lab — la couche qui répond

à « où va-t-on, où en est-on, qu'a-t-on décidé » — en l'adaptant à la logique métier du lab.

Iron Law : *« Le tronc est invariant ; tout le reste s'adapte au métier. On n'impose jamais

une forme (dev ou autre) à un lab qui a une autre logique. »*

Skill scaffoldeur thin, prose agent-driven : il lit le contexte du lab, choisit le bon niveau de rigueur, instancie les templates en les adaptant, et tient l'état à jour. Il ne force aucune structure déterministe et ne duplique pas la mémoire existante.

Le tronc commun (les 7 artefacts — toujours présents, jamais plus que nécessaire)

STATE.md est le seul fichier strictement obligatoire dans tous les cas. C'est lui qui tue la

perte de contexte : il se relit/reconstruit au démarrage de chaque session.

Le détail des 3 profils de rigueur (léger / standard / complet) et le mapping métier → profil sont dans references/PROFILES.md. La doctrine complète (pourquoi, anti-biais, adaptation par métier) est dans references/GUIDE.md. Charger on-demand.

Lab mono-objectif vs lab à compartiments (v2)

Deux topologies. Ne pas plaquer la mauvaise.

• Lab mono-objectif (un seul fil de travail) → un seul `.planning/` à la racine. C'est le cas

par défaut, comportement inchangé.

• Lab à compartiments (plusieurs projets internes / clients / process — ex. projects/*) →

steering au niveau lab + plan conditionnel par compartiment. Règle :

• Le lab porte PROJECT.md (identité) + STATE.md (focus transverse) + `INDEX.md`

(tableau de bord qui POINTE vers les plans). Jamais de `ROADMAP.md` global (plan mort).

• Un compartiment reçoit son propre socle .planning/ **seulement s'il passe le seuil

d'autonomie, et typé** :

• `deliverable` (a une fin) → STATE + ROADMAP + phases/MILESTONES selon profil ;
• `continuous` (se renouvelle) → STATE + `BOARD.md` (colonnes + WIP + cadence), **pas de

roadmap**.

• Sous le seuil, ou infra à suivi intrinsèque (finance/, pipeline/…) → pas de plan, juste une

ligne dans INDEX.md.

Doctrine complète (seuil d'autonomie chiffré, cas hybride, non-cannibalisation, migration sans perte) :

`references/compartments.md`. Charger dès qu'un lab a plusieurs projets/compartiments.

Étape 0 — Qui tient le planning de ce lab ? (TOUJOURS en premier)

Iron Law du rescope (ADR-055) : *« Un projet de code a un seul propriétaire de planning : le

moteur de développement. VibeFlow tient l'altitude au-dessus (le lab) et la couche à côté

(mémoire, enforcement) — jamais la même. »*

Avant toute autre chose, croiser un fait et un jugement.

1. Le fait — lancer scripts/detect-gsd-engine.sh. Il ne dit PAS si le lab est dev : il dit

si un moteur de planning de développement est en place.

Les exits sont listés dans l'ordre où le script les évalue — le premier qui matche gagne, un lab pouvant satisfaire plusieurs situations à la fois. Le marqueur lu est une clé du frontmatter de STATE.md, jamais une chaîne trouvée ailleurs dans le fichier.

1. Le jugement — appliquer references/domain-detection.md (lire CLAUDE.md, les registres, le

vocabulaire dominant). Le métier n'est jamais déduit d'un package.json seul.

1. Brancher :

• Lab non-dev → Séquence A (socle universel) ci-dessous. Comportement historique intact.
• Lab dev → Séquence B : appliquer uniquement la couche lab (INDEX.md, typage des

compartiments, pont mémoire, surface de la dette) et rediriger toute demande portant sur un projet vers son verbe, selon la table de references/gsd-handoff.md. Ne pas générer la charte, la trajectoire, les exigences, l'état ni les étapes d'un projet de code.

Sur un lab dev à compartiments : le lab reçoit INDEX.md + STATE.md de steering (à nous) ; chaque compartiment dev reçoit son .planning/ écrit par le moteur de dev, depuis ce compartiment. Les deux couches ne se croisent sur aucun fichier.

Charger references/gsd-handoff.md dès que l'exit vaut 0 ou 2, ou que le jugement conclut « dev » : la table de redirection intention → verbe y vit, et ne se duplique pas ici.

Séquence A — Socle universel, lab non-dev (.planning/ absent)

1. Lire le métier du lab AVANT de scaffolder. Lire CLAUDE.md, le docs/ existant, les

registres .claude/memory/, et déduire : quel métier ? quelle granularité de travail ? Ne jamais présumer « dev ». Appliquer les heuristiques de references/domain-detection.md (jugement, pas détection figée). Si la logique métier n'est pas claire → une question courte.

1. Choisir le profil de rigueur (references/PROFILES.md) selon le métier détecté. Le

proposer à l'utilisateur (pré-coché), ne pas l'imposer. Léger par défaut pour les métiers créatifs/ponctuels ; standard pour contenu/vente/ops ; complet pour dev/projets critiques.

1. Instancier le tronc en l'ADAPTANT depuis references/templates/ :

• Remplir PROJECT.md avec la vraie valeur métier du lab (pas un gabarit dev).
• Créer STATE.md (clé de voûte) + ROADMAP.md + config.json (profil choisi).
• Profil ≥ standard : ajouter REQUIREMENTS.md, MILESTONES.md, l'arbo phases/.
• Extension de domaine : créer le sous-dossier propre au métier — codebase/ (dev),

editorial/ (contenu), pipeline/ (vente), dossiers/ (montage de dossier), etc. Le nom et le contenu suivent le métier, jamais l'inverse. Aucune extension imposée.

3bis. Si le lab est à compartiments (plusieurs projets/clients/process — ex. projects/*) : poser le .planning/ du lab en mode steering + `INDEX.md` (pas de ROADMAP global) ; puis pour chaque compartiment, appliquer le seuil d'autonomie et le typer deliverable/continuous avant de lui poser (ou non) son propre socle. Détail : references/compartments.md. Gabarits : templates/INDEX.template.md (lab) + templates/BOARD.template.md (compartiment continuous).

1. Établir le pont mémoire (references/bridge-memory.md) : .planning/ = couche avant/présent

(vivante) ; les registres .claude/memory/ = couche capitalisation (figée). Définir où les décisions clés de PROJECT.md remontent en DECISIONS et où STATE.md alimente le JOURNAL — sans dupliquer.

1. Récap : montrer l'arbo posée, le profil, et la prochaine action en vocabulaire du lab.

Séquence A (suite) — Maintenance du socle universel (.planning/ déjà là)

• Vérifier la fraîcheur : scripts/check-planning-state.sh (advisory) signale un STATE.md

périmé ou un .planning/ absent — utilisable manuellement, au /vf-audit, ou en hook SessionStart opt-in (wiring dans references/domain-detection.md).

• Détecter la dette de planning (labs à compartiments) : scripts/detect-planning-debt.sh

(advisory) liste les compartiments actifs + sans plan + au-dessus du seuil d'autonomie. Alerte, jamais bloquant. À lancer au /vf-audit ou via vibeflow-validator.

• Mettre à jour `STATE.md` en priorité (position courante, % d'avancement, focus, todos).
• À la clôture d'une étape : écrire son SUMMARY.md ; à l'ouverture : son PLAN.md.
• À la livraison d'un jalon : archiver dans MILESTONES.md + milestones/.
• Promouvoir les décisions structurantes de PROJECT.md vers la mémoire (pont).

Automatisation livrée (v2.2.0, ADR-050 ; durcie v2.3.0) — la maintenance n'est plus seulement une

discipline manuelle, elle est machine-enforced par 4 hooks :

- SessionStart : planning-context.sh injecte un digest index-first (INDEX du lab, ou STATE

borné en mono) + detect-planning-debt.sh surface le 8e signal de dette + planning-session-snapshot.sh

photographie la baseline de session (epoch, HEAD de départ, porcelain hashé).

- UserPromptSubmit : planning-task-context.sh injecte le STATE.md **du compartiment que vise la

tâche** (jamais tous — structuration du contexte).

- Stop : guard-planning-updated.sh signale (ou bloque) si des livrables ont changé **pendant la

session sans mise à jour du planning. Sévérité proportionnée au profil de rigueur du lab**

(gouvernance proportionnée, audit 2026-07-25) : le hook lit la clé "profile" de

.planning/config.json (source canonique, posée à l'init — cf. references/PROFILES.md) —

profil léger (lab solo/exploratoire) → `warn` par défaut (advisory, n'arrête jamais) ;

profils standard/complet → `block` par défaut ; config absente ou profil illisible →

block (fallback sûr). La variable VF_PLANNING_STOP=block|warn|off reste l'override et

prime toujours sur le profil. L'attribution se fait contre la baseline (commits de la session via

git log --since, dirt nouveau ou au hash modifié) — le dirt préexistant n'est JAMAIS attribué, un

STATE.md mis à jour puis committé (flow GSD/dev-orchestrator) est bien reconnu, et le signal

mtime couvre un .planning/ gitignoré. Au pire un seul blocage par session (marqueur .blocked

+ anti-boucle stop_hook_active), échappatoire .session-noop, baseline absente/périmée → fail-open.

Séquence B — Couche lab au-dessus du moteur de dev (lab dev)

1. Ne générer aucun artefact de projet. Le tronc d'un projet de code (charte, trajectoire,

exigences, état, étapes) appartient au moteur de développement — jamais à ce skill.

1. Poser ou rafraîchir l'altitude lab si le lab a plusieurs compartiments : INDEX.md, typage

deliverable/continuous, seuil d'autonomie (references/compartments.md).

1. Surface de la dette : scripts/detect-planning-debt.sh (advisory).
2. Pont mémoire : promouvoir les décisions structurantes vers .claude/memory/

(references/bridge-memory.md) — référencer, jamais recopier.

1. Rediriger ce qui concerne un projet vers son verbe (table de references/gsd-handoff.md),

en vocabulaire VibeFlow, sans jamais nommer l'outillage sous-jacent.

Garde-fous (anti-biais)