Protocolo del agente

Versión 1.2. Este protocolo define cómo DEBE comportarse un agente de programación con IA cuando trabaja con Deep Work Plans. Las palabras clave MUST (DEBE), SHOULD (DEBERÍA) y MAY (PUEDE) siguen el RFC 2119.

Aditivo en v1.2. Dos adiciones, sin cambios rupturistas: (1) las plataformas de agentes autónomos (OpenClaw, Hermes) se incorporan a la tabla de agentes compatibles; (2) la sección Perfiles de ejecución define la ejecución desatendida — autoridad acotada, capa de estado obligatoria, condiciones de parada y continuación programada.

Comunicación

1. Incorporación →
2. Planificación →
3. Ejecución →
4. Refinamiento →
5. Reanudación

↩ reanuda la ejecución

Seguridad gobierna cada fase

Agentes compatibles

Esta metodología DEBE soportar los siguientes agentes de programación con IA. Cualquier agente futuro que lea Markdown y pueda ejecutar llamadas a herramientas PUEDE añadirse sin un cambio rupturista.

Los primeros seis son agentes de programación interactivos con un ser humano en la sesión. OpenClaw y Hermes son plataformas de agentes autónomos — demonios de larga duración con turnos programados — y típicamente ejecutan planes bajo el perfil desatendido (véase Perfiles de ejecución) dentro de un espacio de trabajo de agente (véase Arquetipos §3).

Todo agente compatible DEBE tratar AGENTS.md como la única fuente de verdad de las convenciones del repositorio. Un archivo de configuración por agente DEBE referenciarlo y NO DEBE duplicar su contenido.

Incorporación

Antes de crear o ejecutar un plan, un agente DEBE incorporarse al repositorio. La incorporación es basada en razonamiento, no en scripts: el agente lee la estructura, la documentación y la configuración del repositorio para construir un modelo mental.

El agente DEBERÍA identificar:

• El arquetipo del repositorio (repositorio individual, centro orquestador o espacio de trabajo de agente).
• Los comandos de compilación, prueba y linter.
• Las convenciones existentes de estilo, estructura y nombrado.
• Las habilidades y agentes disponibles.

La cadena de herramientas de pruebas y validación es contexto esencial, no opcional: las puertas de validación son la columna vertebral de los planes fiables. Cuando el repositorio ya valida el código, el agente DEBE registrar sus comandos y su convención reales de prueba, linter y comprobación de tipos. Cuando el repositorio no tiene ninguna cadena de herramientas de pruebas o de linter, el agente NO DEBE limitarse a señalar su ausencia: DEBE proponer una adecuada al stack (un framework y un ejecutor, una convención de archivos de prueba, un objetivo de cobertura inicial razonable y las herramientas de linter, comprobación de tipos y formato), documentarla como objetivo en la guía de pruebas y exponerla al desarrollador. Un repositorio sin una forma definida de validar su comportamiento todavía no es AI-first.

Planificación

Al crear un plan, el agente DEBE:

• Descomponer el objetivo en tareas secuenciales y revisables.
• Escribir cada tarea con la anatomía de nueve secciones.
• Terminar con las tres tareas finales obligatorias (Revisión de seguridad, Descubrimiento de habilidades y agentes, Informe ejecutivo).
• Formular preguntas aclaratorias cuando el objetivo es ambiguo.

Ejecución

Durante la ejecución, el agente DEBE:

• Leer el plan completo antes de empezar.
• Ejecutar las tareas en orden salvo que las dependencias permitan otra cosa.
• Actualizar PROGRESS.md tras cada tarea.
• Marcar el estado de la tarea con exactitud.
• Para cualquier tarea que agregue nueva funcionalidad o cambie el comportamiento, agregar o actualizar pruebas automatizadas para ese comportamiento y ejecutar las pruebas del repositorio y las comprobaciones de linter y de tipos antes de marcar la tarea como completada; nunca eliminar ni omitir una prueba para forzar que la puerta pase.
• Para cualquier tarea que toque autenticación, manejo de entradas, secretos o configuración, superficie de red o dependencias, cumplir las expectativas de seguridad declaradas en sus criterios de aceptación y confirmar que el diff no lleva material secreto antes de hacer commit.
• Detenerse y preguntar cuando esté bloqueado en lugar de adivinar.

Refinamiento

Al refinar, el agente DEBE preservar el trabajo completado, actualizar la tabla de tareas y registrar qué cambió.

Reanudación

