@dforce2055/dai 0.7.0 → 0.8.1

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

@@ -1,6 +1,6 @@
 ---
 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".
+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
@@ -65,11 +65,24 @@ La US se produce UNA vez con el formato de `../../templates/formato-us.md`. Lo q
    - 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`.)
+     (Jira necesita además `DAI_JIRA_PROJECT` en el `.env` — la clave del **proyecto**,
+     `PROJ`, no la de un ticket.)
+   - **Si la US pertenece a una épica:** `dai publish <us.md> --parent <KEY-de-la-épica>`.
+   - **Si el proyecto exige campos propios** (típico en Jira corporativo): van con
+     `--field alias=valor`, repetible. Los alias son los de `.dai/jira-fields.json`, y
+     `dai doctor` te dice cuáles hay. Si el valor cambia según la US (p. ej. una
+     clasificación Mejora/Corrección), **pregúntaselo a la persona** durante el
+     interrogatorio — no lo elijas tú, es una decisión de negocio.
+     Ej.: `dai publish us.md --parent PROJ-42 --field clasificacion=Corrección`
    - 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).
+4. **Si `dai publish` falla, para y reporta el error tal cual.** No improvises una llamada
+   a la API del tracker por fuera, ni bajes la verificación TLS para pasar un proxy: el
+   atajo publica igual, pero el `## Criterios de aceptación` puede quedar mal formado y
+   **el link QUÉ↔CÓMO se rompe en silencio**. Si el error nombra un campo obligatorio que
+   falta, decláralo en `.dai/jira-fields.json` (molde en `.dai/templates/`) y reintenta.
+5. **Estado.** Dejar la US en `pulida`. Ofrecer que el dev siga con `dai link-us <ID>` → `opsx:propose` (lado técnico).
 
 ## Hand-off
 

package/skills/link-us/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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

package/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+description: "Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions \"red-green-refactor\", wants integration tests, or asks for test-first development."
 ---
 
 # Test-Driven Development

package/templates/jira-fields.example.json

@@ -0,0 +1,49 @@
+{
+  "_comentario": [
+    "Molde de .dai/jira-fields.json — los campos PROPIOS que tu Jira exige al crear un issue.",
+    "Copialo a .dai/jira-fields.json y ajustalo. Si tu Jira no exige campos propios, no lo",
+    "necesitás: sin archivo, dai publica igual que siempre (ADR-0015).",
+    "",
+    "Se declara por issuetype porque los campos obligatorios de una Story y de una Epic casi",
+    "nunca son los mismos. Un campo declarado TIENE que resolver a un valor (por 'default' o",
+    "por --field): se declara porque Jira lo exige. Si es opcional, no lo declares.",
+    "",
+    "  field    el id de Jira (requerido). Lo ves en la URL al editar el campo, o te lo dice",
+    "           el error 400 de Jira cuando falta.",
+    "  shape    cómo se envuelve el valor para la API:",
+    "             select → {\"value\": X}      un desplegable (el caso típico)",
+    "             text   → X                 texto plano",
+    "             multi  → [{\"value\": X}]    lista (el valor se parte por comas)",
+    "             raw    → JSON tal cual     escape hatch para cualquier forma rara",
+    "           Si lo omitís: con 'options' es select; sin 'options', text.",
+    "  default  el valor si no pasás --field. Omitilo cuando el valor cambia SIEMPRE según",
+    "           la US: así dai te lo pide en vez de inventar uno.",
+    "  options  los valores válidos. dai los valida ANTES de llamar a Jira: un typo da un",
+    "           error local con la lista, no un 400 críptico.",
+    "",
+    "Uso:",
+    "  dai publish us.md                                 (usa los defaults)",
+    "  dai publish us.md --field clasificacion=Corrección",
+    "  dai publish us.md --parent PROJ-42            (la cuelga de su épica)",
+    "  dai publish epica.md --issuetype Epic --field clasificacion=Mejora",
+    "",
+    "Verificá que parsee con:  dai doctor"
+  ],
+
+  "Story": {
+    "clasificacion": {
+      "field": "customfield_10042",
+      "shape": "select",
+      "default": "Mejora",
+      "options": ["Mejora", "Corrección"]
+    }
+  },
+
+  "Epic": {
+    "clasificacion": {
+      "field": "customfield_10042",
+      "shape": "select",
+      "options": ["Mejora", "Corrección"]
+    }
+  }
+}

package/templates/skill.md

@@ -1,9 +1,9 @@
 <!--
   MOLDE DE SKILL · dai
   ─────────────────────────────────────────────────────────────────
-  Formato: Agent Skills de Claude (SKILL.md). dai lo INGIERE y lo convierte a los 3
-  asistentes (Claude copia · Cursor `skillToCursor` · Copilot `.prompt.md`), con
-  `dai skills install --from <repo|path>` (ADR-0013).
+  Formato: Agent Skills (SKILL.md) — un estándar abierto que leen Claude, Copilot y
+  Cursor. dai lo INGIERE y lo distribuye a los 3 (Claude y Copilot copia cruda · Cursor
+  `skillToCursor`), con `dai skills install --from <repo|path>` (ADR-0013 · ADR-0014).
 
   Estructura del repo/dir fuente:
       skills/
@@ -15,13 +15,17 @@
     - frontmatter con `name` y `description` (ambos obligatorios, en una línea).
     - `name`: slug en kebab-case, IGUAL al nombre del directorio.
     - `description`: una frase — con esto el agente decide CUÁNDO usar la skill.
+    - ambos, YAML VÁLIDO. Ojo: los asistentes parsean el frontmatter con YAML de
+      verdad, y un `: ` (dos puntos + espacio) suelto en la descripción hace que YAML
+      la lea como un mapa y DESCARTE LA SKILL ENTERA. Por eso la descripción va
+      SIEMPRE entre comillas dobles: te deja escribir la frase que quieras.
 
   dai NO valida el CONTENIDO (qué dice la skill, qué hacen sus scripts): eso es
   criterio del equipo. Las instalás bajo tu propio riesgo.
 -->
 ---
 name: mi-skill
-description: Qué hace la skill y cuándo conviene invocarla — concreto y orientado al disparador.
+description: "Qué hace la skill y cuándo conviene invocarla: concreto y orientado al disparador. Las comillas dobles no son decorativas — sin ellas, un ': ' rompe el YAML."
 ---
 
 # <Título de la skill>