siesa-agents 2.1.33 → 2.1.34

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/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.33",
+  "version": "2.1.34",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {