Work Implement

Skill: Implementar trabajo

Guia general para ejecutar en codigo trabajo ya especificado, de distintos tipos. Cada tipo de implementacion tiene su propio flujo (ubicaciones, validaciones, unidad de confirmacion, cierre) en references/. El cuerpo de este SKILL.md contiene solo lo transversal a todos los tipos; el detalle de cada tipo se carga unicamente cuando se necesita.

Alcance (cualquier tipo): consume especificaciones ya redactadas por los skills de planificacion (work-define, work-plan). No reescribe ni reestructura la especificacion - solo la implementa. Correcciones menores acordadas con el usuario son la unica excepcion.

Solo implementacion: no modifica documentacion de producto (README de US, TK-XXX, WI-XXX, TC-XXX, FT-XXX, ADRs, technical-docs) - solo el progress.md. Excepcion de checkboxes: avanzar el estado de las subtareas del artefacto en ejecucion a medida que se trabajan —[ ] (pendiente) => [~] (en curso) => [x] (completada)— es la unica modificacion permitida en archivos de especificacion; no se toca ninguna otra seccion del artefacto. El archivo a editar depende del tipo: TK-XXX.md para tareas de historia de usuario, el README.md del WI para tareas de mantenimiento. En los tipos de automatizacion de pruebas (TC-XXX / FT-XXX) no aplica: los test cases no tienen subtareas y su especificacion no se toca en absoluto. Si se detecta un conflicto en la documentacion que pueda afectar el resultado, parar inmediatamente y notificar al usuario antes de continuar.

Ritmo - una unidad por confirmacion (confirmByUnit: always, valor por defecto): implementar una unidad, actualizar progress.md y la lista de tareas (to-dos) del agente, ejecutar lint/build, y esperar confirmacion explicita del usuario antes de arrancar la siguiente. La unidad depende del tipo (ver tabla de seleccion). El commit de la unidad terminada no se hace al completarla: queda pendiente durante la pausa de confirmacion, dejando una ventana para que el usuario revise el resultado, aplique correcciones manuales o le indique ajustes al agente antes de que el cambio quede commiteado. El commit se hace al confirmar el avance, como primer paso antes de arrancar la siguiente unidad (o, si el usuario detiene el flujo ahi, en el cierre — ver Paso 4 de cada referencia).

Modo de ejecucion paralela: si el alcance incluye mas de una unidad y la politica resuelta dice no pausar entre unidades — porque implementation.md resolvio confirmByUnit: never, o porque el usuario lo pide explicitamente en el turno (p. ej. "sin preguntar", "de corrido", "todas a la vez") —, se activa el modo de ejecucion paralela (ver seccion Ejecucion paralela con subagentes y worktrees), que corre las unidades independientes en subagentes con worktree y omite las pausas intermedias. Si falta cualquiera de las dos condiciones, se mantiene el modo secuencial.

Alcance de las pruebas - solo archivos afectados: este skill ejecuta las pruebas (y lint/typecheck/build) unicamente sobre los archivos o el paquete afectados por la unidad implementada — tanto por unidad (Paso 3) como en el cierre (Paso 4) y tras cada merge en modo paralelo. Nunca corre la bateria completa de pruebas del repositorio. Ejecutar toda la bateria de pruebas (regresion de todo el repo) es responsabilidad exclusiva de quality-check, que corre en work-integrate / pr-create antes de integrar o crear el PR; este skill no la sustituye ni la anticipa.

Como preguntar al usuario

Mecanismo, ritmo y fallback compartidos: ${PLUGIN_ROOT}/reference/asking.md.

Cada vez que este skill o sus referencias digan preguntar, pedir, confirmar, validar o sugerir algo al usuario, asume ese mecanismo; no se repite allí.

Confirmaciones entre unidades: solo con confirmByUnit: always. Una pregunta por turno con opciones claras (p. ej. Opciones: [Si, continuar] / [No, detener aqui]). No avanzar antes de la respuesta.

