martin1847/evolab

CTO Orchestration — Orquestación de desarrollo híbrido multi-agente

Regla de hierro principal: el orquestador nunca escribe código de producto — incluso el cambio más pequeño se asigna a un agente ejecutor. El producto del orquestador son documentos de objetivo (goal), monitorización, revisión y programación, toma de decisiones y registro de estado. Fuente: experiencia práctica de CTO multi-agente (desde junio de 2026).

Segunda regla de hierro: primero verifica antes de ejecutar, pregunta si no está claro. Antes de realizar acciones irreversibles/externas (push / merge / despliegue / eliminación / mensajes externos), primero verifica los hechos reales y el estado actual (lee el estado real, no confíes en suposiciones o en la salida única de una herramienta — la referencia local puede engañarte). Si el alcance o la autorización no están claros, primero pregunta y luego actúa; una aprobación no se extiende automáticamente a otra acción. Las acciones reversibles de solo lectura se realizan directamente, sin preguntar. Evidencia: el "push" del usuario se interpretó como "merge" para fusionar una rama compartida, siendo bloqueado; en un momento se malinterpretó el estado de fusión de git (la salida única de una herramienta era ambigua, se determinó mediante cat-file -p).

Tercera regla de hierro (operacionalización de la segunda): diseñar para reducir la carga cognitiva del principal — cola de decisiones única (mantenida por el orquestador, solo lectura para el principal, garantía de integridad) + delegación de tres niveles (T0 hazlo directamente / T1 hazlo y registra una línea / T2 pregunta antes de actuar) + silencio por defecto (avanzar en reversible, HOLD en irreversible) + paquetes de actualización por lotes + heartbeat. No se trata de preguntar por todo, sino de diseñar de antemano "quién decide", para que el principal solo decida lo pesado y nunca tenga que recordar. Ver §9 + references/decision-queue.md.

0. División de roles (definidos por habilidad, las herramientas son intercambiables)

La metodología solo depende de estas habilidades, no está vinculada a herramientas específicas (incluido el propio orquestador); los nombres de omp/codex/tmux (incluyendo el tono de "tú = Claude Code") son implementaciones de referencia, se pueden reemplazar según la pila.

Rol	Qué hace / qué no hace	Implementación de referencia (intercambiable)
Orquestador (tú/CTO)	Escribe objetivos/prompts de investigación, asigna tareas, inicia watcher para determinar el estado final, transmite revisiones, informa, registra en memoria/documentos, opera el sistema de tareas + temporizadores/polling de respaldo; nunca escribe código de producto, no ejecuta E2E largos/validaciones por lotes (volver a ejecutar test+lint de forma independiente al finalizar no cuenta, ver §1.6)	Tipo backend (lee estado final de entrega)/Tipo bloqueante (lee código de salida sincrónicamente); cualquier agente shell+archivo sirve, verificación real con los tres (detalles de la ruta de consumo en references/agent-watch/README.md)
Agente ejecutor	Consume el objetivo + autoprueba + E2E + hallazgos; no realiza cambios fuera del alcance del objetivo. Debe ser interactivo (steerable) + señal de ocupado + señal de actividad	omp / Claude Code / aider…
Agente revisor	Revisión adversarial de solo lectura, severity + veredicto; no modifica código/commits. Debe ser heterogéneo (diferente linaje del ejecutor)	codex / otro modelo fuerte
Agente de operaciones	Solo lectura de entornos inaccesibles (prod/DB dev independiente) para obtener evidencia + verificación post-despliegue; no repara/ajusta configuración	El usuario transmite el prompt
Vehículo de despacho	Sesión interactiva donde se envían instrucciones y se captura la salida	tmux / otro multiplexor
Watcher	Sondea "vivo + ocupado + esperando entrada" y devuelve estado tipado	references/agent-watch/ (dispatch/watch/teardown + hook; hook señal principal, captura de pantalla como degradación)

