@factor_ec/ai-tools 0.1.0

package/templates/git-commit/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ab-git-commit
+description: 'Ejecutar git commit con análisis de mensajes conventional commits, staging inteligente y generación de mensajes. Usar cuando el usuario pida hacer commit de cambios, crear un git commit o mencione "/commit". Soporta: (1) Detección automática de tipo y scope desde los cambios, (2) Generación de mensajes conventional commit desde el diff, (3) Commit interactivo con opciones para sobrescribir tipo/scope/descripción, (4) Staging inteligente de archivos para agrupación lógica'
+license: MIT
+allowed-tools: Bash
+---
+
+# Git Commit con Conventional Commits
+
+## Resumen
+
+Crear commits de git estandarizados y semánticos usando la especificación Conventional Commits. Analizar el diff real para determinar el tipo, scope y mensaje apropiados.
+
+## Formato Conventional Commit
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Tipos de Commit
+
+| Tipo       | Propósito                         |
+| ---------- | --------------------------------- |
+| `feat`     | Nueva funcionalidad               |
+| `fix`      | Corrección de bug                 |
+| `docs`     | Solo documentación                |
+| `style`    | Formato/estilo (sin lógica)       |
+| `refactor` | Refactorización (sin feature/fix) |
+| `perf`     | Mejora de rendimiento             |
+| `test`     | Añadir/actualizar tests           |
+| `build`    | Sistema de build/dependencias     |
+| `ci`       | Cambios en CI/configuración       |
+| `chore`    | Mantenimiento/miscelánea          |
+| `revert`   | Revertir commit                   |
+
+## Cambios Breaking
+
+```
+# Signo de exclamación después de type/scope
+feat!: remove deprecated endpoint
+
+# Footer BREAKING CHANGE
+feat: allow config to extend other configs
+
+BREAKING CHANGE: `extends` key behavior changed
+```
+
+## Flujo de Trabajo
+
+### 1. Analizar el Diff
+
+```bash
+# Si hay archivos en staging, usar el diff staged
+git diff --staged
+
+# Si no hay nada en staging, usar el diff del árbol de trabajo
+git diff
+
+# También verificar el estado
+git status --porcelain
+```
+
+### 2. Añadir Archivos al Staging (si es necesario)
+
+Si no hay nada en staging o quieres agrupar los cambios de otra forma:
+
+```bash
+# Añadir archivos específicos
+git add path/to/file1 path/to/file2
+
+# Añadir por patrón
+git add *.test.*
+git add src/components/*
+
+# Staging interactivo
+git add -p
+```
+
+**Nunca hacer commit de secretos** (.env, credentials.json, claves privadas).
+
+### 3. Generar el Mensaje del Commit
+
+Analizar el diff para determinar:
+
+- **Tipo**: ¿Qué tipo de cambio es este?
+- **Scope**: ¿Qué área/módulo está afectado?
+- **Descripción**: Resumen en una línea de lo que cambió (tiempo presente, modo imperativo, <72 caracteres)
+
+### 4. Ejecutar el Commit
+
+```bash
+# Una sola línea
+git commit -m "<type>[scope]: <description>"
+
+# Multi-línea con body/footer
+git commit -m "$(cat <<'EOF'
+<type>[scope]: <description>
+
+<optional body>
+
+<optional footer>
+EOF
+)"
+```
+
+## Buenas Prácticas
+
+- Un cambio lógico por commit
+- Tiempo presente: "add" no "added"
+- Modo imperativo: "fix bug" no "fixes bug"
+- Referenciar issues: `Closes #123`, `Refs #456`
+- Mantener la descripción bajo 72 caracteres
+
+## Protocolo de Seguridad Git
+
+- NUNCA actualizar la configuración de git
+- NUNCA ejecutar comandos destructivos (--force, hard reset) sin petición explícita
+- NUNCA saltar hooks (--no-verify) a menos que el usuario lo pida
+- NUNCA hacer force push a main/master
+- Si el commit falla por hooks, corregir y crear un NUEVO commit (no amend)

