Repo Task Proof Loop

¿Qué hace Repo Task Proof Loop?

Usa este skill cuando el usuario quiera un flujo de trabajo de implementación repetible y auditable para una tarea de codificación no trivial, especialmente una característica, refactorización, migración o corrección de errores que deba dejar evidencia local en .agent/tasks/<TASK_ID>/.

Todos los artefactos de la tarea creados por este flujo de trabajo deben permanecer dentro del repositorio.

Cuando los ejemplos a continuación mencionen scripts/task_loop.py, esa ruta es relativa a la raíz de este skill. Ejecútalo mientras tu directorio de trabajo del shell esté dentro del repositorio de destino.

Qué hace este skill

1. Inicializa una carpeta de tarea estricta local al repositorio bajo .agent/tasks/<TASK_ID>/
2. Siembra o actualiza los archivos de artefacto requeridos
3. Instala plantillas de subagentes de Codex y Claude con alcance de proyecto en .codex/agents/ y .claude/agents/
4. Actualiza AGENTS.md (línea base de Codex) y el archivo guía de Claude del repositorio (CLAUDE.md o .claude/CLAUDE.md) con un bloque gestionado que explica el flujo de trabajo
5. Guía al agente a través de un bucle estricto:
   • congelación de especificación
   • implementación del constructor
   • empaquetado de evidencia
   • verificación en sesión nueva
   • corrección mínima
   • verificación en sesión nueva otra vez hasta que se apruebe (PASS)

Ver:

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

Comandos que este skill soporta

Trata las siguientes palabras como comandos cuando el usuario invoque este skill:

• init <TASK_ID>: crear .agent/tasks/<TASK_ID>/, instalar o refrescar plantillas de subagentes, y actualizar AGENTS.md más el archivo guía de Claude del repositorio
• freeze <TASK_ID>: crear o refinar spec.md a partir de la tarea del usuario, archivo de tarea y guía del repositorio
• build <TASK_ID>: implementar la tarea contra la especificación congelada
• evidence <TASK_ID>: crear o refrescar evidence.md, evidence.json y artefactos crudos sin cambiar el código de producción
• verify <TASK_ID>: ejecutar una pasada de verificación en sesión nueva y escribir verdict.json, además de problems.md cuando sea necesario
• fix <TASK_ID>: aplicar el conjunto de correcciones seguras más pequeñas de problems.md, luego refrescar el paquete de evidencia
• run <TASK_ID>: ejecutar el bucle completo desde la congelación de especificación hasta la verificación
• status <TASK_ID>: resumir el estado actual del artefacto

Si el usuario no proporciona un comando, inferir el siguiente paso del estado del repositorio:

• Si la carpeta de tarea no existe, ejecutar init primero. Si el usuario claramente quiere solo la inicialización, detenerse ahí. De lo contrario, después de que init tenga éxito y exista .agent/tasks/<TASK_ID>/spec.md, continuar reevaluando el estado del repositorio en el mismo turno. No superponer init con freeze, build, evidence, verify, fix, validate, status o trabajo de subagentes.
• Si spec.md falta o es solo un marcador de posición, hacer freeze
• Si la implementación aún no está completa, hacer build
• Si la evidencia está obsoleta o falta, hacer evidence
• Si no hay un veredicto reciente, hacer verify
• Si el veredicto no es PASS, hacer fix

Paso de inicialización

Ejecuta el inicializador empaquetado desde la raíz del repositorio o el directorio de trabajo actual dentro del repositorio:

scripts/task_loop.py init --task-id <TASK_ID>

Siembra opcional de tareas:

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "Texto de la tarea del usuario"

El inicializador:

• resolverá la raíz del repositorio
• creará .agent/tasks/<TASK_ID>/
• creará todos los artefactos requeridos, incluidos marcadores de posición bajo raw/
• instalará archivos de subagentes con alcance de proyecto
• insertará o refrescará bloques de flujo de trabajo gestionados en AGENTS.md y el archivo guía de Claude del repositorio

Para Codex, el inicializador mantiene su bloque de flujo de trabajo gestionado en AGENTS.md de la raíz del repositorio. Codex también soporta AGENTS.override.md y nombres de archivo guía de respaldo configurados; los archivos anidados más cercanos al código aún tienen prioridad, y este skill intencionalmente no los sobrescribe. Si init crea o reescribe AGENTS.md durante una sesión activa de Codex, inicia una nueva sesión de Codex antes de confiar en las instrucciones actualizadas. Codex toma una instantánea de la guía de documentación del proyecto al inicio de la sesión.

Para Claude Code, el inicializador mantiene su bloque de flujo de trabajo gestionado en CLAUDE.md de la raíz del repositorio. Claude Code también soporta .claude/CLAUDE.md, .claude/rules/*.md y CLAUDE.local.md, pero este skill trata CLAUDE.md de la raíz como la guía principal del proyecto porque Claude la muestra directamente.

En Claude Code, si init acaba de escribir o refrescar .claude/agents/* durante la sesión actual, no asumas que esos agentes actualizados ya están disponibles a mitad de sesión.

Trata init como un requisito previo serial. Nunca lo superpongas con freeze, build, evidence, verify, fix, validate, status o la creación de subagentes.

Flujo de trabajo predeterminado para tareas pesadas

Para tareas grandes, mantén la solicitud del usuario simple. En Codex, continúa de forma serial a menos que el usuario solicite explícitamente delegación o trabajo de agente en paralelo; después de esa autorización, el skill puede elegir la configuración interna de subagentes automáticamente cuando la superficie de producto actual soporte delegación y la forma de la tarea lo justifique.

Secuencia delegada preferida

1. Ejecuta init <TASK_ID> si es necesario. Espera a que termine, luego confirma que .agent/tasks/<TASK_ID>/spec.md y la estructura de tareas local al repositorio existen antes de continuar.
2. Solo después de que init se complete, crea exactamente un subagente congelador de especificación y espera a que termine
3. Crea exactamente un subagente constructor y déjalo implementar
4. Continúa con la misma sesión del constructor para el empaquetado de evidencia
5. Crea exactamente un subagente verificador en sesión nueva y espera a que termine
6. Si el veredicto no es PASS, crea exactamente un subagente corrector
7. Crea un subagente verificador en sesión nueva otra vez
8. Repite los pasos 6-7 hasta que el verificador devuelva PASS o el usuario detenga el bucle

Expansión adaptativa de Codex

Usa esto solo después de que el usuario haya autorizado explícitamente la delegación de Codex y la tarea sea lo suficientemente amplia como para beneficiarse de trabajo paralelo acotado. Usa la secuencia serial más simple anterior para tareas estrechas.

Buenos candidatos:

• múltiples preguntas independientes sobre la base de código deben responderse antes de que la especificación sea estable
• la implementación se puede dividir en ámbitos de escritura disjuntos
• la prueba requiere varias verificaciones de solo lectura independientes en diferentes superficies

Patrón de Codex:

1. init permanece serial.
2. Si la tarea aún es ambigua, expande hasta 3 subagentes explorer incorporados en paralelo. Dale a cada uno una sola pregunta, subsistema o ámbito de ruta. Espera a que terminen, luego congela la especificación.
3. Crea un subagente congelador de especificación y espera a que termine.
4. Crea un subagente task-builder como propietario de la integración.
5. Si la implementación se divide limpiamente, el padre también puede crear subagentes worker incorporados acotados en paralelo. Cada trabajador debe tener propiedad explícita de archivo o módulo y no debe escribir evidence.md, evidence.json, verdict.json o problems.md.
6. Usa send_input o la superficie de seguimiento equivalente para mantener vivo al constructor de integración para el empaquetado de evidencia. El constructor sigue siendo el único propietario del paquete de evidencia.
7. Si se necesita más prueba, el padre puede expandir un pequeño conjunto acotado de subagentes explorer de solo lectura para reejecutar verificaciones disjuntas o inspeccionar brechas de prueba separadas en paralelo. Esos subagentes pueden reportar comandos, salidas y hallazgos, pero no escriben verdict.json.
8. Ejecuta exactamente un subagente verificador en sesión nueva para cada pasada de verificación.

Comportamiento de la plataforma

• En Codex, mantén la ruta normal serial y con auto-modo primero después de init. Evita mostrar los detalles de delegación a menos que afecten materialmente el trabajo.
• En Codex, crea subagentes acotados solo cuando el usuario solicite explícitamente subagentes, delegación o trabajo de agente en paralelo.
• En Codex, una vez que la delegación esté autorizada, el skill puede elegir los roles secundarios coincidentes y si mantenerse un subagente a la vez o usar expansión acotada. El usuario no debería necesitar nombrar roles secundarios específicos o comandos de barra.
• En Codex, la creación de subagentes sigue siendo una acción explícita del padre/orquestador. Si la superficie actual de Codex bloquea la delegación, dilo brevemente solo cuando afecte materialmente el trabajo, luego continúa de forma serial.
• En Codex, mantén el árbol de tareas poco profundo. La sesión padre debe crear subagentes de investigación, constructor, corrector y verificador directamente en lugar de pedirle a un subagente de tarea personalizado que orqueste más subagentes.
• En Codex, una vez que la delegación esté autorizada, elige entre delegación un subagente a la vez y expansión acotada basada en la especificación congelada, la forma del repositorio y la superficie de delegación actual. Mantén init, la propiedad de la evidencia y cada pasada de verificación serializados en cualquier caso.
• En Codex, mantén la expansión de subagentes modesta y basada en oleadas. Prefiere hasta 3 subagentes ayudantes en paralelo a la vez, espera a que esa oleada termine, luego decide la siguiente fase.
• En Codex, el explorer incorporado es la primera opción para el descubrimiento de repositorio de solo lectura y sondeos de prueba. El worker incorporado es apropiado para implementación disjunta acotada o reejecuciones de verificación cuando puedas asignar propiedad explícita.
• En Codex, reutiliza el subagente constructor activo para el empaquetado de evidencia enviándole una instrucción de seguimiento. Las pasadas de verificación deben usar un subagente o sesión nueva; no satisfagas la novedad del verificador reanudando un verificador anterior. Los subagentes constructor y corrector pueden reutilizarse o reanudarse cuando quieras intencionalmente ese contexto de vuelta.
• En Codex, inspecciona la lista actual de hilos secundarios antes de reutilizar o reanudar un subagente. Usa /agent en Codex CLI o cualquier superficie de inventario de hilos secundarios equivalente disponible en la superficie de producto actual de Codex.
• En Codex, la UI de lista de verificación/plan de update_plan es solo una guía de sesión opcional. Es útil para mostrar el progreso en vivo, pero no es la fuente de verdad para este flujo de trabajo.
• En Claude Code, el skill debe decidir si permanecer en el hilo principal o dejar que la sesión principal de Claude delegue automáticamente la fase actual a un subagente incorporado o de proyecto después de init. El usuario no debería necesitar solicitar un subagente específico de Claude o modo de delegación por separado.
• En Claude Code, TodoWrite o la UI visible de tarea/lista de tareas es solo una pantalla de progreso de sesión opcional. Puede ayudar con el seguimiento en vivo en la sesión actual, pero no es la fuente de verdad para este flujo de trabajo.
• En Claude Code, prefiere los subagentes de proyecto instalados desde .claude/agents/, con descripciones escritas como condiciones de activación proactivas para la fase coincidente del bucle de prueba. La sesión principal de Claude enruta según la solicitud de tarea, las descripciones de subagentes y el contexto actual, así que mantén cada mensaje de fase claro en lenguaje natural. Reutiliza el mismo subagente constructor para el paso de evidencia de forma predeterminada. Solo ejecuta un constructor nuevo en modo solo evidencia si la sesión del constructor original no está disponible o la descartaste intencionalmente. Si init acaba de refrescar .claude/agents/* durante la sesión actual de Claude, recurre al hilo principal o a los agentes ya visibles en lugar de asumir que los refrescados están disponibles de inmediato.
• En Claude Code, mantén la orquestación plana: la delegación automática de la sesión principal está bien, pero los agentes del flujo de trabajo del bucle de prueba son roles de hoja. La sesión padre debe ser propietaria de las transiciones de fase del bucle de prueba en lugar de pedirle a un subagente de tarea personalizado que cree otro.
• En Claude Code, el estado duradero canónico es siempre el conjunto de artefactos local al repositorio bajo .agent/tasks/<TASK_ID>/, especialmente spec.md, evidence.md, evidence.json, verdict.json y problems.md.
• Si los subagentes no están disponibles, preserva la misma separación de roles en sesiones separadas o cambios de modo claros en la sesión actual.

Usa los mensajes de rol exactos de references/COMMANDS.md.

Requisitos de congelación de especificación

spec.md debe contener al menos:

• declaración original de la tarea
• criterios de aceptación explícitos etiquetados como AC1, AC2, ...
• restricciones
• no objetivos

También puede incluir:

• fuentes de guía del repositorio
• plan de verificación
• supuestos resueltos de manera estrecha a partir de la solicitud del usuario

No edites código de producción durante la congelación de especificación.

Requisitos de empaquetado de evidencia

evidence.md y evidence.json deben juzgar cada criterio de aceptación de forma independiente con uno de:

• PASS
• FAIL
• UNKNOWN

El empaquetado de evidencia puede ejecutar verificaciones faltantes, pero no debe seguir cambiando el código de producción.

Cada PASS debe citar prueba concreta como:

• rutas de archivo
• comandos ejecutados
• códigos de salida
• resúmenes de salida
• rutas de artefactos bajo raw/

No afirmes PASS general en el paquete de evidencia a menos que cada criterio de aceptación sea PASS.

Requisitos de verificación en sesión nueva

El verificador debe ser una sesión nueva o un subagente nuevo. En Codex, no satisfagas este requisito reanudando un subagente verificador anterior.

El verificador debe juzgar el estado actual del repositorio y los resultados de reejecuciones actuales, no la narrativa del constructor.

El verificador escribe:

• .agent/tasks/<TASK_ID>/verdict.json
• .agent/tasks/<TASK_ID>/problems.md solo cuando el veredicto general no es PASS

problems.md debe incluir, para cada criterio no-PASS:

• id y texto del criterio
• estado
• por qué no está probado
• pasos mínimos de reproducción
• esperado vs real
• archivos afectados
• corrección segura más pequeña
• pista correctiva en 1-3 oraciones

El verificador no debe modificar el código de producción ni rellenar el paquete de evidencia.

Requisitos del corrector

El corrector lee solo:

• spec.md
• verdict.json
• problems.md

El corrector debe:

• reconfirmar cada problema listado en la base de código antes de editar
• hacer el conjunto de cambios seguros más pequeño
• evitar regresiones en criterios ya aprobados
• regenerar evidence.md, evidence.json y artefactos crudos
• detenerse sin escribir una aprobación final

Validación

Antes de afirmar que el flujo de trabajo está correctamente inicializado o que el conjunto de artefactos está completo, ejecuta:

scripts/task_loop.py validate --task-id <TASK_ID>

Ejecuta validate solo después de que init haya terminado por completo. Si reporta que la inicialización está en progreso, espera y vuelve a ejecutarlo en lugar de tratar ese resultado como un fallo estable de la tarea.

Para un resumen rápido:

scripts/task_loop.py status --task-id <TASK_ID>

Ejecuta status solo después de que init haya terminado por completo cuando necesites un estado de tarea estable. Si reporta init_in_progress: true, trata eso como una condición de reintentar más tarde.

Barreras de protección

• Mantén .agent/tasks/<TASK_ID>/ dentro del repositorio
• Trata la UI de lista de verificación/tareas de Codex como progreso efímero solo; el estado duradero son los artefactos locales
• No confíes en listas de verificación efímeras para la fuente de verdad del flujo de trabajo
• Cuando realices ediciones en el código de producción, asegúrate de que los artefactos de prueba se regeneren
• No superpongas la inicialización (init) con ninguna otra operación de flujo de trabajo
• No edites código de producción durante la congelación de especificación o el empaquetado de evidencia
• El verificador no debe modificar el código de producción