siesa-agents 2.1.78 → 2.1.80

package/siesa-agents/bmm/workflows/4-implementation/sprint-status/workflow_ext.md

@@ -36,7 +36,7 @@ Invocar `AskUserQuestion` con la siguiente configuración:
 ➡️ Encadenando con Retrospective tal como seleccionaste al inicio...
 ```
 
-Luego invocar `/bmad:bmm:workflows:retrospective`.
+Luego invocar `/bmad-retrospective `.
 
 ---
 

package/siesa-agents/bmm/workflows/5-documentation/README.md

@@ -0,0 +1,235 @@
+# 5-Documentation Phase - BMM Module
+
+**Phase:** Documentation
+**Module:** BMM (Build & Management Module)
+**Purpose:** Workflows for generating user documentation, API documentation, technical guides, and other end-user/developer documentation artifacts from project artifacts (PRDs, Epics, Architecture, Stories)
+
+---
+
+## Overview
+
+La fase **5-documentation** contiene workflows especializados en la generación de documentación técnica y de usuario a partir de artefactos de proyecto existentes. Estos workflows automatizan la creación de guías comprehensivas, asegurando consistencia, trazabilidad y calidad en la documentación producida.
+
+---
+
+## Workflows Disponibles
+
+### 📚 create-user-guide
+
+**Ruta:** `_siesa-agents/bmm/workflows/5-documentation/create-user-guide/`
+**Comando:** `/sa-create-user-guide`
+**Versión:** 1.0.0
+
+#### Descripción
+
+Genera guías de usuario en español desde features del proyecto (archivos individuales `prd/feature-*.md` + `epics/epic-*.md`), con diagramas Mermaid, screenshot placeholders y trazabilidad `[Source: FX Story Y.Z]`.
+
+#### Características Principales
+
+- ✅ **Salida en Español:** Archivo único por audiencia, actualizable con nuevos features
+- ✅ **Diagramas Mermaid:** Incluye diagramas para cada feature y workflow
+- ✅ **Screenshot Placeholders:** Sistema estructurado de placeholders con índice
+- ✅ **Trazabilidad:** Citaciones a épicas y stories de origen
+- ✅ **Continuación:** Soporte para resumir workflows interrumpidos
+- ✅ **Enfocado en Features:** Lee `prd/feature-*.md` + `epics/epic-*.md` por feature seleccionada
+
+#### Estructura de Archivos (15 archivos)
+
+```
+create-user-guide/
+├── workflow.md                              # Entry point del workflow
+├── workflow-plan-create-user-guide.md       # Documento de planificación
+│
+├── steps/                                   # 8 step files
+│   ├── step-01-init.md                     # Inicialización + detección continuación
+│   ├── step-01b-continue.md                # Reanudación de workflow
+│   ├── step-02-seleccion-epicas.md         # Selección de épicas (PRESCRIPTIVE)
+│   ├── step-03-analisis-fuentes.md         # Análisis de artefactos (INTENT-BASED)
+│   ├── step-04-elicitacion.md              # Elicitación de info (INTENT-BASED)
+│   ├── step-05-generacion-espanol.md       # Generación español (PRESCRIPTIVE)
+│   ├── step-06-traduccion-ingles.md        # Traducción inglés (PRESCRIPTIVE)
+│   └── step-07-validacion-guardado.md      # Validación final (PRESCRIPTIVE)
+│
+├── templates/                               # 2 templates bilingües
+│   ├── user-guide-template-es.md           # Template español con frontmatter
+│   └── user-guide-template-en.md           # Template inglés con frontmatter
+│
+└── data/                                    # 3 CSV data files
+    ├── audience-types.csv                  # 4 tipos de audiencia
+    ├── diagram-types.csv                   # 5 tipos de diagramas Mermaid
+    └── section-structure.csv               # 9 secciones de guía
+
+```
+
+#### Flujo del Workflow (8 pasos)
+
+1. **step-01-init** → Inicialización y configuración de audiencia
+   - Detecta workflows existentes
+   - Configura audiencia (enduser/admin/api/mixed)
+   - Crea documento inicial con frontmatter
+
+2. **step-01b-continue** → Continuación (si aplica)
+   - Carga estado guardado
+   - Resume desde último paso completado
+
+3. **step-02-seleccion-epicas** → Selección de Features
+   - Escanea `planning_artifacts/prd/feature-*.md`
+   - Usuario selecciona qué features documentar
+   - Verifica existencia de épica correspondiente por feature
+   - Registra selección en frontmatter (`features_selected`)
+
+4. **step-03-analisis-fuentes** → Análisis de Features
+   - Por cada feature: lee `prd/feature-*.md` (descripción, FRs, key behaviors)
+   - Si existe: lee `epics/epic-*.md` (historias, GWT, acceptance criteria)
+   - Lee contexto general (goals.md, background-context.md)
+   - Genera sección "Contexto del Proyecto"
+
+5. **step-04-elicitacion** → Elicitación de preferencias
+   - Conversación para capturar nivel técnico
+   - Escenarios adicionales
+   - Features a excluir
+
+6. **step-05-generacion-espanol** → Generación en español
+   - Genera 9 secciones completas
+   - Incluye diagramas Mermaid para cada feature
+   - Agrega screenshot placeholders
+   - Cita fuentes `[Source: FX Story Y.Z]`
+
+7. **step-06-traduccion-ingles** → ⛔ DESHABILITADO
+   - Paso conservado como referencia pero no se ejecuta
+   - El workflow salta directamente a step-07
+
+8. **step-07-validacion-guardado** → Validación y guardado
+   - Ejecuta TOP 5 validaciones
+   - Presenta resultados al usuario
+   - Permite loop a step-05 para correcciones
+   - Guarda ambas versiones + index.md
+
+#### Datos Estructurados
+
+**audience-types.csv** (4 tipos de audiencia)
+```csv
+audience_id,audience_name_es,audience_name_en,description_es,description_en,filename_prefix
+enduser,Usuarios Finales,End Users,...,enduser-guide
+admin,Administradores,Administrators,...,admin-guide
+api,Consumidores de API,API Consumers,...,api-guide
+mixed,Audiencia Mixta,Mixed Audience,...,complete-guide
+```
+
+**diagram-types.csv** (5 tipos de diagramas)
+```csv
+content_type,diagram_type,mermaid_syntax,use_case_es,use_case_en
+feature_overview,flowchart,"flowchart LR",...
+user_workflow,flowchart,"flowchart TD",...
+sequential_process,sequenceDiagram,...
+state_changes,stateDiagram-v2,...
+user_journey,journey,...
+```
+
+**section-structure.csv** (9 secciones)
+```csv
+section_id,section_name_es,section_name_en,description,required
+1,Introducción,Introduction,...,true
+2,Primeros Pasos,Getting Started,...,true
+3,Conceptos Clave,Core Concepts,...,true
+4,Funcionalidades,Features and How to Use Them,...,true
+5,Flujos de Trabajo,Common Workflows,...,true
+6,Solución de Problemas,Troubleshooting,...,false
+7,Preguntas Frecuentes,FAQ,...,true
+8,Glosario,Glossary,...,true
+9,Índice de Capturas,Screenshot Index,...,true
+```
+
+#### Criterios de Validación (TOP 5)
+
+1. **📄 Bilingual Output Completo** - Ambas versiones existen con estructura idéntica
+2. **🔗 Source Citations Obligatorias** - Cada feature tiene citación de origen
+3. **📊 Diagramas Mermaid Completos** - Cada feature/workflow tiene diagrama
+4. **📸 Screenshot Placeholders Presentes** - Formato correcto + índice
+5. **✅ Self-Check Pasado** - Completeness >= 90%, sin TODOs
+
+#### Output Generado
+
+**Ubicación:** `docs/user-guide/`
+
+```
+docs/user-guide/
+├── index.md                          # Selector de idioma
+├── es/
+│   └── {audience}-guide.md          # Guía en español
+└── en/
+    └── {audience}-guide.md          # Guía en inglés
+```
+
+Donde `{audience}` = `enduser-guide` | `admin-guide` | `api-guide` | `complete-guide`
+
+#### Patrones de Interacción
+
+- **PRESCRIPTIVE Steps** (01, 02, 05, 06, 07): Instrucciones exactas, ejecución paso a paso
+- **INTENT-BASED Steps** (03, 04): Objetivo claro, libertad de implementación
+- **Collaboration Level:** 40% user input / 60% autonomous generation
+
+#### Tecnologías Utilizadas
+
+- Mermaid.js para diagramas
+- Markdown con frontmatter YAML
+- CSV para datos estructurados
+- Sistema de templates bilingües
+
+---
+
+## Estadísticas de la Fase
+
+| Métrica | Valor |
+|---------|-------|
+| Total Workflows | 1 |
+| Total Archivos | 15 |
+| Step Files | 8 |
+| Templates | 2 |
+| Data Files | 3 |
+| Idiomas Soportados | 2 (ES/EN) |
+
+---
+
+## Uso
+
+Para ejecutar el workflow create-user-guide:
+
+```bash
+/sa-create-user-guide
+```
+
+O mediante Skill tool:
+```bash
+sa-create-user-guide
+```
+
+---
+
+## Arquitectura
+
+Todos los workflows en esta fase utilizan **step-file architecture**:
+
+- **Micro-file Design**: Cada step es autocontenido
+- **Just-In-Time Loading**: Solo el step actual en memoria
+- **Sequential Enforcement**: Secuencia estricta sin optimizaciones
+- **State Tracking**: Progreso en frontmatter `stepsCompleted`
+- **Append-Only Building**: Construcción incremental de documentos
+
+---
+
+## Próximos Workflows (Planificados)
+
+- `create-api-docs` - Generación de documentación API desde arquitectura
+- `create-tech-guide` - Guías técnicas para desarrolladores
+- `create-deployment-guide` - Documentación de deployment y operaciones
+- `update-documentation` - Actualización de docs existentes con cambios
+
+---
+
+## Metadatos
+
+**Última Actualización:** 2026-01-14
+**Creado Por:** BMAD Module Builder Workflow
+**Versión BMAD:** 6.0
+**Módulo:** BMM (Build & Management Module)

package/siesa-agents/bmm/workflows/5-documentation/create-user-guide/steps/step-01-init.md

@@ -0,0 +1,213 @@
+---
+name: 'step-01-init'
+description: 'Initialize the user guide generation workflow by detecting continuation state and configuring target audience'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/5-documentation/create-user-guide'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-seleccion-features.md'
+workflowFile: '{workflow_path}/workflow.md'
+featuresOutputFolder: '{output_folder}/documentation-artifacts/user-guide'
+templateSpanish: '{workflow_path}/templates/user-guide-template-es.md'
+
+# Output: ONE FILE PER FEATURE at {featuresOutputFolder}/{feature-slug}-guide.md
+# State is kept in memory during the session (no state file)
+
+# Data References
+audienceTypesData: '{workflow_path}/data/audience-types.csv'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+
+# Config
+bmmConfig: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Step 1: Inicialización del Workflow
+
+## STEP GOAL:
+
+Inicializar el workflow de generación de guías de usuario. Verificar qué features ya tienen documentación en `{featuresOutputFolder}/` para saber si es re-ejecución o nueva. El estado se mantiene en memoria durante la sesión.
+
+**ARQUITECTURA DE OUTPUT:**
+- Un archivo por feature: `{featuresOutputFolder}/{feature-slug}-guide.md`
+- Si el archivo de la feature ya existe → se actualiza (action: update)
+- Si no existe → se crea nuevo (action: create)
+- Sin archivo de estado externo — todo en memoria
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a technical writer and documentation specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring documentation expertise and structure, user brings project knowledge
+- ✅ Maintain collaborative professional tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization and audience configuration
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Keep all state in memory (no external state file)
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md and config.yaml are available
+- Previous context = what's in output document + frontmatter (if exists)
+- Don't assume knowledge from other steps
+- Input document discovery happens in step-03
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Load Configuration
+
+Load `{bmmConfig}` and resolve:
+- `{project_name}`
+- `{communication_language}`
+- `{document_output_language}`
+- `{planning_artifacts}`
+- `{implementation_artifacts}`
+- `{project_knowledge}`
+
+Communicate with user in `{communication_language}` (typically Spanish).
+
+### 2. Load Audience Types Data
+
+Load and parse `{audienceTypesData}` to understand available audience types:
+- enduser (Usuarios Finales / End Users)
+- admin (Administradores / Administrators)
+- api (Consumidores de API / API Consumers)
+- mixed (Audiencia Mixta / Mixed Audience)
+
+### 3. Check for Existing Feature Docs
+
+Scan `{featuresOutputFolder}/` for files matching `*-guide.md`.
+
+For each file found, read its frontmatter to extract: `feature_id`, `feature_slug`, `generated_date`, `review_status`.
+
+Build a lookup map in memory: `{ "gestion-de-clientes": { generated_date, review_status }, ... }`
+
+- If any files found → existing documentation detected (step 5)
+- If no files found → fresh workflow (step 6)
+
+This map will be used in step-02 to identify which features are **new** vs **update**.
+
+### 5. Handle Existing Documentation
+
+**If any `*-guide.md` files exist in `{featuresOutputFolder}`:**
+
+List the existing feature docs found in step 3.
+
+"✅ **Documentación Existente Encontrada**
+
+Ya existe documentación generada para las siguientes features:
+{for each existing feature doc}
+- **{feature_id}** — {feature_slug}-guide.md (generada: {generated_date}, estado: {review_status})
+{end for}
+
+¿Qué deseas hacer?
+
+**[N]** Nueva ejecución - Seleccionar features adicionales o regenerar
+**[U]** Update - Actualizar features existentes (re-ejecutar workflow)
+**[X]** Cancel - Cancelar workflow
+
+Por favor selecciona una opción:"
+
+**Menu Handling:**
+- IF N: Continue with fresh run (step 6) — existing feature files are preserved unless re-selected
+- IF U: Continue with fresh run (step 6) — step-02 will mark existing features as action: update
+- IF X: HALT workflow and inform user
+
+### 6. Fresh Workflow Setup (If No Guides or User Selected New)
+
+"👋 **Bienvenido al Generador de Guías de Usuario**
+
+Este workflow te ayudará a crear guías de usuario comprehensivas en español desde las features del proyecto (archivos PRD + épicas individuales por feature).
+
+**Características:**
+- 📄 Guía en español, archivo único actualizable por feature
+- 📊 Diagramas Mermaid para features y workflows
+- 📸 Screenshot placeholders con índice consolidado
+- 🔗 Trazabilidad completa a fuentes (features, stories)
+- ✅ Validación de completitud y calidad
+
+Comencemos configurando la guía de usuario..."
+
+#### A. Determine Target Audience
+
+<!-- AUDIENCE SELECTION DISABLED: always use enduser by default. Do NOT show audience menu to user. -->
+
+Auto-select without asking:
+- audience_id = "enduser"
+- filename_prefix = "enduser-guide"
+
+<!-- Available options (kept for reference, not shown):
+- E → enduser / enduser-guide
+- A → admin / admin-guide
+- I → api / api-guide
+- M → mixed / complete-guide
+-->
+
+Store selected audience information from CSV data.
+
+#### B. Confirmation Message
+
+"✅ **Configuración Inicial Completada**
+
+- Audiencia objetivo: **{audience_name_es}**
+- Idioma: Español
+- Arquitectura: Un archivo por feature en `{output_folder}/documentation-artifacts/user-guide/`
+- Estado del workflow: `_workflow-state.md`
+
+Continuando a la selección de features..."
+
+### 7. Proceed Automatically
+
+- Load, read entire file, then execute `{nextStepFile}` immediately (no menu, no pause)
+
+## CRITICAL STEP COMPLETION NOTE
+
+NO MENU in this step. Proceed automatically to `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Configuration loaded from config.yaml
+- Audience types loaded from CSV
+- `{featuresOutputFolder}` scanned for existing `*-guide.md` files
+- Existing docs detected → [N]/[U]/[X] menu shown, or fresh run started
+- User welcomed and audience auto-selected (enduser)
+- Feature doc lookup map built in memory
+- Ready to proceed to step 2
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning for existing feature docs in `{featuresOutputFolder}`
+- Creating a single monolithic output file (forbidden — must be per-feature)
+- Creating `_workflow-state.md` (forbidden — no state file)
+- Missing audience configuration
+- Proceeding without user confirmation when docs already exist
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.