siesa-agents 2.1.32 → 2.1.34

package/bmad-core/agents/po.md

@@ -80,6 +80,7 @@ commands:
   - sync-epic-to-jira {epic-number}: Find all stories matching pattern {epic-number}.*.story.md in docs/stories/, then for EACH story execute the full sync-story-to-jira workflow creating all Jira subtasks (task sync-stories-batch-to-jira with scope epic-{epic-number})
   - update-epic-status {epic-number}: Batch update status of all stories in an epic (task update-epic-stories-jira-status)
   - validate-story-draft {story}: run the task validate-next-story against the provided story file
+  - create-user-guide: Run the task create-user-guide
   - yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
   - exit: Exit (confirm)
 dependencies:

package/bmad-core/tasks/create-user-guide.md

@@ -0,0 +1,605 @@
+<!-- Powered by BMAD" Core -->
+
+# Create User Guide Task
+
+## Purpose
+
+To generate a comprehensive, user-facing guide that explains how to use the system from an end-user perspective. This guide should be written in clear, non-technical language and focus on practical usage instructions, workflows, and common scenarios. Unlike technical documentation (README, architecture docs), this guide is intended for the final user of the application.
+
+## Prerequisites
+
+- PRD documents exist in `docs/prd/`
+- Core workflows are defined in `docs/architecture/core-workflows.md`
+- The system has functional features ready for end-user documentation
+
+## Language Requirements
+
+**IMPORTANT:** When executing this task, the agent **MUST** interact with the user in **Spanish**, regardless of the language used in previous conversations. All questions, clarifications, and status updates should be in Spanish.
+
+**Output Languages:** This task produces user guides in TWO languages:
+- **Spanish** (`es/`) - Primary version
+- **English** (`en/`) - Translated version
+
+Both versions must have identical content and structure, differing only in language.
+
+---
+
+## SEQUENTIAL Task Execution (Do not proceed until current Task is complete)
+
+### 1. Load Core Configuration and Gather Context
+
+#### 1.1 Load Configuration
+
+- Load `.bmad-core/core-config.yaml` from the project root
+- If the file does not exist, ask the user for the documentation output location (default: `docs/user-guide/`)
+- Extract key configurations: `prd.*`, `architecture.*`
+
+#### 1.2 Identify Target Audience
+
+Ask the user to clarify the target audience (in Spanish):
+
+- "¿Cuál es la audiencia principal para esta guía de usuario?"
+  - Usuarios finales (clientes que usan la aplicación)
+  - Administradores (usuarios que gestionan el sistema)
+  - Ambos (usuarios finales y administradores)
+  - Consumidores de API (desarrolladores que integran con el sistema)
+
+#### 1.3 Check for Existing User Guides
+
+Before proceeding, check for existing user guide files:
+
+1. Scan the documentation directory (default: `docs/`) for existing user guides:
+   - `docs/user-guide.md`
+   - `docs/user-guide/*.md`
+   - `docs/user-guide/es/*.md` (Spanish guides)
+   - `docs/user-guide/en/*.md` (English guides)
+   - `docs/user-guide-*.md` (e.g., `user-guide-admin.md`, `user-guide-enduser.md`)
+   - Any files matching pattern `*user*guide*.md`
+
+2. If existing user guides are found, present them to the user (in Spanish):
+   - "He encontrado las siguientes guías de usuario existentes: [listar archivos con su audiencia objetivo si es identificable]"
+   - Preguntar: "¿Cómo desea proceder?"
+     - **Crear una nueva guía separada** - Crear una nueva guía con un nombre distintivo para la audiencia seleccionada
+     - **Actualizar una guía existente** - Modificar una de las guías existentes (especificar cuál)
+     - **Reemplazar una guía existente** - Sobrescribir una guía existente (requiere confirmación explícita)
+     - **Cancelar** - Detener y revisar la documentación existente primero
+
+3. If user chooses to create a new separate guide:
+   - **Automatically select** the filename based on target audience (do NOT ask for confirmation):
+     - End users: `user-guide/es/enduser-guide.md` + `user-guide/en/enduser-guide.md`
+     - Administrators: `user-guide/es/admin-guide.md` + `user-guide/en/admin-guide.md`
+     - API consumers: `user-guide/es/api-guide.md` + `user-guide/en/api-guide.md`
+     - Mixed: `user-guide/es/complete-guide.md` + `user-guide/en/complete-guide.md`
+   - Inform the user of the selected filename: "Se utilizará el nombre de archivo: [filename]"
+
+4. If user chooses to replace an existing guide:
+   - Require explicit confirmation (in Spanish): "¿Está seguro de que desea reemplazar [filename]? Esta acción no se puede deshacer. (sí/no)"
+   - Only proceed with explicit "sí" or "yes" confirmation
+
+5. Record the chosen action and target filename for use in step 7
+
+### 2. Gather Product Information
+
+#### 2.1 Identify Available Epics and Select Scope
+
+Before reading documentation, identify and present available epics to the user:
+
+1. Scan the `docs/prd/` directory for epic files (e.g., `epic-1.md`, `epic-2.md`, etc.)
+
+2. Present the list of available epics to the user (in Spanish):
+   - "He encontrado las siguientes épicas en el proyecto:"
+   - List each epic with its number and title (extracted from the file)
+   - Example format:
+     ```
+     - Epic 1: [Título del épico]
+     - Epic 2: [Título del épico]
+     - Epic 3: [Título del épico]
+     ...
+     ```
+
+3. Ask the user which epics to include (in Spanish):
+   - "¿Cuáles épicas desea incluir en la guía de usuario? Puede seleccionar:"
+     - **Todas las épicas** - Incluir todas las funcionalidades documentadas
+     - **Épicas específicas** - Seleccionar épicas individuales (proporcionar números separados por comas, ej: 1, 3, 5)
+     - **Excluir épicas específicas** - Incluir todos excepto las especificadas
+
+4. Record the selected epics for use in subsequent steps
+   - Only read and document features from the selected epics
+   - Stories from non-selected epics should be ignored
+
+#### 2.2 Review PRD Documents
+
+Based on `prdSharded` from config and the **selected epics from step 2.1**, locate and read PRD documents to understand:
+
+- **Product Overview**: Goals, background, and purpose from `docs/prd/goals-and-background-context.md`
+- **Requirements**: Functional requirements from `docs/prd/requirements.md`
+- **User Interface**: UI design goals from `docs/prd/user-interface-design-goals.md`
+- **Epic Definitions**: Feature sets from **selected epic files only** (as determined in step 2.1)
+
+Extract:
+- System purpose and value proposition (in user terms)
+- Key features and capabilities
+- User roles and permissions
+- Primary use cases
+
+#### 2.2 Review Core Workflows
+
+Read `docs/architecture/core-workflows.md` to understand:
+
+- Primary user journeys
+- Step-by-step processes users will follow
+- Decision points and branching paths
+- Expected outcomes for each workflow
+
+#### 2.3 Review UI Components (if applicable)
+
+If frontend exists, review `docs/architecture/components.md` to understand:
+
+- Available screens and pages
+- Navigation structure
+- Key UI elements users will interact with
+
+### 3. Elicit Additional Information
+
+Present findings to the user and ask clarifying questions (in Spanish):
+
+1. "Basándome en las épicas seleccionadas ([listar épicas]), he identificado estas funcionalidades principales: [lista]. ¿Hay alguna funcionalidad que deba excluirse de la guía de usuario?"
+2. "¿Hay escenarios o casos de uso específicos que sean particularmente importantes de documentar?"
+3. "¿Cuál es el nivel de competencia técnica esperado de sus usuarios?" (Novato / Intermedio / Mixto)
+4. "¿Hay limitaciones conocidas o advertencias que los usuarios deban conocer?"
+5. "¿Debería incluir la guía secciones de solución de problemas?"
+
+### 4. Structure the User Guide
+
+Create the user guide with the following structure:
+
+```markdown
+# [Product Name] User Guide
+
+## Introduction
+- What is [Product Name]?
+- Who is this guide for?
+- How to use this guide
+
+## Getting Started
+- Prerequisites (what users need before starting)
+- First-time setup (if applicable)
+- Accessing the system
+- Overview of the interface
+
+## Core Concepts
+- Key terminology
+- Understanding [main concepts relevant to the product]
+- User roles and permissions (if applicable)
+
+## Features and How to Use Them
+
+### [Feature 1]
+- What it does
+- **Diagram**: [Feature diagram showing key components/flow]
+- [Screenshot: FEATURE_NAME - Brief description of what to capture]
+- Step-by-step instructions
+- Tips and best practices
+- Common scenarios
+
+### [Feature 2]
+...
+
+## Common Workflows
+
+### [Workflow 1: e.g., "Managing Your First Application"]
+- **Workflow Diagram**: [Flowchart or sequence diagram showing the complete workflow]
+- [Screenshot: WORKFLOW_STEP_1 - Description of key step to capture]
+1. Step-by-step walkthrough
+   - [Screenshot: WORKFLOW_STEP_N - Description for each key step]
+2. Expected results
+3. What to do if something goes wrong
+
+### [Workflow 2]
+...
+
+## Troubleshooting (if requested)
+- Common issues and solutions
+- Error messages and what they mean
+- When to contact support
+
+## FAQ
+- Frequently asked questions based on requirements
+
+## Glossary
+- Terms and definitions
+
+## Appendix (if needed)
+- Quick reference tables
+- Keyboard shortcuts
+- Additional resources
+
+## Screenshot Index
+
+This section lists all screenshots that need to be added to this guide. Once a screenshot is added, update the corresponding placeholder with the actual image.
+
+| ID | Location | Description | Status |
+|----|----------|-------------|--------|
+| FEATURE_NAME_1 | Section X.X | Brief description of what the screenshot should show | Pending |
+| WORKFLOW_STEP_1 | Section Y.Y | Brief description of the workflow step to capture | Pending |
+| ... | ... | ... | ... |
+
+**Instructions for adding screenshots:**
+1. Capture the screenshot as described in the "Description" column
+2. Save the image in `docs/user-guide/[lang]/images/` with the ID as filename (e.g., `FEATURE_NAME_1.png`)
+3. Replace the placeholder `[Screenshot: ID]` with `![Description](./images/ID.png)`
+4. Update the "Status" column to "Added"
+```
+
+### 5. Generate User Guide Content
+
+#### 5.1 Writing Guidelines
+
+When writing content, follow these principles:
+
+- **Use plain language**: Avoid technical jargon; explain concepts in terms users understand
+- **Be task-oriented**: Focus on what users want to accomplish, not how the system works internally
+- **Use active voice**: "Click the Submit button" not "The Submit button should be clicked"
+- **Include visual cues**: Reference UI elements by their labels (bold text for buttons, menus)
+- **Provide context**: Explain WHY users might want to do something, not just HOW
+- **Use numbered steps**: For sequential instructions, use numbered lists
+- **Include examples**: Where helpful, provide concrete examples of inputs/outputs
+- **Note prerequisites**: Before each task, list what the user needs to have ready
+
+#### 5.2 Content Generation Rules
+
+- **DO NOT** include technical implementation details (API endpoints, database schemas, code)
+- **DO NOT** reference internal architecture or system design
+- **DO NOT** include developer-focused information (build steps, environment setup for development)
+- **DO NOT** invent or assume feature behaviors - every description must be backed by documentation
+- **DO** focus on user goals and outcomes
+- **DO** explain error messages in user-friendly terms
+- **DO** include "what happens next" after each major action
+- **DO** cite source documents for ALL feature descriptions, definitions, and workflows (see 5.3)
+
+#### 5.3 Source Citation Requirements (MANDATORY)
+
+Every feature definition, workflow explanation, or capability description **MUST** include a source citation. This ensures accuracy and traceability.
+
+**Citation Format:**
+- For epic-level information: `[Source: Epic X]`
+- For story-level information: `[Source: Epic X Story Y]`
+- For PRD sections: `[Source: PRD - {section-name}]`
+- For multiple sources: `[Source: Epic X Story Y, Epic Z Story W]`
+
+**What Requires Citation:**
+- Feature descriptions and what they do
+- Workflow steps and expected behaviors
+- User role definitions and permissions
+- System capabilities and limitations
+- Error scenarios and their meanings
+
+**Example:**
+```markdown
+### Managing Credentials
+
+Users can create, view, update, and delete credentials through the Credentials
+Management interface. Each credential is associated with a specific application
+and can be configured with custom expiration policies. [Source: Epic 2 Story 3]
+
+#### Creating a New Credential
+
+1. Navigate to **Credentials** > **New Credential**
+2. Select the target application from the dropdown
+3. Enter the credential details...
+[Source: Epic 2 Story 3, Epic 2 Story 4]
+```
+
+**Verification:**
+- Before writing any feature or workflow content, first locate the corresponding epic/story file
+- Read the acceptance criteria and requirements from the source file
+- Only document behaviors explicitly stated in the source
+- If no source can be found for a feature, flag it to the user: "I could not find documentation for [feature]. Please provide the source or confirm this should be excluded."
+
+#### 5.4 Diagram Requirements (MANDATORY)
+
+Every feature and workflow **MUST** include a diagram to visually explain the concept. Diagrams help users understand complex processes at a glance.
+
+**Diagram Format:**
+- Use Mermaid syntax for all diagrams (compatible with most markdown renderers)
+- Diagrams must be in the same language as the surrounding content (Spanish for `es/`, English for `en/`)
+
+**Diagram Types by Content:**
+
+| Content Type | Recommended Diagram | Purpose |
+|--------------|---------------------|---------|
+| Feature overview | `flowchart` or `block-beta` | Show main components and relationships |
+| User workflow | `flowchart TD` | Show step-by-step process with decision points |
+| Sequential process | `sequenceDiagram` | Show interactions between user and system |
+| State changes | `stateDiagram-v2` | Show how data/entities change states |
+| User journey | `journey` | Show user experience across touchpoints |
+
+**Example - Feature Diagram:**
+```markdown
+### Gestión de Credenciales
+
+Esta funcionalidad permite crear, ver, actualizar y eliminar credenciales.
+
+```mermaid
+flowchart LR
+    A[Usuario] --> B{Acción}
+    B --> C[Crear]
+    B --> D[Ver]
+    B --> E[Actualizar]
+    B --> F[Eliminar]
+    C --> G[(Base de Datos)]
+    D --> G
+    E --> G
+    F --> G
+```
+
+[Source: Epic 2 Story 3]
+```
+
+**Example - Workflow Diagram:**
+```markdown
+### Flujo de Autenticación
+
+```mermaid
+sequenceDiagram
+    actor U as Usuario
+    participant A as Aplicación
+    participant S as Servidor
+
+    U->>A: Ingresa credenciales
+    A->>S: Envía solicitud de login
+    S-->>A: Retorna token JWT
+    A-->>U: Muestra dashboard
+```
+
+[Source: Epic 1 Story 2]
+```
+
+**Diagram Guidelines:**
+- Keep diagrams simple and focused (max 10-12 nodes for flowcharts)
+- Use clear, descriptive labels in user-friendly language
+- Include decision points (diamonds) for conditional flows
+- Show error paths when relevant to the user
+- Ensure diagram accurately reflects the documented behavior from epic/story sources
+
+**What NOT to include in diagrams:**
+- Technical implementation details (database schemas, API internals)
+- System architecture components invisible to users
+- Code-level abstractions
+
+#### 5.5 Screenshot Placeholder Requirements (MANDATORY)
+
+The agent must include screenshot placeholders throughout the document to guide reviewers on what visual aids to add. Screenshots will be added later by the person reviewing the guide.
+
+**Placeholder Format:**
+```
+[Screenshot: IDENTIFIER - Description of what to capture]
+```
+
+**Identifier Naming Convention:**
+- Use UPPER_SNAKE_CASE for identifiers
+- Prefix with context: `FEATURE_`, `WORKFLOW_`, `UI_`, `ERROR_`
+- Make identifiers unique and descriptive
+- Examples:
+  - `[Screenshot: FEATURE_CREDENTIALS_LIST - Vista de la lista de credenciales con filtros aplicados]`
+  - `[Screenshot: WORKFLOW_LOGIN_STEP2 - Pantalla de verificación de dos factores]`
+  - `[Screenshot: UI_DASHBOARD_MAIN - Panel principal después de iniciar sesión]`
+  - `[Screenshot: ERROR_INVALID_TOKEN - Mensaje de error cuando el token expira]`
+
+**Where to Add Screenshot Placeholders:**
+- After feature introductions (show the main UI for that feature)
+- At key steps in workflows (show the screen at each important step)
+- For complex UI elements that need visual explanation
+- For error messages and their resolution screens
+- For before/after comparisons when relevant
+
+**Screenshot Index (End of Document):**
+At the end of each user guide, include a "Screenshot Index" section that consolidates all placeholders:
+
+```markdown
+## Screenshot Index / Índice de Capturas de Pantalla
+
+| ID | Ubicación | Descripción | Estado |
+|----|-----------|-------------|--------|
+| FEATURE_CREDENTIALS_LIST | Sección 4.1 | Vista de la lista de credenciales con filtros | Pendiente |
+| WORKFLOW_LOGIN_STEP2 | Sección 5.2 | Pantalla de verificación de dos factores | Pendiente |
+```
+
+**Guidelines:**
+- Add 1-3 screenshot placeholders per feature section
+- Add screenshot placeholders for each major step in workflows
+- Descriptions should be specific enough for someone else to capture the correct screen
+- Use the same language as the document (Spanish descriptions in `es/`, English in `en/`)
+- Track all placeholders in the Screenshot Index for easy reference
+
+### 6. Review and Validation
+
+#### 6.1 Self-Check
+
+Before finalizing, verify:
+
+- [ ] All major features from the PRD are covered
+- [ ] Instructions are clear enough for a new user
+- [ ] No technical jargon remains unexplained
+- [ ] All referenced UI elements exist and are named correctly
+- [ ] Workflows match actual system behavior
+- [ ] Troubleshooting covers common error scenarios
+- [ ] **Every feature description has a source citation** `[Source: Epic X Story Y]`
+- [ ] **Every workflow explanation has a source citation**
+- [ ] **No undocumented features are described** (if source not found, flagged to user)
+- [ ] Source citations reference actual existing epic/story files
+- [ ] **Every feature includes a Mermaid diagram** explaining its components/flow
+- [ ] **Every workflow includes a Mermaid diagram** showing the process
+- [ ] Diagrams are in the correct language (Spanish in `es/`, English in `en/`)
+- [ ] Diagrams are simple, user-focused, and free of technical implementation details
+- [ ] **Every feature has screenshot placeholders** with format `[Screenshot: ID - Description]`
+- [ ] **Every workflow has screenshot placeholders** for key steps
+- [ ] Screenshot placeholders have unique UPPER_SNAKE_CASE identifiers
+- [ ] **Screenshot Index exists at end of document** listing all placeholders with locations
+
+#### 6.2 Present Draft to User
+
+Present the completed draft and ask (in Spanish):
+
+1. "¿Cubre esto todas las funcionalidades que sus usuarios necesitan conocer?"
+2. "¿Es el lenguaje apropiado para su audiencia objetivo?"
+3. "¿Hay secciones que necesiten más detalle o ejemplos?"
+4. "¿Debería agregar marcadores de posición para capturas de pantalla en secciones específicas?"
+
+### 7. Finalize and Save
+
+#### 7.1 Apply Filename Decision from Step 1.3
+
+- Use the target filename and action determined in step 1.3
+- If creating a new guide or replacing (with confirmation), proceed with save
+- If updating an existing guide, merge new content appropriately while preserving existing customizations
+
+#### 7.2 Save the User Guide (Both Languages)
+
+Save user guides in BOTH Spanish and English using the following folder structure:
+
+**Standard Structure (single file per language):**
+```
+docs/user-guide/
+├── es/
+│   └── [audience]-guide.md      (e.g., admin-guide.md, enduser-guide.md)
+├── en/
+│   └── [audience]-guide.md
+└── index.md                      (language selector / navigation)
+```
+
+**Extended Structure (sharded, for extensive guides):**
+```
+docs/user-guide/
+├── es/
+│   └── [audience]/
+│       ├── index.md
+│       ├── getting-started.md
+│       ├── features/
+│       │   └── [feature-name].md
+│       ├── workflows/
+│       │   └── [workflow-name].md
+│       └── troubleshooting.md
+├── en/
+│   └── [audience]/
+│       ├── index.md
+│       ├── getting-started.md
+│       ├── features/
+│       │   └── [feature-name].md
+│       ├── workflows/
+│       │   └── [workflow-name].md
+│       └── troubleshooting.md
+└── index.md
+```
+
+Where `[audience]` matches the target audience (e.g., `admin`, `enduser`, `api`)
+
+**Process:**
+1. First, generate the complete user guide content in Spanish
+2. Then, translate the content to English maintaining identical structure
+3. Ensure source citations `[Source: Epic X Story Y]` remain unchanged in both versions
+4. Save both versions to their respective language folders
+
+#### 7.3 Update User Guide Index (Language Selector)
+
+Create or update `docs/user-guide/index.md` with language selection and guide navigation:
+
+```markdown
+# User Guides / Guías de Usuario
+
+## Select Language / Seleccionar Idioma
+
+| Language | Idioma |
+|----------|--------|
+| [English](./en/) | [Español](./es/) |
+
+---
+
+## Available Guides / Guías Disponibles
+
+### English
+
+| Guide | Audience | Description |
+|-------|----------|-------------|
+| [Guide Name](./en/[audience]-guide.md) | [Audience] | [Brief description] |
+
+### Español
+
+| Guía | Audiencia | Descripción |
+|------|-----------|-------------|
+| [Nombre de Guía](./es/[audience]-guide.md) | [Audiencia] | [Descripción breve] |
+```
+
+#### 7.4 Provide Summary
+
+Provide summary to user (in Spanish):
+
+- Acción realizada: [Creado nuevo / Actualizado existente / Reemplazado]
+- Ubicación de guías:
+  - Español: `[ruta del archivo en español]`
+  - English: `[ruta del archivo en inglés]`
+- Audiencia objetivo: [audiencia identificada]
+- Épicas incluidas: [listar épicas seleccionadas, ej: Epic 1, Epic 3, Epic 5]
+- Épicas excluidas: [listar épicas no incluidas, si aplica]
+- Funcionalidades documentadas: [cantidad]
+- Flujos de trabajo documentados: [cantidad]
+- Diagramas incluidos: [cantidad]
+- Capturas de pantalla sugeridas: [cantidad] (ver Índice de Capturas de Pantalla al final del documento)
+- Otras guías existentes: [listar otras guías de usuario en el proyecto]
+- Próximos pasos recomendados:
+  - Revisar con usuarios finales reales para obtener retroalimentación
+  - Agregar capturas de pantalla o ayudas visuales donde se indique
+  - Establecer un ciclo de revisión para mantener la guía actualizada
+  - Considerar crear guías adicionales específicas por audiencia si es necesario
+  - Verificar que ambas versiones (español e inglés) estén sincronizadas
+
+## Success Criteria
+
+- User guide is written in non-technical, user-friendly language
+- All major features and workflows are documented
+- Instructions are actionable and verifiable
+- Document is structured for easy navigation
+- Content is traceable to PRD requirements
+- Guide is appropriate for the identified target audience
+- Existing user guides are preserved unless explicit replacement is confirmed
+- Multiple audience-specific guides can coexist with clear organization
+- User guide index is maintained when multiple guides exist
+- **Every feature and workflow description includes source citation** in format `[Source: Epic X Story Y]`
+- **No content is invented** - all descriptions are backed by epic/story documentation
+- **Only selected epics are documented** - user explicitly chose which epics to include
+- **Every feature includes a Mermaid diagram** explaining its components or flow
+- **Every workflow includes a Mermaid diagram** showing the complete process
+- **Diagrams are localized** - Spanish labels in `es/`, English labels in `en/`
+- **Every feature and workflow has screenshot placeholders** with format `[Screenshot: ID - Description]`
+- **Screenshot Index exists at end of document** consolidating all placeholders for reviewers
+- **Both Spanish and English versions are generated** with identical content and structure
+- **Language folder structure** (`es/`, `en/`) is properly created and maintained
+- **Index file includes language selector** for easy navigation between versions
+
+## Notes
+
+- This task creates documentation for END USERS, not developers
+- The guide should be usable by someone with no knowledge of the underlying technology
+- Focus on user outcomes and business value, not technical implementation
+- Keep the guide maintainable by linking to single sources of truth where possible
+- Consider versioning the guide alongside product releases
+- **Multiple Guides**: A project may have separate guides for different audiences (admins, end users, API consumers). Each should be clearly named and organized
+- **Never Auto-Replace**: Always check for existing guides and require explicit user confirmation before replacing any existing documentation
+- **Language Requirements**:
+  - Agent interaction with users must be in **Spanish** during task execution
+  - Output is generated in **both Spanish and English**
+  - Spanish version is created first, then translated to English
+  - Source citations `[Source: Epic X Story Y]` remain in original format (not translated)
+  - Both versions must be kept synchronized when updates are made
+- **Diagram Requirements**:
+  - Every feature and workflow MUST have a Mermaid diagram
+  - Diagrams must be user-focused, not technical
+  - Diagram labels must be in the same language as the document (Spanish/English)
+  - Use appropriate diagram types: flowcharts for processes, sequence diagrams for interactions
+  - Keep diagrams simple (max 10-12 nodes) for readability
+- **Screenshot Requirements**:
+  - Include placeholders with format `[Screenshot: ID - Description]`
+  - Use UPPER_SNAKE_CASE identifiers with prefixes: `FEATURE_`, `WORKFLOW_`, `UI_`, `ERROR_`
+  - Descriptions must be specific enough for reviewers to capture the correct screen
+  - Screenshot Index at end of document consolidates all placeholders
+  - Reviewers will add actual screenshots later following the index instructions

package/bmad-core/tasks/sync-epic-files-to-jira.md

@@ -4,7 +4,16 @@
 
 ## Purpose
 
-Automatically synchronize individual epic files from `docs/prd/` directory to Jira. This task is designed for scenarios where epics and stories have been developed using BMAD but Jira was never updated. It scans for files starting with `epic-` and creates corresponding epics and stories in Jira.
+Automatically synchronize individual epic files from `docs/prd/` directory to Jira using an **atomic processing approach**. This task is designed for scenarios where epics and stories have been developed using BMAD but Jira was never updated.
+
+**Key Features:**
+- Processes each epic atomically: create epic → create stories → update files
+- Immediately saves Jira references after each epic is processed
+- Resilient to interruptions - completed epics retain their Jira keys
+- Automatically updates story files in `docs/stories/` with Jira Information sections
+- Safe to re-run - skips already synced items
+
+This atomic approach ensures that if the process fails at any point, all previously completed epics have their Jira references saved and won't be lost.
 
 ## When to Use This Task
 
@@ -18,10 +27,28 @@ Automatically synchronize individual epic files from `docs/prd/` directory to Ji
 **Prerequisites:**
 
 - Epic files in `docs/prd/` following naming pattern: `epic-*.md`
+- Story files in `docs/stories/` following naming pattern: `{epic-number}.{story-number}-*.md` (optional)
 - Jira preferences configured in `.bmad-core/data/jira-preferences.md`
 - Active Jira connection with appropriate permissions
 - MCP Jira integration available
 
