@dforce2055/dai 0.1.0

package/skills/dai-review/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: dai-review
+description: Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai, y deja un comentario estándar en español con errores y mejoras. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), compone el comentario estándar y lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme.
+---
+
+# dai-review — review de PR consciente de la metodología
+
+Es el **primer pase** del paso 6 (code review). No reemplaza al partner humano: le
+saca el ruido para que firme lo que importa ([Art. 5](../../docs/MANIFIESTO.md#art-5) del manifiesto). Funciona igual
+en **GitHub y GitLab**.
+
+## Las dos caras (cómo postea el comentario)
+
+Mismo comentario estándar, dos formas de dejarlo (elige la disponible, en este orden):
+
+1. **MCP del forge** — si hay un MCP de GitHub/GitLab conectado, postea por ahí.
+2. **CLI con token** — si no, `dai forge comment <ref> --body-file <archivo>`. Usa
+   `GITHUB_TOKEN`/`GITLAB_TOKEN` del `.env` (token scopeado, **nunca** contraseña).
+
+> **Auth:** git (traer la branch) usa **SSH**; comentar la PR usa **token del forge**
+> (comentar no se puede por SSH). Cero contraseñas.
+
+## Input
+
+- **Ref de la PR/MR:** URL completa o solo el número (con el remoto git configurado).
+- Si no viene, intenta inferirla de la branch actual; si no, pedila.
+
+## Proceso
+
+1. **Resolver la PR** — `dai forge pr <ref>` (o el MCP) para título, descripción, branch.
+2. **Traer el diff** — `git fetch` + `git diff <base>...<branch>` (local, por SSH). No
+   dependas de la API para el diff.
+3. **Chequeos de metodología (mecánicos, deterministas):**
+   - `dai check` → ¿la US quedó **atrasada** (ac_hash) respecto de la viva?
+   - ¿existe `implements.yaml`? (si es un PR de producto, es obligatorio)
+   - **Definition of Done** (`templates/definition-of-done.md`): cuenta cuántos ítems cumple.
+4. **Review de código (criterio, no mecánico):** busca
+   - 🔴 **Errores** de correctitud (bugs, casos borde, seguridad).
+   - 🟡 **Mejoras** de calidad (reuso, simplicidad, eficiencia).
+   - ✅ Lo que está **bien** (refuerza lo bueno).
+5. **Componer el comentario estándar** (ver formato abajo).
+6. **Postear** por MCP o `dai forge comment`. Confirmar el link al comentario.
+
+## El comentario estándar
+
+Es el mismo que emite `renderReviewComment` del CLI — respeta esta forma:
+
+```markdown
+## 🤖 dai-review
+
+**US:** `ABC-482` @ v1 · `dai check`: ✅ al día
+**Definition of Done:** 4/5
+
+### 🔴 Errores (correctitud)
+- <hallazgo concreto con archivo:línea>
+
+### 🟡 Mejoras (calidad, reuso, simplicidad)
+- <sugerencia concreta>
+
+### ✅ Lo que está bien
+- <algo real y específico>
+
+---
+_Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manifiesto)._
+```
+
+## Dos cortes duros
+
+1. **No aprobar.** La skill **comenta**, no firma la aprobación. Eso es de un humano.
+2. **Hallazgos concretos.** Nada de "mejorar la calidad" en abstracto: archivo, línea,
+   y el porqué. Si no es accionable, no va.
+
+## Relación con el modelo
+
+- Es el paso 6 de [`SCRUM-CON-IA.md`](../../docs/SCRUM-CON-IA.md).
+- Se apoya en `dai check` (ADR-0003) y en el forge adapter (`dai forge`, ADR-0002:
+  lo mecánico en el CLI, la inteligencia en la skill).
+- El comentario estándar hace que todos los reviews del equipo se lean igual.

package/skills/doc-to-backlog/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: doc-to-backlog
+description: Toma un documento de análisis (PDF, Word, o un archivo en Drive/SharePoint/ClickUp vía MCP) y produce un BACKLOG CANDIDATO — un mapa de épicas y User Stories propuestas — para que el funcional lo priorice y lo valide. NO emite US ni épicas finales: extrae candidatos marcados "sin validar" y hace handoff de cada sobreviviente a grill-epic / grill-user-story (modo refinar). Es la puerta de entrada del caso "llegué con un documento y quiero sacar el backlog". Invocar como /doc-to-backlog con el path o el link del documento. Usar antes de grill-epic / grill-user-story cuando el input es un doc grande.
+---
+
+# doc-to-backlog
+
+Convierte un **documento de análisis** en un **backlog candidato** (épicas + US), para
+arrancar el trabajo funcional cuando el input no es una idea suelta sino un PDF/Word con
+todo el proyecto adentro.
+
+Llena [templates/backlog-candidato.md](templates/backlog-candidato.md) — es la única
+fuente de verdad de la forma del mapa. Nunca lo reescribas inline.
+
+## El principio que NO se negocia
+
+**El documento SIEMBRA el grilling, no lo reemplaza.** Un doc tienta a "genera 40 US de
+una" — eso es vibe coding de requerimientos: salen US que nadie validó, de features que
+quizás nadie necesita. Por eso esta skill **no publica nada final**: produce **candidatos**,
+el humano prioriza, y recién ahí cada ítem pasa por su grill ([Art. 4](../../docs/MANIFIESTO.md#art-4) y Art. 5).
+
+## Input
+
+- **El documento:** path a un PDF/Word local, o un link a Drive/SharePoint/ClickUp
+  (traelo por **MCP** si está conectado). Claude lee PDFs de forma nativa.
+- Si no viene, pedirlo.
+
+## Proceso — 3 fases
+
+### ① Extraer (la IA lee)
+
+1. Leer el documento entero.
+2. Armar el **mapa de candidatos**: las **épicas** que el doc sugiere, y bajo cada una,
+   las **US candidatas**. Cada ítem con un título corto y una línea de qué cubre.
+3. **Anotar la procedencia:** de qué sección/página del doc salió cada candidato (para
+   poder trazar de vuelta al análisis).
+4. Marcar TODO como **`sin validar`**. Es una hipótesis, no un backlog final.
+
+### ② Triage (el humano decide)
+
+5. Presentar el mapa y **frenar**: el doc es un **menú, no un mandato**. Pedir al
+   funcional que **priorice y corte** — qué entra, qué queda para después, qué se
+   descarta. No todo lo que está en el doc hay que construirlo.
+6. Para lo dudoso, sugerir pasar por `/grill-intent` (Gate 0): ¿este ítem resuelve un
+   problema real, o está en el doc "por las dudas"?
+
+### ③ Routear (cada sobreviviente a su grill)
+
+7. **No grillar todo de golpe.** Empezar por la **rebanada priorizada** (las 1–3 épicas o
+   US más importantes), no las 40 (Art. 14).
+8. Handoff, en modo **refinar** (el doc pre-llena, el grill cubre solo los huecos):
+   - épica candidata → `/grill-epic` (con el fragmento del doc como fuente)
+   - US candidata (suelta) → `/grill-user-story`
+9. Recién en ese paso se publica en el tracker, testeable y linkeable (`dai link-us`).
+
+## Dos cortes duros
+
+1. **No emitir US/épicas finales desde el doc.** Solo candidatos. Lo final sale del grill,
+   con el humano respondiendo. Si te descubres "completando" criterios que el doc no dice,
+   detente: eso lo define el funcional en el grill.
+2. **No ahogar.** Un doc de 60 páginas puede sugerir 50 ítems. Prioriza y entrega la
+   rebanada de arriba; el resto queda en el mapa candidato, listo para más tarde.
+
+## Relación con el modelo
+
+- **Es la puerta de entrada** del caso bulk. Reemplaza "idea suelta" por "doc" como fuente.
+- **Abajo:** `grill-epic` (épicas) y `grill-user-story` (US) toman cada candidato y lo
+  vuelven artefacto válido. `grill-intent` desafía el problema de los dudosos.
+- **No toca el link:** el `implements.yaml` y el `ac_hash` viven a nivel US, mucho después
+  (`dai link-us`). Esta skill solo prepara el QUÉ.

package/skills/doc-to-backlog/templates/backlog-candidato.md

@@ -0,0 +1,49 @@
+<!--
+  BACKLOG CANDIDATO · lo produce la skill doc-to-backlog
+  ─────────────────────────────────────────────────────────────────
+  Es un BORRADOR para triage, NO un backlog final. Nada de acá se publica
+  en el tracker hasta que pase por grill-epic / grill-user-story.
+  Todo arranca en estado "sin validar".
+-->
+
+# Backlog candidato — <nombre del proyecto>
+
+> **Fuente:** <documento.pdf / link de Drive> · Extraído por `doc-to-backlog`
+> **Estado:** 🟡 candidato, sin validar — pendiente de triage y grilling.
+
+## Resumen
+
+2–3 líneas de qué es el proyecto según el documento. Sin interpretar de más.
+
+## Épicas candidatas
+
+### E1 · <título de la épica>  🟡 sin validar
+- **Qué cubre:** <una línea>
+- **Procedencia:** <sección / página del doc>
+- **Prioridad:** _(la pone el funcional en el triage)_
+- **US candidatas:**
+  - [ ] <título US> — <una línea> · _proc: <ref>_
+  - [ ] <título US> — <una línea> · _proc: <ref>_
+
+### E2 · <título de la épica>  🟡 sin validar
+- **Qué cubre:** …
+- **US candidatas:** …
+
+## US sueltas candidatas (sin épica)
+
+- [ ] <título US> — <una línea> · _proc: <ref>_
+
+## Dudas para el triage
+
+Ítems que quizás NO haya que construir (candidatos a `/grill-intent` — Gate 0):
+
+- <ítem> — <por qué es dudoso / qué habría que confirmar>
+
+---
+
+<!--
+  PRÓXIMO PASO (no lo hace esta skill sola):
+  1. El funcional prioriza y corta este mapa (menú, no mandato).
+  2. La rebanada de arriba se rutea: épicas → /grill-epic, US → /grill-user-story.
+  3. Recién ahí se publica en el tracker, testeable y linkeable.
+-->

package/skills/grill-epic/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: grill-epic
+description: Interroga a un PO o analista funcional para producir una ÉPICA bien formada — un bloque grande de valor de negocio que se parte en varias User Stories — siguiendo el template del método. O toma una US que resultó demasiado grande y la promueve a épica. Se queda a nivel funcional/alcance: define el objetivo de negocio y la partición en US, NUNCA criterios de aceptación (esos viven en cada US) ni diseño técnico. Al terminar, publica la épica en Jira/ClickUp (o deja un .md) y hace handoff de cada US hija a grill-user-story. Invocar como /grill-epic, opcionalmente con un título, un ID/URL del tracker, o una US grande a promover. Usar cuando algo es demasiado grande para una sola US.
+---
+
+# grill-epic
+
+Producir una **épica** por interrogación, no por generación. Una épica es un **bloque
+grande de valor de negocio** que se parte en varias User Stories. Es el nivel de
+arriba de la US: define el **alcance**, no el detalle.
+
+Llena [templates/epica.md](../../templates/epica.md) — es la única fuente de verdad de
+la forma. Nunca reescribas el formato inline.
+
+## Qué es (y qué NO es) una épica
+
+- **Es** un contenedor: agrupa US que juntas entregan una capacidad grande.
+- **No se implementa directamente** — las US que la componen son las que viajan por el
+  flujo (`grill-user-story` → `dai link-us` → …). El link QUÉ↔CÓMO vive a nivel US.
+- **No tiene criterios de aceptación** — esos son de cada US. La épica tiene objetivo
+  de negocio, alcance y métricas de éxito.
+
+## Inputs (cualquier combinación)
+
+- **Título** — nombre corto de la épica.
+- **ID / URL del tracker** — si ya existe el ticket.
+- **Fuente:**
+  - *Desde cero* — solo una idea grande. Grillar desde 0.
+  - *Promover una US* — una US que resultó demasiado grande (viene de `grill-user-story`).
+    Leerla, y usar su contenido como material para la partición.
+
+## Dos cortes duros (no negociables)
+
+1. **Cortar en los criterios de aceptación.** Si la charla deriva a definir ACs
+   testeables, frenar: "eso es de cada US, no de la épica". La épica define *qué
+   capacidades* entran, no *cómo se verifica cada una*.
+2. **Cortar en lo técnico.** Endpoints, tablas, arquitectura → es diseño, va mucho
+   después. La épica es puro negocio de alto nivel.
+
+## Proceso
+
+1. **Resolver inputs.** Título e ID del tracker. Si se promueve una US, leerla.
+2. **Grillar, un eje por vez.** Preguntar, escuchar, profundizar. Cubrir en orden:
+   - **Objetivo de negocio** — qué resultado grande persigue, y *por qué ahora*.
+   - **Alcance** — qué entra y qué **no** entra (el límite grueso que las US respetan).
+   - **Partición en US** — el eje central: partir la épica en **User Stories
+     independientes**, cada una con valor propio y que quepa en un sprint (INVEST).
+     Nombrar cada una con un título corto. No detallar los criterios acá.
+   - **Métricas de éxito** — indicadores de negocio de la épica entera.
+   - **Dependencias y riesgos** — qué tiene que existir antes o en paralelo.
+3. **Chequeo de tamaño (al revés que en la US).**
+   - Si la "épica" **no se puede partir** en US independientes, probablemente sea **una
+     sola US grande** — devolverla a `grill-user-story`, no forzar una épica.
+   - Si una US hija sigue siendo enorme, puede ser una **sub-épica** — raro; primero
+     revisar si el corte está bien.
+4. **Emitir + publicar** (ver abajo).
+
+## Salida — publicar + handoff a las US
+
+1. **Armar la épica** con el formato de `templates/epica.md`: metadata (`ID`, autor,
+   estado, US que la componen) + objetivo + alcance (in/out) + lista de US + métricas +
+   dependencias.
+2. **Publicar en el tracker** (según `DAI_PM` del `.env`: `jira` → MCP de Atlassian ·
+   `clickup` → MCP de ClickUp · `md`/sin token → `.md` para pegar a mano). **No asumas
+   el tracker: lee `DAI_PM` primero.** Crear el ticket de épica; las US hijas se crean
+   como tickets vinculados (o quedan listadas para crearse).
+3. **Handoff.** Ofrecer pasar **cada US hija** por `/grill-user-story` para convertirla
+   de "título en la lista" a US testeable con criterios. Ese es el paso que las hace
+   linkeables (`dai link-us`).
+
+## Relación con el modelo
+
+- **Arriba:** `grill-intent` puede desafiar el *problema* de la épica antes de armarla.
+- **Abajo:** cada US de la partición pasa por `grill-user-story` → `dai link-us`.
+- El link QUÉ↔CÓMO y el `ac_hash` viven **a nivel US**, nunca de épica (la épica agrupa,
+  no se implementa).

package/skills/grill-intent/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: grill-intent
+description: Gate 0 of the SDD workflow — challenge the *problem* behind a clean user story before any spec is generated. Interrogates whether this is the right problem, for the right user, within constraints, and whether the story's implied solution is a premature jump. Produces intent.md and a verdict that can be "go to spec", "reframe", or "don't build". In the spirit of grill-me, specialized for problem-challenge. Invoke as /grill-intent on a user story (the output of grill-user-story). Use after grill-user-story and before openspec propose.
+---
+
+# grill-intent — Gate 0, challenge the problem
+
+The highest-ROI gate in the cycle: catch the wrong feature *before* a single spec artifact is written. This challenges the problem behind a user story — it does not construct the story (`grill-user-story` did that) and does not design the solution (`openspec propose` / `design.md` does that).
+
+A valid outcome is "don't build this" or "the real problem is different". That is the point of Gate 0, not a failure of it.
+
+Fill [templates/intent.md](templates/intent.md). That template is the single source of truth for the shape — never restate it inline.
+
+## Input
+
+- The clean user story (output of `grill-user-story`).
+- The constitution: `openspec/project.md`, `CLAUDE.md`, and the team's AI-native manifesto — the immutable constraints the problem must live within.
+
+## The challenge (five axes)
+
+Pull *up* from the story's "I want Y" to the problem underneath, and pressure-test it:
+
+1. **Right problem** — what actually hurts today, in the user's terms? Is the story solving that, or a symptom?
+2. **Right user** — who genuinely has this pain? Reject a generic actor; name the one who feels it.
+3. **Why now / cost of inaction** — what happens if we don't do this? If "nothing much", that's a signal to stop.
+4. **Constraints** — does the problem collide with anything in the constitution (security, stack, roles, performance, branding, hard limits)?
+5. **Solution-lock** — the story says "I want Y". Is Y a premature jump? Is there a cheaper or different way to solve the *same* problem? Could we solve it by *not building*?
+
+## Two hard cuts (non-negotiable)
+
+1. **Cut on solutioning.** If the conversation slides into how to build it, or even into shaping the feature's behaviour, stop it: "we're testing the problem, not designing the solution." Design is later.
+2. **Cut on rubber-stamping.** Do not emit the intent until the problem has actually survived a challenge — at minimum axes 1, 3 and 5 answered with something real. Approving the story's implicit problem unexamined is the exact failure this gate exists to prevent.
+
+## Process
+
+1. **Read** the user story and the constitution.
+2. **Challenge, one axis at a time.** grill-me discipline: ask, listen, push, move on. Don't dump the five questions at once.
+3. **Reach a verdict** — `a-spec` (problem survived, go to propose), `reframe` (the real problem is different, back to `grill-user-story`), or `descartar` (not worth solving now, stop and record why).
+4. **Emit** the filled `intent.md` (default location `openspec/intents/<YYYYMMDD-slug>/intent.md`; adjust to where the manifesto puts intents). Embed the tracker ID (the issue/task key — Jira or ClickUp, per `DAI_PM` in the repo's `.env`) and the source story.
+
+## Hand-off
+
+If the verdict is `a-spec`, the validated `intent.md` plus the user story together are the description you hand to `/openspec:proposal` — propose explores the specs and codebase itself and generates `proposal.md`, `design.md`, `tasks.md` and the `specs/` deltas. If `reframe`, return to the story. If `descartar`, stop — that is the gate doing its highest-value work.

package/skills/grill-intent/templates/intent.md

@@ -0,0 +1,36 @@
+<!-- Plantilla canónica de intent (Gate 0). Define y DESAFÍA el problema, antes de la solución.
+     La llena grill-intent. No describe el cómo ni la solución — eso es openspec propose / design.md. -->
+
+# Intent: <slug del problema>
+
+> US de origen: <link o título>  ·  ClickUp: <id>  ·  Veredicto: pendiente | a-spec | reframe | descartar
+
+## Problema
+
+<Qué duele hoy, en términos del usuario. No la solución. Un párrafo.>
+
+## Usuario / actor
+
+<Quién tiene realmente este problema. Concreto, nunca "el usuario".>
+
+## Por qué ahora / costo de no hacerlo
+
+<Qué pasa si no lo resolvemos. Si la respuesta honesta es "nada grave", eso es una señal.>
+
+## Restricciones
+
+<Lo que la constitution / el contexto impone: seguridad, stack, performance, roles, branding, límites absolutos.>
+
+## No-goals
+
+<Lo que este intent explícitamente NO abarca. Corta el scope creep desde la raíz.>
+
+## Alternativas consideradas
+
+<Otras formas de resolver el MISMO problema — incluidas "no hacer nada" y "una solución más barata". Por qué la dirección elegida.>
+
+## Veredicto
+
+<a-spec: el problema sobrevivió el desafío → pasa a openspec propose.
+ reframe: el problema real es otro → volver a grill-user-story.
+ descartar: no vale la pena resolverlo ahora → motivo.>

package/skills/grill-user-story/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: grill-user-story
+description: Interroga a un PO o analista funcional para producir una User Story funcional y testeable siguiendo el formato del modelo de trazabilidad — o pule una US vaga existente. Se queda a nivel funcional/usuario y se niega a derivar en diseño técnico o a emitir una US con criterios no testeables. Al terminar, PUBLICA la US en el tracker configurado del repo (Jira o ClickUp, según DAI_PM del .env) usando su MCP; si no hay MCP/token, deja un .md con el mismo formato para copiar y pegar. Invocar como /grill-user-story, opcionalmente con un título, un ID/URL del tracker, y/o una US rústica existente. Usar antes de opsx:propose, o cuando alguien dice "necesito una US", "convierte esto en una US como corresponde", o "esta historia está muy vaga".
+---
+
+# grill-user-story
+
+Producir una buena User Story **por interrogación, no por generación**. Es la puerta de entrada funcional del pipeline de specs (el QUÉ): su salida alimenta `opsx:propose` del lado técnico. Trabaja **solo a nivel usuario/solución** — el grill técnico ocurre después, en el `design.md` del dev.
+
+Llena [templates/user-story.md](templates/user-story.md). El formato completo y su racional viven en [../../templates/formato-us.md](../../templates/formato-us.md) — es la única fuente de verdad de la forma. Nunca reescribas el formato inline.
+
+## Por qué el formato importa (modelo de trazabilidad)
+
+Esta US es el **QUÉ linkeable**. El `implements.yaml` del repo la va a referenciar por su **ID del tracker**, y `dai stamp` la usa para estampar cobertura. Por eso la salida DEBE tener:
+- **ID** = el ticket del tracker (`ABC-###` en Jira, `86xxxx` en ClickUp) — identidad estable.
+- **spec_version** = `v1` al nacer.
+- **Criterios de aceptación en Gherkin** — es el bloque que se hashea (`ac_hash`); tienen que ser estables y testeables.
+- **Autor** = quién la definió.
+
+## Inputs (cualquier combinación, por argumento o preguntando)
+
+- **Título** — nombre corto de la historia.
+- **ID / URL de Jira** — si ya existe el ticket, para preservar el seam con el PM.
+- **Fuente**:
+  - *Desde cero* — solo un título o idea. Grillar desde 0.
+  - *Refinar existente* — una US vaga ya escrita (texto pegado o path de archivo). Leerla primero, diagnosticar qué falta contra el formato, y grillar solo los huecos — no re-preguntar lo que ya está claro.
+
+Si no viene nada, pedir título y si hay un borrador existente.
+
+## Tres cortes duros (no negociables)
+
+1. **Cortar en lo técnico.** Si la charla deriva a tablas, endpoints, migraciones o elección de framework, frenar: "eso es diseño, no ahora". La US nombra *qué necesita el usuario*, nunca *cómo se construye*.
+2. **Cortar en lo no testeable.** Nunca emitir un criterio que no pueda volverse un test. "El usuario tiene una buena experiencia" se rechaza. "Un carrito vacío no se puede finalizar" se acepta — funcional y verificable. Empujar cada AC hasta que sea observable.
+3. **Publicar, no pedir.** Si el tracker está configurado (`DAI_PM=jira|clickup` con token en `.env`), **CREA el ticket tú** (por MCP o con `dai publish`). **Nunca** cierres pidiéndole al usuario que te "pase el ID/URL del ticket" como si ya existiera — el ticket lo creas tú en este paso. Solo pides un ID existente si el usuario dijo explícitamente que está refinando una US ya creada.
+
+## Proceso
+
+0. **Detectar el tracker (SIEMPRE, antes de nada).** Lee el archivo `.env` del repo y observa `DAI_PM`:
+   - `DAI_PM=jira` → publicas en **Jira** (base: `DAI_JIRA_BASE_URL`), vía el MCP de Atlassian/Jira.
+   - `DAI_PM=clickup` → publicas en **ClickUp**, vía el MCP de ClickUp.
+   - `DAI_PM=md` (o sin `.env`) → no hay tracker: dejas la US como `.md`.
+   **No asumas el tracker** — depende del `.env`. Si no hay `.env`, pregunta cuál usa el equipo.
+1. **Resolver inputs.** Obtener título e ID del tracker (si existe). Si se refina, leer la US y anotar — para uno mismo — qué secciones del formato faltan o están flojas: rol genérico ("el usuario"), falta el "para", sin flujo de excepción, solución prefijada, ACs vagos.
+2. **Grillar, un eje por vez.** No tirar un cuestionario — preguntar, escuchar, profundizar, y seguir. Cubrir en orden:
+   - **Título** — corto, **3 a 6 palabras**, nombra la capacidad (de ahí sale la branch). Si el título es una frase larga, acórtalo: el detalle va en la descripción, no en el título. Ej: "Confirmar acciones con consecuencias", no "Confirmación deliberada antes de ejecutar acciones con consecuencias".
+   - **Quién** — el usuario/rol real. Rechazar "el usuario"; conseguir el actor concreto.
+   - **Job-to-be-done** — qué intenta lograr de verdad, y el *por qué* (el "para").
+   - **Flujos** — happy path primero, después alternativos, después excepciones: "¿qué pasa cuando no es válido / no está permitido / está vacío?"
+   - **Criterios de aceptación** — convertir cada flujo en una condición funcional y testeable, en Gherkin. Aplicar el corte #2 acá, fuerte.
+   - **Fuera de scope** — qué NO hace esta historia (mata el scope creep más adelante).
+3. **Chequeo de tamaño (INVEST).** Si los flujos y ACs desbordan y la historia se dispersa, es demasiado grande para una sola US. No seguir empujando: **promoverla a una épica** con `/grill-epic` (que la parte en varias US independientes) y después volver acá para grillar cada US hija. Una US que no entra en un sprint es la señal de que hay una épica adentro.
+4. **Publicar la US en el tracker (PASO OBLIGATORIO, ver abajo).** No termines con "¿la guardo y/o disparo el siguiente paso?": el trabajo de esta skill **incluye dejar la US publicada** en el tracker (con su key), no solo redactarla.
+
+## Salida — publicar en el tracker (según `DAI_PM`), con fallback a .md
+
+La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo que cambia es **dónde se publica** — lo definió el paso 0:
+
+1. **Armar la US** completa: metadata de trazabilidad (`ID`, `spec_version: v1`, autor, repos esperados) + historia + contexto + casos de uso + criterios Gherkin + fuera de scope + reglas + dependencias + métricas.
+2. **Publicar en el tracker que dice `DAI_PM`:**
+   - **Jira** (`DAI_PM=jira`): vía el MCP de Atlassian, crear/actualizar el issue en `DAI_JIRA_BASE_URL` — título (summary), descripción, y los **criterios bajo un heading `## Criterios de aceptación`** (es lo que `dai` hashea). El issue devuelve el key (`ABC-###`).
+   - **ClickUp** (`DAI_PM=clickup`): vía el MCP de ClickUp, crear/actualizar la tarea con los criterios en la descripción, bajo el mismo heading. Devuelve el task ID.
+   - Confirmar al usuario con el link al ticket publicado.
+   - **Importante:** los criterios SIEMPRE van bajo `## Criterios de aceptación` en la descripción — así `dai link-us`/`check` los encuentran, sin importar el tracker.
+3. **Fallback SIN MCP → publicar con el CLI (`dai publish`):**
+   - Si NO hay MCP del tracker conectado (pero sí `DAI_PM=jira|clickup` + token en `.env`):
+     escribe la US como `.md` (formato `formato-us.md`) y publícala con el comando:
+     **`dai publish <ruta-del-md>`** → crea el issue/tarea vía REST y devuelve el key.
+     (Jira necesita además `DAI_JIRA_PROJECT` en el `.env`.)
+   - Si tampoco hay token (o `DAI_PM=md`): deja solo el `.md` para que la persona lo
+     pegue a mano en el tracker. Avisa el motivo.
+   - El contenido es **idéntico** en los tres caminos (MCP / `dai publish` / manual).
+4. **Estado.** Dejar la US en `pulida`. Ofrecer que el dev siga con `dai link-us <ID>` → `opsx:propose` (lado técnico).
+
+## Hand-off
+
+La US terminada es el input de `opsx:propose`, que produce las capas técnicas (`design.md`, `specs/`, `tasks.md`) y donde el dev declara el link con la skill `link-us`. El grill técnico —modelo de datos, roles, migraciones— ocurre ahí, con un dev o arquitecto, no acá.

package/skills/grill-user-story/templates/user-story.md

@@ -0,0 +1,61 @@
+<!-- Plantilla canónica de historia de usuario · Modelo de Trazabilidad QUÉ↔CÓMO.
+     Funcional y de alto nivel: sin tecnología. La llena la skill grill-user-story.
+     Formato completo y su racional en ../../formato-us.md (fuente de verdad de la forma). -->
+
+# 🔗 Metadata de trazabilidad
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | `ABC-###` |
+| **spec_version** | `v1` |
+| **Autor** | `<PO / analista>` |
+| **Estado** | `borrador` |
+| **Repos esperados** | `<frontend, bff, backend — opcional>` |
+
+# <título de la historia>
+
+## Historia
+
+Como <rol / tipo de usuario concreto, nunca "el usuario">
+quiero <capacidad o resultado>
+para <valor / por qué>.
+
+## Contexto / Problema
+
+Por qué esto importa ahora. Qué duele hoy sin esta funcionalidad.
+
+## Casos de uso
+
+Flujos a nivel usuario — qué hace la persona y qué responde el sistema. Sin tecnología.
+
+- **Happy path** — <el usuario hace X, obtiene Y>
+- **Alternativo** — <variación esperada del flujo>
+- **Excepción** — <qué pasa cuando algo no es válido, no está permitido, o está vacío>
+
+## Criterios de aceptación
+
+Gherkin (Dado / Cuando / Entonces). Cada uno tiene que poder convertirse en un test.
+Este bloque es lo que se hashea (ac_hash) — orden estable, sin tecnología.
+
+- [ ] **AC-1** — Dado <precondición>, cuando <acción>, entonces <resultado observable>
+- [ ] **AC-2** — Dado <...>, cuando <...>, entonces <...>
+
+## Reglas de negocio
+
+- <invariante / límite / restricción de dominio>
+
+## Fuera de scope
+
+- <lo que esta historia explícitamente NO hace>
+
+## Dependencias
+
+- <ABC-### / sistema / decisión previa>
+
+## Métricas de éxito
+
+- <indicador de negocio observable>
+
+## Preguntas abiertas
+
+- <lo que necesita una decisión antes de implementar>

package/skills/link-us/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: link-us
+description: Del lado del dev — crea la branch desde el link de la User Story en Jira SIN margen de error y genera el archivo implements.yaml con el link a la US (id + version + ac_hash). Es la que hace que el link QUÉ↔CÓMO sea correcto por construcción, sin que el dev tipee el key a mano. Invocar como /link-us ABC-### (o con la URL del ticket de Jira). Usar al arrancar la implementación de una US, antes o junto con opsx:explore / opsx:propose.
+---
+
+# link-us
+
+Arranca la implementación de una User Story **atándola al QUÉ desde el primer commit**. El dev no escribe el key de Jira a mano en ningún lado: la branch y el `implements.yaml` salen los dos del mismo ID, así el link no puede quedar mal tipeado.
+
+Es la contraparte técnica de `grill-user-story`: donde esa produce el QUÉ (en Jira), esta abre el CÓMO (en el repo) ya linkeado.
+
+## Input
+
+- **ID o URL de la US en Jira** — `ABC-###` o el link completo. Es lo único obligatorio.
+- Si no viene, pedirlo. Validar el formato del key antes de seguir; si no matchea `ABC-\d+`, frenar y avisar.
+
+## Proceso
+
+1. **Resolver el key.** Extraer `ABC-###` del argumento (acepta key crudo o URL). Este key es la **única fuente** de todo lo que sigue — no re-tipearlo.
+2. **Traer la US (si se puede).**
+   - Si hay **MCP de Jira/Atlassian** o **token** (`JIRA_BASE_URL` + `JIRA_TOKEN`): traer título, `spec_version` y el bloque de **criterios de aceptación**.
+   - Calcular `ac_hash` = hash del bloque de criterios normalizado (whitespace colapsado, orden estable).
+   - Si no hay acceso a Jira: pedir al dev el título y la `spec_version`, o leer un `.md` local de la US; dejar `ac_hash` como `pendiente` con un aviso de que el CI lo completará.
+3. **Crear la branch, sin margen de error.**
+   - Nombre: `feature/ABC-###-<slug>` donde `<slug>` sale del título (minúsculas, sin acentos, `-` como separador).
+   - Base según convención del repo (`main` o `develop`). Verificar que la branch no exista ya.
+   - No permitir crear la branch si el key no fue validado en el paso 1.
+4. **Generar el link.** Crear `openspec/changes/<change-id>/implements.yaml` a partir de [templates/implements.yaml](templates/implements.yaml), completando `id`, `version`, `ac_hash`, `repo` y `autor`. Dejar `introduces` para que el dev liste las capacidades técnicas nuevas.
+5. **Hand-off.** Ofrecer seguir con `opsx:explore` → `opsx:propose` para armar el change (proposal/design/tasks) sobre la branch ya creada y linkeada.
+
+## Guardrails (por qué esta skill existe)
+
+- **El key nunca se tipea a mano** en la branch ni en el `implements.yaml`: ambos derivan del argumento validado. Elimina el error de tipeo que rompe la trazabilidad.
+- **Sin `implements.yaml`, no hay link** — y el CI del repo falla el PR si falta. Esta skill garantiza que exista desde el arranque.
+- **El link apunta del CÓMO al QUÉ** (`implements: ABC-###`), nunca al revés. La cobertura inversa la genera el CI, no esta skill.
+
+## Relación con el modelo
+
+- `grill-user-story` → produce el QUÉ en Jira (`ABC-###`).
+- **`link-us`** → abre el CÓMO en el repo, ya atado a ese `ABC-###`.
+- El CI → al mergear, estampa en Jira "implementado por &lt;repo&gt; @&lt;version&gt; ✓".
+- El CD → al desplegar, reporta en qué ambiente (dev/test/pre/prod) quedó viva esa versión.

package/skills/link-us/templates/implements.yaml

@@ -0,0 +1,16 @@
+# Link QUÉ↔CÓMO · lo genera link-us / `dai link-us`, lo versiona git junto al código.
+# Es el ÚNICO link autorado a mano. La cobertura inversa la deriva `dai stamp`.
+# Schema: docs/adr/0004-ubicacion-y-schema-implements.md
+
+change: <change-id>              # ← identidad del CÓMO (nombre local del change/spec). Auto-contenido.
+repo:   <nombre-del-repo>        # ← p. ej. frontend
+
+implements:                      # FORWARD: qué QUÉ del negocio cumple este change
+  - id: ABC-###                 # ← ticket de Jira/ClickUp (identidad del QUÉ). NO tipear a mano: lo pone link-us.
+    version: v1                  # ← spec_version de la US al momento de implementar (nº legible)
+    ac_hash: <autogenerado>      # ← lo calcula `dai ac-hash`. Dispara el ⚠️ si el QUÉ cambia.
+
+introduces:                      # capacidades TÉCNICAS nuevas que agrega este change (opcional)
+  - <capacidad-tecnica>          #   p. ej. guard-carrito-vacio
+
+autor: <dev>                     # quién implementa