siesa-agents 2.1.43 → 2.1.44

package/bmad/bmm/workflows/5-documentation/README.md

@@ -0,0 +1,234 @@
+# 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:** `_bmad/bmm/workflows/5-documentation/create-user-guide/`
+**Comando:** `/bmad:bmm:workflows:create-user-guide`
+**Versión:** 1.0.0
+
+#### Descripción
+
+Genera guías de usuario comprehensivas en español e inglés desde épicas y PRDs, con diagramas Mermaid, screenshot placeholders y trazabilidad completa a fuentes.
+
+#### Características Principales
+
+- ✅ **Salida Bilingüe:** Genera versiones en español e inglés con estructura idéntica
+- ✅ **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
+- ✅ **Múltiples Audiencias:** End users, administrators, API consumers, mixed
+
+#### 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 épicas
+   - Escanea múltiples ubicaciones (BMAD 6, BMAD 4, custom)
+   - Usuario selecciona épicas a documentar
+   - Registra selección en frontmatter
+
+4. **step-03-analisis-fuentes** → Análisis de artefactos
+   - Lee PRDs, épicas, arquitectura autónomamente
+   - Extrae features y workflows
+   - 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: Epic X Story Y]`
+
+7. **step-06-traduccion-ingles** → Traducción al inglés
+   - Traduce contenido manteniendo estructura
+   - Traduce labels de Mermaid
+   - Valida consistencia estructural
+
+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
+/bmad:bmm:workflows:create-user-guide
+```
+
+O mediante Skill tool:
+```bash
+bmad:bmm:workflows: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/bmad/bmm/workflows/5-documentation/create-user-guide/data/audience-types.csv

@@ -0,0 +1,5 @@
+audience_id,audience_name_es,audience_name_en,description_es,description_en,filename_prefix
+enduser,Usuarios Finales,End Users,"Usuarios que interactúan con la aplicación","Users who interact with the application",enduser-guide
+admin,Administradores,Administrators,"Usuarios que gestionan el sistema","Users who manage the system",admin-guide
+api,Consumidores de API,API Consumers,"Desarrolladores que integran con el sistema","Developers who integrate with the system",api-guide
+mixed,Audiencia Mixta,Mixed Audience,"Usuarios finales y administradores","End users and administrators",complete-guide

package/bmad/bmm/workflows/5-documentation/create-user-guide/data/diagram-types.csv

@@ -0,0 +1,6 @@
+content_type,diagram_type,mermaid_syntax,use_case_es,use_case_en
+feature_overview,flowchart,"flowchart LR","Mostrar componentes y relaciones","Show components and relationships"
+user_workflow,flowchart,"flowchart TD","Proceso paso a paso con decisiones","Step-by-step process with decisions"
+sequential_process,sequenceDiagram,"sequenceDiagram","Interacciones usuario-sistema","User-system interactions"
+state_changes,stateDiagram-v2,"stateDiagram-v2","Cambios de estado de datos","Data state changes"
+user_journey,journey,"journey","Experiencia del usuario","User experience across touchpoints"

package/bmad/bmm/workflows/5-documentation/create-user-guide/data/section-structure.csv

@@ -0,0 +1,10 @@
+section_id,section_name_es,section_name_en,description,required
+1,Introducción,Introduction,"What is the product, who is this guide for, how to use it",true
+2,Primeros Pasos,Getting Started,"Prerequisites, setup, accessing system, interface overview",true
+3,Conceptos Clave,Core Concepts,"Key terminology, main concepts, user roles",true
+4,Funcionalidades,Features and How to Use Them,"Feature descriptions with diagrams and screenshots",true
+5,Flujos de Trabajo,Common Workflows,"Step-by-step workflows with diagrams",true
+6,Solución de Problemas,Troubleshooting,"Common issues and solutions",false
+7,Preguntas Frecuentes,FAQ,"Frequently asked questions",true
+8,Glosario,Glossary,"Terms and definitions",true
+9,Índice de Capturas,Screenshot Index,"Table of all screenshot placeholders",true

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

@@ -0,0 +1,313 @@
+---
+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}/_bmad/bmm/workflows/5-documentation/create-user-guide'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-seleccion-epicas.md'
+continueFile: '{workflow_path}/steps/step-01b-continue.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFileSpanish: '{output_folder}/documentation-artifacts/user-guide/es/{audience}-guide.md'
+templateSpanish: '{workflow_path}/templates/user-guide-template-es.md'
+
+# Data References
+audienceTypesData: '{workflow_path}/data/audience-types.csv'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+# Config
+bmmConfig: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Step 1: Inicialización del Workflow
+
+## STEP GOAL:
+
+Detectar si existe un workflow en ejecución (continuación) o inicializar un nuevo workflow de generación de guías de usuario. Determinar audiencia objetivo, verificar guías existentes para evitar sobrescrituras accidentales, y crear el documento de output con frontmatter inicial.
+
+## 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
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 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 User Guides
+
+Scan for existing user guides in:
+- `{output_folder}/documentation-artifacts/user-guide/es/*.md`
+- `{output_folder}/documentation-artifacts/user-guide/en/*.md`
+
+For each guide found:
+- Read frontmatter to extract: target_audience, generated_date, review_status
+- Check if it has `stepsCompleted` array
+
+### 4. Handle Continuation (If Guides Exist with stepsCompleted)
+
+**If guides exist with `stepsCompleted` array AND steps are incomplete:**
+
+"🔄 **Workflow en Ejecución Detectado**
+
+He encontrado una guía de usuario en progreso:
+- Audiencia: {target_audience}
+- Última modificación: {last_modified}
+- Steps completados: {stepsCompleted}
+- Step actual: {currentStep}
+
+Voy a cargar el estado previo para continuar donde dejamos..."
+
+**STOP here and immediately load, read entire file, then execute `{continueFile}`**
+
+### 5. Handle Completed Guides
+
+**If guides exist with ALL steps completed (stepsCompleted includes all 7 steps):**
+
+"✅ **Guía Existente Encontrada**
+
+He encontrado una guía de usuario completada:
+- Audiencia: {target_audience}
+- Generada: {generated_date}
+- Estado: {review_status}
+
+¿Qué deseas hacer?
+
+**[N]** Nueva guía - Crear una nueva guía de usuario
+**[U]** Update - Actualizar la guía existente (re-ejecutar workflow)
+**[R]** Replace - Reemplazar completamente (borrar y crear nueva)
+**[X]** Cancel - Cancelar workflow
+
+Por favor selecciona una opción:"
+
+**Menu Handling:**
+- IF N: Continue with fresh workflow (step 6)
+- IF U: Load `{continueFile}` to resume and update
+- IF R: Delete existing files, continue with fresh workflow (step 6)
+- 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 e inglés desde la documentación existente de tu proyecto (PRDs, épicas, stories).
+
+**Características:**
+- 📄 Guías bilingües (español/inglés) con estructura idéntica
+- 📊 Diagramas Mermaid para features y workflows
+- 📸 Screenshot placeholders con índice consolidado
+- 🔗 Trazabilidad completa a fuentes (épicas, stories)
+- ✅ Validación de completitud y calidad
+
+Comencemos configurando la guía de usuario..."
+
+#### A. Determine Target Audience
+
+"**¿Para qué audiencia deseas generar la guía de usuario?**
+
+Según tu proyecto, puedo crear guías optimizadas para:
+
+**[E]** Usuarios Finales (Enduser)
+   - Personas que interactúan con la aplicación
+   - Enfoque: tareas cotidianas, UI, workflows
+
+**[A]** Administradores (Admin)
+   - Personas que gestionan el sistema
+   - Enfoque: configuración, gestión de usuarios, mantenimiento
+
+**[I]** Consumidores de API (API)
+   - Desarrolladores que integran con el sistema
+   - Enfoque: endpoints, autenticación, ejemplos de código
+
+**[M]** Audiencia Mixta (Mixed)
+   - Usuarios finales + administradores
+   - Enfoque: guía completa con todas las perspectivas
+
+Por favor selecciona una opción (E/A/I/M):"
+
+**Wait for user input and parse response:**
+- E → audience_id = "enduser", filename_prefix = "enduser-guide"
+- A → audience_id = "admin", filename_prefix = "admin-guide"
+- I → audience_id = "api", filename_prefix = "api-guide"
+- M → audience_id = "mixed", filename_prefix = "complete-guide"
+
+Store selected audience information from CSV data.
+
+#### B. Create Output Document
+
+Load template from `{templateSpanish}` and create initial Spanish output file at:
+`{output_folder}/documentation-artifacts/user-guide/es/{filename_prefix}.md`
+
+Initialize with frontmatter:
+
+```yaml
+---
+# Workflow state
+stepsCompleted: [1]
+currentStep: step-01-init
+workflow_name: create-user-guide
+workflow_version: 1.0.0
+
+# Project context
+project_name: "{project_name}"
+generated_date: "{current_date}"
+last_modified: "{current_timestamp}"
+
+# Configuration
+target_audience: "{audience_id}"
+output_language: "es"
+epics_selected: []
+epics_excluded: []
+
+# Source artifacts discovered (populated in step-03)
+source_artifacts:
+  prd_docs: []
+  epics_file: ""  # Path to consolidated epics.md file
+  architecture_docs: []
+  workflow_docs: []
+
+# Content tracking
+features_documented: 0
+workflows_documented: 0
+diagrams_generated: 0
+screenshot_placeholders: 0
+
+# Quality metrics
+source_citations_count: 0
+completeness_score: 0
+review_status: "draft"
+
+# User preferences (populated in step-04)
+technical_level: ""
+include_troubleshooting: false
+additional_scenarios: []
+
+# Bilingual output
+spanish_version: "{output_folder}/documentation-artifacts/user-guide/es/{filename_prefix}.md"
+english_version: "{output_folder}/documentation-artifacts/user-guide/en/{filename_prefix}.md"
+translation_completed: false
+---
+
+# {project_name} - Guía de Usuario
+
+[El contenido se generará en los siguientes steps]
+```
+
+#### C. Confirmation Message
+
+"✅ **Configuración Inicial Completada**
+
+- Audiencia objetivo: **{audience_name_es}**
+- Idioma base: Español (se traducirá a inglés en step-06)
+- Documento creado: `{output_folder}/documentation-artifacts/user-guide/es/{filename_prefix}.md`
+
+Continuando a la selección de épicas..."
+
+### 7. Update State and Proceed
+
+Before loading next step:
+- Ensure frontmatter.stepsCompleted = [1]
+- Ensure frontmatter.currentStep = "step-02-seleccion-epicas"
+- Save outputFile
+
+### 8. Present MENU OPTIONS
+
+Display: **Select an Option:** [C] Continue
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+#### Menu Handling Logic:
+
+- IF C: Update frontmatter, then load, read entire file, then execute `{nextStepFile}`
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and initialization is complete (OR continuation is properly routed to step-01b-continue.md), will you then load, read entire file, then execute `{nextStepFile}` to begin epic selection.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Configuration loaded from config.yaml
+- Audience types loaded from CSV
+- Existing guides checked and handled appropriately
+- Continuation routed to step-01b-continue.md if needed
+- OR new document created from template with complete frontmatter
+- frontmatter.stepsCompleted = [1]
+- User welcomed and confirmed audience selection
+- Ready to proceed to step 2
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking for existing documents properly
+- Not routing to step-01b-continue.md when appropriate
+- Creating duplicate documents
+- Missing audience configuration
+- Not initializing frontmatter completely
+- Proceeding without user confirmation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.