Aller au contenu

ADR 0009 — Intégration Nick Tune dans sdeg-kernel v3

Contexte

sdeg-kernel v2 est un kit opinionated sur la décomposition métier (BE → FE → US), 4 portes canoniques (G1–G4), machine d'états en sdlc/schema.js, 16 prompts Copilot principalement orientés Vision/Business. L'observation du pilote kanban-vibe confirme l'analyse : le kit est fort sur l'amont (vision, découpe, plan-dev) mais mince sur l'aval proche du code — la bascule US → merge repose sur tdd-dev.prompt.md et convention TDD, sans discipline intra-tâche, sans harness qualité par tâche, sans rétrospective structurée pour alimenter la boucle Re-G1.

Nick Tune a publié (jan–mars 2026) trois articles et deux repos qui adressent précisément cet aval :

  • NTCoding/deterministic-agent-workflows — moteur TypeScript + SQLite event-store + hook Claude Code PreToolUse qui bloque les tool calls violant l'état courant.
  • NTCoding/claude-skillz — ~40 skills / commands / subagents packagés en plugin Claude Code, dont create-tasks, lightweight-task-workflow, task-check, architect-refine-critique/arc-prd, reflection-process.

Les deux approches partagent trois invariants qui rendent la greffe compatible :

  1. L'agent IA ne transite jamais d'état lui-même.
  2. La définition des états est en code, pas dans un prompt.
  3. La décision humaine est un événement tracé avec contexte git.

La v3 consolide sdeg-kernel en important sélectivement les patterns de Nick sans casser nos invariants (sdlc-registry.json single-writer, portes G1–G4 canoniques, pre-commit comme filet déterministe principal).

Options envisagées

Sur l'emplacement du PRD (artefact manquant entre BE et FE)

  • A. PRD = artefact COLD du BE post-G2 — nouveaux statuts DEV_PLAN_ARRETE → PRD_EN_COURS → PRD_ARRETE formant une mini-porte G2.5. Trace décisionnelle explicite mais alourdit le cycle BE de deux statuts pour une porte sans signature sponsor ni freeze OKRs.
  • B. PRD = artefact LIVING de la FE pré-G3 — nouveau fe.PRD_EN_COURS entre NOT_STARTED et FAB_PLAN_EN_COURS. Check G3 enrichi de prd.md. Moins invasif, le PRD reste mutable jusqu'à G3.
  • C. PRD = artefact optionnel sans statut — un fileExists soft, rien dans schema.js. Risque d'un PRD jamais rédigé.

Sur l'import du moteur Nick Tune

  1. Import en bloc du moteur TS + event-store SQLite — adopte la per-state tool-policy et le hook PreToolUse, mais casse le single-writer de sdlc-registry.json et impose Claude Code aux consumers (beaucoup sont Copilot-first).
  2. Pas d'import du moteur ; on copie seulement les patterns pertinents (shape {canTransitionTo, transitionGuard(GitInfo)}) sans remplacer schema.js.
  3. Import optionnel Claude Code — schema.js inchangé, hook PreToolUse fourni en opt-in pour les consumers qui tournent en Claude Code natif.

Sur la décomposition tâches + harness qualité

  • i. Import tel quel des skills create-tasks + lightweight-task-workflow + task-check en plugins Claude Code (EN).
  • ii. Adaptation Copilot — traduction FR et republication comme .prompt.md dans .github/prompts/.
  • iii. Dual-format — shipper les deux (Copilot FR + Claude Code EN) via scripts/bootstrap.js.

Sur la rétrospective post-cycle

  • α. Event-store SQLite à la Nick — ~/.workflow-events.db, table reflections. Nouvelle persistance parallèle au registry.
  • β. Git log comme event-log — les commits chore(sdlc): <ID> <FROM>→<TO> [<GATE>] sont déjà un event-log structuré. Un nouveau prompt sdeg-reflection les consomme pour produire bilan-mvp.md.

Décision

v3 = fusion sélective, pas fusion en bloc. Cinq décisions reliées :

