@tacuchi/agent-workflow-cli 12.4.0 → 12.6.0

package/skills/w/roles/testing/SKILL.md

@@ -28,10 +28,10 @@ Dar a los loops la capacidad de razonar sobre tests: qué nivel aplicar, con qu
 
 ### Execution rule
 
-Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner:
+Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner, preguntar al humano vía *structured-choice* (capacidad del arnés — ver `../../harness/SKILL.md`). En **Claude Code** es `AskUserQuestion` (máx 4 preguntas/llamada → **≤3 preguntas de contenido + 1 control `flow`**); en un arnés sin elección estructurada, degrada a **markdown numerado**.
 
 ```
-AskUserQuestion:
+structured-choice:
   "¿Correr los tests?"
   [a] Sí, el loop los ejecuta
   [b] Los corro yo manualmente

package/skills/w/roles/ui-spec/SKILL.md

@@ -2,12 +2,12 @@
 name: ui-spec
 description: >-
   UI spec authoring — built-in default for the `ui-design` capability. Given a UI
-  requirement, author a structured, framework-agnostic screen specification (the
-  universal `Screen` model in JSON) plus its readable Markdown render. Knows the
-  `Screen` schema, the kind/region vocabulary, the authoring rules, design-system /
-  theme / variant handling, and the exact Markdown render format. Use when a loop is
-  refining a spec that involves screens, forms, dashboards, modals or any UI surface
-  — primarily `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
+  requirement, author a structured, framework-agnostic screen specification as
+  **Markdown** (single output format). Knows the conceptual screen structure, the
+  kind/region vocabulary, the authoring rules, design-system / theme / variant
+  handling, and the exact Markdown render format. Use when a loop is refining a spec
+  that involves screens, forms, dashboards, modals or any UI surface — primarily
+  `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
 ---
 
 # ui-spec — UI spec authoring
@@ -18,37 +18,31 @@ description: >-
 
 ## Purpose
 
-Dado un requerimiento de UI, autorar una **especificación de pantalla estructurada** — un modelo universal, agnóstico de framework — más su render Markdown legible. **Reemplaza** al servicio single-shot `ui-spec-generator`: ahora la IA la autora **nativamente**, guiada por esta skill. No hay endpoint que llamar; el saber del servicio vive aquí.
+Dado un requerimiento de UI, autorar una **descripción estructurada en Markdown** de las pantallas y sus componentes — descriptiva (qué hay y para qué) y estructurada (regiones → componentes, con vocabulario consistente), agnóstica de framework. **Reemplaza** al servicio single-shot `ui-spec-generator`: ahora la IA la autora **nativamente**, guiada por esta skill. No hay endpoint que llamar; el saber del servicio vive aquí. **Salida en un solo formato: Markdown** (sin representación JSON paralela).
 
 ## Composed by
 
-La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop.md`) cuando el requerimiento involucra UI. El loop aporta lo que el servicio viejo no tenía:
+La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop/SKILL.md`) al resolver el gap **UI sin especificar** (cuando el requerimiento involucra UI). El loop aporta lo que el servicio viejo no tenía:
 
-- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía `AskUserQuestion`.
+- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía *structured-choice* (capacidad del arnés — ver `../../harness/SKILL.md`). En **Claude Code** es `AskUserQuestion` (máx 4 preguntas/llamada → **≤3 preguntas de contenido + 1 control `flow`**); en un arnés sin elección estructurada, degrada a **markdown numerado**.
 - **Itera** gap-driven hasta converger.
 - Ofrece **variantes** y **cura** el resultado.
 
-Cualquier loop podría componerla; el caso primario es SPEC. El `Screen` y su Markdown aterrizan como una sección dentro del documento spec (`docs/specs/NNN-spec.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
+Cualquier loop podría componerla; el caso primario es SPEC. La descripción Markdown aterriza como una sección dentro del documento spec (`docs/specs/NNN-spec-<slug>.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
 
 ## Knowledge
 
-### Schema (modelo `Screen` — universal, recursivo)
+### Estructura conceptual (universal, recursiva)
 
-```
-Screen {
-  name: string             # nombre de la pantalla
-  purpose: string          # "tipo" semántico: auth, dashboard, form, list, detail, error, ...
-  platform: string         # web (default), mobile, ...
-  description?: string
-  regions?:   Region[]     # pantallas complejas
-  components?: Component[]  # pantallas simples
-}                          # usar regions O components, no ambos
-Region    { type: string, components: Component[] }
-Component { kind: string, role?: string, label?: string, children?: Component[] }  # recursive
-```
+Una **pantalla** tiene: `nombre`, `tipo` (propósito semántico: auth, dashboard, form, list, detail, error, …), `plataforma` (web por default, mobile, …), `descripción` opcional, y **o bien regiones** (pantalla compleja) **o bien componentes** directos (pantalla simple) — **no ambos**.
+
+- Una **región** agrupa componentes y tiene un `type`.
+- Un **componente** tiene un `kind`, y opcionalmente `role`, `label` y `children` (anidables, recursivos).
 
-- `type` (region) ∈ `header · main · footer · sidebar · filters · summary`
-- `kind` (component) por categoría:
+Es un modelo conceptual para guiar la autoría; **no se serializa a JSON** — la única salida es el render Markdown (ver Output).
+
+- `type` (región) ∈ `header · main · footer · sidebar · filters · summary`
+- `kind` (componente) por categoría:
   - **Contenedores**: `card · panel · modal`
   - **Datos**: `table · list · grid`
   - **Visualización**: `chart · metric · badge · image`
@@ -57,8 +51,6 @@ Component { kind: string, role?: string, label?: string, children?: Component[]
   - **Navegación**: `navBar · tabs · breadcrumb`
   - **Feedback**: `alert · progress`
 
-JSON serializado en **camelCase**, **claves null omitidas** (no emitir `"description": null`).
-
 ### Rules
 
 1. **Conciso** — solo lo esencial. Nada de relleno ni componentes especulativos.
@@ -66,11 +58,11 @@ JSON serializado en **camelCase**, **claves null omitidas** (no emitir `"descrip
 3. Pantalla compleja (dashboard, mantenimiento CRUD) → `regions` para organizar.
 4. `role` es **opcional** — solo si aporta claridad (`role:"logo"`, `role:"primary"`).
 5. Límites: **≤100 componentes**, **≤5 niveles** de anidación.
-6. Un solo `Screen` por sección; si el requerimiento son varias pantallas, una sección por pantalla.
+6. Una sola pantalla por bloque `#`; si el requerimiento son varias pantallas, se listan una tras otra (cada una con su `#`).
 
 ### Design options (las pregunta el loop al humano)
 
-Estas opciones **guían contenido/labels**; el modelo `Screen` es **agnóstico** de design-system y NO las lleva como campos. Se **anotan en el spec** (encabezado de la sección), no en el JSON:
+Estas opciones **guían contenido/labels**; la estructura de la pantalla es **agnóstica** de design-system y NO las lleva como parte del modelo. Se **anotan en el spec** (encabezado de la sección):
 
 - **Design system**: `material3 · bootstrap5 · tailwind3 · antDesign · chakraUI · custom`.
 - **Tema**: `light · dark · auto`.
@@ -80,11 +72,11 @@ Estas opciones **guían contenido/labels**; el modelo `Screen` es **agnóstico**
 
 ### Variants
 
-Cuando el requerimiento admite más de un layout razonable (ej. tabla vs. grid de cards; tabs vs. acordeón), ofrecer **2-3 variantes** como `Screen` alternativos y pedir al humano que elija. Una sola variante se cura y queda; las descartadas no se persisten.
+Cuando el requerimiento admite más de un layout razonable (ej. tabla vs. grid de cards; tabs vs. acordeón), ofrecer **2-3 variantes** como pantallas Markdown alternativas y pedir al humano que elija. Una sola variante se cura y queda; las descartadas no se persisten.
 
 ### Disambiguation
 
-Antes de autorar, resolver ambigüedades con `AskUserQuestion` (lo dispara el loop):
+Antes de autorar, resolver ambigüedades con *structured-choice* (lo dispara el loop; ver `../../harness/SKILL.md`):
 
 - Pantalla simple o compleja (¿necesita `regions`?).
 - Qué acciones primarias/secundarias existen.
@@ -95,27 +87,45 @@ Si el humano no responde, asumir el caso más simple coherente con la descripci
 
 ### Examples (few-shot)
 
-```json
-// Simple (sin regions)
-{"name":"Recuperar Contraseña","purpose":"auth","platform":"web","components":[{"kind":"image","role":"logo"},{"kind":"textInput","label":"Correo electrónico"},{"kind":"button","label":"Enviar enlace"},{"kind":"link","label":"Volver al login"}]}
+**Simple (sin regiones)** — "Recuperar Contraseña" (auth, web):
 
-// Complejo (con regions)
-{"name":"Dashboard","purpose":"dashboard","platform":"web","regions":[{"type":"summary","components":[{"kind":"metric","label":"Total"},{"kind":"metric","label":"Pendientes"}]},{"type":"main","components":[{"kind":"table","label":"Registros"}]}]}
+```markdown
+# Recuperar Contraseña
+**Tipo**: auth | **Plataforma**: web
+
+## Componentes
+- **logo** (image)
+- **Correo electrónico** (textInput)
+- **Enviar enlace** (button)
+- **Volver al login** (link)
+```
+
+**Complejo (con regiones)** — "Dashboard" (web):
+
+```markdown
+# Dashboard
+**Tipo**: dashboard | **Plataforma**: web
+
+## Summary
+- **Total** (metric)
+- **Pendientes** (metric)
+
+## Main
+- **Registros** (table)
 ```
 
-## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec.md`)
+## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec-<slug>.md`)
 