Rutas de las referencias compartidas. ${PLUGIN_ROOT} es la raíz del plugin instalado (la carpeta que contiene skills/, agents/ y reference/), y toda referencia compartida de este skill se escribe como ${PLUGIN_ROOT}/reference/<archivo>.md. Resolverla así, en este orden: (1) en Claude Code, ${PLUGIN_ROOT} es ${CLAUDE_PLUGIN_ROOT} — comprobar con echo "$CLAUDE_PLUGIN_ROOT" y usar ese valor; (2) en cualquier otro cliente, o si la variable está vacía, la carpeta desde la que se cargó este archivo, dos niveles arriba. El destino de cada enlace markdown (../../reference/…) existe solo para navegar el repositorio en GitHub o en un editor: no resolverlo desde el directorio de trabajo. Nunca buscar reference/ en el proyecto: un <proyecto>/reference/language.md que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.

Resolución de idioma

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/language.md.

Las reglas de language.md son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos y mensajes generados por este skill.

No continúes hasta haber leído y aplicado language.md.

Excepción deliberada: la salida y los mensajes de error de las herramientas (lint, build, tests) no se traducen; el código, los identificadores y los nombres de artefacto tampoco.

Resolucion de la politica de implementacion

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/implementation.md.

Las reglas de implementation.md son obligatorias y tienen prioridad para determinar el ritmo de confirmacion entre unidades (confirmByUnit), que hacer con cambios sin commitear al iniciar o reanudar (uncommittedChanges), el uso y la ubicacion de los worktrees (workTree, workTreePath), el maximo de subagentes concurrentes (maxParallel) y si el cierre pasa al siguiente skill sin preguntar (handoff, ver Regla de handoff).

No continues hasta haber leido y aplicado implementation.md.

Excepcion deliberada: archiveMode no lo aplica este skill — el archivado del artefacto ocurre al cerrarlo, en work-integrate / pr-create.

Límite de intentos y escalamiento

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/escalation.md.

Las reglas de escalation.md son obligatorias y determinan, vía escalation.maxAttempts y escalation.onLimit, cuántos intentos consecutivos se hacen sobre el mismo problema que no se resuelve —una prueba en rojo, un build que no compila o un check que sigue fallando en modo correccion— y qué se hace al agotarlos: detener el trabajo sobre ese problema, presentar el parte de bloqueo y preguntar al usuario cómo seguir (ask), o marcarlo como BLOCKED en el informe y continuar con el alcance que no dependa de él (report).

El contador es por problema, no global, y el límite es un techo, no una cuota: si no hay una hipótesis nueva que justifique el siguiente intento, se escala ya. Nunca se «resuelve» un bloqueo desactivando o saltando una prueba, relajando una aserción ni bajando un umbral.

No continúes hasta haber leído y aplicado escalation.md.

Seleccion del tipo de implementacion

Antes de cualquier otra cosa, identificar que tipo de implementacion corresponde y cargar su flujo. No mezclar tipos en una misma ejecucion.

La senal que distingue los tipos es el artefacto que el usuario referencia (o, en el modo correccion, el que le pasa quality-check).

Artefacto archivado. Al cerrar un trabajo, work-integrate y pr-create pueden mover su carpeta a docs/archive/user-stories/ o docs/archive/work-items/. Si el artefacto referenciado no aparece en su ruta activa, buscarlo ahi antes de darlo por inexistente — y nunca crear la carpeta en la ruta activa por no haberla encontrado: este skill hace «leer o crear» el progress.md, asi que el descuido produciria una carpeta fantasma con un identificador ya usado. Ver work-integrate/references/archive.md. Que se haga con el hallazgo depende del modo:

• En los cuatro tipos de implementacion (US/TK, WI, TC, FT): parar y avisar. Implementar trabajo nuevo sobre un artefacto ya cerrado exige desarchivarlo primero —mover su carpeta de vuelta—, y eso lo decide el usuario.
• En modo correccion: un artefacto archivado es esperable, no un error — la correccion llega justo en la fase de cierre, cuando el archivado ya se commiteo. Continuar con la correccion, pero sin escribir dentro de la carpeta archivada: la nota de retrabajo va en el informe de quality-check, no en el progress.md archivado.

Ver work-integrate/references/archive.md.

Modo correccion (entrada delegada desde quality-check). Ademas de los cuatro tipos, este skill acepta una correccion puntual delegada por quality-check cuando un check falla en el cierre y el usuario autoriza el arreglo. No es un tipo nuevo: es un modo acotado sobre el artefacto que ya se implemento en esta rama — US-XXX, WI-XXX, una automatizacion de pruebas (FT-XXX / TC-XXX en rama test/), o un artefacto externo al plugin. Ver Modo correccion.

Reglas de seleccion:

• Identificar el artefacto -> leer su referencia -> seguir unicamente su flujo.
• Si la referencia del usuario es ambigua (p. ej. un numero sin prefijo, o no esta claro si hay historia asociada), preguntar al usuario antes de continuar; no asumir el tipo ni inventar artefactos.
• Solo se implementa trabajo en Estado: Ready (la US/TK, el WI, el TC o el FT). Si esta en Draft, parar y devolver a la fase que lo produce (work-plan / work-define para US/TK/WI, test-define para un TC, el flujo «Analizar legado» de work-research para un FT).
• Codigo de produccion vs. pruebas. Los tipos TK-XXX y WI-XXX implementan funcionalidad nueva con sus tests. Los tipos TC-XXX y FT-XXX entregan pruebas: el comportamiento ya existe, asi que las pruebas confirman lo documentado.
• Un FT-XXX no es un plan de implementacion. Es el registro de funcionalidad que ya existe en el codigo — no tiene plan, ni subtareas, ni nada que desarrollar. De el solo salen las pruebas que cubren sus TC-XXX. En los tipos TC-XXX y FT-XXX, tocar codigo de produccion se admite unicamente como correccion puntual derivada de una prueba en rojo, con la evidencia presentada y la decision explicita del usuario; nunca para escribir funcionalidad nueva (ver references/test-cases.md). Si el usuario espera funcionalidad de un FT-XXX, parar y avisar: eso se especifica como US-XXX o WI-XXX.

Validacion de repositorio (transversal)

Verificar estas condiciones antes de implementar, sea cual sea el tipo. Si alguna falla, parar - informar al usuario y resolver primero.

Con worktrees, el orden es: primero «Cambios sin commitear al iniciar» sobre el arbol principal (segun uncommittedChanges), y solo despues se crea el worktree del artefacto, sobre el que se aplican el resto de verificaciones — ver Arbol principal intocable cuando se usan worktrees. En particular, «Rama correcta» no autoriza un git checkout en el arbol principal cuando workTree resolvio always (o ask con respuesta afirmativa, o modo paralelo): la rama del artefacto se crea y se usa desde su worktree.

Excepcion — modo correccion. En la correccion delegada desde quality-check (ver Modo correccion) no aplican ni «Working tree limpio» ni «Artefacto en Ready»: el cierre corre sobre la rama consolidada, con el artefacto ya implementado y posiblemente con cambios sin commitear. El resto de condiciones (rama del artefacto, solo trabajo de la rama actual) siguen vigentes.

• No iniciar en la rama de otro trabajo (primera verificacion): obtener la rama actual con git branch --show-current. Si ya tiene un prefijo de implementacion (feature/, fix/, chore/, refactor/, test/) y no corresponde al artefacto que se va a implementar, parar e indicar al usuario que no se puede iniciar la implementacion desde la rama de otro trabajo; debe situarse en la rama base acordada (p. ej. develop/main) para que el skill cree o cambie a la rama del artefacto. Con worktrees esta verificacion no aplica al arbol principal: la rama en la que este el usuario es irrelevante, porque el skill no va a cambiarla; solo se comprueba que el worktree del artefacto quede en su rama. Excepcion - reanudar: si la rama actual es precisamente la del artefacto pedido, continuar normalmente.
• Cambios sin commitear al iniciar: git status --porcelain al iniciar la sesion de implementacion (o al reanudarla). Si hay salida, resolver segun implementation.uncommittedChanges (ver ${PLUGIN_ROOT}/reference/implementation.md): commit los comitea (invocando git-commit) y continua; stash los guarda con git stash y continua, avisando donde quedaron; ask (por defecto) para e informa al usuario, sin continuar hasta que lo resuelva. No aplica durante la pausa de confirmacion entre unidades: los cambios de la unidad recien terminada quedan sin commitear ahi a proposito (ver Ritmo obligatorio), hasta que el usuario confirma avanzar.
• Rama correcta: estar en (o crear) la rama de trabajo del artefacto — en el arbol principal solo si la ejecucion no usa worktrees; con worktrees, en el worktree del artefacto. No implementar en main ni en ramas de otro trabajo sin instruccion explicita. El nombre de rama lo define cada referencia segun el tipo. Excepcion — WI-XXX de tipo bug-fix o security-update: no llevan rama propia; se implementan directamente sobre la rama de integracion y cierran sin handoff (ver references/work-items.md). Ahi la verificacion no es "estar en la rama del artefacto" sino estar en la rama de integracion confirmada con el usuario — que tampoco se asume.
• Solo trabajo de la rama actual: solo se implementan unidades (TK / WI / TC / FT) que pertenezcan al artefacto asociado a la rama de implementacion actual. No implementar tareas de otro artefacto o de otra rama: si la unidad pedida no corresponde a la rama actual, parar y cambiar a su rama correspondiente (o pedir al usuario que lo haga) antes de continuar; nunca mezclar trabajo de distintos artefactos en una misma rama.
• Artefacto en Ready: el artefacto a implementar existe y esta en Estado: Ready (lo verifica cada referencia con su regla propia).
• Solapamiento de progreso: leer progress.md si existe; respetar unidades ya en Done; si hay alguna In Progress, revisar notas y estado real antes de continuar.