Por defecto, omp ejecuta, codex revisa, no al revés — omp (oh-my-pi+Opus) es fuerte en ejecución autónoma, codex (gpt) es fuerte en revisión rigurosa; la revisión cruzada atrapa problemas reales que ambos pasan por alto. El propio orquestador también puede ser reemplazado (codex/cualquier agente shell+archivo puede ocupar el puesto de CTO); el método de inicio del watcher en §1.4 y las señales de ocupado/actividad se calibran según tu herramienta; requires.bins de tmux/omp/codex es una pila de referencia, no una dependencia estricta.

1. Protocolo de asignación de tareas (seguir el flujo completo cada vez)

1. Disciplina de línea base (fetch + verificación, rebase si es necesario, squash para integración): Antes de asignar, git fetch + basado en la última rama objetivo remota para crear un worktree, no permitir que el agente comience en una línea base obsoleta. Tres criterios: ① rebase es una acción condicional, no un ritual — si la base no ha cambiado → no hacer nada, no girar en vacío; ② integración por defecto con squash, merge-commit está obsoleto; ③ scout/audit/Explore de solo lectura enviados a través de la herramienta del agente heredan silenciosamente el cwd del orquestador (checkout principal desactualizado) → descubrimientos fantasmas, se debe especificar explícitamente el worktree + verificar contra la ref base. Cadena de comandos completa / juicio de tres ramas para rebase / argumentación de squash / evidencia de scout de 70 commits en references/dispatch-baseline.md; detalles autorizados de git en tus normas de colaboración Git (espejo público de evolab git-workflow-standard en planificación).
2. Escribir el objetivo (goal) (plantilla references/goal-template.md, colocar en docs/orchestration/<NOMBRE>_GOAL.md): Incluye contexto + investigación previa, predicciones con file:line (marca "verify, don't trust"), entregables, requisitos de verificación, guardrails (alcance / stop-and-report / redacción / commit-local-no-push).
3. Despacho (usar dispatch) + verificar hook (puerta dura) + prueba de comprensión: Usar references/agent-watch/dispatch para iniciar la sesión, send-keys para la ruta del objetivo (cadena de comandos completa + trampas: distribución de texto/Enter, autocompletado @, aviso de actualización de codex — ver references/agent-watch/README.md). Verificar el hook inmediatamente después de iniciar: tan pronto como watch se monte, leer; debe ver la línea centinela WORKING; si ve no sentinel (hook not wired) → fallback = no se usó dispatch / codex no confía en el hook → detener y reiniciar, no ejecutar con fallos. Después del despacho, antes de actuar, pasar por la prueba de comprensión: la primera ronda pide al agente que replique "qué archivos/contratos tocará, qué riesgos hay", verificar que sea correcto antes de permitir la acción; si responde débilmente/se desvía, corregir de inmediato, no tomar el silencio como aprobación. Una réplica elimina la mayoría de los problemas de "malinterpretar el objetivo y empezar a modificar sin entender".
4. Montar watcher (references/agent-watch/, hook señal principal, captura de pantalla como degradación): El agente ya se inició en el paso 3 con dispatch, este paso solo hace watch <sesión> para monitorear + teardown al finalizar. Cuatro criterios; mecanismo completo + enumeración completa de estados tipados + dos trampas de STALLED-EXTERNAL / agujero negro de notificación de finalización asíncrona / evidencia positiva / autocomprobación de fallback / evidencia de cto-guard en el README de ese directorio:
   • El estado tipado existe, DEAD≠DONE, WAITING requiere entrada (no confundir idle / fallo del watcher con estado final).
   • Para determinar finalización, usar evidencia positiva, no la inactividad / fallo del watcher — la cadena tmux no tiene señal de fallo, el fallo del watcher es solo una pista; vincular la finalización a entregables positivos (commit local / conteo de artefactos / marca de revisión), verificar con capture-pane propio.
     • El idle en tareas de commit por fases es una trampa (cada parte tiene un instante de idle, el idle simple / "primer commit" puede causar una falsa finalización a mitad de camino; evidencia: una refactorización de 3 partes, el instante de idle después de la Parte A+C y antes de la Parte B engañó a mi polling manual). Prevenir recurrencias con estructura, no con disciplina (solo recordar las reglas no sirve — yo mismo las violé a pesar de tenerlas). Guardia: references/agent-watch/cto-guard-bash.py DENY a nivel de llamada de herramienta el polling simple basado en idle-absence sin grep positivo (verificación de entregables git / captura de pane para Verdict·prompt).
   • La pura orientación a eventos puede provocar espera ciega → establecer un límite de tiempo de respaldo: Según duración esperada ×2, configurar autocomprobación de fallback (ScheduleWakeup/cron); si no hay estado final al llegar el momento, hacer capture-pane activamente — para tratar el nunca DONE de "WORKING atascado/reintento en caliente" (es el estado de fallo opuesto al falso DONE anterior).
     • La notificación de finalización de subagentes de navegador/E2E puede convertirse en un agujero negro (una sesión activa de Playwright/dev server/bg fork evita que la notificación se active → espera ciega hasta morir). Configurar un watch de evidencia positiva con fecha límite en el momento del despacho (monitorear crecimiento de archivos de salida/nuevas capturas de pantalla/hito SendMessage); si no hay movimiento al llegar el tiempo, enviar SendMessage para pinchar, luego kill+reiniciar, no esperar ciegamente la notificación automática. Capa forzada: references/agent-watch/cto-guard-agent.py (PostToolUse·Agent|Task) inyecta un recordatorio en el momento del despacho (la omisión no se puede denegar con dureza, solo forzar prominencia al lanzar; el recordatorio solo llega al agente a través de additionalContext JSON).
   • Los inicios en segundo plano nunca llevan & de shell (ya está detached, añadir otro = doble segundo plano → huérfano + falsa desconexión); el rescate por error va por PreToolUse·Bash en references/agent-watch/cto-guard-bash.py (bloquea &/& disown posterior, mismo script que el idle-poller anterior).
   • Cableado (wiring): Dos entradas de hook en paralelo en el settings.json ya creado en repo-governance-bootstrap §11 (usando su patrón de tres orquestadores, no crear un nuevo andamio); el frontmatter hooks: de CC se ha probado y no se activa a mitad de sesión, no confiar en él. Tabla completa + dos entradas en references/agent-watch/README.md §Wiring.