+## Processing Model
+
+**IMPORTANT:** This task uses an **atomic processing model**. Each epic is fully processed (Jira creation + file updates) before moving to the next:
+
+```
+For each epic file:
+  1. Create epic in Jira → Get epic key
+  2. Create all stories for this epic → Get story keys
+  3. Update epic file with all keys immediately
+  4. Update story files in docs/stories immediately
+  5. Move to next epic file
+
+If process fails at epic N, epics 1 to N-1 are complete with saved references.
+```
+
+This approach ensures **zero data loss** - you never lose Jira keys if the process is interrupted.
+
 ## Instructions
 
 ### Phase 1: Configuration & Validation
@@ -144,11 +171,15 @@ format: |
   Enter selection (1-5):
 ```
 
-### Phase 2: Epic Creation
+### Phase 2: Epic and Story Creation (Process Each Epic Atomically)
+
+**CRITICAL:** Process each epic file completely before moving to the next. This ensures that if the process fails, all completed epics will have their Jira references saved.
+
+**For each epic file, execute Steps 5-7.5 before moving to the next epic:**
 
-#### Step 5: Create Epics in Jira
+#### Step 5: Create Epic in Jira
 
-**For each epic file:**
+**For the current epic file:**
 
 1. **Check Existing Jira Key:**
    - Search for `[PM-XX]` or similar pattern in epic header
@@ -194,19 +225,13 @@ format: |
 
 **Progress Output:**
 ```markdown
