siesa-agents 2.1.90 → 2.1.91

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

@@ -0,0 +1,195 @@
+# MANDATORY RULES: WDS-VISUAL-PROPOSALS WORKFLOW
+
+These Siesa-specific rules are injected into memory BEFORE the base workflow runs and remain active throughout. They are non-negotiable.
+
+---
+
+## 1. MANDATORY RULE — PHASE BRANCH CREATION AT WORKFLOW START
+
+**TRIGGER:** Immediately when the user initiates this workflow (e.g., `/wds-visual-proposals`).
+
+**CRITICAL INSTRUCTION:** Before executing any workflow step, you MUST invoke the `generate-commits-by-phase` skill to create the **Phase 2 (planning)** branch. Visual proposals are a planning-phase activity.
+
+### EXECUTION STEPS (PERFORM THESE ACTIONS NOW, BEFORE ANYTHING ELSE)
+
+**STEP 1: INVOKE THE SKILL — CREATE PHASE 2 BRANCH**
+
+```bash
+node _siesa-agents/scripts/phases/phase2.js
+```
+
+- If the `planning` branch already exists, the script will report it — continue normally.
+- If it is created successfully, confirm to the user and proceed.
+
+**STEP 2: CONFIRM AND CONTINUE**
+
+Output to the user:
+> `✅ Rama Phase 2 (planning) lista. Procediendo con la generación de propuestas visuales WDS...`
+
+**DO NOT proceed to the workflow steps until this rule is fully executed.**
+
+---
+
+## 2. CONTEXT AND STANDARDS SETUP
+
+Establish the following context paths for use throughout all steps:
+
+- `company_standards_path` = `{project-root}/_siesa-agents/bmm/workflows/3-solutioning/create-architecture/data/company-standards`
+- `wds_module_path` = `{project-root}/_siesa-agents/wds`
+- `wds_scripts_path` = `{wds_module_path}/scripts`
+- `siesa_uikit_catalog_url` = `https://siesa-ui-kit.pages.dev/llms.txt`
+- `base_ux_spec` = `{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md`
+- `frontend_base_repo` = `https://github.com/SiesaTeams/BaseFrontend`
+- `frontend_dir` = `{design_artifacts}/_kit-playground` (el harness del frontend ES un clon de `frontend_base_repo`)
+
+### Company Standards Integration
+
+🔴 **CRITICAL**: Load these before producing any spec or prototype:
+- `{company_standards_path}/frontend-standards.md` — **siesa-ui-kit** rules + component strategy
+- `{company_standards_path}/technical-preferences-ux.md` — UX/UI preferences and patterns
+
+| Priority | Rule | Why Critical |
+|----------|------|--------------|
+| 🔴 P0 | **siesa-ui-kit obligatorio** | Check siesa-ui-kit (via `{siesa_uikit_catalog_url}`) before proposing ANY component |
+| 🔴 P0 | **UI text in Spanish** | All user-facing text MUST be in Spanish |
+| 🔴 P0 | **Vite over Next.js** | Any rendered prototype harness uses Vite + React + Tailwind v4, never Next.js |
+| 🔴 P0 | **Fidelidad al diseño de referencia** | Si el usuario entregó un diseño a seguir (mockup HTML, imagen, Figma), **renderízalo** y replícalo; su look manda sobre los defaults del kit y se **verifica lado a lado** (ver §3C) |
+| 🟡 P1 | Design tokens | Use the tokens defined in `{base_ux_spec}` and the project `ux-design-specification.md` |
+
+---
+
+## 3. SIESA-UI-KIT MANDATORY CHECK (applies to step-04 and step-05)
+
+**BEFORE mapping any object to a component or rendering any prototype, you MUST:**
+
+1. Fetch the live catalog from `{siesa_uikit_catalog_url}` (authoritative source of available components).
+2. Resolve the **actual installed package name** by reading the target frontend app's `package.json` — do NOT assume `@siesa/ui-kit`. `llms.txt` does not declare the npm name.
+3. Follow the Component Decision Protocol:
+
+```
+Component needed  →  ¿Está en siesa-ui-kit (per llms.txt / kit-grounding.md)?
+   ├── YES → USA el componente siesa-ui-kit tal cual
+   └── NO  → busca en shadcn (registro MCP de shadcn)
+              ├── existe     → usa el componente shadcn
+              └── no existe  → el agente lo CREA (compone primitivos + tokens de marca)
+   (AUTOMÁTICO — no preguntar al usuario; registrar la decisión kit/shadcn/custom en el design log.)
+```
+
+4. Prefer siesa-ui-kit **view-level** components when they fit the page (e.g. `LoginView`, `SignUpView`, `RecoverPasswordView`, `Dashboard`, `LayoutBase`, `ProductsView`, `MasterCrud`) — they raise fidelity and reduce effort.
+
+### UI Text Language Rule
+
+🔴 **MANDATORY**: All user-facing text MUST be in Spanish.
+- ✅ "Guardar", "Cancelar", "Enviar", "Nombre de usuario", "Datos guardados correctamente"
+- ❌ "Save", "Cancel", mixed "Save cambios"
+
+> **Note on the bilingual scaffold:** the WDS scripts (`wds-add-object.js`) expose `--se` (Swedish) and `--en` (English) fields. For Siesa, put the **Spanish** UI string in `--se` (primary product language) and the English reference in `--en`. Spanish is the language the prototype renders.
+
+---
+
+## 3A. MANDATORY RULE — CLONA Y TRABAJA BAJO BaseFrontend
+
+**TRIGGER:** En step-02b (Kit Warm-up), al montar el harness del frontend, y durante todo step-05.
+
+🔴 **CRITICAL:** El frontend NO se scaffoldea a mano. Se **clona el repositorio base oficial** `{frontend_base_repo}` en `{frontend_dir}` y se trabaja **dentro de él**. Ese repo ya trae Vite 6 + React 19 + TS + Tailwind v4 + `siesa-ui-kit@^1.0.109` con TODOS los peers instalados, TanStack Router (file-based), Clean Architecture por módulos, capa mock en memoria y un shell (`LayoutBase`) ya cableado. No reinventar nada de eso.
+
+```bash
+git clone --depth 1 {frontend_base_repo} {frontend_dir}
+rm -rf {frontend_dir}/.git   # el clon vive DENTRO del repo SIESA; no anidar .git
+cd {frontend_dir} && npm install
+```
+
+- **`.git` fuera:** tras clonar, borra `{frontend_dir}/.git` para que los fuentes queden versionados por el repo SIESA padre (no como submódulo). `node_modules/` ya está en el `.gitignore` del propio base.
+- **Ejecución:** el prototipo se ve con `npm run dev` (modo standalone, **puerto 3010**, todos los permisos activos, datos en memoria mock). NUNCA Next.js.
+- **Convenciones del base (respétalas, no las reescribas):**
+  - **Shell = `_app.tsx`** → usa `LayoutBase` de siesa-ui-kit con `navigationItems` de `src/config/navigation.tsx` + `<Outlet/>`. Este ES el shell persistente; no hay que construir Navbar/rail a mano.
+  - **Un módulo por dominio** en `src/modules/<dominio>/` con las 4 capas `domain / application / infrastructure / presentation` (copia el patrón de los módulos de ejemplo `agentes` y `colaboradores`, que luego se reemplazan).
+  - **Listado + CRUD** → componente `MasterCrud` dirigido por un array `fields` (accessorKey/header/type/config) + un `service` que implementa `CrudService<T>` + schema Zod. No coloques objetos a mano cuando `MasterCrud` cubre la pantalla.
+  - **Estado compartido = capa mock** (`src/lib/mock/*.mock.ts`): BD en memoria por entidad. Los flujos conectados entre módulos (eliminar padre → hijos huérfanos, asociar/reasignar reflejado en ambos, enlaces cruzados) se implementan sobre estos stores.
+  - **Rutas** = TanStack Router file-based: una ruta por módulo en `src/routes/_app/<modulo>.tsx` + su ítem en `config/navigation.tsx`. `routeTree.gen.ts` se autogenera (no editar).
+
+---
+
+## 3B. MANDATORY RULE — KIT WARM-UP GROUNDING BEFORE DESIGN
+
+**TRIGGER:** After the strategic bridge (step-02) and BEFORE generating scenarios/specs (step-03+).
+
+🔴 **CRITICAL:** El agente NO debe diseñar contra el catálogo `llms.txt` solo. Debe ejecutar **step-02b (Kit Warm-up)**: clonar BaseFrontend (§3A), instalarlo, verificar con `npm run build`/render que el paquete **real** de siesa-ui-kit compila, y producir `{frontend_dir}/kit-grounding.md` con nombres y props **reales**.
+
+- **Source of truth:** cuando `kit-grounding.md` y el catálogo discrepan, **gana el grounding** (usa el export real: p. ej. `ContentLayout` no `LayoutContent`; no inventes `Dashboard`/`StatCard` → compón con `Card`). BaseFrontend ya usa `LayoutBase` y `MasterCrud` con contratos reales — documéntalos en el grounding.
+- **No silent skip:** si no se puede clonar/instalar (sin red/registro), `kit-grounding.md` se escribe igual desde el catálogo pero marcado `⚠️ NO VERIFICADO EN RUNTIME`.
+- **Spec Sync (feedback obligatorio):** todo hallazgo del warm-up que invalide un supuesto del `ux-design-specification.md` (nombre/contrato inexistente) debe reflejarse en una sección "Kit Grounding — Spec Sync" del spec en el mismo ciclo.
+
+🔴 **ENTREGABLE = LA APP CLONADA (BaseFrontend) INTEGRADA, NO pantallas sueltas.** Step-05 trabaja **dentro de `{frontend_dir}`**: reemplaza los módulos de ejemplo por **un módulo por dominio** del alcance, siguiendo las convenciones del base (shell `LayoutBase`, `MasterCrud` data-driven, stores mock compartidos, rutas + nav). Resultado: una app navegable de punta a punta con `npm run dev`, **estado compartido** entre módulos y **flujos conectados** (eliminar padre → hijos huérfanos; asociar/reasignar refleja en ambos; enlaces cruzados navegables). Las épicas de relación se integran DENTRO de los módulos que relacionan; la épica de shell YA es el shell del base. **Prohibido** entregar un prototipo aislado por épica, y **prohibido** HTML+CSS que se auto-rotule como si usara el kit (`<div class="rail" title="NavigationRail">`, `/* siesa-ui-kit Button */`) — esa es la alucinación que este flujo elimina. Todo con componentes reales, `npm run build` exit 0. **Entregable estático = la app compilada en UN HTML autocontenido (`propuesta-app.html`, vía vite-plugin-singlefile + hash routing), NO una galería de screenshots** (los screenshots son solo verificación interna del agente). Gotchas obligatorios (el base ya resuelve varios): `ContentLayout` = master-detail (no header); `GenericEntityModal`/`ContactManager` requieren `QueryClientProvider` (el base ya lo provee en `config/query-client.ts`); `LookupField` requiere `fetcher` mock.
+
+---
+
+## 3C. MANDATORY RULE — REFERENCE DESIGN FIDELITY (cuando el usuario entrega un diseño a seguir)
+
+**TRIGGER:** El usuario aportó, en cualquier punto del flujo, un **diseño de referencia** que la propuesta debe replicar: un mockup HTML (incluidos los HTML autocontenidos/"bundled" que se auto-desempaquetan), una imagen (PNG/JPG), un PDF de pantallas, o un enlace de Figma. step-01 lo detecta e ingesta; step-05 lo replica; **esta regla aplica durante todo el flujo.**
+
+🔴 **Regla de oro: NO se diseña contra una descripción textual del diseño — se diseña contra el diseño RENDERIZADO.** El fallo que esta regla previene es construir "de memoria"/desde texto y declarar fidelidad sin haber visto nunca el diseño real.
+
+### A. Renderizar el diseño de referencia a imágenes (obligatorio antes de diseñar)
+
+Convierte el diseño a screenshots que sean la **verdad visual** (guárdalos en `{design_artifacts}/_design-ref/`):
+
+- **Imagen/PDF** → úsala directamente (o exporta cada página del PDF a PNG).
+- **HTML autocontenido/bundled** (abre por sí solo, p. ej. un export con assets en base64) → renderízalo en **Chrome headless**:
+  `chrome --headless=new --disable-gpu --hide-scrollbars --window-size=1600,1050 --virtual-time-budget=8000 --screenshot=<out.png> "file:///<ruta-del-html>"`.
+  Dale tiempo (`--virtual-time-budget`) si el HTML se desempaqueta/renderiza vía JS.
+- **HTML interactivo / multi-pantalla** (la pantalla objetivo se alcanza haciendo clic, p. ej. "Crear/Editar") → **NO basta la pantalla inicial**: conduce el Chrome instalado con `puppeteer-core` (`npm i puppeteer-core`, `executablePath` = Chrome local), navega/haz clic hacia cada estado (lista, crear, editar, diálogos) y captura **un screenshot por pantalla**.
+- **Figma/URL** → exporta los frames a PNG (o pide al usuario los PNG exportados). Si no hay acceso, avísalo y trabaja con lo que haya.
+
+Registra las referencias en `_progress/wds-project-outline.yaml` (`reference_design: [rutas]`) y en el design log.
+
+### B. Extraer sus tokens (gotcha que deja todo sin estilo)
+
+Si el diseño define tokens como custom properties CSS (`:root { --surface-card: …; --space-4: …; --radius-xl: …; --text-sm: … }`), **cópialos al harness** (`{kit_playground}/src/styles/tokens.css`, importado desde `src/index.css`) **antes** de escribir componentes custom. Los componentes que referencian `var(--…)` sin esas definiciones renderizan **colapsados/sin estilo** (flex/gap 0, sin fondos ni bordes) — `siesa-ui-kit/styles.css` define SUS tokens, no los del diseño de referencia.
+
+### C. Precedencia de fidelidad (el diseño manda sobre los defaults del kit)
+
+siesa-ui-kit primero **sigue vigente para primitivos** (`Input`, `Textarea`, `Select`, `Switch`, `Badge`, `Button`, `LookupField`, `Table`). Pero los **componentes de vista** (`MasterCrud`, `LayoutBase`, etc.) imponen un look que **puede no parecerse en nada** al diseño de referencia (p. ej. el diseño usa barra superior sin rail y una tabla limpia con pills de color, no el toolbar por defecto de `MasterCrud`). Cuando el default del kit diverge del diseño: **compón la presentación a medida para igualar el diseño**, importando primitivos del kit donde encajen. La fidelidad al diseño entregado por el usuario tiene prioridad sobre "usar el componente de vista del kit". Registra kit/custom en el design log.
+
+### D. Verificación lado a lado (antes de declarar "listo")
+
+Para CADA página del alcance: renderiza tu build y ponlo **al lado del screenshot de referencia**; solo pasa si coinciden **layout, colores, espaciado, tipografía y componentes**. 🚫 **PROHIBIDO declarar fidelidad** contra tu propio modelo mental, contra una descripción textual, o contra la pantalla inicial cuando la referencia tiene más pantallas. Si no coincide, corrige e itera antes de presentar.
+
+---
+
+## 4. PATH RECONCILIATION (WDS docs are internally inconsistent)
+
+WDS docs disagree on output paths. Resolve at runtime in this order:
+
+1. Read `{wds_module_path}/config.yaml`. Use its `design_artifacts` value as the **base output path** for all WDS scaffold scripts (`--output <design_artifacts>`). Scripts create `C-UX-Scenarios/` under it.
+2. Place the bridge artifacts as Freya's activation expects them, relative to that base:
+   - `{design_artifacts}/A-Product-Brief/product-brief.md`
+   - `{design_artifacts}/B-Trigger-Map/trigger-map.md` (+ personas)
+   - `{design_artifacts}/C-UX-Scenarios/` (scenarios + page specs)
+   - `{design_artifacts}/_progress/wds-project-outline.yaml` and `_progress/00-design-log.md`
+3. NEVER hardcode `_bmad-output` vs `design-artifacts`. Always derive from `config.yaml`.
+
+---
+
+## 5. MANDATORY RULE — PHASE COMMIT AT WORKFLOW END
+
+**TRIGGER:** Immediately after the visual proposals (specs + prototype + index) are generated and saved (end of step-06).
+
+**STEP 1: INSPECT CHANGES**
+1. `git status --short`
+2. `git diff --stat`
+
+**STEP 2: GENERATE COMMIT MESSAGE**
+Format: `[Phase 2 - Planning] <brief description>` — e.g. `[Phase 2 - Planning] add WDS visual proposals for <project name>`. Write it in `{communication_language}`.
+
+**STEP 3: INVOKE THE SKILL — COMMIT PHASE 2 CHANGES**
+
+```bash
+node _siesa-agents/scripts/phases/phase2.js --commit "<generated commit message>"
+```
+
+**STEP 4: CONFIRM COMPLETION**
+Output to the user:
+> `✅ Propuestas visuales WDS committeadas en la rama Phase 2 (planning).`
+
+**This is the LAST action of the workflow. Do not execute any further steps after this commit.**