D1 — PRD : option B (artefact LIVING de la FE pré-G3)

Ajout au type fe :

  • nouveau statut PRD_EN_COURS (meta IN_PROGRESS, pas de porte canonique) ;
  • transition NOT_STARTED → PRD_EN_COURS (pré-requis souples : parent BE en DEV_PLAN_ARRETE / FABRICATION_MVP / PERSEVERE, Feature candidate confirmée par G2) ;
  • transition PRD_EN_COURS → FAB_PLAN_EN_COURS (remplace l'actuelle transition directe depuis NOT_STARTED) ;
  • check G3 (FAB_PLAN_EN_COURS → FAB_PLAN_ARRETE) enrichi de fileExists: .product/.features/{id}/prd.md + frontmatterHas: [problem_statement, user_personas, success_criteria].

Pourquoi B : le PRD est un artefact de cadrage qui précède la découpe technique, pas une porte décisionnelle métier autonome. L'option A créait une micro-porte G2.5 qui dédouble G2 sans valeur transactionnelle (pas de signature sponsor, pas de freeze OKRs — juste un freeze spec, déjà couvert par G3). L'option C n'impose rien, donc n'impose rien.

D2 — Import ciblé, pas de moteur TS (option 2)

  • NON importés : moteur TypeScript, event-store SQLite, identity-verification 🔵 STATE: X, hook Stop auto-review (doublon de pre-commit).
  • OUI importés — comme patterns, pas comme code : shape {canTransitionTo, transitionGuard(GitInfo), allowedWorkflowOperations} pour guider nos futures extensions de schema.js ; forme du verdict PreconditionResult (déjà alignée avec evaluator.js).

sdlc/schema.js reste la seule source de vérité. .product/sdlc-registry.json reste single-writer. pre-commit reste le filet déterministe principal.

D3 — Décomposition tâches intra-US : dual-format (option iii)

Trois skills ajoutés, avec une micro-machine d'états orthogonale vivant à l'intérieur de us.DEV — aucun changement à schema.js, aucun nouveau statut :

  • create-tasks — Example Mapping + SPIDR + INVEST + Given/When/Then sur une US pour produire .claude/tasks.md projet.
  • lightweight-task-workflow — micro-SM CHECK_STATUS → WORKING → VERIFY → COMPLETE → AWAITING_COMMIT → MARK_TASK_COMPLETE.
  • task-check — agent verdict PASS / FAIL / NEED_INFO sur CONTEXT / COMPLETENESS / BUGS / QUALITY / ISSUES, pré-requis à la transition interne VERIFY → COMPLETE.

Packaging dual : .github/prompts/*.prompt.md (FR, Copilot) et .claude/plugins/... (EN, Claude Code natif). scripts/bootstrap.js déploie les deux formats chez le consumer ; le choix d'usage dépend de l'environnement de l'équipe (Copilot Chat vs Claude Code).

D4 — PRD : nouveau skill prd-architect (traduit)

Nouveau prompt .github/prompts/prd-architect.prompt.md inspiré de claude-skillz/architect-refine-critique/arc-prd : chaîne architect → refiner → critique produisant prd.md à partir du plan-dev.md du BE parent + des éléments Feature pré-cadrés par G2. Traduction FR, lentilles adaptées (separation-of-concerns et tactical-ddd conservées, reformulées dans le vocabulaire sdeg). Déclenché en Copilot par #prd-architect, en Claude Code par slash-command /prd si le plugin est activé.

D5 — Rétrospective Re-G1 : option β (git log comme event-log)

Nouveau prompt .github/prompts/sdeg-reflection.prompt.md qui prend en entrée git log --grep='chore(sdlc)' filtré sur un BE-<id> + les frontmatters de decision.md / bilan-mvp.md / release-note.md, et produit un bilan structuré alimentant bilan-mvp.md (déjà checké par la transition FABRICATION_MVP → REVUE_MVP).

Catégories adaptées de reflection-process :

  • state-efficiency — durées inter-portes, temps passé par statut ;
  • review-rework — boucles G2↔G1, G3↔G2 ;
  • quality-gates — verdicts NEEDS-REVIEW fréquents, préconditions souvent en échec ;
  • tooling — frictions Copilot / hooks observées ;
  • workflow-design — décisions schema.js remises en cause par le cycle.

Pas d'event-store SQLite. Git log structuré suffit — c'est déjà notre event-log.

Conséquences

Positives :

  • Aval comblé : sdeg devient aussi fort sur US → merge que sur Vision → BE. La promesse « cohérence bout-en-bout » du kit tient.
  • PRD explicite : fin de la zone floue entre G2 et G3 où le « quoi » de la Feature était implicite dans spec.md.
  • Harness qualité tâche : task-check capture les régressions avant G4 ; réduit le coût des aller-retours en revue.
  • Boucle Re-G1 outillée : la rétrospective était exigée par schema.js sans outil ; elle en a un.
  • Invariants préservés : single-writer sdlc-registry.json, portes G1–G4 canoniques, split IA/déterministe. Zéro concession.
  • Cohérence FR : tout ce qui est public consumer reste francophone.

Négatives :

  • Surface d'entretien doublée sur les 3 skills task-level (FR Copilot + EN Claude Code). Mitigation : seuls ces 3 sont dupliqués ; les 16 existants et les nouveaux prd-architect + sdeg-reflection restent mono-format Copilot.
  • Breaking change schema.js : le check G3 devient plus exigeant (prd.md obligatoire). Les FEs existantes sautent par défaut PRD_EN_COURS — nécessite un support legacy de la transition NOT_STARTED → FAB_PLAN_EN_COURS pendant la migration, ou un script de migration forcé. Tranché en non-objectif pour v3.0, à détailler en implémentation.
  • Dépendance pilote : les 3 skills task-level doivent être validés empiriquement sur kanban-vibe avant bootstrap généralisé chez les consumers.
  • Nouveau format de packaging : .claude/plugins/ est inexistant en v2. Adaptation scripts/bootstrap.js + meta/ + documentation requise.

Neutres :

  • Vocabulaire Nick Tune : GWT, SPIDR, Example Mapping entrent dans le glossaire sdeg sans y être natifs. Acceptable, ces termes sont reconnus dans la communauté agile/DDD.
  • Pas de preview Claude Code hook PreToolUse en v3 : reporté à v3.x si demande consumer ; la valeur marginale est faible tant que pre-commit tient.

Règle dérivée

Pour tout import futur depuis un écosystème voisin (Nick Tune, BMAD, Anthropic skills library, etc.) :

  1. Vérifier la compatibilité avec les trois invariants sdeg : agent ne transite pas, état en code, décision = commit tracé.
  2. Ne jamais importer un moteur qui dupliquerait sdlc/schema.js ou sdlc-registry.json.
  3. Importer comme pattern (shape, algorithme) plutôt que comme code, quand la logique est petite.
  4. Importer comme prompt traduit FR quand la logique tient dans un document narratif.
  5. Importer comme plugin en dual-format uniquement si l'équivalence Copilot est trop coûteuse et la demande consumer existe.

Non-objectifs de cette vague

  • Hook PreToolUse Claude Code — reporté : valeur incertaine tant que pre-commit tient ; reprise envisageable en v3.x si un consumer demande un enforcement plus strict.
  • Event-store SQLite — définitivement hors périmètre (clash avec single-writer).
  • Identity-verification 🔵 STATE: X — trop intrusive pour un public Copilot-first.
  • Migration automatique des FEs en cours — première livraison v3 : support legacy de NOT_STARTED → FAB_PLAN_EN_COURS en transition dépréciée, à supprimer dans une v3.x ultérieure.
  • Traduction FR des 40 skills claude-skillz — seuls les 3 task-level et arc-prd sont ciblés en v3. Le reste est signalé pour import à la demande si un besoin consumer émerge.

Références