English | 简体中文 | 日本語 | 한국어 | Tiếng Việt | Português | Español | Deutsch | Français | हिंदी

Flowser *Creado por ingenieros de clase mundial, para vibecoders en*
*[flowser.ai](https://flowser.ai) — Agentes de IA con computadoras para GTM*
# vibecode-pro-max-kit

Flow like water

"Concentración Total — Respiración de Especificación, Décima Forma: el Flujo Vibe nunca se rompe."
— Tanjiro Kamado

*Añádelo a cualquier proyecto. Tu agente de IA obtiene un proceso de desarrollo completo orientado al plan — 7 fases con controles, bucles de autocorrección y piloto automático que funciona de inicio a fin sin perder el hilo.*
📦 Instalación en un solo comando
Una línea con curl lo integra en cualquier proyecto. Detecta si eres nuevo o usuario habitual y nunca sobreescribe tus archivos.		 🌐 Funciona en todas partes
Cualquier stack tecnológico, cualquier lenguaje y cualquier agente de código de IA: Claude Code, Codex, Cursor, Windsurf, Copilot y más.
🧭 Flujo de trabajo RIPER-5 orientado al plan
7 fases con controles (Research → Spec → Innovate → Plan → Validate → Execute → Update-Process) evitan que el agente salte directamente al código.		 🚀 Modo piloto automático (quick / fast / full)
Inicia una ejecución sin intervención en cualquier fase con una sola frase. Tres carriles ajustan la formalidad al nivel de riesgo.
🎯 /goal — el token de ejecución continua
Un bloque que se puede copiar y pegar mantiene al agente avanzando fase a fase sin detenerse — y retoma la ejecución en una sesión nueva.		 🔁 Bucles de autocorrección PVL + EVL
Los bucles de comprobación-y-corrección del plan y de las pruebas detectan errores, los corrigen y vuelven a verificar solos — hasta 10 ciclos cada uno.
🔍 vc-autoresearch
Un bucle reutilizable de encontrar-errores → corregir → repetir que puedes aplicar a planes, pruebas, especificaciones, documentación o evaluaciones.		 🧪 Sondas de viabilidad
Veredictos de prueba-antes-de-construir (VIABLE / NOT-VIABLE) antes de que el agente se comprometa con cualquier enfoque de diseño.
🎛️ Selector de estrategia inteligente
Antes de cada fase, evalúa un agente versus varios versus un equipo coordinado — con estimaciones de coste — y elige la opción más económica que se adapte.		 🧮 Uso inteligente de modelos
El modelo costoso solo escribe código; el modelo más económico hace todo lo demás. Menor coste, misma calidad.
🤔 Aclaración de intención
Cuando una solicitud es vaga, el agente hace unas pocas preguntas concretas al inicio en lugar de adivinar y construir algo incorrecto.		 🛡️ 36 validadores
Verificaciones mecánicas de corrección — no opiniones — protegen la estructura propia del kit y detectan desviaciones antes de que lleguen a producción.
🏗️ Programas de fases
Los proyectos grandes se dividen en fases independientes con controles de calidad entre ellas, para que el trabajo grande no se derrumbe.		 🔀 Programas que se reorganizan solos
A medida que aprende, el agente inserta nuevas fases, reordena el trabajo y omite pasos bloqueados — el plan se adapta sobre la marcha.
🧠 Nunca pierde el hilo
El progreso se escribe en disco en cada fase, por lo que una ejecución sobrevive a un reinicio de memoria y retoma exactamente donde lo dejó.		 📚 Memoria de proyecto que mejora sola
Aprende tu base de código en la configuración inicial y mantiene sus propias notas compartidas actualizadas tras cada entrega, para que la documentación nunca quede desfasada.
⚡ Quick Fix + Fast Mode
Carriles ligeros para cambios pequeños que omiten la formalidad completa, para que una corrección de una línea siga siendo una corrección de una línea.		 🧱 Habilidades organizadas y autodescubiertas
Las habilidades están organizadas en capas claras y se descubren automáticamente — el agente siempre encuentra la herramienta adecuada para cada paso.
🤖 15 agentes · 33 habilidades · 10 hooks
Un equipo completo de agentes especializados, habilidades reutilizables y hooks de seguridad, todos conectados desde el primer momento.		 🔄 Ciclo de vida completo del kit
Instalar, configurar, actualizar y publicar son un solo comando cada uno — manteniendo todos los proyectos en la versión más reciente del kit de forma segura.
📝 SPEC — tu aprobación en lenguaje sencillo
Antes de cualquier diseño, describes lo que hay que construir en historias de usuario simples — el momento más económico para detectar malentendidos.		 🎯 Siempre verifica tu intención
Cada fase posterior se mide contra tu SPEC: ¿lo que estamos construyendo es realmente lo que pediste?

Stars Forks License Contributors CI Version Agents Skills Hooks 7 Tools

El kit de desarrollo más simple, flexible y apto para equipos, para

Claude Code  Codex CLI  Cursor  Windsurf
Antigravity  OpenCode  GitHub Copilot

Funciona con cualquier stack tecnológico, cualquier lenguaje, cualquier proyecto

Tech Stack Row 1
Tech Stack Row 2
Tech Stack Row 3

No es solo decorativo. Cuando ejecutas vc-setup, los agentes escanean tu base de código,
detectan tu stack y construyen grupos de conocimiento específicos del proyecto que cada habilidad lee antes de actuar.
Otros harnesses bloquean a los agentes en un solo lenguaje — rust-review-agent, python-linter — inútiles en otro contexto.
Este se adapta a cualquier combinación de las anteriores y acumula conocimiento a medida que entregas.

--- ## ⚡ Empieza Ya — Un Comando, 30 Segundos > **Requisitos previos:** Node.js ≥ 22, git, bash (macOS / Linux / WSL; en Alpine: `apk add bash`). **Hay un solo comando y funciona para todos.** Ejecútalo dentro de la carpeta de tu proyecto. Detecta si eres usuario nuevo o habitual, instala de forma segura sin sobreescribir tus archivos y luego *te dice exactamente qué hacer a continuación.* ```bash curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash ``` Cuando termine, muestra uno de dos mensajes — **lee el final de la salida y haz exactamente lo que indica:**

🆕 Proyecto nuevo

El instalador detecta que no hay harness y muestra:

Next: Run: claude → Say: "Run vc-setup"

→ Abre tu agente y di Run vc-setup

vc-setup detecta tu stack tecnológico, crea la carpeta process/, escanea tu base de código y rellena tu arquitectura real, convenciones y comandos de prueba — una conversación, no una lista de comprobación.

🔄 Harness existente (actualización)

El instalador detecta una instalación previa y muestra:

Next (upgrade detected): Run: claude → Say: "Run vc-update"

→ Abre tu agente y di Run vc-update

vc-update descarga la versión más reciente y, si encuentra planes o carpetas en formato antiguo, te da un prompt listo para pegar que completa la migración con cero pérdida de datos. Tu carpeta process/ nunca se toca.
> 💡 **Nunca tendrás que adivinar el comando.** `install.sh` te dirige: nuevo → `vc-setup`, actualización → `vc-update`. Volver a ejecutar la instalación siempre es seguro — nunca rompe nada. **Usuarios de Codex:** ejecuta `/vc-setup` (o `/vc-update`) en lugar de decirlo en el chat.
📦 Qué instala en disco (no destructivo)
``` your-project/ ├── .claude/ │ ├── agents/ # 🤖 15 agent definitions (.md) │ ├── skills/ # ⚡ 33 skills (each a dir with SKILL.md) │ └── hooks/ # 🪝 10 lifecycle hooks (.cjs / .mjs) ├── .codex/agents/ # 🔄 Mirrored agents for Codex ├── .agents/skills → # 🔗 Symlink to .claude/skills (Codex discovery) ├── CLAUDE.md # 📋 Orchestrator + routing rules ├── AGENTS.md # 📖 Agent + skill registry (cross-tool) └── process/ └── development-protocols/ # 📜 22 shared workflow docs (seeded by install) # context/, plans, features → built by vc-setup ``` - **No destructivo.** Tus `.claude/skills/`, `.claude/agents/`, `process/` y `settings.json` existentes nunca se borran. Solo se escriben o actualizan los archivos propiedad del kit. - **¿Configuración existente?** Se respalda en `.vibecode-backup/`; tu `settings.json` se restaura después. - **¿`CLAUDE.md` existente?** Se respalda como `CLAUDE.md.pre-vibecode`. - **¿`process/` existente?** La instalación nunca lo toca — `vc-setup` / `vc-update` lo migran de forma interactiva, mostrándote primero las diferencias. > **Advertencia en la primera instalación:** si tienes habilidades o agentes personalizados cuyos nombres comienzan con `vc-` (el espacio de nombres reservado del kit) y *nunca* has ejecutado la instalación antes, el paso de eliminación de elementos obsoletos podría marcarlos. Tras la instalación, ejecuta `ls .claude/skills/ .claude/agents/` para confirmarlo. Usa un prefijo distinto de `vc-` (`my-`, `team-`, `proj-`) para tus propias adiciones y evitar esto por completo.
🤖 ¿Prefieres configurarlo desde tu agente? (prompt completo)
> Abre Claude Code o Codex **con la carpeta de tu proyecto como directorio de trabajo** y luego pega: ``` First, install the vibecode-pro-max-kit agent harness by running this command: curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash After install completes, run vc-setup and follow the full interactive flow: 1. DETECT — Read package.json (or go.mod, Cargo.toml, pyproject.toml, etc.), detect my stack: framework, package manager, monorepo structure, test framework, database, auth. Also check for any existing .claude/, process/, or context files. 2. SHOW ME WHAT YOU FOUND — Summarize detection and wait for me to confirm. If this is an existing project, tell me what looks good vs what could be improved. 3. ASK ME ABOUT THE PROJECT — Have a real conversation. Ask follow-ups, probe anything vague, keep going until you genuinely understand it. Summarize back and confirm. 4. SCAFFOLD — Create the process/ directory. If process/ already exists, show me the plan and wait for approval. Never silently move or delete my files. 5. STUDY — Deep-scan and populate process/context/all-context.md with REAL content: repo structure, stack + versions, patterns, import aliases, env vars, routes, schema, tests. No placeholder text. 6. VALIDATE — Run all validation checks to confirm everything is wired correctly. Rules: read and preserve good existing context; show me a summary before each major change and wait for my OK; never create empty placeholder files; ask before reorganizing. ```
Tabla de contenidos - [De un vistazo](#-de-un-vistazo) · [El problema](#-el-problema) · [La solución](#-la-solución) - [La revolución del Vibe Coding](#la-revolución-del-vibe-coding) · [Para quién es esto](#para-quién-es-esto) · [Cómo se compara](#cómo-se-compara) · [Qué lo hace diferente](#-qué-lo-hace-diferente) - [Cómo funciona: el coordinador](#-cómo-funciona--el-coordinador) · [El ciclo de vida RIPER-5](#-el-ciclo-de-vida-riper-5) · [Aclaración de intención](#-aclaración-de-intención) - [Los dos bucles de calidad (PVL + EVL)](#-los-dos-bucles-de-calidad--pvl--evl) · [Comparación de estrategias + política de modelos](#-comparación-de-estrategias--política-de-modelos) · [Modo piloto automático](#-modo-piloto-automático--riper-5-sin-intervención) · [Sondas de viabilidad + validadores](#-sondas-de-viabilidad--la-red-de-seguridad-de-validadores) - [Sistemas de seguridad integrados](#-sistemas-de-seguridad-integrados) · [Inteligencia previa a la implementación](#-inteligencia-previa-a-la-implementación) · [Cadena de calidad](#-cadena-de-calidad--integrada-en-la-ejecución) - [Ciclo de vida del plan](#-el-ciclo-de-vida-del-plan) · [Programas de fases](#-programas-de-fases--proyectos-grandes-que-no-se-derrumban) · [Grupos de contexto](#-grupos-de-contexto) · [Carpetas de funcionalidades](#-carpetas-de-funcionalidades) · [Capas de habilidades](#-capas-de-habilidades) · [Memoria que mejora sola](#-memoria-de-proyecto-que-mejora-sola) - [Qué incluye](#-qué-incluye) · [Quick Fix + Fast Mode](#-quick-fix--fast-mode) · [Ciclo de vida del kit](#-ciclo-de-vida-del-kit-install--setup--update--publish) · [Contribuir](#contribuir)
--- ## 🎁 De un Vistazo

🤖

15

Agentes
Uno por fase + 6 agentes especialistas

⚡

33

Habilidades
20 de flujo de trabajo + 13 de ayuda, asociadas por palabra clave

🪝

10

Hooks
Barreras de seguridad + carga automática de contexto

📜

22

Protocolos
Reglas compartidas que sigue cada agente

🛡️

36

Validadores
Verificaciones automáticas que detectan errores antes de que lleguen a producción

🔧

7

Herramientas
Claude Code · Codex · Cursor · Windsurf · Antigravity · OpenCode · Copilot

🌍

10

Idiomas
EN · 中文 · 日本語 · 한국어 · VI · PT · DE · FR · ES · हिन्दी

⚡

30s

Instalación
Un comando, luego tu agente guía el resto

🛩️

Piloto automático
3 carriles (quick / fast / full) — arranca en cualquier fase, funciona de inicio a fin sin parar

📌

Bloques /goal
Textos cortos que se copian y pegan para retomar ejecuciones sin intervención entre sesiones tras un reinicio

🔁

vc-autoresearch
Bucle de encontrar-errores → corregir → repetir (herramienta compartida para planes, pruebas y evaluaciones)

🔬

Sondas de viabilidad
Veredictos de prueba-antes-de-construir (VIABLE / NOT-VIABLE) antes de comprometerse con un diseño
--- ## 🔥 El Problema Le pides a Claude que "añada soporte para webhooks". Inmediatamente empieza a escribir código. Sin preguntas sobre tu arquitectura. Sin revisar los patrones existentes. Sin plan. Obtienes 400 líneas que no encajan en tu base de código y te pasas una hora arreglándolo. **Pero eso es solo la superficie.** Los problemas más profundos duelen más:

🧠

El contexto muere en cada sesión

Tu agente olvida todo lo que aprendió. Los mismos errores, las mismas preguntas, cada vez. Sin memoria, sin conocimiento acumulado.

📄

La documentación queda obsoleta al instante

Escribiste buena documentación de contexto la semana pasada. Ya está desactualizada. Nada la actualiza automáticamente a medida que evoluciona la base de código.

💥

Las tareas grandes colapsan a mitad de camino

La ventana de contexto se llena, el estado se pierde y el agente empieza a alucinar. Reinicias desde cero en la hora 3.

🤝

Sin especificaciones, sin revisión, sin colaboración

Tu PM no puede revisar lo que el agente está a punto de construir. No hay un plan escrito para compartir, discutir o aprobar antes de escribir el código.

🎭

Las decisiones de arquitectura se inventan

El agente inventa patrones en lugar de investigar cómo otras bases de código resolvieron el mismo problema.

🚀

Nadie verifica que esté "listo"

El agente dice "todas las pruebas pasan" — pero nunca las volvió a ejecutar de forma independiente. Te enteras en producción.
**Tu agente tiene inteligencia pero no tiene proceso, no tiene memoria y no tiene manera de colaborar con tu equipo.** Tanto si eres desarrollador, PM o CEO que acaba de empezar con el vibe coding — esto afecta a todos de la misma manera, y la solución es la misma: **dale a tu agente un proceso de desarrollo real.** --- ## 🛠️ La Solución Este kit instala un sistema de desarrollo completo en tu proyecto — no solo un `CLAUDE.md`, sino **15 agentes especializados, 33 habilidades, 10 hooks y 22 protocolos** — con un flujo de trabajo por fases que hace que tu agente **comprenda antes de construir, y demuestre antes de entregar.**

📋

Enfoque orientado al plan

PMs y desarrolladores revisan el mismo plan escrito antes de escribir cualquier código

🔄

Conocimiento que mejora solo

Se actualiza cada vez que se entrega una funcionalidad — la documentación nunca queda obsoleta

⚡

Ejecución sin intervención

Sobrevive a los reinicios de sesión — funciona durante horas, no minutos

🧬

Investigación de arquitectura

Estudia bases de código reales antes de tomar decisiones de diseño

✅

Dos controles de calidad

Los planes se verifican antes de codificar; las pruebas se vuelven a ejecutar de forma independiente después

🧭

Enrutamiento inteligente de conocimiento

Carga solo lo que es relevante — no toda tu base de conocimiento cada vez

### El flujo completo RIPER-5 — 7 fases, cada paso con control ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD R["RESEARCH\nread-only facts"] S["SPEC\nrequirements doc"] I["INNOVATE\n2-3 approaches"] P["PLAN\ndetailed checklist"] V["VALIDATE\nplan → contract\n(PVL loop)"] E["EXECUTE\nimplement\n(EVL loop)"] U["UPDATE PROCESS\ncapture + archive"] R -->|"go"| S S -->|"go"| I I -->|"go"| P P -->|"ENTER VALIDATE"| V V -->|"Gate: PASS"| E E -->|"gates green"| U style R fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style S fill:#0277BD,stroke:#01579B,color:#FFFFFF style I fill:#E65100,stroke:#BF360C,color:#FFFFFF style P fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style V fill:#558B2F,stroke:#33691E,color:#FFFFFF style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF style U fill:#00695C,stroke:#004D40,color:#FFFFFF ``` **En modo interactivo**, cada fase espera tu "go" antes de continuar — tú permaneces en el circuito en cada paso. **En modo piloto automático o /goal**, das la aprobación una vez al inicio y el sistema se dirige solo hasta el final. Solo se detiene en tres casos específicos que se indican a continuación. **VALIDATE** y la repetición de pruebas tras EXECUTE no son opcionales — son controles obligatorios que impiden que el trabajo deficiente llegue a producción — y se ejecutan automáticamente en ambos modos. --- ## La Revolución del Vibe Coding

"El lenguaje de programación más popular nuevo es el inglés."

— Andrej Karpathy

**El vibe coding cambió quién puede construir software. El desarrollo orientado al plan cambia lo que pueden entregar.**

63%

de los usuarios de vibe coding NO son desarrolladores

16.2M

desarrolladores ciudadanos en todo el mundo
(crecimiento interanual del 38%)

$4.7B

mercado de vibe coding
creciendo un 38% anual

25%

de las startups de YC W25 tenían bases de código con más del 95% generadas por IA
La mayoría de las herramientas te ayudan a iniciar un proyecto. Este kit te ayuda a **terminarlo** — con planes que tu equipo puede revisar, conocimiento que nunca queda obsoleto y controles de seguridad que detectan errores antes de que lleguen a producción. --- ## ¿Para Quién Es Esto?

"Lo importante no es quién lo escribió. Es lo que se entregó."

— Garry Tan, YC

🧑‍💼

CEO / Fundador

"Construye un SaaS con autenticación, facturación y una página de aterrizaje"

El agente investiga tu stack, escribe un plan de arquitectura que puedes revisar, implementa con pruebas y captura cada decisión para que tu cofundador técnico pueda auditarla más tarde.

📊

Product Manager

"Crea un panel que muestre MRR, churn y métricas de crecimiento"

Genera un SPEC estilo PRD, obtiene tu aprobación antes de escribir código, implementa según lo acordado y archiva el plan como historial de proyecto consultable.

🎨

Diseñador

"Replica este mockup de Figma con precisión de pixel"

El agente con conciencia de diseño analiza tu mockup, implementa componente a componente con tus tokens de diseño y lanza verificaciones de comparación visual.

⚙️

Ingeniero

"Refactoriza el módulo de autenticación para soportar RBAC sin tiempo de inactividad"

Investiga tu código de autenticación actual y cómo otras bases de código resolvieron RBAC, escribe un plan de migración que indica qué archivos podrían verse afectados y luego lo construye de forma segura con notas de reversión.
--- ## Cómo Se Compara | Funcionalidad | vibecode-pro-max-kit | Superpowers | GSD | gstack | |---------|---------------------|-------------|-----|--------| | Ciclo de vida orientado al plan | RIPER-5 completo (research → spec → innovate → plan → validate → execute → update) | Flujos de trabajo obligatorios | Corrección de deterioro de contexto | Parcial | | Restricciones por fase | Las herramientas del agente están restringidas por fase (investigación de solo lectura, sin escritura en innovate) | Restricciones basadas en habilidades | Separación de fases | Ninguna | | Bucles de control de calidad | **Dos** — PVL (verificar el plan) + EVL (volver a ejecutar pruebas de forma independiente) | Por habilidad | Ninguno automático | Ninguno | | Soporte multi-herramienta | 7 herramientas mediante estándares abiertos `AGENTS.md` + `SKILL.md` | Plugin de Claude Code | 14 entornos de ejecución | 1 herramienta | | Conocimiento que mejora solo | Conocimiento agrupado por tema, actualizado tras cada funcionalidad | Memoria de plugin | Estado persistente en disco | Manual | | Colaboración en equipo | Planes, especificaciones y archivos de revisión compartidos | Individual | Individual | Individual | | Sistema de habilidades | 33 autodescubiertas, asociadas por palabra clave en cada prompt | 86 habilidades componibles | Meta-prompting | 23 herramientas de rol | | Proyectos grandes multifase | Planes globales + bucle interno por fase con verificaciones de regresión | Tarea única | Tarea única | Tarea única | | Modo sin intervención | Piloto automático (3 carriles) + consentimiento permanente `/goal` | Manual | Manual | Manual | | Instalación | 30s `curl` + configuración enrutada automáticamente | Marketplace de plugins | npx one-liner | git clone | > **Sobre la amplitud de entornos:** GSD soporta 14 entornos de ejecución. Nosotros soportamos 7 en profundidad — con harnesses de agentes completos, descubrimiento de habilidades y hooks de ciclo de vida en cada plataforma. Amplitud frente a profundidad: tú decides. --- ## ⚡ Qué Lo Hace Diferente

🔒

Restricciones de herramientas por fase

Tu agente literalmente no puede escribir código durante la investigación. RESEARCH es de solo lectura, INNOVATE no tiene escritura, PLAN/VALIDATE solo escriben en process/. Límites de capacidad reales, no meras sugerencias.

🎯

El agente principal nunca toca el código

El coordinador enruta, supervisa y dirige los bucles — nunca edita archivos fuente ni ejecuta pruebas por sí mismo. Cada edición y cada ejecución de prueba ocurre dentro de un subagente dedicado. Sin trabajo oculto.

🔍

Descubrimiento automático de habilidades

Antes de gestionar cualquier solicitud, escanea 33 habilidades y asocia palabras clave. Di "añade soporte para webhooks" y vc-security + vc-scenario se incorporan automáticamente.

💾

Sobrevive a los reinicios de sesión

Planes, informes, documentación de conocimiento y aprendizajes viven en disco. El hook de inicio restaura los controles de aprobación tras un reinicio de sesión. No se pierde nada.

🛡️

Guardia de fase autovigilante

Cuando el agente está a punto de saltarse un paso obligatorio, se detiene solo: "PHASE JUMPING PREVENTED." Una barrera integrada contra los atajos.

🔄

Funciona con 7 herramientas de código IA

Dos estándares abiertos — AGENTS.md y SKILL.md — significan cero adaptadores, cero plugins. Empieza en Claude Code, cambia a Cursor, continúa en Codex.
--- ## 🧭 Cómo Funciona — El Coordinador Tu sesión principal es un **coordinador** (llamado el orquestador), no un trabajador. Hace cuatro cosas y nada más: ``` Tu solicitud → Step 0: Skill Discovery (scan 33 skills, match keywords, attach candidates) → Detectar intención (funcionalidad / error / pregunta / refactor / UI) + puntuar ambigüedad → Enrutar al agente correcto en una ventana de contexto nueva → Supervisar: cumplimiento de pasos, códigos de estado, gestión de bucles ```

🧑‍✈️

Delega, nunca implementa

Investigación → vc-research-agent. Plan → vc-plan-agent. Código → vc-execute-agent. El coordinador transfiere el contexto correcto y espera — nunca hace el trabajo real por sí mismo.

🚫

Sin ejecución oculta — nunca

En el momento en que existe un plan con una lista de verificación acordada, "ENTER EXECUTE MODE" siempre lanza vc-execute-agent. Incluso una corrección de una línea pasa por él. Las pruebas solo se ejecutan dentro de un vc-tester dedicado. Esto se mantiene independientemente del tamaño del cambio.

📨

Códigos de estado claros, no señales vagas

Cada subagente termina con uno de: DONE · DONE_WITH_CONCERNS · BLOCKED · NEEDS_CONTEXT. El coordinador nunca ignora un bloqueo y nunca reintenta el mismo enfoque bloqueado tres veces.

🔁

Gestiona los bucles de corrección

Los subagentes se ejecutan una vez, reportan un resultado y se detienen. Solo el coordinador los vuelve a lanzar. Gestiona tanto el bucle PVL (verificar-y-corregir el plan) como el EVL (verificar-y-corregir las pruebas) y mantiene todo el seguimiento.
```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD REQ["User request"] SD["Step 0: Skill Discovery\nscan 33 skills, match keywords"] INT{"Detect intent\n+ score ambiguity"} RES["vc-research-agent\n(feature / question)"] PLN["vc-plan-agent\n(after INNOVATE)"] VAL["vc-validate-agent\n(PVL loop)"] EXE["vc-execute-agent\n(EXECUTE)"] TST["vc-tester\n(EVL loop)"] UPD["vc-update-process-agent\n(closeout)"] MON["Monitor\nstatus codes · loop driving\nno inline execution ever"] REQ --> SD --> INT INT -->|"feature / research"| RES INT -->|"plan phase"| PLN INT -->|"validate phase"| VAL INT -->|"execute phase"| EXE EXE -.->|"EVL"| TST INT -->|"update phase"| UPD RES --> MON PLN --> MON VAL --> MON TST --> MON UPD --> MON style REQ fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style SD fill:#0277BD,stroke:#01579B,color:#FFFFFF style INT fill:#E65100,stroke:#BF360C,color:#FFFFFF style RES fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style PLN fill:#558B2F,stroke:#33691E,color:#FFFFFF style VAL fill:#558B2F,stroke:#33691E,color:#FFFFFF style EXE fill:#C62828,stroke:#B71C1C,color:#FFFFFF style TST fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style UPD fill:#00695C,stroke:#004D40,color:#FFFFFF style MON fill:#37474F,stroke:#263238,color:#FFFFFF ``` > **Por qué importa:** un agente que puede tanto decidir *como* editar en secreto encontrará la manera de saltarse el plan. Al separar el coordinador de los trabajadores (subagentes), el proceso se vuelve estructuralmente honesto — la única manera de escribir código es pasar por los pasos obligatorios. --- ## 📊 El ciclo de vida RIPER-5 | Fase | Qué ocurre | Agente | Usted dice | |-------|-------------|-------|---------| | 🔍 **RESEARCH** | Recopilación de información de solo lectura — código base y web. No modifica archivos. | `vc-research-agent` | *(automático en solicitudes de funcionalidades)* | | 📝 **SPEC** | Documento de requisitos de descubrimiento de producto — historias de usuario, criterios de aceptación, fuera de alcance — para **su revisión antes de cualquier diseño**. | `vc-spec-agent` | `go` / `ENTER SPEC MODE` | | 💡 **INNOVATE** | Exploración de 2-3 enfoques con sus ventajas y desventajas. Resumen de decisión (elegido + rechazados + por qué). | `vc-innovate-agent` | `go` | | 📋 **PLAN** | Redacción de la especificación detallada: puntos de contacto, contratos públicos, qué archivos puede tocar, evidencia de verificación, resumen de retomada. | `vc-plan-agent` | `go` | | ✅ **VALIDATE** | Convertir el plan en una lista de verificación acordada (puntos de control V1–V7). Veredicto: **PASS / CONDITIONAL / BLOCKED**. Ejecuta el bucle PVL. | `vc-validate-agent` | `ENTER VALIDATE MODE` | | ⚡ **EXECUTE** | Implementar *exactamente* el plan. Notas de progreso en el informe de fase, protocolo de desviación, autorrevisión. Luego el bucle EVL vuelve a ejecutar los puntos de control. | `vc-execute-agent` | `ENTER EXECUTE MODE` | | 🧠 **UPDATE PROCESS** | Registrar aprendizajes, actualizar contexto, archivar el plan, redactar el paquete de cierre. | `vc-update-process-agent` | *(recomendado después de trabajo no trivial)* | > 📝 **Por qué SPEC es su propia fase:** la mayoría de los sistemas pasan de "comprender" a "diseñar" directamente. Insertar un paso de SPEC de descubrimiento de producto significa que *usted* (o su gestor de producto) da el visto bueno a **qué** se va a construir — en historias de usuario e criterios de aceptación sencillos — *antes* de que el agente debata el **cómo**. Es el lugar más barato posible para detectar un malentendido. (Dentro del bucle interno de un programa de fases, SPEC se omite — la SPEC general rige todas las fases.) > > **La SPEC es la vara de medir.** Establece el comportamiento esperado en términos simples que se pueden revisar en un minuto. Cada fase posterior — Innovate, Plan, Validate, Execute — se remite a ella y formula la misma pregunta: *¿lo que estamos construyendo es realmente lo que usted pidió?* Cuando el trabajo empieza a desviarse, la SPEC es lo que lo detecta. ```mermaid flowchart TD U["You: what I really want
(plain words)"] --> S["📝 SPEC
expected behavior + acceptance
criteria — you approve"] S --> I["💡 INNOVATE"] S --> P["📋 PLAN"] S --> V["✅ VALIDATE"] S --> E["⚡ EXECUTE"] I -.->|"check back"| Q{"Is this what
you asked for?"} P -.->|"check back"| Q V -.->|"check back"| Q E -.->|"check back"| Q Q -->|yes| GO["keep building"] Q -->|no| S ```
### 💻 Sesiones de ejemplo ``` # 🆕 Feature request You: "add webhook support to the API" → Skill discovery surfaces: vc-scenario, vc-security → research-agent gathers context (read-only, can't touch code) → "go" → spec-agent writes requirements doc → you approve → "go" → innovate-agent compares approaches → decision summary → "go" → plan-agent writes the plan, listing which files it will touch → "ENTER VALIDATE MODE" → validate-agent gates the plan (PVL loop) → Gate: PASS → "ENTER EXECUTE MODE" → execute-agent implements → tester re-runs gates (EVL) → reviewer → git-manager → Closeout packet: what changed, what's verified, recommended next step ``` ``` # 🐛 Bug fix You: "login redirect is broken" → Routes to vc-debugger → gathers evidence FIRST → 2-3 competing hypotheses → Systematically eliminates each → root cause with proof chain → execute-agent implements the fix → EVL re-test → quality pipeline ``` ``` # ⏩ Fast mode You: "ENTER FAST MODE - add rate limiting middleware" → Compressed RESEARCH + SPEC + INNOVATE + PLAN + VALIDATE in one pass → Mandatory safety pause after VALIDATE → you review → "ENTER EXECUTE MODE" ``` ``` # 🤖 Autopilot (hands-free) You: "autopilot full: build a notifications system" → ONE consolidated clarification round → provisional /goal block (standing consent) → Drives the full RIPER-5 sequence autonomously, pausing only on hard stops ``` ``` # 🏗️ Large program You: "build a full testing platform" → Umbrella plan + phase plans in a feature folder → Each phase inner loop: research → innovate → plan → PVL → execute → EVL → update → Progress survives context compaction — durable reports on disk ``` --- ## 🎯 Clarificación de intención Antes de enrutar, el agente principal puntúa la ambigüedad de su solicitud en **4 señales binarias (0–4)** y elige un nivel. Hace preguntas *solo cuando realmente cambiarían lo que va a hacer.* | Nivel | Cuándo | Comportamiento | |---|---|---| | **Nivel 0** — enrutamiento automático silencioso | Puntuación 0–1, o usted dijo "go" / "just do it", o retomando un plan | Enruta inmediatamente, sin preguntas | | **Nivel 1** — resumen en línea | Puntuación 2 | Expone su comprensión y la ruta elegida en una línea, y continúa | | **Nivel 2** — preguntas | Puntuación 3+ | Formula preguntas de opción múltiple enfocadas antes de enrutar | > 🧠 **Dos rondas como máximo.** Si tras el Nivel 2 persiste la ambigüedad, formula una última pregunta directa y después recurre de manera predeterminada a la investigación con el alcance más acotado posible. Nunca repite la clarificación indefinidamente. Tras RESEARCH, vuelve a verificar la intención — si la investigación muestra que la solicitud era distinta a lo supuesto, la vuelve a presentar; si se confirma, continúa sin preguntar de nuevo. ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD REQ["User request"] SCORE{"ambiguity score\n0–4 binary signals"} AUTO["Auto-skip conditions\n(go / continue / mid-phase\n/ trivial / explicit mode\n/ resuming plan / pure info)"] T0["Tier 0\nsilent auto-route\n(score 0–1 OR auto-skip)"] T1["Tier 1\ninline summary\n(score 2)"] T2["Tier 2\nask focused questions\n(score 3+)"] ROUTE["Route to matching agent\n(research / plan / execute / …)"] STILL{"still unclear\nafter Tier 2?"} FINAL["One final plain question\n(max 2 clarification rounds)"] NARROW["Default: vc-research-agent\nnarrowest reasonable scope"] REQ --> AUTO AUTO -->|"auto-skip matches"| T0 AUTO -->|"no auto-skip"| SCORE SCORE -->|"0–1"| T0 SCORE -->|"2"| T1 SCORE -->|"3+"| T2 T0 --> ROUTE T1 --> ROUTE T2 --> STILL STILL -->|"resolved"| ROUTE STILL -->|"still unclear"| FINAL --> NARROW style REQ fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style AUTO fill:#0277BD,stroke:#01579B,color:#FFFFFF style SCORE fill:#E65100,stroke:#BF360C,color:#FFFFFF style T0 fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style T1 fill:#558B2F,stroke:#33691E,color:#FFFFFF style T2 fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style ROUTE fill:#C62828,stroke:#B71C1C,color:#FFFFFF style STILL fill:#F57F17,stroke:#F9A825,color:#000000 style FINAL fill:#AD1457,stroke:#880E4F,color:#FFFFFF style NARROW fill:#00695C,stroke:#004D40,color:#FFFFFF ``` --- ## ✅ Los dos bucles de calidad — PVL + EVL La mayoría de los sistemas verifican *una vez*, si es que lo hacen. Este envuelve EXECUTE en **dos bucles independientes** — uno antes de escribir código, otro después. ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '15px', 'lineColor': '#8888AA'}} }%% flowchart TD PLAN["📋 PLAN written"] PVL{"✅ PVL\nValidate the plan\nV1–V7 gates"} PASS["Gate: PASS"] SUPP["📝 plan-agent supplements\n(addresses gaps)"] EXEC["⚡ EXECUTE\nimplement the plan"] EVL{"🧪 EVL\ntester re-runs the\nvalidate-contract gates"} FIX["⚡ execute-agent\nsupplement (fix gate)"] DONE["🧠 UPDATE PROCESS"] PLAN --> PVL PVL -->|"CONDITIONAL / BLOCKED"| SUPP SUPP -->|"re-run from V1"| PVL PVL -->|"PASS"| PASS PASS -->|"ENTER EXECUTE"| EXEC EXEC --> EVL EVL -->|"gate fails"| FIX FIX -->|"re-run"| EVL EVL -->|"all gates green"| DONE style PLAN fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style PVL fill:#558B2F,stroke:#33691E,color:#FFFFFF style PASS fill:#00695C,stroke:#004D40,color:#FFFFFF style SUPP fill:#E65100,stroke:#BF360C,color:#FFFFFF style EXEC fill:#C62828,stroke:#B71C1C,color:#FFFFFF style EVL fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style FIX fill:#AD1457,stroke:#880E4F,color:#FFFFFF style DONE fill:#00695C,stroke:#004D40,color:#FFFFFF ```

📋 PVL — Plan-Validate-Fix

Antes de EXECUTE, vc-validate-agent somete el plan a puntos de control V1–V7 — distribuyendo el trabajo entre varios agentes para cubrir infraestructura, cobertura de pruebas, cambios disruptivos, seguridad y viabilidad por sección. Un CONDITIONAL o BLOCKED en el primer pase nunca es el final — regresa a vc-plan-agent para actualizar el plan y luego vuelve a verificar desde V1.

Gestionado por vc-autoresearch (dominio: plan) — un bucle de búsqueda y corrección de brechas. Límite de 10 ciclos. Detección de estancamiento. Solo Gate: PASS (o un CONDITIONAL que usted acepte explícitamente) desbloquea EXECUTE.

🧪 EVL — Execute-Validate-Fix

Cuando EXECUTE informa que ha terminado — incluso cuando asegura que todos los puntos de control están en verde — el agente principal siempre lanza vc-tester para volver a ejecutar de forma independiente los comandos de prueba exactos de la lista acordada. Un punto de control fallido dirige a una corrección acotada de vc-execute-agent, y luego vuelve a probarse.

Gestionado por vc-autoresearch (dominio: tests). Límite de 10 ciclos. El bucle interno "iterar hasta verde" del propio execute-agent nunca sustituye esta confirmación independiente.
> 💎 **La escala de veredictos:** **PASS** → continuar · **CONDITIONAL** → brechas subsanables; el bucle actúa (o usted las acepta de manera formal) · **BLOCKED** → un problema más profundo; vuelve a PLAN (en modo autopiloto: la brecha pasa a una lista de pendientes y la ejecución continúa). ### 🔁 vc-autoresearch — Motor de bucle compartido Tanto PVL como EVL utilizan la misma capa de seguimiento: **`vc-autoresearch`** — un bucle de buscar brechas → corregir → repetir. El agente principal conduce el bucle — es dueño del contador de rondas, los informes por ronda, el registro TSV y las verificaciones de estancamiento, límite y regresión. Los agentes de trabajo son de tipo "lanzar y olvidar": devuelven un resultado y se detienen. Ningún agente se relanza a sí mismo ni lanza otro agente de fase. El mismo motor puede funcionar de forma independiente: "reforzar esta especificación", "corregir todos los errores de lint", "mejorar la cobertura de pruebas", "mejorar esta documentación" — cualquier tarea repetida de búsqueda y corrección de brechas en 6 dominios (spec · tests · ux · docs · plan · errors). ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD START["Start loop\n(orchestrator init results.tsv\nheader + baseline row)"] FIND["Find gaps\n(validate-agent / tester\nreturns gap list)"] RPT["Write iteration report\n{slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md"] TSV["Append results.tsv row\n(cycle N, gap count)"] FIX["Fix gaps\n(plan-agent supplement\nOR execute-agent supplement)"] CHK["Guard checks\nplateau? cap hit? regression?"] RECHECK["Re-check\n(re-run validate / tester)"] SUCC["SUCCESS\nall-clear 2 consecutive rounds"] HALT["HALT\nplateau / 10-cycle cap / regression"] START --> FIND --> RPT --> TSV --> FIX --> CHK CHK -->|"safe to continue"| RECHECK RECHECK --> FIND CHK -->|"plateau / cap / regression"| HALT FIND -->|"no gaps found (×2)"| SUCC style START fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style FIND fill:#E65100,stroke:#BF360C,color:#FFFFFF style RPT fill:#558B2F,stroke:#33691E,color:#FFFFFF style TSV fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style FIX fill:#C62828,stroke:#B71C1C,color:#FFFFFF style CHK fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style RECHECK fill:#0277BD,stroke:#01579B,color:#FFFFFF style SUCC fill:#00695C,stroke:#004D40,color:#FFFFFF style HALT fill:#B71C1C,stroke:#7F0000,color:#FFFFFF ``` | Modo | Qué hace | Se detiene cuando | |---|---|---| | `vc-autoresearch` (núcleo) | busca brechas → corrige → repite | no se encuentran brechas O se alcanza el objetivo de la métrica | | `vc-autoresearch:probe` | 8 personas interrogan el corpus hasta la saturación | no hay nuevas restricciones durante 3 rondas | | `vc-autoresearch:reason` | debate adversarial con jueces ciegos | los jueces convergen o se alcanza el límite de iteraciones | | `vc-autoresearch:evals` | analiza los resultados TSV — tendencias, estancamientos, recomendaciones | solo análisis | **Condiciones de parada:** SUCCESS (todo despejado dos rondas seguidas) · HALT_PLATEAU (sin progreso durante 3 rondas) · HALT_CAP (límite estricto de 10 rondas) · HALT_REGRESSION (una verificación que pasaba ahora falla). --- ## 👥 Comparación de estrategias y política de modelos En **cada transición de fase**, el agente principal invoca `vc-agent-strategy-compare` para recomendar *cómo* ejecutar la siguiente fase — con estimaciones de costo. | Estrategia | Cuándo | Coordinación | |---|---|---| | **Secuencial** | El trabajo depende de la salida anterior | Un agente a la vez | | **Subagentes en paralelo** | Dimensiones independientes, sin seguimiento posterior | Ninguna — el agente principal recoge y combina los resultados | | **Flujo de trabajo** | División predecible del trabajo a través de una lista | Pasos programados | | **Equipo de agentes** | Los agentes deben comunicarse entre sí durante la ejecución (p. ej., cada uno toca archivos separados en 3+ planes de fase) | TeamCreate + lista de tareas compartida + SendMessage | ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD SS["vc-agent-strategy-compare\n(every phase transition)"] SC{"signal score\n0–7"} SEQ["Sequential\none agent at a time\n(output feeds next)"] PAR["Parallel subagents\nfire-and-forget\n(independent dimensions)"] WF["Workflow\nscripted steps\nacross a list"] TEAM["Agent team\nTeamCreate + TaskCreate\n+ SendMessage\n(must coordinate mid-run)"] MC{"which phase?"} OPUS["🔴 opus\n(EXECUTE only)"] SONNET["🔵 sonnet\n(every other phase)"] SS --> SC SC -->|"low / dependent"| SEQ SC -->|"mid / independent"| PAR SC -->|"predictable split"| WF SC -->|"high / must coordinate\nor 3+ phase plans"| TEAM SS --> MC MC -->|"EXECUTE / fast-mode\nquick-fix (real code)"| OPUS MC -->|"Research / Spec\nInnovate / Plan\nValidate / Update\nall reviewers"| SONNET style SS fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style SC fill:#E65100,stroke:#BF360C,color:#FFFFFF style SEQ fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style PAR fill:#558B2F,stroke:#33691E,color:#FFFFFF style WF fill:#00695C,stroke:#004D40,color:#FFFFFF style TEAM fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style MC fill:#0277BD,stroke:#01579B,color:#FFFFFF style OPUS fill:#C62828,stroke:#B71C1C,color:#FFFFFF style SONNET fill:#37474F,stroke:#263238,color:#FFFFFF ``` > ⚠️ **"Equipo de agentes" significa la maquinaria real** — compañeros de equipo con nombre, una lista de tareas compartida y mensajería entre agentes — *no* simples agentes en paralelo llamados "equipo". Es **obligatorio** (no opcional) para crear 3+ planes de fase y para ediciones de múltiples archivos en las que los agentes deben mantenerse cada uno en sus propios archivos. Solo un equipo verdadero puede comunicarse mientras trabaja. ### 🧮 Política de selección de modelos | Fase | Modelo | Por qué | |---|---|---| | **EXECUTE** (+ fast-mode, quick-fix con código real) | 🔴 **opus** | Ediciones reales de código fuente, compilaciones, migraciones | | Research · Spec · Innovate · Plan · Validate · Update · todos los revisores/investigadores | 🔵 **sonnet** | Planificación y análisis — más económico, completamente capaz | > Cuando el trabajo se distribuye entre varios agentes, solo el agente de *codificación* usa opus. Cada revisor, investigador, validador y planificador usa sonnet. El agente principal indica el modelo cada vez que lanza un agente de trabajo. --- ## 🤖 Modo Autopiloto — RIPER-5 sin intervención Diga **`autopilot [tarea]`** (o `run autopilot`, `autonomous mode`, `ENTER AUTOPILOT MODE`) y el agente ejecuta *toda* la secuencia RIPER-5 restante con **una** ronda de clarificación inicial — y luego no hay más pausas hasta que termina. **Se activa en cualquier punto:** el autopiloto puede iniciarse al comienzo de una sesión *o* en cualquier momento durante la misma. Al activarse, el agente principal lee los archivos guardados en disco para determinar en qué fase de RIPER-5 se encuentra ya, y desde allí continúa y conduce el resto de manera autónoma. | Estado en disco | Fase de entrada | |---|---| | Sin archivo SPEC | Comenzar en RESEARCH | | Archivo SPEC presente | Saltar a post-SPEC (INNOVATE) | | Archivo de plan presente | Saltar a post-PLAN (VALIDATE) | | Contrato de validación con PASS/CONDITIONAL | Saltar a EXECUTE | ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD TRG["autopilot trigger phrase\n(anywhere in session)"] DISK["Read saved files on disk\ndetect current phase"] CLR["ONE consolidated\nclarification round"] GOAL["Emit provisional /goal block\n(≤4000 chars, copy-pasteable\nstanding EXECUTE consent)"] ACT["AUTOPILOT_ACTIVATED\nautonomous run begins"] PHASES["Drive remaining phases\nRESEARCH → … → UPDATE PROCESS\n(no user pauses)"] HS1["🛑 Irreversible / outward action\nnot pre-approved"] HS2["⛔ Cascade BLOCKED\n(several phases stuck)"] HS3["💸 Live-provider billed probe\n(double opt-in required)"] DONE["Run complete\nautopilot deactivates"] TRG --> DISK --> CLR --> GOAL --> ACT --> PHASES PHASES -->|"hard stop 1"| HS1 PHASES -->|"hard stop 2"| HS2 PHASES -->|"hard stop 3"| HS3 PHASES -->|"all phases done"| DONE style TRG fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style DISK fill:#0277BD,stroke:#01579B,color:#FFFFFF style CLR fill:#E65100,stroke:#BF360C,color:#FFFFFF style GOAL fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style ACT fill:#558B2F,stroke:#33691E,color:#FFFFFF style PHASES fill:#C62828,stroke:#B71C1C,color:#FFFFFF style HS1 fill:#B71C1C,stroke:#7F0000,color:#FFFFFF style HS2 fill:#B71C1C,stroke:#7F0000,color:#FFFFFF style HS3 fill:#B71C1C,stroke:#7F0000,color:#FFFFFF style DONE fill:#00695C,stroke:#004D40,color:#FFFFFF ``` ``` You: "autopilot full: add team invitations with email + role management" → Reads saved files → detects current phase → enters there → ONE consolidated clarification round (scope, hard stops, autonomy boundaries, first-phase strategy) → Provisional /goal block emitted (≤4000 chars, copy-pasteable, standing EXECUTE consent) → AUTOPILOT_ACTIVATED → drives remaining phases on its own → Stops ONLY for hard stops ``` ### Tres modos — adapte el nivel de formalidad al riesgo | Modo | Activación | Flujo | |---|---|---| | 🟢 **quick** | `autopilot quick: [tarea]` | Exploración → edición → verificación acotada. Sin plan, sin contrato, sin EVL. | | 🟡 **fast** | `autopilot fast: [tarea]` | R→S→I→P→V comprimidos → EXECUTE + EVL. | | 🔴 **full** | `autopilot [tarea]` / `autopilot full:` | RIPER-5 completo (predeterminado). | ### 🌙 Sin intervención: una frase, construido mientras usted duerme Diga `autopilot full: [tarea]` — o pegue un bloque `/goal` — y todo lo siguiente ocurre con **cero intervención humana**: - **Bucle de verificación y corrección del plan** — encuentra brechas en el plan, las corrige y vuelve a verificar. Hasta 10 rondas por sí solo. - **Bucle de construcción, prueba y corrección** — escribe código, ejecuta pruebas, corrige fallos, vuelve a ejecutar. Hasta 10 rondas por sí solo. Nunca confía en su propio "todo en verde" — un verificador independiente (`vc-tester`) vuelve a ejecutar todas las pruebas de forma autónoma para confirmar. - **Avance de fase en fase** — pasa de investigación a plan, de plan a código y de código a finalizado sin esperarle. - **Retoma tras un reinicio de memoria** — los planes, informes y el progreso se guardan como archivos en disco. Tras la compactación (cuando la memoria a corto plazo de la IA se borra), la siguiente sesión lee esos archivos y continúa exactamente donde se quedó. - **¿Funcionalidad bloqueada? La pospone y sigue adelante** — si una fase no puede resolverse, el agente escribe una nota en la lista de pendientes y avanza a la siguiente funcionalidad. Puede ejecutar muchas funcionalidades en paralelo sin que un bloqueador lo detenga todo. - **Equipos de agentes para funcionalidades en paralelo** — varios agentes pueden construir funcionalidades separadas al mismo tiempo, cada uno limitado a sus propios archivos para que nunca colisionen. Una funcionalidad bloqueada queda apartada, no bloquea al resto. ### Las paradas de emergencia siempre se muestran (incluso en autopiloto) Estas son las **únicas tres veces que se detiene y le pregunta**: - 🛑 Cualquier cosa que no pueda deshacer, o que alcance el mundo exterior y no haya sido preaprobada (publicar en producción, enviar mensajes reales, cobrar dinero) - ⛔ Varias fases seguidas se bloquean sin progreso — un callejón sin salida real que merece su atención - 💸 Una prueba que gastaría dinero real en un servicio externo de pago — pregunta antes de ejecutarla --- ### 🎯 /goal — el token de ejecución autónoma **Obligatorio, no decorativo:** después de que cada fase VALIDATE se completa, el agente principal *debe* emitir un bloque `/goal` listo para copiar y pegar antes de que comience EXECUTE. Se trata de un archivo de traspaso obligatorio — no un comentario opcional. **Restricciones de formato:** | Tipo de bloque | Campos obligatorios | Límite estricto | |---|---|---| | Bloque post-VALIDATE | SESSION GOAL · Charter+umbrella plan · Autonomy · Hard stop conditions · Next phase · Validate contract · Execute start | ≤ 4000 chars | | Bloque provisional (autopiloto) | SESSION GOAL · ENTRY PHASE · REMAINING PHASES · CLARIFICATIONS LOCKED · EXECUTE CONSENT · DECISION POLICY · HARD STOPS · TEST GATES · START (+ LANE opcional) | ≤ 4000 chars | El comando `/goal` rechaza bloques de más de 4000 caracteres. Manténgalo breve — use los campos obligatorios como estructura, no como un ensayo en prosa. **Modo /goal independiente:** pegue un bloque `/goal` en una nueva sesión y la ejecución se retoma desde la fase indicada en `START`. Las clarificaciones y las reglas de decisión ya están establecidas — no se inicia una nueva ronda de clarificación. Con un `/goal` activo, el agente decide por sí mismo en cada paso reversible, envía los elementos BLOCKED a una lista de pendientes y redacta sus propios informes — pero **la delegación a agentes de trabajo sigue siendo obligatoria.** El modo autopiloto elimina *solo las pausas de aprobación*, nunca la regla de no-ejecución-en-línea. Validado por `validate-autopilot-goal-block.mjs`. --- ## 🔬 Sondeos de viabilidad + La red de seguridad de validadores ### 🔬 Sondeos de viabilidad — pruebe el supuesto antes de construir sobre él Cuando SPEC, INNOVATE o VALIDATE encuentra un supuesto clave que no puede confirmar solo con lectura, emite `VC-FEASIBILITY-PROBE-NEEDED` y se detiene. El agente principal lanza `vc-debugger` para ejecutar una prueba real y redactar un **VERDICT**: | Veredicto | Significado | |---|---| | ✅ **VIABLE** | El supuesto se cumple — el diseño puede basarse en él | | ❌ **NOT-VIABLE** | El supuesto es falso — ese enfoque queda descartado | | ❓ **INCONCLUSIVE** | No se pudo probar — se registra como una brecha conocida | Cada veredicto viene acompañado de una nota de diseño de 3 partes: **qué permite el resultado · qué descarta · qué sigue siendo incierto** — introducida tal cual en la fase pausada. Los sondeos tienen una **clasificación de costo** (`cheap-local` / `needs-container` / `needs-live-provider` → doble confirmación / `needs-browser` / `needs-cf`) para que un sondeo facturado o con recursos compartidos nunca se ejecute de forma silenciosa. ### 🛡️ 36 validadores — corrección mecánica, no de opinión El kit incluye **36 scripts validadores** que convierten "¿siguió el agente las reglas?" en un resultado claro de aprobado/reprobado. Se ejecutan después de cualquier fase que toque los archivos del sistema, y como puntos de control obligatorios en UPDATE PROCESS: | Familia de validadores | Verifica | |---|---| | `vc-audit-vc` | Paridad de agentes (Claude/Codex), registro de habilidades, portabilidad del kit, metadatos de agentes | | `vc-audit-context` | Enrutamiento de contexto, metadatos de descubrimiento, palabras clave de habilidades | | `vc-audit-plans` | Inventario de planes, estado general, completitud de fases, informes de fases, notas de pendientes | | 14 validadores de comportamiento del sistema VC | Cada uno tiene un par de ejemplos de aprobado/reprobado — salida de comparación de estrategias, cierre, clarificación de intención, veredicto de viabilidad, registro de autoresearch, y más | --- ## 🛡️ Sistemas de seguridad integrados Estas no son pautas — son **reglas estrictas** incorporadas en cada agente.

📝

Notas de progreso, no pausas a mitad de la ejecución

Durante la codificación, el agente escribe notas de progreso en el archivo de informe de fase mientras trabaja. Sin pausas a mitad de la ejecución, sin mensajes de "¿continuar o volver?". Si encuentra un problema que requiere un cambio de plan, se detiene y regresa a PLAN. De lo contrario, sigue adelante.

🚫

Nunca desviarse en silencio

Si durante la codificación surge un problema que requiere un cambio de plan, el agente se detiene de inmediato, lo explica y regresa a PLAN. Sin improvisación silenciosa.

🔐

Protección de privacidad mediante gancho

El agente tiene bloqueada la lectura de archivos .env, credenciales, claves SSH y archivos .pem sin aprobación explícita.

⚠️

Paquetes de evidencia para tareas de alto riesgo

Para cambios de autenticación, facturación, migraciones de esquema o modificaciones de API pública, el sistema exige un paquete de evidencia de 5 archivos antes de considerar el trabajo "terminado" — siempre manual, nunca omitido automáticamente.

📨

Disciplina de códigos de estado

Los agentes de trabajo deben cerrar con DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT. Los bloqueos nunca se ignoran; las dudas de corrección se convierten en elementos de acción.

📊

Cierre y puntuación de deriva

Después de la codificación, un paquete de cierre puntúa la urgencia: LOW (toque ligero) → MEDIUM (significativo) → HIGH (archivos del sistema o del protocolo modificados), y recomienda el siguiente paso seguro.
--- ## 🔍 Inteligencia pre-implementación Antes de escribir una sola línea de código, tres habilidades especializadas pueden detectar problemas:

🎭

Debate de 5 personas — vc-predict

Arquitecto, Seguridad, Rendimiento, UX y Abogado del Diablo debaten su plan. Produce un veredicto GO / CAUTION / STOP antes de escribir una línea.

🎲

Casos extremos en 12 dimensiones — vc-scenario

Descompone una funcionalidad en 12 dimensiones (tipos de usuario, extremos de entrada, temporización, escala, estado, entorno, errores, autenticación, datos, integraciones, cumplimiento, lógica de negocio). La salida sirve también como especificaciones de prueba.

🔐

Auditoría STRIDE + OWASP — vc-security

Auditoría de seguridad con doble metodología que incluye auditoría de dependencias, detección de secretos y un modo de corrección automática que ordena por gravedad y corrige primero los elementos Críticos con protecciones contra regresiones.

🔬

Depuración basada en evidencia — vc-debugger

Recopila evidencia → formula 2-3 hipótesis en competencia → prueba cada una → documenta el proceso de eliminación. Nunca adivina — demuestra.
--- ## ✅ Línea de calidad — integrada en la ejecución **Pruebas primero, código después.** La lista de verificación acordada (redactada antes de tocar cualquier código) define las pruebas exactas que deben pasar. El execute-agent escribe código hasta que esas pruebas queden en verde. Luego un verificador independiente — `vc-tester` — vuelve a ejecutar todas las pruebas por su cuenta para confirmar. El propio "todo en verde" del execute-agent nunca se acepta sin más. Al final, el revisor comprueba que todo el proyecto sigue funcionando en conjunto, no solo la nueva pieza. El execute-agent no se limita a escribir código y declarar que ha terminado. Avanza automáticamente a través de una **línea de calidad**:
```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '16px', 'lineColor': '#8888AA'}} }%% flowchart TD E["⚡ Execute-Agent\nImplements the plan"] SR["🔎 Self-Review\nLine-by-line check\nagainst plan"] T["🧪 Tester (EVL)\nDiff-aware — re-runs\nthe contract gates"] CR["🔍 Code Reviewer\nEdge case scout\n+ adversarial review"] CS["✨ Code Simplifier\nClarity refactoring"] GM["📦 Git Manager\nLogical commit splitting\nfrom touched_files"] E --> SR --> T --> CR --> CS --> GM style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF style SR fill:#AD1457,stroke:#880E4F,color:#FFFFFF style T fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style CR fill:#283593,stroke:#1A237E,color:#FFFFFF style CS fill:#00695C,stroke:#004D40,color:#FFFFFF style GM fill:#37474F,stroke:#263238,color:#FFFFFF ``` | Paso | Qué hace | |---|---| | 🔎 **Autorrevisión** | Verifica cada elemento de la lista frente al plan, registra cualquier desviación | | 🧪 **Tester (EVL)** | Vuelve a ejecutar las pruebas de la lista acordada de forma independiente; mapea archivos modificados → archivos de prueba, escala a la suite completa cuando >70% está mapeado | | 🔍 **Revisor de código** | Envía un explorador de casos extremos *antes* de la revisión; comprueba consultas N+1, rutas de autenticación, filtraciones de datos | | ✨ **Simplificador** | Limpia el código para mayor claridad después de la revisión — sin cambios de comportamiento | | 📦 **Gestor de Git** | Recibe `touched_files`, divide en commits convencionales lógicos, rechaza archivos desconocidos | --- ## 📋 El Ciclo de Vida de un Plan Toda funcionalidad no trivial sigue un **ciclo de vida de plan** — una especificación escrita que se crea, se revisa, se implementa y luego se archiva como historial permanente del proyecto.
```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '16px', 'lineColor': '#8888AA'}} }%% flowchart TD A["🆕 Feature Request"] B["📝 Plan Created\nin active/{slug}_{date}/"] C{"👀 User Reviews\nthe Plan"} D["✅ VALIDATE\n(PVL gates)"] E["⚡ Execute + EVL"] F["📦 Plan Archived\nto completed/"] G["🧠 Learnings →\nall-context.md"] H["🔄 Next Feature\nStarts Smarter"] A --> B --> C C -->|"✏️ Needs Changes"| B C -->|"✅ Approved"| D --> E --> F --> G --> H H -.->|"context compounds"| A style A fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style B fill:#E65100,stroke:#BF360C,color:#FFFFFF style C fill:#F57F17,stroke:#F9A825,color:#000000 style D fill:#558B2F,stroke:#33691E,color:#FFFFFF style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF style F fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style G fill:#00695C,stroke:#004D40,color:#FFFFFF style H fill:#1565C0,stroke:#0D47A1,color:#FFFFFF ``` > 💡 Seis meses después, cuando alguien pregunte *"¿por qué construimos la autenticación de esta manera?"*, la respuesta estará en `completed/`. No perdida en un hilo de Slack. **Dónde viven los planes — convención de carpeta de tarea:** ``` process/ ├── general-plans/ │ ├── active/ │ │ └── webhooks_28-05-26/ # 📋 Carpeta de tarea: plan + informes/referencias colocalocadas │ │ └── webhooks_PLAN_28-05-26.md │ ├── completed/ # ✅ Archivado (historial consultable) │ └── backlog/ # 📌 Trabajo diferido └── features/ └── billing/ # 🏷️ Específico por funcionalidad (5+ artefactos) ├── active/{slug}_{date}/ ├── completed/ └── backlog/ ``` ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD PC["vc-plan-agent creates task folder\nprocess/general-plans/active/{slug}_{date}/\nOR features/{feature}/active/{slug}_{date}/"] PLAN["{slug}_PLAN_{dd-mm-yy}.md\n— plan file\n— Validate Contract appended here"] REF["{slug}_REF_{dd-mm-yy}.md\n— optional references"] RPT["{slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md\n— per PVL/EVL cycle report"] TSV["results.tsv\n— rolling loop log\n(header + baseline + cycle rows)"] PP["PHASE PROGRAM extras"] UMB["umbrella_PLAN_{dd-mm-yy}.md\n— Program Goal Charter\n— /goal block"] PHN["phase-N_PLAN_{dd-mm-yy}.md\n— one file per phase"] REG["phase-blast-radius-registry.md\n— per-phase file ownership"] PC --> PLAN PC --> REF PC --> RPT PC --> TSV PC --> PP PP --> UMB PP --> PHN PP --> REG style PC fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style PLAN fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style REF fill:#558B2F,stroke:#33691E,color:#FFFFFF style RPT fill:#E65100,stroke:#BF360C,color:#FFFFFF style TSV fill:#C62828,stroke:#B71C1C,color:#FFFFFF style PP fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style UMB fill:#00695C,stroke:#004D40,color:#FFFFFF style PHN fill:#00695C,stroke:#004D40,color:#FFFFFF style REG fill:#37474F,stroke:#263238,color:#FFFFFF ``` > Cada plan contiene: 📍 **puntos de contacto** (archivos creados/modificados) · 📜 **contratos públicos** · 💥 **qué archivos puede tocar** (qué podría romperse, qué hay que probar) · ✅ **evidencia de verificación** · 🔄 **entrega para retomar**. `vc-plan-discovery` encuentra el plan correcto para retomar; el hook `post-write-plan-check` verifica la estructura del plan en cada escritura. --- ## 🏗️ Programas de Fases — Proyectos Grandes Que No Se Desmoronan Las funcionalidades normales usan un solo plan. **Los proyectos grandes de múltiples fases** usan un programa de fases: un plan paraguas más planes por fase, cada uno ejecutando un **bucle interno de 7 pasos** con sus propios puntos de control y un informe guardado.
```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD UP["🎯 Umbrella Plan\nProgram Goal Charter\n(north star · done · scope tiers)"] P1["📋 Phase 1"] P2["📋 Phase 2 ..."] subgraph LOOP["🔁 Per-phase inner loop (skips SPEC)"] direction TB R["🔍 Research"] I["💡 Innovate"] PL["📋 Plan-supplement"] PVL["✅ PVL"] EX["⚡ Execute"] EVL["🧪 EVL"] UPD["🧠 Update"] R --> I --> PL --> PVL --> EX --> EVL --> UPD end UP --> P1 --> LOOP LOOP -.->|"learnings feed\nnext phase"| P2 style UP fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style P1 fill:#E65100,stroke:#BF360C,color:#FFFFFF style P2 fill:#E65100,stroke:#BF360C,color:#FFFFFF style R fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style I fill:#E65100,stroke:#BF360C,color:#FFFFFF style PL fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style PVL fill:#558B2F,stroke:#33691E,color:#FFFFFF style EX fill:#C62828,stroke:#B71C1C,color:#FFFFFF style EVL fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style UPD fill:#00695C,stroke:#004D40,color:#FFFFFF ``` | | Característica | Por qué importa | |---|---|---| | 🔄 | **Nueva investigación en cada fase** | Verifica la deriva del código, lee los últimos informes y actualiza los supuestos | | ✅ | **Puntos de control por fase** | Una fase no está terminada hasta que la evidencia lo demuestre. Estado honesto: `PLANNED → CODE DONE → TESTING → VERIFIED` o `BLOCKED` | | 📄 | **Informes guardados** | Cada fase escribe resultados en disco — el progreso sobrevive a un reinicio de memoria | | 🧠 | **Los aprendizajes se transmiten hacia adelante** | Los hallazgos de la Fase 1 actualizan el plan de la Fase 2 antes de comenzar a programar | | 🏗️ | **Base vs expansión** | Separa explícitamente "demostrar la arquitectura" de "implementar todo" | | 🚧 | **Gestión honesta de bloqueos** | Las fases bloqueadas permanecen en `BLOCKED` con evidencia. No se finge un estado verde |
### 🔀 El programa se remodela a medida que aprende El plan que escribes al inicio es un mapa aproximado, no un contrato fijo. A medida que el programa avanza, se ajusta — así no tienes que predecir cada paso de antemano. **Puede agregar una nueva fase en medio de una ejecución.** Mientras trabaja, el agente puede descubrir un paso que falta — algo que debe ocurrir antes de que la siguiente fase pueda continuar. Cuando eso sucede, inserta una nueva fase justo ahí, renumera el resto y sigue adelante. Sin intervención humana. (Señal interna: `MID_PROGRAM_PLAN_CREATED` — el nuevo plan se escribe en disco y se agrega al registro automáticamente.) **Puede reordenar las fases.** La investigación a veces muestra que el orden planificado es incorrecto — por ejemplo, la Fase 3 depende de algo que solo produce la Fase 4. El agente reorganiza las fases restantes y registra el motivo. (Señal interna: `PHASE_RESTRUCTURE_NOTICE` — guardada en el informe de fase como rastro de auditoría, no como bloqueante.) **Actualiza el plan de cada fase justo antes de programarla.** Antes de que comience a programar cualquier fase, una breve revisión de investigación examina lo que el programa ha aprendido hasta el momento. Luego actualiza la lista de verificación de esa fase con los nuevos hallazgos. Este paso se llama **plan-supplement**. Los planes nunca se congelan — absorben hechos recientes de las fases anteriores. **Omite el trabajo que aún no puede comenzar.** Si una fase depende de algo que todavía no está listo — un servicio aún no construido, una decisión aún no tomada — el agente marca esa fase como bloqueada por dependencia, la deja de lado y pasa a la siguiente. El programa completo no se detiene porque una fase está esperando. **Sabe cuándo detenerse y preguntar.** Una sola fase bloqueada simplemente se deja en el backlog y el programa continúa. Pero si varias fases consecutivas chocan contra un muro sin progreso, el agente lo trata como un callejón sin salida real — una **parada en cascada** — y hace una pausa para mostrarte lo que ocurrió. Una fase bloqueada es normal. Varias seguidas señalan que algo estructural está mal. **Mantiene un marcador en tiempo real.** Cada programa tiene una sección de estado de una página en el plan paraguas que muestra cuál es la fase actual, si está terminada y dónde vive el informe. Cualquiera — o el propio agente tras un reinicio de memoria — puede leerlo y saber exactamente el estado de la situación. También mantiene un registro de archivos sencillo para que dos fases que trabajen al mismo tiempo nunca editen los mismos archivos. **Una gran verificación final.** Al final de todo el programa, el agente ejecuta una prueba de extremo a extremo que confirma que todo el proyecto sigue funcionando en conjunto — no solo cada parte por separado. Los puntos de control de cada fase demuestran que cada parte funciona; esta verificación final demuestra que las partes funcionan como un todo. --- ### 🧠 Nunca Pierde el Hilo (Sobrevive a un Reinicio de Memoria) Los trabajos largos terminan correctamente — incluso cuando la memoria de la IA se reinicia a mitad del proceso. El plan, el progreso y la prueba viven en archivos en disco, no solo en la cabeza del agente. Los agentes de IA tienen una memoria de trabajo limitada. En un trabajo largo esa memoria se llena y se comprime — los detalles pueden difuminarse. Cuando comienza una nueva sesión (o se borra la memoria), el agente no adivina dónde lo dejó. Lee los archivos. Así es exactamente como funciona: **1. Escribe un breve informe después de cada fase.** Cuando termina una fase, se escribe un archivo de informe en disco. El progreso vive en la carpeta de tu proyecto, no solo en la cabeza del agente. Una compresión de memoria no puede borrar un archivo. **2. Mantiene una lista de verificación de los pasos completados.** Cada plan de fase tiene una lista de **Phase Loop Progress** — casillas de verificación para cada paso (investigación, comprobación del plan, construcción, prueba, captura de aprendizajes). Tras un reinicio, el agente lee esas casillas y conoce el siguiente paso exacto. No hace falta ponerlo al día. **3. Un breve "sobre" al inicio de cada fase.** Cada agente trabajador (un ayudante especializado que realiza una fase del trabajo) comienza emitiendo un **Context Envelope** — una nota de 10 campos: qué funcionalidad, qué fase, qué rama, qué archivo de plan, qué pruebas ejecutar. Se lee en segundos. El agente está listo antes de hacer cualquier cosa. **4. Confía en los archivos más que en su propia memoria.** Al retomar, el agente verifica lo que hay realmente en el código y en el historial de git frente a lo que dice el plan. El estado real prevalece. Un plan que quedó desactualizado no puede engañar al agente para que repita trabajo u omita pasos. **5. Un marcador en curso e informes por ronda.** Cada bucle de corrección (el bucle de comprobación del plan y el bucle de construcción-prueba) mantiene un archivo marcador `results.tsv` — una fila por ronda, con seguimiento de cuántos problemas quedan. Cuando una sesión termina a mitad del bucle, la siguiente sesión lee el conteo, retoma en la ronda correcta y continúa. No se pierde ninguna ronda. **6. Reinyecta un recordatorio al retomar.** Cuando la memoria se comprime, el sistema recarga automáticamente la nota de estado más reciente en la nueva sesión. Si había alguna aprobación pendiente — por ejemplo, un punto de control que requería un "sí" antes de continuar — el recordatorio lo señala. Nada se omite silenciosamente. > 💡 En resumen: puedes iniciar una ejecución en piloto automático, cerrar tu portátil y volver horas después. El agente estará exactamente donde debe — o retomará desde el último punto de control guardado, con evidencia en disco que lo demuestra. --- ## 🧠 Grupos de Contexto El conocimiento del proyecto se organiza en **grupos de contexto** — áreas de conocimiento estables, cada una con un archivo enrutador `all-{group}.md` que indica a los agentes qué leer y cuándo. Los agentes siguen el enrutador y cargan solo lo relevante — no toda la base de conocimiento cada vez.
``` process/context/ ├── all-context.md # 🧭 Enrutador raíz — arquitectura, pila, patrones, convenciones ├── tests/all-tests.md # 🧪 Ejecutores de prueba, comandos, procedimientos de depuración ├── container/all-container.md # 🐳 Docker, despliegue, procedimientos de infraestructura ├── uxui/all-uxui.md # 🎨 Componentes, tokens de diseño, patrones ├── infra/all-infra.md # 🖥️ Infraestructura de servidores, despliegue └── {your-domain}/all-{domain}.md # 📚 Cualquier dominio con 3+ documentos duraderos (promovido automáticamente) ``` | | Cómo funciona | |---|---| | 🧭 **Patrón de enrutador** | Los agentes leen solo lo relevante para su tarea | | 📏 **Promoción automática** | Los temas con 3+ documentos (o un solo archivo que crece demasiado) obtienen su propio grupo | | 🔄 **Siempre actualizado** | Lo actualiza `vc-update-process-agent` tras cada funcionalidad no trivial | | 🧪 **Auditable** | `vc-audit-context` verifica el enrutamiento, el frontmatter de descubrimiento y la coherencia | | 📨 **Context Envelope** | Cada agente del bucle interno emite una nota de 10 campos al inicio (feature → phase → session-goal → branch → worktree → context-group → blast-radius-packages → active-plan → test-runner → validate-contract) para que un agente trabajador recién iniciado sepa exactamente dónde se encuentra | > El kit solo incluye la semilla del protocolo — tus grupos de contexto son **construidos para tu proyecto** por `vc-setup`, escaneando tu código real. Son un patrón, no una lista fija. --- ## 📁 Carpetas de Funcionalidad Cuando un tema acumula 5 o más archivos, obtiene su propia **carpeta de funcionalidad** — un contenedor de ciclo de vida completo. ``` process/features/{feature}/ ├── active/{slug}_{date}/ # 📋 Planes en curso (informes/referencias colocalizados) ├── completed/ # ✅ Planes archivados (historial de decisiones consultable) └── backlog/ # 📌 Trabajo diferido (los agentes lo consultan antes de duplicar) ``` | | Qué ocurre | |---|---| | 🆕 | El nuevo trabajo comienza en `active/` → los informes se acumulan → el plan se archiva en `completed/` | | 📌 | El trabajo diferido va a `backlog/` — los agentes lo consultan antes de crear planes duplicados | | 📦 | La promoción de funcionalidad ocurre automáticamente cuando los artefactos generales llegan a 5+ | | 🔍 | Cada funcionalidad tiene un historial completo y autónomo — planes, decisiones, informes, investigación | --- ## 🧱 Capas de Habilidades Las 33 habilidades se dividen en tres capas. Cada `SKILL.md` declara su `layer` + `trigger_keywords` en el frontmatter, y un catálogo generado mantiene el descubrimiento rápido.

🎭

Agentes actores

Poseen una fase o un rol. Viven en .claude/agents/ — son los 15 agentes, no habilidades.

📜

Habilidades de contrato (20)

Cada una produce un archivo específico o una salida acordada — vc-generate-plan, vc-validate-findings, vc-autopilot, las auditorías. Los resultados pueden verificarse.

🛠️

Habilidades de apoyo (13)

Mejoran cómo trabajan los agentes, sin producir archivos propios — vc-scout, vc-sequential-thinking, vc-problem-solving, vc-docs-seeker.
--- ## 🧠 Memoria de Proyecto que Mejora Sola Cada funcionalidad completada retroalimenta los aprendizajes al sistema de contexto — **el conocimiento se acumula, no se reinicia.** La mayoría de los proyectos asistidos por IA tienen la propiedad contraria: cada nueva sesión empieza desde cero. El agente vuelve a leer los mismos archivos, vuelve a descubrir los mismos patrones y vuelve a tomar las mismas decisiones — porque el conocimiento de la sesión anterior solo vivía en una ventana de chat. La respuesta del kit no es un truco de instrucciones. Es un **sistema de archivos de contexto duradero** (`process/context/`) que cada agente lee al inicio de la sesión, cada validador protege y cada funcionalidad completada enriquece. Seis meses y muchos reinicios de memoria después, el agente todavía sabe *por qué* tu autenticación funciona como funciona — porque ese conocimiento está en disco, enrutado y auditable, no atrapado en una sesión muerta.
```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD FEAT["Feature ships\n(EXECUTE + EVL complete)"] UP["UPDATE PROCESS phase\nvc-update-process-agent"] CTX["process/context/ updated\nsmallest relevant file\n+ all-context.md router"] AGENT["Next agent spawned\nreads context router\n→ routes to correct group file"] BETTER["Better next feature\nno re-discovery, no stale patterns"] FEAT --> UP --> CTX --> AGENT --> BETTER BETTER -.->|"compounds each feature"| FEAT style FEAT fill:#C62828,stroke:#B71C1C,color:#FFFFFF style UP fill:#00695C,stroke:#004D40,color:#FFFFFF style CTX fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style AGENT fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style BETTER fill:#E65100,stroke:#BF360C,color:#FFFFFF ``` ### El mecanismo central: `process/context/` como memoria portátil y compartida `process/context/` almacena conocimiento estructurado organizado en grupos temáticos — decisiones de arquitectura, convenciones de código, pasos de despliegue, patrones de prueba, datos de infraestructura. A diferencia de un historial de chat, este conocimiento: - **viaja a cada agente trabajador** — `vc-context-discovery` enruta cada agente iniciado al enrutador `all-{group}.md` correcto para su tarea, y luego al archivo profundo más pequeño relevante. Un agente de investigación, uno de planificación y uno de programación comienzan todos con el mismo entendimiento compartido - **sobrevive a un reinicio de memoria** — está en disco, no en una ventana de contexto; una sesión comprimida no pierde nada - **es legible tanto por Claude como por Codex** — `.agents/skills` es un enlace directo a `.claude/skills/`, por lo que el mismo sistema de contexto sirve a ambos agentes sin duplicación El enrutador raíz (`all-context.md`) apunta a enrutadores de grupo (`all-{group}.md`), que enrutan al archivo profundo más pequeño relevante. Los agentes siguen el enrutador — nunca codifican rutas de archivo en duro. Esto significa que los cambios de nombre y las divisiones de grupo solo requieren ediciones del enrutador, no una búsqueda en todo el código. ``` process/context/ ├── all-context.md ← enrutador raíz (arquitectura, pila, patrones) ├── tests/all-tests.md ← ejecutores de prueba, depuración, comandos ├── container/all-container.md ← Docker, despliegue, procedimientos de infraestructura ├── uxui/all-uxui.md ← componentes, tokens de diseño, convenciones visuales └── {domain}/all-{domain}.md ← cualquier dominio con 3+ documentos duraderos (promovido automáticamente) ```
### Qué lo hace mejorar solo (no solo "documentación viva") La expresión "documentación viva" suele significar "documentación que pretendemos mantener actualizada pero que en su mayoría olvidamos." Este sistema hace cumplir la intención de forma mecánica. **La fase UPDATE PROCESS requiere una revisión de contexto por archivo antes de poder cerrarse.** `vc-update-process-agent` no puede terminar una fase hasta que cada archivo de contexto potencialmente afectado haya sido revisado con un motivo concreto por archivo. "No se necesitan actualizaciones" está permitido — pero debe nombrar cada archivo revisado y explicar por qué. Los motivos vagos son rechazados. El punto de control es binario: registrar la revisión, o la fase no se cierra. El bucle de retroalimentación completo por cada funcionalidad completada: | Paso | Responsable | Qué ocurre | |------|-------|-------------| | 1. Análisis de git diff | `vc-scout` | Mapea los archivos modificados → áreas de contexto afectadas | | 2. Revisión por archivo | `vc-update-process-agent` | Nombra cada archivo de contexto, indica la actualización o un explícito "sin cambio + motivo" | | 3. Actualizaciones aplicadas | agentes trabajadores en paralelo | El archivo de contexto de cada área se actualiza con nuevos patrones, decisiones y aprendizajes | | 4. Enrutamiento verificado | `validate-context-discovery.mjs` | Confirma que cada documento está indexado y que los enrutadores son coherentes | | 5. Descubrimiento confirmado | `validate-all-context.mjs` | Confirma que `all-context.md` y los enrutadores de grupo coinciden con los archivos actuales en disco | Tu funcionalidad número 100 se beneficia de todo lo aprendido en las 99 primeras — no como aspiración, sino como garantía mecánica.
### Vista anticipada: los aprendizajes se transmiten hacia adelante, no solo hacia atrás Cada informe de fase incluye una sección `## Forward Preview` escrita para el agente de la *siguiente* fase. Incluye los comandos exactos para mantener todo en verde, los cambios de dependencias y los cambios de alcance de archivos detectados a mitad de fase. El agente que retoma la Fase 3 no tiene que releer la salida de la Fase 2 y adivinar qué importa. Recibe un resumen enfocado. Esto es diferente a los documentos de contexto: los documentos de contexto contienen conocimiento *duradero* (decisiones que se mantienen válidas a lo largo de funcionalidades); Forward Preview contiene un estado de entrega *temporal* (lo que la siguiente sesión de trabajo necesita saber ahora mismo).
### El conjunto de validadores previene la obsolescencia El conocimiento duradero queda desactualizado cuando nadie lo verifica. El kit incluye validadores que se ejecutan como parte del cierre de cada fase: | Validador | Qué detecta | |-----------|----------------| | `validate-context-discovery.mjs` | Documentos no indexados por ningún enrutador; enlaces rotos; frontmatter faltante | | `validate-all-context.mjs` | `all-context.md` desincronizado con los archivos reales en disco | | `validate-skill-keywords.mjs` | Habilidades sin campos `trigger_keywords` o `layer` (rompe el enrutamiento del Paso 0) | | `validate-protocol-discovery.mjs` | Archivos de protocolo en `process/development-protocols/` sin frontmatter de descubrimiento | Se ejecutan como verificaciones automáticas — un documento obsoleto o huérfano falla. El sistema vigila su propia salud.
### Los grupos de contexto se organizan solos Los grupos se crean automáticamente cuando un tema alcanza 3+ documentos o un solo archivo supera las ~800 líneas. Los agentes siguen los enrutadores y nunca codifican rutas en duro — por lo que agregar un nuevo grupo (p. ej., `process/context/billing/all-billing.md`) solo requiere actualizar el enrutador, no modificar cada agente que mencione facturación. El enrutador es la referencia estable; los archivos que hay detrás de él pueden reorganizarse libremente. > El kit siembra los grupos de contexto a partir de tu código base real (mediante `vc-setup`). Los grupos no son una lista fija — son un patrón. Tu área de autenticación, tu área de infraestructura y tu área de pagos se convierten cada una en conocimiento enrutable de primera clase a medida que el proyecto crece. --- ## 🤖 Qué Hay Dentro
### 15 Agentes
Haz clic para ver la lista de agentes
**Agentes del flujo de trabajo principal** — uno por fase RIPER-5 (R → SPEC → I → P → V → E → UP): | Agente | Modelo | Rol | |-------|:---:|------| | 🔍 `vc-research-agent` | sonnet | Investigación de código base y web, solo lectura. Seguimiento de contradicciones integrado | | 📝 `vc-spec-agent` | sonnet | Documento de requisitos de descubrimiento de producto antes de INNOVATE. Produce `*_SPEC_*.md` | | 💡 `vc-innovate-agent` | sonnet | Compara 2-3 enfoques. Resumen de decisión (elegido + rechazado) antes de PLAN | | 📋 `vc-plan-agent` | sonnet | Escribe el plan con protecciones contra atajos. "Ya sé cómo hacerlo" no es un plan | | ✅ `vc-validate-agent` | sonnet | Convierte el plan en una lista de verificación acordada (V1–V7). Punto de control: PASS/CONDITIONAL/BLOCKED | | ⚡ `vc-execute-agent` | **opus** | Implementa según el plan. Notas de progreso al informe de fase, protocolo de desviación, autorrevisión | | ⏩ `vc-fast-mode-agent` | **opus** | R→S→I→P→V comprimido con una pausa de seguridad obligatoria antes de EXECUTE | | 🔧 `vc-quick-fix-agent` | **opus** | Carril QUICK FIX: una pequeña edición de bajo riesgo + verificación acotada, sin plan/validación | | 🧠 `vc-update-process-agent` | sonnet | Cierre de 7 fases: archivar, actualizar contexto, escaneo de artefactos obsoletos, aprendizajes |
**Agentes especialistas** — llamados durante EXECUTE o de forma independiente: | Agente | Rol | |-------|------| | 🐛 `vc-debugger` | Recopila evidencia antes de formular una hipótesis. Hipótesis en competencia, cadenas de eliminación, sondas de viabilidad | | 🧪 `vc-tester` | Consciente de los cambios. Vuelve a ejecutar las pruebas de la lista de verificación acordada (EVL). Escala automáticamente ante cambios de configuración | | 🔎 `vc-code-reviewer` | Envía un explorador de casos límite ANTES de la revisión. Detección N+1, verificación de rutas de autenticación | | ✨ `vc-code-simplifier` | Ordena el código para mayor claridad sin cambiar el comportamiento | | 🎨 `vc-ui-ux-designer` | Frontend consciente del diseño. Puede iniciar un agente de investigación a mitad de la construcción | | 📦 `vc-git-manager` | Divide en commits lógicos desde `touched_files`. Rechaza archivos desconocidos |

### 33 Habilidades (descubrimiento automático)
Haz clic para ver la lista de habilidades (20 de contrato + 13 de apoyo)
**📜 Habilidades de contrato (20)** — poseen un artefacto: `vc-generate-plan` · `vc-generate-context` · `vc-generate-spec` · `vc-generate-closeout` · `vc-generate-phase-program` · `vc-audit-context` · `vc-audit-plans` · `vc-audit-vc` · `vc-update` · `vc-publish` · `vc-feasibility-test` · `vc-risk-evidence-pack` · `vc-test-coverage-plan` · `vc-validate-findings` · `vc-autoresearch` · `vc-intent-clarify` · `vc-autopilot` · `vc-agent-strategy-compare` · `vc-plan-discovery` · `vc-context-discovery` **🛠️ Habilidades de apoyo (13)** — mejoran cómo trabajan los agentes: `vc-review-situation` · `vc-sequential-thinking` · `vc-problem-solving` · `vc-scout` · `vc-debug` · `vc-docs-seeker` · `vc-frontend-design` · `vc-agent-browser` · `vc-web-testing` · `vc-setup` · `vc-predict` · `vc-scenario` · `vc-security`
> **⚠️ Regla de nomenclatura:** NO uses el prefijo `vc-` para tus propias habilidades o agentes — ese espacio de nombres está reservado para los archivos incluidos en el kit, y el guardián de eliminación de obsoletos trata cualquier ruta `vc-*` bajo `.claude/skills/` y `.claude/agents/` como propiedad del kit. Usa `my-`, `team-` o `proj-` en su lugar.
### 🪝 10 Ganchos | Gancho | Qué hace | |------|-------------| | 🔐 `privacy-block.cjs` | Bloquea la lectura de `.env`, credenciales, claves SSH. Requiere aprobación explícita | | 🚫 `scout-block.cjs` | Evita deambular por `node_modules/`, `dist/`. `.ckignore` con sintaxis gitignore | | 🧠 `session-init.cjs` | Detecta la pila, inyecta el entorno, recupera puntos de aprobación tras compresión | | 💉 `subagent-init.cjs` | Inyecta un bloque de contexto compacto en cada subagente | | ✨ `post-edit-simplify-reminder.cjs` | Tras 5+ ediciones, sugiere ejecutar el simplificador (no bloqueante, con límite de frecuencia) | | 📛 `descriptive-name.cjs` | Convenciones de nomenclatura de archivos según el lenguaje en cada escritura | | 📊 `session-state.cjs` | Métricas de sesión y conciencia de tokens | | 📋 `post-write-plan-check.mjs` | Valida la estructura del artefacto de plan en cada escritura a un `*_PLAN_*.md` | | 🧹 `post-commit-lint.mjs` | Verifica el prefijo de commits convencionales en cada `git commit` | | 🔍 `stop-validator-sweep.cjs` | Ejecuta los validadores principales del arnés cuando la sesión se detiene |
**Dónde vive todo:** ```text your-project/ ├── .claude/{agents,skills,hooks}/ # 🤖 15 agentes · ⚡ 33 habilidades · 🪝 10 ganchos ├── .codex/agents/ # 🔄 Reflejado para Codex ├── .agents/skills -> .claude/skills # 🔗 Enlace simbólico para el descubrimiento de Codex ├── CLAUDE.md · AGENTS.md # 📋 Configuración del orquestador + registro entre herramientas └── process/ ├── context/ # 🧠 Dominios de conocimiento con enrutamiento automático ├── general-plans/ # 📋 Planes transversales + carpetas de tarea ├── features/ # 🏷️ Carpetas de ciclo de vida por funcionalidad └── development-protocols/ # 📜 22 documentos de flujo de trabajo compartido ``` --- ## ⚡ Corrección Rápida + Modo Rápido Dos opciones más ligeras para cuando el proceso RIPER-5 completo es más de lo que el trabajo necesita:

🔧

Corrección Rápida — "quick fix: …"

Más grande que un simple retoque de una línea, más pequeño que "necesita un plan." El agente principal explora en modo solo lectura → confirmación de una línea → inicia vc-quick-fix-agent para la edición + una verificación acotada solo a los archivos tocados. Sin plan, sin lista de verificación acordada, sin EVL.

Se cancela de inmediato si el cambio toca superficies de esquema, autenticación, API, facturación o migración — en ese caso se enruta a RESEARCH completo.

⏩

Modo Rápido — "ENTER FAST MODE - …"

Comprime RESEARCH + SPEC + INNOVATE + PLAN + VALIDATE en un solo paso — pero aun así escribe un plan, escribe una lista de verificación acordada y hace una pausa antes de EXECUTE.

En el Modo Rápido estándar hay una pausa tras VALIDATE — tú revisas y luego dices "ENTER EXECUTE MODE." Usa autopilot fast: [task] para eliminar esa pausa y ejecutar todo de principio a fin sin detenerse.
--- ## 🔄 Ciclo de Vida del Kit: Instalar · Configurar · Actualizar · Publicar | Comando | Qué hace | Cuándo | |---|---|---| | `curl … install.sh \| bash` | Sincroniza los archivos del kit sin sobrescribir los tuyos; detecta automáticamente si es instalación nueva o actualización y te guía | Primera instalación + cada actualización | | **Ejecutar vc-setup** | Detecta la pila, estructura `process/`, escanea en profundidad el código base, rellena el contexto real | Tras una instalación nueva | | **Ejecutar vc-update** | Calcula un diff preciso, muestra qué cambiará, espera tu confirmación; migra planes/carpetas en formato antiguo sin pérdida de datos | En cada actualización | | **Ejecutar vc-publish** *(mantenedores)* | Publica los cambios del arnés de vuelta al repositorio del kit | Al contribuir al kit mismo | ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%% flowchart TD TRG["EXECUTE complete\nENTER UPDATE PROCESS MODE"] AGT["spawn vc-update-process-agent"] A["(a) Archive plan\nactive/ → completed/"] B["(b) Update process/context/\nsmallest relevant file\n+ all-context.md router"] C["(c) Tier-1 audits\n(change-type gated)"] AVC["vc-audit-vc\nharness/agent edits"] ACX["vc-audit-context\ncontext-doc edits"] APL["vc-audit-plans\nplan/program edits"] D["(d) Capture learnings\nto memory"] E["(e) Write closeout packet\nvc-generate-closeout"] F["(f) Conventional commit\nvc-git-manager"] TRG --> AGT --> A --> B --> C C --> AVC C --> ACX C --> APL AVC --> D ACX --> D APL --> D D --> E --> F style TRG fill:#1565C0,stroke:#0D47A1,color:#FFFFFF style AGT fill:#0277BD,stroke:#01579B,color:#FFFFFF style A fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF style B fill:#00695C,stroke:#004D40,color:#FFFFFF style C fill:#E65100,stroke:#BF360C,color:#FFFFFF style AVC fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style ACX fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style APL fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF style D fill:#558B2F,stroke:#33691E,color:#FFFFFF style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF style F fill:#37474F,stroke:#263238,color:#FFFFFF ``` > 💡 `vc-update` muestra una vista previa del diff y espera tu confirmación. Tu directorio `process/` y el contenido específico del proyecto **nunca** se modifican en silencio. Volver a ejecutar la instalación es seguro aunque se haga dos veces. --- ## 💡 Más Razones por las Que Simplemente Funciona Muchos pequeños valores predeterminados inteligentes se suman para reducir la supervisión necesaria y el costo. - **Cada rol solo obtiene las herramientas que necesita.** Durante la planificación, el agente literalmente no puede editar código — esas herramientas están desactivadas. Esto evita que el agente se adelante y cambie cosas antes de que el plan esté aprobado. El sistema simplemente no lo permite. - **Usa el modelo de IA premium solo donde importa.** La escritura de código usa el modelo más avanzado. La planificación, la investigación, la revisión y la verificación usan un modelo más económico y rápido. El resultado: un costo aproximadamente 60–70% menor en comparación con usar el modelo más avanzado para todo — sin pérdida de calidad en el trabajo que realmente importa. - **Prueba las suposiciones arriesgadas antes de construir sobre ellas.** Cuando el agente no está seguro de que algo funcionará — un comportamiento específico de API, una característica de biblioteca, una suposición de infraestructura — primero realiza un pequeño experimento real. El resultado es claro: funciona, no funciona o no está claro. Ese veredicto y una nota en lenguaje sencillo se incluyen directamente en el plan. El agente no pierde horas construyendo sobre una suposición incorrecta. - **Puntos de guardado ordenados y con significado.** Los cambios se confirman en fragmentos lógicos y limpios con mensajes claros — de forma automática. El historial es fácil de leer y fácil de deshacer una parte a la vez. - **Recordatorios automáticos útiles.** Pequeños ayudantes integrados sugieren cosas como ejecutar las verificaciones correctas en los archivos modificados, mantener el código simple y escribir un mensaje de commit adecuado. La calidad se mantiene alta sin que tengas que supervisarlo. - **Puedes ejecutar el bucle de mejora continua por tu cuenta.** El mismo motor de "encontrar problemas, corregirlos, repetir" que impulsa la comprobación del plan y la corrección de pruebas también funciona como herramienta independiente en cualquier área desordenada — una especificación, la documentación, las pruebas, una lista de errores. No necesitas una funcionalidad completa para usarlo. - **Prueba incorporada de que las reglas del flujo de trabajo realmente funcionan.** El kit incluye su propio conjunto de pruebas: un conjunto de verificaciones con ejemplos conocidos como buenos y malos que demuestran que las reglas del flujo de trabajo se comportan correctamente. El sistema se verifica a sí mismo. No tienes que confiar en que los mecanismos de protección están activos — puedes ejecutar las verificaciones y verlo. --- ## Contribuir ¡Damos la bienvenida a las contribuciones! Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para conocer las pautas.
**Enlaces rápidos:** - 🐛 [Reportar un error](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=1.bug_report.yml) - 💡 [Solicitar una funcionalidad](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=2.feature_request.yml) - ⚡ [Enviar una habilidad](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=3.skill_submission.yml) - 🌐 [Añadir una traducción](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=5.translation.yml)
Contributors
### 🙏 Créditos vibecode-pro-max-kit se centra en el marco de desarrollo basado en especificaciones y la organización de contexto que mejora sola, sin sobrecargarte con más de 80 habilidades. Menos herramientas, más estructura. --- ## ⭐ Historial de Estrellas Star History Chart --- ## 📄 Licencia MIT