package/templates/project-create/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: project-create
+description: Orienta la creación de un proyecto nuevo según el stack tecnológico disponible (Angular, React, Symfony u otros registrados), usando la plantilla del equipo en el repo del usuario. No crea ni modifica los repos plantilla. Si el usuario no indica el stack, el agente debe preguntar cuál desea antes de seguir. Para cada stack documentado, sigue el archivo en references/. Usar con skill project-create (/project-create) o cuando el usuario pida crear un proyecto de un stack concreto.
+---
+
+# Crear proyecto nuevo (desde proyecto base)
+
+## Qué es (y qué no es)
+
+- **Sí**: crear un **proyecto nuevo para el usuario** importando el contenido de un **proyecto base** ya mantenido por el equipo (template).
+- **No**: crear, publicar ni mantener el repositorio del proyecto base; ese es otro flujo.
+
+El patrón habitual: **repo git del usuario ya existente** → remote hacia la plantilla → **fetch/merge** → instalación de dependencias del stack → **sustitución** de nombres/IDs/envs según el tipo.
+
+---
+
+## Obligatorio: tipo de proyecto
+
+Antes de ejecutar comandos o merges:
+
+1. Si el usuario usa **`/project-create`** (skill **project-create**) o pide explícitamente “crear proyecto” / “nuevo proyecto desde plantilla”, **comprueba si ha indicado el stack tecnológico**: Angular, React, Symfony, u otro listado en [Registro de proyectos base](#registro-de-proyectos-base).
+2. **Si el tipo no está claro o no lo ha dicho**, **no asumas Angular ni otro stack**. **Pregunta de forma explícita**, por ejemplo: *¿Qué tipo de proyecto quieres crear? (Por ahora el procedimiento detallado está para **Angular**; **React** y **Symfony** están pendientes de documentar.)*
+3. Cuando el tipo esté claro, **lee el material de referencia de ese stack** (si existe) y sigue solo ese flujo.
+
+| Stack    | Referencia detallada | Estado |
+|----------|----------------------|--------|
+| Angular  | **[references/angular.md](references/angular.md)** — **leer este archivo al completo** cuando el usuario quiera un **proyecto Angular** nuevo desde la plantilla (no confundir con mantener el repo `angular-base-project`). | Completo |
+| React    | _pendiente_          | Preguntar; avisar si aún no hay `references/react.md`. |
+| Symfony  | _pendiente_          | Idem. |
+
+---
+
+## Convenciones comunes (cualquier stack)
+
+1. **Repo del usuario**: debe ser **raíz de un repositorio git** (`.git` presente). Si no: `git init` o clonar antes.
+2. **Remote hacia la plantilla**: convención `upstream` salvo que el repo ya lo use para otra cosa; si hay conflicto, acordar nombre y anotarlo en el registro.
+3. **Merge**: normalmente `git merge upstream/<rama-default> --allow-unrelated-histories` con mensaje que nombre el template.
+4. **Post-merge**: comandos del stack (`npm install`, `composer install`, …) y sustituciones acordadas.
+5. **Conflictos**: si el merge falla, orientar resolución manual.
+
+---
+
+## Registro de proyectos base
+
+Cada fila describe **de dónde** se parte para crear el **proyecto nuevo** del usuario. El detalle operativo por stack vive en `references/<stack>.md` cuando exista.
+
+| Tipo    | Repo del proyecto base | Referencia |
+|---------|-------------------------|------------|
+| Angular | `https://github.com/juanca202/angular-base-project.git` | [references/angular.md](references/angular.md) |
+| React   | _TBD_                   | _TBD_ |
+| Symfony | _TBD_                   | _TBD_ |
+
+### Extender este skill
+
+1. Añadir `references/<stack>.md` con el mismo nivel de detalle que Angular.
+2. Registrar la fila en [Registro de proyectos base](#registro-de-proyectos-base) y enlazar desde la tabla “tipo de proyecto”.
+3. Mantener la lista de stacks en la tabla alineada con los procedimientos reales de cada plantilla del equipo.

package/templates/project-create/references/angular.md

@@ -0,0 +1,124 @@
+# Proyecto nuevo Angular (desde plantilla `angular-base-project`)
+
+## Alcance
+
+Esta referencia describe cómo **crear un proyecto nuevo** para el usuario **a partir del proyecto base** del equipo (`angular-base-project`), dentro de un repositorio git **ya existente**.
+
+- **Aplica** cuando el usuario pida un **proyecto Angular** nuevo.
+- **No aplica** si el objetivo es **crear, publicar o mantener** el repositorio del proyecto base en sí; ese es otro proceso.
+
+---
+
+## Requisitos previos
+
+1. **Git**: el directorio de trabajo (`targetPath` o el actual) debe ser la **raíz de un repo** con `.git`. Si no existe: `git init` o clonar antes de seguir.
+2. **Herramientas**: `git` y **Node/npm** disponibles en el PATH para `npm install` y `npm start`.
+3. **Red**: acceso a GitHub para `git fetch` del remoto de la plantilla.
+
+---
+
+## Parámetros
+
+| Parámetro      | Obligatorio | Descripción |
+|----------------|-------------|-------------|
+| `projectName`  | Sí          | Nombre legible del paquete / app (ej. `mi-app`). |
+| `projectId`    | Sí          | Identificador (ej. `mi-app` o `com.empresa.miapp`). |
+| `targetPath`   | No          | Raíz del repo donde ejecutar; si se omite o está vacío: directorio actual. |
+
+### Validación
+
+Ambos `projectName` y `projectId` deben cumplir:
+
+- No vacíos; `projectName` máx. **64** caracteres, `projectId` máx. **128**.
+- Patrón: deben **empezar** con letra o número; el resto puede ser letras, números, `.`, `_`, `-` (regex: `^[a-zA-Z0-9][a-zA-Z0-9._-]*$`).
+
+---
+
+## Proyecto base (plantilla)
+
+| Concepto | Valor |
+|----------|--------|
+| URL del repo | `https://github.com/juanca202/angular-base-project.git` |
+| Nombre del remote | `upstream` |
+| Rama a integrar | `upstream/main` |
+| Mensaje de merge sugerido | `Merge angular-base-project template` |
+
+---
+
+## Procedimiento paso a paso
+
+Ejecutar desde la **raíz del repo del usuario** (`targetPath`).
+
+### 1. Añadir remote `upstream`
+
+```bash
+git remote add upstream https://github.com/juanca202/angular-base-project.git
+```
+
+- Si Git responde que el remote **ya existe** y apunta al repo correcto del equipo, **continuar** sin duplicar.
+- Si existe pero apunta a **otra** URL, no sobrescribir sin acuerdo con el usuario; puede ser un `upstream` legítimo para forks.
+
+### 2. Obtener la plantilla
+
+```bash
+git fetch upstream
+```
+
+### 3. Merge con historias no relacionadas
+
+```bash
+git merge upstream/main --allow-unrelated-histories -m "Merge angular-base-project template"
+```
+
+- Si hay **conflictos**, el usuario (o el agente guiando) debe resolverlos antes de seguir.
+- Si la plantilla cambiara la rama por defecto en el futuro, ajustar la ref (`upstream/<rama>`) según el registro del skill principal.
+
+### 4. Dependencias
+
+```bash
+npm install
+```
+
+En la raíz del proyecto (donde está `package.json` tras el merge).
+
+### 5. Personalizar `package.json`
+
+- Campo **`name`**: debe quedar como `projectName` (valor JSON entre comillas dobles).
+
+Sustituir el valor actual del campo `"name"` por `projectName`.
+
+### 6. Personalizar environments (si existen)
+
+Archivos típicos (rutas relativas al repo):
+
+- `src/environments/environment.ts`
+- `src/environments/environment.development.ts`
+
+En cada uno que exista, alinear:
+
+- `appName: '…'` → `appName: '<projectName>'` (comillas simples como en la plantilla esperada).
+- `appId: '…'` → `appId: '<projectId>'`
+
+Si la plantilla añade más archivos `environment.*.ts`, aplicar la misma convención si existe `appName` / `appId`.
+
+---
+
+## Después del setup
+
+```bash
+npm start
+```
+
+Desde la raíz del proyecto. Confirmar la ruta final con el usuario si usó `targetPath` distinto del cwd.
+
+---
+
+## Errores habituales
+
+| Situación | Qué hacer |
+|-----------|-----------|
+| No hay `.git` en la ruta | Inicializar o clonar repo antes. |
+| `git remote add` falla por otra razón que no sea “already exists” | Revisar stderr; corregir URL o nombre de remote. |
+| `git fetch` / `git merge` fallan | Red, permisos, rama inexistente, o **conflictos** en merge. |
+| `npm install` falla | Revisar versión de Node, lockfile, y errores de red/registry. |
+| Validación de nombres | Ajustar `projectName` / `projectId` al patrón y longitudes indicados. |

package/templates/user-story-add-task/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: user-story-add-task
+description: Crea especificaciones en TK-XXX.md bajo docs/product/US-.../ (sin implementar código), con metadatos, unidad de trabajo obligatoria e implementador previsto opcional (inferible con git config user.name o lo que indique el usuario). Enlaza technical-docs y docs/adr; valida coherencia con la historia (US) y otras tareas.
+---
+
+# Crear tarea de historia de usuario (TK-XXX)
+
+## Alcance de este skill: solo especificaciones
+
+Cuando se pida **crear una tarea**, el agente debe producir **únicamente el documento de especificación** (`TK-XXX-....md`) y, si corresponde, actualizar o enlazar documentación existente autorizada. **No implementar** código, migraciones, APIs ni pruebas: solo redactar las especificaciones que luego guiarán la implementación.
+
+## Cuándo aplicar
+
+Al documentar trabajo técnico asociado a una historia de usuario existente.
+
+**Prerrequisito:** debe existir la carpeta `docs/product/US-XXX-[nombre-corto]/` con su `README.md`.
+
+Las historias de usuario pueden descomponerse en tareas técnicas. Cada tarea se documenta en un **archivo independiente** dentro de la carpeta de la historia.
+
+## Contexto obligatorio: la historia de usuario
+
+Antes de redactar o crear el archivo de tarea:
+
+1. **Leer y usar** el `README.md` de la historia (US-XXX) a la que pertenece la tarea como contexto principal (Como/Quiero/Para, características, reglas de negocio, criterios de aceptación).
+2. **Revisar todas las tareas ya existentes** en esa misma carpeta (`TK-*.md` del mismo `US-XXX`) y comprobar que la nueva tarea **no contradiga** alcances, supuestos ni entregables de las demás; si hay solapamiento o conflicto, **aclarar con el usuario** o ajustar el alcance en el documento antes de dar la tarea por **lista para implementar**.
+
+## Aclaraciones previas
+
+Si la descripción solicitada para la tarea es **poco clara**, **incompleta** o **ambigua**, **no crear** aún el `TK-XXX-....md`. **Preguntar al usuario** lo necesario (límites técnicos, flujos, datos, integraciones, dependencias entre tareas, etc.) y **solo cuando la información sea suficiente** para cumplir la validación previa (apartado siguiente), proceder a la creación del documento.
+
+## Validación previa a la creación del documento
+
+Antes de crear el archivo de tarea, comprobar lo siguiente. Si algo no se cumple, resolver preguntando o completando referencias — **no avanzar** con un TK vacío o genérico.
+
+- **Sin ambigüedades:** la descripción y el alcance técnico se entienden sin suposiciones ocultas.
+- **Contexto técnico suficiente** en la medida que aplique, referenciado o explícito: por ejemplo modelo **entidad-relación** o esquema de datos, **DTOs** o contratos, **flujos** (secuencia, estados), y decisiones de arquitectura ya documentadas.
+- **ADRs y arquitectura:** las definiciones arquitectónicas deben **apoyarse en ADRs existentes** bajo **`docs/adr/`**. **No crear** archivos ADR de forma automática. Si la tarea revela la necesidad de una decisión arquitectónica no documentada, **sugerir al usuario** que conviene añadir o actualizar un ADR en `docs/adr/` y enlazarlo desde la tarea cuando exista.
+- **Referencias:** usar `docs/product/technical-docs/` para detalle técnico de producto (DTOs, endpoints, etc.) cuando aporte claridad, y rutas al código o contratos del repo según el proyecto.
+- **Unidad de trabajo:** debe estar definida (inferida con criterio o confirmada por el usuario); sin ella, no crear el TK.
+
+## Ubicación
+
+- Directorio: `docs/product/US-XXX-[nombre-corto]/` (mismo nivel que `README.md` y `assets/`).
+- Documentación transversal (DTOs, contratos API, etc.): `docs/product/technical-docs/`, enlazada con rutas relativas desde la tarea (`../technical-docs/...`).
+- Decisiones de arquitectura: enlazar archivos bajo **`docs/adr/`** con ruta relativa adecuada desde el repo (p. ej. `../../../docs/adr/...` según la profundidad real del proyecto).
+
+## Formato del nombre del archivo
+
+`TK-XXX-[nombre-descriptivo].md`
+
+**Convenciones:**
+
+- El prefijo `TK-XXX` debe estar en mayúsculas (ejemplo: `TK-001`, `TK-002`)
+- El número es secuencial **dentro de la historia**
+- El nombre descriptivo debe estar en minúsculas y en formato kebab-case
+- Ejemplos: `TK-001-seleccion-materiales.md`, `TK-002-creacion-dry-good-temporal.md`
+
+## Metadatos en cabecera y unidad de trabajo
+
+Toda tarea debe incluir al inicio del cuerpo (después del título `#`), una lista de metadatos **en el mismo espíritu** que la historia de usuario:
+
+- **ID:** `TK-XXX` (alineado al archivo y al título)
+- **Nombre corto:** etiqueta breve de la tarea
+- **Estado:** Draft / Ready / In Progress / Done
+- **Prioridad:** Alta / Media / Baja
+
+### Implementador previsto (opcional)
+
+Campo **no obligatorio** que indica **quién** tiene previsto implementar la tarea.
+
+- Si el **usuario** indica responsable o implementador, usar **esa** indicación.
+- Si no lo indica y conviene rellenarlo, el agente puede **inferir** el valor con la configuración de Git del entorno: `git config user.name` (nombre habitual en el repo local). Si no hay valor útil, omitir la línea o dejar explícito que está pendiente de asignar.
+- **No** es requisito para dar la tarea por lista para implementar: se puede omitir toda la línea.
+
+### Unidad de trabajo (obligatoria)
+
+El campo **Unidad de trabajo** es **obligatorio** en cada `TK-XXX`: identifica *dónde* o *en qué artefacto del ecosistema* se ejecuta principalmente el trabajo (paquete, app, módulo, servicio, librería, etc.).
+
+- **Inferencia:** si el contexto del repositorio lo permite, el agente puede **inferir** la unidad sin preguntar. Ejemplos:
+  - Proyecto **npm/node:** el campo `name` del `package.json` más cercano al alcance de la tarea (raíz del paquete o workspace).
+  - **Monorepo:** nombre del paquete o app concreta (según `package.json`, `pnpm-workspace`, `nx.json`, etc.).
+  - Otros tipos: equivalente habitual del stack (módulo Gradle/Maven, proyecto .NET, crate de Rust, etc.) según archivos del repo.
+- Si **no** está claro qué conviene (varios paquetes, límites difusos, tarea transversal), **preguntar al usuario** qué unidad de trabajo debe constar antes de crear el documento.
+
+En la plantilla, el valor debe quedar escrito de forma explícita (p. ej. `**Unidad de trabajo:** @scope/mi-paquete` o el nombre acordado con el usuario).
+
+## Plantilla del documento
+
+```markdown
+# TK-XXX: Título corto de la tarea
+
+- **ID:** TK-XXX
+- **Nombre corto:**
+- **Estado:** Draft / Ready / In Progress / Done
+- **Prioridad:** Alta / Media / Baja
+- **Unidad de trabajo:** _[obligatorio: paquete/módulo/servicio/etc.; inferido del proyecto o indicado por el usuario]_
+- **Implementador previsto:** _[opcional — priorizar lo indicado por el usuario; si no, inferir con `git config user.name`; omitir línea si no aplica]_
+
+## Descripción
+
+[Descripción técnica de qué implementar y desde dónde se accede — sin ambigüedad]
+
+## Referencias
+
+- **Historia de usuario:** [US-XXX](./README.md) — Nombre de la historia
+- **ADRs (arquitectura):** enlaces a `docs/adr/...` cuando la tarea dependa de decisiones ya registradas; no inventar ADRs nuevos
+- **Documentación técnica (producto):** [título](../technical-docs/archivo.md) — DTOs, ER, flujos, endpoints en `docs/product/technical-docs/` si aplica
+- **Modelos de datos / código:** rutas o enlaces en el repo
+- **Diseño:** [Figma - ...](URL)
+- **Punto de acceso:** ruta en el código
+- **Plantilla:** componente o patrón a reutilizar
+
+## Componentes a usar
+
+- Lista de componentes UI o servicios existentes
+
+## Criterios de aceptación
+
+- Criterio 1
+- Criterio 2
+- ...
+
+## Alcance técnico
+
+- Modelos, DTOs, componentes, repositorios, mutaciones involucradas
+```
+
+## Alcance del contenido (técnico)
+
+La tarea debe ser **técnica**: implementación *descrita*, componentes, modelos, repositorios y criterios verificables por desarrollo. No duplicar la narrativa funcional de la historia de usuario; enlazar `./README.md`.
+
+### Validación de contexto (funcional vs técnico)
+
+Antes de dar una tarea por **lista para implementar**, valida que el contexto sea **técnico** (no solo lenguaje funcional del `README.md` de la historia).
+
+| Artefacto | Contexto esperado | Ejemplo |
+| --- | --- | --- |
+| **Historia de usuario** (`README.md`) | **Funcional** — valor para el usuario, negocio y criterios en lenguaje de dominio | "Como desarrollador quiero agregar materiales temporales para analizar costos" |
+| **Tarea** (`TK-XXX`) | **Técnico** — implementación, componentes, modelos, repositorios y criterios verificables por desarrollo | "Implementar el diálogo DryGoodPicker usando Material Button, Checkbox y DryGoodRepository" |
+
+Para la historia: contexto funcional. Para la tarea: contexto técnico y **lista para implementar** solo si cumple las validaciones de este skill.
+
+## Checklist de evaluación — Tarea (lista para implementar)
+
+Antes de considerar una tarea **lista para implementar**, pásala por este checklist:
+
+- ¿Está alineada con el `README.md` de la historia (misma carpeta `US-XXX-...`) y **no entra en conflicto** con otras `TK-*.md` de la misma historia?
+- ¿La descripción **no tiene ambigüedades** y el contexto necesario está citado o descrito (ER, DTOs, flujos, **ADRs en `docs/adr/`**, etc.)?
+- ¿Tiene referencia explícita a la historia de usuario?
+- ¿La descripción usa contexto técnico (no funcional)?
+- ¿Incluye referencias necesarias (technical-docs, diseño, punto de acceso, plantilla, ADRs existentes)?
+- ¿Los criterios de aceptación son verificables por desarrollo?
+- ¿El alcance técnico está definido (componentes, repositorios, DTOs)?
+- ¿Está acotada y se puede implementar en un sprint?
+- ¿Se ha **especificado** el trabajo sin **implementar** código en el repositorio?
+- ¿Consta la **unidad de trabajo** (inferida del tipo de proyecto o confirmada preguntando al usuario)?
+- (Opcional) Si figura **Implementador previsto**, ¿coincide con lo dicho por el usuario o con `git config user.name` cuando se infirió?
+
+## Pasos para el agente
+
+1. Leer `./README.md` de la historia objetivo (carpeta `docs/product/US-XXX-...`) y **todas** las tareas `TK-*.md` ya existentes en esa carpeta; detectar solapamientos o conflictos y resolverlos con el usuario o en el texto.
+2. Determinar **unidad de trabajo**: revisar contexto del repo (p. ej. `package.json`, estructura de monorepo) para inferirla; si no es clara, **preguntar al usuario** antes de crear el archivo.
+3. **Implementador previsto (opcional):** si el usuario indica quién implementa, usar ese valor; si no y conviene rellenarlo, obtener `git config user.name` en el repositorio y añadir el campo solo si el resultado es útil; en caso contrario omitir la línea.
+4. Si la petición es incompleta o ambigua, **preguntar aclaraciones**; **no crear** el archivo hasta tener información suficiente para la [Validación previa a la creación del documento](#validación-previa-a-la-creación-del-documento).
+5. Verificar criterios de validación previa (sin ambigüedad, unidad de trabajo definida, contexto ER/DTOs/flujos/ADRs según aplique; **ADRs solo como referencia a `docs/adr/`** o sugerencia explícita al usuario si falta decisión documentada).
+6. Identificar el siguiente `TK-XXX` en esa carpeta.
+7. **Solo entonces** crear el archivo `TK-XXX-....md` con la plantilla (metadatos + **Unidad de trabajo** rellenados; **Implementador previsto** solo si aplica); **no** implementar producto ni tests.
+8. Si hace falta documentación en `docs/product/technical-docs/`, crear o actualizar allí y enlazar; **no** crear ADRs automáticamente — sugerir al usuario si procede.
+9. Asegurar el enlace a la historia de usuario: `[US-XXX](./README.md)`.

package/templates/user-story-create/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: user-story-create
+description: Crea historias de usuario US-XXX bajo docs/product/ con plantilla funcional, Given/When/Then, INVEST, Fibonacci y Definition of Ready. Si la descripción o características son ambiguas o faltan datos para INVEST, pregunta al usuario antes de crear la historia. Usar al crear historias de usuario o docs de producto; technical-docs cuando corresponda.
+---
+
+# Crear historia de usuario
+
+## Cuándo aplicar
+
+Al generar o reorganizar una historia de usuario según las convenciones de este repositorio.
+
+## Aclaraciones previas (INVEST)
+
+Antes de crear la historia, revisar la **descripción**, las **características**, reglas de negocio y cualquier contexto aportado. Si hay **ambigüedad**, **huecos** o **falta de información** que impida completar con criterio honesto la **validación INVEST** (p. ej. usuario o valor poco claro, alcance indefinido, dependencias desconocidas, criterios de aceptación imposibles de testear sin más detalle), **no** crear aún la carpeta ni el `README.md`.
+
+En ese caso, **preguntar al usuario** de forma explícita todo lo necesario: actor y beneficio, límites del alcance, reglas y excepciones, integraciones o dependencias con otras historias (US) o sistemas, supuestos de datos o permisos, y cualquier matiz que permita redactar criterios **Given / When / Then** y valorar **I, N, V, E, S, T** sin forzar respuestas. Solo cuando los insumos sean suficientes, proceder con la creación de la historia.
+
+## Estructura de carpetas
+
+Cada historia de usuario se organiza bajo **`docs/product/`**:
+
+```
+docs/product/
+├── technical-docs/              (Opcional — documentación técnica transversal o por feature)
+│   └── ...
+└── US-[Número]-[Nombre-corto]/
+    ├── README.md                (Historia de usuario — contexto funcional)
+    ├── TK-XXX-[nombre-tarea].md (Tareas — contexto técnico, opcional; ver skill user-story-add-task)
+    └── assets/
+        ├── imagen-1.png
+        ├── diagrama-flujo.svg
+        └── ...
+```
+
+**`docs/product/technical-docs/`:** usar para documentar DTOs, entidades, endpoints, reglas de negocio **técnicas** (validaciones, contratos API, invariantes de implementación), etc. Las reglas en **lenguaje de negocio** siguen en el `README.md` de la historia. Nombrar archivos en kebab-case y enlazarlos desde el `README.md` o desde los `TK-XXX` con rutas relativas (por ejemplo `../technical-docs/contrato-api.md`).
+
+### Convenciones del nombre de carpeta
+
+- El nombre de la carpeta debe seguir el formato: `US-XXX-[nombre-corto]`
+  - El código `US-XXX` debe estar en mayúsculas (ejemplo: `US-001`, `US-002`)
+  - El nombre corto debe estar completamente en minúsculas
+  - El nombre corto debe ser en formato kebab-case (palabras separadas por guiones)
+  - **El nombre debe ser descriptivo pero corto**: eliminar palabras innecesarias como artículos ("de", "del", "la", "una"), preposiciones redundantes y frases largas. Priorizar palabras clave que identifiquen claramente la funcionalidad.
+  - Ejemplos de nombres cortos y descriptivos:
+    - `US-001-seleccion-item-sdp-desde-receta` (en lugar de "seleccion-de-item-de-sdp-cuando-estoy-en-la-receta")
+    - `US-002-seleccion-item-sdp-desde-sdp` (en lugar de "seleccion-de-item-de-sdp-cuando-estoy-en-el-sdp")
+    - `US-003-mostrar-contexto-al-crear-receta` (en lugar de "mostrar-datos-de-contexto-al-crear-una-receta")
+    - `US-004-resumen-costos-receta` (en lugar de "visualizar-resumen-de-costos-de-la-receta")
+    - `US-007-importar-receta` (en lugar de "importar-una-receta")
+- El archivo principal siempre debe llamarse `README.md`
+- Todas las imágenes y recursos visuales deben estar en la carpeta `assets/`
+- Las referencias a imágenes en el README.md deben usar rutas relativas: `![Descripción](assets/nombre-imagen.png)`
+
+## Plantilla README.md
+
+Usar esta estructura en el `README.md` de la carpeta de la historia (`US-XXX-...`).
+
+````markdown
+- **ID:** US-XXX
+- **Nombre corto:**
+- **Estado:** Draft / Ready / In Progress / Done
+- **Prioridad:** Alta / Media / Baja
+
+## Descripción
+
+**Como** _[tipo de usuario]_
+**Quiero** _[necesidad / acción]_
+**Para** _[beneficio / resultado esperado]_
+
+## Características
+
+- Característica 1:
+- Característica 2:
+- Característica 3:
+
+## Reglas de negocio
+
+- Regla 1
+- Regla 2
+- Regla 3
+
+## Criterios de Aceptación
+
+Formato **Given / When / Then** (obligatorio para considerarse "Ready").
+
+```gherkin
+Given
+When
+Then
+```
+
+## Validación INVEST
+
+La historia debe alinearse con el modelo **INVEST**. Marcar cada criterio solo si se cumple; si alguno no aplica o está en riesgo, documentarlo en observaciones.
+
+- [ ] **I — Independiente:** se puede entregar valor sin quedar bloqueada por otras historias no resueltas (o las dependencias están explícitas y acotadas).
+- [ ] **N — Negociable:** el detalle del *qué* es discutible con producto; no impone solución técnica cerrada.
+- [ ] **V — Valiosa:** beneficio claro para usuario o negocio.
+- [ ] **E — Estimable:** hay suficiente contexto para que el equipo estime con confianza razonable.
+- [ ] **S — Pequeña:** alcance acotado para completarse en un sprint; si no, conviene dividir la historia.
+- [ ] **T — Testeable:** los criterios de aceptación permiten comprobar el resultado de forma objetiva.
+
+## Complejidad (Fibonacci)
+
+Usar la escala típica de story points: **1, 2, 3, 5, 8, 13** (solo Fibonacci en ese conjunto).
+
+- **Story points propuestos:** _[elegir uno: 1 | 2 | 3 | 5 | 8 | 13]_
+- **Justificación breve:** _[por qué ese valor: incertidumbre, alcance, integraciones, riesgo]_
+
+El agente debe **proponer** un valor y una justificación acorde al alcance descrito; el equipo puede ajustarlo en refinamiento.
+
+## Definition of Ready
+
+Criterios para considerar la historia lista para entrar a planificación / desarrollo. Marcar cuando se cumplan:
+
+- [ ] Descripción **Como / Quiero / Para** clara y sin ambigüedad mayor
+- [ ] Criterios de aceptación en **Given / When / Then** redactados
+- [ ] Reglas de negocio y alcance revisados con producto (o explícitamente pendientes en Observaciones)
+- [ ] **INVEST** revisado; bloqueos o dependencias críticas documentadas
+- [ ] Dependencias externas identificadas (diseño, APIs, datos, otras historias US, flags)
+- [ ] **Estimación Fibonacci** propuesta y registrada arriba
+- [ ] Prioridad y valor de negocio coherentes con el backlog
+
+## Observaciones
+
+- Observaciones adicionales:
+- Notas importantes:
+- Decisiones pendientes:
+````
+
+## Alcance del contenido (funcional)
+
+La historia debe ser **funcional**: valor para el usuario, el problema de negocio y los criterios de aceptación en lenguaje de dominio — no detalle de implementación (eso va en tareas `TK-XXX` y en `technical-docs/` si aplica).
+
+### Validación de contexto
+
+Antes de dar una historia por **lista**, valida que el contexto sea **funcional** (no técnico).
+
+| Artefacto | Contexto esperado | Ejemplo |
+| --- | --- | --- |
+| **Historia de usuario** (`README.md`) | **Funcional** — valor para el usuario, negocio y criterios en lenguaje de dominio | "Como desarrollador quiero agregar materiales temporales para analizar costos" |
+| **Tarea** (`TK-XXX`) | **Técnico** — implementación, componentes, modelos, repositorios y criterios verificables por desarrollo | "Implementar el diálogo DryGoodPicker usando Material Button, Checkbox y DryGoodRepository" |
+
+Para crear o revisar tareas, usar el skill **user-story-add-task**.
+
+## Checklist de evaluación — Historia de usuario
+
+Antes de dar una historia como "lista", pásala por este checklist (complementa **INVEST** y **Definition of Ready** en la plantilla):
+
+- ¿Tiene usuario, acción y razón?
+- ¿Es comprensible por producto y dev?
+- ¿Tiene criterios de aceptación claros?
+- ¿Se puede verificar con pruebas?
+- ¿Tiene criterios de "no casos"? (edge cases)
+- ¿Está acotada / no es demasiado grande?
+
+## Pasos para el agente
+
+1. Analizar descripción, **características** y contexto: si hay ambigüedad o falta información para cumplir **INVEST** con rigor, **preguntar primero** al usuario (ver [Aclaraciones previas](#aclaraciones-previas-invest)); no crear archivos hasta tener respuestas suficientes.
+2. Determinar el siguiente `US-XXX` si no lo da el usuario (revisar carpetas `US-*` existentes en `docs/product/`).
+3. Proponer `nombre-corto` en kebab-case según las convenciones anteriores.
+4. Crear carpeta `docs/product/US-XXX-[nombre-corto]/` y `assets/` si hay o habrá imágenes.
+5. Escribir `README.md` con la plantilla completa, rellenando con la información del usuario.
+6. Si el usuario pide DTOs, entidades, endpoints o reglas técnicas documentadas: crear `docs/product/technical-docs/` si no existe y añadir o actualizar los documentos allí; enlazarlos desde la historia o desde las tareas.
+7. Completar **Validación INVEST** (valorar cada letra; si algo falla, anotarlo en Observaciones).
+8. **Proponer story points (Fibonacci: 1, 2, 3, 5, 8, 13)** con justificación breve según alcance, riesgo e incertidumbre.
+9. Rellenar el checklist **Definition of Ready**; estado **Ready** implica criterios Given/When/Then en gherkin y, idealmente, DoR marcado en lo esencial según el equipo.