Aller au contenu

Outillage du développement assisté par IA

Organisation du dépôt

.agents/
├── AGENTS.md
├── context/
│   ├── project-map.md
│   └── generated-catalog.md
├── plans/
│   ├── TEMPLATE.md
│   ├── INDEX.md
│   ├── active/
│   └── archive/YYYY/MM/
├── sdds/
│   ├── TEMPLATE.md
│   ├── INDEX.md
│   ├── active/
│   └── archive/YYYY/MM/
├── scripts/
│   ├── refresh-context.mjs
│   ├── sdd-workflow.mjs
│   └── plan-workflow.mjs
├── skills/
│   ├── medusa-project-context/
│   ├── medusa-sdd-discovery/
│   ├── medusa-change-plan/
│   └── medusa-implement-plan/
└── tests/

Les skills sont placés à la racine dans .agents/skills, emplacement de dépôt découvert par Codex depuis tous les sous-répertoires. Chaque skill reste centré sur un seul rôle : découvrir le contexte, conduire une conception SDD, planifier, ou implémenter. Les règles invariantes restent dans AGENTS.md; les procédures détaillées sont chargées progressivement depuis les skills et leurs références.

Routage de contexte par domaine

Le skill medusa-project-context applique une divulgation progressive en trois niveaux : règles globales et carte du projet, manifeste de domaines, puis packs et sources ciblés. Les fichiers sont stockés sous :

.agents/skills/medusa-project-context/references/domains/
├── manifest.json
├── index.md
├── access-administration.md
├── characters-appearance.md
├── banking.md
├── items-inventories.md
├── world-interactions.md
├── groups.md
├── skills.md
├── simulation-hud.md
└── platform-operations.md

manifest.json est versionné (schema_version: 1). Pour chaque domaine, il déclare identifiant, libellé, déclencheurs, pack, ressources propriétaires et associées, routeurs FastAPI, chemins connexes et documentation fonctionnelle/technique/test. Une ressource peut être associée à plusieurs domaines mais possède exactement un propriétaire principal. Un routeur peut être partagé, mais tous les routeurs actuels doivent être couverts.

L’algorithme de sélection est le suivant :

  1. déterminer le résultat utilisateur ou opérationnel demandé ;
  2. choisir le domaine qui en est propriétaire comme domaine principal ;
  3. ajouter un domaine secondaire uniquement pour une frontière réellement traversée ;
  4. limiter normalement la sélection à un principal et deux secondaires ;
  5. lire uniquement les packs retenus, puis vérifier les contrats dans le catalogue et le code ;
  6. inscrire la sélection et les handoffs dans le plan ou rapport de découverte.

Le validateur utilise uniquement les modules standard Node.js :

node .agents/scripts/validate-domain-context.mjs
node .agents/scripts/validate-domain-context.mjs --root <fixture-ou-depot>

Il échoue si le schéma, un identifiant, un pack/rubrique, un chemin, une ressource propriétaire ou la couverture des routeurs est incohérent. Les tests construisent des dépôts temporaires minimaux pour vérifier les erreurs sans modifier le projet.

La taxonomie actuelle contient neuf domaines. banking possède medusa-bank et le routeur bank.py; skills possède medusa-skills et le routeur skills.py. Les liens avec inventaires, groupes, interactions, buffs, personnages et administration sont exprimés comme handoffs plutôt que par une ownership primaire dupliquée.

Un pack reste une référence, pas un skill autonome. Sa promotion nécessite un workflow spécialisé répété, un script/asset déterministe utile, une capacité explicitement invocable ou des incidents démontrant que le routeur ne suffit plus. Cette promotion suit un nouveau plan approuvé et ne duplique jamais les règles globales ni les responsabilités des trois skills de cycle.

Catalogue des contrats

refresh-context.mjs parcourt le code pour générer un index déterministe :

  • ressources medusa-* ;
  • commandes, événements réseau reçus, callbacks NUI et exports fournis ;
  • routes déclarées par les routeurs FastAPI ;
  • permissions ADMIN_* et GROUP_* avec leurs fichiers de référence.
node .agents/scripts/refresh-context.mjs
node .agents/scripts/refresh-context.mjs --check
node .agents/scripts/refresh-context.mjs --stdout

Le catalogue accélère la découverte et détecte les interfaces oubliées dans un plan. Il ne remplace pas l’inspection du code : les appels dynamiques, contrats de données et effets métier doivent être lus dans les sources, schémas, migrations et tests concernés.

Cycle des SDD

sdd-workflow.mjs utilise uniquement la bibliothèque standard Node.js. Il gère les métadonnées, valide les 17 sections du template, refuse les placeholders lors de la revue, exige au moins un ID FR-*, NFR-* et AC-*, et bloque l’approbation tant qu’une case reste ouverte sous « Questions bloquantes ». Les transitions sont :

À la lecture, parseDocument() normalise uniquement les séquences Windows CRLF (\r\n) vers LF avant d’analyser le frontmatter et le corps. La chaîne source n’est pas réécrite par une validation ; les transitions qui enregistrent déjà le document continuent d’utiliser la sérialisation LF déterministe. Le modèle canonique et toutes les règles de validation restent inchangés.

stateDiagram-v2
  [*] --> draft
  draft --> in_discussion
  in_discussion --> in_review
  in_review --> in_discussion: révision
  in_review --> approved: validation humaine
  approved --> in_discussion: révision + incrément
  approved --> archived
  draft --> cancelled
  in_discussion --> cancelled
  in_review --> cancelled
  cancelled --> archived