-Creating Epics:
-⊘ Epic 1: Foundation & Category Management → PM-6 (already exists, skipped)
-✓ Epic 2: Task Management Core → PM-25 (created)
-✓ Epic 3: Task Filtering & API Polish → PM-26 (created)
-
-Summary: 2 created, 1 skipped
+Processing Epic 1: Foundation & Category Management
+⊘ Epic already exists with key PM-6 (skipped)
 ```
 
-### Phase 3: Story Creation
-
-#### Step 6: Create Stories in Jira
+#### Step 6: Create Stories in Jira for Current Epic
 
-**For each story in each epic file:**
+**For each story in the current epic file:**
 
 1. **Check Existing Jira Key:**
    - Search for `[PM-XX]` in story header
@@ -262,22 +287,14 @@ Creating Stories for Epic PM-6:
 ⊘ Story 1.3: Category Repository → PM-11 (already exists, skipped)
 ⊘ Story 1.4: Category API Endpoints → PM-12 (already exists, skipped)
 
-Creating Stories for Epic PM-25:
-✓ Story 2.1: Task Entity → PM-27 (created)
-✓ Story 2.2: Task Repository → PM-28 (created)
-✓ Story 2.3: Task Validation → PM-29 (created)
-✓ Story 2.4: Task API → PM-30 (created)
-
-Summary: 4 created, 4 skipped
+Summary for Epic 1: 0 created, 4 skipped
 ```
 
