@factor_ec/ai-tools 0.1.0

package/templates/work-item-develop/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: work-item-develop
+description: Implementa trabajo desde docs/product (US-XXX y/o TK-XXX). Si solo se da TK-XXX, pregunta primero a qué US pertenece. Respeta unidad de trabajo e implementador, progress.md, una tarea por vez y sin tests hasta el final. Usar al desarrollar o ejecutar ítems de producto.
+---
+
+# Desarrollar ítem de trabajo (US / TK)
+
+## Cuándo aplicar
+
+Cuando el usuario pida **implementar**, **desarrollar** o **ejecutar** trabajo descrito en documentación de producto: referencia **US-XXX**, **TK-XXX**, ruta a `docs/product/US-.../` o a un `TK-....md` concreto.
+
+Las especificaciones siguen las convenciones de **user-story-create** y **user-story-add-task** (`README.md` + `TK-XXX-....md` bajo `docs/product/US-XXX-[nombre]/`).
+
+## Entrada del usuario (resolver el alcance)
+
+Aceptar cualquiera de:
+
+- Identificador de historia: `US-001`, `US-123` (buscar carpeta `docs/product/US-XXX-*` que coincida en número).
+- Identificador de tarea: `TK-001` — ver regla obligatoria siguiente.
+- Ruta a carpeta de historia o a un archivo `TK-*.md`.
+
+### Solo se indica el número de tarea (`TK-XXX`)
+
+Si el usuario **solo** especifica una tarea (p. ej. «implementa **TK-002**») **sin** decir a qué historia pertenece **ni** dar una ruta de archivo/carpeta que fije la US, **no** buscar ni implementar todavía: **preguntar explícitamente** de qué historia de usuario **`US-XXX`** corresponde esa tarea y **solo continuar** cuando el usuario la identifique (o proporcione ruta equivalente).
+
+**No aplica** esta pregunta cuando ya está claro el vínculo, por ejemplo: el usuario menciona **US-XXX y TK-XXX** en el mismo mensaje; la entrada es una **ruta** a `docs/product/US-.../TK-....md`; o el archivo abierto en contexto ya asocia la tarea a una carpeta `US-XXX-*` y el usuario lo confirma.
+
+Si hay ambigüedad adicional (varias carpetas con el mismo `US-XXX`, varios archivos que coinciden), **preguntar** antes de implementar.
+
+## Archivo `progress.md` (obligatorio en el flujo)
+
+**Ubicación:** `docs/product/US-XXX-[nombre-corto]/progress.md` (junto al `README.md` de esa historia).
+
+**Antes de implementar:**
+
+1. **Buscar** si `progress.md` ya existe en esa carpeta.
+2. Si existe: **leerlo** y respetar tareas **done** (no repetir implementación); si hay **in-progress**, revisar `notes` y archivos listados para continuar desde el estado real del repo.
+3. Si no existe: **crearlo** al iniciar con estructura mínima (ver plantilla abajo).
+
+**Durante el trabajo:** actualizar `progress.md` al cambiar de estado de cada tarea (`pending` → `in-progress` → `done`) y al añadir archivos tocados o notas.
+
+**Identificador de tarea en el progreso:** usar **`TK-XXX`** (mismo que el prefijo del archivo), no alias arbitrarios.
+
+### Plantilla sugerida
+
+```markdown
+# Progress
+
+## user-story: US-XXX
+status: in-progress
+work-unit: "[opcional: unidad filtrada, p. ej. name del package.json]"
+implementador-filter: "[opcional: nombre si solo aplica a ese implementador]"
+
+### tasks
+
+- id: TK-001
+  title: Título breve de la tarea
+  status: pending
+  implementador-previsto: "[si consta en el TK]"
+  files: []
+  notes: []
+
+- id: TK-002
+  title: ...
+  status: in-progress
+  files:
+    - src/ejemplo.ts
+  notes:
+    - Subpaso o decisión técnica puntual
+```
+
+Valores de **status** recomendados: `pending`, `in-progress`, `done`, `skipped` (si el usuario acuerda omitir).
+
+## Qué implementar (filtros)
+
+### 1) Entrada solo **US-XXX**
+
+- Leer `README.md` y **todos** los `TK-*.md` de la carpeta + referencias enlazadas (`../technical-docs/`, `docs/adr/`, código citado).
+- **Unidad de trabajo actual:** inferir la del contexto de ejecución (p. ej. `name` del `package.json` del workspace o paquete abierto en el IDE). **Solo** encolar tareas cuyo campo **Unidad de trabajo** del TK coincida con esa unidad (comparación razonable: igualdad o prefijo `@scope/pkg`). Si no se puede inferir, **preguntar** al usuario qué unidad usar.
+- **Implementador previsto:** obtener `git config user.name`. Si el TK incluye **Implementador previsto**, solo ejecutar tareas donde ese campo coincida de forma razonable con el nombre de git o con un nombre que el usuario haya indicado en el chat **antes** de filtrar. Si el TK **no** tiene implementador, puede entrar en la cola salvo otras reglas.
+- **Excepciones por instrucción del usuario:** si dice explícitamente **todas** las tareas, **una lista** (`TK-001`, `TK-003`) o **un nombre** de persona distinto, **priorizar** esa instrucción sobre el filtro por git.
+
+### 2) Entrada **TK-XXX** o archivo de tarea
+
+- Cumplir primero [Solo se indica el número de tarea](#solo-se-indica-el-número-de-tarea-tk-xxx): si hacía falta, ya se conoce la **US** vinculada.
+- Implementar **esa** tarea (y solo esa), salvo que el usuario pida explícitamente más. Actualizar solo la entrada correspondiente en `progress.md`.
+
+### 3) Orden
+
+- Respetar orden numérico `TK-001`, `TK-002`, … salvo dependencias obvias en el texto; si hay conflicto, **preguntar**.
+
+## Ritmo de implementación (una tarea por vez)
+
+1. Completar **una** tarea TK según su descripción, alcance y criterios de aceptación.
+2. Validar con **lint** o **build** del paquete/unidad de trabajo afectada si existe en el proyecto.
+3. **No** añadir ni ejecutar **pruebas unitarias ni E2E** durante este ciclo.
+4. Marcar la tarea en `progress.md` como **done** (o actualizar **in-progress** con notas si quedó a medias).
+5. **Preguntar al usuario** si desea continuar con la siguiente tarea. **No** arrancar la siguiente sin confirmación explícita.
+
+## Validación sin tests
+
+Mientras dure el desarrollo por tareas:
+
+- Permitido: linters, typecheck, `npm run build` / equivalente del stack.
+- No permitido: escribir o lanzar suites de tests unitarios o E2E hasta la fase final acordada.
+
+## Cierre: pruebas (solo si el usuario acepta)
+
+Cuando no queden tareas pendientes en el alcance acordado (o el usuario detiene el flujo):
+
+1. **Preguntar** si debe implementarse **prueba unitaria** (y en su caso E2E) para el trabajo realizado.
+2. Si acepta: basar casos en los **criterios de aceptación** más relevantes del **`README.md`** de la US **y** de cada **TK** ejecutado; no duplicar cobertura superflua.
+3. Si rechaza: dejar constancia en `progress.md` (nota bajo la historia o tarea).
+
+## Pasos resumidos para el agente
+
+1. Si la entrada es solo `TK-XXX` sin US ni ruta explícita, **preguntar la historia `US-XXX`** y detenerse hasta tenerla.
+2. Resolver ruta de la historia US y lista de TK afectados; leer `progress.md` o crearlo.
+3. Aplicar filtros (unidad de trabajo, implementador, instrucciones explícitas del usuario).
+4. Para **cada** tarea en orden: implementar → lint/build → actualizar `progress.md` → **preguntar si continúa**.
+5. Al terminar el conjunto acordado: ofrecer fase de tests según criterios de la US y TK.
+
+## Relación con otros skills
+
+- **user-story-add-task** define el formato de los TK (metadatos, unidad de trabajo, implementador previsto); este skill **consume** esas especificaciones para código real, no para redactar TK nuevos salvo correcciones menores acordadas con el usuario.