@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

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

@@ -0,0 +1,136 @@
+---
+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.
+---
+
+# ui-spec — UI spec authoring
+
+## Role
+
+`ui-design` — this is its **built-in default implementation**. Rebindable in `.workflow/skills.toml` to a third-party skill (installed via skills.sh) or `off`. Resolution: built-in default → `~/.workflow/skills.toml` (global) → `.workflow/skills.toml` (workspace).
+
+## 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í.
+
+## 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:
+
+- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía `AskUserQuestion`.
+- **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).
+
+## Knowledge
+
+### Schema (modelo `Screen` — universal, recursivo)
+
+```
+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
+```
+
+- `type` (region) ∈ `header · main · footer · sidebar · filters · summary`
+- `kind` (component) por categoría:
+  - **Contenedores**: `card · panel · modal`
+  - **Datos**: `table · list · grid`
+  - **Visualización**: `chart · metric · badge · image`
+  - **Entrada**: `textInput · select · checkbox · datePicker · toggle`
+  - **Acciones**: `button · link · actionGroup`
+  - **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.
+2. Pantalla simple (login, recuperar contraseña, error) → `components` directo, **sin** `regions`.
+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.
+
+### 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:
+
+- **Design system**: `material3 · bootstrap5 · tailwind3 · antDesign · chakraUI · custom`.
+- **Tema**: `light · dark · auto`.
+- **Idioma**: `es · en · …` (afecta los `label`).
+- **Densidad** (opcional): `compact · comfortable · spacious`.
+- **maxWidth** (opcional): pixeles, 320–3840 (anotación de layout).
+
+### 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.
+
+### Disambiguation
+
+Antes de autorar, resolver ambigüedades con `AskUserQuestion` (lo dispara el loop):
+
+- Pantalla simple o compleja (¿necesita `regions`?).
+- Qué acciones primarias/secundarias existen.
+- Qué datos muestra (tabla, métricas, ambos).
+- Si hay estados (loading, empty, error) que el spec deba enumerar.
+
+Si el humano no responde, asumir el caso más simple coherente con la descripción y anotar el supuesto.
+
+### 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"}]}
+
+// 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"}]}]}
+```
+
+## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec.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:
+
+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**.
+
+Ejemplo de render para el dashboard de arriba:
+
+```markdown
+# Dashboard
+**Tipo**: dashboard | **Plataforma**: web
+
+## Summary
+- **Total** (metric)
+- **Pendientes** (metric)
+
+## Main
+- **Registros** (table)
+```
+
+## 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).

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

@@ -0,0 +1,90 @@
+---
+name: writing
+description: >-
+  Clear technical writing capability — built-in default for the `writing` role. Rules
+  for any prose the AI produces in agent-workflow context: spec/plan/session artifacts,
+  commit messages, PR descriptions, export deliverables (manuals/reports). Short
+  sentences, lists over prose, one idea per line, "what + why" on one line, no jargon,
+  no filler. Use across all loops and in export-manuals / export-reports.
+---
+
+# writing — Clear technical writing
+
+## Role
+
+`writing` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). The most broadly composed role.
+
+## Purpose
+
+Reglas de estilo y formato para **toda la prosa** que la IA produce en contexto agent-workflow. Read-only por diseño: carga reglas; el `.md` lo materializa el consumidor (loop o export).
+
+## Composed by
+
+- **Todos los loops** — al escribir specs, planes, artefactos de sesión, mensajes de commit, descripciones de PR.
+- **`export-manuals`** — al redactar manuales técnicos (`docs/manuals`).
+- **`export-reports`** — al redactar informes ejecutivos (`docs/reports`).
+
+(También aplica a respuestas en chat sobre temas agent-workflow.)
+
+## Knowledge
+
+### Las 6 reglas
+
+1. **Frases cortas**: máximo ~15 palabras. Si pasa de 20, partir en dos.
+2. **Listas sobre prosa**: 3+ ideas paralelas van en bullets. Prosa solo para narrar.
+3. **Una idea por línea**: si el bullet usa "y" o ";" para meter una segunda idea, separar.
+4. **"Qué + por qué" en una línea**: formato `<qué>: <por qué corto>`. Sin párrafo aparte para el "por qué".
+5. **Sin jerga ni abreviaturas raras**: palabras comunes. Términos técnicos (MCP, C4) OK; abreviaturas inventadas (ej. "TLDR del CTX") no.
+6. **Sin relleno**: borrar "es importante notar que…", "cabe destacar…", "como se mencionó…", "en conclusión…". La idea va directo.
+
+### Palabras a evitar / preferir
+
+| Evitar | Preferir |
+|---|---|
+| "es importante notar que" / "cabe destacar" | (borrar, empezar con la idea) |
+| "en otras palabras" / "asimismo" | (borrar) / "también" |
+| "se procede a" / "llevar a cabo" | verbo directo / "hacer" |
+| "implementar la funcionalidad de X" | "implementar X" |
+| "realizar la validación de" | "validar" |
+| "a los efectos de" / "en el marco de" | "para" / "en" |
+| "no obstante" / "previamente mencionado" | "pero" / "antes" |
+| "TLDR", "FYI", "WIP" | escribir la palabra completa |
+
+### Ejemplo antes / después
+
+Antes:
+> Es importante notar que cada llamada implica un round-trip al servidor MCP además del consumo de tokens correspondiente al JSON de respuesta.
+
+Después (-50%):
+> Cada llamada MCP cuesta un round-trip y los tokens del JSON.
+
+Decisión densa, antes:
+> Se decidió, luego de analizar las alternativas, implementar la validación de roles solo en el frontend, dado que el backend no requiere la lógica y evita duplicar la regla.
+
+Después:
+> **Decisión**: validar permisos solo en el frontend.
+> **Por qué**: el backend no necesita la lógica; evita duplicar la regla.
+
+### Cuándo SÍ se permite prosa larga
+
+- Resúmenes ejecutivos donde la decisión necesita 4-6 oraciones para sostenerse.
+- Cadena causal de un incidente (causa raíz puede requerir un párrafo).
+- Tradeoffs de UX que necesitan explicación.
+
+Aún ahí: oraciones simples encadenadas, no oraciones largas.
+
+### Aplicación a los documentos del modelo nuevo
+
+- **spec** (`docs/specs`): brief y criterios de aceptación claros; la sección `## UI spec` la formatea el rol `ui-design`.
+- **plan** (`docs/plans`): resumen + fases + tasks con dependencias; tasks sin código inline (el código va en evidencia y se referencia).
+- **decisiones**: `**Decisión**:` + `**Por qué**:`, 3-6 líneas; si es obvia, no se registra.
+- **commit messages / PR**: mismas reglas (frases cortas, sin jerga, sin relleno). Formato canónico del mensaje en el rol `git`.
+- **export manuals/reports**: audiencia operadores/gerencia; bullets sobre prosa, sin relleno corporativo.
+
+## Output
+
+Ninguno propio. La skill aporta reglas; el `.md` lo escribe el consumidor (loop o export). Cuando escribe a `docs/`, lo hace solo el export que la compone (invariante 1) y solo en su carpeta (invariante 2).
+
+## Source
+
+Reciclada de `standards/redaccion-simple/` (las 6 reglas, tabla evitar/preferir, ejemplos, cuándo permitir prosa larga). Se descarta el catálogo de estructuras por artefacto del modelo viejo (OBJETIVO/DECISIONES/etc.); los documentos del modelo nuevo son spec/plan + artefactos de sesión, y su estructura la definen los loops y exports.