siesa-agents 2.1.27 → 2.1.29

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

@@ -0,0 +1,513 @@
+<!-- Powered by BMAD™ Core -->
+
+# Sync Epic Files to Jira Task
+
+## 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.
+
+## 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`
+- Jira preferences configured in `.bmad-core/data/jira-preferences.md`
+- Active Jira connection with appropriate permissions
+- MCP Jira integration available
+
+## 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 Creation
+
+#### Step 5: Create Epics in Jira
+
+**For each 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
+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
+```
+
+### Phase 3: Story Creation
+
+#### Step 6: Create Stories in Jira
+
+**For each story in each 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)
+
+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
+```
+
+### Phase 4: Update Epic Files with Jira Keys
+
+#### Step 7: Update Epic Files
+
+**CRITICAL:** Update each epic file with Jira references for traceability
+
+**For each processed 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
+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)
+
+Total: 3 files processed, 2 files updated, 10 new keys added
+```
+
+### Phase 5: 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}}
+- **Files Updated:** {{updated_files}}/{{total_files}}
+
+## Created Items by Epic File
+
+### Epic File 1: {{filename}}
+
+**Epic:** {{epic_name}} → {{epic_key}} {{status}}
+
+**Stories:**
+
+| Story Title | Jira Key | Status |
+|-------------|----------|--------|
+| {{title}}   | {{key}}  | ✓ Created |
+| {{title}}   | {{key}}  | ⊘ Skipped |
+
+---
+
+### Epic File 2: {{filename}}
+
+**Epic:** {{epic_name}} → {{epic_key}} {{status}}
+
+**Stories:**
+
+| Story Title | Jira Key | Status |
+|-------------|----------|--------|
+| {{title}}   | {{key}}  | ✓ Created |
+| {{title}}   | {{key}}  | ✓ Created |
+
+---
+
+## Failed Items
+
+{{If any items failed}}
+
+| Item | Type | File | Error |
+|------|------|------|-------|
+| {{name}} | {{type}} | {{file}} | {{error}} |
+
+## Updated Files
+
+| File | Epic Key | Stories Updated | Status |
+|------|----------|-----------------|--------|
+| {{file}} | {{key}} | {{count}} | ✓ Updated |
+
+## 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
+
+## Traceability
+
+Epic files have been mapped to Jira as follows:
+
+| Epic File | Epic Key | Story Count |
+|-----------|----------|-------------|
+| {{file}}  | {{key}}  | {{count}}   |
+
+All epic files have been updated with inline Jira keys for future reference.
+
+---
+*Generated by PM Agent - sync-epic-files-to-jira task*
+```
+
+#### Step 9: Validation Checklist
+
+**Manual verification steps:**
+
+- [ ] All new epics created with correct information
+- [ ] All new stories linked to appropriate epics
+- [ ] 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
+
+#### Step 10: Handoff
+
+```elicit
+path: Complete sync process
+format: |
+  Epic files sync complete! 
+  
+  Summary:
+  - Epics Created: {{created_epics}}
+  - Stories Created: {{created_stories}}
+  - Files Updated: {{updated_files}}
+  
+  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
+
+## 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
+
+## 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:** 1.0.0
+**Last Updated:** 2025-12-11
+**Dependencies:** MCP Jira Integration, jira-preferences.md, shard-prd task (optional)