-La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego dos representaciones:
+**Salida en un solo formato: Markdown.** La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego el render Markdown, con estas reglas exactas (recicladas del `MarkdownFormatter`):
 
-1. **`Screen` (JSON)** — camelCase, claves null omitidas, en bloque ```json.
-2. **Markdown** — render legible (reglas exactas, recicladas del `MarkdownFormatter`):
-   - `# {name}`
-   - `**Tipo**: {purpose} | **Plataforma**: {platform}`
-   - `description` como párrafo aparte (solo si existe).
-   - Con `regions`: un `## {Type capitalizado}` por región (capitalizar la primera letra del `type`).
-   - Sin `regions`: un `## Componentes`.
-   - Cada componente: `- **{label || role || kind}**`, seguido de ` ({kind})` **solo si** había `label` o `role`.
-   - `children` indentados **2 espacios por nivel**.
+- `# {nombre}`
+- `**Tipo**: {tipo} | **Plataforma**: {plataforma}`
+- `descripción` como párrafo aparte (solo si existe).
+- Con regiones: un `## {Type capitalizado}` por región (capitalizar la primera letra del `type`).
+- Sin regiones: un único `## Componentes`.
+- Cada componente: `- **{label || role || kind}**`, seguido de ` ({kind})` **solo si** había `label` o `role`.
+- `children` indentados **2 espacios por nivel**.
+- Si hay varias pantallas, se listan una tras otra (cada una con su `#`).
 
 Ejemplo de render para el dashboard de arriba:
 