Si hay conflicto:

` WARNING No es posible continuar:

Arbol principal intocable cuando se usan worktrees (transversal)

Cuando la ejecucion usa worktrees —workTree: always, workTree: ask respondido que si, o el modo de ejecucion paralela— el arbol principal es de solo lectura durante toda la implementacion: la rama en la que esta al empezar es la misma al terminar. Ningun git checkout/switch/merge/reset se ejecuta sobre el, ni se le pide al usuario que cambie de rama. Unica operacion previa admitida: antes de crear el primer worktree, si el arbol principal tiene cambios sin commitear, se aplica uncommittedChanges exactamente igual que sin worktrees (commit via git-commit, stash, o ask); resuelto eso, arranca el proceso de worktrees y el arbol principal ya no se toca. La razon de ser de workTree: always es que el usuario siga trabajando en su arbol —normalmente en la rama de integracion— mientras la implementacion avanza aparte; un checkout «solo para crear la rama» rompe eso.

Todo ocurre en worktrees, en dos niveles: el worktree del artefacto (<workTreePath>/<artefacto>, en la rama del artefacto, creado con git worktree add … [-b <rama>] <rama-base> — sin checkout previo de la base, que es solo una referencia) y un worktree por unidad (wt/<unidad>, derivado del anterior). El «Paso 1 — Preparar repositorio y rama» de cada referencia de tipo se cumple creando el worktree del artefacto; progress.md, TDD, lint/build, commits y los merges de unidades corren dentro de un worktree (git -C <ruta> …). «No iniciar en la rama de otro trabajo» y «Rama correcta» se cumplen por construccion en el worktree del artefacto; «Cambios sin commitear al iniciar» se evalua sobre el arbol principal, antes de crear el worktree, como en cualquier ejecucion. Al cerrar se eliminan todos los worktrees; la rama del artefacto queda para work-integrate / pr-create.

Casos particulares (reanudar con la rama del artefacto ya en el arbol principal, bug-fix/security-update sin rama propia, workTreePath dentro del repo) en references/worktrees.md. Una peticion explicita del usuario gana («sin worktrees», «implementalo aqui mismo») para esa ejecucion, sin modificar settings.json.

progress.md (transversal)

Cada tipo mantiene un progress.md como unica bitacora que este skill puede modificar (nunca la especificacion de producto). Estados validos por unidad: Pending, In Progress, Done. No usar Skipped ni otros valores.

• Crear desde assets/progress-template.md si no existe, adaptando el encabezado y las unidades al tipo (TK / WI / TC / FT) segun indique la referencia.
• Por cada unidad: Pending => In Progress => Done; anadir notas si quedan aspectos parciales.
• Archivos: registrar los archivos tocados al implementar la unidad, uno por linea dentro de un bloque de codigo (fences , con el titulo Archivos:fuera del bloque), prefijando cada ruta con+(creado),~` (modificado) o - (eliminado). Se llena al cerrar la unidad, con lo que efectivamente se toco — no con lo que el plan preveia. Va en bloque de codigo y sin vineta a proposito: el prefijo - de un archivo eliminado se confundiria con el guion de la lista.
• Implementador: registrar {{usuario}} / {{agente}} / {{modelo}} / {{session id}}, donde el usuario se infiere de git config user.name, el agente es el que ejecuta la implementacion (p. ej. Claude, Cursor, Codex), el modelo es el modelo concreto usado en la sesion (p. ej. claude-sonnet-5) y el session id es el identificador de la sesion o conversacion actual (p. ej. juanca202 / Claude / claude-sonnet-5 / 0cc3519b-0e7f-456d-93de-4203d89e38fe). Omitir de derecha a izquierda cualquier dato que el agente no exponga (sin session id; sin modelo ni session id; o solo el usuario si tampoco puede identificarse el agente).
• Registrar en Decisiones adicionales toda decision tomada durante la sesion de chat que no este ya documentada en la especificacion. Si no hubo decisiones nuevas, omitir la seccion.
• Cobertura de test cases: cuando el artefacto tiene test cases, el campo Cobertura de test cases de la unidad no es un detalle exhaustivo de cada TC-XXX: registrar solo observaciones puntuales -- todo TC-XXX que no se pudo automatizar (con el motivo) y toda decision de crear un tipo de prueba distinto al que sugiere el test case (p. ej. cubrir con integracion un TC pensado como unit). Si la implementacion fue como se esperaba (todos los TC-XXX se automatizaron tal cual), no es necesario comentar nada en el campo; si el artefacto no tiene test cases, omitirlo. En los tipos TC-XXX / FT-XXX este campo es obligatorio (los test cases son el objeto mismo de la unidad) y suma dos observaciones propias: AC-XXX sin ningun TC que lo cubra y discrepancias entre el TC y el codigo con la decision tomada.