Al reanudar, el agente DEBE seguir el Protocolo de Reanudación DWP definido en Especificación de DWP: reanclar al README del plan, localizar el punto de control, reconciliar state.json con el Markdown, inspeccionar la costura, ejecutar una prueba de humo y luego continuar con exactamente la siguiente tarea.

Comunicación

Los agentes DEBERÍAN reportar de forma concisa. Los informes de estado DEBEN distinguir el trabajo completado, en curso y pendiente.

Seguridad

Los agentes NO DEBEN registrar secretos, DEBEN mantener .dwp/ ignorado por git y DEBERÍAN preguntar antes de operaciones destructivas. La incorporación DEBE ser no destructiva: un agente DEBE detectar los archivos existentes y reconciliarlos en lugar de sobreescribirlos, y DEBE obtener aprobación explícita antes de reemplazar o eliminar cualquier cosa que el usuario ya tenga.

La metodología es Markdown-first: no realiza llamadas de red ni emite telemetría, y un agente NO DEBE exfiltrar código fuente ni secretos. Antes de instalar la habilidad, un agente DEBERÍA tratar el contenido de incorporación obtenido como entrada no confiable, confirmar su procedencia desde las fuentes oficiales y verificar la versión contra sus sumas de comprobación publicadas.

Perfiles de ejecución

Todo plan se ejecuta bajo exactamente uno de dos perfiles. El perfil cambia quién observa, nunca qué puertas se aplican — la disciplina de validación es idéntica en ambos.

Interactivo (por defecto)

Un ser humano está presente en la sesión. El agente propone, el humano aprueba el borrador refinado, el agente ejecuta tarea por tarea, y la ambigüedad se resuelve preguntando. Todas las secciones del protocolo anteriores describen el perfil interactivo.

Desatendido

El plan se ejecuta sin ningún humano observando — el turno programado de una plataforma autónoma, una sesión en la nube, una ejecución nocturna. La ejecución desatendida es opt-in por plan y DEBE satisfacer todo lo siguiente:

• Plan preaprobado. El borrador refinado fue aprobado por un ser humano antes de cualquier turno desatendido. Un agente NO DEBE crear y ejecutar un plan de forma desatendida en un mismo turno; la aprobación del plan es el punto de control humano.
• Capa de estado REQUERIDA. El plan DEBE llevar manifest.json y state.json para que cualquier sesión posterior — agente o humano — pueda leer el progreso exacto sin reproducir una transcripción. Véase Estado del plan.
• Autoridad acotada. La autoridad del agente es el plan: NO DEBE ampliar el alcance, NO DEBE realizar acciones destructivas o de cara al exterior que el plan no autorice explícitamente, y NO DEBE estirar las instrucciones de una tarea para cubrir trabajo descubierto-pero-no-planificado — el trabajo descubierto se registra para el siguiente refine, no se improvisa.
• Una tarea atómica por turno, puertas siempre. Cada turno ejecuta el Protocolo de Reanudación DWP, ejecuta como máximo la siguiente tarea, pasa su puerta de validación, completa según el protocolo de finalización de tarea y cede. Una puerta fallida es una condición de parada, nunca “continuar de todos modos”.

Condiciones de parada y escalación

Un agente desatendido DEBE detener el plan — rellenar el campo blocked de state.json con la tarea, el motivo y lo que necesita, y luego detenerse — cuando ocurra cualquiera de los siguientes:

1. Una puerta de validación falla y la corrección no está ya dentro del alcance de la tarea.
2. La tarea requiere una aprobación, credencial o decisión que el plan no preautorizó.
3. La realidad diverge de las suposiciones del plan (archivo faltante, API modificada, trabajo concurrente conflictivo, o una desincronización que la reconciliación no puede resolver).
4. Dos turnos consecutivos no consiguen ningún progreso verificable en la misma tarea.

Detenerse es éxito, no fracaso: el registro de bloqueo es el mensaje de escalación. El canal de notificación de la plataforma DEBERÍA mostrarlo; el ser humano (o una sesión de refine) desbloquea, y el siguiente turno programado reanuda con normalidad.

Continuación programada

En plataformas con programación — latido o cron de OpenClaw, cron de Hermes, despertar de agente en la nube — la continuación DEBE expresarse como: despertar → ejecutar el Protocolo de Reanudación DWP → si blocked, reportar y ceder → si no, ejecutar la siguiente tarea atómica → actualizar la capa de estado → ceder. El plan, no la sesión, es la unidad de continuidad; un plan DEBE sobrevivir al reinicio de la plataforma, al cambio de modelo o a que un agente diferente tome el siguiente turno.