marcioaltoe/write-tasks

Escribir Tareas

Convierte docs/specs/<slug>/_prd.md (y _techspec.md cuando esté presente) en el grafo de tareas ejecutables: un task_NN.md por cada tarea más _tasks.md, el manifiesto que implement-task y el Daemon Roundfix programan. Los artefactos son el contrato: una sesión de agente nueva debe poder tomar un archivo de tarea y construirlo sin más contexto que la carpeta de especificaciones.

Planificación del nivel ligero

Una Tarea con complexity: low que no es QA y no declara una Ruta Gobernada se ejecuta en el nivel ligero. El autor puede ejecutar roundfix spec judge <slug> --stage tasks para una sugerencia de nivel consultiva antes de que se fusione la Solicitud de Extracción de planificación; la sugerencia no controla el envío.

Precondiciones

$ARGUMENTS nombra la especificación. _prd.md debe existir. Si _techspec.md falta en una característica con superficie arquitectónica real, ejecuta write-techspec primero y luego descompón: la creación del artefacto faltante es la resolución, nunca una razón para detenerse a pedir permiso. En trabajo autónomo esto no necesita confirmación: dirigir trabajo autónomo autoriza toda la cadena de creación para cada Especificación ya en la cola aprobada, según docs/agents/autonomous-work.md. Pide aceptación solo cuando se te indique explícitamente descomponer sin una especificación técnica, y luego compensa con una exploración más profunda del código fuente antes de descomponer.

Verificación previa de restricciones del proyecto

Ejecuta esta verificación previa antes de derivar o aprobar un desglose:

1. Clasifica la Especificación. Una Especificación bajo el directorio de archivo resuelto (docs/history/specs/ para la raíz incorporada docs/specs, o <spec-root>/_archived/ para una raíz externa o no predeterminada), o una que se demuestre que se completó antes de que este contrato se aplicara, es una Especificación heredada completada o archivada. Deja cada artefacto heredado byte-idéntico: no lo rellenes, reformatees, regeneres ni reescribas de otra manera.
2. Para cada Especificación activa, no archivada y no ya completada, exige que la PRD y cada TechSpec presente contengan secciones completas de Restricciones del proyecto. Cada sección debe registrar Estrategia de identificador, Autenticación y HTTP, Obligaciones de ADR activas y Autoridad de herramientas según corresponda o no corresponda con una razón, y cada fila debe citar su ruta de origen operativa docs/agents/.
3. Si alguno de los artefactos activos está ausente o incompleto, rechaza crear o actualizar _tasks.md o cualquier archivo de Tarea. Nombra cada fila, razón o ruta de origen faltante y envía la Especificación de vuelta a través de la habilidad de autoría propietaria.
4. Inspecciona los fragmentos propuestos en busca de cualquier creación, edición, renombramiento, movimiento o eliminación de configuración de herramientas del repositorio, scripts, archivos de ignorar, declaraciones de complementos o fijaciones de versión. Dicho trabajo está autorizado solo cuando la PRD y la TechSpec presente registran autorización del mantenedor y los archivos exactos delimitados relativos al repositorio que cubre. Una solicitud de implementación genérica, aprobación de configuración o asignación de Tarea no es autorización. Sin ambos, la autorización y los archivos delimitados, rechaza la descomposición.
5. Resuelve el registro operativo en <spec-root>/<slug>/_authorization.md para cada fragmento de herramientas. Un registro ausente, un registro propuesto, o un registro sin fecha de concesión no autoriza nada; rechaza la descomposición hasta que exista una concesión operativa. Una concesión nueva o ampliada debe aterrizar en la ascendencia objetivo antes de la entrega squash consumidora, por lo que la concesión o enmienda no puede plegarse en el cambio que autoriza.
6. Copia la lista de archivos delimitados en el alcance y los criterios de aceptación de cada Tarea de herramientas autorizada. La Tarea solo puede cambiar esas rutas más su propio archivo de Tarea; divide cualquier trabajo que necesite un límite diferente.
7. La lista operations del registro debe conceder cada operación de entrega que la Especificación utilizará. roundfix deliver start rechaza un registro que carece de implement, commit, push, pull_request o merge; una Especificación sin Rutas Gobernadas registra paths: [].
8. Un commit de Tarea mantiene un archivo ejecutable no rastreado solo cuando su ruta exacta está listada bajo ejecutables en el registro de autorización de la Especificación; cualquier otro ejecutable no rastreado es rechazado. La lista debe estar en el objetivo de entrega antes de que la Ejecución la lea. Los commits de Informe de QA y Lote nunca mantienen un ejecutable no rastreado. Un repositorio con core.fileMode false registra el archivo como 100644.

Las dependencias siguen siendo propiedad exclusiva de _tasks.md; el estado de la Tarea sigue siendo propiedad exclusiva de cada archivo de Tarea. La verificación previa nunca mueve ninguna de las dos responsabilidades.

El código para otro sistema operativo se verifica compilando su código no de prueba para ese sistema, con un ejemplo como GOOS=windows go build -buildvcs=false ./<package>, y nunca con go vet, que también compila pruebas escritas para el anfitrión.

Reglas de propiedad (qué vive dónde, y por qué)

• Las dependencias viven solo en el grafo _tasks.md. Nunca en los archivos de tarea. Dos copias de un borde es cómo los grafos se desvían.
• El estado vive solo en el frontmatter de cada archivo de tarea. _tasks.md posee la topología, no el progreso — los programadores releen los archivos de tarea para el estado.
• El Tipo de Tarea es obligatorio en cada archivo de tarea. Usa exactamente uno de backend, frontend, data, infra, docs, test, chore o qa. Reserva qa para la puerta terminal única creada nombrada por el campo qa: del manifiesto. El Comando de Implementación consume este valor para el enrutamiento y rechaza valores faltantes o desconocidos; nunca dejes un marcador de posición ni infieras el tipo más tarde.
• Referencias de contenido, nunca duplicados. Los archivos de tarea apuntan a secciones de PRD/TechSpec por nombre; una tarea que reformula la especificación se vuelve obsoleta la primera vez que se modifica la especificación. Vincula una fuente adoptada en su ruta posterior a la adopción en la Especificación propietaria con un destino relativo a ese archivo de tarea, nunca en su ruta de procedencia anterior a la adopción. Una Especificación secundaria vincula la copia del propietario principal y no adopta nada. El archivo del propietario realiza un Reenlace de Archivo: promueve esa copia a docs/references/ y reescribe los enlaces de la Especificación secundaria, por lo que la fuente mantiene un propietario y la Especificación secundaria no necesita copia (ADR-0260, ADR-0083).
• Las entradas de contexto son rutas etiquetadas. Agrega ## Contexto solo cuando la Tarea necesite instrucciones específicas o rutas de interfaz más allá del paquete de Especificación estándar. Usa viñetas con forma de - instrucción: <ruta>, - interfaz: <ruta>, - crea: <ruta> o - elimina: <ruta>. Las rutas deben ser limpias, relativas al repositorio y únicas; una Tarea puede declarar como máximo 50 entradas únicas. El Daemon reserva esas rutas antes de llenar el Paquete de Contexto de Especificación de 200 rutas con archivos cambiados previamente.
• Las ediciones declaradas y las rutas gobernadas son explícitas. Cada ruta que una Tarea edita se declara bajo interfaz: o crea:; cada ruta que elimina se declara solo bajo elimina:, nunca interfaz: y nunca instrucción:. Una Tarea que lee un archivo antes de eliminarlo aún lo lista una vez, bajo elimina:. Una eliminación se omite en las comprobaciones de referencia no resuelta y cuenta en el alcance, la Ruta Gobernada y las auditorías de colisión de Ola. El Daemon rechaza la liquidación antes de la Verificación cuando una eliminación declarada aún existe, con elimina: <ruta> aún existe. Una ruta instrucción: es de solo lectura y nunca hace que dos Tareas colisionen. Cada Tarea que cambia un comando declara el único archivo de comando que cambia: .agents/skills/roundfix/references/<command>.md con su espejo, y docs/user-guide/commands/<command>.md, nunca el SKILL.md o commands.md de la habilidad a menos que cambie el archivo de entrada en sí. Dos Tareas que declaran el mismo archivo no pueden compartir una Ola, por lo que las Tareas que cambian diferentes comandos pueden ejecutarse juntas y las Tareas que cambian el mismo comando necesitan un borde entre ellas. Una Ruta Gobernada declarada o de Verificación-lectura debe aparecer en _authorization.md de la Especificación en paths: y en ambas filas archivos delimitados:, o la creación se rechaza con SC-TOOLING-UNDECLARED. Una Tarea que nombra una superficie CLI nombra su habilidad o guía a sí misma o a través de una Tarea de la que depende; de lo contrario, se informa con SC-CLI-UNDOCUMENTED.