package/siesa-agents/wds/config.yaml

@@ -0,0 +1,20 @@
+# WDS Module Configuration
+# Generated by BMAD installer
+# Version: 6.9.0
+# Date: 2026-06-25T17:13:35.737Z
+
+project_knowledge: "{project-root}/docs"
+project_type: digital_product
+design_artifacts: "{project-root}/design-artifacts"
+design_system_mode: none
+methodology_version: wds-v6
+product_languages:
+  - en
+design_experience: intermediate
+
+# Core Configuration Values
+user_name: Ssancheze
+project_name: Dev
+communication_language: Spanish
+document_output_language: English
+output_folder: "{project-root}/_bmad-output"

package/siesa-agents/wds/data/agent-contracts.md

@@ -0,0 +1,72 @@
+# WDS Agent Contracts
+
+Defines what each agent owns, what they explicitly do not own, and how they hand off to each other.
+All agents load this file at activation. These rules are non-negotiable.
+
+---
+
+## Domain Boundaries
+
+| Agent | Owns | Does NOT own |
+|-------|------|--------------|
+| **Saga** | Phases 0–2: Alignment, Product Brief, Trigger Mapping | Any design work. Any code. Scenarios (Phase 3+). |
+| **Freya** | Phases 3–4: UX Scenarios, UX Design. Phases 6–7: Asset Generation, Design System. | Discovery (Phases 1–2). Any code. PRDs. |
+| **Mimir** | Phase 5: Tech Audit, PRD, Build. Phase 8: Product Evolution. | Discovery. Design. Writing specs without a Work Order. |
+
+**If a user asks an agent to do work outside its domain:** name the right agent and offer to hand off. Never attempt the work yourself.
+
+---
+
+## Prerequisites
+
+Each agent requires the following before starting core work:
+
+| Agent | Required | Blocks |
+|-------|----------|--------|
+| Saga | Nothing | — |
+| Freya | `A-Product-Brief/product-brief.md` + `B-Trigger-Map/00-trigger-map.md` | Cannot design without strategic foundation |
+| Mimir | At least one Work Order from Freya | Cannot build without a WO. Cannot PRD without a WO. |
+| Mimir (existing codebase) | `E-Development/000-tech-audit.md` | Cannot PRD without knowing the codebase |
+
+---
+
+## Handoff Rules
+
+**Saga → Freya**
+Trigger: Product Brief and Trigger Map are complete and aligned.
+Action: Saga runs `/wrap freya`. Freya picks up with `/freya progress/freya.md`.
+Never: Saga does not write scenarios or design anything before handing off.
+
+**Freya → Mimir**
+Trigger: Work Order written, page spec complete, ready for implementation.
+Action: Freya runs `/wrap mimir` or `/handoff mimir`. Mimir picks up the Work Order.
+Never: Freya does not write code. Freya does not write PRDs.
+
+**Mimir → Freya**
+Trigger: Implementation complete, browser-verified. Or: blocked on design decision.
+Action: Mimir runs `/handoff freya` with the specific question or completion note.
+Never: Mimir does not modify specs or Work Orders. He implements what they say.
+
+---
+
+## Quality Rules (all agents)
+
+- **One task at a time.** Complete and verify before moving on.
+- **No plausible-looking wrong output.** If you cannot follow the template exactly, stop and say so. Wrong-but-plausible output breaks every downstream phase.
+- **Read the template before writing.** Every artifact has a template. Load it, follow it.
+- **Decisions are documented.** Any deviation from a template or unexpected choice goes in the design log.
+
+---
+
+## Out-of-Scope (explicit)
+
+Things no WDS agent does, ever:
+
+- Produce output in a custom format when a WDS template exists
+- Write to `progress/` without going through the memory tool
+- Commit without a meaningful message (conventional commits required)
+- Force push, skip hooks, or bypass git safety
+- Start a new phase without the prerequisite documents
+- Write code without a PRD (Mimir only)
+- Mark a requirement done without browser verification (Mimir only)
+- Design without a Trigger Map (Freya only)

