siesa-agents 2.1.90 → 2.1.91

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

@@ -0,0 +1,97 @@
+---
+name: 'step-04-specs'
+description: 'Puebla cada page-spec con objetos mapeados a componentes siesa-ui-kit y spacing, en español, y valida estructuralmente'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-04-specs.md'
+nextStepFile: '{workflow_path}/steps/step-05-prototype.md'
+
+wds_scripts: '{project-root}/_siesa-agents/wds/scripts'
+add_object: '{wds_scripts}/wds-add-object.js'
+add_spacing: '{wds_scripts}/wds-add-spacing.js'
+validate: '{wds_scripts}/wds-validate.js'
+
+componentMappingData: '{workflow_path}/data/component-mapping.csv'
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+kit_grounding: '{design_artifacts}/_kit-playground/kit-grounding.md'
+freya_spec_quality: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/specification-quality.md'
+freya_design_system: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/design-system.md'
+---
+
+# Step 4: Page Specs con siesa-ui-kit (Phase 4 WDS)
+
+## STEP GOAL
+
+Rellenar cada página con sus objetos UI (mapeados a componentes **siesa-ui-kit**), spacing y tipografía, con todo el texto en **español**, y dejar las specs validando sin errores.
+
+## MANDATORY EXECUTION RULES
+
+- 🧩 NEVER edit the page markdown by hand — use `wds-add-object.js` / `wds-add-spacing.js`
+- 🧪 **GROUNDING FIRST**: load `{kit_grounding}` (de step-02b) and treat it as the **authoritative source** for component names and props. If `{kit_grounding}` and the catalog (`llms.txt`) disagree, **el grounding gana** (usa el nombre/contrato real, p. ej. `ContentLayout` no `LayoutContent`; no inventes `Dashboard`/`StatCard`). If `{kit_grounding}` is missing, go back and run step-02b.
+- 🔴 siesa-ui-kit FIRST: cada objeto se mapea a un componente del catálogo antes de considerar algo custom
+- 🇪🇸 Texto de UI en español → va en `--se`; referencia en inglés → `--en`
+- 📖 Read this entire file first; load `{freya_spec_quality}` and `{freya_design_system}`
+- ✅ Speak in `{communication_language}`
+
+## EXECUTION SEQUENCE
+
+### 1. Load Grounding + Catalog (grounding wins)
+
+1. **FIRST** load `{kit_grounding}` (real package truth from step-02b): exact export names, prop signatures, and the "hallucinations caught" table. This is authoritative.
+2. Then load the catalog (`{siesa_uikit_catalog_url}`) and `{componentMappingData}` as a secondary reference. When they conflict with the grounding, **use the grounding** (real names/props).
+3. Prefer **view-level** components when a whole page matches — but use the **real export names from the grounding** (e.g. `ContentLayout`, `MasterCrud`, `MasterPatternView`, `ListView`, `LoginView`; note there is no `Dashboard`/`StatCard` export — compose with `Card`).
+
+### 2. For Each Page — Define Objects
+
+Walk the page's originating story + acceptance criteria. For each UI element, decide the section (e.g. "Encabezado", "Formulario", "Acciones") and the siesa-ui-kit component, then append:
+
+```bash
+node {add_object} \
+  --page "{design_artifacts}/C-UX-Scenarios/<scenario-slug>/<page-slug>/<page-slug>.md" \
+  --section "<Sección>" \
+  --object "<Nombre del objeto>" \
+  --component "<Componente siesa-ui-kit>" \
+  --se "<Texto en ESPAÑOL>" \
+  --en "<English reference>" \
+  --behavior "<comportamiento, ej. onClick: enviar formulario>"
+```
+
+**Component Decision Protocol** (per workflow_ext.md §3) — **automático, sin preguntar**: si la necesidad NO está en siesa-ui-kit, **busca el componente en shadcn** (registro MCP de shadcn). Si existe en shadcn, úsalo. Si tampoco está en shadcn, **el agente crea el componente** (componiendo primitivos + tokens de marca). Registra la decisión (`kit` / `shadcn` / `custom`) en el design log.
+
+For `MasterCrud`-shaped pages (listados con CRUD), consult the `MasterCrud` skill for the contract and capture its key props as object behaviors.
+
+### 3. For Each Page — Define Spacing
+
+Add the spacing decisions that shape the layout rhythm:
+
+```bash
+node {add_spacing} \
+  --page "{design_artifacts}/C-UX-Scenarios/<scenario-slug>/<page-slug>/<page-slug>.md" \
+  --direction <v|h> --type <space|separator|line> --size <zero|sm|md|lg|xl|2xl|3xl|flex> \
+  --reason "<por qué, en español>"
+```
+
+### 4. Add Source Traceability
+
+In each page's "Reference Materials" / "Overview", add the `[Source: <Épica>/<Historia>/FR-x]` line recorded in step-03, and set Success Criteria from the story's acceptance criteria.
+
+### 5. Validate
+
+Run validation and fix every error before proceeding:
+
+```bash
+node {validate} --all --output {design_artifacts}
+```
+
+Common fixes: missing SE/EN content, Object IDs not kebab-case or wrong page prefix, missing sketches folder, wrong nav row count. Re-run until 0 errors.
+
+### 6. Update Log & Proceed
+
+Update the design log "Current" to "Phase 4 — render de prototipos". Load and execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Todos los objetos mapeados a siesa-ui-kit, texto en español, `wds-validate.js --all` con 0 errores, trazabilidad presente.
+❌ Componentes custom sin pasar por el protocolo; UI en inglés; specs que no validan; objetos sin componente asignado.

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

