siesa-agents 2.1.90 → 2.1.91

package/claude/skills/sa-wds-visual-proposals/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: sa-wds-visual-proposals
+description: 'Toma los artefactos de planning ya hechos (PRD, épicas/historias, UX spec, arquitectura) como base y dirige el módulo WDS (Freya) para generar propuestas visuales — escenarios UX, page-specs y prototipos renderizados con siesa-ui-kit — ayudando a los diseñadores. Úsalo cuando el usuario diga "generar propuestas visuales", "wds visual proposals", "diseñar pantallas desde el planning" o quiera convertir el planning en mockups con siesa-ui-kit.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: FIRST load the FULL @_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/workflow_ext.md and apply its mandatory Siesa rules. THEN load the FULL @_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/workflow.md, READ its entire contents and follow its directions exactly!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.90",
+  "version": "2.1.91",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/data/component-mapping.csv

@@ -0,0 +1,47 @@
+ui_need,siesa_uikit_component,level,notes
+Botón de acción / CTA,Button,atom,"variantes Default/Outline/Plain, soporta icono"
+Grupo de botones tipo toggle,ButtonGroup,atom,selección estilo radio
+Contenedor de contenido,Card,atom,"subcomponentes Header/Title/Content/Footer"
+Etiqueta / estado / categoría,Badge,atom,variantes de color
+Diálogo modal / confirmación,Alert Dialog,atom,alertas y diálogos del sistema
+Imagen de perfil de usuario,Avatar,atom,
+Casilla de verificación,Checkbox,atom,
+Selección única en grupo,Radio,atom,"RadioGroup, RadioGroupItem"
+Interruptor on/off,Switch,atom,
+Campo de texto,Input,atom,
+Campo numérico,InputNumber,atom,
+Área de texto multilínea,Textarea,atom,
+Selector desplegable,Select,atom,navegación por teclado
+Menú de opciones,Dropdown,atom,"items, headings, dividers"
+Navegación por pestañas,Tabs,atom,soporta icono/badge
+Tabla de datos,Table,atom,"ordenamiento, variantes visuales"
+Separador de contenido,Divider,atom,
+Paginación,Pagination,atom,
+Selección jerárquica con checkboxes,Tree,atom,cascada
+Mensaje informativo / banner,Info,atom,
+Notificación temporal,Toast,atom,sistema de notificaciones
+Contador de alertas,Notification,atom,badge con contador
+Navegación lateral,NavigationRail,navigation,"con NavigationRailGroup/Item/Panel"
+Navegación inferior móvil,NavigationBar,navigation,3-5 destinos
+Carga de archivos,FileUploader,file,"drag-and-drop, progreso, validación"
+Galería de archivos,FileUploaderGallery,file,
+Búsqueda de entidad relacionada,LookupField,form,relación entre entidades
+Lista clave-valor,DescriptionList,form,
+Guardar/restaurar filtros,FormCacheSelector,form,
+Gestión CRUD de entidad,MasterCrud,enterprise,"listados+formularios+acciones; modos Modal/Sidebar/Page; consultar skill MasterCrud"
+Contenedor de formulario CRUD,MasterPatternView,enterprise,
+Gestión documental,MasterDocument,enterprise,"InstallmentsPanel, WithholdingsPanel, etc."
+Auditoría (historial + detalle),AuditHistoryPanel,audit,"timeline + diff campo a campo"
+Pantalla de login,LoginView,view,vista completa de inicio de sesión
+Pantalla de registro,SignUpView,view,con aceptación de términos
+Recuperar contraseña,RecoverPasswordView,view,
+Layout comercial (rail + navbar),LayoutBase,view,
+Contenedor principal con toolbar,LayoutContent,view,
+Vista de lista genérica,ListView,view,
+Tablero / dashboard,Dashboard,view,
+Selección de productos POS,ProductsView,view,categorías/grid/carrito
+Gestión de mesas POS,TableLayoutView,view,
+Gestión de contactos,ContactManager,view,CRUD completo de contactos
+Chat de soporte,ChatWidget,view,flotante
+Edición de parámetros del sistema,ParameterEditor,config,Server-Driven UI
+Administración de entidades dinámicas,Dynamic Entities/Admin,dynamic,no-code

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-01-init.md

