ainova-systems/intelligence-dev-packs

Initialiser le Substrat de Documentation Orientée Spécifications

Mettre en place la base de connaissances partagée du dépôt – la couche que les humains et les agents lisent – afin que le reste du pack de spécifications (spec-create, spec-execute) ait un endroit où écrire. Opération sûre et additive : rien n'est supprimé, les brouillons sont considérés comme inférés jusqu'à confirmation, et le propriétaire approuve avant que quoi que ce soit ne devienne autoritaire.

Résoudre la structure cible (apprendre, puis profiler, puis défaut) – ne jamais imposer

1. Apprendre d'abord du projet. Si le dépôt a déjà une structure de documentation (docs/, Documentation/, une règle de docs, des docs de fonctionnalités sœurs), l'adopter – chercher d'abord, lire deux docs sœurs, imiter sans inventer. Une structure existante mature l'emporte sur la valeur par défaut ; ne pas restructurer ce qui fonctionne déjà.
2. Profiler pour fixer les chemins quand ils sont ambigus : specs_dir, features_dir, rules_dir, decisions_dir, spec_grouping.
3. Défaut greenfield = l'arbre de documentation orientée IA (voir references/docs-tree.md) : docs/ avec model.md, glossary.md, rules/R-NNN-*.md, features/<feature>.md, specs/NNN-<feature>/{requirements,plan,tasks}.md, decisions/NNNN-*.md, architecture/, guides/, _inbox/.

Le modèle en couches (ce que ce skill possède)

Classé par l'intensité avec laquelle chaque couche contraint un agent : un agent suit une vérification exécutable de façon plus fiable qu'un texte en prose.

• Couche A – contraintes exécutables (configs lint, boundary, contract-test, tests/) : la plus forte. Hors périmètre ici – à configurer séparément.
• Couche B – règles lisibles par machine & connaissances d'architecture (règles-en-tant-que-contrats rules/R-NNN, graphe des dépendances, journal des décisions). spec-init crée ces docs ; le routeur d'entrée de l'agent (AGENTS.md) reste propriété du moteur de synchronisation – ce skill s'assure seulement qu'il pointe vers l'arbre de documentation, sans jamais l'écraser.
• Couche C – base de connaissances partagée (modèle, glossaire, docs de fonctionnalités, spécifications, architecture, guides). spec-init crée la structure et l'amorce.

Étapes

1. Inventorier la documentation existante : chaque *.md, export wiki, diagramme, note éparse. Classer chaque élément en modèle / glossaire / comportement-fonctionnalité / flux / décision / architecture / guide / non classé.
2. Mettre en place l'arbre résolu – créer seulement ce qui manque (dossiers + un index docs/README.md). Ne jamais écraser un document existant.
3. Migrer en toute sécurité – mettre d'abord en quarantaine. Déplacer tout le contenu préexistant, non classé ou hérité dans _inbox/ (la quarantaine) afin que seule la nouvelle structure soit lue comme autoritaire, puis reclasser un élément à la fois avec révision du propriétaire : notes « comment X fonctionne » -> features/, diagrammes de flux -> architecture/diagrams/, décisions -> decisions/. Rien n'est supprimé ; le reclassement se fait un par un, jamais en masse automatique.
4. Rédiger les documents de base à partir du code, marqués confirmed / inferred : le modèle du domaine (model.md) et le glossaire (glossary.md) à partir des types et des noms de champs ; les lignes de base des comportements de fonctionnalités (features/) à partir du comportement réel du code aujourd'hui + les critères d'acceptation EARS ; le graphe des dépendances à partir des imports réels ; les règles métier numérotées candidates (rules/R-NNN) que le code applique déjà.
5. Appliquer le principe de nommage. Tout ce qui se trouve sous la racine de la documentation est en minuscules kebab-case ; les séries ordonnées utilisent des préfixes à zéros (NNNN- ADR, NNN- specs) ; un concept, un nom, pas de synonymes. Les seuls fichiers en majuscules sont AGENTS.md et README.md à la racine (les standards externes exigent ces noms).
6. Validation par le propriétaire. Présenter l'arbre créé, le contenu de _inbox/ en attente de reclassement, et les documents rédigés. Rien n'est autoritaire tant que le propriétaire n'a pas confirmé chaque document ; tout reste inferred jusqu'à ce moment.

Vérifier

• L'arbre résolu existe ; l'index le liste ; chaque fichier préexistant est soit reclassé, soit dans _inbox/ (aucun perdu) ; chaque document rédigé est marqué confirmé/inféré ; AGENTS.md n'a pas été écrasé.

Périmètre / transition

• Création d'une spécification de changement dans le dossier specs/ créé – spec-create.
• Contraintes exécutables de couche A (lint, boundary, contract tests) – hors périmètre ; configuration séparée.
• Maintenir la documentation synchronisée avec le code par la suite – spec-audit-docs.

CRITIQUE

• Ne jamais supprimer ou écraser de la documentation existante – mettre en quarantaine dans _inbox/, reclasser un par un avec révision du propriétaire.
• Ne jamais imposer l'arbre par défaut sur une structure de projet fonctionnelle – apprendre et adopter d'abord.
• Mention honnête à inclure dans la sortie : cela ne fige que ce qui est déjà structuré dans le code. Les règles métier qui résident dans la configuration, les lignes de base de données ou les extensions enregistrées à l'exécution sont invisibles pour la rédaction statique – les signaler pour des tests fonctionnels ou un déplacement progressif dans le code ; ne jamais inventer une règle que le code ne montre pas.