vlv-code/init-meta-project

Initialisation et mise à niveau de l'environnement agent (Meta-projet Init & Audit)

Compétence autonome pour préparer n'importe quel dépôt aux workflows agent. Vérifie automatiquement la présence d'une structure meta-project existante, empêche l'écrasement des données accumulées et effectue une mise à niveau sécurisée vers la dernière norme ou amorce la structure à partir de zéro.

Repose sur le principe de rafraîchissement continu/opportuniste : lors de l'accès aux tranches de méta-connaissance, l'agent doit combler les lacunes et maintenir une vision cohérente du projet.

---

Quand invoquer la compétence

• L'utilisateur demande : "prépare le dépôt pour les agents", "initialise le meta-projet", "vérifie agents.md", "met à jour la structure agent", "rafraîchis la méta-connaissance".

---

Étapes d'exécution

Phase 0 : Vérification de l'environnement meta-projet existant

Avant toute écriture, vérifier la présence des composants meta-projet :

1. Vérifier la présence de AGENTS.md à la racine du dépôt.
2. Vérifier la présence des répertoires .agents/project_knowledge/ et .agents/skills/.

Scénario A : Structure déjà existante (Mode Audit et mise à niveau sécurisée)

Si AGENTS.md ou le dossier .agents/ est déjà présent dans le dépôt :

1. Interdiction d'écrasement destructeur :
   • Il est strictement interdit de supprimer ou d'écraser observations.md — toutes les observations accumulées doivent être conservées.
   • Il est interdit de supprimer les invariants personnalisés et les descriptions utilisateur de l'AGENTS.md existant.
2. Audit de conformité aux normes :
   • Vérifier la présence de la section "Principes et orientations architecturales (North Stars)" dans AGENTS.md. Si elle est absente, l'ajouter sans modifier l'objectif du service et les invariants.
   • Vérifier la présence du protocole de directive avec le lien "accès + rafraîchissement opportuniste" dans AGENTS.md. S'il est obsolète, mettre à jour la section.
   • Vérifier dans boundaries.md l'utilisation de motifs glob, la protection des répertoires de données (data/**, *.db), l'affectation des modules de formatage/rendu à la zone Jaune, et la présence de l'invariant Default Deny (zone Noire).
   • Vérifier la présence de la colonne Catégorie dans le tableau observations.md. Si le format hérité à 4 colonnes est utilisé, mettre à jour l'en-tête du tableau sans supprimer les lignes de données.
   • Vérifier l'actualité des fichiers SKILL.md dans .agents/skills/ (record-observation, sync-architecture, ground-meta-project).
3. Amélioration sécurisée :
   • Créer les tranches manquantes (par exemple, si weak_spots.md est absent).
   • Compléter le registre des compétences dans AGENTS.md avec de nouvelles compétences de pile spécialisées pour le dépôt.
4. Rapport de mise à niveau :
   • Informer l'utilisateur : "Meta-projet existant détecté. Audité et mis à niveau vers la dernière norme sans perte de données accumulées."

---

Scénario B : Configuration initiale (Mode génération squelette propre)

Si aucune structure n'existe, exécuter l'algorithme standard en deux passes :

Passe 1 : Scan express et génération du squelette (Rapide & Haut niveau)

1. Inspection express de la racine du dépôt : Lister le répertoire racine et identifier :

   • Manifests : package.json, pyproject.toml, go.mod, Cargo.toml, requirements.txt, pom.xml, docker-compose.yml.
   • Répertoires principaux : src/, app/, tests/, migrations/, scripts/, data/.
   • Règle Zéro Répertoire Non Mappé : Énumérer tous les répertoires source de premier niveau à la racine du dépôt. Filtrer strictement les chemins de .gitignore, les métadonnées VCS et les caches de construction/package/test standards (.git, node_modules, .venv, venv, dist, build, coverage, __pycache__, .pytest_cache, .idea, .vscode). Chaque répertoire source de premier niveau restant DOIT être explicitement comptabilisé et mappé vers une zone Verte, Jaune ou Rouge dans boundaries.md (les répertoires non mappés tombent par défaut sous Default Deny / Zone Rouge).
   • Nom du projet, objectif et concepts principaux à partir du README.md (si présent).
   • Clés et dépendances requises à partir de .env.example (si présent).

2. Identifier la pile technique et les principes fondamentaux :

   • Formuler une chaîne de pile concise (par exemple, Python 3.12, FastAPI, uv, pytest, Docker).
   • Mettre en évidence 2 à 3 orientations de base (par exemple, simplicité architecturale, typage strict, immuabilité des données, hors ligne en premier).

3. Créer la structure de répertoires : Créer les répertoires :

   • .agents/project_knowledge/
   • .agents/project_knowledge/archive/
   • .agents/skills/record-observation/
   • .agents/skills/sync-architecture/
   • .agents/skills/ground-meta-project/
   • scripts/

4. Déployer les compétences meta-projet groupées et les scripts d'exécution : Écrire les fichiers SKILL.md à partir des modèles intégrés ci-dessous dans :

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md Déployer les scripts d'automatisation de délimitation et de compactage sans dépendance dans le répertoire scripts/ du dépôt :
   • scripts/check_boundaries.py (Interface de ligne de commande Boundary Gate)
   • scripts/compact_memory.py (Bouclier de rotation de contexte et compacteur de mémoire)