@@ -0,0 +1,148 @@
+---
+name: 'step-01-init'
+description: 'Inicializa el workflow: carga config, detecta continuación, descubre artefactos de planning y el catálogo siesa-ui-kit, y define el alcance de las propuestas visuales'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+continueStepFile: '{workflow_path}/steps/step-01b-continue.md'
+nextStepFile: '{workflow_path}/steps/step-02-bridge.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# WDS module
+wds_module_path: '{project-root}/_siesa-agents/wds'
+wds_config: '{wds_module_path}/config.yaml'
+wds_scripts_path: '{wds_module_path}/scripts'
+
+# Catalog / standards
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+company_standards_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/create-architecture/data/company-standards'
+base_ux_spec: '{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md'
+
+# Data References
+componentMappingData: '{workflow_path}/data/component-mapping.csv'
+
+# Config
+bmmConfig: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Step 1: Inicialización y Descubrimiento
+
+## STEP GOAL
+
+Preparar todo el contexto para construir el puente planning → WDS: cargar configuración, detectar si es una re-ejecución, descubrir los artefactos de planning existentes, resolver el catálogo y el paquete de siesa-ui-kit, y acordar con el usuario el **alcance** (qué épicas/features se convierten en propuestas visuales).
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 NEVER generate WDS artifacts in this step — solo descubrimiento y alcance
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 🇪🇸 Texto de UI siempre en español; siesa-ui-kit primero
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## INITIALIZATION SEQUENCE
+
+### 1. Load Configuration
+
+Load `{bmmConfig}` and resolve: `{project_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{implementation_artifacts}`, `{project_knowledge}`, `{output_folder}`.
+
+Load `{wds_config}` and resolve `{design_artifacts}` (WDS base output path) and `{wds_output_folder}`. **WDS config wins for WDS paths** (see workflow_ext.md §4).
+
+### 2. Detect Continuation
+
+Check whether a WDS project already exists for visual proposals:
+
+- `{design_artifacts}/_progress/wds-project-outline.yaml`
+- `{design_artifacts}/A-Product-Brief/product-brief.md`
+- `{design_artifacts}/C-UX-Scenarios/` (any scenario folders)
+
+**If any exist** → this is a re-run. Load `{continueStepFile}`, read it fully, and execute it. STOP here.
+
+**If none exist** → fresh run. Continue to section 3.
+
+### 3. Discover Planning Artifacts (the BASE)
+
+Search the workspace for the SIESA planning artifacts that will feed the bridge. Look under `{planning_artifacts}/`, `{project_knowledge}/`, `{output_folder}/`, and the repo root:
+
+| Artifact | Typical location / glob | Used for |
+|---|---|---|
+| PRD | `*PRD*.md`, `prd/*.md`, `prd/feature-*.md` | Vision, goals, target users, scope → Product Brief |
+| Épicas/historias | `epics*.md`, `epics/epic-*.md`, `stories/*.md` | Flows + acceptance criteria → Scenarios & pages |
+| UX design spec | `*ux-design-specification*.md` | Design tokens, component strategy → render fidelity |
+| Arquitectura | `*architecture*.md`, `solution-architecture*.md` | Technical constraints on what can be proposed |
+
+Build an in-memory inventory: `{ prd: [...], epics: [...], ux_spec: path|null, architecture: [...] }`.
+
+**If NO planning artifacts are found**, inform the user and offer:
+- `[B]` Buscar en otra ruta (pídela)
+- `[X]` Cancelar — este workflow requiere planning previo (usa `/create-prd`, `/create-epics-and-stories`, `/create-ux-design` primero)
+
+HALT and wait. Do not fabricate planning content.
+
+### 3b. Detect & Render the Reference Design (if the user provided one)
+
+🔴 **Aplica workflow_ext §3C.** Busca un **diseño de referencia** aportado por el usuario que la propuesta deba replicar: un mockup/`*.html` (incluidos HTML autocontenidos/bundled), imágenes (`*.png/*.jpg`), un PDF de pantallas, o un enlace de Figma — en el prompt del usuario, en la raíz del repo, o junto a los planning artifacts.
+
+**Si existe un diseño de referencia:**
+1. **Renderízalo a screenshots AHORA** (no diseñes contra una descripción textual): imagen → úsala tal cual; HTML autocontenido → Chrome headless (`--screenshot`, con `--virtual-time-budget` amplio); HTML interactivo/multi-pantalla → condúcelo con `puppeteer-core` haciendo clic hacia cada estado (lista/crear/editar/diálogos) y captura uno por pantalla; Figma → exporta frames a PNG. Guárdalos en `{design_artifacts}/_design-ref/`.
+2. Si el diseño define tokens CSS (`:root { --… }`), **extrae ese bloque** para copiarlo luego al harness en step-02b/05 (evita que los componentes custom salgan sin estilo).
+3. Registra `reference_design: [rutas de los screenshots]` para el outline y anótalo para que step-05 verifique **lado a lado** contra estas imágenes.
+
+**Si NO hay diseño de referencia:** continúa normal (la fidelidad se guía por `{base_ux_spec}` + tokens de marca).
+
+### 4. Resolve siesa-ui-kit Catalog & Package
+
+1. Fetch `{siesa_uikit_catalog_url}` and keep the component catalog in memory (atoms + view-level components like `LoginView`, `Dashboard`, `MasterCrud`, `LayoutBase`).
+   - If unreachable, warn: "⚠️ No se pudo acceder al catálogo de siesa-ui-kit; usaré la semilla local `{componentMappingData}` y los tokens de `{base_ux_spec}`."
+2. El paquete siesa-ui-kit lo **fija el repo base BaseFrontend** (`siesa-ui-kit@^1.0.109` en su `package.json`) que step-02b clona como harness (workflow_ext §3A) — no hay que resolver el nombre a mano ni requiere una app consumidora previa.
+3. Load `{componentMappingData}` (seed mapping) and `{company_standards_path}/frontend-standards.md`.
+
+### 5. Define Scope (AUTO — todas las épicas con frontend, sin preguntar)
+
+🚫 **NO preguntes al usuario.** Selecciona automáticamente **TODAS las épicas que requieren frontend** — es decir, las que contienen al menos una historia con UI de cara al usuario. **Excluye** épicas/historias puramente backend o de infraestructura (p. ej. init de proyecto, configuración de base de datos, endpoints API sin pantalla) porque no tienen UI que proponer.
+
+Reporta la selección (sin HALT) y continúa:
+
+```
+📋 Inventario de planning: PRD {n} · épicas {n} · UX spec {sí/no} · arquitectura {n}
+🧩 Catálogo siesa-ui-kit: {cargado / fallback local} · paquete: {nombre}
+🎯 Alcance (automático): todas las épicas con frontend → {lista de épicas seleccionadas}
+   Excluidas por ser backend/infra: {lista o "ninguna"}
+```
+
+Store `scope` (todas las épicas con frontend) en memoria y **procede directamente** a la sección 6 — sin menú, sin esperar.
+
+### 6. Confirm and Proceed
+
+Confirm:
+```
+✅ Configuración lista.
+- Alcance: {scope}
+- Salida WDS: {design_artifacts}
+Continuando a construir el puente estratégico (Product Brief + Trigger Map)...
+```
+
+Load, read entire file, then execute `{nextStepFile}` immediately (no further menu).
+
+## CRITICAL STEP COMPLETION NOTE
+
+Two exit paths: continuation (`{continueStepFile}`) OR fresh → `{nextStepFile}`. Never both.
+
+---
+
+## 🚨 SUCCESS / FAILURE METRICS
+
+### ✅ SUCCESS
+- Both configs loaded; WDS `design_artifacts` resolved
+- Continuation correctly detected
+- Planning inventory built from real files (not invented)
+- siesa-ui-kit catalog fetched + render mode + package resolved
+- Scope = todas las épicas con frontend, auto-seleccionadas (sin preguntar)
+
+### ❌ FAILURE
+- Inventing planning content when none found
+- Hardcoding output paths instead of reading `{wds_config}`
+- Assuming the npm package name instead of reading `package.json`
+- Preguntar el alcance al usuario en vez de auto-seleccionar todas las épicas con frontend

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-01b-continue.md

