siesa-agents 2.1.43 → 2.1.45

package/bmad/bmm/workflows/5-documentation/create-user-guide/workflow.md

@@ -0,0 +1,61 @@
+---
+name: create-user-guide
+description: Genera guías de usuario comprehensivas en español e inglés desde épicas y PRDs, con diagramas Mermaid y trazabilidad completa
+web_bundle: true
+---
+
+# Create User Guide
+
+**Goal:** Generar guías de usuario comprehensivas desde documentación existente (PRDs, épicas, stories) para diferentes audiencias (usuarios finales, administradores, consumidores de API). Producir guías en español e inglés con diagramas Mermaid, screenshot placeholders, trazabilidad a fuentes y estructura navegable.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a technical writer and documentation specialist (Marcus ✍️) collaborating with Product Managers, Technical Writers, and documentation teams. This is a partnership, not a client-vendor relationship. You bring expertise in documentation structure, technical writing, and user experience, while the user brings their domain knowledge and specific project requirements. Work together as equals.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. 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`
+- `planning_artifacts`, `implementation_artifacts`, `project_knowledge`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.

package/bmad/bmm/workflows/sync-epics-stories/completion-summary-sync-epics-stories.md

@@ -0,0 +1,43 @@
+---
+workflowName: sync-epics-stories
+creationDate: 2026-01-13
+module: bmm
+status: COMPLETE
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9]
+---
+
+# Workflow Creation Summary
+
+## Workflow Information
+
+- **Name:** sync-epics-stories
+- **Module:** bmm (Created via bmb-creations)
+- **Created:** 2026-01-13
+- **Location:** _bmad-output/bmb-creations/workflows/sync-epics-stories
+
+## Generated Files
+
+- `workflow.md`
+- `steps/step-01-init.md`
+- `steps/step-01b-continue.md`
+- `steps/step-02-setup.md`
+- `steps/step-03-scope.md`
+- `steps/step-04-epics.md`
+- `steps/step-05-stories.md`
+
+## Quick Start Guide
+
+**To run this workflow:**
+
+1.  Ensure you have `mcp-atlassian` configured and authenticated.
+2.  Ensure you have your artifacts ready at:
+    - `_bmad-output/planning-artifacts/epics.md`
+    - `_bmad-output/planning-artifacts/stories.md`
+3.  Command an agent to run the workflow:
+    > "Execute the workflow at `_bmad-output/bmb-creations/workflows/sync-epics-stories/workflow.md`"
+
+## Next Steps
+
+1.  **Run a Test:** Execute the workflow with a small set of epics/stories (or backups) first.
+2.  **Verify Jira:** Check that issues are created correctly and linked.
+3.  **Check Docs:** Verify that your local markdown files are updated with the Sync Status blocks.

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

@@ -0,0 +1,150 @@
+---
+name: 'step-01-init'
+description: 'Initialize the Jira synchronization workflow by detecting continuation state'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-setup.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{project-root}/_bmad-output/jira_docs/project_config.yaml' # Using config file as main state tracker
+continueFile: '{workflow_path}/steps/step-01b-continue.md'
+# Input Files
+epicsFile: '{output_folder}/planning-artifacts/epics.md'
+storiesFolder: '{output_folder}/implementation-artifacts/'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+---
+
+# Step 1: Workflow Initialization
+
+## 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
+
+### Role Reinforcement:
+
+- ✅ You are a Jira Integration Specialist
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring technical precision, user brings product requirements
+- ✅ Maintain collaborative and precise tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization and setup
+- 🚫 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 are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+
+## STEP GOAL:
+
+To initialize the synchronization workflow by detecting continuation state, verifying input files, and preparing for setup.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow State
+
+First, check if the project configuration already exists:
+
+- Look for file at `{outputFile}` (`_bmad-output/jira_docs/project_config.yaml`)
+- If exists, read the complete file including any frontmatter or comments
+- **Note:** This workflow tracks state in the config file or within the markdown files themselves. For this step, we check if we have a valid config to potentially resume.
+
+### 2. Handle Continuation (If Config Exists)
+
+If the config file exists AND has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `{continueFile}` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup
+
+If no config exists or no `stepsCompleted`:
+
+#### A. Input Document Discovery
+
+This workflow requires existing artifacts:
+
+- Check existence of `{epicsFile}`
+- Check for Markdown files in `{storiesFolder}` (e.g., `*.md`)
+
+If files are missing, WARN the user: "I cannot find `epics.md` or any story files in `implementation-artifacts/`. Please ensure artifacts exist before synchronizing."
+
+#### B. Create Initial State (Virtual)
+
+Since `project_config.yaml` is a strict YAML file, we might not want to pollute it with frontmatter if it's used by other tools.
+**Decision:** We will manage `stepsCompleted` in a virtual state or append it as a comment block if supported, OR we treat the *first run* as creating the config in Step 2.
+
+For this Initialization Step, if no config exists, we simply proceed to Step 2 to create it.
+
+#### C. Show Welcome Message
+
+"Welcome to the **Jira Synchronization Workflow**.
+
+I am your Jira Integration Specialist. I will help you synchronize your Epics and Stories with Jira.
+
+We will:
+1.  Configure/Validate your Jira Connection.
+2.  Select what to synchronize (Epics, Stories, or Both).
+3.  Execute the synchronization with duplicate prevention."
+
+## ✅ SUCCESS METRICS:
+
+- Input files verified
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR continuation properly routed to step-01b-continue.md
+
+### 4. Present MENU OPTIONS
+
+Display: **Proceeding to Jira Setup...**
+
+#### Menu Handling Logic:
+
+- Immediately load, read entire file, then execute `{nextStepFile}` to begin setup.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Input files verified
+- User welcomed
+- Ready to proceed to step 2
+- OR existing workflow routed to step-01b
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without checking input files
+- Not routing to step-01b when appropriate
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete, will you then immediately load, read entire file, then execute `{nextStepFile}` to begin setup.

package/bmad/bmm/workflows/sync-epics-stories/steps/step-01b-continue.md

@@ -0,0 +1,79 @@
+---
+name: 'step-01b-continue'
+description: 'Handle workflow continuation from previous session'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+outputFile: '{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 1B: Workflow Continuation
+
+## STEP GOAL:
+
+To resume the synchronization workflow from where it was left off, ensuring smooth continuation without loss of context.
+
+## 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
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on analyzing and resuming workflow state
+- 🚫 FORBIDDEN to modify content completed in previous steps
+- 🚪 DETECT exact continuation point from `stepsCompleted`
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current State
+
+Review the `stepsCompleted` in `{outputFile}` (if available) or ask the user.
+
+- **stepsCompleted: [1, 2]** -> Completed Setup. Next: Scope Selection (Step 3).
+- **stepsCompleted: [1, 2, 3]** -> Scope Selected. Next: Execution (Step 4 or 5 depending on scope, but usually Step 3 loops to menu).
+- **stepsCompleted: [1, 2, 3, 4]** -> Epics synced. Next: Stories (Step 5) or Finish.
+
+### 2. Determine Next Step
+
+Based on analysis:
+- If Setup (2) done -> Go to Step 3 (Scope).
+- If Epics (4) done -> Go to Step 3 (Scope) or Step 5 (Stories) if previously selected "Both".
+
+### 3. Welcome Back Dialog
+
+"Welcome back! We have an existing configuration.
+Last completed step: [Analyze last step].
+
+Ready to continue?"
+
+### 4. Present MENU OPTIONS
+
+Display: "**Resuming - Select an Option:** [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute the determined next step file.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Correctly identified last completed step
+- User confirmed readiness
+- Workflow resumed at appropriate next step
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

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

@@ -0,0 +1,117 @@
+---
+name: 'step-02-setup'
+description: 'Configure and validate Jira integration'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-02-setup.md'
+nextStepFile: '{workflow_path}/steps/step-03-scope.md'
+outputFile: '{project-root}/_bmad-output/jira_docs/project_config.yaml'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+---
+
+# Step 2: Jira Configuration & Setup
+
+## STEP GOAL:
+
+To configure the Jira integration by authenticating via MCP, validating project access, and saving the configuration file.
+
+## MANDATORY EXECUTION RULES:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A JIRA INTEGRATION SPECIALIST
+- 🔒 **STRICT MCP ONLY:** You must ONLY use the provided MCP tools. NO curl, NO fetch, NO custom API calls.
+
+## EXECUTION SEQUENCE:
+
+### 1. 🔒 PRE-FLIGHT CHECK: MCP Authentication
+
+**CRITICAL FIRST STEP:** Before reading any files or configurations, verify we can talk to Jira.
+
+**Action:** Execute MCP Tool `getAccessibleAtlassianResources`.
+
+-   **FAILURE CONDITION:** If the tool fails, returns an error, or returns an empty list `[]`.
+    -   **STOP IMMEDIATELY.**
+    -   **Display Error:** "❌ **MCP Authentication Failed.** I cannot connect to Jira. Please ensure you are authenticated with the Atlassian MCP server."
+    -   **Instruction:** "Run the following command to authenticate (copy and paste into your terminal/chat):"
+    -   **Display:**
+        ```bash
+        /mcp auth mcp-atlassian
+        ```
+    -   **Display Info:**
+        ```text
+        ℹ  Note: Authentication requires completing an OAuth flow in your web browser.
+           Follow the on-screen instructions provided by the CLI after running the command.
+        ```
+    -   **Instruction:** "After validating in the browser, please choose an option:"
+    -   **Menu:**
+        -   **[R] Retry Authentication:** Re-run the check (`getAccessibleAtlassianResources`).
+        -   **[E] Exit:** Stop the workflow.
+    -   **Logic:**
+        -   **IF R:** Restart this Step 2 from the beginning.
+        -   **IF E:** Terminate the workflow with a message: "Workflow aborted due to authentication failure."
+    -   **DO NOT PROCEED** past this point without successful authentication.
+
+-   **SUCCESS CONDITION:** If the tool returns a valid list of resources.
+    -   Proceed to Section 2.
+
+### 2. Check Existing Configuration
+
+Check if `{outputFile}` exists.
+- If YES: Read and Display current settings (Project Key, Cloud ID). Ask: "Do you want to use this configuration? [Y/N]"
+- If NO: Proceed to setup.
+
+### 3. Elicit Project Key
+
+If not already known (from config), ask: "Please enter your Jira Project Key (e.g., PROJ, SCRUM):"
+
+### 4. Validate Project Access
+
+**Action:** Execute MCP Tool `getVisibleJiraProjects` with `cloudId` and search for `projectKey`.
+
+- **Success:** Confirm Project Name and Key match.
+- **Failure:** Stop and ask user to check permissions or key.
+
+### 5. Save Configuration
+
+Create/Update `{outputFile}` with:
+
+```yaml
+project_key: "{{project_key}}"
+project_name: "{{project_name}}"
+cloud_id: "{{cloud_id}}"
+jira_url: "https://siesa-team.atlassian.net"
+# stepsCompleted: [1, 2] # (Optional tracking)
+```
+
+### 6. Present MENU OPTIONS
+
+Display: "**Configuration Complete - Select an Option:** [C] Continue to Scope Selection"
+
+#### Menu Handling Logic:
+
+- IF C: Save content to `{outputFile}`, load, read entire file, then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Valid `project_config.yaml` created
+- Access verified via MCP
+- User confirmed configuration
+
+### ❌ SYSTEM FAILURE:
+
+- Creating config with invalid credentials
+- Skipping MCP validation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

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

@@ -0,0 +1,70 @@
+---
+name: 'step-03-scope'
+description: 'Select synchronization scope (Epics, Stories, or Both)'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-03-scope.md'
+stepEpics: '{workflow_path}/steps/step-04-epics.md'
+stepStories: '{workflow_path}/steps/step-05-stories.md'
+outputFile: '{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 3: Scope Selection
+
+## STEP GOAL:
+
+To determine the scope of synchronization: Epics, Stories, or Both.
+
+## MANDATORY EXECUTION RULES:
+
+- 🛑 **STOP AND WAIT:** You MUST halt execution at the menu options. Do NOT proceed until the user explicitly selects an option.
+- 🛑 **NO AUTO-PILOT:** Even if you "think" you know what the user wants based on available files, you MUST ask.
+- 📖 **READ FIRST:** Read the complete step file before taking any action.
+
+## EXECUTION SEQUENCE:
+
+### 1. Present Options
+
+"**Select Synchronization Scope:**
+
+1.  **Epics Only** (Syncs `epics.md` -> Jira Epics)
+2.  **Stories & Tasks** (Syncs `stories.md` -> Jira Stories & Sub-tasks, requires Parent Epics to exist)
+3.  **Both** (Syncs Epics first, then Stories & Tasks)"
+
+### 2. Handle Selection
+
+**Logic:**
+
+- **Option 1 (Epics):** Load `{stepEpics}`. Set next step after Epics to "Finish".
+- **Option 2 (Stories):** Load `{stepStories}`.
+- **Option 3 (Both):** Load `{stepEpics}`. Set next step after Epics to `{stepStories}` (Chain).
+
+### 3. Present MENU OPTIONS
+
+Display: "**Select Scope:** [1] Epics [2] Stories & Tasks [3] Both"
+
+#### Menu Handling Logic:
+
+- IF 1: Update frontmatter `target_scope: epics`, load `{stepEpics}`.
+- IF 2: Update frontmatter `target_scope: stories`, load `{stepStories}`.
+- IF 3: Update frontmatter `target_scope: both`, load `{stepEpics}` (and pass flag to chain next step).
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- User selection captured
+- Correct next step loaded
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

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

@@ -0,0 +1,124 @@
+---
+name: 'step-04-epics'
+description: 'Synchronize Epics from markdown to Jira'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-04-epics.md'
+nextStepStories: '{workflow_path}/steps/step-05-stories.md'
+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 4: Epic Synchronization
+
+## STEP GOAL:
+
+To read `epics.md`, check for existing Epics in Jira, create missing ones, and update the markdown file with synchronization status.
+
+## 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`).
+- ⛔ **FORBIDDEN:** Do NOT use `fetch`, `curl`, or raw HTTP requests.
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Data
+
+- Read `{configFile}` to get `project_key` and `cloud_id`.
+- Read `{epicsFile}`.
+
+### 2. Iterate and Sync
+
+For each Epic in the file:
+
+1.  **Local Idempotency Check (CRITICAL):**
+    -   Check if the Epic Title in the markdown ALREADY contains a Jira Key (e.g., `[PROJ-123]`).
+    -   If found: **SKIP creation**. Log Key.
+    -   If not found: Proceed to JQL check.
+
+2.  **Remote Idempotency Check:**
+    -   Execute `searchJiraIssuesUsingJql`: `project = KEY AND issuetype = Epic AND summary ~ "Epic Name"`
+    -   If found: **SKIP creation**. Log Key. Update markdown with found key.
+    -   If not found: **PROCEED**.
+
+    3.  **Creation (Atomic Transaction):**
+
+        -   Execute `createJiraIssue` using the following REFERENCE TEMPLATE:
+
+        -   ⚠️ **CRITICAL CONSTRAINT:** `issueTypeName` MUST be exactly `"Epic"`. DO NOT translate to "Épica" or any other language. The API requires the English identifier.
+
+        
+
+        ```json
+
+        {
+
+          "provider": "jira",
+
+          "issueTypeName": "Epic",
+
+          "summary": "[Epic] {{Epic Name}}",
+
+
+      "description": "## Epic Goal\n{{goal}}\n\n## Details\n{{description}}\n\n---\n*Source: {{file_path}}*",
+      "projectKey": "{{project_key}}",
+      "additional_fields": {
+         "priority": { "name": "Medium" },
+         "labels": ["prd-sync", "automated", "epic-file-sync", "{{epic-slug}}"],
+         "customfield_10011": "{{Epic Name}}"
+      }
+    }
+    ```
+
+4.  **Immediate File Persistence (CRITICAL):**
+    -   **IMMEDIATELY** after obtaining the new `key` (or finding an existing one):
+    -   Update `{epicsFile}` **RIGHT NOW**. Do not wait for the loop to finish.
+    -   **Action:**
+        1.  Append/Update the `[Key]` to the Epic Header in the file.
+        2.  Append a "Jira Information" block at the end of the Epic section:
+            ```markdown
+            > **Jira Sync:** [{{KEY}}]({{jira_url}}/browse/{{KEY}}) | Status: Synced
+            ```
+    -   *Why?* This ensures that if the process fails at Epic #5, Epics #1-4 are safely saved.
+
+### 3. Report Results
+
+Display summary: "Created: X, Skipped: Y, Failed: Z".
+
+### 4. Determine Next Step
+
+- If `target_scope` was "Both", proceed to Stories.
+- Else, Finish.
+
+### 5. Present MENU OPTIONS
+
+Display: "**Epics Synced - Select an Option:** [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF C:
+  - If scope == both: Load `{nextStepStories}`.
+  - Else: Display "Workflow Complete" and exit.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics processed
+- No duplicates created
+- `epics.md` updated with IDs
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.