vibecode-pro-max-kit: specs, memoria y flujo multiagente para programar con IA

La programación con IA suele perder control no por un fallo espectacular del modelo, sino por tres rupturas pequeñas: el contexto se corta, los planes quedan solo en el historial del chat y las decisiones no dejan rastro. Cada cambio de requisitos obliga a explicar el proyecto entero otra vez.

vibecode-pro-max-kit intenta resolver un problema de workflow. Acerca un AI coding agent a un equipo de ingeniería guiado por specs: primero se escribe la especificación, luego se planifica, después se ejecuta, y cada paso deja registros auditables. No es un framework de chat y no reemplaza CI/CD. Su trabajo es más concreto: hacer que las decisiones de programación con IA sean trazables.

---

Qué problema resuelve

Pérdida de contexto: las conversaciones largas se cortan por compaction, y desaparecen decisiones de diseño, condiciones de borde y pistas de depuración. El siguiente cambio exige volver a explicar todo o dejar que la IA adivine.

Planes y decisiones sin rastro: exportar Markdown desde un chat no crea documentación estructurada. Durante una revisión, el equipo no ve por qué se eligió una solución ni qué opciones se descartaron.

Handoffs multiagente costosos: una tarea puede dividirse entre varios agents, pero el traspaso suele depender de lenguaje natural impreciso. Quién es responsable de cada paso, cuál es el formato de salida y dónde están los criterios de aceptación siguen requiriendo supervisión humana.

Juntas, estas tres cosas hacen que programar con IA se sienta como empezar desde cero cada vez. vibecode-pro-max-kit las mete en un solo harness: spec al principio, plan en el medio, checkpoints durante execution y memoria alrededor del proceso.

---

Instalación y auditoría de seguridad

Comando de instalación

El README propone una instalación mediante shell remoto:

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

Después de instalar, ejecuta vc-setup en Claude Code; los usuarios de Codex deben seguir el README y usar /vc-setup. Esto crea el directorio process/ e inicializa la configuración del proyecto.

Archivos que escribe la instalación

El README actual describe la instalación como non-destructive: no borra .claude/skills/, .claude/agents/, process/ ni settings.json existentes; solo escribe o actualiza kit-owned files. Aun así, coloca estos directorios y archivos en el proyecto:

Ruta	Contenido
.claude/agents	Definiciones de agent para Claude Code; el README actual dice 15
.claude/skills	Definiciones de skill para Claude Code; el README actual dice 33
.claude/hooks	Hooks de ciclo de vida; el README actual dice 10
.codex/agents	Agents mirrored para Codex
.agents/skills	Symlink a .claude/skills para Codex discovery
CLAUDE.md	Orquestador de Claude Code y routing rules
AGENTS.md	Registro de agent y skill entre herramientas
process/	Directorio de ciclo de vida de planes y memoria del proyecto

El README también indica que la configuración existente se respalda en .vibecode-backup/, que un CLAUDE.md existente se guarda como CLAUDE.md.pre-vibecode y que un process/ existente no lo migra directamente el instalador. Eso lo manejan vc-setup / vc-update de forma interactiva.

Checklist de auditoría de seguridad

No ejecutes curl | bash directamente en un repositorio de producción. Aunque el README llame non-destructive a la instalación, el script remoto necesita revisión porque escribe en rutas sensibles como .claude/, .codex/, CLAUDE.md y AGENTS.md.

Para la primera prueba, usa este flujo:

1. haz un fork o copia de un proyecto no productivo
2. ejecuta el instalador en ese fork
3. revisa los archivos con git diff
4. migra solo si los cambios de configuración son esperados

También debes verificar que el comportamiento de respaldo encaja con tu repositorio. Los proyectos con skills o agents personalizados que empiecen por vc- deben seguir la advertencia del README y revisar el resultado con cuidado.

“Non-destructive” tampoco significa “sin riesgo”. Reduce la probabilidad de borrar un directorio existente, pero no sustituye la revisión de supply chain, los límites de permisos ni la preparación de rollback. En un proyecto de equipo, el movimiento mínimo seguro sigue siendo: leer el script, ejecutarlo en una copia y pedir a otra persona que revise el diff.

---

Idea central: spec-driven workflow

Contexto de Spec Kit

La idea central de vibecode-pro-max-kit viene de workflows de spec-driven development como Spec Kit. El flujo es simple: primero escribir la spec, luego convertirla en plan, dividir el plan en tareas y finalmente implementar.

Cada fase genera un artefacto Markdown que entrega contexto estructurado a la siguiente fase:

Fase	Entrada	Salida
Spec	Descripción del requisito	Documento de especificación con límites, restricciones y criterios de aceptación
Plan	Documento de especificación	Plan de implementación con pasos, responsables y dependencias
Tasks	Plan de implementación	Lista de tareas concretas y verificables
Implement	Lista de tareas	Cambios de código + notas del proceso

Este workflow no es nuevo, pero vibecode-pro-max-kit lo instala dentro del proyecto: agents, skills y hooks están organizados alrededor de ese proceso.

Ciclo de vida del plan

El README actual destaca un workflow RIPER-5 plan-first y lo describe como 7 gated phases:

Fase	Qué hace	Artefacto
Research	Reúne contexto y confirma límites	research artifact
Spec	Escribe user stories y límites de requisitos	spec artifact
Innovate	Compara opciones y registra trade-offs	alternatives / decision notes
Plan	Detalla pasos, responsabilidad y validación	plan artifact
Validate	Revisa plan y riesgos antes de ejecutar	validation notes
Execute	Implementa tareas y registra el proceso	code changes + execution notes
Update-Process	Actualiza memoria y limpia notas obsoletas	process / context updates

