n0ctx/dag-engineering

DAG Engineering

Divide tareas grandes de ingeniería en subtareas (nodos) con dependencias. Cada nodo es implementado por un subagente en su propio worktree y rama. El agente principal los integra y verifica uno por uno en un worktree de integración. Las reparaciones también respetan este aislamiento; los subagentes no modifican ni hacen commit en el worktree de integración. El agente principal se encarga de la investigación, planificación, despacho, integración, coordinación de reparaciones y la verificación final. Los subagentes de investigación solo leen y responden preguntas específicas. Los subagentes de nodos primero refinan sus pasos, luego implementan y hacen commit. Los subagentes de revisión solo leen y revisan.

La profundidad de la investigación, el número de subagentes y el alcance de la verificación dependen de la complejidad real de la tarea. No se deben crear subagentes cuando no haya trabajo independiente para ellos.

Al despachar cualquier subagente en Codex, establecer explícitamente fork_turns="none".

0. Continuar un plan existente

Antes de empezar, verificar .dag/ en el área de trabajo principal. Si existe un plan con estado "plan en progreso", leerlo y, combinándolo con el estado real de Git, continuar desde el progreso actual sin redividir el trabajo. Si el plan no coincide con el estado de Git, corregir el plan basándose en el estado de código verificado.

1. Si el worktree de integración tiene un MERGE_HEAD (git -C <integracion-wt> rev-parse -q --verify MERGE_HEAD): la integración se interrumpió y el resultado es desconocido. Ejecutar git merge --abort y reintegrar ese nodo como submitted.
2. Revisar cada nodo individualmente:
   • done: Confirmar que el commit del nodo se ha fusionado en la rama de integración (git -C <integracion-wt> merge-base --is-ancestor <commit> HEAD). Si es así, no repetir la ejecución.
   • submitted: Si el commit del nodo ya está fusionado en la rama de integración, marcarlo directamente como done (los commits de fusión solo se producen tras la verificación). En caso contrario, integrar según el paso 6.
   • running: Si el agente de esta sesión aún está ejecutándose, esperar. Si el agente ya no existe, revisar los commits y cambios sin commit en el worktree del nodo y despachar un nuevo agente al mismo worktree para continuar desde el progreso actual, sin crear un nuevo worktree.
   • blocked: Leer la razón y determinar si la condición ya se ha resuelto.
   • pending: Despachar según el paso 5. Si el nodo aún está escrito en el formato antiguo (objetivo, alcance, pasos, verificación, validación), reescribirlo con la plantilla del paso 4 antes de despachar.
3. Si todos los nodos están done: continuar desde el paso 7.

Cuando el estado no esté claro, no eliminar worktrees, ramas ni cambios sin commit.

1. Crear el worktree de integración

Para cada DAG, crear un worktree y una rama de integración. Solo el agente principal escribe en él; el área de trabajo principal no se modifica.

git worktree add "../<repo>-<plan-id>" -b "dag/<plan-id>"

• <plan-id>: usar una descripción corta en kebab-case para este trabajo. Si la rama o el directorio ya existen, elegir un nombre diferente.
• Si el área de trabajo principal tiene cambios sin commit, informar al usuario de que estos cambios no se incluirán en el worktree y dejar que el usuario decida si hacer commit o continuar.
• Si los comandos de verificación dependen de pasos de instalación (ej. node_modules, entorno virtual), completar la instalación en el worktree de integración primero.
• Registrar el commit de inicio (git rev-parse HEAD). La revisión general se basará en este commit.

2. Investigación y diseño clave

Orden: Análisis de requisitos → Investigación de código dirigida → Diseño clave unificado.

El agente principal debe localizar la implementación existente, los módulos relacionados, las relaciones de llamada y las pruebas basándose en los requisitos. Debe enumerar las preguntas desconocidas que afecten a la planificación. Si las ambigüedades pueden cambiar el objetivo, el alcance o los criterios de aceptación, preguntar al usuario primero. El resto de incertidumbres se anotan en la sección "Suposiciones" del plan.

Cuando haya múltiples preguntas de investigación independientes, despachar subagentes de investigación de solo lectura en paralelo en el mismo mensaje. Si las preguntas son pocas o interdependientes, el agente principal investiga por sí mismo. Dividir la investigación por preguntas específicas (implementación existente y reutilización, interfaces clave y cadenas de llamadas, estado compartido y recursos externos, pruebas y restricciones de ingeniería, etc.), no por directorios de forma mecánica. Los subagentes de investigación leen directamente el worktree de integración; no necesitan su propio worktree. Las instrucciones deben incluir:

Investigación de solo lectura en <integracion-wt>, no modificar ningún archivo, no despachar otros agentes. Objetivo: <...>. Alcance: <...>. Preguntas a responder: . Detener cuando se hayan respondido las preguntas, sin hacer exploración fuera del alcance. Informar solo: hechos clave y su ubicación (archivo:símbolo), implementación existente reutilizable, restricciones de ingeniería, elementos no confirmados; distinguir entre hechos confirmados y conjeturas.

El agente principal integra los resultados, maneja conclusiones contradictorias e investiga solo las brechas que afectan a la planificación. Detener la investigación cuando los hechos sean suficientes para escribir el goal, scope, verify y stop de los nodos. Los detalles de los steps se dejan para que los subagentes de los nodos los refinen al comenzar (paso 5). La investigación durante la planificación solo debe llegar a la profundidad necesaria para definir los límites de los nodos: usar consultas estructurales (archivos y líneas, relaciones de llamada, aristas de dependencia, entradas de lista de verificación) para responder, sin leer implementaciones de funciones. Entender la implementación es tarea del subagente del nodo.

Los hechos entre módulos (quién llama a un símbolo, de qué depende un módulo, el tamaño de un conjunto de archivos con sus dependencias) deben buscarse bajo demanda con Language Server, ast-grep o búsquedas, sin leer todo el código fuente para deducirlos. Una vez encontrado un hecho, registrarlo para reutilizarlo: el agente principal o el subagente de investigación lo escriben en el resultado de refine o en una nota del nodo relevante. El subagente del nodo enumera los nuevos hechos entre nodos que encuentre en su informe; el agente principal los registra en el refine de los nodos downstream que los necesiten. Cuando un nodo downstream comience, primero revisará estos registros. Si los registros son insuficientes o pueden estar desactualizados (porque el código relevante ha sido modificado por nodos posteriores), entonces los volverá a buscar.

A continuación, determinar y escribir en la sección "Diseño clave" del plan:

• Comportamiento objetivo y no objetivo.
• Implementaciones existentes, dependencias o capacidades de la plataforma que se reutilizan directamente.
• Asignación de funcionalidades y código.
• Interfaces, estructuras de datos y restricciones arquitectónicas que deben ser consistentes entre nodos.
• Recursos compartidos y condiciones de integración.

Solo fijar el diseño necesario para la colaboración entre nodos. La implementación interna de cada nodo se deja a su subagente. No añadir abstracciones para necesidades futuras. No reimplementar capacidades existentes.

3. División del DAG

• Granularidad de los nodos: Cada nodo debe representar un comportamiento verificable de forma independiente, incluyendo lo necesario para que sea ejecutable y verificable. La configuración, el andamiaje (scaffolding) y la documentación se fusionan en un nodo si solo los usa un nodo. Si los usan varios nodos, se convierten en un nodo upstream. El trabajo altamente acoplado, que al dividirse crearía un estado intermedio no verificable o requeriría muchas modificaciones repetidas, debe fusionarse en un solo nodo. El trabajo débilmente acoplado debe dividirse para permitir el paralelismo. No forzar la división solo para aumentar el paralelismo.
• Verificación elemento por elemento: Cuando un nodo necesita cubrir muchos archivos o elementos, definir primero los elementos a verificar y los criterios de aceptación elemento por elemento. Delegar la verificación de rangos verificables de forma independiente a subagentes de solo lectura en paralelo, y después de resumir las brechas, proceder a la implementación. Si las conclusiones de una verificación anterior siguen siendo válidas, reutilizarlas directamente sin escanear de nuevo.
• Dependencias: Escribir una dependencia solo si el nodo downstream realmente necesita el código, las decisiones o el comportamiento verificado del nodo upstream, o si el fallo del nodo upstream invalidaría el nodo downstream. Si las interfaces compartidas ya están determinadas en el diseño clave y ambas partes pueden implementar y probar por separado, no escribir dependencias. Esto permite el paralelismo y la verificación de la integración real se encargará de comprobar la conexión real. No inventar dependencias solo para controlar el orden.
• Conflictos: Marcar como conflictivos solo los nodos que no tienen dependencias pero no pueden ejecutarse de forma segura al mismo tiempo: modificaciones que se afectan lógicamente entre sí, recursos compartidos de ejecución (bases de datos, puertos), recursos que deben asignarse secuencialmente (números de migración). La superposición normal de cambios en el mismo archivo no se considera un conflicto; se permite el paralelismo y lo manejará la fusión de Git. Marcar como conflicto solo cuando la superposición sea densa y el costo de fusionar sea claramente mayor que hacerlo en serie.
• Esquemas aún no determinados que requieren experimentación: Crear un nodo de investigación para llegar a una conclusión, del cual dependerán los nodos downstream.

Escribir cada nodo siguiendo la plantilla del paso 4. Durante la planificación, escribir goal, scope, verify, stop y refine. Los steps los detallará el subagente del nodo al comenzar (paso 5), aunque los pasos que ya se puedan determinar durante la planificación se pueden escribir de antemano.

• goal: Una o dos frases que describan qué comportamiento se logrará al completar el nodo.
• scope: Los archivos o directorios que se pueden modificar, las partes que explícitamente no se deben modificar, y las restricciones de diseño clave y de negocio que se deben respetar.
• verify: Resultados de aceptación observables y comandos reales ejecutables, incluyendo las guardas existentes afectadas por los cambios de este nodo (como verificación de volúmenes de documentación, complejidad de código, comprobaciones de capas y contratos). Priorizar puntos de entrada estrechos; solo ejecutar la verificación completa si no hay puntos de entrada estrechos. La verificación completa no debe ejecutarse concurrentemente con otras verificaciones.
• stop: Condiciones específicas de este nodo para detenerse e informar, como "no se puede determinar la pertenencia según las reglas" o "tal interfaz no existe". Las condiciones generales ya están en las instrucciones de despacho, no repetirlas aquí.
• refine: Escribir los elementos que los steps necesitan aclarar, como consultas ejecutables. Ejemplo: "Listar todos los elementos bajo el prefijo X y sus módulos no procesados de los que dependen" o "Listar todos los llamadores de Y". El subagente del nodo los completará en la primera fase de su trabajo. Si ya se encontraron conclusiones durante la planificación o la investigación, escribirlas directamente en refine y marcarlas como "ya verificado". El subagente las usará directamente sin reinvestigar. Dejar solo las preguntas no respondidas como consultas en refine. Si no hay nada pendiente, escribir "Ninguno".
• steps: Pasos ordenados, cada uno haciendo una cosa verificable, escritos a nivel de módulo, comando e interfaz: qué hacer, dónde hacerlo, cuál es el comportamiento externo. La descripción a nivel de función solo se usa en los límites: cuando un mismo archivo debe asignarse a diferentes nodos, o cuando hay disputa sobre la pertenencia de una función. En ese caso, enumerar las funciones a cada lado del límite.

Los valores, condiciones y límites ya determinados de los materiales fuente y el diseño clave deben escribirse directamente en los nodos relevantes, sin dejar que el subagente los deduzca. Los archivos, símbolos y comandos deben provenir del código real, no deben inventarse. Las siguientes redacciones deben corregirse:

• Descripciones no ejecutables como "implementar según sea necesario" o "manejar casos límite".
• Criterios de aceptación que solo repiten la acción de implementación, como "X está implementado".
• Verificaciones de comportamiento que solo se basan en la existencia de un archivo, la capacidad de importarlo o una búsqueda por palabras clave.
• Clasificaciones o decisiones que solo citan nombres de reglas o secciones de documentos (ej. "juzgar según D7"), sin escribir la acción por defecto y las condiciones de excepción.

Antes de despachar, revisar el plan para responder a dos conjuntos de preguntas.

Cuando el plan esté completo, ¿se alcanzarán necesariamente los criterios de aceptación globales? Buscar brechas según los siguientes puntos:

1. El alcance debe enumerarse desde las fuentes reales, no solo deducirse de los requisitos: código involucrado, configuración, archivos fuera del repositorio y estado de la máquina local, métodos de instalación e implementación, otras plataformas de ejecución, llamadores externos. Cada elemento debe pertenecer exactamente a un nodo, o escribirse como no objetivo.
2. Cada verificación debe ser válida: debe poder ejecutarse en el entorno objetivo; durante la ejecución no debe escribir en bases de datos de producción ni en sistemas externos (si es necesario, el nodo debe especificar el método de aislamiento); pasar la verificación debe implicar la conclusión de aceptación correspondiente; la herramienta utilizada para la verificación debe estar verificada.
3. Cualquier exención temporal, capa de compatibilidad, datos transitorios y herramientas introducidos por el plan deben tener un nodo responsable de eliminarlos o convertirlos en permanentes.
4. Para caminos que involucren sistemas externos, cambios en entornos de producción o que solo se ejecuten en otras plataformas, al menos un nodo debe ejecutarlos una vez en el entorno real antes de la entrega.
5. Las interfaces y la arquitectura entre nodos deben ser consistentes. Las dependencias y conflictos no deben tener errores ni omisiones. Debe haber un nodo responsable de la integración entre nodos. El refine de cada nodo debe poder determinar los steps, y el verify debe poder ejecutarse.

