vibecode-pro-max-kit: specifiche, memoria e collaborazione multi-agent per progetti di AI coding

I progetti scritti con l’IA tendono a perdere il controllo in tre punti: il contesto viene tagliato, i piani restano sparsi nella chat, le decisioni non lasciano traccia. Ogni volta che cambia un requisito, bisogna rispiegare l’intero progetto.

vibecode-pro-max-kit affronta il problema del processo: trasforma l’AI coding agent in un engineering team guidato da specifiche. Prima si scrivono le specifiche, poi il piano, poi l’esecuzione, e ogni passaggio lascia un record auditabile. Non è un framework di chat e non sostituisce CI/CD; fa una cosa precisa: rende tracciabile il processo decisionale dell’AI coding.

---

Che problema risolve

Perdita di contesto: le conversazioni lunghe vengono tagliate dalla compaction e spariscono decisioni di design, condizioni al contorno e ragionamenti di debug. Alla richiesta successiva devi rispiegare tutto, oppure lasci che l’IA indovini.

Piani e decisioni senza traccia: esportare una chat in Markdown non crea documentazione strutturata. Quando un team fa review, non vede la storia: perché è stata scelta una soluzione, quali opzioni sono state escluse, quali vincoli erano in gioco.

Collaborazione multi-agent costosa: un task diviso in più passaggi, affidato a agent diversi, dipende da handoff vaghi in linguaggio naturale. Chi possiede quale fase, qual è il formato di output, dove sono i criteri di accettazione: tutto va sorvegliato a mano.

Somma questi tre problemi e l’AI coding diventa “ogni volta come la prima volta”. vibecode-pro-max-kit li raccoglie in un harness: spec davanti, plan nel mezzo, checkpoint durante l’esecuzione e memoria del processo.

---

Installazione e audit di sicurezza

Comando di installazione

Il README propone l’installazione via shell remota:

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

Dopo l’installazione, in Claude Code si esegue vc-setup; chi usa Codex segue il README e usa /vc-setup. Il comando crea la directory process/ e inizializza la configurazione.

File scritti nel progetto

Il README attuale descrive l’installazione come non distruttiva: non svuota .claude/skills/, .claude/agents/, process/ o settings.json; scrive o aggiorna solo file di proprietà del kit. Inserisce comunque questi file e directory nel progetto:

Percorso	Contenuto
.claude/agents	Definizioni di agent per Claude Code; il README attuale ne indica 15
.claude/skills	Definizioni di skill per Claude Code; il README attuale ne indica 33
.claude/hooks	Hook del ciclo di vita; il README attuale ne indica 10
.codex/agents	Agent mirror per l’uso con Codex
.agents/skills	Symlink verso .claude/skills per la discovery di Codex
CLAUDE.md	Orchestrator e routing rules per Claude Code
AGENTS.md	Registry cross-tool di agent e skill
process/	Directory per ciclo di vita dei piani e memoria di progetto

Il README spiega anche che le configurazioni esistenti vengono salvate in .vibecode-backup/, un CLAUDE.md già presente viene copiato come CLAUDE.md.pre-vibecode, e un process/ esistente non viene migrato direttamente dallo script: la gestione interattiva passa da vc-setup / vc-update.

Punti di audit di sicurezza

Non eseguire curl | bash direttamente nella repository di produzione. Anche se il README dichiara un’installazione non distruttiva, uno script shell remoto va controllato, perché scrive in percorsi sensibili come .claude/, .codex/, CLAUDE.md e AGENTS.md.

Per una prima prova:

1. fai un fork o copia un progetto non produttivo
2. esegui l’installazione nel fork
3. controlla con git diff i file scritti
4. valuta la migrazione solo dopo aver confermato che non ci sono modifiche inattese

Devi verificare tu se il meccanismo di backup dello script è adatto alla tua repository. I progetti che hanno già skill o agent personalizzati con prefisso vc- devono controllare con ancora più attenzione le caveat del README.

“Non sovrascrive” non significa “senza rischio”. Riduce la probabilità di cancellare directory esistenti, ma non sostituisce audit di supply chain, isolamento dei permessi e piano di rollback. Per un team, il minimo rimane: leggere lo script, provarlo su una copia, far guardare il diff a un reviewer.

---

Concetto centrale: workflow guidato da specifiche

Contesto Spec Kit

L’idea principale di vibecode-pro-max-kit viene dai workflow di spec-driven development (SDD) come Spec Kit. Il flusso è: prima si scrivono le specifiche, poi si trasformano in piano, poi in task, infine si esegue.

Ogni fase genera un artifact Markdown che fornisce contesto strutturato alla fase successiva:

Fase	Input	Output
Spec	Descrizione del requisito	Documento di specifica: confini, vincoli, criteri di accettazione
Plan	Documento di specifica	Piano di implementazione: passaggi, responsabili, dipendenze
Tasks	Piano di implementazione	Lista di task concreta e verificabile
Implement	Lista di task	Modifiche al codice + record del processo

Il flusso non è nuovo, ma vibecode-pro-max-kit lo “installa nel progetto”: agent, skill e hook sono progettati intorno a questo processo.

Ciclo di vita del piano

Il README attuale enfatizza un workflow RIPER-5 plan-first e lo descrive come 7 fasi con gate:

Fase	Cosa fa	Artifact prodotto
Research	Raccoglie contesto e conferma i confini	research artifact
Spec	Chiarisce user story e confini del requisito	spec artifact
Innovate	Confronta soluzioni e registra trade-off	alternatives / decision notes
Plan	Dettaglia passaggi, responsabilità e verifiche	plan artifact
Validate	Valida piano e rischi prima dell’esecuzione	validation notes
Execute	Esegue i task e registra il processo	code changes + execution notes
Update-Process	Aggiorna la memoria e rimuove record obsoleti	aggiornamenti a process / context

