Communitygithub.com

rjv-gated-build

Construcción por pares adversarios: un agente revisa y rechaza el trabajo de otro hasta que se gana la aprobación explícita. Calidad mediante independencia.

¿Qué es rjv-gated-build?

El skill 'rjv-gated-build' implementa un flujo de construcción multiagente con revisión adversarial, ideal para sistemas donde los errores costosos (financieros, de seguridad) no son tolerables. Su núcleo es la separación de roles: un Orquestador gestiona el plan y la integración, un Autor redacta el código/diseño, y un Revisor examina cada paso con el objetivo de decir 'NO-AGREE' hasta que se alcanza un 'APPROVED' explícito. La eficiencia se logra comprimiendo todo lo que los agentes leen (especs, notas, prompts del revisor) para poder costear un segundo agente que contradiga al primero. El skill soporta múltiples plataformas y configuraciones: desde agentes frontier de diferentes proveedores (cruce de familias para evitar puntos ciegos) hasta modelos locales para tareas mecánicas, pasando por subagentes de bajo costo. Incluye reglas estrictas para el revisor (debe ser al menos tan potente como el autor), un bucle de compuertas (grill loop) con límite de rondas, y un documento ancla persistente que almacena el estado fuera de la conversación viva, garantizando que una caída de conexión no pierda el progreso.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add rjvim/ai-skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Construcción por pares — construcción multiagente adversarial

Para trabajos donde ser plausiblemente incorrecto es costoso. Un solo agente — por más disciplinado que sea — no puede detectar sus propios errores de forma confiable: el mismo punto ciego que produjo el error lo revisa. La calidad proviene de la independencia: un segundo agente cuyo trabajo es decir NO-AGREE, analizando cada paso hasta que se gane un APPROVED explícito.

La economía: comprimir todo lo que los agentes leen (especificaciones, notas, indicaciones de revisión), para que puedas permitirte un segundo agente que contradiga. La eficiencia financia la redundancia.

1. Asignación de roles

Tres roles: Orquestador (tiene el documento ancla, asigna los otros, integra), Autor (redacta código/diseño), Revisor (analiza hasta APPROVED). Asignados por tarea, no por costumbre:

AutorRevisorCuándo
Agente frontier (con contexto completo del repo)Agente frontier de otro proveedorConstrucciones de alto riesgo y con mucho diseño — el patrón central
Agente CLI externo (ej. Codex)El propio OrquestadorEscritura mecánica de código repetitivo; el orquestador tiene el contexto + juicio
Modelo local (clase Ollama)OrquestadorRedacción a nivel de función de costo cero desde una especificación ajustada
Subagente de nivel baratoModelo tope de gamaEconomía intra-familia: manos baratas, juez caro

Enlaces de ejecución — cada asignación necesita un transporte concreto en tu infraestructura; usa lo que ya existe en lugar de inventar tuberías:

  • Autor con modelo local → el skill rjv-ollama-delegate (ejecutor empaquetado, reglas de escritura de prompts, mandato de verificación).
  • Autor/Revisor CLI externo (clase Codex) → su plugin de agente o un subagente delgado como reenviador Bash (ej. el subagente de rescate de Codex en Claude Code) — una llamada de entrada, stdout de vuelta, modelo más barato posible en el propio reenviador.
  • Autor barato intra-familia → lanzamiento de subagente con el modelo establecido explícitamente (ver §7).

Registra la asignación en el plan. La asignación ocurre UNA VEZ, al inicio de la construcción, y se escribe en la sección ## Cast del plan ancla (ver rjv-feature-workflow): orquestador, autor, revisor, niveles de subagente, compuertas humanas — con modelos nombrados explícitamente. Cada reanudación lee la asignación y juega su rol; el bucle con compuerta nunca renegocia quién aprueba. Reasignar es una Decisión registrada con un porqué.

Dos reglas duras de asignación (respaldadas por evidencia, no las dobles):

  1. El revisor debe ser al menos tan potente como el autor. La fuerza del revisor es de donde viene la calidad; la fuerza del autor es solo velocidad de escritura. Un modelo débil no revisa nada — probado: al pedirle encontrar un error real en código enviado a producción, un modelo local de 35B dijo "no hay errores".
  2. Prefiere cruce de proveedores para el análisis. Diferentes familias de modelos fallan en diferentes modos de fallo; la revisión dentro de la misma familia hereda los puntos ciegos del autor.