@@ -0,0 +1,102 @@
+---
+name: 'step-05-prototype'
+description: 'Fase de prototipado: construye UNA app integrada navegable con los componentes reales de siesa-ui-kit y la verifica en navegador'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-05-prototype.md'
+nextStepFile: '{workflow_path}/steps/step-06-handoff.md'
+
+freya_agentic: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/agentic-development.md'
+base_ux_spec: '{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md'
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+kit_grounding: '{design_artifacts}/_kit-playground/kit-grounding.md'
+kit_playground: '{design_artifacts}/_kit-playground'
+---
+
+# Step 5: Prototipos Renderizados (Visual Design)
+
+## STEP GOAL
+
+Producir prototipos **navegables y visibles** de las páginas especificadas, fieles a siesa-ui-kit, y verificarlos en navegador. Este es el entregable que el diseñador "ve".
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first; load `{freya_agentic}` (design loop + verificación Puppeteer de Freya)
+- 🧬 Trabaja **DENTRO del clon de BaseFrontend** en `{kit_playground}` (de step-02b), per workflow_ext §3A. Ya trae el paquete real, todos los peers, el shell `LayoutBase`, routing, capa mock y los módulos de ejemplo `agentes`/`colaboradores` que vas a **reemplazar**.
+- 🧪 Load `{kit_grounding}` (de step-02b) y úsalo para imports/props reales. Importa siempre desde `siesa-ui-kit` (nunca asumas `@siesa/ui-kit`).
+- 🎨 Implementa contra los Object IDs de las page-specs — la spec es la fuente de verdad
+- 🇪🇸 Todo el texto visible en español; 🔴 siesa-ui-kit primero; ⚙️ Vite (BaseFrontend), nunca Next.js
+- ✅ Speak in `{communication_language}`
+
+## ENTREGABLE: LA APP CLONADA (BaseFrontend) INTEGRADA
+
+El entregable es **la app de BaseFrontend clonada en `{kit_playground}`**, con sus módulos de ejemplo reemplazados por los módulos del dominio del alcance, navegable de punta a punta con `npm run dev` (standalone, puerto 3010). NO un prototipo aislado por épica. Respeta las **convenciones del base** (no las reescribas):
+
+1. **Shell = ya está** en `src/routes/_app.tsx` → `LayoutBase` de siesa-ui-kit con `navigationItems` de `src/config/navigation.tsx` + `<Outlet/>`. La épica de shell (nav/rail/404) **es este layout**; ajústalo (productName, logo, ítems), no lo reconstruyas.
+2. **Un módulo por dominio**, NO por página-spec, bajo `src/modules/<dominio>/` con las 4 capas del patrón `agentes`/`colaboradores`:
+   - `domain/<x>.types.ts` — entidad + DTOs
+   - `application/schemas/<x>.schema.ts` (Zod) + `application/hooks/` (useQuery/useMutation)
+   - `infrastructure/api/<x>.api.ts` (mock → Axios) + `infrastructure/service/<x>.service.ts` (`CrudService<T>`)
+   - `presentation/pages/<X>Page.tsx`
+   Agrupa épicas relacionadas en el mismo módulo:
+   - Épicas de "listado + CRUD de una entidad" → un `MasterCrud` dirigido por `fields` (copia el patrón de `AgentesPage.tsx`): cada campo `{accessorKey, header, type, config:{required, showInList, searchable, cardPosition,…}}`.
+   - Épicas de "relación/asociación" NO son un módulo aparte: **se integran dentro de los módulos que relacionan** (panel de asociados + "Asociar/Reasignar" dentro del módulo correspondiente).
+   - Épica de dashboard/inicio → página de tarjetas (`Card`) con totales **calculados del estado real** (lee los stores mock).
+   - Épica de administración/catálogos → su módulo (`MasterCrud` o `GenericEntities`/`GenericEntityModal`).
+3. **Estado compartido = la capa mock** (`src/lib/mock/<x>.mock.ts`): una BD en memoria por entidad que los servicios leen/escriben. Los flujos se conectan DE VERDAD sobre estos stores:
+   - Eliminar una entidad padre → sus hijos quedan huérfanos y aparecen así en el otro módulo.
+   - Asociar/reasignar/crear/editar → se refleja al instante en todos los módulos afectados (invalida las queries de TanStack Query).
+   - Enlaces cruzados navegables ("Ver cliente" desde un contacto → `navigate({ to: '/clientes', search:{ id } })`).
+4. **Rutas + nav**: por cada módulo, crea `src/routes/_app/<modulo>.tsx` (`createFileRoute` → tu `Page`) y añade su ítem a `src/config/navigation.tsx` (con su permiso en `permissions.ts`). `routeTree.gen.ts` lo regenera el plugin de Vite al levantar `dev` — no lo edites.
+5. **Providers ya cableados**: `App.tsx` monta `QueryClientProvider` (`config/query-client.ts`) y el toaster. No los re-declares.
+6. Borra o vacía los módulos/rutas/nav de ejemplo (`agentes`, `colaboradores`) que no correspondan al proyecto.
+
+**Nunca** generes HTML+CSS que finja usar el kit (`<div class="rail" title="NavigationRail">`, `/* siesa-ui-kit Button */`) — se importan los componentes reales, siempre.
+
+**Gotchas reales (el base ya resuelve varios):**
+- **`QueryClientProvider` ya provisto** por `App.tsx`/`config/query-client.ts` → `GenericEntityModal`/`ContactManager` funcionan sin envolver nada extra.
+- **`LayoutBase` ya maneja logos/usuario** vía props en `_app.tsx` (`productName`, `siesaLogoPath`, `userDropdown`). Ajusta esas props, no toques Navbar/rail a mano.
+- **`MasterCrud`** es data-driven por `fields` + `service` + `schema` (ver `AgentesPage.tsx`). Para el contrato completo consulta el skill `MasterCrud`.
+- **`ContentLayout`** = master-detail `{children, factBox, factBoxOpen, onFactBoxClose}` (main + FactBox), no un header de título.
+- **`LookupField`** es server-driven: `fetcher` mock que devuelva `{ data, page, pageSize }` (records con `Id` PascalCase). No es un `<Select>`.
+- **`Button`** variante = `type` (`default|outline|plain`), no `variant`. **`Badge`** texto en `label`. **`Input`** trae `label`/`errorMessage`. **Toast** = `sonner`.
+
+## DESIGN LOOP (per page) — Freya's pattern
+
+For each page, follow the inline-testing split from `{freya_agentic}`:
+
+1. **Implement** the section from the spec (objects, spacing, Spanish text).
+2. **Verify en navegador** (agent-checkable, measurable). Levanta el harness (`cd {kit_playground} && npm run dev`, puerto **3010**) y captura cada módulo/estado (navega por el rail; abre detalle/form/diálogos). BaseFrontend usa **rutas de historial**, captura por ruta (`/clientes`, `/contactos`, …), no por hash.
+   - 🔴 **Si hay diseño de referencia (`{design_artifacts}/_design-ref/`, de step-01/workflow_ext §3C): compara tu screenshot LADO A LADO contra el de referencia — solo pasa si coinciden layout, colores, espaciado, tipografía y componentes.** No declares fidelidad contra una descripción textual ni contra tu modelo mental. Si el diseño usa tokens `var(--…)`, confirma que su bloque `:root` está importado en el harness (`src/styles/tokens.css` desde `src/index.css`) o los componentes custom saldrán sin estilo. Si el default de un componente de vista del kit (`MasterCrud`/`LayoutBase`) no se parece al diseño, compón la presentación a medida para igualarlo (importando primitivos del kit).
+   - Text content matches the spec (Spanish strings)
+   - Colors / key dimensions match tokens
+   - Interactive states (hover/focus/disabled, empty/error) render
+   - Navigation links work
+   **Captura de screenshots:** si no hay Puppeteer/Playwright instalado, usa **Chrome headless** directamente (suele estar disponible en Windows):
+   `chrome --headless=new --disable-gpu --hide-scrollbars --window-size=1440,900 --virtual-time-budget=4000 --screenshot=<out.png> "http://localhost:3010/<ruta>"`.
+   Guárdalos en `{design_artifacts}/C-UX-Scenarios/<scenario>/<page>/sketches/<page-slug>-real.png`. Nota: cada invocación de Chrome tarda ~7–10s; captura en lotes pequeños y mata procesos chrome colgados entre lotes.
+3. **Fix** measurable issues before presenting.
+4. **Present** to the user for qualitative feedback (feel, jerarquía visual, claridad). Iterate per their notes.
+
+## EXECUTION SEQUENCE
+
+1. **Construye los módulos dentro del clon** (`{kit_playground}/src/modules/<dominio>/`, 4 capas cada uno) + sus rutas (`src/routes/_app/<modulo>.tsx`) + ítems de nav (`config/navigation.tsx`), y ajusta el shell (`_app.tsx`). Reemplaza los módulos de ejemplo. Estado compartido en la capa mock; flujos cruzados de verdad (ver arquitectura arriba). Muestra progreso por módulo.
+2. **Verifica** con `cd {kit_playground} && npm run build` (exit 0) y `npm run dev` (puerto 3010), y **guarda un screenshot por página-spec** en su `sketches/<page-slug>-real.png` (satisface la validación WDS); captura los módulos/estados navegando por rutas reales, no pantallas aisladas.
+3. **Empaqueta la app como UN HTML autocontenido → `{design_artifacts}/propuesta-app.html`.** 🔴 Este ES el entregable estático para el diseñador. **NO** generes una galería de screenshots (`propuestas-visuales.html`): el entregable es la **app real funcional** en un solo archivo que abre por doble clic (`file://`), no imágenes. Los screenshots del paso 2 son solo para tu verificación interna. La app clonada es un SPA de Vite; para que funcione por `file://` se compila con JS+CSS inline y **hash routing**:
+   a. Instala el plugin en el clon: `cd {kit_playground} && npm i -D vite-plugin-singlefile`.
+   b. Crea `{kit_playground}/vite.config.singlefile.ts`: `base: './'`, `define: { 'import.meta.env.VITE_SINGLEFILE': JSON.stringify('true') }`, plugins `[TanStackRouterVite({...}), tailwindcss(), react(), viteSingleFile()]`, `resolve.alias` igual al base, `build: { outDir: 'dist-single', assetsInlineLimit: 100000000, chunkSizeWarningLimit: 100000 }`. Añade `dist-single/` al `.gitignore`.
+   c. En `src/App.tsx` usa **hash routing SOLO bajo el flag** (la app web normal se queda con history routing): `import { createHashHistory } from '@tanstack/react-router'` → `const isSingleFile = Boolean((import.meta.env as Record<string, unknown>).VITE_SINGLEFILE)` → `createRouter({ routeTree, ...(isSingleFile ? { history: createHashHistory() } : {}) })`. Sin hash, la ruta inicial `file://…` no matchea y sale 404.
+   d. **Importa los assets (logos/imágenes) vía Vite** (`import logo from '@/assets/logo.png'` y pásalo como prop), NO por ruta pública (`/logo.png`): solo los importados se inlinan como data-URI y cargan por `file://`. Copia a `src/assets/` cualquier logo que hoy viva en `public/`.
+   e. Compila y copia: `npx vite build --config vite.config.singlefile.ts` y luego `cp {kit_playground}/dist-single/index.html {design_artifacts}/propuesta-app.html`.
+   f. **Verifica** abriendo `file:///.../propuesta-app.html` (screenshot headless): deben verse el shell + logo, y una **ruta profunda por hash** (`propuesta-app.html#/<ruta>`, ej. `#/clientes/1`).
+   - La versión interactiva/viva sigue siendo `cd {kit_playground} && npm run dev` (:3010).
+   - Si existen `{design_artifacts}/C-UX-Scenarios/<escenario>/prototype.html`, reescríbelos como una nota breve que apunta a `propuesta-app.html` y a `npm run dev`.
+4. Update `{design_artifacts}/_progress/00-design-log.md` with what was rendered and any open design questions.
+5. Load and execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ App **clonada de BaseFrontend** con módulos del dominio (4 capas), shell `LayoutBase`, estado compartido en la capa mock y flujos conectados; `npm run build` exit 0 y `npm run dev` levanta en :3010; **`propuesta-app.html`** = la app real en UN HTML autocontenido que abre por `file://` (single-file + hash routing), verificada por screenshot; texto en español; **si había diseño de referencia, cada página verificada lado a lado contra él y coincidiendo**.
+❌ Scaffoldear un frontend a mano en vez de clonar BaseFrontend; entregar pantallas sueltas por épica; **entregar una galería de screenshots (`propuestas-visuales.html`) en vez de la app real**; HTML que finja usar el kit; usar Next.js; saltar la verificación en navegador; **declarar fidelidad sin comparar lado a lado contra el diseño de referencia renderizado** (o diseñar contra una descripción textual); **dejar sin importar los tokens `var(--…)` del diseño de referencia** (componentes custom sin estilo); replicar solo la pantalla inicial cuando la referencia tiene más pantallas.

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