Estado de iteracion para el seguimiento de especificaciones (transversal)

Los hooks de seguimiento de especificaciones del plugin (ver hooks/README.md) necesitan un iterationId que se mantenga igual mientras se reintenta la unidad en curso -o la correccion delegada desde quality-check- y cambie al pasar a otra. Se resuelve con un archivo de estado local y no versionado: .sdd-devkit/current-iteration.json, con {"iterationId": "<uuid>", "key": "<codigo de la unidad, o correction: en modo correccion>"}.

• Al iniciar una unidad (Pending -> In Progress, primera vez) o al recibir una correccion delegada para un check nuevo: si el archivo no existe, o su key no coincide con la unidad/correccion actual, generar un UUID nuevo (p. ej. uuidgen) y sobrescribir el archivo.
• En un reintento con el mismo key (build/test que vuelve a fallar dentro de la misma unidad, o un segundo intento de la misma correccion): no tocar el archivo — el iterationId existente sigue siendo el correcto.
• Al cerrar la unidad como Done, o al terminar la correccion (aplicada o no — ver Cuando la correccion no se aplica): eliminar el archivo.
• La primera vez que se escribe, normalizar el .gitignore: comprobar con git check-ignore -q .sdd-devkit/current-iteration.json y, si no esta ignorado, anadir esa linea — es una cache local y desechable, igual que .sdd-devkit/test-run.json (ver quality-check).
• Mantenerlo siempre, sin comprobar antes si trackingEnabled esta activo en .sdd-devkit/settings.json: es barato de escribir y, si ningun hook lo lee, no tiene efecto observable.

Lista de tareas del agente (transversal)

Durante la ejecucion, mantener la herramienta de lista de tareas (to-dos) del agente como reflejo vivo del plan de implementacion en curso: una entrada por cada tarea del plan. Da visibilidad del progreso en tiempo real y no sustituye al progress.md, que sigue siendo la bitacora persistente en el repositorio.

• Al empezar a ejecutar un plan de implementacion: poblar la lista de to-dos con, como primera entrada, el titulo del artefacto en ejecucion (TK-XXX/WI-XXX + su titulo) para tener siempre presente que se esta ejecutando, seguida de una entrada por cada tarea del plan (IT-XX), en el orden en que se van a abordar. Cada entrada de tarea muestra unicamente la descripcion corta (su IT-XX + la linea corta), nunca el detalle largo, las referencias a codigo ni el texto completo de la tarea.
• Al iniciar cada tarea: marcar su entrada como in_progress, en el mismo momento en que se marca [ ] => [~] (en progreso) en el artefacto. Solo una tarea in_progress / [~] a la vez.
• A medida que se completa cada tarea: marcar su entrada como completed, en el mismo momento en que se marca [~] => [x] en el artefacto.
• La primera entrada (titulo del TK/WI) se marca como completed solo cuando todas las tareas del plan de implementacion hayan finalizado; hasta entonces permanece como recordatorio del artefacto en curso.
• Al terminar el plan: todas las tareas quedan completed, incluida la primera entrada del titulo. Al comenzar el siguiente plan de implementacion, reemplazar la lista con el titulo del nuevo artefacto y sus tareas.
• Coherencia: la lista de to-dos, los checkboxes del artefacto y progress.md no deben contradecirse.
• Fallback: si el cliente no expone la herramienta de to-dos, basta con progress.md y los checkboxes del artefacto; no narrar el progreso como prosa paso a paso.

