npm - siesa-agents - Versions diffs - 2.1.36 → 2.1.38 - Mend

siesa-agents 2.1.36 → 2.1.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (869) hide show

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

@@ -1,632 +0,0 @@
-<!-- Powered by BMAD™ Core -->
-# Sync Epic Files to Jira Task
-## Purpose
-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
-**Use this task when:**
-- You have already developed epics/stories in separate markdown files
-- Jira was never synchronized during development
-- You need to retroactively populate Jira from existing documentation
-- Each epic has been "sharded" into individual files in `docs/prd/`
-**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
-#### Step 0: Validate Jira Authentication (REQUIRED)
-**CRITICAL:** Validate authentication BEFORE any Jira operations
-**Action:** Execute authentication check
-- [ ] Call `validate-jira-auth.md` task
-- [ ] Verify authentication is active
-- [ ] Only proceed if validation passes
-**If validation fails:** HALT and instruct user to re-authenticate via MCP panel before continuing.
----
-#### Step 1: Load Jira Preferences
-```elicit
-path: Load the Jira preferences file
-format: |
-  Loading Jira configuration from: `.bmad-core/data/jira-preferences.md`
-  Please confirm the following settings:
-  - Provider: {{provider}}
-  - Project Key: {{project_key}}
-  - Create Epics First: {{create_epics_first}}
-  - Dry Run Mode: {{dry_run_mode}}
-  Type 'proceed' to continue, or 'edit' to modify preferences first.
-```
-#### Step 2: Scan Epic Files
-**Action:** Scan `docs/prd/` directory for epic files
-- [ ] List all files in `docs/prd/` directory
-- [ ] Filter files matching pattern `epic-*.md` (exclude `epic-list.md`)
-- [ ] Sort files by epic number (epic-1, epic-2, etc.)
-- [ ] Validate each file has valid epic structure
-**Expected Output:**
-```markdown
-## Found Epic Files:
-1. docs/prd/epic-1-foundation-category-management-pm-6httpssiesa-test-sandboxatlassiannetbrowsepm-6.md
-2. docs/prd/epic-2-task-management-core-pm-7httpssiesa-test-sandboxatlassiannetbrowsepm-7.md
-3. docs/prd/epic-3-task-filtering-api-polish-pm-8httpssiesa-test-sandboxatlassiannetbrowsepm-8.md
-Total: {{file_count}} epic files detected
-```
-#### Step 3: Parse Epic Files
-**For each epic file found:**
-1. **Read File Content:**
-   - Load markdown content
-   - Extract epic metadata from header/title
-   - Identify story sections within the file
-2. **Extract Epic Information:**
-   - Epic Name: From first `# Epic` header
-   - Epic Goal: From **Goal:** section
-   - Existing Jira Key: Check if already linked `[PM-XX]`
-   - Description: Content before first story
-3. **Extract Stories:**
-   - Parse each `## Story` section
-   - Extract story title, user story format, acceptance criteria
-   - Check if story already has Jira key `[PM-XX]`
-**Expected Output:**
-```markdown
-## Parsed Epic Files:
-### Epic 1: Foundation & Category Management
-- File: docs/prd/epic-1-foundation-category-management-pm-6httpssiesa-test-sandboxatlassiannetbrowsepm-6.md
-- Existing Jira Key: PM-6 (SKIP if found)
-- Stories: 4
-  - Story 1.1: Project Scaffolding and Clean Architecture Setup [PM-9]
-  - Story 1.2: PostgreSQL Database Configuration [PM-10]
-  - Story 1.3: Category Repository Setup [PM-11]
-  - Story 1.4: Category API Endpoints [PM-12]
-### Epic 2: Task Management Core
-- File: docs/prd/epic-2-task-management-core-pm-7httpssiesa-test-sandboxatlassiannetbrowsepm-7.md
-- Existing Jira Key: PM-7 (SKIP if found)
-- Stories: 4
-  - Story 2.1: Task Entity and Database Configuration [PM-13]
-  - Story 2.2: Task Repository and Core Use Cases [PM-14]
-  - Story 2.3: Task Validation and Status Transitions [PM-15]
-  - Story 2.4: Task API Endpoints [PM-16]
-Total: {{epic_count}} epics, {{story_count}} stories
-Already synced: {{synced_epic_count}} epics, {{synced_story_count}} stories
-To create: {{new_epic_count}} epics, {{new_story_count}} stories
-```
-#### Step 4: Confirm Sync Plan
-```elicit
-path: Review and confirm sync plan
-format: |
-  The following items will be created in Jira ({{project_key}}):
-  {{Display parsed structure from Step 3}}
-  ⚠️ Items with existing Jira keys will be SKIPPED to avoid duplicates.
-  Options:
-  1. Proceed with creation (skip existing)
-  2. Force recreate all (ignore existing keys)
-  3. Enable dry-run mode (preview only)
-  4. Select specific epics to sync
-  5. Cancel
-  Enter selection (1-5):
-```
-### 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 Epic in Jira
-**For the current epic file:**
-1. **Check Existing Jira Key:**
-   - Search for `[PM-XX]` or similar pattern in epic header
-   - If found: SKIP this epic (already synced) UNLESS force mode enabled
-   - If not found: Proceed with creation
-2. **Extract Epic Data:**
-   - Epic Name: From file header
-   - Epic Goal: First paragraph after goal marker
-   - Description: Detailed content from file (excluding stories)
-   - Labels: `prd-sync`, `automated`, `epic-file-sync`, `{epic-slug}`
-3. **Map Custom Fields:**
-   ```
-   Based on jira-preferences.md:
-   - Epic Name (customfield_10011): {{epic_name}}
-   - Business Value (customfield_10020): {{if specified}}
-   - Target Quarter (customfield_10021): {{if specified}}
-   ```
-4. **Create Epic Issue:**
-   ```javascript
-   // Using MCP Jira - Pseudo-code for clarity
-   {
-     provider: "jira",
-     issue_type: "Epic",
-     summary: "[Epic] {{Epic Name}}",
-     description: "## Epic Goal\n{{goal}}\n\n## Details\n{{description}}\n\n---\n*Source: {{file_path}}*",
-     project_key: "{{from preferences}}",
-     priority: "{{from preferences}}",
-     labels: ["prd-sync", "automated", "epic-file-sync", "{{epic-slug}}"],
-     custom_fields: {
-       "customfield_10011": "{{epic_name}}"
-       // Additional custom fields from preferences
-     }
-   }
-   ```
-5. **Store Epic Key:**
-   - Save the created Jira epic key (e.g., `PM-123`)
-   - Maintain mapping: `Epic File` → `Jira Key`
-   - Prepare to update file with new key
-**Progress Output:**
-```markdown
-Processing Epic 1: Foundation & Category Management
-⊘ Epic already exists with key PM-6 (skipped)
-```
-#### Step 6: Create Stories in Jira for Current Epic
-**For each story in the current epic file:**
-1. **Check Existing Jira Key:**
-   - Search for `[PM-XX]` in story header
-   - If found: SKIP this story UNLESS force mode enabled
-   - If not found: Proceed with creation
-2. **Extract Story Data:**
-   - Title: From story header or user story format
-   - User Story: "As a... I want... So that..." format
-   - Description: Detailed content from story section
-   - Acceptance Criteria: Extracted from AC sections
-   - Technical Notes: From implementation sections
-   - Parent Epic: Use epic key from Step 5 or existing key
-3. **Map Custom Fields:**
-   ```
-   Based on jira-preferences.md:
-   - Story Points (customfield_10016): {{if specified}}
-   - Acceptance Criteria (customfield_10017): {{extracted AC}}
-   - Technical Notes (customfield_10018): {{tech details}}
-   - Dependencies (customfield_10019): {{if specified}}
-   ```
-4. **Create Story Issue:**
-   ```javascript
-   // Using MCP Jira - Pseudo-code for clarity
-   {
-     provider: "jira",
-     issue_type: "Story",
-     summary: "{{Story Title}}",
-     description: "## User Story\n{{user_story}}\n\n## Description\n{{description}}\n\n## Acceptance Criteria\n{{ac}}\n\n---\n*Source: {{file_path}}*",
-     project_key: "{{from preferences}}",
-     priority: "{{from preferences}}",
-     labels: ["prd-sync", "automated", "epic-file-sync", "{{parent-epic-slug}}"],
-     epic_link: "{{parent_epic_key}}",
-     custom_fields: {
-       "customfield_10017": "{{acceptance_criteria}}",
-       "customfield_10018": "{{technical_notes}}"
-       // Additional custom fields from preferences
-     }
-   }
-   ```
-5. **Link to Epic:**
-   - Establish parent-child relationship with epic
-   - Use `epic_link` field with parent epic key
-**Progress Output:**
-```markdown
-Creating Stories for Epic PM-6:
-⊘ Story 1.1: Project Scaffolding → PM-9 (already exists, skipped)
-⊘ Story 1.2: PostgreSQL Database → PM-10 (already exists, skipped)
-⊘ Story 1.3: Category Repository → PM-11 (already exists, skipped)
-⊘ Story 1.4: Category API Endpoints → PM-12 (already exists, skipped)
-Summary for Epic 1: 0 created, 4 skipped
-```
-#### Step 7: Update Current Epic File with Jira Keys
-**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.
-**For the current epic file:**
-1. **Update Epic Header:**
-   - Locate epic header line (e.g., `# Epic 1: Foundation...`)
-   - Add or update Jira key: `# Epic 1: Foundation... [PM-XX](https://...)`
-   - Preserve existing format if key already present
-2. **Update Story Headers:**
-   - Locate each story header (e.g., `## Story 1.1: ...`)
-   - Add or update Jira key: `## Story 1.1: ... [PM-XX](https://...)`
-   - Preserve existing format if key already present
-3. **Add/Update Sync Metadata:**
-   - At end of file, add or update sync information:
-```markdown
----
-## Jira Synchronization
-**Last Sync:** {{current_date}}
-**Epic Key:** [{{EPIC_KEY}}]({{jira_url}}/browse/{{EPIC_KEY}})
-**Project:** [{{project_key}}]({{jira_url}}/browse/{{project_key}})
-### Story Mappings
-| Story | Jira Key | Link |
-|-------|----------|------|
-| Story {{N}}.1: {{Title}} | {{KEY}} | [View]({{jira_url}}/browse/{{KEY}}) |
-| Story {{N}}.2: {{Title}} | {{KEY}} | [View]({{jira_url}}/browse/{{KEY}}) |
----
-*Synchronized by PM Agent - sync-epic-files-to-jira task on {{current_date}}*
-```
-**Progress Output:**
-```markdown
-✓ 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
-_Note: Tasks will not be created in Jira until this story has an associated Jira issue._
-```
-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
-**Create comprehensive summary report:**
-```markdown
-# Epic Files to Jira Sync Report
-**Source Directory:** docs/prd/
-**Epic Files Processed:** {{file_count}}
-**Jira Project:** {{project_key}}
-**Sync Date:** {{timestamp}}
-**Dry Run:** {{dry_run_mode}}
-## Summary
-- **Total Epics Processed:** {{total_epics}}
-  - Created: {{created_epics}}
-  - Skipped (existing): {{skipped_epics}}
-- **Total Stories Processed:** {{total_stories}}
-  - Created: {{created_stories}}
-  - Skipped (existing): {{skipped_stories}}
-- **Failed Items:** {{failure_count}}
-- **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}}
-## Processing Summary by Epic
-### Epic 1: {{epic_name}} (File: {{filename}})
-**Epic in Jira:** {{epic_key}} {{status}}
-**Epic File:** ✓ Updated with Jira keys
-**Story Files Updated:** {{story_files_updated}}/{{story_files_found}}
-**Stories Created/Updated:**
-| Story Title | Jira Key | Status | File Updated |
-|-------------|----------|--------|--------------|
-| {{title}}   | {{key}}  | ✓ Created | ✓ |
-| {{title}}   | {{key}}  | ⊘ Skipped | ✓ |
----
-### Epic 2: {{epic_name}} (File: {{filename}})
-**Epic in Jira:** {{epic_key}} {{status}}
-**Epic File:** ✓ Updated with Jira keys
-**Story Files Updated:** {{story_files_updated}}/{{story_files_found}}
-**Stories Created/Updated:**
-| Story Title | Jira Key | Status | File Updated |
-|-------------|----------|--------|--------------|
-| {{title}}   | {{key}}  | ✓ Created | ✓ |
-| {{title}}   | {{key}}  | ✓ Created | ✓ |
----
-## Failed Items
-{{If any items failed during processing}}
-| 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}} 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
-All processed epic files have been updated with inline Jira keys during the sync process:
-| Epic File | Epic Key | Stories | Epic File Updated | Story Files Updated |
-|-----------|----------|---------|-------------------|---------------------|
-| {{file}}  | {{key}}  | {{count}} | {{timestamp}} | {{count}} files |
-**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*
-```
-#### Step 9: Validation Checklist
-**Manual verification steps:**
-**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
-**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!
-  Summary:
-  - Epics Created: {{created_epics}}
-  - Stories Created: {{created_stories}}
-  - 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):
-```
-## Error Handling
-### Common Issues and Solutions
-**Issue:** Epic file has no valid epic header
-- **Solution:** Verify file follows expected format with `# Epic N:` header
-- **Action:** Skip file and log warning, or prompt user to fix format
-**Issue:** Cannot determine story structure
-- **Solution:** Check that stories follow `## Story N.M:` format
-- **Action:** Skip stories without clear structure, log details
-**Issue:** Duplicate epics detected (existing Jira key found)
-- **Solution:** Default behavior is to skip existing items
-- **Action:** Use force mode to recreate if needed
-**Issue:** Epic link field not available
-- **Solution:** Epic links may not be enabled in Jira project
-- **Action:** Use labels or alternative linking method
-**Issue:** File permission errors when updating epic files
-- **Solution:** Check file permissions in docs/prd/ directory
-- **Action:** Ensure write access to all epic files
-**Issue:** Inconsistent file naming
-- **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. **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
-- **Before:** Use `shard-prd` to split main PRD into individual epic files
-- **Alternative:** Use `sync-prd-to-jira` for monolithic PRD documents
-- **Complementary:** Use `create-story` for additional stories after initial sync
-- **Related:** Use `validate-jira-auth` to check authentication before syncing
-## Configuration Reference
-All configuration is managed in `.bmad-core/data/jira-preferences.md`. Key settings:
-- **Provider Settings:** Jira, Azure DevOps, GitHub, GitLab, Linear
-- **Project Configuration:** Project key, organization, default values
-- **Field Mappings:** Standard and custom field IDs
-- **Parsing Rules:** How to extract epics/stories from markdown files
-- **Automation Preferences:** Batch creation, naming conventions, error handling
-- **Skip Logic:** How to handle existing Jira keys in source files
-Refer to the configuration file for detailed documentation of all available settings.
----
-**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)