@@ -0,0 +1,79 @@
+---
+name: 'step-01b-continue'
+description: 'Reanuda una ejecución previa del workflow de propuestas visuales a partir del estado WDS guardado'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+bridgeStep: '{workflow_path}/steps/step-02-bridge.md'
+warmupStep: '{workflow_path}/steps/step-02b-kit-warmup.md'
+scenariosStep: '{workflow_path}/steps/step-03-scenarios.md'
+specsStep: '{workflow_path}/steps/step-04-specs.md'
+prototypeStep: '{workflow_path}/steps/step-05-prototype.md'
+handoffStep: '{workflow_path}/steps/step-06-handoff.md'
+wds_validate: '{project-root}/_siesa-agents/wds/scripts/wds-validate.js'
+---
+
+# Step 1b: Reanudación
+
+## STEP GOAL
+
+Detectar dónde quedó la generación previa de propuestas visuales y reanudar en el paso correcto, sin rehacer trabajo ya hecho.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the complete step file before acting
+- 🚫 NEVER overwrite existing WDS artifacts — append/continue only
+- ✅ Speak in `{communication_language}`
+
+## RESUME SEQUENCE
+
+### 1. Read the WDS State
+
+Read `{design_artifacts}/_progress/wds-project-outline.yaml` and `{design_artifacts}/_progress/00-design-log.md` (if present). Extract phase status and the "Current" task.
+
+### 2. Assess What Exists
+
+Check, under `{design_artifacts}`:
+
+| Evidence | Means stage complete |
+|---|---|
+| `A-Product-Brief/product-brief.md` + `B-Trigger-Map/trigger-map.md` | Bridge (step-02) done |
+| `_kit-playground/` (clon BaseFrontend) + `_kit-playground/kit-grounding.md` | Kit Warm-up (step-02b) done |
+| `C-UX-Scenarios/<scenario>/README.md` + page folders | Scenarios (step-03) done |
+| Page specs pass `node {wds_validate} --all --output {design_artifacts}` | Specs (step-04) done |
+| Módulos del dominio en `_kit-playground/src/modules/` + screenshots `-real.png` | Prototype (step-05) done |
+| `proposal-index.md` present | Handoff (step-06) done |
+
+### 3. Present Resume Menu (HALT)
+
+```
+🔁 Encontré una ejecución previa de propuestas visuales.
+Estado: {resumen del outline}
+
+¿Cómo continúo?
+[R] Reanudar donde quedó ({siguiente paso detectado})
+[E] Ir a un paso específico (bridge / kit-warmup / scenarios / specs / prototype / handoff)
+[N] Empezar de cero (conservará los archivos existentes; pediré confirmación antes de sobrescribir)
+[X] Cancelar
+```
+
+HALT and wait.
+
+### 4. Route
+
+Load and execute the chosen step file:
+- bridge → `{bridgeStep}`
+- kit-warmup → `{warmupStep}`
+- scenarios → `{scenariosStep}`
+- specs → `{specsStep}`
+- prototype → `{prototypeStep}`
+- handoff → `{handoffStep}`
+
+Read the chosen file fully before executing.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Correct stage detected and resumed without redoing finished work.
+❌ Re-running the bridge over existing artifacts, or overwriting specs without confirmation.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-02-bridge.md