5. Créer les premières ébauches de tranches de connaissances : Écrire les fichiers dans .agents/project_knowledge/ :

   • observations.md (tableau à 5 colonnes avec la première ligne d'initialisation ; utiliser des exemples de commandes multi-plateformes, par exemple : python -m pytest).
   • boundaries.md (modèle de zones avec motifs glob de base : formatage dans la zone Jaune, données dans la zone Rouge).
   • weak_spots.md (structure du registre des risques de base).
   • architecture.md (structure architecturale de base).
   • tasks.md (objectif actif, liste de contrôle d'équipe et registre de délégation).

Passe 2 : Plongée profonde dans le dépôt, Principes et compétences shell

1. Liste de contrôle d'inspection principale obligatoire : Interdiction de remplir weak_spots.md et architecture.md avec des modèles génériques sans lire le code source des modules clés ! L'agent doit exécuter des appels read_file pour les zones critiques suivantes :

   • Stockage & Base de données : Lire le module d'accès aux données principal (storage.py, repositories, models). Évaluer la taille monolithique (nombre de lignes), le couplage de schéma et la configuration de migration.
   • API externe & Clients de service : Lire les modules d'intégration (SDK de modèles d'IA, clients externes). Vérifier les tentatives, les délais d'attente, les solutions de repli et les singletons globaux.
   • Conteneurisation & Runtime : Lire Dockerfile, docker-compose.yml et les workflows CI (.github/workflows/). Vérifier les dépendances binaires système (FFmpeg, utilitaires), les permissions utilisateur (UID) et les montages de volumes de données.
   • Interface utilisateur & Entrée : Lire les modules clavier/routeur. Vérifier les contraintes de plateforme (par exemple, limite de 64 octets pour callback_data Telegram, états FSM, confirmation pour les actions destructrices).

2. Entretien d'étalonnage interactif (Protocole codifié à deux questions) : Les analyses automatisées identifient ce qui existe dans le code, mais ne peuvent pas détecter le contexte historique non écrit, les invariants métier ou les sensibilités de production. L'agent mène un entretien interactif structuré et bref (via l'outil ask_question ou une invite interactive directe) en posant exactement 2 questions ciblées :

   • Question 1 (North Stars et Invariants principaux) : "Quels sont les invariants architecturaux clés, les règles métier et les contraintes de production (North Stars) qui ne doivent jamais être violés lors de modifications ?"
   • Question 2 (Zone Rouge et chemins sensibles) : "Quels répertoires ou modules spécifiques (facturation, base de données, cryptographie, clés, legacy) sont critiques et doivent être bloqués en Zone Rouge ?"

   Traitement des réponses :

   • Les réponses de l'utilisateur à la Question 1 sont immédiatement intégrées dans la Section 1 de AGENTS.md ("Principes et orientations architecturales (North Stars)").
   • Les réponses de l'utilisateur à la Question 2 sont mappées dans la Zone Rouge de boundaries.md avant la vidage en une seule passe.
   • Si l'utilisateur ignore ou fournit une réponse vide, revenir par défaut aux orientations déduites de la liste de contrôle d'inspection principale.

3. Étalonner les concepts et principes du projet : Synthétiser les résultats de la liste de contrôle et les réponses de l'entretien en 2 à 3 orientations architecturales concises (North Stars) empêchant les actions contradictoires de l'agent.

4. Faire correspondre les compétences de pile à partir du registre shell de l'agent : Mapper la pile du dépôt aux compétences spécialisées disponibles dans l'environnement de l'agent (~/.gemini/config/skills/ et intégrées) :

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / migrations → postgresql-optimization, sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Bot Telegram / aiogram → telegram-bot-builder
   • Pipelines CI/CD → github-actions-creator
   • Code propre & revue → clean-code, code-reviewer

5. Étalonner les limites (boundaries.md) : Affiner les motifs glob dans .agents/project_knowledge/boundaries.md pour les répertoires réels du projet :

   • Default Deny / Couverture de chemin à 100 % (Zéro répertoire non mappé) : Garantir que chaque répertoire source de premier niveau non ignoré est explicitement affecté à une zone. Ajouter la règle Default Deny (zone Noire) : tout chemin non mappé est strictement en zone Rouge par défaut.
   • Différenciation des zones de test :
     • Créer de nouveaux tests pour de nouvelles fonctionnalités — zone Verte.
     • Suite de tests de régression existante (tests/**, *_test.*, *.spec.*) — strictement zone Jaune avec invariant interdisant l'affaiblissement des assertions (assert/expect).
     • Tests d'intégrité architecturale, de contrat API et de schéma de données (*integrity*, *contract*, *schema*, E2E) — strictement zone Rouge.
   • Modules de formatage/échappement et moteurs de template — strictement zone Jaune.
   • Fichiers et répertoires de base de données (data/**, *.db, *.sqlite*) — strictement zone Rouge.
   • Remplacer les chemins fictifs par les chemins de migration réels (alembic/versions/**, prisma/migrations/**, etc.).
   • Remplacer les chemins de route/contrôleur par les emplacements réels des sous-systèmes.

6. Analyse des risques et des points faibles (weak_spots.md) : Enregistrer la dette technique concrète identifiée lors de l'inspection principale (monolithes, singletons), les dépendances d'exécution externes (Redis, Postgres, courtiers de messages, utilitaires système comme FFmpeg), les contraintes de plateforme et les variables obligatoires de .env.example.

7. Remplir la tranche d'architecture (architecture.md) : Décrire la pile de haut niveau, les sous-systèmes, les tâches de fond/planificateurs et les flux de données en fonction des modules principaux inspectés.

   • Flux de données de bout en bout conditionnels : Générer le schéma "Flux de données de bout en bout (Traçage de flux avant vol)" chaque fois que des composants multi-niveaux, client-serveur, API ou UI sont détectés (mappage [Origine : UI/CLI/Événement] ➔ [Transport : Route API / Message] ➔ [Domaine / Stockage : Persistance] ➔ [Assembleur / Empaqueteur] ➔ [Consommateur : Client / Démon]). Pour les bibliothèques CLI ou stdlib pures à une seule couche sans communication externe ou couches de persistance, omettre cette section pour éviter le gonflement du contexte.

8. Protocole de vidage de synthèse en mémoire : L'agent n'écrit pas de brouillons intermédiaires sur le disque. Tous les invariants sont synthétisés dans la mémoire de travail pendant les passes 1 et 2, après quoi les fichiers sont écrits dans un ordre strict de bas en haut :

   • Étape A : Compétences pré-installées (.agents/skills/record-observation/, sync-architecture/ et ground-meta-project/) et scripts d'automatisation (scripts/check_boundaries.py, scripts/compact_memory.py si configuration de dépôt partagé).
   • Étape B : Tranches de connaissances (observations.md -> boundaries.md -> weak_spots.md -> architecture.md).
   • Étape C : Passeport racine (AGENTS.md) — strictement en dernier, en tant qu'agrégateur de références aux tranches et aux compétences de pile.

---

Finalisation et vérification

1. Vérifier les fichiers créés/mis à jour à l'aide de Get-ChildItem -Recurse .agents ou ls -R .agents.
2. Option de superposition invisible locale : Si l'initialisation a lieu dans un projet externe/client ou si un mode personnel sans commits Git est demandé :
   • Ajouter AGENTS.md et .agents/ à .git/info/exclude dans le dépôt cible.
   • Vérifier git status : les fichiers meta-projet ne doivent pas apparaître dans les fichiers non suivis.
3. Produire un résumé concis pour l'utilisateur :
   • Mode d'exécution (configuration initiale vs audit avec mise à niveau ; superposition partagée vs invisible).
   • Arborescence des fichiers créés/mis à jour.
   • Orientations du projet capturées (North Stars).
   • Liste des compétences de pile liées.

---

Modèles de référence intégrés

Modèle : record-observation/SKILL.md

---
name: record-observation
description: >-
  Utilisez cette compétence pour enregistrer un bug non documenté, un caprice d'environnement, un cas limite d'exécution
  ou une solution non évidente dans le tableau `.agents/project_knowledge/observations.md` du dépôt.
---

# Enregistrer une observation dans la base de connaissances du dépôt

1. Vérifier que `.agents/project_knowledge/observations.md` existe.
2. Vérifier les 20 dernières lignes pour les doublons.
3. Ajouter une entrée strictement comme une seule ligne de tableau Markdown :
   `| YYYY-MM-DD | [<catégorie>] | <Chemin_ou_composant> | <Résumé bref du problème/fait> | <Solution ou contournement> |`
   Catégories : `[build]`, `[runtime]`, `[deps]`, `[db]`, `[api]`, `[test]`, `[env]`, `[ci]`, `[boundaries]`, `[orchestration]`, `[decommission]`, `[incident]`, `[init]`, ou une balise de domaine explicite (par exemple `[theme]`).
4. Si le nombre de lignes > 30–40, archiver les enregistrements résolus dans `.agents/project_knowledge/archive/observations-YYYY.md`.

Modèle : sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  Utilisez cette compétence pour analyser les modules, les dépendances et les points d'entrée du dépôt,
  et générer ou mettre à jour `.agents/project_knowledge/architecture.md`.
---

# Synchroniser la tranche d'architecture du projet

1. Lire les manifests de dépendances et de construction.
2. Identifier les points d'entrée et les répertoires de premier niveau.
3. Identifier 3 à 5 sous-systèmes, leurs rôles et leurs flux de données.
4. Mettre à jour `.agents/project_knowledge/architecture.md`.
5. Afficher un bref résumé des modifications à l'utilisateur.

Modèle : ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  Compétence d'urgence de mise à la terre et de recalibrage : arrête les modifications incontrôlées, force un zoom arrière,
  relit AGENTS.md, le passeport de rôle actif, boundaries.md et la carte d'architecture, diagnostique la dérive de contexte
  et réinitialise l'âge.

...

[tronqué pour la traduction]