-### Phase 4: Update Epic Files with Jira Keys
+#### Step 7: Update Current Epic File with Jira Keys
 
-#### Step 7: Update Epic Files
+**CRITICAL:** Immediately update the epic file with Jira references for traceability. This ensures that if the process fails later, this epic's references are already saved.
 
-**CRITICAL:** Update each epic file with Jira references for traceability
-
-**For each processed epic file:**
+**For the current epic file:**
 
 1. **Update Epic Header:**
    - Locate epic header line (e.g., `# Epic 1: Foundation...`)
@@ -314,15 +331,85 @@ Summary: 4 created, 4 skipped
 
 **Progress Output:**
 ```markdown
-Updating Epic Files:
-✓ epic-1-foundation-category-management.md (no changes, already synced)
-✓ epic-2-task-management-core.md (updated with 5 new Jira keys)
-✓ epic-3-task-filtering-api-polish.md (updated with 5 new Jira keys)
+✓ epic-1-foundation-category-management.md (updated with 5 Jira keys)
+```
+
+#### Step 7.5: Update Story Files in docs/stories for Current Epic
+
+**CRITICAL:** Immediately after updating the epic file, search and update individual story files for this epic. This ensures atomicity per epic.
+
+**For the current epic:**
+
+1. **Extract Epic Number:**
+   - Get epic number from file name (e.g., `epic-1-` → epic number is `1`)
+   - Use this to search for related story files
+
+2. **Search Story Files:**
+   - Scan `docs/stories/` directory
+   - Filter files matching pattern: `{epic-number}.{story-number}-*.md`
+   - Example: For epic 1, find files like `1.1-*.md`, `1.2-*.md`, `1.3-*.md`, etc.
+   - Only include files that start with the epic number prefix
+
+3. **For Each Story File Found:**
+   - Read file content
+   - Check if it already has a "## Jira Information" section
+   - If not present, add the section at the end of the file (before any existing metadata)
+
+4. **Add Jira Information Section:**
+   - Insert the following markdown at an appropriate location (after main content, before metadata):
+
+```markdown
+## Jira Information
+
+**Jira Issue Key:** Not synced to Jira yet
+**Jira URL:** Story will be synced to Jira using sync-story-to-jira task
 
-Total: 3 files processed, 2 files updated, 10 new keys added
+_Note: Tasks will not be created in Jira until this story has an associated Jira issue._
 ```
 