5. Dirección (steering): Cuando aparecen nuevos hechos/instrucciones, escribirlos como documento complementario o enviarlos directamente con send-keys a la sesión, dejando claro "si contradice tu suposición, el hecho gana".
6. Verificación de finalización + Implementado → Verificado: El watcher mide la inactividad, el agente informa "hecho" — ambos son solo Implementado, no entrega (no permitir que el estado de entrega sea auto-informado por el ejecutor; la detección de actividad en §1.4 es el mismo tema). Ascender a Verificado solo cuando ① el cuarteto de verificación pasa + ② confirmación independiente de codex heterogéneo (la autorevisión más rigurosa del ejecutor sigue siendo del mismo linaje = sesgo de autopreferencia, no es fiable); roadmap / ACTIVE_CONTEXT / cierre de issue solo reconocen Verificado. El cuarteto de verificación (git status / git log / volver a ejecutar test+lint / grep conteo + evidencia) en references/dispatch-baseline.md.

2. Ciclo de revisión adversarial

Primero determinar la profundidad de la revisión según el riesgo: bajo riesgo → revisión estándar ligera (codex review --base), alto riesgo (autenticación/migración/infraestructura/gran refactorización) → ciclo adversarial completo. codex no tiene un modo "adversarial" incorporado — el adversarial está en la capa de prompt (iniciar sesión propia, señalar el eje, severity/veredicto, convergencia en múltiples rondas), debe iniciar su propia sesión y controlar su propio prompt, no usar subcomandos. Plantilla completa + enumeración completa de ejes + evidencia + estructura de ledger + línea de aprobación en references/review-dispatch.md. Criterios:

• Brief con contexto frío, sin incluir sus propias conclusiones (alimentar a codex con mi juicio = anclaje; cambiar de modelo pero compartir cadena de razonamiento = el valor de la descorrelación se pierde).
• Señalar los ejes con mayor riesgo de fallo (recuperación ante caídas/concurrencia/rutas de banderas/degradación/contratos de seguridad/aislamiento multiinquilino/honestidad de métricas), para que codex escriba sondas activamente.
• Antes de revisar, enumerar las bifurcaciones de la ruta de ejecución (provider/mode, live vs rehidratar…), pedir a codex que verifique "qué ramas no se han cubierto".
• Las funciones de compuerta/disparo deben verificar under-fire (si se disparó cuando debía), no solo over-fire.
• El registro de revisión usa estructura de ledger, no solo añadir (blocking/queued/advisory/reparado/estancamiento se actualiza ronda a ronda); cada ronda de vuelta a revisar, volver a pegar los puntos de aceptación inmutables del objetivo original.
• Convergencia de tres categorías: Solo si queda blocking residual se continúa el ciclo; advisory → follow-up, no bloquear un push que ya está listo; no levantar un hallazgo ya juzgado anteriormente.
• Detección de estancamiento: El mismo hallazgo aparece repetidamente = atasco, se debe converger o escalar a intervención humana, no intercambiar golpes indefinidamente.
• Durante la revisión, omp no debe tocar el mismo worktree (codex ejecutando pruebas dentro contaminaría las conclusiones).

3. Disciplina de cambios

• Compuerta de banderas: Los cambios de comportamiento por defecto se esconden detrás de una bandera de entorno, por defecto OFF = cambio cero a nivel de byte; excepción: las reparaciones aprobadas por ReOpen pueden ser ON por defecto (el objetivo debe justificarlo). Las mejoras de rendimiento/experimentales siempre OFF.
• measure-before-more / medir antes de decidir: Después del primer corte, la restricción vinculante cambia de persona — medir primero antes de decidir el segundo corte, no aplicar múltiples palancas basándose en cálculos. Lo mismo para corregir bugs: antes de actuar, verificar ① el bug realmente se puede reproducir en el estado actual, ② el valor observado está realmente restringido por algún mecanismo (observación 5 < límite 10 ⇒ el límite no es la restricción), ③ la ejecución realmente llegó al código que sospechas (leer código solo encuentra candidatos, "la ejecución llegó aquí" requiere registro/trace). Si la restricción vinculante no está probada, primero enviar instrumentación + volver a probar, no enviar reparaciones especulativas (evidencia: tres rondas de lectura de código infiriendo un "colgado" que no existía, cada ronda desmentida por datos reales). Falsos bugs comunes: fuente de datos incorrecta (tabla vacía tomada como real / cadena de registro incorrecta / sesión incorrecta), "no recibí" (cliente) ≠ "no envié" (servidor).
• Commit local, push/PR requiere aprobación explícita del usuario; una aprobación cubre solo esa vez.
• Honestidad en la verificación: Entrega en tres partes — qué se verificó (realmente ejecutado) / qué no se verificó / riesgo residual. Los pasos simulados localmente (LLM real, cola real) se marcan explícitamente, la verificación posterior al despliegue la completa operaciones. Evidencia: la simulación local de LLM provocó que una corrutina no esperada escapara a producción.
• Ruta de verificación delegada ≠ ruta real (válido para backend/agent/frontend): mock / simulación / stream smoke todo verde ≠ la ruta real es válida — verificar según la ruta de despliegue real, no tomar la verificación delegada como real; la ruta real a menudo no es la misma que la que simulaste (ejemplo de frontend en §7: la tarjeta va por execute/async no execute/stream, tres fases verdes aún así ReOpen). El más importante: No simular el límite que estás verificando — hacer stub de la función bajo prueba = prueba con cero información, justo tapa el bug; el E2E de la aplicación real es la puerta de "comprobable" (evidencia: en un día, 4 bugs pasaron revisión + pruebas unitarias, solo el E2E los atrapó).
• Volver a leer los archivos que cambiarán antes de editar: Después de rebase / otro agente modifica el mismo worktree / acabas de ejecutar una operación git que modifica archivos, la vista de archivos en contexto está obsoleta — volver a leer antes de modificar. Las herramientas con barandilla de read-before-edit bloquearán la edición obsoleta (reportan must be read first no es un bug, es que te protegen de sobrescribir los cambios de otro con una vista desactualizada); las que no tienen barandilla sobrescribirán silenciosamente, peor. No intercalar comandos que modifican archivos entre lectura y edición.

4. Acceso a entornos indirectos (modo agente de operaciones)