@@ -0,0 +1,96 @@
+---
+name: 'step-06-handoff'
+description: 'Empaqueta las propuestas visuales para los diseñadores (índice + app autocontenida en UN HTML + trazabilidad) y commitea la fase'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-06-handoff.md'
+
+proposalIndexTemplate: '{workflow_path}/templates/proposal-index.md'
+# Entregable consolidado = la app real en UN HTML autocontenido (propuesta-app.html),
+# generada en step-05 §3 (vite-plugin-singlefile + hash routing). NO una galería de screenshots.
+wds_validate: '{project-root}/_siesa-agents/wds/scripts/wds-validate.js'
+phase2: '{project-root}/_siesa-agents/scripts/phases/phase2.js'
+---
+
+# Step 6: Empaquetado, Handoff y Commit
+
+## STEP GOAL
+
+Dejar las propuestas visuales listas para el equipo de diseño: un índice navegable con trazabilidad (`proposal-index.md`), la **app real compilada en UN HTML autocontenido** (`propuesta-app.html`, generada en step-05 §3), validación final, y el commit de fase. 🔴 El visor consolidado es la app funcional, NO una galería de screenshots.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first
+- ✅ Speak in `{communication_language}`
+
+## EXECUTION SEQUENCE
+
+### 1. Final Validation
+
+```bash
+node {wds_validate} --all --output {design_artifacts}
+```
+
+Must be 0 errors. Fix any remaining before continuing.
+
+### 2. Build the Proposal Index
+
+Using `{proposalIndexTemplate}`, create `{design_artifacts}/proposal-index.md` with:
+- Instrucción destacada para abrir la **app clonada de BaseFrontend** interactiva: `cd {design_artifacts}/_kit-playground && npm run dev` (puerto 3010), y enlace a la **app autocontenida** `propuesta-app.html` (un solo HTML, doble clic, sin servidor) para revisión rápida.
+- Por escenario/página: ruta del **módulo/página** correspondiente en la app (`/clientes`, `/contactos`, …) y su screenshot, no un HTML por épica.
+- Nombre de la página + enlace a su page-spec
+- Miniatura/enlace al screenshot real (`sketches/<page>-real.png`)
+- Componentes siesa-ui-kit usados
+- Trazabilidad `[Source: <Épica>/<Historia>/FR-x]`
+- Preguntas de diseño abiertas (del design log)
+
+This index is the single entry point a designer opens.
+
+### 2b. Consolidated viewers
+
+Dos formas de ver las propuestas (ambas son **la app real**, no screenshots):
+
+1. **App interactiva** = el clon de BaseFrontend en `{design_artifacts}/_kit-playground` → `npm run dev` (puerto 3010). Navegable de punta a punta por el rail (`LayoutBase`), con estado compartido y flujos conectados. Es la fuente viva.
+2. **`{design_artifacts}/propuesta-app.html`** — **la app compilada en UN HTML autocontenido** (JS+CSS inline + hash routing), generada en step-05 §3. Abre por doble clic, sin servidor: es la MISMA app funcional (navegación, CRUD, asociación en memoria) empaquetada para compartir/revisar sin instalar nada. 🔴 NO es una galería de imágenes.
+
+Ambos complementan al `proposal-index.md` (el índice con specs/trazabilidad).
+
+### 3. Present to Designer (HALT)
+
+```
+🎨 Propuestas visuales listas.
+- Escenarios: {n}   - Páginas: {n}
+- App interactiva (clon BaseFrontend): cd {design_artifacts}/_kit-playground && npm run dev  (:3010)
+- Índice: {design_artifacts}/proposal-index.md
+- App autocontenida (un HTML, doble clic): {design_artifacts}/propuesta-app.html
+
+¿Cómo seguimos?
+[D] Entregar al diseño (solo commitear) — recomendado
+[I] Iterar sobre alguna página antes de cerrar
+```
+
+HALT and wait.
+
+### 4. Update State
+
+Mark phases 3–4 complete in `{design_artifacts}/_progress/wds-project-outline.yaml` and update `_progress/00-design-log.md`.
+
+### 5. Phase Commit (per workflow_ext.md §5)
+
+```bash
+git status --short
+git diff --stat
+node {phase2} --commit "[Phase 2 - Planning] add WDS visual proposals for {project_name}"
+```
+
+Confirm:
+> `✅ Propuestas visuales WDS committeadas en la rama Phase 2 (planning).`
+
+**This is the LAST action. Do not continue after the commit.**
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Validación 0 errores; proposal-index.md con trazabilidad; **`propuesta-app.html` generada (la app real en un solo HTML autocontenido)**; estado WDS actualizado; commit de fase hecho.
+❌ Entregar sin índice; índice sin trazabilidad; **entregar una galería de screenshots en vez de la app autocontenida `propuesta-app.html`**; olvidar el commit de fase.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/templates/product-brief-bridge.md