@@ -0,0 +1,114 @@
+---
+name: 'step-02-bridge'
+description: 'Traduce los artefactos de planning de SIESA a la fundación estratégica que WDS/Freya exige: Product Brief, Trigger Map, personas, tokens y project outline'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-02-bridge.md'
+nextStepFile: '{workflow_path}/steps/step-02b-kit-warmup.md'
+
+productBriefTemplate: '{workflow_path}/templates/product-brief-bridge.md'
+triggerMapTemplate: '{workflow_path}/templates/trigger-map-bridge.md'
+base_ux_spec: '{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md'
+
+# WDS guides to honor while writing the foundation
+freya_strategic_guide: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/strategic-design.md'
+saga_existing_materials: '{project-root}/_siesa-agents/wds/data/agent-guides/saga/working-with-existing-materials.md'
+wds_glossary: '{project-root}/_siesa-agents/wds/data/wds-glossary.md'
+---
+
+# Step 2: Puente Estratégico (Planning → WDS)
+
+## STEP GOAL
+
+Producir, a partir de los artefactos de planning ya hechos, los prerequisitos EXACTOS que Freya valida antes de diseñar:
+
+1. `{design_artifacts}/A-Product-Brief/product-brief.md`
+2. `{design_artifacts}/B-Trigger-Map/trigger-map.md` (+ personas + feature-impact)
+3. Semilla de tokens/decisiones visuales desde la UX spec (para fidelidad de marca)
+4. `{design_artifacts}/_progress/wds-project-outline.yaml` y `_progress/00-design-log.md`
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first
+- 🧭 Load `{saga_existing_materials}` — usa el patrón "import existing materials": referenciar → validar vigencia → llenar huecos → sintetizar. NO inventes; deriva todo del planning.
+- 🧠 Load `{freya_strategic_guide}` — el Product Brief y el Trigger Map deben quedar en términos que Freya pueda usar (golden circle WHY→HOW→WHAT, driving forces, awareness stages).
+- 📚 Load `{wds_glossary}` para respetar nombres/estructura de artefactos WDS.
+- 🇪🇸 Comunicación en `{communication_language}`; el contenido de documentos sigue `{document_output_language}`, PERO el texto de UI de ejemplo siempre en español.
+
+## EXECUTION SEQUENCE
+
+### 1. Map PRD → Product Brief
+
+Read the PRD artifacts from the step-01 inventory. Using `{productBriefTemplate}`, populate:
+
+| WDS Product Brief field | Source in SIESA planning |
+|---|---|
+| Vision / WHY | PRD problem statement, goals, value proposition |
+| Target users | PRD user segments / personas section |
+| Business goals & KPIs | PRD objectives / success metrics |
+| Scope & constraints | PRD scope + architecture constraints |
+| Content language / tone | UX spec voice (default: español, tono corporativo Siesa) |
+| Visual direction | UX spec tokens (color primario `#0e79fd`, tipografía Inter, etc.) |
+
+Write to `{design_artifacts}/A-Product-Brief/product-brief.md`. Add a provenance footer listing the source files. Where the PRD is silent, mark `⚠️ [Asunción — confirmar]` and ask the user before finalizing.
+
+### 2. Map PRD + Epics → Trigger Map & Personas
+
+Using `{triggerMapTemplate}`:
+
+- **Personas:** derive from PRD user segments. Use alliterative names per WDS convention (e.g. "Carla la Cajera"). One file each: `{design_artifacts}/B-Trigger-Map/NN-persona-<nombre>-<arquetipo>.md`.
+- **Driving forces:** map each persona's positive forces (wishes, aspirations) and negative forces (fears, frustrations) from the PRD pains/gains and epic goals.
+- **Awareness stage** per persona (Unaware → … → Most Aware) inferred from the product context.
+- **Feature impact:** build `{design_artifacts}/B-Trigger-Map/feature-impact.md` cross-referencing each in-scope epic/feature × persona × driving force.
+
+Write the main `{design_artifacts}/B-Trigger-Map/trigger-map.md`.
+
+### 3. Seed Visual Foundation from UX Spec
+
+Read `{base_ux_spec}` and the project-specific `ux-design-specification.md` (if found in step-01). Extract into a short note `{design_artifacts}/A-Product-Brief/visual-direction.md`:
+- Color tokens (primary/secondary/tertiary scales)
+- Typography (Inter), spacing scale, dark mode availability
+- Component strategy summary (siesa-ui-kit first)
+
+This note is what step-05 uses to keep prototypes brand-faithful.
+
+### 4. Write the WDS Project Outline & Design Log
+
+Create `{design_artifacts}/_progress/wds-project-outline.yaml` so Freya's activation recognizes the project:
+
+```yaml
+project_name: {project_name}
+methodology_version: wds-v6
+source: siesa-planning-bridge
+phases:
+  "1-product-brief": complete
+  "2-trigger-map": complete
+  "3-ux-scenarios": pending
+  "4-ux-design": pending
+scope: {scope from step-01}
+siesa_uikit_package: {resolved package name}
+```
+
+Initialize `{design_artifacts}/_progress/00-design-log.md` with a "Current" table pointing to "Phase 3 — generar escenarios".
+
+### 5. Review Gate (HALT)
+
+Present a concise summary of the generated foundation (personas, driving forces, visual direction) and ask:
+
+```
+He construido la base estratégica WDS desde tu planning:
+- Product Brief ✅   - Trigger Map + {n} personas ✅   - Dirección visual ✅
+
+[C] Continuar al Kit Warm-up (grounding del UI kit real) y luego a escenarios
+[E] Editar algo de la base antes de continuar
+[X] Detener aquí (la base queda lista para usar /freya manualmente)
+```
+
+HALT. On `C`, update the design log and load+execute `{nextStepFile}` (Kit Warm-up — step-02b).
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ product-brief.md, trigger-map.md, personas, visual-direction.md y wds-project-outline.yaml creados, todos trazables al planning.
+❌ Inventar personas/objetivos sin fuente; omitir el outline (Freya no reconocería el proyecto); escribir UI de ejemplo en inglés.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-02b-kit-warmup.md