El Daemon registra una ruta que una Tarea cambió sin declararla bajo ## Rutas registradas en el commit. La auditoría de alcance de QA cuenta esa ruta registrada como declarada, y el registro divulga un cambio y no reserva nada. Declarar cada ruta previsible sigue siendo la regla.

Un ayudante de prueba, simulacro, accesorio o golden que dos Tareas pueden cambiar cada una es una ruta previsible. Decláralo bajo interfaz: en cada Tarea que pueda cambiarlo, para que roundfix spec check --strict informe SC-WAVE-COLLISION mientras la Especificación aún está siendo creada y el borde needs que nombra ejecuta esas Tareas en serie. El registro no reserva nada, y una Tarea completada nunca colisiona: el commit de liquidación de una Tarea es evidencia de colisión solo mientras una de las dos Tareas no está completada, como una Tarea reabierta a pending, por lo que dos Tareas de una Ola que ambas se completan después de cambiar el mismo archivo no declarado nunca son rechazadas. Declarar el archivo es la única protección.

Tareas de Habilidades para Superficies de Comportamiento Cambiadas

Lee el Mapa de Cobertura de Habilidades del repositorio en docs/references/skill-coverage.json cuando exista. Para cada Superficie de Comportamiento cubierta cuya fuente una Tarea no QA declara bajo interfaz:, crea: o elimina:, incluye una Tarea de habilidades no QA que declare uno de sus archivos de habilidad de cobertura bajo interfaz: o crea:. SC-SKILLS-UNTASKED informa una superficie sin dicha Tarea.

Cuando el cambio no necesita texto de habilidad, registra - sin cambios: <id de superficie> — <razón> en la sección opcional ## Habilidades de la PRD e incluye una Tarea no QA que declare el mapa bajo interfaz: o crea: para registrar la Revisión de Cobertura. La entrada por sí sola no excusa la superficie. SC-SKILLS-MALFORMED informa una entrada de otra forma, una superficie desconocida o una razón en blanco. Ambas reglas comienzan en el commit que agregó el mapa; los repositorios sin él las omiten.

Una Tarea no QA que declara una página Markdown bajo docs/user-guide/ bajo interfaz:, crea: o elimina: también debe declarar docs/references/behavior-surfaces.json bajo interfaz: o crea: y nombrar el paso -record-skill-coverage en un requisito. Otra Tarea no puede cubrirlo: la liquidación de la Tarea de guía verifica su huella digital. Los Límites de _authorization.md de la Especificación nunca deben prohibir ese registro. SC-SURFACE-RECORD-UNTASKED informa cualquier brecha desde la etapa de Tareas, sin horizonte, en repositorios que tienen el registro.

Reglas de descomposición

El código para otro sistema operativo se verifica compilando su código no de prueba para ese sistema, con un ejemplo como GOOS=windows go build -buildvcs=false ./<package>, y nunca con go vet, que también compila pruebas escritas para el anfitrión.

• Rebanadas verticales. Cada tarea entrega un camino estrecho pero completo a través de cada capa que toca, demostrable o verificable por sí mismo — una bala trazadora, no una capa ("todos los esquemas" es una tarea incorrecta; "importaciones vencidas reintentan y muestran su estado" es una correcta).

• Pre-factoring primero. Cuando una rebanada necesita preparar el terreno, haz de eso su propia tarea principal: haz el cambio fácil, luego haz el cambio fácil.