node .agents/scripts/sdd-workflow.mjs new --title "Titre" --summary "Besoin et résultat"
node .agents/scripts/sdd-workflow.mjs discuss <sdd>
node .agents/scripts/sdd-workflow.mjs validate <sdd> --strict
node .agents/scripts/sdd-workflow.mjs review <sdd>
node .agents/scripts/sdd-workflow.mjs approve <sdd> --by "Nom" --evidence "Référence"
node .agents/scripts/sdd-workflow.mjs revise <sdd>
node .agents/scripts/sdd-workflow.mjs archive <sdd>

revise incrémente la révision et efface l’approbation. archive déplace un SDD approuvé ou annulé sous archive/YYYY/MM/ et régénère l’index. Un SDD annulé archivé ne peut pas sourcer un plan car il ne possède pas de métadonnées d’approbation.

Le skill garde son entrée concise et charge trois références seulement selon le besoin : playbook de discussion, lenses de cas limites et rubrique de qualité. Son invocation implicite est autorisée, mais sa description la limite aux demandes de conception réellement incertaines ou explicitement SDD.

Modèle canonique unique

.agents/sdds/TEMPLATE.md est la seule source de structure. Son frontmatter porte template_version; new lit cette valeur et la persiste dans chaque document. Le script extrait directement du Markdown canonique les titres ## et ### situés hors blocs de code : aucune seconde liste de rubriques n’est maintenue dans JavaScript.

Aux gates validate --strict, review et approve, le workflow exige :

  • la même template_version que le modèle courant ;
  • chaque titre canonique présent une seule fois et dans le même ordre ;
  • aucun titre principal ## étranger au modèle ;
  • les contrôles existants sur placeholders, exigences et critères.

Une sous-rubrique ### supplémentaire est autorisée pour détailler un domaine, tant qu’elle ne duplique pas ou ne déplace pas une sous-rubrique canonique. Les SDD archivés ne sont jamais réécrits quand le modèle évolue : leur contenu et leur version restent les preuves approuvées. Un futur changement incompatible du modèle doit incrémenter template_version et suivre un nouveau plan.

Handoff SDD vers plan

La commande de création d’un plan accepte --sdd <chemin>. Le chemin doit rester dans le dépôt ; le document doit être approved ou archived, comporter une révision et une preuve de validation humaine. Le plan persiste source_sdd et source_sdd_revision. Chaque validation ultérieure du plan vérifie que cette révision n’a pas changé. Les plans directs et historiques sans ces champs restent valides.

Le plan doit mapper les exigences SDD aux étapes et tests. L’implémentation peut relire le SDD pour comprendre cette traçabilité, mais son périmètre et son autorisation proviennent uniquement du plan final approuvé.

Cycle des plans

stateDiagram-v2
  [*] --> draft
  draft --> in_review
  in_review --> approved: validation humaine
  approved --> in_review: révision
  approved --> implementing
  implementing --> in_review: écart matériel
  implementing --> completed
  completed --> archived
  draft --> cancelled
  in_review --> cancelled
  approved --> cancelled
  cancelled --> archived

Commandes principales :

node .agents/scripts/plan-workflow.mjs new --title "Titre" --summary "Résultat attendu"
node .agents/scripts/plan-workflow.mjs new --title "Titre" --summary "Résultat attendu" --sdd .agents/sdds/archive/<sdd>.md
node .agents/scripts/plan-workflow.mjs validate .agents/plans/active/<plan>.md
node .agents/scripts/plan-workflow.mjs review .agents/plans/active/<plan>.md
node .agents/scripts/plan-workflow.mjs approve <plan> --by "Nom" --evidence "Référence"
node .agents/scripts/plan-workflow.mjs implement <plan>
node .agents/scripts/plan-workflow.mjs complete <plan>
node .agents/scripts/plan-workflow.mjs archive <plan>

Le script contrôle les transitions, les sections obligatoires et les métadonnées d’approbation. Il refuse les identités de validation IA connues. Cette vérification technique complète la règle de processus : l’agent ne lance approve qu’après une approbation humaine explicite de la version finale.

Règles de maintenance

  • Une évolution de contrat régénère generated-catalog.md dans le même commit.
  • Le template de plan version 2 exige une évaluation distincte du catalogue, de la carte projet, des packs, du manifeste et des références de skills. Les plans historiques non versionnés restent validables sans cette rubrique.
  • La clôture compare cette évaluation au diff réel et met à jour toute connaissance réutilisable d'architecture, ownership, contrat, convention, workflow ou piège avant l'archive.
  • Une évolution de ressource, routeur, chemin ou pack exécute validate-domain-context.mjs et met à jour le manifeste dans le même commit.
  • Une modification approuvée du plan exécute revise, ce qui efface la validation.
  • Une modification d’un SDD revu/approuvé exécute sdd-workflow.mjs revise, incrémente sa révision et efface sa validation avant toute nouvelle planification.
  • Un plan ne passe à completed qu’après critères d’acceptation, documentation et vérifications.
  • Une archive n’est jamais utilisée comme plan actif ; un changement ultérieur crée un nouveau plan qui référence l’ancien si nécessaire.
  • INDEX.md est généré et ne se modifie pas manuellement.
  • Le workflow n’ajoute aucun service ni dépendance runtime au serveur : les scripts utilisent Node.js déjà présent dans l’environnement de développement.

Choix par rapport aux cadres génériques

Le dispositif reprend l’idée de boucles persistantes planification, revue, vérification et mémoire, mais l’adapte aux contraintes Medusa : séparation FastAPI/FiveM, permissions Discord partagées, deux interfaces admin, NUI AR/VR, documentation en trois volets et plans de recette identifiés. Aucun framework externe n’est requis pour exécuter le cycle.