Las brechas se convierten en nodos. Si no se puede complementar, o si el costo de hacerlo requiere una decisión del usuario, escribir en la sección "Brechas de integridad" del plan y dejar que el usuario decida.

¿Se está perdiendo el tiempo en diseño?

6. Cada nodo debe tener un consumidor downstream de su producto, incluida su verificación. Eliminar los nodos que no tengan consumidores.
7. Los nodos que requieran la decisión o presencia del usuario, o que cambien el comportamiento existente, no deben bloquear a otros nodos. Si hay nodos downstream que deben esperar, dividir el nodo en una parte que no cambie el comportamiento (que se hace primero) y una parte que sí lo haga (que se hace después).
8. Cualquier capacidad o herramienta que vayan a utilizar dos o más nodos debe convertirse en un nodo upstream, para que cada nodo no tenga que implementarla por separado. Revisar cada nodo para ver en qué se basa su verify. Si dos o más nodos van a utilizar el mismo medio de verificación (comparación nuevo-viejo, reproducción, comparación de resultados, etc.), también convertirlo en una herramienta de nodo upstream. El verify de este nodo debe incluir una muestra con una diferencia conocida para demostrar que la herramienta puede detectar la diferencia. Si dos o más nodos necesitan consultar repetidamente un mismo conjunto grande de información (lista, tabla de mapeo, documento de decisión) y el proyecto no tiene un punto de entrada para consultas bajo demanda, también crear un nodo upstream para proporcionar ese punto de entrada.
9. Estimar la cantidad de código que cada nodo necesita leer y modificar (basándose en los archivos dentro de su alcance, más el código del que depende que aún no se ha procesado). Si la cantidad es demasiado grande para que un subagente la maneje de forma fiable, o si abarca módulos no relacionados que podrían verificarse de forma independiente, dividir el nodo. Si el acoplamiento es fuerte y dividirlo crearía un estado intermedio no verificable, no dividir aunque la cantidad sea grande. El número de líneas es solo una guía, no se establece un umbral fijo. Si no se puede estimar, escribir los elementos a calcular en refine y dejar que el subagente del nodo los estime en su primera fase. La decisión de cómo dividir debe tomarse antes de crear el worktree, siguiendo el paso 5: primero despachar un subagente de investigación para la estimación.
10. No reimplementar capacidades existentes. No debe haber divisiones innecesarias o sobrediseño. Los nodos que se puedan ejecutar en paralelo de forma segura no deben estar serializados.

Cuando haya 5 nodos o menos, el agente principal los revisa. Cuando haya más de 5, escribir primero el borrador según el paso 4 en .dag/<plan-id>.md, luego despachar un subagente de solo lectura para que lo revise. Proporcionarle solo el plan, los requisitos y la ubicación del código, no el razonamiento del agente principal:

Revisión de solo lectura de <ruta-del-plan>, no modificar ningún archivo, no despachar otros agentes. Requisitos: <requisitos originales o su ubicación>. Código: <integracion-wt>. Revisar cada uno de los siguientes puntos: <texto original de los puntos 1-10 anteriores>. Informar solo: brechas para completar el objetivo, diseños que pierden el tiempo, elementos que requieren decisión del usuario; para cada uno escribir la ubicación, la evidencia (archivo:símbolo, salida de comando o texto del plan) y la sugerencia de modificación mínima, distinguiendo entre problemas confirmados y conjeturas.

El agente principal solo modifica los problemas que tienen evidencia concreta.

4. Guardar el plan

Escribir en .dag/<plan-id>.md dentro del área de trabajo principal, no dentro de ningún worktree, para evitar que se incluya en un commit. Si .dag/ no está en .gitignore, añadirlo a .git/info/exclude.

# <plan-id>

- Objetivo:
- Criterios de aceptación globales:
- No objetivos:
- Suposiciones:
- Brechas de integridad: <parte que aún no se puede garantizar incluso después de completar el plan, y la decisión del usuario; si no hay, escribir "Ninguna">
- Diseño clave:
- Estado del plan: en progreso
- Worktree de integración: <ruta>   Rama: dag/<plan-id>   Inicio: <sha>
- Registro de interfaces: `.dag/<plan-id>-interfaces.md`

## Nodos

### N1 <título>
#### goal
#### scope
#### steps
<El subagente del nodo los detallará al comenzar>
#### verify
#### stop
#### refine
#### state
- Dependencias: ninguna
- Conflictos: ninguno
- Estado: pending
- worktree:   Rama:   Commit:

## Registro de ejecución
- N1: <sha del commit de fusión> <resumen del resultado>. <Reparaciones, anomalías o problemas restantes; si no hay, no escribir>

El archivo de registro de interfaces se coloca junto al plan. Cada vez que se fusione un nodo, se añade una sección. Los subagentes de nodos pueden leerlo, pero solo en modo lectura:

## N1 (<sha del commit de fusión>)
- <interfaz, nombre y ubicación>: <forma y uso>

El registro de ejecución solo contiene los resultados y los problemas restantes. Las interfaces externas se escriben en el archivo de registro de interfaces. Los hechos entre nodos se escriben en el refine de los nodos downstream que los necesiten. Los detalles de las diferencias, etc., se dejan en el mensaje de commit del nodo y en el archivo de informe.

El goal, scope, steps, verify, stop y refine se pasan al subagente del nodo. El state solo lo usa el agente principal.

Valores de estado:

• pending: No despachado.
• running: El subagente está implementando o reparando.
• submitted: El subagente ha hecho commit, esperando integración.
• done: Fusionado en la rama de integración y aprobado por el agente principal.
• blocked: No se puede continuar; la razón se anota en el registro de ejecución.

El plan solo lo modifica el agente principal. Cada cambio de estado se actualiza inmediatamente; es la base para continuar el trabajo entre sesiones.

Después de guardar, mostrar al usuario un resumen de los nodos, las dependencias, los nodos que se pueden ejecutar en paralelo, las brechas de integridad y todos los elementos que requieran una decisión del usuario (listarlos todos a la vez, no por rondas de preguntas). Si el usuario solo solicitó un plan, detenerse aquí. De lo contrario, continuar con la ejecución.

5. Despacho dinámico

Los nodos pending cuyas dependencias estén todas done y que no tengan conflictos con nodos running/submitted son nodos listos. Encontrar todos los nodos listos y despacharlos en paralelo en el mismo mensaje. No hay un límite de concurrencia fijo; la concurrencia real está limitada por la herramienta de agente y el entorno. Cada vez que un nodo pasa a done, buscar inmediatamente nuevos nodos listos y despacharlos, sin esperar a que terminen otros nodos independientes.

Antes de despachar cada nodo, el agente principal solo realiza una verificación previa: listar las decisiones, interfaces, nombres y reglas upstream que utiliza este nodo, y confirmar que ya están fusionadas en HEAD de la rama de integración. Si alguno de estos elementos todavía puede ser cambiado por nodos running o pending, añadir la dependencia a este nodo y no despacharlo todavía.

Las consultas en refine las realiza el subagente del nodo en la primera fase de su trabajo; el agente principal no las ejecuta. Hay dos excepciones, en las que primero se despacha un subagente de investigación de solo lectura según el paso 2, y solo se recogen las conclusiones:

• El nodo puede tener que dividirse en varios nodos paralelizables, y la forma de dividir debe decidirse antes de crear el worktree: el subagente de investigación estima el tamaño y el acoplamiento según refine, y el agente principal lo divide según el punto 9 del paso 3 antes de despachar cada parte.
• Varios nodos listos necesitan investigar la misma pregunta: despachar un subagente de investigación para responder a todos, no uno por nodo.

A continuación, crear el worktree del nodo desde el HEAD actual de la rama de integración (el último commit de integración verificado). Escribir la ruta y la rama en el plan y marcar el nodo como running:

git -C <integracion-wt> worktree add "../<repo>-<plan-id>-<node-id>" -b "dag-node/<plan-id>/<node-id>" HEAD

Cuando los pasos de verificación dependan de pasos de instalación, requerir en las instrucciones que el subagente del nodo complete la instalación en su propio worktree primero.

Las instrucciones para el subagente del nodo deben organizarse en el siguiente orden y contener solo esto:

1. Ruta y rama del worktree.
2. Texto original de goal, scope, steps (si los hay), verify, stop y refine de ese nodo en el plan.
3. Nota (solo en las instrucciones, no en el plan):
   • Ruta absoluta al archivo de registro de interfaces. Solo la ruta, no repetir las interfaces upstream en las instrucciones.
   • Suplementos específicos de este nodo: límites y decisiones tomadas por el agente principal, texto original de decisiones del usuario, hechos upstream solo relevantes para este nodo, problemas conocidos, comandos para buscar información. Generalmente no más de ~20 líneas; si el material supera las ~200 líneas o solo se necesita una parte, proporcionar extractos o comandos de consulta, no solo la ruta del archivo. Las reglas ya escritas en los archivos de documentación del proyecto que el subagente carga automáticamente no se repiten. Si un comando de verify produce una salida muy larga, indicar qué parte mirar (por ejemplo, las líneas de resumen al final).
   • Ruta del archivo de informe: .dag/<plan-id>-reports/<node-id>.md (ruta absoluta en el área de trabajo principal).