@@ -0,0 +1,68 @@
+---
+type: wds-product-brief
+status: bridged-from-planning
+source: siesa-planning-bridge
+generated_date: ""
+source_files: []
+stepsCompleted: []
+---
+
+# Product Brief — {{project_name}}
+
+> Documento generado por el workflow `wds-visual-proposals` a partir de los artefactos de planning existentes. Es el prerequisito de Fase 1 que Freya (WDS) valida antes de diseñar. Cada sección referencia su fuente con `[Source: ...]`.
+
+## 1. Vision (WHY)
+
+{{vision}}
+
+[Source: {{prd_source}}]
+
+## 2. Golden Circle
+
+- **WHY** — {{why}}
+- **HOW** — {{how}}
+- **WHAT** — {{what}}
+
+## 3. Target Users
+
+{{target_users}}
+
+[Source: {{prd_users_source}}]
+
+## 4. Business Goals & KPIs
+
+| Objetivo | Métrica / KPI |
+|---|---|
+| {{goal_1}} | {{kpi_1}} |
+
+[Source: {{prd_goals_source}}]
+
+## 5. Scope & Constraints
+
+- **En alcance:** {{in_scope}}
+- **Fuera de alcance:** {{out_of_scope}}
+- **Restricciones técnicas:** {{tech_constraints}}
+
+[Source: {{architecture_source}}]
+
+## 6. Content Language & Tone
+
+- **Idioma de UI:** Español (obligatorio)
+- **Tono:** {{tone}}
+
+## 7. Visual Direction (resumen)
+
+- **Color primario:** `#0e79fd` (siesa-ui-kit) {{color_overrides}}
+- **Tipografía:** Inter
+- **Sistema de componentes:** siesa-ui-kit primero
+- Detalle completo en `A-Product-Brief/visual-direction.md`
+
+[Source: ux-design-specification.md]
+
+## 8. Asunciones a confirmar
+
+{{assumptions}}
+
+---
+
+_Provenance: este brief NO contiene contenido inventado; deriva de los archivos listados en `source_files`._

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/templates/proposal-index.md