@@ -0,0 +1,96 @@
+---
+name: 'step-02b-kit-warmup'
+description: 'Kit Warm-up: instala/usa el paquete REAL de siesa-ui-kit en una mini app, verifica con build+render, y produce kit-grounding.md (fuente de verdad anti-alucinación) ANTES de diseñar'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-02b-kit-warmup.md'
+nextStepFile: '{workflow_path}/steps/step-03-scenarios.md'
+
+# Outputs
+kit_playground: '{design_artifacts}/_kit-playground'
+kit_grounding: '{design_artifacts}/_kit-playground/kit-grounding.md'
+
+# References
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+componentMappingData: '{workflow_path}/data/component-mapping.csv'
+base_ux_spec: '{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md'
+---
+
+# Step 2b: Kit Warm-up — Grounding del UI kit REAL (anti-alucinación)
+
+## STEP GOAL
+
+Antes de mapear objetos a componentes y renderizar, el agente debe **tocar el kit real**: instalarlo, compilarlo y renderizarlo. El resultado es `kit-grounding.md` — la **fuente de verdad** (nombres, props, contratos reales) que consumen step-04 (specs) y step-05 (prototype). Esto evita alucinaciones como suponer componentes/props que el catálogo `llms.txt` lista pero el paquete no expone (p. ej. `LayoutContent` vs el real `ContentLayout`, o `Dashboard`/`StatCard` inexistentes).
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first.
+- 🔴 La verdad la da el **paquete instalado**, NO el catálogo. Si `kit-grounding.md` y `llms.txt` discrepan, **gana el grounding**.
+- 🧪 No se considera "verificado" hasta que el playground **compile** (build exit 0) o renderice.
+- 🇪🇸 Texto de UI siempre en español.
+- ✅ Speak in `{communication_language}`.
+
+## EXECUTION SEQUENCE
+
+### 1. Detect existing grounding (skip if fresh)
+
+If `{kit_grounding}` already exists AND records the same `siesa_uikit_package` version resolved in step-01:
+- Inform the user it's current and **skip to section 6** (no reinstall).
+Otherwise continue.
+
+### 2. Clone BaseFrontend (the harness) — per workflow_ext §3A
+
+El harness del frontend ES un clon del repo base oficial `{frontend_base_repo}` (Vite 6 + React 19 + TS + Tailwind v4 + `siesa-ui-kit@^1.0.109` con todos los peers ya instalados, TanStack Router, Clean Architecture por módulos, capa mock y shell `LayoutBase`). NO scaffoldees a mano.
+
+```bash
+git clone --depth 1 https://github.com/SiesaTeams/BaseFrontend {kit_playground}
+rm -rf {kit_playground}/.git    # no anidar .git dentro del repo SIESA
+cd {kit_playground} && npm install
+```
+
+- Si `{kit_playground}` ya existe con un clon válido (tiene `package.json` con dependencia `siesa-ui-kit`), reutilízalo — no re-clones.
+- El `.gitignore` del base solo trae `node_modules/`; añade `dist/` para no versionar el build de verificación.
+- Si NO hay red/acceso al repo o al registro npm → ve a la sección 5 (grounding degradado) y avisa al usuario.
+- El paquete queda **fijado por el `package.json` del base** (`siesa-ui-kit@^1.0.109`); no hay que resolver el nombre a mano. CSS ya se importa en `src/main.tsx` (`import 'siesa-ui-kit/styles.css'`).
+
+### 3. Verify the real package builds (the grounding act)
+
+1. `npm run build` en `{kit_playground}` debe salir **exit 0** (compila los imports/exports reales del kit contra los módulos de ejemplo `agentes`/`colaboradores`). Un import roto es en sí un hallazgo.
+2. Opcional: `npm run dev` (puerto 3010) + screenshot para confirmar el render visual del shell `LayoutBase` + `MasterCrud`.
+3. Extrae los **exports y prop types reales** desde el paquete instalado: `{kit_playground}/node_modules/siesa-ui-kit/dist/index.d.ts` y `dist/components/**/*.types.d.ts`.
+4. Documenta los contratos que el base **ya usa** como referencia verificada: `LayoutBase` (props del shell + `navigationItems`), `MasterCrud` (array `fields` con `accessorKey`/`header`/`type`/`config` + `service`/`schema`), y el patrón de 4 capas de un módulo (`src/modules/agentes/`).
+
+### 5. Write `kit-grounding.md`
+
+Write `{kit_grounding}` with, at minimum:
+- **Install**: package name + version + peer deps + transitive deps + CSS import + order gotchas.
+- **Real component inventory** (verified export names).
+- **Real prop signatures** for the components in scope (e.g. `Button.type` not `variant`, `Badge.label`, `DescriptionList` = one `term`/`details` per row, `Table` data-driven, server-driven `LookupField`/`ContactManager`).
+- **Hallucinations caught**: a table of "assumed name → real name / does-not-exist" (this is the anti-hallucination payload).
+
+**Degraded mode** (no install possible): still write `kit-grounding.md` from `{siesa_uikit_catalog_url}` + `{componentMappingData}`, clearly flagged `⚠️ NO VERIFICADO EN RUNTIME — derivado del catálogo`. Never silently skip the file.
+
+### 6. Spec Sync gate (HALT)
+
+Present a concise summary of the grounding (package/version, components verified, hallucinations caught) and ask:
+
+```
+🧪 Kit Warm-up listo. Grounding en _kit-playground/kit-grounding.md
+- Paquete: {nombre}@{versión} ({verificado por build/render | degradado})
+- Componentes verificados: {n}   - Correcciones detectadas: {n}
+
+[C] Continuar a generar escenarios (step-04/05 usarán el grounding)
+[S] Sincronizar el spec ahora (aplicar correcciones a ux-design-specification.md)
+[E] Editar el grounding antes de continuar
+```
+
+If `[S]`: apply the name/contract corrections to the project `ux-design-specification.md` (add/refresh a "Kit Grounding — Spec Sync" section). Then return to this menu.
+
+On `[C]`: update `_progress/00-design-log.md` ("Phase 3 — generar escenarios; grounding listo") and load + execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Paquete real resuelto; playground compila/renderiza; `kit-grounding.md` escrito con nombres/props reales y alucinaciones detectadas; gate de Spec Sync presentado.
+❌ Saltar el grounding y diseñar contra el catálogo; omitir `kit-grounding.md`; declarar "verificado" sin build/render; escribir UI de ejemplo en inglés.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-03-scenarios.md