4. Los siguientes requisitos, colocados al final de las instrucciones:

Trabaja únicamente dentro del worktree dado. No operes en la rama de integración, ni en las ramas o worktrees de otros nodos. No despaches otros agentes. No modifiques archivos bajo .dag/ excepto el archivo de informe indicado en las instrucciones. No leas archivos bajo .dag/ excepto el archivo de registro de interfaces. Las instrucciones de inicio y finalización escritas para la sesión principal en los archivos de documentación del proyecto (leer el plan, ejecutar comprobaciones de estado, reanudar el plan, etc.) no se aplican a ti. Para buscar información, usa primero los comandos y extractos proporcionados en la nota. Si la nota no lo cubre, puedes buscarlo por tu cuenta. No leas el plan completo, documentos de decisión o listas grandes.

Trabaja en dos fases. Fase uno: según refine, determina los hechos (usa directamente las conclusiones marcadas como "ya verificado" en refine; solo responde las preguntas no respondidas). Sin cambiar el goal, las interfaces ni el scope, determina los steps (escritos a nivel de módulo, comando e interfaz; cuando un mismo archivo deba compartirse con otros nodos, enumera las funciones a cada lado del límite). Estima la cantidad de código que necesitas leer y modificar. Detente e informa un resumen de no más de ~30 líneas (borrador de steps, estimación, sugerencia de división, elementos que requieren decisión del agente principal o del usuario) si ocurre alguna de las siguientes situaciones: no se puede determinar el límite o la pertenencia; es necesario cambiar una interfaz entre nodos o modificar un archivo fuera del scope; el código real entra en conflicto con la descripción del nodo; la cantidad es demasiado grande para que un subagente la maneje de forma fiable, o abarca módulos que podrían verificarse de forma independiente; ocurre una condición listada en stop. Si no ocurre nada de esto, no te detengas; entra directamente en la fase dos. El resumen se incluirá en el informe final.

Fase dos: Implementa según los steps. Sin cambiar el goal, las interfaces ni el scope, decide por ti mismo la forma local de implementación. Ejecuta los comandos de verify. Si pasan, haz commit de todos los cambios del nodo con el mensaje <plan-id>/<nodo>: <resumen>. Confirma que git status está limpio. No hagas commit si la verificación falla. Si durante la fase dos ocurre alguna de las condiciones de parada enumeradas en la fase uno, o si la cantidad real supera aproximadamente el doble de la estimación de la fase uno, detente e informa. No te expandas por tu cuenta. Si la parte completada puede pasar los comandos aplicables de verify, haz commit primero. Si no, mantenlo en el worktree sin commit. Informa el trabajo completado y el restante.

Al finalizar o detenerte, escribe el informe completo (resumen de cambios, comandos de verificación y sus resultados completos, diferencias, explicación de desviaciones) en el archivo de informe. Devuelve solo al agente principal un resumen de no más de ~40 líneas: estado (DONE: completado y verificado; DONE_WITH_CONCERNS: completado pero con dudas; BLOCKED: no se puede completar o se detuvo), sha del commit, una línea con el resultado de la verificación, las interfaces externas nuevas o modificadas, los nuevos hechos entre nodos descubiertos (ej. qué otros módulos usan un símbolo, la forma real de una interfaz), las razones de las dudas o el bloqueo, y los elementos que requieren una decisión.

Cuando el subagente se detenga en la fase uno para devolver un resumen, el agente principal verifica los límites y los elementos que requieren una decisión (si necesita decisión del usuario, preguntar primero). Escribe los steps confirmados de nuevo en el plan. Luego, usando la capacidad de continuación de la herramienta de agente (SendMessage de Claude Code; Codex envía una entrada posterior al mismo agente), dejar que el mismo subagente continúe con la fase dos. No despachar un nuevo agente para evitar que tenga que releer el código que ya ha leído. Si se sugiere una división, seguir la regla del paso 6 "el plan en sí tiene un error": el agente original continúa con una parte, y la otra parte se despacha como un nuevo nodo desde el paso 5. Si no se puede continuar con el agente original, despachar un nuevo agente en el mismo worktree para continuar, adjuntando el resumen.