@@ -0,0 +1,46 @@
+---
+type: wds-proposal-index
+project: "{{project_name}}"
+generated_date: ""
+siesa_uikit_package: ""
+---
+
+# Propuestas Visuales — {{project_name}}
+
+> Punto de entrada para el equipo de diseño. Cada página enlaza su especificación WDS, su ruta en la app y su screenshot, con trazabilidad al planning de origen.
+
+**App interactiva (clon BaseFrontend):** `cd _kit-playground && npm run dev` (:3010)  ·  **App autocontenida (un HTML, doble clic):** [`propuesta-app.html`](propuesta-app.html)  ·  **Paquete siesa-ui-kit:** {{siesa_uikit_package}}
+
+---
+
+## Resumen
+
+| Escenario | Páginas | Origen (Épica) |
+|---|---|---|
+| {{scenario_1}} | {{scenario_1_pages}} | {{scenario_1_epic}} |
+
+---
+
+## Detalle por escenario
+
+### {{scenario_1}}
+
+[Source: {{scenario_1_epic}}]
+
+| # | Página | Spec | Prototipo | Screenshot | Componentes siesa-ui-kit | Origen |
+|---|---|---|---|---|---|---|
+| 01 | {{page_name}} | [spec]({{page_spec_path}}) | [ver]({{page_prototype_path}}) | ![]({{page_screenshot_path}}) | {{page_components}} | [Source: {{page_source}}] |
+
+---
+
+## Preguntas de diseño abiertas
+
+{{open_questions}}
+
+---
+
+## Cómo revisar
+
+1. Corre `cd _kit-playground && npm run dev` (:3010) y navega por el rail entre módulos, o abre `propuesta-app.html` (doble clic) — la app real en un solo HTML autocontenido.
+2. Compara contra la page-spec (texto en español, componentes siesa-ui-kit).
+3. Deja feedback cualitativo; el workflow puede iterar página por página (`/wds-visual-proposals` → reanudar → iterar).

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/templates/trigger-map-bridge.md