Documentacion de codigo segun ADR (transversal)

Antes de escribir codigo, verificar si el proyecto tiene algun ADR que defina como documentar el codigo (estilo de docstrings, comentarios, JSDoc/TSDoc, convenciones de encabezado de archivo, anotaciones, etc.). Los ADR suelen vivir bajo docs/adr/ o donde el proyecto los registre.

• Si existe un ADR vigente sobre documentacion de codigo, aplicarlo dentro de la misma unidad que se implementa (la TK o el WI). La documentacion que el ADR exige es parte del entregable de esa unidad, no un paso posterior.
• No diferir esa documentacion "para otro momento", un commit aparte o una tarea futura. Una unidad cuyo codigo no cumple la documentacion que su ADR exige no esta Done.
• Esto no contradice la regla de no modificar la especificacion de producto: seguir un ADR significa obedecerlo al escribir el codigo, no editar el ADR. El ADR se respeta, no se cambia.
• Si hay varios ADR aplicables, o uno ambiguo respecto al alcance actual, preguntar al usuario antes de continuar en lugar de asumir.

Principios de desarrollo (transversal)

Toda implementacion, sea cual sea el tipo de artefacto, sigue estos dos principios. No son opcionales.

TDD — Test-Driven Development

El ciclo obligatorio por cada unidad de comportamiento es Red → Green → Refactor:

1. Red: escribir el test que falla antes de escribir el codigo de produccion. El test debe describir el comportamiento esperado segun los insumos de comportamiento del artefacto: los criterios de aceptacion (AC-XXX) y —cuando existan— las reglas de negocio (BR-XX) y los casos de prueba (TC-XXX). Nota: si el artefacto (US o WI) referencia una investigacion de migracion con casos de Golden Master en su validation.md, esos casos forman parte de las pruebas de la unidad.

Test cases como insumo de las pruebas automatizadas: si el artefacto tiene test cases (carpeta test-cases/ en la US o el WI), leer su README.md antes de escribir codigo para identificar que TC-XXX describen y cuales pueden convertirse en pruebas automatizadas (unit, integracion, e2e) dentro del ciclo TDD. Cada TC-XXX que sea automatizable se cubre con su prueba en la unidad correspondiente. Cuando un TC-XXX no se pueda automatizar (p. ej. es manual o exploratorio) o se decida crear otro tipo de prueba distinto al que sugiere el test case, registrarlo en progress.md (ver seccion progress.md). Escribir la prueba en el ciclo TDD es una cosa; ejecutarla sigue el Uso escalonado de pruebas (unit e integracion en cada iteracion y acotadas al cambio, e2e solo al final de la implementacion).

2. Green: escribir el minimo codigo necesario para que el test pase.
3. Refactor: limpiar el codigo (produccion y test) sin romper los tests.

El paso Red no aplica a las pruebas e2e. Se escriben dentro del ciclo TDD como cualquier otra prueba, pero no se ejecutan durante las iteraciones (ver Uso escalonado de pruebas), asi que no hay rojo que observar. Su primer y unico rojo/verde en este skill ocurre en el cierre de la implementacion. Unitarias e integracion si cumplen Red→Green→Refactor completo en cada iteracion.

Los tests son parte del entregable de la unidad, no una fase posterior. Una unidad no esta Done si sus tests no existen, o si los que corresponde ejecutar en la iteracion (unitarias e integracion) no pasan. Las pruebas e2e escritas pero diferidas al cierre —y, en modo paralelo, las de integracion diferidas por infra no aislable— no bloquean el Done de la unidad, siempre que esten escritas y su diferimiento quede registrado en progress.md; su verificacion es condicion del cierre de la implementacion, no de la unidad.

Variante para los tipos TC-XXX / FT-XXX: ahi el entregable son las pruebas y el comportamiento ya esta implementado, asi que no hay paso Red por diseno: lo esperado es que la prueba pase en verde a la primera y confirme el comportamiento documentado. Si la prueba falla, hay una discrepancia real entre el TC-XXX y el codigo: se para, se presenta la evidencia al usuario y se decide con el si se corrige produccion (y ahi el rojo si actua como paso Red), si se corrige la prueba, o si vuelve a test-define. Nunca se relaja una asercion para forzar el verde. Detalle en references/test-cases.md.

