vibecode-pro-max-kit : specs, mémoire et workflow multi-agent pour le codage IA

Le codage IA dérape rarement à cause d’un échec spectaculaire du modèle. Le problème vient plus souvent de trois ruptures discrètes : le contexte est tronqué, les plans restent dans l’historique du chat, et les décisions ne laissent aucune trace. À chaque changement de besoin, il faut réexpliquer tout le projet.

vibecode-pro-max-kit s’attaque à ce problème de workflow. Il rapproche un AI coding agent d’une équipe d’ingénierie pilotée par les specs : écrire la spécification d’abord, planifier avant d’exécuter, et laisser des traces auditables à chaque étape. Ce n’est pas un framework de chat et cela ne remplace pas CI/CD. Son rôle est plus étroit : rendre les décisions de codage IA traçables.

---

Quel problème résout-il ?

Perte de contexte : les longues conversations sont coupées par la compaction, et les décisions de conception, les limites et les pistes de débogage disparaissent. Au changement suivant, il faut tout réexpliquer ou laisser l’IA deviner.

Plans et décisions sans trace : un export Markdown du chat n’est pas une documentation structurée. Pendant une revue, l’équipe ne voit pas pourquoi une solution a été retenue ni quelles options ont été écartées.

Handoff multi-agent coûteux : une tâche peut être divisée entre plusieurs agents, mais le passage de relais repose souvent sur du langage naturel approximatif. Qui possède quelle étape, quel format de sortie est attendu, et où se trouvent les critères d’acceptation : tout cela demande une supervision humaine.

Ensemble, ces problèmes donnent l’impression de recommencer à zéro à chaque cycle de codage IA. vibecode-pro-max-kit les place dans un même harness : spec au début, plan au milieu, checkpoints pendant l’execution, et mémoire autour du processus.

---

Installation et audit de sécurité

Commande d’installation

Le README utilise une installation par shell distant :

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

Après l’installation, lancez vc-setup dans Claude Code ; les utilisateurs de Codex doivent suivre le README et utiliser /vc-setup. Cela crée le répertoire process/ et initialise la configuration du projet.

Fichiers écrits par l’installation

Le README actuel décrit l’installation comme non-destructive : elle ne supprime pas les .claude/skills/, .claude/agents/, process/ ou settings.json existants ; elle écrit ou met à jour uniquement les kit-owned files. Elle place tout de même ces répertoires et fichiers dans le projet :

Chemin	Contenu
.claude/agents	Définitions d’agents pour Claude Code ; le README actuel en indique 15
.claude/skills	Définitions de skills pour Claude Code ; le README actuel en indique 33
.claude/hooks	Hooks de cycle de vie ; le README actuel en indique 10
.codex/agents	Agents mirrored pour Codex
.agents/skills	Symlink vers .claude/skills pour Codex discovery
CLAUDE.md	Orchestrateur Claude Code et routing rules
AGENTS.md	Registre agent et skill partagé entre outils
process/	Répertoire du cycle de vie des plans et de la mémoire projet

Le README précise aussi que la configuration existante est sauvegardée dans .vibecode-backup/, qu’un CLAUDE.md existant est sauvegardé sous CLAUDE.md.pre-vibecode, et qu’un process/ existant n’est pas migré directement par l’installateur. vc-setup / vc-update le gèrent de manière interactive.

Checklist d’audit de sécurité

N’exécutez pas curl | bash directement dans un dépôt de production. Même si le README parle d’installation non-destructive, le script shell distant doit être relu. Il écrit dans des chemins sensibles comme .claude/, .codex/, CLAUDE.md et AGENTS.md.

Pour un premier essai, suivez plutôt ce flux :

1. forker ou copier un projet non productif
2. exécuter l’installateur dans ce fork
3. inspecter les fichiers avec git diff
4. migrer seulement si les changements de configuration sont attendus

Il faut aussi vérifier que le comportement de sauvegarde convient à votre dépôt. Les projets qui ont déjà des skills ou agents personnalisés avec le préfixe vc- doivent suivre l’avertissement du README et contrôler le résultat de près.

“Non-destructive” ne veut pas dire “sans risque”. Cela réduit le risque d’effacer un répertoire existant, mais ne remplace ni la revue supply-chain, ni les limites de permissions, ni le plan de rollback. Dans un projet d’équipe, le geste minimal reste : lire le script, l’exécuter dans une copie, et faire relire le diff.

---

Idée centrale : spec-driven workflow

Contexte Spec Kit

L’idée centrale de vibecode-pro-max-kit vient des workflows de spec-driven development, comme Spec Kit. Le principe est simple : écrire la spec, la transformer en plan, découper le plan en tâches, puis implémenter.

Chaque phase génère un artefact Markdown qui fournit un contexte structuré à la phase suivante :

Phase	Entrée	Sortie
Spec	Description du besoin	Document de spécification avec limites, contraintes et critères d’acceptation
Plan	Document de spécification	Plan d’implémentation avec étapes, responsables et dépendances
Tasks	Plan d’implémentation	Liste de tâches concrètes et vérifiables
Implement	Liste de tâches	Changements de code + notes de processus

Ce workflow n’est pas nouveau, mais vibecode-pro-max-kit l’installe dans le projet : agents, skills et hooks sont organisés autour de ce processus.

Cycle de vie du plan

Le README actuel met en avant un workflow RIPER-5 plan-first et décrit 7 gated phases :

Phase	Rôle	Artefact
Research	Collecter le contexte et confirmer les limites	research artifact
Spec	Écrire les user stories et les limites du besoin	spec artifact
Innovate	Comparer les options et noter les arbitrages	alternatives / decision notes
Plan	Détailler les étapes, responsabilités et validations	plan artifact
Validate	Vérifier le plan et les risques avant exécution	validation notes
Execute	Implémenter les tâches et enregistrer le processus	code changes + execution notes
Update-Process	Mettre à jour la mémoire et nettoyer les notes obsolètes	process / context updates