-### Phase 5: Verification & Reporting
+5. **File Update Strategy:**
+   - If file has no "## Jira Information" section: Add it before the last `---` separator (if present) or at the end
+   - If file already has the section: Skip (do not modify)
+   - Preserve all existing content and formatting
+
+**Progress Output:**
+```markdown
+Updating Story Files for Epic 1:
+✓ 1.1-project-scaffolding.md (added Jira Information section)
+✓ 1.2-database-configuration.md (added Jira Information section)
+⊘ 1.3-category-repository.md (already has Jira Information, skipped)
+✓ 1.4-category-api.md (added Jira Information section)
+
+Summary for Epic 1: 4 story files found, 3 updated, 1 skipped
+```
+
+---
+
+**After completing Steps 5-7.5 for the current epic, move to the next epic file and repeat the process.**
+
+---
+
+**Error Handling Per Epic:**
+- **Issue:** Epic creation fails in Jira
+  - **Action:** Log error with details, skip to next epic (previous epics already saved)
+- **Issue:** Story creation fails for a story
+  - **Action:** Log error, continue with remaining stories, update file with successful stories only
+- **Issue:** Cannot update epic file
+  - **Action:** Log critical error with Jira keys, save keys to temporary file, continue processing
+- **Issue:** No story files found for an epic
+  - **Action:** Log info message, continue with next epic (not an error)
+- **Issue:** Story file cannot be read
+  - **Action:** Log warning, skip file, continue processing
+- **Issue:** Story file cannot be written
+  - **Action:** Log error, report file path, continue with remaining files
+
+**Advantages of Atomic Processing:**
+- ✅ If process fails at Epic 3, Epics 1-2 are fully synced with saved references
+- ✅ Easy to resume from last failed epic
+- ✅ No risk of losing Jira keys created earlier in the process
+- ✅ Each epic is a complete transaction
+
+### Phase 3: Final Verification & Reporting
 
 #### Step 8: Generate Sync Report
 
@@ -346,67 +433,70 @@ Total: 3 files processed, 2 files updated, 10 new keys added
   - Created: {{created_stories}}
   - Skipped (existing): {{skipped_stories}}
 - **Failed Items:** {{failure_count}}
-- **Files Updated:** {{updated_files}}/{{total_files}}
+- **Epic Files Updated:** {{updated_files}}/{{total_files}}
+- **Story Files Updated:** {{updated_story_files}}/{{total_story_files}}
+  - Files with Jira Information added: {{jira_info_added}}
+  - Files already with Jira Information: {{jira_info_skipped}}
 
-## Created Items by Epic File
+## Processing Summary by Epic
 
-### Epic File 1: {{filename}}
+### Epic 1: {{epic_name}} (File: {{filename}})
 