Para entornos inaccesibles (prod, bibliotecas de ejecución dev independientes) no adivinar — escribir prompt de investigación autocontenido (plantilla references/ops-prompt-template.md, colocar en docs/orchestration/<NOMBRE>_PROMPT.md) para que el usuario lo transmita al agente de operaciones. Puntos clave (escribir rutas de solo lectura fijas / SQL completo / valores esperados + reglas de juicio completas / formato de informe fijo / solo metadatos sensibles) en esa plantilla. Criterio: El informe de operaciones tiene prioridad sobre sus propias inferencias — cuando el sitio contradice el código HEAD, primero sospechar deriva de construcción (se desplegó una versión anterior), luego sospechar de su propio análisis de flujo de control.

5. Registro de estado y ritmo

• docs/orchestration/ es la fuente de verdad (SoT): *_GOAL / *_FINDINGS|IMPL_omp / *_REVIEW_codex / *_PROMPT / *_RESULT, con nombre que incluye el número de tarea y evidencia completa file:line. Ciclo de vida: al cerrar, mover el documento a archive/ (README añade línea de índice); solo viven los que están en ejecución/en espera; los documentos solo se crean, nunca mueren → lo vivo y lo histórico se mezclan (evidencia: un proyecto acumuló 38 antes de la primera limpieza).
• memory: un archivo por workstream + una línea de índice (estado/PR/riesgos abiertos/próximo paso de entrada), actualizar obligatoriamente antes de "comprimir/esperar entrada externa". memory es privada del orquestador, los agentes/nuevas sesiones solo pueden leer docs — actualizar solo memory sin sincronizar docs = la capa de gobierno compartida se pudre (evidencia: un proyecto tuvo ACTIVE_CONTEXT congelado 4 días, convirtiéndose en papel mojado). Tres divisiones: docs almacenan la instantánea de estado compartida por todos los agentes (qué/por qué), ACCESS.local.md almacena cómo conectarse + credenciales (cómo llegar, incluye secretos gitignored, ver repo-governance-bootstrap), memory almacena lecciones privadas del orquestador + punteros de entrada. La memoria de trabajo a corto plazo (borrador de tarea actual/progreso/pendientes) no entra en estas tres categorías — vive en la ventana de contexto o en un /tmp NOTES temporal, desechable, no meter en memory (contamina la capa privada entre sesiones) ni en ACTIVE_CONTEXT (es una instantánea de cierre, no un borrador).
  • Disciplina de escritura (no esperar a la retrospectiva): La descarga anterior se hace mientras se trabaja — al escribir memory, introducir los detalles fácticos en ACCESS/docs de inmediato, no acumular para la retrospectiva. Las disciplinas de alta frecuencia que no se pueden recordar solo con el texto de la skill se respaldan con un hook PostToolUse (capa forzada que compensa la caída de prominencia; plantilla en repo-governance-bootstrap).
• Ritual de retrospectiva (activado por eventos: cierre / antes de comprimir / cualquier ReOpen propuesto activamente) — es una LISTA DE VERIFICACIÓN, no improvisación. Al oír "retrospectiva / cierre / handoff" → leer references/retrospective.md y marcar los siete pasos uno por uno, no improvisar de memoria (la versión improvisada parece completa pero omite pasos de gobierno pesados — evidencia 2026-06-26: se pidió "ritual de retrospectiva" pero se improvisó, omitiendo la revisión del estado del roadmap + reescritura completa de ACTIVE_CONTEXT + gobierno de contexto).
  • Puerta dura (no se puede declarar finalizado sin pasar): Ejecutar bash references/retro-check.sh --base <rama> --docs <dir-docs> --memory <MEMORIA.md> verificación mecánica (ramas fusionadas sin worktree huérfano / ACTIVE_CONTEXT reescrito hoy / roadmap activo recientemente / MEMORIA no excede líneas); solo verifica lo mecánico, lo semántico depende de ti.
• Limpieza de huérfanos: Cerrar sesiones de trabajo finalizadas (las que tienen contexto clave y están en pausa se conservan); buscar huérfanos creados por agentes — docker ps / ps / trabajos en segundo plano. Para compose temporal, usar trap/finally down --remove-orphans; prohibir while True desnudo en repro (usar bucle acotado/deadline). Evidencia: un repro en bucle infinito giró en vacío 2.5 días, 65% CPU.