Ogni fase richiede approvazione esplicita per avanzare. È il punto che impedisce all’IA di deragliare: l’essere umano interviene ai checkpoint, conferma la direzione e solo dopo lascia proseguire.

Agent e skill

Il README attuale parla di 15 agent, 33 skill e 10 hook. È il conteggio verificato nel README al 2026-06-23; può cambiare con gli aggiornamenti della repository, quindi non va trattato come un numero permanente.

La struttura delle skill è allineata a Codex Skills e Claude Code skills: ogni skill ha un SKILL.md con le istruzioni e, opzionalmente, scripts/, references/, assets/. Una skill può essere chiamata esplicitamente o attivata implicitamente se rientra nel suo perimetro.

Altri due concetti:

• context groups: blocchi di contesto organizzati per tema o funzione, così non serve caricare sempre tutto il progetto
• feature folders: file organizzati per modulo funzionale, ciascuno con le proprie spec e il proprio process

---

Meccanismi di sicurezza

Il README elenca alcune famiglie di meccanismi di sicurezza e processo che vale la pena controllare:

Meccanismo	Funzione	Quando si attiva
privacy guardrails	Evita che informazioni sensibili finiscano in process o negli output	Prima degli output degli agent e degli aggiornamenti di processo
gated phases	Impedisce all’agent di saltare direttamente alla scrittura del codice	Avanzamento da Research a Update-Process
check loops	Permette all’esecuzione di autocontrollarsi e tornare al piano	Durante esecuzione e validazione
deviation protocol	Registra deviazioni dal piano originale	Quando il piano cambia o l’esecuzione se ne discosta
high-risk evidence pack	Richiede prove aggiuntive per decisioni ad alto rischio	Al superamento di certe soglie di giudizio

Questi meccanismi rendono più difficile per l’IA prendere decisioni rischiose senza supervisione. Ma dipendono dal corretto funzionamento di hook e configurazioni. Se gli hook sono disabilitati, i permessi sono troppo ampi o il team non rivede process/, possono comunque perdere efficacia.

---

Tabella per decidere se usarlo

Scenario	Adatto?	Motivo
Progetto mantenuto nel tempo	Sì	La memoria sedimenta in process/ e i piani sono auditabili
Review di team	Sì	Decisioni e deviazioni sono tracciabili
Requisiti complessi	Sì	Collaborazione multi-agent e affinamento per fasi
Contesto che si perde facilmente	Sì	Conversazione strutturata dallo spec-driven workflow
Script una tantum	Non molto	L’overhead del processo è eccessivo
Piccole correzioni	Non molto	Il costo dell’harness supera il beneficio
Processo ingegneristico già maturo	Con cautela	Può entrare in conflitto con CI/CD e review esistenti
Non vuoi introdurre un harness esterno	No	README, AGENTS.md, CLAUDE.md e process cambiano la struttura della repository

Il criterio chiave è: l’overhead del processo vale il costo? Nei progetti lunghi, complessi e collaborativi, l’overhead compra auditabilità ed efficienza di coordinamento. Nei progetti brevi, semplici e solitari, resta solo costo.

---

Relazione con Spec Kit, Codex Skills e Claude Code

Spec Kit: definisce il contesto e il framework dello SDD, cioè spec-driven development. È il livello concettuale, non legato a un singolo agent.

Codex Skills: è la struttura di directory delle skill OpenAI: SKILL.md + scripts/ + references/. Impacchetta istruzioni, risorse e script in workflow riutilizzabili.

Claude Code skills: struttura simile, SKILL.md più file di supporto. Tratta le skill come unità di processo riutilizzabili, chiamabili in modo esplicito o implicito.

vibecode-pro-max-kit: porta queste idee dentro il progetto. Non sostituisce Spec Kit; trasforma il flusso spec-driven in agent + skill + hook eseguibili, compatibili con la configurazione di progetto di Claude Code e Codex.

Costo di migrazione: se il progetto ha già .claude/agents, .claude/skills, CLAUDE.md o AGENTS.md, devi valutare il diff e verificare che le tue configurazioni personalizzate non vadano perse.

---

Procedura per la prima prova

Segui il consiglio del README e prova prima su un progetto non produttivo:

Passaggio 1: fai un fork o copia un progetto non produttivo

Non lavorare direttamente sulla repository principale. Usa un fork o copia una directory locale di test.

Passaggio 2: esegui il comando di installazione

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

Passaggio 3: esegui vc-setup

In Claude Code esegui vc-setup; in Codex usa /vc-setup come indicato dal README. Verrà creata la directory process/ e inizializzata la configurazione.

Passaggio 4: controlla i file scritti

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

Verifica che i file scritti corrispondano alle aspettative.

Passaggio 5: prova il primo workflow spec-driven

Dai all’agent una richiesta semplice, per esempio “aggiungi una funzione di logging”. Osserva il percorso Research -> Spec -> Innovate -> Plan -> Validate -> Execute -> Update-Process e verifica che il meccanismo di approvazione si attivi a ogni fase.

Passaggio 6: accetta o scarta

Solo dopo aver visto artifact dentro process/, modifiche comprensibili a CLAUDE.md / AGENTS.md e nessun errore da hook o agent, valuta la migrazione su un progetto reale.

---

Prossimi passi e letture correlate

Articoli già pubblicati:

• Pratica di routing multi-agent con OpenClaw
• Guida completa al workflow di Claude Code
• Come funziona la memoria degli AI agent

Contenuti futuri della serie:

• Checklist di troubleshooting per la collaborazione multi-agent
• Caso pratico di progetto spec-driven