siesa-agents 2.1.44 → 2.1.45

package/bmad/bmm/workflows/sync-epics-stories/steps/step-05-stories.md

@@ -0,0 +1,189 @@
+---
+name: 'step-05-stories'
+description: 'Synchronize Stories from markdown to Jira, linking to Parent Epics'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-05-stories.md'
+storiesFolder: '{output_folder}/implementation-artifacts/'
+epicsFile: '{output_folder}/planning-artifacts/epics.md'
+configFile: '{project-root}/_bmad-output/jira_docs/project_config.yaml'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+---
+
+# Step 5: Story Synchronization
+
+## STEP GOAL:
+
+To read story files from `{storiesFolder}`, link them to Parent Epics (found in `epics.md`), check existence in Jira, create missing stories, and update documentation.
+
+## MANDATORY EXECUTION RULES:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔒 **STRICT MCP ONLY:** You must ONLY use the provided MCP tools (`searchJiraIssuesUsingJql`, `createJiraIssue`, `addCommentToJiraIssue`).
+- ⛔ **FORBIDDEN:** Do NOT use `fetch`, `curl`, or raw HTTP requests.
+
+## EXECUTION SEQUENCE:
+
+### 1. Pre-flight Validation (Parent Check)
+
+1.  **Analyze Dependencies:**
+    -   Scan all markdown files in `{storiesFolder}`.
+    -   Extract all Parent Epic names/references.
+    -   Check `{epicsFile}` for these links.
+2.  **Verify Sync Status:**
+    -   For each Parent Epic:
+        -   Does it have a `[KEY-123]` (Jira Key) in the header?
+        -   If NO: Mark as `Unsynced`.
+3.  **Decision Gate:**
+    -   If `Unsynced` count > 0:
+        -   Display: "⚠️ CRITICAL: Found {{count}} Parent Epics that are not synced to Jira. Stories cannot be linked without Parent IDs."
+        -   Display: "**Unsynced Epics detected:** {{List of Epics}}"
+        -   **Prompt Menu:**
+            -   **[S]** Sync Epics First (Required)
+            -   **[E]** Exit Workflow
+        -   **Handler [S]:** Load and execute `{workflow_path}/steps/step-04-epics.md` IMMEDIATELY. (Note: Step 4 will ask to Continue back to this step if scope allows, or you must restart).
+        -   **Handler [E]:** Exit and terminate.
+    -   If All Parents Synced: **PROCEED** to Load Data.
+
+### 2. Load Data
+
+- Read `{configFile}`.
+- Get list of all `.md` files in `{storiesFolder}`.
+- Read `{epicsFile}` (to lookup Parent Epic IDs).
+
+### 3. Iterate and Sync
+
+For each markdown file in `{storiesFolder}`:
+
+1.  **Parse & Local Check (Prevention of Duplicates):**
+    -   Read file content.
+    -   **Check:** Does the file already contain a `**Jira Issue Key:**` [KEY-123] reference?
+    -   **Condition A (Already Synced Locally):**
+        -   If YES:
+            -   **Log:** "Story {{StoryName}} already synced locally as {{KEY}}."
+            -   **Extract:** The Jira Key (e.g., `KEY-123`) from the file to use in Step 6.
+            -   **ACTION:** **SKIP** Steps 2, 3, and 4.
+            -   **JUMP DIRECTLY** to **Step 6 (Sub-task Synchronization)**.
+    -   **Condition B (Not Synced):**
+        -   If NO: Proceed to Step 2.
+
+2.  **Resolve Parent (If Condition B):**
+    -   Find the parent Epic in `{epicsFile}` based on reference.
+    -   Extract its **Jira Issue Key** (e.g., KEY-1).
+    -   If no Key found: **SKIP Story** (Cannot link). Log failure.
+
+3.  **Remote Idempotency Check (If Condition B):**
+    -   Execute `searchJiraIssuesUsingJql`: `project = KEY AND issuetype in (Story, Historia) AND summary ~ "Story Name"`
+    -   **Condition Found (Remote Exists):**
+        -   If found:
+            -   **Log:** "Story {{StoryName}} found in Jira as {{FoundKEY}}."
+            -   **Set:** `{{KEY}}` = `{{FoundKEY}}`.
+            -   **Update Action:** APPEND the Jira Information block to the end of the file. **DO NOT rewrite existing content.**
+            -   **SKIP** Step 4 (Creation).
+            -   **PROCEED** to **Step 6 (Sub-task Synchronization)**.
+    -   **Condition Not Found:**
+        -   Proceed to Step 4.
+
+4.  **Creation (Atomic Transaction - If Condition Not Found):**
+    -   Execute `createJiraIssue` using the following REFERENCE TEMPLATE:
+
+    ```json
+    {
+      "provider": "jira",
+      "issueTypeName": "Story",
+      "projectKey": "{{project_key}}",
+      "summary": "{{Story Name}}",
+      "description": "## User Story\n{{user_story}}\n\n## Description\n{{description}}\n\n## Acceptance Criteria\n{{acceptance_criteria}}\n\n---\n*Source: {{file_path}}*",
+      "parent": "{{Parent_Epic_Key}}",
+      "additional_fields": {
+         "priority": { "name": "Medium" },
+         "labels": ["prd-sync", "automated", "epic-file-sync", "{{parent-epic-slug}}"],
+         "customfield_10014": "{{Parent_Epic_Key}}" // 'Epic Link' field. IMPORTANT: Check project capability for field ID.
+      }
+    }
+    ```
+    -   **Set:** `{{KEY}}` = New Issue Key.
+
+5.  **Immediate File Persistence (CRITICAL):**
+    -   **IMMEDIATELY** after obtaining the `key` (from Step 4):
+    -   Update the story file **RIGHT NOW**.
+    -   **Action:** Append the following block to the end of the file:
+
+    ```markdown
+
+    ## Jira Information
+
+    **Jira Issue Key:** [{{KEY}}]({{jira_url}}/browse/{{KEY}})
+    **Jira URL:** {{jira_url}}/browse/{{KEY}}
+    **Status:** Synced
+    ```
+
+6.  **Sub-task Synchronization (Hierarchical Sync & Validation):**
+    -   **Prerequisite:** Ensure we have a valid `{{KEY}}` for the Parent Story. If ID is missing, SKIP sub-tasks.
+    -   **Goal:** Sync items from `## Tasks / Subtasks` to Jira as Sub-tasks, avoiding duplicates.
+    -   **Action:**
+        1.  **Parse Sync Table:** Read the `## Synced Tasks` table at the bottom of the file (if it exists).
+            -   Create a list/set of *already synced tasks* by minimizing/normalizing the "Task Name" column.
+        2.  **Locate Source Tasks:** Find `## Tasks / Subtasks` section.
+            -   If missing: Log "No Tasks section". **CONTINUE** to next file.
+        3.  **Iterate:** For each **Level 1 Bullet Point** (The Task) in the source list:
+            -   **Validation (Idempotency):**
+                -   Check: Is `{{Task Name}}` already present in the *already synced tasks* list?
+                -   **If YES:** **SKIP** this task. Log "Task '{{Task Name}}' already synced."
+                -   **If NO:** **PROCEED** to Create.
+            -   **Create:** Execute `createJiraIssue`:
+                ```json
+                {
+                  "provider": "jira",
+                  "issueTypeName": "Sub-task",
+                  "projectKey": "{{project_key}}",
+                  "parent": "{{KEY}}",
+                  "summary": "{{Task Text}}"
+                }
+                ```
+            -   **Context:** If the task has nested items (indented bullets), combine them into a **simple markdown bulleted list** (ensuring no checklist `[ ]` syntax is used) and execute `addCommentToJiraIssue`:
+                ```json
+                {
+                   "issueIdOrKey": "{{New_SubTask_Key}}",
+                   "commentBody": "## Details\n\n{{nested_bullets_content}}"
+                }
+                ```
+            -   **Persistence (Append Update):**
+                -   **Immediately** append a new row to the `## Synced Tasks` table (create table header if it doesn't exist yet):
+                ```markdown
+                | {{Task Name}} | [{{SubTaskKey}}]({{url}}) | Synced | {{Date}} |
+                ```
+                *(Ensure the table structure is maintained)*
+
+### 4. Report Results
+
+Display summary: "Created: X, Skipped: Y, Failed: Z".
+
+### 5. Present MENU OPTIONS
+
+Display: "**Stories Synced - Select an Option:** [C] Finish"
+
+#### Menu Handling Logic:
+
+- IF C: Display "Workflow Complete. All artifacts synchronized." and exit.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Stories processed and linked to Epics
+- No duplicates
+- `stories.md` updated
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/bmad/bmm/workflows/sync-epics-stories/workflow-plan-sync-epics-stories.md

@@ -0,0 +1,252 @@
+---
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
+---
+
+# Workflow Creation Plan: sync-epics-stories
+
+## Initial Project Context
+
+- **Module:** bmm
+- **Target Location:** _bmad-output/bmb-creations/workflows/sync-epics-stories
+- **Created:** 2026-01-13
+
+## Detailed Requirements
+
+### 1. Workflow Purpose and Scope
+- **Problem:** Synchronize epics and user stories documentation generated by Bmad (Markdown files) with a Jira project.
+- **User:** Product Owner (PO) Team.
+- **Main Outcome:**
+  - Validated Jira configuration.
+  - Epics and Stories created/synced in Jira.
+  - Local documentation (`epics.md`, `stories.md`) updated with Jira Issue Keys and sync status.
+
+### 2. Workflow Type
+- **Type:** **Action Workflow** with interactive setup and decision points (Branching).
+
+### 3. Workflow Flow and Structure (Action & Branching)
+The workflow will follow a phased approach as detailed in `_bmad/bmm/data/docs.md`:
+
+**Phase 0: Initialization & Configuration (Jira Setup Task)**
+1.  **Check Config:** Check for `_bmad/jira_docs/project_config.yaml`.
+2.  **Authenticate/Validate:** Use MCP to get accessible resources (Cloud ID).
+3.  **Project Key:** Elicit from user.
+4.  **Verify Access:** Use MCP to verify project access and get project name/URL.
+5.  **Save Config:** Create/Update `project_config.yaml`.
+
+**Phase 1: Bifurcation (Scope Selection)**
+- User selects: [1] Epics, [2] Stories, [3] Both.
+
+**Phase 2: Epic Synchronization (if selected)**
+1.  **Load:** Read `_bmad-output/planning-artifacts/epics.md`.
+2.  **Iterate:**
+    - Check for existence in Jira (Idempotency check via JQL).
+    - Create if missing (Issue Type: "Epic").
+3.  **Update:** Append "Jira Sync Status" to `epics.md`.
+4.  **Report:** Summary of created/skipped/failed.
+
+**Phase 3: Story Synchronization (if selected)**
+1.  **Load:** Read `_bmad-output/planning-artifacts/stories.md`.
+2.  **Iterate:**
+    - **Resolve Parent:** Find Jira Key of parent Epic from `epics.md`. Skip if missing.
+    - Check for existence in Jira (Idempotency check).
+    - Determine Issue Type ("Story" or localized "Historia").
+    - Create if missing (linked to Parent Epic).
+3.  **Update:** Append "Jira Sync Status" to `stories.md`.
+4.  **Report:** Summary of created/skipped/failed.
+
+### 4. User Interaction Style
+- **Collaborative Setup:** Guided setup for credentials and project selection.
+- **Autonomous Execution:** Once configured and scope selected, the sync process runs largely autonomously, reporting progress.
+
+### 5. Instruction Style
+- **Prescriptive:** Specific steps for MCP calls, strict rules for idempotency, and exact formatting for updating markdown files.
+
+### 6. Input Requirements
+- **Configuration:** Jira Project Key, User Authentication (via MCP).
+- **Files:** `_bmad-output/planning-artifacts/epics.md`, `_bmad-output/planning-artifacts/stories.md`.
+
+### 7. Output Specifications
+- **Jira:** Created Epics and Stories.
+- **Local Files:** Updated `epics.md` and `stories.md` with sync status/links.
+- **Config File:** `_bmad/jira_docs/project_config.yaml`.
+- **Console:** Progress logs and final summary reports.
+
+### 8. Success Criteria
+- **Zero Duplication:** Idempotency checks prevent creating duplicate tickets.
+- **Correct Linking:** Stories are correctly linked to their parent Epics in Jira.
+- **Traceability:** Local files contain direct links and IDs of created Jira issues.
+- **Stability:** Handles authentication failures or missing files gracefully.
+
+### 9. Technical Specifics (from docs.md)
+- **MCP Server:** `mcp-atlassian` (or equivalent provided environment).
+- **Tools:** `getAccessibleAtlassianResources`, `getVisibleJiraProjects`, `createJiraIssue`, `searchJiraIssuesUsingJql`.
+- **Structure:** Sequential steps with a central branching menu.
+
+## Tools Configuration
+
+### Core BMAD Tools
+
+- **Party-Mode**: Excluded (Technical workflow)
+- **Advanced Elicitation**: Excluded (Technical workflow)
+- **Brainstorming**: Excluded (Technical workflow)
+
+### LLM Features
+
+- **Web-Browsing**: Included - Use cases: Lookup Jira error codes or API nuances if needed.
+- **File I/O**: Included - Operations: Read/Write markdown files and config.
+- **Sub-Agents**: Excluded - Single thread execution for reliability.
+- **Sub-Processes**: Excluded.
+
+### Memory Systems
+
+- **Sidecar File**: Included - Purpose: Backup context and session persistence.
+
+### External Integrations
+
+- **MCP Atlassian (Jira)**: Essential.
+    - `getAccessibleAtlassianResources`
+    - `getVisibleJiraProjects`
+    - `createJiraIssue`
+    - `searchJiraIssuesUsingJql`
+
+### Installation Requirements
+
+- **mcp-atlassian**: Must be installed and authenticated via `/mcp auth mcp-atlassian`.
+
+## Output Format Design
+
+**Format Type**: Mixed (Strict Template & Structured)
+
+**Output Requirements**:
+- **Configuration**: YAML file (`project_config.yaml`)
+- **Status Updates**: Markdown blocks appended to existing files (`epics.md`, `stories.md`)
+- **File Format**: YAML, Markdown
+
+**Structure Specifications**:
+
+**A. Configuration (`project_config.yaml`) - Strict Template:**
+```yaml
+project_key: "{{PROJECT_KEY}}"
+project_name: "{{PROJECT_NAME}}"
+cloud_id: "{{CLOUD_ID}}"
+jira_url: "{{JIRA_URL}}"
+```
+
+**B. Sync Status Block (`.md` append) - Structured:**
+```markdown
+### Jira Sync Status
+- **Status:** {{Synced | Skipped | Failed}}
+- **Issue Key:** {{JIRA-KEY}}
+- **Issue ID:** {{issue_id}}
+- **Link:** {{issue_url}}
+- **Last Sync:** {{timestamp}}
+- **Notes:** {{notes}}
+- **Last Updated:** {{current_date}}
+```
+
+**Template Information**:
+- **Source**: Defined in workflow plan.
+- **Placeholders**: `{{PROJECT_KEY}}`, `{{CLOUD_ID}}`, `{{JIRA-KEY}}`, etc.
+
+**Special Considerations**:
+- **Idempotency**: Must check existence before creating.
+- **Traceability**: Must log specific Issue Keys to enable linking.
+
+## Workflow Structure Design
+
+### 1. Structure Overview
+- **Type**: Multi-session Action Workflow
+- **Role**: Jira Integration Specialist
+- **Continuation Support**: YES (`step-01-init` + `step-01b-continue`)
+
+### 2. Step Sequence
+
+**Step 1: Init (`step-01-init.md`)**
+- **Goal:** Detect existing workflow state or initialize.
+- **Logic:** Check for `stepsCompleted` in output files.
+- **Route:** Go to `step-01b` if resuming, or `step-02` for fresh run.
+
+**Step 1b: Continue (`step-01b-continue.md`)**
+- **Goal:** Resume context and route to the next pending step.
+
+**Step 2: Configuration & Setup (`step-02-setup.md`)**
+- **Goal:** Validate Jira configuration and access.
+- **Actions:**
+  - Check/Create `_bmad/jira_docs/project_config.yaml`.
+  - Authenticate via MCP (`getAccessibleAtlassianResources`).
+  - Elicit `project_key` if missing.
+  - Verify access (`getVisibleJiraProjects`).
+- **Output:** Validated configuration.
+
+**Step 3: Scope Selection (`step-03-scope.md`)**
+- **Goal:** User selects synchronization scope.
+- **Menu Options:**
+  - [1] **Epics Only** -> Load `step-04-epics.md`.
+  - [2] **Stories Only** -> Load `step-05-stories.md`.
+  - [3] **Both** -> Load `step-04-epics.md` (with logic to chain to `step-05`).
+
+**Step 4: Epic Synchronization (`step-04-epics.md`)**
+- **Goal:** Sync `epics.md` to Jira.
+- **Actions:**
+  - Read `epics.md`.
+  - For each epic: Check existence (JQL) -> Create if missing (MCP) -> Update `epics.md`.
+- **Logic:** If scope was "Both", load `step-05` next. Else, finish.
+
+**Step 5: Story Synchronization (`step-05-stories.md`)**
+- **Goal:** Sync `stories.md` to Jira, linking to Epics.
+- **Actions:**
+  - Read `stories.md`.
+  - For each story: Find Parent Epic ID -> Check existence -> Create (linked) -> Update `stories.md`.
+- **Completion:** Final report and workflow finish.
+
+### 3. File Structure
+- `.../workflows/sync-epics-stories/`
+  - `workflow.md` (Main entry)
+  - `steps/`
+    - `step-01-init.md`
+    - `step-01b-continue.md`
+    - `step-02-setup.md`
+    - `step-03-scope.md`
+    - `step-04-epics.md`
+    - `step-05-stories.md`
+
+### 4. Data Flow
+- **Inputs:** `project_config.yaml`, `epics.md`, `stories.md`, Jira API (MCP).
+- **State:** Tracked in file frontmatter (`stepsCompleted`) and markdown content updates.
+- **Outputs:** Created Jira Issues, updated markdown files.
+
+## Build Summary
+
+**Generated Files:**
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/workflow.md`
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/steps/step-01-init.md`
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/steps/step-01b-continue.md`
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/steps/step-02-setup.md`
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/steps/step-03-scope.md`
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/steps/step-04-epics.md`
+- `_bmad-output/bmb-creations/workflows/sync-epics-stories/steps/step-05-stories.md`
+
+**Status:**
+- All files created successfully.
+- Structure aligns with approved plan.
+- Ready for review.
+
+## Review and Completion
+
+### Review Findings
+- **File Structure**: Correctly mirrors the standard BMAD structure.
+- **Configuration**: All paths use dynamic placeholders (`{project-root}`, etc.) for portability.
+- **Compliance**: Steps follow the micro-file architecture (one step, one file).
+- **Logic**: Continuation logic is properly implemented in Steps 1 and 1b.
+
+### Deployment
+- **Path**: `_bmad-output/bmb-creations/workflows/sync-epics-stories/workflow.md`
+- **Execution**: Can be run immediately by an agent pointing to this path.
+- **Testing**:
+  1. Ensure `mcp-atlassian` is authenticated.
+  2. Ensure `epics.md` and `stories.md` exist in `_bmad-output/planning-artifacts/`.
+  3. Run the workflow.
+
+### Final Approval
+- User approved the design and build.
+- Workflow ready for production use.

package/bmad/bmm/workflows/sync-epics-stories/workflow.md

@@ -0,0 +1,54 @@
+---
+name: sync-epics-stories
+description: Synchronize Bmad generated epics and stories documentation with Jira
+web_bundle: true
+---
+
+# Sync Epics & Stories
+
+**Goal:** Synchronize epics and user stories documentation generated by Bmad (Markdown files) with a Jira project, ensuring zero duplication and correct linking.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a **Jira Integration Specialist** collaborating with the **Product Owner Team**. This is a partnership, not a client-vendor relationship. You bring **technical precision and Jira API expertise**, while the user brings **product requirements**. Work together as equals.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/bmm/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `{project-root}/_bmad/bmm/workflows/sync-epics-stories/steps/step-01-init.md` to begin the workflow.

package/claude/commands/bmad/bmm/workflows/sync-epics-stories.md

@@ -0,0 +1,5 @@
+---
+description: 'Sync Epics and Stories'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/sync-epics-stories/workflow.md, READ its entire contents and follow its directions exactly!

package/gemini/commands/bmad-workflow-bmm-sync-epics-stories.toml

@@ -0,0 +1,4 @@
+description = "BMAD BMM Workflow: sync-epics-stories"
+prompt = """
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/sync-epics-stories/workflow.md, READ its entire contents and follow its directions exactly!
+"""

package/package.json

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