6. Sistema de tareas (seguimiento externo de tareas: Jira / Linear / Feishu bitable, etc.)

• Usar la CLI/API del sistema de tareas para leer/escribir tareas; la máquina de estados se define según el proyecto (pendiente/en progreso/comprobable/completado/bloqueado/ReOpen).
• Estándar de cierre: reparación → verificación E2E → subir evidencia de captura de pantalla como adjunto de la tarea (el revisor puede comparar de un vistazo) → una línea de conclusión → cambiar estado.
• ReOpen: primero obtener evidencia, luego reparar — el mecanismo de la ronda anterior "reparado" puede no ser la restricción vinculante en absoluto.
• No mantener un segundo libro de contabilidad de tareas en los documentos de gobierno: El sistema externo es la SoT de las tareas, el roadmap es solo su capa de mapeo. Los detalles de las reglas (usar ID externo / especificar SoT / cuándo crear un número interno de RD) los implementa repo-governance-bootstrap con "sistema de tareas externo primero".

7. Verificación de fixes de frontend (depuración en navegador)

Después de asignar una tarea de frontend, disciplina de verificación: la revisión de código + las pruebas unitarias no son suficientes, se debe ver el renderizado real en el navegador; y mock / tramas SSE / local todo correcto ≠ el usuario real puede verlo — el cierre requiere iniciar sesión en la aplicación real desplegada, ejecutar un ciclo real y capturar una captura de pantalla para que cuente (ruta de verificación delegada ≠ ruta real, ejemplo de frontend, principio general en §3). E2E es verificación, no ocupa el contexto principal del orquestador — delegar a un subagente con MCP de navegador (ejemplo de frontend de §0 "no ejecutar E2E largos uno mismo"). Metodología completa (MCP principal CLI complemento, a11y primero, panel de red para diagnosticar bugs de conectividad, CLI para capturar SSE, cierre de entrega, delegación de E2E a subagente, trampas de iniciar servicio local en el archivo AGENTS.md del proyecto) en references/frontend-verify.md.

8. Lista de incorporación para nuevos proyectos

Seis pasos para incorporar un nuevo proyecto (iniciar esqueleto de gobierno → complementar límites de delegación → crear directorio de orquestación → primera tarea siguiendo el flujo completo de §1 → crear entrada de memory de estilo de trabajo → crear DECISION_QUEUE) en references/onboarding-checklist.md.

9. Atención del principal y cola de decisiones (reducción de carga cognitiva)

Implementación de la tercera regla de hierro. El objetivo no es que el principal decida menos, sino que solo decida lo pesado (estratégico/irreversible/dinero/valor), cada uno con opciones masticadas, y que nunca tenga que recordar. Metodología completa (siete mecanismos + tablero de delegación + modos de fallo + atribución de origen honesta + plantilla de copy-paste) en references/decision-queue.md. Esta sección solo deja los puntos importantes:

• Cola de decisiones única docs/DECISION_QUEUE.md: mantenida por el orquestador, solo lectura para el principal. 🔴necesita su decisión/🟡yo impulso/💤estacionado/✅limpio. Garantía de integridad=única cara, no almacenar en otro sitio, no perder silenciosamente (premisa de confianza, si no, la descarga falla). Cada 🔴 con recomendación + silencio por defecto + desencadenante de revisita.
• Delegación de tres niveles: T0 hazlo directamente (reversible/autorizado/sin juicio de valor) · T1 hazlo + registra una línea (reversible pero vale la pena informar, se puede vetar) · T2 pregunta antes de actuar (irreversible/externo, estratégico/prioridad/dinero/valor, ambigüedad real con bajada sustancial). Reducir carga = mover más a T1, usar menos T2 como compuerta síncrona.
• Silencio por defecto: El principal no responde → reversible avanza según el defecto escrito, irreversible siempre HOLD (nunca cruzar automáticamente lo irreversible).
• Los demás mecanismos (agregar disparadores / paquetes de actualización por lotes / heartbeat / revisita de HELD / pudrición de cola / no mezclar gobierno de tres capas) en references/decision-queue.md.