claude-doc-genome

init-project

objectif

Amorcer le système de documentation d'un nouveau projet à partir d'un bundle portable en une seule commande. Après initialisation, le projet se maintient tout seul en utilisant la norme déployée (arbre de décision doc-organization.md §8.3 + standards portables méta). init s'exécute une fois par projet ; update peut être relancé ultérieurement sur ce projet pour récupérer les fichiers portables plus récents depuis le bundle (fusion sécurisée à 3 voies — n'écrase jamais les modifications locales non promues). check/promote maintiennent le bundle lui-même et ne s'exécutent que sur ce dépôt maître.

dépendances

• ./portable/rules/ — 7 règles portables (chargement permanent + scope-chemin)
• ./portable/agent-guide/ — five-why.md, markdown.md, mermaid.md, orchestration-policy.md, worktree.md (déployer vers docs/agent-guide/general/)
• ./portable/skills/ — skill-designer/, skill-writer/, document-writer/ (arbres complets)
• ./portable/agents/ — skill-writer-auditor.md
• ./templates/ — CLAUDE.md.tpl, agent-guide/index.md.tpl, docs/index.md.tpl
• ./VERSION — version du bundle, incrémentée à chaque promote
• scripts/update.mjs (racine du dépôt) — moteur du mode update (fusion bundle→live à 3 voies) ; scripts/sync-version.mjs — synchronisation unique de version

modes

appel	exécution sur	action
/init-project	nouveau projet	déployer le bundle (workflow ci-dessous)
/init-project check	dépôt maître	comparer sha256 bundle ↔ live selon §map → signaler les divergences
/init-project promote	dépôt maître	copier live → bundle pour chaque fichier mappé, incrémenter VERSION
/init-project update	projet initialisé	récupérer les fichiers portables plus récents bundle → live, fusion sécurisée à 3 voies (manifest ↔ live ↔ bundle) ; ignorer les conflits (workflow ci-dessous)

workflow (init — nouveau projet)

1. Analyser le projet : détecter la pile + modules optionnels selon la colonne signal de la ## matrice des modules. Sortie : ensemble de modules proposés + valeurs de slots découvertes.
2. Interview : confirmer l'ensemble de modules proposés ; demander les slots non scrutables (ports de dev utilisés, propriété du scope, langue de la doc). Slot sans réponse → laisser un marqueur TODO, jamais inventer une valeur ; module incertain → l'ignorer.
3. Copier portable/ à l'identique : portable/rules/* → .claude/rules/ ; portable/agent-guide/* → docs/agent-guide/general/ ; portable/skills/* → .claude/skills/ ; portable/agents/* → .claude/agents/.
4. Rendre les templates : remplir {{slots}} de l'interview dans CLAUDE.md, docs/agent-guide/index.md, docs/index.md ; slot manquant → conserver le marqueur TODO.
5. Générer les règles optionnelles : pour chaque module optionnel confirmé, écrire une règle adaptée au projet dans docs/agent-guide/general/ selon les standards d'écriture de règles, et ajouter sa ligne de déclenchement dans CLAUDE.md dans la même étape — pas de modèle codé en dur.
6. Écrire le manifeste .claude/init-manifest.json : { version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] } (provenance ; files[] lu par update pour la détection de dérive à 3 voies — maintenir le sha256 précis ; templates[] enregistre le sha de chaque .tpl avec lequel un fichier rendu a été construit — path = chemin du template relatif à templates/ e.g. CLAUDE.md.tpl, utilisé par update pour AVERTIR lorsqu'un template a changé depuis le déploiement).
7. Vérifier : chaque fichier déployé est au bon niveau ; chaque fichier de règle/guide-agent porte un frontmatter scope: ; CLAUDE.md respecte le budget de tokens ; chaque fichier à la demande affectant le comportement a une ligne de déclenchement ou une entrée de routeur (accessibilité, fichier→déclencheur) ; chaque déclencheur MUST Read dans CLAUDE.md pointe vers un fichier déployé (accessibilité, déclencheur→fichier — aucun déclencheur mort) ; aucun {{slot}} non rendu ne subsiste sauf les marqueurs TODO intentionnels. Terminé = checklist validée + manifeste écrit.

carte bundle ↔ live (check / promote — dépôt maître ; update — projet initialisé)

chemin bundle	chemin live
portable/rules/*	.claude/rules/*
portable/agent-guide/*	docs/agent-guide/general/*
portable/skills/*	.claude/skills/*
portable/agents/*	.claude/agents/*

• check : sha256 chaque paire → lister les discordances. La direction de mise à jour par défaut est live → bundle (promote) ; d'abord corriger live, puis promote.
• promote : copier live → bundle pour chaque fichier mappé, puis augmenter la version via node scripts/sync-version.mjs set <x.y.z> (écrit le VERSION canonique + le reflète dans .claude-plugin/* et le badge du README).

workflow (update — projet initialisé)

Direction bundle → live (inverse de promote). Ne touche que l'ensemble portable à l'identique ; le phénotype rendu (CLAUDE.md, index.md, guides rédigés par le projet) est hors scope. Invoquer update.mjs par son chemin à l'intérieur du plugin installé (il localise lui-même le bundle depuis son propre emplacement) ; --project est la racine du projet initialisé et par défaut le répertoire courant.

1. Simulation : node <plugin>/scripts/update.mjs --project <project-root> → examiner le plan AJOUTER / METTRE À JOUR / CONFLIT et l'écart de version.
2. Résoudre d'abord chaque CONFLIT — un conflit = un fichier portable modifié localement depuis le déploiement. Le promouvoir en amont (pour que l'amélioration entre dans le bundle) ou le réécrire manuellement après examen. Ne jamais écraser à l'aveugle.
3. Appliquer : node <plugin>/scripts/update.mjs --apply --project <project-root> → écrit AJOUTER + METTRE À JOUR, ignore les conflits, rafraîchit la version du manifeste + files[].sha256.
4. Uniquement ajouts + modifications — update ne supprime jamais : un fichier retiré du bundle reste dans le projet, et un fichier supprimé localement est rajouté. Élaguer manuellement si nécessaire.
   • templates/* (CLAUDE.md, index.md — phénotype rendu) ne sont jamais écrasés : leurs slots contiennent des valeurs propres au projet. update émet seulement un AVERTISSEMENT lorsqu'un .tpl a changé depuis le déploiement (sha vs manifest.templates[]) ; re-rendre manuellement (diff .tpl vs live, réappliquer les changements structurels, conserver les valeurs de slot) ou réexécuter /init-project. L'AVERTISSEMENT persiste jusqu'à ce que la prochaine initialisation réenregistre le sha du template.
5. Code de sortie : 0 = à jour ou appliqué proprement ; 1 = des conflits subsistent ; 2 = erreur de configuration (pas de manifeste → le projet n'a pas été initialisé par ce plugin).

matrice des modules

module	inclut	déployer quand	signal d'analyse (exemples, non exhaustif)
core	portable/* (les 4 groupes) + 3 templates	toujours	—
runtime	agent-guide/general/local-runtime.md + déclencheur CLAUDE.md (skill écrit selon analyse, étape 5)	le projet fait tourner un serveur de dev	scripts dev/start dans package.json, launchSettings.json, configuration vite/next/dotnet/django/cargo
e2e	agent-guide/general/<outil>.md (nommé d'après l'outil détecté) + déclencheur CLAUDE.md (étape 5)	le projet a des tests navigateur E2E	dépendance playwright/cypress/selenium, dossier e2e/, configuration E2E

• Les modules optionnels ne sont déployés que si l'analyse les confirme OU si l'utilisateur les confirme lors de l'interview — incertain → ignorer.
• Git : barrière de sécurité minimale (commiter uniquement sur demande, jamais pusher) intégrée dans CLAUDE.md.tpl ; la politique détaillée a scope: project — le projet écrit docs/agent-guide/general/git.md à la demande, en ajoutant sa ligne de déclenchement dans le même commit (accessibilité — jamais un déclencheur pointant vers un fichier manquant).
• Un module ignoré puis nécessaire ultérieurement → le projet écrit la règle lui-même selon la norme déployée. Un nouveau module entre dans le bundle uniquement via promote après qu'un projet réel a testé le motif en conditions réelles.

règles d'indépendance

• Le skill s'exécute une fois par projet ; les fichiers déployés ne référencent aucun fichier de ce dépôt maître ; les règles du projet ne nomment jamais ce skill.
• Autonome sauf la carte bundle↔live ci-dessus, qui s'exécute uniquement sur le dépôt maître pour check/promote.

exemples

✅ l'analyse trouve un package.json avec un script "dev" → proposer le module runtime → étape 5 écrit
   general/local-runtime.md + ajoute "serveur de dev auto-exécuté → MUST Read ..." dans CLAUDE.md
❌ déployer le module runtime sans signal d'analyse ni confirmation lors de l'interview (module deviné)

✅ /init-project check → "MISMATCH: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
   → corriger live d'abord → /init-project promote
❌ modifier portable/* directement puis initialiser un nouveau projet (bundle diverge silencieusement du live)

fichiers de référence

• bundle : ./portable/**
• templates : ./templates/**
• version : ./VERSION