El humano también es un revisor. En una ejecución real, el usuario detectó un agujero (latencia del bróker) que AMBOS modelos frontier habían pasado por alto después de cuatro rondas de análisis. Presenta los diseños al humano en los límites de fase; su experiencia en el dominio supera a los sesgos del modelo — cuando su evidencia en vivo contradice tu diseño, el diseño se actualiza de inmediato y lo declara.

2. Analiza la ESPECIFICACIÓN antes de cualquier código

El análisis de mayor apalancamiento ocurre antes de la implementación. En el proyecto original, el veredicto de la primera ronda del revisor sobre el diseño fue "no construible tal como está escrito" — 10 escenarios de ataque clasificados, 8 válidos. Arreglarlos antes del código costó reescribir un documento; después del código habría costado toda la construcción.

  • Envía la especificación/diseño al revisor con: "ATACA este diseño. Enumera escenarios de fallo clasificados. Veredicto: AGREE / NO-AGREE con bloqueos."
  • Itera especificación → ataque → enmienda hasta AGREE. Registra cada ronda en el documento ancla (v1 → v2 → v2.1 …), anotando qué objeciones se aceptaron por mérito y cuáles se rechazaron con razones.
  • Un revisor que nunca dice NO-AGREE no está revisando. Si cada ronda aprueba instantáneamente, afila el prompt (ver §4) o reasigna.

3. El bucle con compuerta (por paso de implementación)

checkpoint de especificación → implementar → auto-revisión + prueba rápida → ANÁLISIS DEL REVISOR → arreglar → re-analizar … → APPROVED → commit → siguiente
  • Especificación primero. Escribe los criterios de aceptación del paso en el documento ancla ANTES de codificarlo. Calificarte contra una especificación inventada durante el código es cómo los errores son bendecidos.
  • Auto-revisión + prueba rápida descartable antes de entregar — detecta los errores tontos de forma barata para que las rondas del revisor se centren en los sutiles.
  • Analiza hasta obtener un APPROVED explícito. Un solo ciclo de ida y vuelta no es revisión.
  • Estaciona, nunca sella de forma automática. Limita las rondas de análisis por paso (~6). Si aún está bloqueado → escribe los bloqueos abiertos en el documento ancla y DETÉN ese paso. Un "estacionado deliberadamente, he aquí por qué" es mejor que una aprobación falsa — no negociable cuando hay dinero o seguridad en juego.
  • Plan vivo / alcances hacia atrás. Cuando un análisis invalida un paso ANTERIOR ya aprobado: reábrelo, arréglalo, vuelve a probar, vuelve a analizar, REGISTRA el alcance hacia atrás. Un paso incorrecto fijado es peor que uno reabierto.

4. Dirigir al revisor — reglas de prompt

  • SOLO REVISIÓN. Primera línea: "SOLO REVISIÓN — no modifiques archivos, no implementes." El revisor lee, razona, vota.
  • Tú ejecutas las pruebas, no el revisor. Los entornos aislados del revisor se cuelgan con la ejecución. Ejecuta la suite tú mismo, pega los resultados en el prompt ("suite ya ejecutada: N pasadas — revisa leyendo el código"). Leer archivos está bien; ejecutar no.
  • Nombra los modos de fallo. Apunta a archivos exactos, la sección de la especificación y una lista numerada de búsqueda. Para código financiero: doble exposición, sobreventa, intención perdida/duplicada en reinicios, condiciones de carrera en órdenes, idempotencia, comisiones/precisión, la ruta arriesgada específica que se acaba de escribir. Prompts vagos obtienen revisiones vagas.
  • Acota cada análisis; cancela primero si hay tiempo de espera. Ponlo en segundo plano con un límite de tiempo real (~12–15 min). Al cumplirse el tiempo: CANCELA el trabajo PRIMERO, verifica que nada se esté ejecutando, relanza fresco. Mata procesos huérfanos. Limita los relanzamientos (~3); falta persistente de veredicto = fallo de herramienta → estaciona, no finjas.

5. El documento ancla (la memoria real de la construcción)