@@ -0,0 +1,102 @@
+---
+name: 'step-03-scenarios'
+description: 'Deriva escenarios UX y páginas desde las épicas/historias usando los scripts scaffold de WDS'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-03-scenarios.md'
+nextStepFile: '{workflow_path}/steps/step-04-specs.md'
+
+wds_scripts: '{project-root}/_siesa-agents/wds/scripts'
+init_scenario: '{wds_scripts}/wds-init-scenario.js'
+init_page: '{wds_scripts}/wds-init-page.js'
+nav: '{wds_scripts}/wds-nav.js'
+---
+
+# Step 3: Escenarios y Páginas (Phase 3 WDS)
+
+## STEP GOAL
+
+Convertir cada épica/historia del alcance en la estructura de escenarios y páginas de WDS, usando EXCLUSIVAMENTE los scripts scaffold (nunca markdown a mano). Salida bajo `{design_artifacts}/C-UX-Scenarios/`.
+
+## MANDATORY EXECUTION RULES
+
+- 🧩 NEVER write the scenario/page markdown by hand — use the scripts
+- 📖 Read this entire file first
+- ✅ Speak in `{communication_language}`
+
+## MAPPING MODEL
+
+```
+Épica            → Escenario WDS   (un flujo de usuario)
+Historia         → Página WDS      (una pantalla del flujo)
+Criterio (AC)    → Success Criteria de la página
+Orden de historias → numeración de páginas (01, 02, ...)
+```
+
+## EXECUTION SEQUENCE
+
+### 1. Plan the Scenarios (HALT for confirmation)
+
+From the in-scope epics, propose the scenario/page breakdown:
+
+```
+Propuesta de escenarios:
+1. "01 <Épica A>"  → páginas: 01 <Historia> · 02 <Historia> · ...
+2. "02 <Épica B>"  → páginas: ...
+
+[C] Confirmar y generar la estructura
+[E] Ajustar el desglose
+```
+
+HALT. Group stories that clearly belong to the same flow; split very large epics into multiple scenarios if needed. Keep page count realistic for a proposal.
+
+### 2. Create Each Scenario
+
+For each confirmed scenario:
+
+```bash
+node {init_scenario} \
+  --scenario "NN <Nombre del escenario>" \
+  --description "<flujo en una frase, en español>" \
+  --output {design_artifacts}
+```
+
+### 3. Create Each Page
+
+For each story/screen in the scenario:
+
+```bash
+node {init_page} \
+  --page "NN <Nombre de la página>" \
+  --scenario "NN <Nombre del escenario>" \
+  --platform "Web" \
+  --visibility "<Public|Authenticated>" \
+  --output {design_artifacts}
+```
+
+Choose `--platform` from the architecture (default "Web"; "Mobile web" if the PRD targets mobile). Choose `--visibility` from whether the story is pre/post login.
+
+### 4. Wire Navigation
+
+After all pages of a scenario exist:
+
+```bash
+node {nav} --scenario "NN <Nombre del escenario>" --output {design_artifacts}
+```
+
+Or, once everything is created: `node {nav} --all --output {design_artifacts}`.
+
+### 5. Record Source Traceability
+
+For each created page, note in memory (used in step-04 and step-06) the originating `[Source: <Épica> / <Historia> / FR-x]` so every spec and proposal traces back to planning.
+
+### 6. Update Log & Proceed
+
+Update `{design_artifacts}/_progress/00-design-log.md` "Current" to "Phase 4 — poblar page-specs". Load and execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Cada escenario y página creados vía scripts; navegación cableada; trazabilidad a épicas/historias registrada.
+❌ Escribir specs a mano; páginas sin orden numérico; perder el vínculo con las historias de origen.