# Work Implement > Implementar en código trabajo ya especificado, de cuatro tipos: (1) tareas técnicas (TK-XXX) bajo una historia de usuario; (2) tareas de mantenimiento (WI-XXX) sin historia — bugs, refactor, deuda técnica, dependencias, operativas; (3) casos de prueba (TC-XXX) — automatizar las pruebas ya documentadas por test-define; (4) features (FT-XXX) — automatizar los TC de sus criterios. Selecciona el tipo según el artefacto referenciado. Solo implementa trabajo en Estado: Ready; acepta además un modo corrección acotado, delegado por quality-check, sobre cualquier artefacto de la rama (US-XXX, WI-XXX, FT-XXX, TC-XXX en rama test/, o un artefacto externo al plugin), para arreglar un check o una prueba en rojo. Activar siempre que el usuario pida "implementar", "desarrollar", "ejecutar tareas", "codificar", "automatizar las pruebas", "implementa los test cases", "trabaja en el TK/WI/TC/FT" o variantes que impliquen escribir código desde una especificación ya redactada. - Skill: `juanca202/work-implement` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add juanca202/work-implement` - Raw SKILL.md: https://api.skillmd.com/api/skills/juanca202/work-implement/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: juanca202 (https://skillmd.com/u/juanca202) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/juanca202/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`](../../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/.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 `/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`](../../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`](../../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](#regla-de-handoff-transversal)). 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`](../../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`). | Tipo | Como se identifica | Que se implementa | Unidad de confirmacion | Flujo a leer | |------|--------------------|-------------------|------------------------|--------------| | **Tarea de historia de usuario** | El trabajo referencia una historia `US-XXX` o una tarea `TK-XXX` que cuelga de ella; el artefacto vive bajo `docs/specs/user-stories/` (o su equivalente archivado, ver la nota de abajo). | El plan tecnico de la TK (codigo de produccion + sus tests) | **Una `TK-XXX`** | `references/user-story-tasks.md` — **leer antes de implementar.** | | **Tarea de mantenimiento** | El trabajo referencia un `WI-XXX` (bug, refactor, deuda tecnica, dependencias, operativa) **sin historia asociada**; vive bajo `docs/specs/work-items/` (o su equivalente archivado, ver la nota de abajo). | El plan del WI (codigo de produccion + sus tests) | **El `WI-XXX` completo** | `references/work-items.md` — **leer antes de implementar.** | | **Caso de prueba** | El trabajo referencia uno o varios `TC-XXX`; viven en la carpeta `test-cases/` de un artefacto padre (`US-XXX`, `WI-XXX` o `FT-XXX`). | **Las pruebas automatizadas de esos `TC-XXX`** | **Un `TC-XXX`** | `references/test-cases.md` — **leer antes de implementar.** | | **Feature** | El trabajo referencia un `FT-XXX` — funcionalidad **ya implementada** registrada bajo `docs/specs/features/`. | **Las pruebas de todos los `TC-XXX` asociados a los `AC-XXX` que contiene el feature** — nunca funcionalidad nueva | **El `FT-XXX` completo** | `references/test-cases.md` — **leer antes de implementar.** | > **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`](../work-integrate/references/archive.md#contrato-para-el-resto-del-catálogo). 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](#modo-correccion-delegado-desde-quality-check)**: 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`](../work-integrate/references/archive.md#contrato-para-el-resto-del-catálogo). > **Modo correccion (entrada delegada desde [`quality-check`](../quality-check/SKILL.md#corrección-de-fallos)).** 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](#modo-correccion-delegado-desde-quality-check). 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](#arbol-principal-intocable-cuando-se-usan-worktrees-transversal). 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](#modo-correccion-delegado-desde-quality-check)) **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`](../../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`](references/work-items.md#excepcion-bug-fix-y-security-update-no-crean-rama)). 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** (`/`, en la rama del artefacto, creado con `git worktree add … [-b ] ` — sin checkout previo de la base, que es solo una referencia) y un **worktree por unidad** (`wt/`, 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 …`). «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`](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. | Situacion | Que hacer | |-----------|-----------| | Posponer una unidad | Mantener `Pending` y registrar el motivo en `Notas`. | | Sacar una unidad del alcance | Parar; alinear con el skill de planificacion correspondiente; eliminar la entrada si ya no aplica. | | Unidad completada | `Done`. | --- ## 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": "", "key": "` 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](#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](#uso-escalonado-de-pruebas-optimizacion) (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](#uso-escalonado-de-pruebas-optimizacion)), > 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`](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) | Condicion | Agente / MCP requerido | | --------- | ---------------------- | | La unidad genera o modifica archivos de UI (HTML, CSS, componentes) | Ejecutar bajo el agente `ui-specialist` **si el proyecto lo define** | | La unidad consiste en automatizar test cases (tipos `TC-XXX` / `FT-XXX`) | Ejecutar la escritura de las pruebas bajo el agente `quality-specialist` **si el proyecto lo define**, delegando via la herramienta Task | | La referencia de diseno es un enlace o archivo de Figma | Usar el **MCP de Figma** para obtener el contexto del diseno antes y durante la implementacion | 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](#arbol-principal-intocable-cuando-se-usan-worktrees-transversal): 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 / -b wt/ ` (p. ej. `.worktrees/TK-003` con rama `wt/TK-003`). `` es una **referencia**: no hace falta —ni se debe— hacer checkout de ella en el arbol principal …(truncated)