-**Epic:** {{epic_name}} → {{epic_key}} {{status}}
+**Epic in Jira:** {{epic_key}} {{status}}
+**Epic File:** ✓ Updated with Jira keys
+**Story Files Updated:** {{story_files_updated}}/{{story_files_found}}
 
-**Stories:**
+**Stories Created/Updated:**
 
-| Story Title | Jira Key | Status |
-|-------------|----------|--------|
-| {{title}}   | {{key}}  | ✓ Created |
-| {{title}}   | {{key}}  | ⊘ Skipped |
+| Story Title | Jira Key | Status | File Updated |
+|-------------|----------|--------|--------------|
+| {{title}}   | {{key}}  | ✓ Created | ✓ |
+| {{title}}   | {{key}}  | ⊘ Skipped | ✓ |
 
 ---
 
-### Epic File 2: {{filename}}
+### Epic 2: {{epic_name}} (File: {{filename}})
 
-**Epic:** {{epic_name}} → {{epic_key}} {{status}}
+**Epic in Jira:** {{epic_key}} {{status}}
+**Epic File:** ✓ Updated with Jira keys
+**Story Files Updated:** {{story_files_updated}}/{{story_files_found}}
 
-**Stories:**
+**Stories Created/Updated:**
 
-| Story Title | Jira Key | Status |
-|-------------|----------|--------|
-| {{title}}   | {{key}}  | ✓ Created |
-| {{title}}   | {{key}}  | ✓ Created |
+| Story Title | Jira Key | Status | File Updated |
+|-------------|----------|--------|--------------|
+| {{title}}   | {{key}}  | ✓ Created | ✓ |
+| {{title}}   | {{key}}  | ✓ Created | ✓ |
 
 ---
 
 ## Failed Items
 
-{{If any items failed}}
-
-| Item | Type | File | Error |
-|------|------|------|-------|
-| {{name}} | {{type}} | {{file}} | {{error}} |
+{{If any items failed during processing}}
 
-## Updated Files
-
-| File | Epic Key | Stories Updated | Status |
-|------|----------|-----------------|--------|
-| {{file}} | {{key}} | {{count}} | ✓ Updated |
+| Epic/Story | Type | File | Error | Files Updated? |
+|------------|------|------|-------|----------------|
+| {{name}} | {{type}} | {{file}} | {{error}} | {{yes/no}} |
 
 ## Next Steps
 
 1. Review created issues in Jira: {{jira_project_url}}
-2. {{If failures}} Retry failed items manually or after fixing configuration
-3. Verify all epic files have been updated with Jira keys
-4. Update story points and assignments as needed
-5. Add to sprint/backlog for planning
+2. {{If failures}} Review failed items table above. All successful epics were saved during processing.
+3. {{If failures}} To retry failed epics: Simply run the task again - successfully synced epics will be skipped automatically.
+4. Verify all epic files have been updated with Jira keys (check files in docs/prd/)
+5. Verify story files have Jira Information section (check files in docs/stories/)
+6. Update story points and assignments as needed in Jira
+7. Add to sprint/backlog for planning
 
 ## Traceability
 
-Epic files have been mapped to Jira as follows:
+All processed epic files have been updated with inline Jira keys during the sync process:
 
-| Epic File | Epic Key | Story Count |
-|-----------|----------|-------------|
-| {{file}}  | {{key}}  | {{count}}   |
+| Epic File | Epic Key | Stories | Epic File Updated | Story Files Updated |
+|-----------|----------|---------|-------------------|---------------------|
+| {{file}}  | {{key}}  | {{count}} | {{timestamp}} | {{count}} files |
 
-All epic files have been updated with inline Jira keys for future reference.
+**Note:** Each epic was processed atomically - Jira items created and files updated immediately before moving to the next epic. This ensures no references are lost if the process is interrupted.
 
 ---
 *Generated by PM Agent - sync-epic-files-to-jira task*
@@ -416,34 +506,46 @@ All epic files have been updated with inline Jira keys for future reference.
 
 **Manual verification steps:**
 
-- [ ] All new epics created with correct information
-- [ ] All new stories linked to appropriate epics
+**Jira Validation:**
+- [ ] All new epics created with correct information in Jira
+- [ ] All new stories linked to appropriate epics in Jira
 - [ ] Existing items were properly skipped (no duplicates)
 - [ ] Custom fields populated correctly
 - [ ] Labels applied for filtering
 - [ ] Descriptions formatted correctly
-- [ ] All epic files updated with Jira keys
-- [ ] Sync metadata added to each file
-- [ ] Links between files and Jira documented
+
+**File Validation:**
+- [ ] Each processed epic file has been updated with Jira keys (check in docs/prd/)
+- [ ] Sync metadata added to each epic file
+- [ ] Story headers in epic files have Jira keys
+- [ ] Story files in docs/stories updated with Jira Information section
+- [ ] Story files maintain proper naming convention ({epic-number}.{story-number}-*.md)
+- [ ] No temporary files left behind
+
+**Process Validation:**
+- [ ] If process was interrupted, check which epics have Jira keys (those are complete)
+- [ ] Failed epics are clearly identified in the report
+- [ ] Traceability is complete for all successful epics
 
 #### Step 10: Handoff
 
 ```elicit
 path: Complete sync process
 format: |
-  Epic files sync complete! 
-  
+  Epic files sync complete!
+
   Summary:
   - Epics Created: {{created_epics}}
   - Stories Created: {{created_stories}}
-  - Files Updated: {{updated_files}}
-  
+  - Epic Files Updated: {{updated_files}}
+  - Story Files Updated: {{updated_story_files}} (Jira Information added)
+
   Would you like to:
   1. View full sync report
   2. Open Jira project in browser
   3. Generate stakeholder notification
   4. Complete and exit
-  
+
   Enter selection (1-4):
 ```
 
@@ -475,16 +577,32 @@ format: |
 - **Solution:** Files must start with `epic-` to be detected
 - **Action:** Rename files or adjust scanning pattern
 
