Especificación de DWP

Versión 4.0.0. Estado: estable. Este documento es la especificación normativa de la metodología Deep Work Plan (DWP). Las palabras clave MUST (DEBE), MUST NOT (NO DEBE), SHOULD (DEBERÍA), SHOULD NOT (NO DEBERÍA) y MAY (PUEDE) se interpretan según las describe el RFC 2119.

Aditivo en 2.4.0, sin cambios rupturistas. (1) La sección Superficie tocada — el contrato entre lo que una tarea cambia y lo que debe validarse, con selección de puerta por clase de riesgo (aislada / costura / compartida-núcleo / desconocida); (2) la validación completa pasa a ser un requisito de estado final que se ejecuta en el único Final Review obligatorio del plan, con reglas explícitas de reutilización de evidencia; (3) las decisiones de skills por tarea se mudan a la tarea que las origina, y el Reporte Ejecutivo pasa a ser opcional, a petición; (4) un flujo create consciente del modo — el modo trust materializa directamente conservando el análisis y las comprobaciones de calidad; (5) materialización de planes Lite primero — el create guiado produce un plan Lite directamente ejecutable en lugar de un borrador no ejecutable, promovible a un plan Full en cualquier momento (véase Planes Lite); y (6) una matriz de compatibilidad explícita: los planes y repositorios de versiones anteriores siguen siendo conformes.

Estándar 4.0.0. El salto de versión alinea el número del estándar con la línea de productos — 2.x es histórico y no existe un estándar 3.x — y no cambia ningún requisito respecto de 2.4.0. Los planes y repositorios de versiones anteriores siguen siendo conformes.

Definición

Un Deep Work Plan es un artefacto estructurado, basado solo en Markdown, que describe una tarea de ingeniería compleja descompuesta en unidades de trabajo secuenciales y revisables, diseñado para ser creado, ejecutado y mantenido por agentes de programación con IA que trabajan de forma autónoma.

DWP está guiado por especificación: el plan es la especificación, y los agentes DEBEN ejecutar contra sus criterios de aceptación y puertas de validación explícitos en lugar de improvisar. La especificación — no una transcripción de chat — es la fuente de verdad duradera, de modo que el trabajo es verificable y reanudable entre sesiones y agentes. Es además ingeniería de harness hecha portable: el contexto, el bucle de control, las salvaguardas y el estado reanudable que hacen fiable a un agente se instalan en el propio repositorio como Markdown plano, de modo que cualquier agente conforme PUEDE pilotar el repositorio sin un framework específico de una herramienta.

Flujo create — un solo paso, consciente del modo

El flujo create recoge una sola vez el objetivo, el contexto, las restricciones y el esquema de tareas, ejecuta su análisis de requisitos (alcance, orden de dependencias entre tareas, selección de validación a partir de la Superficie tocada, nivel de rigor proporcional) y luego materializa según el modo que eligió el desarrollador:

• Modo guiado (por defecto). El flujo materializa un plan Lite directamente — una propuesta compacta y ya ejecutable con registros de tarea {#task-N} en línea, revisable en una sola pasada — y pide al desarrollador que lo conserve como Lite, lo promueva a un plan Full, solicite cambios o se detenga. No se produce ningún borrador intermedio no ejecutable.
• Modo trust (trust / auto). El flujo materializa la representación elegida (Lite, o Lite seguido inmediatamente de la promoción a Full) directamente, sin paso de revisión — el desarrollador renunció a ella. El análisis de requisitos, el orden de dependencias y una comprobación de calidad del plan siguen ejecutándose: trust renuncia a la revisión, no al análisis. Un plan en modo trust se registra como preaprobado para ejecución desatendida.

Ambos modos deciden el formato del plan (Lite o Full) como parte del mismo análisis de requisitos, nunca como algo posterior. Véase Planes Lite para el ciclo de vida completo de representación, creación-y-selección, y promoción.

Estructura del plan

Un plan DEBE ser un directorio bajo .dwp/plans/ llamado PLAN_<slug>/, en una de dos representaciones:

• Full. El directorio DEBE contener README.md (resumen del plan, objetivo, tabla de tareas y estado), un archivo por tarea con el nombre <n>.task_<slug>.md, y PROGRESS.md (un registro continuo de la ejecución).
• Lite. Los registros de tarea, compactos y totalmente ejecutables, viven en línea dentro de README.md tras anclas estables {#task-N} en lugar de archivos de tarea separados — cada registro sigue llevando un objetivo, una Superficie tocada, criterios de aceptación, validación y un registro de finalización. PROGRESS.md sigue siendo REQUERIDO. Un plan Lite PUEDE promoverse a Full en cualquier momento. Véase Planes Lite para el ciclo de vida completo, en lugar de duplicarlo aquí.

Un plan PUEDE llevar adicionalmente la capa de estado legible por máquina: manifest.json (identidad estática, escrito una vez en la materialización) y state.json (estado de ejecución activo por tarea). La capa de estado es RECOMENDADA para planes nuevos y REQUERIDA para la ejecución desatendida y para espacios de trabajo de agente sin git. Véase Estado del plan.

Anatomía de la tarea

Archivo de tarea

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Cada archivo de tarea DEBE contener estas diez secciones, en orden:

1. Objetivo: una declaración de un párrafo de lo que logra la tarea.
2. Contexto: antecedentes, enlaces y por qué existe esta tarea.
3. Superficie tocada: el contrato entre lo que la tarea cambia y lo que debe validarse.
4. Pasos: acciones concretas y ordenadas que ejecutar.
5. Criterios de aceptación: una lista de condiciones que definen lo terminado.
6. Validación: comandos o pruebas que ejecutar para verificar, seleccionados a partir de la Superficie tocada.
7. Archivos: rutas que se espera crear o modificar.
8. Dependencias: otras tareas o requisitos externos.
9. Riesgos: qué podría salir mal y sus mitigaciones.
10. Finalización y registro: un marcador de estado más notas cronológicas.

Una tarea PUEDE incluir adicionalmente una sección Delta (RECOMENDADA para cambios de comportamiento en proyectos brownfield — véase más abajo) y una sección de Reversión (RECOMENDADA para migraciones, cambios de infraestructura o despliegues).

La Superficie tocada

La Superficie tocada es el contrato entre lo que una tarea cambia y lo que debe validarse. Existe para que la validación se seleccione por efecto, no por costumbre, y para que un lector posterior pueda ver por qué se eligió una puerta. Una tarea que cambia el comportamiento DEBE registrar:

• Superficie planificada: las rutas, módulos, paquetes o configuración que la tarea pretende cambiar, escrita antes de editar.
• Superficie real: la lista reconciliada tras editar, tomada del diff real. El agente DEBE reconciliar las superficies planificada y real antes de seleccionar la puerta.
• Consumidores afectados: módulos, paquetes o servicios que dependen de la superficie real, hasta donde el mapeo documentado del repositorio pueda establecerlo. Donde no pueda, la entrada DEBE decirlo.
• Clase de riesgo: una de: aislada (confinada a un módulo y sus pruebas); costura (altera un contrato, persistencia, enrutamiento, serialización, autenticación o el cableado del framework entre colaboradores); compartida/núcleo (importada ampliamente, o un cambio de dependencia, migración, configuración de build/pruebas, esquema o cadena de herramientas); desconocida (el mapeo falta, está desactualizado o está sin verificar).
• Mapeo de pruebas usado: qué mapeo o herramienta documentada produjo la selección.
• Puerta seleccionada y motivo: los comandos exactos y por qué cubren la superficie real.

Los archivos de configuración, esquemas, manifiestos de dependencias, plantillas, fixtures, migraciones y archivos de instrucciones de agente pueden cambiar el comportamiento y DEBEN clasificarse por su efecto, nunca por extensión de archivo. Una tarea que solo cambia prosa, comentarios o artefactos de investigación PUEDE declarar la superficie como no aplicable y aun así ejecuta las comprobaciones no runtime del repositorio.

La sección Delta (cambios brownfield)

La mayor parte del trabajo real modifica el comportamiento existente en lugar de crear comportamiento nuevo. Una tarea que cambia el funcionamiento de un sistema existente DEBERÍA llevar una sección Delta que describa el cambio como un contrato explícito de antes/después, usando tres encabezados de lista:

• ADDED — comportamiento que existe después de la tarea y no existía antes.
• MODIFIED — comportamiento que existe en ambos, expresado como was: … → now: ….
• REMOVED — comportamiento que existía antes y desaparece intencionalmente después.

Cada entrada DEBE ser comportamiento observable — la respuesta de un endpoint, un indicador CLI, un estado de UI, un valor por defecto — no un detalle de implementación. La sección Delta es el diff del revisor a nivel de comportamiento: los criterios de aceptación verifican las entradas ADDED/MODIFIED, y las entradas REMOVED son la licencia explícita para eliminar. Todo lo que no figure como REMOVED DEBE seguir funcionando.

Puertas de validación — seleccionadas por clase de riesgo

La validación es la puerta que convierte una afirmación de finalización en evidencia de ella: una tarea NO DEBE marcarse como completada hasta que cada comando de su sección de Validación se haya ejecutado y haya pasado. La puerta de una tarea que cambia el comportamiento se selecciona a partir de su Superficie tocada reconciliada, por clase de riesgo:

Un cambio de comportamiento DEBE producir una selección de pruebas no vacía y relevante — un selector inválido o un ejecutor que seleccionó cero pruebas no es cobertura. Donde el mapeo de pruebas del repositorio esté desactualizado, se deriva la invocación correcta y se registra la actualización del mapeo; un pequeño comando faltante nunca exige una ejecución completa de incorporación. Donde no exista una invocación acotada, aplica la suite completa aplicable — comportamiento heredado, nunca un error.

Cuando una tarea agrega nueva funcionalidad central o cambia de forma sustancial el comportamiento existente, sus criterios de aceptación DEBEN incluir cobertura de pruebas automatizadas para el comportamiento nuevo o modificado, y su validación ejecuta las pruebas del repositorio junto con las comprobaciones de linter, de tipos y de formato — no solo la compilación. Las pruebas existentes DEBEN seguir en verde.

Validación de estado final

Las puertas por tarea validan lo que cada tarea tocó; no sustituyen la validación del plan como conjunto. Antes de que un plan se complete, la validación completa aplicable del repositorio DEBE ejecutarse y pasar sobre el estado final relevante, tras el último cambio sustancial — en el Final Review. Las ejecuciones más amplias anteriores ocurren en los límites de integración o tras cambios compartidos/núcleo, no según un calendario basado en el conteo de tareas. Un resultado que pasa PUEDE reutilizarse solo con evidencia de que las entradas relevantes son equivalentes; de lo contrario se vuelve a ejecutar. Cada ejecución de puerta deja un registro conciso: comando, alcance, revisión, resultado y una ruta de evidencia.

Disciplina de seguridad

La seguridad es de primera clase del mismo modo que las pruebas, y sigue el mismo modelo de dos capas: disciplina por tarea mientras se realiza el trabajo, más el pase de seguridad del Final Review sobre todo el conjunto de cambios al final. Siempre que una tarea toca autenticación o autorización, el manejo de entradas, secretos o configuración, la superficie de red, de archivos o de shell, o dependencias:

• Sus criterios de aceptación DEBEN declarar las expectativas de seguridad del cambio — entrada validada y escapada, sin material secreto en el código ni en los fixtures, comprobaciones de autenticación preservadas o reforzadas —, de forma coherente con docs/SECURITY.md.
• Cada commit DEBE confirmarse libre de secretos o credenciales antes de incorporarse, incluidos los fixtures de pruebas y los ejemplos de documentación. Un secreto en un commit ya subido DEBE tratarse como filtrado y rotarse, no simplemente eliminarse.
• Donde el trabajo sensible a la seguridad sea sustancial, DEBERÍA colocarse una tarea de endurecimiento dedicada inmediatamente después de las tareas de implementación y antes de la tarea de pruebas exhaustivas, de modo que los hallazgos se corrijan antes de que las pruebas codifiquen el comportamiento y cada hallazgo se convierta en un caso de regresión en lugar de retrabajo.

Esta disciplina por tarea no sustituye al pase de seguridad del Final Review: las comprobaciones por tarea detectan los problemas en el commit donde nacen, mientras que la puerta final audita todo el plan — incluidas las propias tareas de pruebas y documentación.

Ciclo de vida del plan — el Final Review

Todo plan conforme redactado bajo esta versión termina con exactamente una tarea obligatoria: el Final Review (tarea N). Dos responsabilidades que versiones anteriores colocaban en tareas de cierre separadas se reubican: las decisiones de skills pasan a la tarea que produjo el patrón, y el Reporte Ejecutivo pasa a ser un artefacto opcional, a petición. Nada del pase de seguridad se relaja.

El Final Review DEBE, en orden:

(a) Pase de seguridad — revisar el conjunto completo acumulado de cambios del plan en busca de secretos codificados, riesgos de inyección, nueva superficie de ataque, autenticación debilitada y datos sensibles en registros o documentación; auditar las dependencias introducidas; verificar que docs/SECURITY.md siga reflejando la realidad; escribir el informe de revisión de seguridad incluso cuando esté limpio. Un hallazgo crítico se corrige — o el usuario lo acepta explícitamente — antes de que el plan se complete.

(b) Validación de estado final — la validación completa aplicable del repositorio se ejecuta y pasa sobre el estado final relevante.

(c) Reconciliación de skills — cada tarea lleva una disposición de skills y cada candidatura registrada tiene una disposición; no hay un segundo informe de descubrimiento.

(d) Finalización — reportar la finalización con entregables, evidencia de validación y limitaciones; ofrecer el Reporte Ejecutivo una sola vez. El plan queda completo responda o no la oferta.

El Final Review se ejecuta secuencialmente tras todas las demás tareas y nunca se coloca en un grupo paralelo.

Decisiones de skills por tarea

La pregunta “¿este trabajo creó un patrón reutilizable que merezca una skill o un agente?” se responde dentro de la tarea que produjo el patrón, mientras su evidencia está en contexto. La Finalización y registro de cada tarea lleva una disposición de skills: ninguna, actualizar una skill existente, crear un artefacto con nombre, o un aplazamiento con motivo. La autoría justificada ocurre dentro de esa tarea, antes de su puerta de validación y su commit, tras comprobar duplicados contra el catálogo existente.

Reporte ejecutivo — opcional, a petición

El Reporte Ejecutivo ya no es una tarea obligatoria. Al completar, el agente lo ofrece una vez; se genera solo bajo petición explícita, satisfecho a partir de evidencia duradera sin reproducir el plan. Sin respuesta, o en una ejecución desatendida, el plan queda completo sin generar el reporte.

Protocolo de finalización de tarea

Tras pasar la validación y antes de avanzar a la siguiente tarea, el agente DEBE, en orden: (1) marcar la tarea [x] en el README del plan; (2) incrementar el contador de estado del plan; (3) rellenar la sección Finalización y Registro de la tarea sin valores de marcador de posición; (4) añadir una entrada de 3-5 puntos en PROGRESS.md; (5) hacer commit (cuando el plan hace commits) con el formato {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) cuando el plan lleva la capa de estado, reescribir state.json de forma atómica — tarea completed, registros de puertas, registro de resultados, hash del commit.

Los seis pasos forman una transacción lógica. Un agente interrumpido a mitad del protocolo NO DEBE comenzar la siguiente tarea — debe terminar o deshacer la finalización parcial primero.

El protocolo de reanudación DWP

La reanudación DEBE ser posible únicamente a partir de los archivos del plan y del registro git, sin estado externo. En un workspace sin git — véase Arquetipos §3 — el state.json del plan es REQUERIDO y sustituye al registro git.

Un agente que reanuda — una sesión nueva, un agente diferente, un turno programado de un demonio o una sesión en la nube que despierta — DEBE realizar este ritual, en orden:

1. Reanclar. Leer el README del plan: objetivo, directrices globales, la lista de tareas.
2. Localizar el punto de control. Encontrar la primera tarea sin marcar en el README; leer el registro git y el estado de git (o el checkpoint de state.json donde git está ausente).
3. Reconciliar el estado. Donde exista state.json, compararlo con las casillas del README; en caso de desincronización, regenerarlo desde el Markdown antes de continuar.
4. Inspeccionar la costura. Leer la Finalización y Registro de la tarea del punto de reanudación y la última entrada de PROGRESS.md — el último terreno verificado de la sesión anterior.
5. Prueba de humo. Ejecutar la validación permanente más barata del repositorio para confirmar que el mundo sigue funcionando antes de construir sobre él. Una prueba de humo fallida se investiga primero, no se construye sobre ella.
6. Continuar atómicamente. Ejecutar exactamente la siguiente tarea; no avanzar por lotes.

El agente DEBE confiar en las marcas completadas ([x]) y NO DEBE volver a validar las tareas completadas a menos que el usuario lo solicite explícitamente o la prueba de humo falle de un modo que implique a una tarea completada.

El ciclo de ejecución

DWP define cinco operaciones:

• crear: generar un plan nuevo a partir de un objetivo.
• ejecutar: recorrer el plan tarea por tarea.
• refinar: modificar un plan existente.
• reanudar: continuar un plan interrumpido.
• estado: reportar el estado del plan sin ejecutar.

Espacio de trabajo de salida

Espacio de trabajo de salida

• .dwp/ ignorado por git · desechable
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ informes
• SECURITY_REVIEW.md revisión de seguridad
• EXECUTIVE_REPORT.md informe ejecutivo

Todos los artefactos de DWP DEBEN vivir bajo un directorio .dwp/ ignorado por git en la raíz del repositorio.

Estado del plan legible por máquina

Un plan PUEDE llevar la capa de estado legible por máquina — manifest.json (identidad estática) y state.json (estado activo por tarea, registros de puertas de validación, registros de resultados, punto de control, estado de bloqueo). El plan en Markdown sigue siendo la fuente de verdad; la capa JSON es una proyección derivada, regenerada en los puntos de protocolo y reconciliada en la reanudación.

La capa de estado es RECOMENDADA para planes nuevos, REQUERIDA para la ejecución desatendida y REQUERIDA para espacios de trabajo de agente sin git. Véase la definición normativa completa en Estado del plan.

Rigor proporcional

El rigor DEBE ser proporcional al trabajo. La ceremonia en cambios triviales es un fallo de la metodología, no seguridad adicional. Cada pieza de trabajo pertenece exactamente a un nivel:

Un agente al que se le pida crear un plan para trabajo de nivel micro DEBE indicar que un plan es desproporcionado y ofrecer la forma en línea en su lugar. NO DEBE crearse una carpeta de plan para un cambio trivial de un solo archivo.

El trabajo de nivel micro mantiene los elementos no negociables: un objetivo explícito, una puerta de validación que se ejecuta y pasa, y disciplina de pruebas para cambios de comportamiento. El nivel cambia el empaquetado, nunca las puertas.

Cuando el alcance crece a mitad del camino — una tarea micro descubre alcance real, un plan estándar surge en subrepositorios — el agente DEBE detenerse y promover el trabajo al siguiente nivel en lugar de estirar el actual.

Compatibilidad

Los planes y repositorios de versiones anteriores siguen siendo conformes, y un comprobador de conformidad DEBE distinguir un artefacto heredado conocido (aceptado) de un artefacto que declara esta versión y es objetivamente inválido bajo ella (rechazado):

Versionado

Esta especificación sigue el versionado semántico.