Cada fase requiere aprobación explícita antes de avanzar. Ese es el punto de control: una persona valida la dirección antes de que el agent continúe.

Agents y skills

El README dice actualmente 15 agents, 33 skills y 10 hooks. Es la formulación del README oficial verificada el 23 de junio de 2026, no un valor permanente.

La estructura de skills sigue la de Codex Skills y Claude Code skills: cada skill tiene un SKILL.md para instrucciones y, de forma opcional, scripts/, references/ y assets/. Un skill puede llamarse explícitamente o activarse de forma implícita cuando la tarea coincide con su alcance.

También importan dos conceptos:

• context groups: bloques de contexto organizados por tema o función para no cargar todo el proyecto cada vez
• feature folders: carpetas por funcionalidad con su propio material de spec y process

---

Mecanismos de seguridad

El README enumera varios mecanismos de seguridad y workflow que conviene mirar con atención:

Mecanismo	Función	Cuándo importa
privacy guardrails	Evita que información sensible entre en process files u output	Antes de agent output y process updates
gated phases	Impide que el agent salte directo al código	De Research a Update-Process
check loops	Permite que la ejecución se autoevalúe y vuelva al plan	Durante execution y validation
deviation protocol	Registra conductas que se apartan del plan original	Cuando cambia el plan o execution se desvía
high-risk evidence pack	Exige pruebas adicionales para decisiones riesgosas	Cuando se activa un umbral

Estos mecanismos hacen más difícil que la IA tome decisiones de alto riesgo sin supervisión. Aun así dependen de que hooks y configuración funcionen correctamente. Si los hooks están desactivados, los permisos son demasiado amplios o el equipo nunca revisa process/, el mecanismo puede fallar.

---

Tabla de encaje

Escenario	Encaje	Motivo
Proyecto mantenido a largo plazo	Buen encaje	La memoria queda en process/ y los planes son auditables
Revisión por varias personas	Buen encaje	Las decisiones dejan rastro y los desvíos se pueden rastrear
Requisito complejo	Buen encaje	Ayudan la colaboración multiagente y el refinamiento por fases
Contexto fácil de perder	Buen encaje	La estructura spec-driven da forma a la conversación
Script puntual	Poco encaje	El workflow overhead es demasiado alto
Arreglo pequeño	Poco encaje	El harness cuesta más que el cambio
Proceso de ingeniería maduro	Usar con cautela	Puede chocar con el flujo existente de CI/CD y revisión
No quieres un harness externo	No encaja	README, AGENTS.md, CLAUDE.md y process files cambian el repositorio

La pregunta central es si el workflow overhead vale la pena. Los proyectos largos, complejos y colaborativos pueden cambiar ese overhead por auditabilidad y coordinación. Los proyectos cortos, simples e individuales lo pagan como costo puro.

---

Relación con Spec Kit, Codex Skills y Claude Code

Spec Kit: define el contexto y el marco de proceso de SDD, o spec-driven development. Es una capa conceptual y no está atada a un agent específico.

Codex Skills: la estructura de directorios de skills de OpenAI: SKILL.md + scripts/ + references/. Empaqueta instrucciones, recursos y scripts en workflows reutilizables.

Claude Code skills: estructura similar, con SKILL.md y archivos de apoyo. Un skill actúa como una unidad de workflow reutilizable y puede invocarse de forma explícita o implícita.

vibecode-pro-max-kit: instala esas ideas en un proyecto. No reemplaza Spec Kit; convierte un workflow spec-driven en agents, skills y hooks ejecutables, con configuración de proyecto para Claude Code y Codex.

Costo de migración: si el proyecto ya tiene .claude/agents, .claude/skills, CLAUDE.md o AGENTS.md, revisa el diff y asegúrate de que tu configuración personalizada no se haya perdido.

---

Primer flujo de prueba

Siguiendo el README, la primera prueba debe hacerse fuera de producción:

Paso 1: hacer fork o copiar un proyecto no productivo

No trabajes directamente en el repositorio principal. Usa un fork o una copia local de prueba.

Paso 2: ejecutar el comando de instalación

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

Paso 3: ejecutar vc-setup

Ejecuta vc-setup en Claude Code; en Codex, sigue el README y usa /vc-setup. Esto crea process/ e inicializa la configuración.

Paso 4: inspeccionar los archivos escritos

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

Confirma que los archivos escritos coincidan con lo esperado.

Paso 5: probar el primer workflow spec-driven

Dale al agent una petición simple, como “agregar un helper de logging”. Observa el flujo Research → Spec → Innovate → Plan → Validate → Execute → Update-Process y confirma que se active cada gate de aprobación.

Paso 6: validar el resultado

Busca artefactos bajo process/, cambios legibles en CLAUDE.md / AGENTS.md y ningún error de hooks o agents. Solo entonces considera mover el setup a un proyecto real.

---

Próximos pasos y lecturas relacionadas

Artículos relacionados ya publicados:

• Práctica de enrutamiento multiagente con OpenClaw
• Guía completa del workflow de Claude Code
• Mecanismos de memoria de AI agents

Temas previstos en esta serie:

• Una checklist de troubleshooting para colaboración multiagente
• Un caso práctico de proyecto spec-driven