Uso escalonado de pruebas (optimizacion)

El ciclo TDD siempre define las pruebas de la unidad (unit / integracion / e2e segun corresponda), pero ejecutarlas todas y completas en cada iteracion es caro. Escalonar la ejecucion — esto cambia cuando y cuantas veces se corren, no que se escribe ni la definicion de Done:

• Unitarias e integracion — ambas en cada iteracion, al mismo nivel. Las dos son la red de seguridad primaria del ciclo Red→Green→Refactor y se corren en cada iteracion de la unidad. No hay juicio previo sobre si el cambio "cruza una frontera": si la unidad tiene pruebas de integracion, se ejecutan.
• Siempre acotadas exclusivamente al cambio. Lo que abarata la corrida no es saltarse un nivel, es el alcance: ejecutar unicamente el archivo, la suite o el paquete de lo que se acaba de tocar — nunca la suite completa del nivel ni la del repositorio. Usar los filtros del runner (patron de ruta, nombre de test, proyecto/paquete). La corrida completa es tarea exclusiva de quality-check. En Red y Green se ejecuta solo el archivo de test que se acaba de escribir (y, si el runner lo permite, solo el caso en curso); al cerrar la unidad, los tests de los archivos/paquete afectados. Un npm test, pytest o go test ./... a secas es la bateria completa con otro nombre. Filtros por runner y anti-patrones en references/scoped-tests.md.
• E2E — se escriben durante, se ejecutan solo al final. Se definen dentro del ciclo TDD como cualquier otra prueba, pero no se ejecutan en las iteraciones (son lentas y fragiles). Su unica corrida en este skill es en el cierre de la implementacion (Paso 4 de la referencia del tipo, o el paso de Integracion en modo paralelo), una sola vez sobre el codigo consolidado. La corrida exhaustiva como puerta formal la realiza quality-check en work-integrate / pr-create.

En modo paralelo (worktrees): el subagente ejecuta la integracion de su unidad cuando puede aislar la infraestructura (base de datos por worktree, contenedor efimero, testcontainers, esquema o namespace propio). Si la infra es compartida y no aislable —los worktrees concurrentes colisionarian en migraciones, fixtures o estado—, difiere esas pruebas, lo registra en progress.md y lo reporta al orquestador, que las ejecuta en el paso de Integracion tras el merge de la unidad. Un fallo por colision de infra no es un defecto del codigo: no se corrige, se aisla o se difiere.

Registrar en progress.md cuando una prueba se difiera o se decida no ejecutar en una iteracion (e2e por diseno; integracion solo por infra no aislable en modo paralelo), para que la decision quede trazada y el cierre sepa que debe ejecutarla.

Clean Architecture

Organizar el codigo respetando la separacion de responsabilidades:

• Capas con dependencias hacia adentro: Entities → Use Cases → Interface Adapters → Frameworks/Drivers. Las capas internas no conocen las externas.
• Regla de dependencia: el codigo fuente solo puede apuntar hacia adentro; nunca una capa interna importa de una externa.
• Use cases primero: la logica de negocio vive en casos de uso, no en controladores, servicios de infraestructura ni frameworks.
• Inversión de dependencias: las abstracciones (interfaces/puertos) se definen en la capa de dominio; las implementaciones concretas (repositorios, clientes HTTP, etc.) viven en la capa de infraestructura.

Si el proyecto ya tiene una estructura establecida que se aparta de Clean Architecture, respetar la convencion existente y registrar la decision en Decisiones adicionales del progress.md.

Subagentes y MCP condicionales (transversal)

Los subagentes ui-specialist y quality-specialist solo se usan si el proyecto los define; si no existen, ejecutar el paso directamente. Si la unidad no involucra UI ni automatizacion de pruebas, implementar directamente sin delegar.

Ejecucion paralela con subagentes y worktrees (transversal)

Modo alternativo al ritmo secuencial por defecto. Aplica a los cuatro tipos (TK-XXX, WI-XXX, TC-XXX y FT-XXX). Se activa unicamente cuando se cumplen las dos condiciones a la vez:

1. El alcance incluye mas de una unidad (varias TK, varios WI, varios TC o varios FT).
2. No hay que pausar entre unidades: implementation.md resolvio confirmByUnit: never, o el usuario pide explicitamente ejecutar sin confirmacion en el turno (p. ej. "sin preguntar", "de corrido", "todas a la vez", "sin pausas").

Si falta cualquiera de las dos, se mantiene el modo secuencial con una unidad por confirmacion (comportamiento por defecto de cada referencia).

Worktrees en modo secuencial. El modo paralelo siempre usa worktrees. En modo secuencial los usa segun workTree: con always, cada unidad va en su worktree sin preguntar; con never, se trabaja en el arbol principal; con ask, se pregunta una sola vez al inicio y la respuesta vale para toda la ejecucion. Siempre que haya worktrees —en cualquiera de los dos modos— rige Arbol principal intocable: la rama del artefacto vive en su propio worktree y el arbol principal no cambia de rama. El modo paralelo no cambia como se implementa cada unidad — ciclo TDD, Clean Architecture, lint/build, checkboxes del artefacto, cobertura de test cases, validacion por criterios de aceptacion siguen igual —: solo cambia cuantas unidades avanzan a la vez y como se integran.

Paso 0 - Analisis de dependencias (obligatorio, antes de ejecutar nada)

Es el primer paso y condiciona todo lo demas. No lanzar ningun subagente antes de completarlo.

1. Leer cada unidad del alcance y su relacion de dependencias: el campo Dependencias del artefacto (TK/WI), las Observaciones del TC-XXX (donde se declaran dependencias con otros TC) y las dependencias obvias descritas en el texto.

2. Clasificar cada unidad:

   • Independiente: sin dependencias, o cuyas dependencias ya estan en Done.
   • Dependiente dentro del alcance: depende de otra unidad que si esta en esta ejecucion.
   • Dependiente fuera del alcance: depende de una unidad que no esta en esta ejecucion ni en Done.

3. Dependencia fuera del alcance => parar y preguntar. Si alguna unidad depende de trabajo que no forma parte de esta ejecucion, detenerse antes de ejecutar e informar al usuario (herramienta de preguntas estructuradas) para que decida por cada caso:

   "La unidad X depende de Y, que no esta en esta ejecucion ni completada. ¿Como continuo?" Opciones: [Excluir X y continuar] / [Detener aqui]

   No ejecutar hasta resolver todos estos casos.

4. Ordenar por olas (niveles topologicos). Con las dependencias internas al alcance, agrupar las unidades en olas: cada ola contiene unidades que no dependen entre si y cuyas dependencias ya quedaron integradas en olas anteriores. Las unidades de una misma ola son candidatas a correr en paralelo; las olas se ejecutan en secuencia. Si se detecta un ciclo de dependencias (A depende de B y B de A), parar e informar: no es paralelizable; devolver a work-plan / work-define para revisar el alcance.

5. Presentar el plan de ejecucion (olas, que corre en paralelo, que se excluye y por que) y confirmarlo una sola vez. Como el usuario ya pidio ejecutar sin confirmacion, no habra mas pausas entre unidades una vez aprobado este plan (salvo que un paso obligue a parar: dependencia externa, conflicto de merge no trivial o suite en rojo).

Concurrencia y worktrees

• El maximo de subagentes en paralelo lo fija maxParallel (por defecto 3; -1 = sin limite). Si una ola tiene mas unidades independientes que ese maximo, despacharlas en lotes de ese tamano; al liberarse un cupo, entra la siguiente unidad pendiente de la ola.
• Un worktree por unidad. Cada subagente trabaja en su propio git worktree, en una rama derivada de la rama del artefacto:
  • Rama base = la rama del artefacto de esta ejecucion (feature/US-XXX-* o la rama del WI). Si el alcance son WI de tipo bug-fix / security-update —que no tienen rama propia—, la base de los worktrees es la rama de integracion confirmada, y ahi mismo se hacen los merges de las unidades; no se crea una rama intermedia para agruparlos.
  • Crear el worktree bajo la raiz que fije workTreePath (relativa a la raiz del repo si no es absoluta — p. ej. .worktrees/; sin definir, una ruta temporal fuera del arbol principal) con git worktree add <workTreePath>/<unidad> -b wt/<unidad> <rama-base> (p. ej. .worktrees/TK-003 con rama wt/TK-003). <rama-base> es una referencia: no hace falta —ni se debe— hacer checkout de ella en el arbol principal

…(truncated)