Un documento de memoria de trabajo comprimido por construcción — y un repositorio tiene muchas construcciones. No mantengas un solo archivo global RESUME.md: usa el diseño del skill rjv-feature-workflow (.plans/<nombre>.md por pieza de trabajo, enlazado desde la hoja de ruta de la funcionalidad), para que varias construcciones con compuerta puedan estar en curso y cada una se hidrate por nombre. Las secciones siguientes viven DENTRO de ese archivo de plan. La conversación es desechable; el documento ancla no lo es. "La especificación es el único artefacto que gana sus tokens" (cavekit).

Secciones propias — cada fase del bucle escribe solo la suya:

SecciónPropietarioContiene
OBJETIVOhumano + orquestadorun párrafo, el punto, nunca olvidar
RESTRICCIONES / VOCABULARIOhumanopalabras acordadas, palabras muertas, límites duros
REGISTRO DE EVIDENCIAorquestadorresultados en vivo como restricciones de diseño — ideas refutadas marcadas "no resucitar"
INVARIANTESrondas de análisisreglas de hierro que surgieron, cada una trazable a una ronda o a un cadáver
DISEÑO vNbucle especificación-análisisdiseño actual + la traza del análisis (v1 → v2 → …, quién objetó, qué se aceptó por mérito)
TAREAS / PLANorquestadorfases con criterios de aceptación; cada idea tiene un HOGAR o es eliminada
ERRORES / CADÁVERESimplementaciónfallos estudiados al nivel más bajo, taxonomizados
LÁPIDASorquestadorpreguntas resueltas mantenidas visibles "para que nadie las reabra"
ABIERTOcualquieraelementos genuinamente no resueltos, marcados USUARIO donde el humano debe decidir

Regla de registro — comprime por audiencia:

  • Todo lo que los agentes leen (este documento, RESUME, prompts de análisis, memoria): registro cavernícola. Datos, archivo:línea, imperativos. "registrar orden ANTES de enviar (caída de llenado síncrono → sobreventa)" — no prosa. Escrito para un lector sin contexto y 10 segundos. ~75% más barato en cada relectura, y las relecturas son el costo recurrente.
  • Todo lo que los humanos leen (respuestas, documentos orientados al usuario): prosa normal, ejemplos concretos con números. Los fallos de comprensión cuestan más que los tokens de salida.
  • La división de dos audiencias es explícita: las notas de agente pasan a documentos orientados al usuario solo cuando son concretas y acordadas.

La regla de "no después". Nunca archives nada como "después". Cada idea tiene un hogar en una fase nombrada (con el porqué allí) o es eliminada. En el proyecto original, "después" escondió el experimento más valioso — se convirtió en el PRIMER elemento de construcción una vez sacado a la luz. La única demora aceptable = una dependencia estructural real, declarada.

Mantenimiento de la compresión. El documento ancla y los archivos de memoria se releen en cada reanudación — son costo de ENTRADA recurrente, el costoso. Periódicamente (al final de una fase, o cuando el documento se hincha) reescríbelos en el registro: elimina prosa, conserva hechos. Reglas de compresión: nunca toques números, identificadores, referencias archivo:línea, código, comandos o texto de error (byte exacto); nunca comprimas el significado del REGISTRO DE EVIDENCIA — un matiz perdido allí reabre una idea refutada. Las secciones de diseño reemplazadas se reducen a lápidas de una línea; la traza de análisis conserva solo ronda + veredicto + qué cambió.

6. Mantenerse vivo — la ejecución debe sobrevivir caídas

