Factory Spec

Factory Spec - Phase MODEL

Tu es l'orchestrateur de la phase MODEL.

Workflow

1. Verifier Gate 1 (entree) :

   node tools/gate-check.js 1 --json
   

   • Si status === "FAIL" → STOP immediat (prerequis manquants, ne peut pas corriger).
   • Terminer avec : GATE_FAIL|1|<resume erreurs>|0

2. Lire le state :

   node tools/factory-state.js get
   # Retourne: { "evolutionMode": "greenfield|brownfield", "evolutionVersion": N, "requirementsFile": "...", ... }
   
   # Lister les ADR actifs (brownfield : exclut SUPERSEDED)
   node tools/list-active-adrs.js --summary
   
   # Extraire le delta de la version courante (brownfield uniquement)
   node tools/extract-version-delta.js -f brief -f scope
   

   Extraire : evolutionMode, evolutionVersion.

3. Deleguer aux agents (sequentiel strict, UN A LA FOIS) :

   3a. Agent PM (specs fonctionnelles) :

   # Instrumenter la delegation (les hooks ne fonctionnent pas dans les forks)
   node tools/instrumentation/collector.js agent '{"agent":"pm","source":"factory-spec"}'
   

   Task(
     subagent_type: "pm",
     prompt: "Genere les specs fonctionnelles du projet.
     Mode: <evolutionMode>. Version: <evolutionVersion>.
     Si mode=greenfield: CREATE docs/specs/system.md et docs/specs/domain.md.
     Si mode=brownfield: EDIT les specs existantes pour les mettre a jour.
     DELTA VERSION COURANTE: <output de extract-version-delta.js>
     Lis les fichiers BREAK: docs/brief.md, docs/scope.md, docs/acceptance.md.
     Lis les templates: templates/specs/system.md, templates/specs/domain.md.
     IMPORTANT: Respecte EXACTEMENT les headings des templates (##).
     IMPORTANT: NE PAS inventer de numeros de version pour les librairies.
     Ecrire uniquement le nom de la lib (ex: 'Tailwind CSS', pas 'Tailwind CSS 3+').",
     description: "MODEL - PM specs"
   )
   

   3b. Verification web des dependances et generation de stack-reference.md (fait par le fork, AVANT l'architect) :

   OBLIGATOIRE : Verifier les dependances de la stack sur internet AVANT de deleguer a l'architect. Les LLMs ont souvent des connaissances obsoletes sur les versions recentes des libs. L'architect n'a pas acces a WebSearch/WebFetch — c'est le fork qui fournit les infos verifiees.

   Etape 1 : Identifier la stack dans le brief/scope

   Lire docs/brief.md et docs/scope.md pour extraire la liste des dependances prevues (framework, CSS lib, bundler, test runner, linter, chart lib, etc.). Constituer une liste : [ "react", "tailwindcss", "vite", "vitest", ... ].

   Etape 2 : Verifier les versions via npm registry (source canonique)

   Pour chaque dependance identifiee :

   npm view <package> version
   # Retourne la derniere version stable (ex: "19.1.0")
   

   Si le nom npm n'est pas evident (ex: Tailwind CSS → tailwindcss), utiliser :

   npm search <lib> --json | head -5
   

   C'est la source la plus fiable pour les numeros de version. Ne JAMAIS utiliser une version extraite d'une page web si elle contredit npm registry.

   Compteur : noter le nombre de deps verifiees via npm (verified_count).

   Etape 3 : Rechercher les configs et breaking changes via web (complementaire)

   Pour chaque dependance a risque de breaking changes (identifiee dans le brief/scope) :

   a. Trouver la doc officielle :

   • WebSearch : "<lib> getting started" ou "<lib> installation guide"
   • Privilegier les domaines officiels (npmjs.com, github.com/, docs officiels)

   b. Extraire la configuration :

   • WebFetch sur la page d'installation officielle
   • Extraire : packages a installer, fichiers de config requis, snippets de reference
   • Copier le snippet EXACT depuis la doc (pas de memoire LLM)

   c. Identifier les breaking changes :

   • WebSearch : "<lib> migration guide" ou "<lib> upgrade from v<N-1>"
   • Documenter : ancien pattern (a eviter) vs nouveau pattern (a utiliser)

   Si WebSearch/WebFetch echoue (rate limit, erreur reseau) : logger un warning et continuer. La verification configs/breaking changes est best-effort. Les versions npm sont obligatoires.

   Etape 4 : Seuil de fiabilite

   Calculer : ratio = verified_count / total_deps.

   • Si ratio >= 0.5 (50%+) → continuer normalement.
   • Si ratio < 0.5 → logger un warning :

     node tools/factory-log.js "MODEL" "stack-warning" "Seuil de fiabilite non atteint: X/Y deps verifiees via npm. Risque de versions incorrectes."
     

     Continuer quand meme (ne pas bloquer), mais le warning sera visible dans les logs.

   Etape 5 : Generer docs/specs/stack-reference.md

   Lire le template templates/specs/stack-reference.md. Creer le fichier docs/specs/stack-reference.md en remplissant :

   • Dependencies runtime : tableau avec package, version exacte (depuis npm), commande install, URL source
   • Dependencies dev : idem pour les deps de dev
   • Configurations de reference : pour chaque lib necessitant un fichier de config, inclure le snippet EXACT copie depuis la doc officielle (pas de memoire LLM)
   • Compatibilite : notes inter-dependances (ex: "Tailwind v4 necessite @tailwindcss/vite")
   • Breaking changes connus : tableau ancien vs nouveau pour chaque lib avec breaking change

   Ce fichier est la source de verite pour toutes les etapes suivantes. L'architect et le developer doivent s'y referer, pas inventer de versions.

   Etape 6 : Logger

   node tools/factory-log.js "MODEL" "stack-verified" "Verification stack: X/Y deps verifiees via npm, Z configs web → docs/specs/stack-reference.md"
   

   3c. Agent Architect (specs techniques + ADR, avec stack verifiee) :

   # Extraire le delta depuis les specs PM (disponibles apres 3a)
   node tools/extract-version-delta.js -f system -f domain
   
   # Instrumenter la delegation
   node tools/instrumentation/collector.js agent '{"agent":"architect","source":"factory-spec"}'
   

   Task(
     subagent_type: "architect",
     prompt: "Genere les specs techniques et ADR.
     Mode: <evolutionMode>. Version: <evolutionVersion>.
     Si mode=greenfield: CREATE docs/specs/api.md, ADR-0001-stack.md, project-config.json.
     Si mode=brownfield: EDIT api.md + CREATE nouveaux ADR + marquer anciens SUPERSEDED.
     DELTA VERSION COURANTE: <output de extract-version-delta.js>
     Lis les fichiers BREAK: docs/brief.md, docs/scope.md, docs/acceptance.md.
     Lis les specs PM: docs/specs/system.md, docs/specs/domain.md.
     Lis le fichier stack de reference: docs/specs/stack-reference.md.
     Lis les templates: templates/specs/api.md, templates/adr/ADR-template.md, templates/specs/project-config.json.
     IMPORTANT: Respecte EXACTEMENT les headings des templates (##).
   
     STACK REFERENCE (source de verite - UTILISE CES VERSIONS ET CONFIGS, PAS TA MEMOIRE) :
     Lis docs/specs/stack-reference.md pour toutes les versions, packages et configs.
   
     Pour chaque dependance dans l'ADR :
     - Utilise la version exacte et les packages indiques dans stack-reference.md
     - Inclus les snippets de configuration de reference dans une section '## Configuration de reference' de l'ADR
     - Si une lib a un setup specifique (ex: plugin Vite au lieu de PostCSS), documente-le
     - NE PAS inventer de config : utilise UNIQUEMENT les infos de stack-reference.md",
     description: "MODEL - Architect specs"
   )
   

   3d. Agent Rules-Memory (rules Claude Code) :

   # Extraire le delta depuis toutes les specs (disponibles apres 3a+3c)
   node tools/extract-version-delta.js -f system -f domain -f api
   
   # Instrumenter la delegation
   node tools/instrumentation/collector.js agent '{"agent":"rules-memory","source":"factory-spec"}'
   

   Task(
     subagent_type: "rules-memory",
     prompt: "Genere les rules Claude Code pour le projet.
     Mode: <evolutionMode>. Version: <evolutionVersion>.
     Si mode=greenfield: CREATE les rules dans .claude/rules/.
     Si mode=brownfield: mettre a jour les rules existantes, supprimer les obsoletes.
     ADR ACTIFS: <liste des paths retournes par list-active-adrs.js --summary>
     DELTA VERSION COURANTE: <output de extract-version-delta.js>
     IMPORTANT: NE PAS charger les ADR au statut SUPERSEDED.
     Lis les specs: docs/specs/system.md, docs/specs/domain.md, docs/specs/api.md.
     Lis le template: templates/rule.md.",
     description: "MODEL - Rules generation"
   )
   

4. Executer Gate 2 (sortie avec auto-remediation) :

   node tools/gate-check.js 2 --json
   

   Suivre le protocole standard de gate handling :

   Tentative 1 : Analyser le JSON retourne.

   • Si status === "PASS" → continuer a l'etape 5.
   • Si status === "FAIL" :
     • Lire errors[]. Pour chaque erreur fixable: true :
       • missing_section → identifier le fichier et le template de reference dans le message d'erreur (ref: templates/...). Relancer l'agent responsable avec prompt : "Corrige [fichier]. Section manquante : [section]. Lis le template [template] et respecte exactement les headings."
       • missing_file → identifier le fichier manquant :
         • stack-reference.md → re-executer l'etape 3b (verification web + generation du fichier). C'est le fork qui le fait, pas un agent.
         • system.md / domain.md → relancer l'agent PM (step 3a).
         • api.md → relancer l'agent architect (step 3c).
         • Autre → relancer l'agent responsable.
       • missing_pattern → identifier le pattern manquant :
         • .claude/rules/*.md → relancer l'agent rules-memory (step 3d).
         • docs/adr/ADR-* → relancer l'agent architect (step 3c).
       • config → relancer l'architect pour corriger project-config.json.
       • security → corriger les secrets/PII directement.
     • Pour chaque erreur fixable: false → STOP, ne pas retenter.
     • Re-executer : node tools/gate-check.js 2 --json

   Tentative 2 : Relancer les agents fautifs complets (PM, architect ou rules-memory selon les erreurs restantes).

   • Re-executer : node tools/gate-check.js 2 --json

   Tentative 3 : Si toujours FAIL, retourner le rapport d'echec.

   • NE PAS continuer le pipeline.
   • Terminer avec : GATE_FAIL|2|<resume erreurs separees par ;>|3

5. Sync ADR (brownfield) :

   node tools/list-active-adrs.js --summary
   

6. Logger via :

   node tools/factory-log.js "MODEL" "completed" "Phase MODEL terminee"
   

7. Retourner un resume avec liste des fichiers generes (chemins complets).

Protocole d'echec

• Gate d'entree (Gate 1) : Si FAIL → STOP immediat + marqueur GATE_FAIL|1|...|0.
• Gate de sortie (Gate 2) : Auto-remediation 3x puis marqueur GATE_FAIL|2|...|3 si echec persistant.
• Jamais de STOP silencieux — toujours retourner un rapport structure.