package/siesa-agents/wds/data/agent-guides/freya/agentic-development.md

@@ -0,0 +1,223 @@
+# Freya's Agentic Development Guide
+
+**When to load:** When implementing features, building prototypes, or fixing bugs through structured development
+
+> **Note:** Agent dialogs have been replaced by the Design Log system. Use `_progress/00-design-log.md` for state tracking and `_progress/agent-experiences/` for session insights.
+
+---
+
+## Core Principle
+
+**Agentic Development builds incrementally with full traceability via the design log.**
+
+The design log bridges the gap between specifications and working code. Each step is self-contained, allowing fresh context while maintaining continuity.
+
+---
+
+## What is Agentic Development?
+
+Agentic Development is a **workflow approach** that produces various outputs:
+
+| Output Type | Description | When to Use |
+|-------------|-------------|-------------|
+| **Interactive Prototypes** | HTML prototypes that let users FEEL the design | Validating UX before production |
+| **Prototype Implementation** | Building features from specifications | Feature development |
+| **Bug Fixes** | Structured debugging and fixing | Issue resolution |
+| **Design Exploration** | Exploring visual/UX directions | Creative iteration |
+
+**Key Insight:** By structuring work with a design log and experience records, we create:
+- **Isolation** — Each step can run in a fresh context
+- **Traceability** — Clear record of what was planned and executed
+- **Replayability** — Instructions can be rerun if needed
+- **Handoff** — Different agents or humans can continue the work
+
+---
+
+## Agent Startup Protocol
+
+**When awakened, always check the design log:**
+
+```
+1. Read: {output_folder}/_progress/00-design-log.md
+2. Check Current and Backlog sections for:
+   - Items in progress
+   - Items ready to start
+3. Present current state to user
+```
+
+This ensures no captured work is forgotten.
+
+---
+
+## The Bridge Role
+
+The design log bridges **specifications** and **development**:
+
+```
+┌─────────────────────┐         ┌─────────────────────┐         ┌─────────────────────┐
+│   SPECIFICATION     │         │   DESIGN LOG        │         │   DEVELOPMENT       │
+│                     │         │                     │         │                     │
+│ • What to build     │────────▶│ • What's in scope   │────────▶│ • How to build      │
+│ • Object IDs        │         │ • Current/Backlog   │         │ • Code files        │
+│ • Requirements      │         │ • Traceability      │         │ • Components        │
+│ • Translations      │         │ • Progress tracking │         │ • Tests             │
+└─────────────────────┘         └─────────────────────┘         └─────────────────────┘
+     Single Source                   Navigation                    Implementation
+      of Truth                         Layer
+```
+
+**The specification is the single source of truth.** The design log does not duplicate spec content — it maps implementation tasks to spec sections via Object IDs.
+
+---
+
+## Progress Folder Structure
+
+```
+{output_folder}/_progress/
+├── 00-design-log.md                               ← Main state tracking
+└── agent-experiences/
+    ├── {DATE}-{agent}-{feature-name}.md            ← Session insights
+    └── ...
+```
+
+---
+
+## Feedback Protocol
+
+During implementation, classify and handle feedback naturally:
+
+| Type | What It Is | When to Address |
+|------|------------|-----------------|
+| **Bug/Issue** | Something broken or not working as expected | Now — iterate until fixed |
+| **Quick Adjustment** | Small tweak to current work | Now — implement immediately |
+| **Addition** | New requirement that fits current scope | Later step — add to plan |
+| **Change Request** | Outside current dialog scope | Future session — document in Change Requests |
+
+**Response Pattern:**
+1. **Classify** — Note what kind of feedback this is
+2. **Timing** — State when it should be addressed
+3. **Confirm** — For additions and change requests, confirm before proceeding
+4. **Execute** — Implement or document as appropriate
+
+---
+
+## Inline Testing
+
+**The agent tests its own work before presenting it to the user.**
+
+During agentic development, use Puppeteer to verify measurable criteria after each implementation step. This ensures the user only evaluates qualitative aspects (feel, clarity, hierarchy) rather than checking things the agent can measure.
+
+**Key rules:**
+
+1. **Verify before presenting** — After implementing a section, open the page with Puppeteer and check all measurable criteria
+2. **Narrate findings** — Use ✓/✗ marks with actual vs expected values
+3. **Fix before showing** — Never present with known measurable failures
+4. **Capture baselines** — Before modifying existing features, document current state with Puppeteer
+5. **Split test plans** — Story files divide criteria into agent-verifiable and user-evaluable
+
+**Responsibility split:**
+- **Agent handles:** Text content, colors, dimensions, touch targets, error states, visibility, state transitions
+- **Human handles:** Flow feel, visual hierarchy, user understanding, overall consistency
+
+**Full methodology:** `workflows/wds-4-ux-design/agentic-development/guides/INLINE-TESTING-GUIDE.md`
+
+---
+
+## Interactive Prototypes (Output Type)
+
+Interactive Prototypes are **one output** of Agentic Development.
+
+### Why HTML Prototypes?
+
+**Static Specs Can't Show:**
+- How it FEELS to interact
+- Where users get confused
+- What's missing in the flow
+- If the pacing feels right
+
+**HTML Prototypes Reveal:**
+- Interaction feels natural or awkward
+- Information appears when needed
+- Flow has logical gaps
+- Users understand next steps
+
+### Fidelity Levels
+
+| Level | Focus | Use When |
+|-------|-------|----------|
+| **Wireframe** | Information architecture | Testing flow logic only |
+| **Interactive** | User experience | Validating UX (standard) |
+| **Design System** | Component-based | Phase 5 enabled |
+
+### Prototype vs Production
+
+**Prototypes ARE:**
+- Thinking tools
+- Communication tools
+- Validation tools
+- Specification supplements
+
+**Prototypes are NOT:**
+- Production code
+- Pixel-perfect mockups
+- Final design
+
+---
+
+## Prototype Implementation (Output Type)
+
+Building features from specifications through structured dialog steps.
+
+### Step File Structure
+
+Each step links to specifications (doesn't duplicate):
+
+```markdown
+## Object ID Implementation Map
+
+| Object ID | Spec Section | Lines |
+|-----------|--------------|-------|
+| `booking-detail-header` | Drawer Header | L149-L158 |
+| `booking-detail-close` | Close Button | L159-L168 |
+```
+
+### Implementation Checklist Pattern
+
+For each Object ID:
+1. **Read** — Load the spec section
+2. **Implement** — Build to match spec
+3. **Verify (Puppeteer)** — Open in browser, check measurable criteria with ✓/✗ narration
+4. **Fix** — Resolve any mismatches before presenting to user
+
+---
+
+## Best Practices
+
+### Single Source of Truth
+- **Never duplicate spec content** — Link to spec sections with line numbers
+- **Object IDs are the contract** — Every implementation maps to an Object ID
+- **Spec changes update the spec** — Not the dialog or step files
+
+### Design Log
+- **Be thorough in Setup Context** — Assume zero prior knowledge
+- **Include file paths** — Always use absolute or project-relative paths
+- **Track progress** — Update the design log after each step
+
+### Execution
+- **Read spec first** — Before implementing any Object ID
+- **Fresh context is fine** — Steps are designed to work in isolation
+- **Update as you go** — Don't wait to update progress
+- **Capture discoveries** — Note spec changes or issues found
+
+---
+
+## Related Resources
+
+- **Design Log:** `{output_folder}/_progress/00-design-log.md`
+- **Agent Experiences:** `{output_folder}/_progress/agent-experiences/`
+- **Phase 4 UX Design:** `workflows/wds-4-ux-design/workflow.md`
+- **Inline Testing Guide:** `workflows/wds-5-agentic-development/guides/INLINE-TESTING-GUIDE.md`
+
+---
+
+*Build incrementally. Document thoroughly. Let users FEEL the design before committing to production.*