@@ -0,0 +1,54 @@
+---
+type: wds-trigger-map
+status: bridged-from-planning
+source: siesa-planning-bridge
+generated_date: ""
+source_files: []
+stepsCompleted: []
+---
+
+# Trigger Map — {{project_name}}
+
+> Prerequisito de Fase 2 (WDS) generado desde el PRD + épicas. Mapea la psicología del usuario a los objetivos de negocio. Es lo que Freya usa para crear escenarios.
+
+## Personas
+
+> Una persona por archivo: `B-Trigger-Map/NN-persona-<nombre>-<arquetipo>.md`. Nombres aliterados (ej. "Carla la Cajera"). Aquí va el resumen.
+
+| Persona | Arquetipo | Awareness stage | Archivo |
+|---|---|---|---|
+| {{persona_1_name}} | {{persona_1_archetype}} | {{persona_1_awareness}} | {{persona_1_file}} |
+
+## Driving Forces (por persona)
+
+### {{persona_1_name}}
+
+**Fuerzas positivas** (deseos, aspiraciones):
+- {{positive_1}}
+
+**Fuerzas negativas** (miedos, frustraciones):
+- {{negative_1}}
+
+[Source: {{prd_pains_gains_source}}]
+
+## Business Goals ↔ Triggers
+
+| Objetivo de negocio | Trigger del usuario | Persona |
+|---|---|---|
+| {{biz_goal_1}} | {{trigger_1}} | {{persona_ref_1}} |
+
+[Source: {{prd_goals_source}}]
+
+## Feature Impact
+
+> Detalle completo en `B-Trigger-Map/feature-impact.md` (épica/feature × persona × driving force).
+
+| Épica / Feature | Persona | Driving force | Impacto |
+|---|---|---|---|
+| {{feature_1}} | {{persona_ref}} | {{force}} | {{impact}} |
+
+[Source: {{epics_source}}]
+
+---
+
+_Provenance: derivado de los archivos en `source_files`. Marcar `⚠️ [Asunción — confirmar]` donde el planning no lo especifica._

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/workflow.md