Después de que el subagente devuelva el commit, escribir el sha del commit en el plan, marcar el nodo como submitted y proceder al paso 6.

Reglas de espera (aplicables también a subagentes de investigación y revisión):

• Si hay trabajo independiente concreto y que no entre en conflicto con el alcance del subagente (ej. integrar nodos ya enviados), completarlo primero; si no, entrar en espera nativa.
• Claude Code usa la notificación de finalización de agentes en segundo plano o la espera nativa. Codex llama directamente a la herramienta de agente, no la coloca dentro de functions.exec o functions.wait; establecer timeout_ms=600000 en wait_agent. Si el parámetro de la herramienta no admite ese valor, usar la espera máxima permitida. Si la herramienta solo puede devolver resultados en lote, manejarlo según su capacidad, no simular notificaciones inexistentes.
• No usar bucles con sleep corto, ni consultar listas de agentes, ni revisar el estado de Git repetidamente en lugar de esperar. No acortar la espera para enviar actualizaciones de progreso.
• Procesar los resultados o los mensajes del usuario inmediatamente después de recibirlos. Un tiempo de espera agotado no significa fallo; seguir esperando. No redespachar nodos que aún se están ejecutando.

6. Integración y verificación nodo por nodo

El agente principal integra un nodo submitted a la vez en el worktree de integración. Los demás subagentes continúan su trabajo. No confiar ciegamente en los informes de los subagentes:

1. git -C <integracion-wt> diff --stat HEAD...<rama-del-nodo>: Verificar que todos los archivos modificados están dentro del scope del nodo. Verificar que git status en el worktree del nodo no tiene cambios sin commit. Luego, revisar el diff completo de los archivos compartidos con otros nodos (módulos comunes, configuración, líneas base de guardas, listas de verificación, pruebas de contrato) para asegurar que cumplen con el goal y el diseño clave. El nuevo código propio del nodo se evalúa mediante la verificación del paso 3 y el comportamiento real, no leyendo línea por línea. Si se necesitan detalles, leer las secciones relevantes del archivo de informe.
2. Fusionar pero sin hacer commit todavía:

   git -C <integracion-wt> merge --no-ff --no-commit "dag-node/<plan-id>/<node-id>"
   

3. Ejecutar en el worktree de integración los comandos de verify de este nodo, así como las comprobaciones de integración afectadas por la fusión. Verificar cada criterio de aceptación. Al menos, verificar un comportamiento real. Las nuevas fallas en las guardas afectadas se reparan en este nodo, no se dejan para la verificación final. Registrar las fallas existentes por separado, no relajar los umbrales o las líneas base. No es necesario ejecutar todo el suite de pruebas cada vez.
4. Si todo pasa: git -C <integracion-wt> commit --no-edit, marcar el nodo como done, escribir una línea en el registro de ejecución, agregar las interfaces externas al archivo de registro de interfaces, escribir los hechos entre nodos en el refine de los nodos downstream que los necesiten, y luego volver al paso 5 para despachar los nuevos nodos desbloqueados.

Para verificaciones de cobertura de lista de verificación, se debe registrar cada conclusión verificada, los elementos pendientes y las brechas. Solo se puede marcar como done cuando todo el alcance declarado haya sido verificado y cumpla con los criterios de aceptación. La existencia del archivo, un contenido no vacío o un muestreo aprobado no reemplazan la cobertura elemento por elemento.

Si la fusión produce conflictos: si la superposición es normal y la intención de ambas partes está clara, el agente principal la resuelve directamente y luego procede al paso 3.

Para otros conflictos o comprobaciones fallidas: deshacer la fusión no completada (git -C <integracion-wt> merge --abort). La rama de integración se mantiene en el último commit verificado. El commit del nodo se mantiene en la rama del nodo. Manejar según la causa del problema:

• Defecto de implementación del nodo: Volver a marcar el nodo como running. Devolver el problema específico al subagente del nodo original para que lo repare en su worktree y lo vuelva a enviar. Si el agente original no se puede reanudar, despachar un nuevo agente en el mismo worktree para continuar. El agente principal no debe, por defecto, reescribir la implementación del nodo.
• Conflicto que requiere que el nodo haga referencia a los últimos resultados de integración: Hacer que el subagente del nodo fusione dag/<plan-id> en su propio worktree, resuelva el conflicto, vuelva a verificar y haga commit.
• Conflicto de interfaz o lógica entre nodos: El agente principal determina el diseño correcto, actualiza el diseño clave del plan y los nodos afectados, y luego los entrega a los subagentes de los nodos relevantes para que se ajusten.
• El plan en sí tiene un error (scope, steps, dependencias o verify no coinciden con el código real): Modificar solo los nodos afectados, las dependencias y la verificación basándose en los nuevos hechos del código. Conservar los resultados ya completados que sean válidos. No rediseñar todo el DAG. Si la modificación afecta los criterios de aceptación globales o los no objetivos, preguntar primero al usuario.
• El subagente informa DONE_WITH_CONCERNS: Si las dudas afectan los criterios de aceptación, tratarlo como fallo. De lo contrario, integrar con normalidad y anotar las dudas en el registro de ejecución.
• El subagente se detiene porque la cantidad real supera la estimación: Si la parte ya enviada se puede verificar de forma independiente, cambiar el goal, scope y verify de este nodo a la parte completada e integrarla según este paso. El trabajo restante se divide en un nuevo nodo siguiendo la regla "el plan en sí tiene un error" y se despacha desde el paso 5. Si la parte ya enviada no se puede verificar de forma independiente, no integrar. Mantener el nodo como running. Escribir el trabajo restante en los steps del nodo y despachar un nuevo agente en el mismo worktree para continuar desde el progreso actual.
• El subagente informa BLOCKED o el nodo no puede continuar: Marcar como blocked y registrar la razón específica. No despachar los nodos que dependen de él. Los demás nodos continúan. Si no hay nodos listos o en ejecución, pero aún hay nodos blocked, detenerse e informar al usuario sobre la razón del bloqueo. Esperar la decisión del usuario antes de continuar. No pasar al paso 7.

Después de que un nodo pase a done, limpiar su worktree y su rama. Si el worktree tiene cambios sin commit, detenerse y revisar. No usar --force ni -D:

git -C <node-wt> status --porcelain
git -C <integracion-wt> worktree remove "<node-wt>"
git -C <integracion-wt> branch -d "dag-node/<plan-id>/<node-id>"

Los nodos blocked, en reparación o con estado poco claro conservan su worktree y rama.

7. Revisión general

Después de que todos los nodos estén done, despachar un subagente de solo lectura para que revise todos los cambios en la rama de integración:

Revisión de solo lectura de todos los cambios <commit-inicial>..HEAD en <integracion-wt>, no modificar ningún archivo, no despachar otros agentes. Revisar en comparación con los siguientes objetivos, criterios de aceptación globales y no objetivos: cobertura de requisitos, consistencia de interfaces y comportamientos entre nodos, implementaciones duplicadas, desviaciones arquitectónicas del diseño clave, defectos de corrección, código de depuración o temporal restante, pruebas importantes faltantes o que no cubren realmente el comportamiento declarado. Para cada problema, proporcionar ubicación, evidencia y los nodos involucrados, distinguiendo entre problemas confirmados y conjeturas. Además, listar los elementos que requieren una decisión del usuario.

Adjuntar el objetivo, los criterios de aceptación globales, los no objetivos y el diseño clave del plan a las instrucciones.

Después de verificar cada problema, el agente principal programa la reparación según la causa: los problemas que requieren implementación se escriben como nodos de reparación (ej. F1) en el plan, y se despachan e integran según los pasos 5-6. Los problemas locales y obvios (ej. declaraciones de depuración olvidadas) pueden ser corregidos directamente por el agente principal en el worktree de integración y luego hacer commit. No decidir por su cuenta sobre los elementos que requieren una decisión del usuario; escribirlos en el informe.

8. Verificación final e informe

El agente principal realiza las siguientes comprobaciones en el worktree de integración:

1. Revisar el diff completo de <commit-inicial>..HEAD para confirmar que no hay cambios fuera del objetivo del plan.
2. Ejecutar los comandos de verify de todos los nodos, así como las pruebas, las compilaciones y las comprobaciones de lint que cubren los módulos modificados en el proyecto.
3. Verificar cada criterio de aceptación global.

Si las comprobaciones fallan: si el problema está dentro del objetivo del plan, repararlo según la regla de causa del paso 7 y luego volver a comprobar. Si el problema está fuera del objetivo del plan (ej. pruebas que ya fallaban desde el inicio), no repararlo, solo anotarlo en el informe. Cuando todo esté completo, cambiar el "Estado del plan" a "Completado".

El informe final debe incluir: los nodos completados y sus commits de fusión correspondientes, los hallazgos de la revisión y su tratamiento, los resultados de la verificación, los elementos no completados o que presentan riesgo, los elementos que requieren una decisión del usuario, la ruta y la rama del worktree de integración, y los worktrees de nodos conservados. La fusión en la rama objetivo y la eliminación del worktree de integración solo se realizan cuando el usuario lo solicite.