Chaque phase demande une validation explicite avant de continuer. C’est le point de contrôle : un humain vérifie la direction avant que l’agent poursuive.

Agents et skills

Le README indique actuellement 15 agents, 33 skills et 10 hooks. C’est la formulation officielle vérifiée le 23 juin 2026, pas une constante permanente.

La structure des skills suit Codex Skills et Claude Code skills : chaque skill possède un SKILL.md pour les instructions, avec éventuellement scripts/, references/ et assets/. Un skill peut être appelé explicitement ou déclenché implicitement quand la tâche correspond à son périmètre.

Deux autres notions comptent :

• context groups : blocs de contexte organisés par sujet ou par fonctionnalité, pour éviter de charger tout le projet à chaque fois
• feature folders : dossiers par fonctionnalité, avec leur propre spec et leurs propres éléments de process

---

Mécanismes de sécurité

Le README liste plusieurs mécanismes de sécurité et de workflow à examiner :

Mécanisme	Rôle	Moment d’usage
privacy guardrails	Empêcher les informations sensibles d’entrer dans les process files ou l’output	Avant les agent output et process updates
gated phases	Empêcher l’agent de passer directement au code	De Research à Update-Process
check loops	Permettre à l’exécution de s’auto-vérifier et de revenir au plan	Pendant execution et validation
deviation protocol	Enregistrer les écarts par rapport au plan initial	Quand le plan change ou que l’execution dérive
high-risk evidence pack	Exiger des preuves supplémentaires pour les décisions risquées	Quand un seuil est déclenché

Ces mécanismes rendent plus difficile une décision risquée prise par l’IA sans supervision. Ils dépendent tout de même du bon fonctionnement des hooks et de la configuration. Si les hooks sont désactivés, si les permissions sont trop larges, ou si l’équipe ne relit jamais process/, le mécanisme peut échouer.

---

Grille d’adéquation

Scénario	Adéquation	Pourquoi
Projet maintenu sur la durée	Bon choix	La mémoire se dépose dans process/, et les plans sont auditables
Revue à plusieurs	Bon choix	Les décisions laissent une trace, et les écarts sont traçables
Besoin complexe	Bon choix	Collaboration multi-agent et raffinement par phase aident
Contexte facile à perdre	Bon choix	La structure spec-driven donne une forme à la conversation
Script ponctuel	Peu adapté	Le workflow overhead est trop élevé
Petite correction	Peu adapté	Le harness coûte plus cher que le changement
Processus d’ingénierie déjà mature	À utiliser avec prudence	Il peut entrer en conflit avec le CI/CD et le flux de revue existants
Refus d’un harness externe	Pas adapté	README, AGENTS.md, CLAUDE.md et process files modifient le dépôt

La vraie question est : le workflow overhead vaut-il le coût ? Les projets durables, complexes et collaboratifs peuvent échanger cet overhead contre de l’auditabilité et de la coordination. Les projets courts, simples et individuels le paient comme un coût pur.

---

Relation avec Spec Kit, Codex Skills et Claude Code

Spec Kit : définit le cadre et le processus du SDD, ou spec-driven development. C’est une couche conceptuelle, non liée à un agent précis.

Codex Skills : la structure de répertoire de skills d’OpenAI : SKILL.md + scripts/ + references/. Elle regroupe instructions, ressources et scripts dans des workflows réutilisables.

Claude Code skills : structure similaire, avec SKILL.md et des fichiers de support. Un skill agit comme une unité de workflow réutilisable, appelée explicitement ou implicitement.

vibecode-pro-max-kit : installe ces idées dans un projet. Il ne remplace pas Spec Kit ; il rend un workflow spec-driven exécutable sous forme d’agents, skills et hooks, avec une configuration de projet pour Claude Code et Codex.

Coût de migration : si le projet possède déjà .claude/agents, .claude/skills, CLAUDE.md ou AGENTS.md, inspectez le diff et vérifiez que votre configuration personnalisée n’a pas été perdue.

---

Premier workflow d’essai

En suivant l’esprit du README, le premier essai se fait hors production :

Étape 1 : forker ou copier un projet non productif

Ne travaillez pas directement dans le dépôt principal. Utilisez un fork ou une copie locale de test.

Étape 2 : exécuter la commande d’installation

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

Étape 3 : lancer vc-setup

Lancez vc-setup dans Claude Code ; dans Codex, suivez le README et utilisez /vc-setup. Cela crée process/ et initialise la configuration.

Étape 4 : inspecter les fichiers écrits

git status
git diff .claude/ .codex/ .agents/ CLAUDE.md AGENTS.md process/

Vérifiez que les fichiers écrits correspondent aux attentes.

Étape 5 : essayer le premier workflow spec-driven

Donnez à l’agent une demande simple, par exemple “ajouter un helper de logging”. Observez le flux Research → Spec → Innovate → Plan → Validate → Execute → Update-Process et vérifiez que chaque gate de validation se déclenche.

Étape 6 : valider le résultat

Cherchez des artefacts sous process/, des changements lisibles dans CLAUDE.md / AGENTS.md, et aucune erreur provenant des hooks ou agents. Ensuite seulement, envisagez de déplacer le setup vers un vrai projet.

---

Étapes suivantes et lectures liées

Articles publiés liés :

• Pratique du routage multi-agent avec OpenClaw
• Guide complet du workflow Claude Code
• Mécanismes de mémoire des AI agents

Sujets prévus dans cette série :

• Une checklist de dépannage pour la collaboration multi-agent
• Une étude de cas pratique de projet spec-driven