• Caracteriza las superficies externas durante la creación. Cuando una Especificación cruza una superficie externa como un adaptador, contrato o base de datos, crea una tarea de Caracterización que registre lo que el límite real hace, no lo que hace un simulacro, para que una premisa no compatible falle mientras la Especificación aún se está creando en lugar de en la puerta de QA.

  Listala en needs, no meramente antes en el archivo. Cada Tarea cuya premisa depende de la caracterización nombra esa Tarea en su entrada needs en _tasks.md. Las ondas de ejecución se construyen solo a partir de needs, por lo que una Tarea que simplemente aparece más tarde en el manifiesto puede ejecutarse en la misma ola que la caracterización de la que depende, y leer un límite que nadie ha caracterizado todavía. El orden del archivo no es una dependencia.

  Una tarea de Caracterización toca un límite real, así que delimítala explícitamente. Su archivo establece el objetivo al que llegará, por nombre. Lee en lugar de escribir, o se ejecuta contra una instancia aislada que la propia Tarea crea y elimina; nunca caracteriza contra estado compartido o de producción por defecto. Utiliza credenciales limitadas a ese objetivo y no más amplias, respeta la cancelación y limpia lo que creó incluso cuando falla. Una caracterización que debe escribir requiere que esa escritura esté autorizada en la Tarea como cualquier otra acción irreversible — registrar lo que hace un límite no es autoridad para cambiarlo.

  Su Verificación afirma el registro, nunca el límite. El Daemon ejecuta los comandos ## Verificación declarados de una Tarea textualmente a través del shell, una vez contra el árbol sin cambios antes de que exista el turno del Agente y nuevamente en la liquidación. Nada en ese camino lee los límites anteriores: restringen al Agente, y el Daemon no es el Agente. Una Verificación que alcanza la superficie real por lo tanto la alcanza sin límites, dos veces, incluso antes de que se haya realizado cualquier trabajo. Verifica la caracterización que la Tarea registró — su forma, su presencia, lo que las Tareas posteriores leerán — y deja la llamada al límite en el turno del Agente, donde se aplican el objetivo declarado, el aislamiento, las credenciales y la autorización de escritura de la Tarea. Esta es la regla de hermeticidad que estos comandos ya llevan, establecida donde la tentación de romperla es más fuerte: una superficie externa viva es estado ambiente, y un comando que depende de una no es hermético.

• Dimensionada para una sesión fresca. Una tarea que un agente puede completar en una sola sesión con un contexto nuevo. Más de ~7 subtareas o archivos significa dividirla.

• Pruebas integradas, nunca separadas. Los criterios de aceptación de cada tarea incluyen sus propias pruebas; una tarea final de "escribir las pruebas" significa que las tareas anteriores nunca se completaron.

• Implementable de forma independiente. Una vez que sus needs están completas, una tarea no debe requerir ningún otro trabajo sin terminar — eso es lo que permite la ejecución paralela en múltiples árboles de trabajo más tarde.

• La verificación debe ser hermética, portátil, que pruebe efectos y propiedad del Daemon. Cada comando de ## Verificación de cada tarea debe ser satisfacible en un árbol de trabajo nuevo usando solo el estado del árbol, sin dependencias de red, servicios en ejecución o estado ambiental. El Daemon los ejecuta como su propio proceso, no como delegado del Agente.

Archivo de manifiesto _tasks.md

El manifiesto es un archivo Markdown con frontmatter YAML y una sección de dependencias. Usa exactamente:

---
slug: <igual que el nombre de la carpeta>
tasks:
- id: "1"
  title: <título de la tarea>
  complexity: <alta|media|baja>
  type: <backend|frontend|data|infra|docs|test|chore|qa>
  neeeds:
  - "<id>"
  ...
qa: "<id de la tarea qa>"
---

El campo qa nombra el id de la tarea que contiene la puerta terminal de QA. La tarea nombrada debe tener type: qa. El Daemon ejecuta roundfix spec judge <slug> en las tareas nombradas.

Formulario de comprobación previa a la fusión

Antes de enviar una Solicitud de Extracción de planificación, el autor ejecuta:

roundfix spec check <slug> --strict

Esto informa cualquier colisión de Ola, archivos no declarados, autorización faltante, puerta QA faltante o manifiesto malformado. El comando también verifica que cada Tarea tenga un type: válido y que el id qa: nombre una Tarea existente con type: qa.

Archivos de tarea task_NN.md

---
id: "1"
title: <título de la tarea>
complexity: <alta|media|baja>
type: <backend|frontend|data|infra|docs|test|chore|qa>
status: pending
---

## Resumen

<resumen de 1-2 líneas>

## Contexto

(Opcional) Rutas etiquetadas según las reglas de propiedad.

## Criterios de aceptación

- <lista de verificación de criterios>

## Dependencias técnicas

- <dependencias que no están en el grafo `_tasks.md`>

## Verificación

```bash
<comandos que deben ejecutarse para la verificación>

El Daemon actualiza el estado en el frontmatter a `in_progress`, `completed` o `failed`. La Tarea también puede registrar `## Rutas registradas` como una lista YAML de rutas que cambió sin declarar.

---

*Nota de traducción: Esta habilidad está diseñada para agentes de IA y puede contener términos técnicos que no se traducen.*