@@ -133,4 +143,4 @@ Ejemplo de render para el dashboard de arriba:
 
 ## Source
 
-Reciclada de `ui-spec-generator` (Spring Boot/Kotlin). Se **conservan**: el prompt de sistema (vocabulario, kinds, reglas), el esquema `Screen`/`Region`/`Component`, los pocos-shot, el enum de design systems, los constraints (theme/density/maxWidth) y las reglas exactas del `MarkdownFormatter`. Se **descarta**: el transporte HTTP, OpenRouter/Gemini y el modo single-shot — los reemplaza la iteración del `spec-refine-loop`. El endpoint del servicio deja de usarse. También absorbe los principios UX de la vieja skill `standards/frontend-design/` cuando el spec describe mantenimientos CRUD (formularios, listados, modales, navegación, feedback).
+Reciclada de `ui-spec-generator` (Spring Boot/Kotlin). Se **conservan**: el prompt de sistema (vocabulario, kinds, reglas), la estructura conceptual pantalla/región/componente, los pocos-shot (ahora en Markdown), el enum de design systems, los constraints (theme/density/maxWidth) y las reglas exactas del `MarkdownFormatter` (su render era exactamente este). Se **descarta**: la **serialización JSON `Screen`** (segunda representación, ahora innecesaria), el transporte HTTP, OpenRouter/Gemini y el modo single-shot — los reemplaza la iteración del `spec-refine-loop`. El endpoint del servicio deja de usarse. También absorbe los principios UX de la vieja skill `standards/frontend-design/` cuando el spec describe mantenimientos CRUD (formularios, listados, modales, navegación, feedback).