Dos modos de fallo OCURRIRÁN en una ejecución larga: el revisor se cuelga, y tu propia conexión se cae en medio de una respuesta. La defensa es la misma: nunca mantengas el estado solo en la conversación en vivo.

  • Puntero de reanudación + conciliar al abrir. La sección de Próximos Pasos del documento ancla se reescribe al FINAL de cada paso: paso actual + estado, siguiente acción exacta, archivos de lectura obligatoria, reglas duras. En cada reanudación — post-compactación, post-caída, despertar programado — el PRIMER acto es el ritual de conciliación de rjv-feature-workflow: leer el plan → VERIFICAR cada afirmación de "hecho" contra el código/base de datos real → anotar desviación → reescribir Próximos Pasos → sellar "Última conciliación" → luego actuar. Nunca confíes en una casilla de verificación desactualizada; una caída puede haber perdido la edición que la casilla reclama.
  • Haz commit temprano y a menudo. Cada paso aprobado se confirma de inmediato. Una caída entonces pierde como máximo la edición en curso, no el trabajo de una noche.
  • Programa tus propios despertares. Al delegar a un análisis acotado, programa un autodespertar (~15 min) para que REGRESES ACTIVAMENTE — los watchers pasivos de "el trabajo me reinvocará" pueden morir en silencio.
  • Pasos idempotentes. Puedes reingresar en medio de un paso después de una caída; haz que los efectos secundarios sean seguros de reproducir (claves de deduplicación, upserts, comprobaciones de ya hecho).

7. Economía de modelo — no quemes el tope de gama en todo

Las ejecuciones largas se estancan por presupuesto/límites de tasa antes que por dificultad. La finalización depende de la frugalidad:

  • Barato por defecto. Modelo pequeño/rápido para subagentes mecánicos (el REENVIADOR del revisor es una llamada bash — ve al más barato; la calidad del análisis es el modelo del REVISOR, no el del reenviador). Nivel medio para código y análisis rutinarios.
  • Modelos locales para funciones implementables desde especificación — costo cero, y desde una especificación ajustada alcanzan ~90% de calidad de producción. Nunca como revisores (regla dura 1). Ver el skill rjv-ollama-delegate.
  • Reserva el tope de gama para diseño, síntesis, juicio final y el propio análisis.
  • Establece el modelo EXPLÍCITAMENTE por subagente — nunca heredes por defecto el costoso padre.

8. Honestidad de alcance — especialmente para sistemas financieros

Declara claramente lo que significa "hecho". "APROBADO por el revisor hasta el paso N" ≠ "validado contra el mundo real" si la ejecución solo ejercitó una ruta de simulador/paper. Mantén las compuertas peligrosas — trading en vivo, despliegues a producción, operaciones destructivas — físicamente apagadas hasta una fase de validación separada y explícita con su propia compuerta (paridad de paper, bandas de ratio de llenado, umbrales de fallo cerrado). Nunca permitas que "aprobado" se lea como "seguro de enviar a producción".

Apéndice — cuando el revisor es OpenAI Codex CLI

Especificidades operativas ganadas con esfuerzo para dirigir a Codex como analizador:

  • Cancela primero, nunca reconectes. En un tiempo de espera de análisis, NO "reconectes para preservar su trabajo" — la reconexión puede morir instantánea y silenciosamente, dejándote sin vigilancia mientras el trabajo huérfano se ejecuta durante horas. Siempre: cancela el trabajo → verifica que ninguno se esté ejecutando → relanza --fresh.
  • pkill a los huérfanos. Los trabajos cancelados/colgados dejan procesos codex app-server, codex resume y app-server-broker atrás; pkill -9 -f durante la limpieza para que no se acumulen a lo largo de una ejecución larga.
  • Su entorno aislado no puede ejecutar tus pruebas (a menudo no hay directorio temporal escribible; se cuelga "verificando" para siempre) — esta es la RAZÓN por la que existe la regla de §4 de que tú ejecutas las pruebas. Leer archivos (grep/sed/cat) dentro de su entorno aislado está bien.
  • Puede escribir archivos pero no ejecutar git — haz commit desde la sesión del orquestador después de que termine.
  • Los ids de sesión/hilo de su salida son reanudables (--resume-last / reanudar por id) — útil para análisis de seguimiento que necesitan el contexto de la ronda anterior, sujeto a la regla de cancelar primero anterior.

Invariante de una línea: revisor independiente + estado comprimido en disco + autodespertares programados = una ejecución que converge a lo correcto y sobrevive a cada colgado, caída y compactación en el camino.

Procedencia: destilado de una construcción en vivo de alto riesgo (bot de trading de opciones, 2026-07: 6+ rondas de análisis, NO-AGREE reales, un agujero de diseño detectado por humano, pérdidas estudiadas a nivel de tick) y un pico verificado de delegación a modelo local. Las ideas de registro + sección de especificación atribuidas a la familia caveman/cavekit (github.com/juliusbrussee).

Skills relacionados