+**Issue:** Story files not found in docs/stories
+- **Solution:** Verify story files follow naming convention `{epic-number}.{story-number}-*.md`
+- **Action:** Task will log info message and continue (story files are optional)
+
+**Issue:** Story file already has Jira Information section
+- **Solution:** This is expected for previously processed files
+- **Action:** Skip file, no update needed
+
+**Issue:** Cannot write to story files in docs/stories
+- **Solution:** Check write permissions for docs/stories directory
+- **Action:** Log error for affected files, continue with remaining files
+
 ## Tips for Success
 
 1. **Start with Dry Run:** Set `dry_run_mode: true` for first sync to preview results
-2. **Check Existing Keys:** Review epic files for existing `[PM-XX]` keys before syncing
-3. **Use Force Mode Carefully:** Only force recreate when necessary to avoid duplicates
-4. **Backup Files First:** Commit or backup epic files before running sync
-5. **Consistent Formatting:** Ensure all epic files follow similar structure
-6. **Review After Sync:** Manually verify a few items in Jira to ensure correct mapping
-7. **Version Control:** Commit updated epic files after successful sync
-8. **Use Labels:** Leverage `epic-file-sync` label for easy filtering in Jira
+2. **Backup Files First:** Commit or backup epic files before running sync (though atomic processing minimizes risk)
+3. **Safe to Re-run:** If the process fails, just run it again - completed epics will be skipped automatically
+4. **Check Existing Keys:** Epic files with `[PM-XX]` keys are skipped to avoid duplicates
+5. **Monitor Progress:** Watch the console output - each epic completes fully before moving to the next
+6. **Interruption Recovery:** If interrupted, check which epic files have Jira keys - those are complete
+7. **Consistent Formatting:** Ensure all epic files follow similar structure for proper parsing
+8. **Review After Sync:** Manually verify a few items in Jira to ensure correct mapping
+9. **Version Control:** Files are updated during processing - commit after successful completion
+10. **Story File Naming:** Ensure story files in docs/stories follow naming pattern `{epic-number}.{story-number}-*.md`
+11. **Use Labels:** Leverage `epic-file-sync` label for easy filtering in Jira
+12. **Resume Failed Epics:** To retry only failed epics, simply re-run the task
 
 ## Integration with Other Tasks
 
@@ -508,6 +626,7 @@ Refer to the configuration file for detailed documentation of all available sett
 
 ---
 
-**Task Version:** 1.0.0
-**Last Updated:** 2025-12-11
+**Task Version:** 2.0.0
+**Last Updated:** 2025-12-21
+**Major Change:** Atomic processing model - each epic is fully processed (Jira + files) before moving to next
 **Dependencies:** MCP Jira Integration, jira-preferences.md, shard-prd task (optional)

package/claude/commands/BMad/agents/pm.md

@@ -34,6 +34,7 @@ activation-instructions:
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
   - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - JIRA CONFIGURATION CHECK: Before executing any Jira-related command (sync-prd-to-jira, create-epic, create-story), ALWAYS check if docs/jira-conf.md exists. If NOT found, inform user that project-specific Jira configuration is required and offer to run `*jira-setup` command to create it interactively.
 agent:
   name: John
   id: pm
@@ -68,6 +69,7 @@ commands:
   - create-prd: run task create-doc.md with template prd-tmpl.yaml
   - create-story: Create user story from requirements (task brownfield-create-story)
   - doc-out: Output full document to current destination file
+  - jira-setup: Configure Jira integration (provider, project, organization)
   - shard-prd: run the task shard-doc.md for the provided prd.md (ask if not found)
   - sync-epic-files-to-jira: Sync individual epic files from docs/prd/ to Jira (task sync-epic-files-to-jira.md)
   - sync-prd-to-jira: Automatically create Jira epics and stories from PRD (task sync-prd-to-jira.md)
@@ -87,6 +89,7 @@ dependencies:
     - create-deep-research-prompt.md
     - create-doc.md
     - execute-checklist.md
+    - jira-setup.md
     - shard-doc.md
     - sync-epic-files-to-jira.md
     - sync-prd-to-jira.md

package/claude/commands/BMad/agents/po.md

@@ -84,6 +84,7 @@ commands:
   - sync-epic-to-jira {epic-number}: Sync all approved stories from an epic to Jira (task sync-stories-batch-to-jira with scope epic-N)
   - update-epic-status {epic-number}: Batch update status of all stories in an epic (task update-epic-stories-jira-status)
   - validate-story-draft {story}: run the task validate-next-story against the provided story file
+  - create-user-guide: Run the task create-user-guide
   - yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
   - exit: Exit (confirm)
 dependencies:

package/github/chatmodes/pm.chatmode.md

@@ -35,6 +35,7 @@ activation-instructions:
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
   - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - JIRA CONFIGURATION CHECK: Before executing any Jira-related command (sync-prd-to-jira, create-epic, create-story), ALWAYS check if docs/jira-conf.md exists. If NOT found, inform user that project-specific Jira configuration is required and offer to run `*jira-setup` command to create it interactively.
 agent:
   name: John
   id: pm
@@ -66,6 +67,7 @@ commands:
   - create-prd: run task create-doc.md with template prd-tmpl.yaml
   - create-story: Create user story from requirements (task brownfield-create-story)
   - doc-out: Output full document to current destination file
+  - jira-setup: Configure Jira integration (provider, project, organization)
   - shard-prd: run the task shard-doc.md for the provided prd.md (ask if not found)
   - sync-epic-files-to-jira: Sync individual epic files from docs/prd/ to Jira (task sync-epic-files-to-jira.md)
   - sync-prd-to-jira: Automatically create Jira epics and stories from PRD (task sync-prd-to-jira.md)
@@ -85,6 +87,7 @@ dependencies:
     - create-deep-research-prompt.md
     - create-doc.md
     - execute-checklist.md
+    - jira-setup.md
     - shard-doc.md
     - sync-epic-files-to-jira.md
     - sync-prd-to-jira.md

package/package.json

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