@@ -0,0 +1,82 @@
+---
+name: wds-visual-proposals
+description: Toma los artefactos de planning ya existentes (PRD, épicas/historias, UX spec, arquitectura) y los usa como base para que el módulo WDS (Freya) genere propuestas visuales — escenarios UX, page-specs y prototipos renderizados con siesa-ui-kit — ayudando a los diseñadores.
+web_bundle: true
+---
+
+# WDS Visual Proposals — Del Planning a las Propuestas Visuales
+
+**Goal:** Tomar los artefactos de planning ya hechos del proyecto (PRD, épicas/historias, `ux-design-specification.md`, arquitectura) como **base**, traducirlos a la fundación estratégica que el módulo **WDS** necesita, y dirigir a **Freya** para producir **propuestas visuales**: escenarios UX + page-specs (formato WDS) **y** prototipos renderizados con los componentes reales de **siesa-ui-kit**. El resultado ayuda al equipo de diseño a iterar sobre algo tangible en vez de partir de cero.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a **UX Bridge Engineer + Design Facilitator** collaborating with the **Design Team and Product Owners**. This is a partnership, not a client-vendor relationship. You bring expertise in translating product requirements into WDS-compatible design foundations and in driving the WDS/Freya design loop with siesa-ui-kit fidelity, while the user brings product knowledge and design judgment. Work together as equals.
+
+---
+
+## RELACIÓN CON EL MÓDULO WDS
+
+Este workflow es un **adaptador + director**. NO reimplementa el diseño: reutiliza el módulo WDS instalado en `{project-root}/_siesa-agents/wds/`.
+
+- **Puente (Phases 0–2 de WDS):** sintetiza los prerequisitos que Freya exige —`A-Product-Brief/product-brief.md`, `B-Trigger-Map/trigger-map.md`, outline de escenarios y `_progress/wds-project-outline.yaml`— a partir de los artefactos de planning de SIESA. Sin este puente, Freya no puede empezar.
+- **Kit Warm-up (step-02b, anti-alucinación):** antes de diseñar, instala/usa el paquete **real** de siesa-ui-kit, lo compila/renderiza y produce `kit-grounding.md` (nombres/props reales). Es la fuente de verdad que consumen las specs y los prototipos.
+- **Diseño (Phases 3–4 de WDS):** usa los scripts scaffold de WDS (`_siesa-agents/wds/scripts/*.js`) para crear escenarios y page-specs, y el design loop de Freya (`_siesa-agents/wds/data/agent-guides/freya/`) para renderizar y verificar prototipos.
+- **siesa-ui-kit primero:** todo objeto UI se mapea contra `kit-grounding.md` (verdad del paquete) y el catálogo `https://siesa-ui-kit.pages.dev/llms.txt`. Si discrepan, **gana el grounding**. Texto de UI siempre en **español**.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in the WDS project outline (`_progress/wds-project-outline.yaml`) and design log; use `stepsCompleted` array in any output document frontmatter
+- **Append-Only Building**: Build documents by appending content as directed; never overwrite existing WDS artifacts blindly
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update the project outline / design log before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update state when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- 🧩 **NEVER** write raw WDS markdown by hand — use the scaffold scripts (`wds-init-scenario.js`, `wds-init-page.js`, `wds-add-object.js`, `wds-add-spacing.js`, `wds-nav.js`) and validate with `wds-validate.js`
+- 🇪🇸 **ALWAYS** write user-facing UI text in **Spanish**; **ALWAYS** check siesa-ui-kit FIRST before proposing any custom component
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+- `planning_artifacts`, `implementation_artifacts`, `project_knowledge`
+
+Then load `{project-root}/_siesa-agents/wds/config.yaml` and resolve:
+
+- `design_artifacts` (base path where WDS artifacts live — scripts write `C-UX-Scenarios/` under it)
+- `output_folder` (WDS `_bmad-output` base), `communication_language`, `document_output_language`
+
+If the two configs disagree on a value, **WDS `config.yaml` wins** for any WDS artifact path; otherwise use `_bmad/bmm/config.yaml`.
+
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-01-init.md` to begin the workflow.