siesa-agents 2.1.28 → 2.1.30

package/bmad-core/tasks/sync-story-to-jira.md

@@ -0,0 +1,628 @@
+<!-- Powered by BMAD™ Core -->
+
+# Sync Story Tasks to Jira Task
+
+## Purpose
+
+Automatically create Jira subtasks based on an approved user story. This task extracts the tasks structure from a story document and creates corresponding **Subtasks directly under the Story** in Jira using the MCP Jira integration. The original subtasks from the story document are included in each Subtask's description.
+
+## Jira Hierarchy Constraint
+
+**CRITICAL:** Jira Software projects use a fixed hierarchy:
+```
+Epic (level 1)
+  └── Story (level 0)
+        └── Subtask (level -1)
+```
+
+- **Stories and Tasks are at the SAME hierarchy level** - Tasks CANNOT be children of Stories
+- **Only Subtasks can be children of Stories**
+- Therefore, this task creates **story tasks as Jira Subtasks** under the parent Story
+- The original subtasks from the story document are embedded in the Subtask's description
+
+## When to Use This Task
+
+**Use this task when:**
+
+- You have an approved story (Status: "Approved") ready for implementation
+- The story has complete tasks and subtasks defined
+- You need to track implementation progress in Jira
+- You want to maintain traceability between story documents and Jira issues
+
+**Prerequisites:**
+
+- Story document with Status: "Approved" (NOT "Draft", "InProgress", "Review", or "Done")
+- Complete tasks and subtasks defined in the story
+- Jira preferences configured in `.bmad-core/data/jira-preferences.md`
+- Project-specific Jira configuration in `docs/jira-conf.md`
+- Active Jira connection with appropriate permissions
+- MCP Jira integration available
+- Parent story must already exist in Jira (or be created first)
+
+## 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 Configuration
+
+```elicit
+path: Load Jira configuration files
+format: |
+  Loading Jira configuration from:
+  - `.bmad-core/data/jira-preferences.md` (global preferences)
+  - `docs/jira-conf.md` (project-specific settings)
+
+  Please confirm the following settings:
+  - Provider: {{provider}}
+  - Project Key: {{project_key}}
+  - Project Name: {{project_name}}
+  - Cloud ID: {{cloud_id}}
+
+  Type 'proceed' to continue, or 'setup' to run jira-setup first.
+```
+
+**Action:** Verify configuration files exist and are complete
+
+- [ ] `.bmad-core/data/jira-preferences.md` exists
+- [ ] `docs/jira-conf.md` exists with all required fields
+- [ ] Subtask issue type ID available (typically `10318` or as configured)
+
+**If Configuration Missing:**
+```output
+⚠️ Jira configuration incomplete. Please run the `*jira-setup` command first to configure project-specific Jira integration.
+
+Required files:
+- `docs/jira-conf.md` - Project-specific settings (Project Key, Cloud ID, etc.)
+- `.bmad-core/data/jira-preferences.md` - Global preferences
+
+HALT execution until configuration is complete.
+```
+
+#### Step 2: Identify Story Document
+
+```elicit
+path: Locate the story to sync
+format: |
+  Which story document should have its tasks synced to Jira?
+
+  Options:
+  1. Specify file path (e.g., `docs/stories/1.1.user-authentication.story.md`)
+  2. Search for story by name
+  3. Use story from current epic context
+
+  Enter selection (1-3) or file path:
+```
+
+#### Step 3: Validate Story Approval Status
+
+**Action:** Read story document and validate it's ready for Jira sync
+
+- [ ] Load story document content
+- [ ] Check Status field
+- [ ] Verify Status is "Approved" (not "Draft", "InProgress", "Review", or "Done")
+- [ ] Confirm Tasks/Subtasks section exists and is populated
+- [ ] Validate story structure is complete
+
+**Expected Output:**
+```markdown
+## Story Validation Results:
+
+- **Story Title:** {{story_title}}
+- **Status:** {{status}}
+- **Epic:** {{epic_reference}}
+- **Tasks Count:** {{task_count}}
+- **Subtasks Count:** {{subtask_count}}
+
+✓ Story status: Approved
+✓ Tasks/Subtasks section found
+✓ Ready for Jira synchronization
+```
+
+**If Status is NOT "Approved":**
+```output
+❌ STORY NOT APPROVED FOR IMPLEMENTATION
+
+Current Status: {{status}}
+
+This story cannot be synced to Jira because it is not approved.
+
+Valid statuses for sync:
+- "Approved" - Ready for implementation ✓
+
+Invalid statuses:
+- "Draft" - Story still being drafted
+- "InProgress" - Already being implemented (sync not needed)
+- "Review" - Under review (needs approval first)
+- "Done" - Already completed (sync not applicable)
+
+Please ensure:
+1. Story has been validated using `*validate-story-draft` command
+2. Product Owner has approved the story
+3. Story Status field is set to "Approved"
+
+HALT execution until story is approved.
+```
+
+#### Step 3.5: Check for Previous Synchronization
+
+**CRITICAL:** Detect if story was already synced to prevent duplicate subtasks
+
+**Action:** Check story document for existing Jira synchronization
+
+- [ ] Search for "## Jira Synchronization" section in story document
+- [ ] Search for inline Jira keys pattern `[XX-###]` in Tasks section
+- [ ] Determine if story was previously synced
+
+**Detection Methods:**
+
+1. **Section Detection:** Look for `## Jira Synchronization` heading
+2. **Inline Keys Detection:** Look for pattern `\[([A-Z]+-\d+)\]` in task lines
+
+**If Previously Synced - Present Options:**
+
+```elicit
+path: Story already synchronized
+format: |
+  ⚠️ STORY ALREADY SYNCHRONIZED TO JIRA
+
+  This story appears to have been previously synced:
+
+  **Evidence Found:**
+  {{detection_evidence}}
+
+  **Existing Jira References:**
+  {{for each found_key}}
+  - {{jira_key}}: {{task_description}}
+  {{end for}}
+
+  **Options:**
+  1. Skip - Do not sync this story (recommended)
+  2. Force Re-sync - Create NEW subtasks (will create duplicates!)
+  3. Cancel - Abort operation
+
+  ⚠️ WARNING: Option 2 will create DUPLICATE subtasks in Jira.
+  Only use if previous subtasks were deleted or you intentionally want duplicates.
+
+  Enter selection (1-3):
+```
+
+**Behavior Based on Selection:**
+
+- **Option 1 (Skip):**
+  ```output
+  ⊘ Skipping story: {{story_title}}
+  Reason: Already synchronized to Jira
+  Existing subtasks preserved.
+  ```
+  HALT execution for this story.
+
+- **Option 2 (Force Re-sync):**
+  ```output
+  ⚠️ Force re-sync selected.
+  WARNING: This will create duplicate subtasks in Jira.
+  Proceeding with synchronization...
+  ```
+  Continue to Step 4.
+
+- **Option 3 (Cancel):**
+  ```output
+  ❌ Operation cancelled by user.
+  ```
+  HALT execution.
+
+**If NOT Previously Synced:**
+```output
+✓ No previous synchronization detected
+✓ Story is ready for first-time sync
+```
+Continue to Step 4.
+
+---
+
+#### Step 4: Parse Story Tasks Structure
+
+**Action:** Extract tasks and subtasks from story document
+
+- [ ] Parse Tasks / Subtasks section
+- [ ] Identify parent tasks (top-level checkboxes)
+- [ ] Identify subtasks (nested checkboxes under each task)
+- [ ] Extract task descriptions and any AC references
+- [ ] Build hierarchical structure
+- [ ] Validate all tasks are properly formatted
+
+**Expected Output:**
+```markdown
+## Parsed Tasks Structure:
+
+### Task 1: {{Task 1 Description}} (AC: {{ac_refs}})
+- Subtask 1.1: {{Subtask Description}}
+- Subtask 1.2: {{Subtask Description}}
+
+### Task 2: {{Task 2 Description}} (AC: {{ac_refs}})
+- Subtask 2.1: {{Subtask Description}}
+- Subtask 2.2: {{Subtask Description}}
+
+### Task 3: {{Task 3 Description}} (AC: {{ac_refs}})
+- Subtask 3.1: {{Subtask Description}}
+
+**Summary:**
+- Total Tasks: {{task_count}}
+- Total Subtasks in descriptions: {{subtask_count}}
+- Total Jira Subtasks to Create: {{task_count}}
+```
+
+#### Step 5: Check for Existing Jira Story and Get Authenticated User
+
+```elicit
+path: Verify parent story exists in Jira
+format: |
+  Does this story already exist in Jira?
+
+  Options:
+  1. Yes, I have the Jira Story Key (e.g., PM-123)
+  2. No, create the parent story first
+  3. Search for story in Jira by title
+
+  Enter selection (1-3) or Jira Story Key:
+```
+
+**Action:** Validate parent story and get authenticated user
+
+- [ ] If story key provided, verify it exists in Jira
+- [ ] If story doesn't exist, offer to create it first
+- [ ] Retrieve story key for linking subtasks
+- [ ] **Get authenticated user using `atlassianUserInfo` MCP tool**
+- [ ] Store parent story key and user account ID
+
+**Expected Output:**
+```markdown
+✓ Parent Story Verified: {{story_key}} - {{story_title}}
+✓ Authenticated User: {{user_display_name}} ({{user_account_id}})
+
+All tasks will be created as Subtasks of this story.
+```
+
+#### Step 6: Assign Story to Authenticated User
+
+**Action:** Assign the parent story to the authenticated user
+
+```action
+Using MCP Jira Integration:
+1. Call `atlassianUserInfo` to get current authenticated user's account_id
+2. Call `editJiraIssue` to update the story ({{story_key}}) with:
+   - assignee: { accountId: "{{user_account_id}}" }
+```
+
+**Expected Output:**
+```output
+✅ Story {{story_key}} assigned to {{user_display_name}}
+```
+
+#### Step 7: Confirm Sync Plan
+
+```elicit
+path: Review and confirm subtask creation plan
+format: |
+  The following Subtasks will be created in Jira ({{project_key}}):
+
+  **Parent Story:** {{story_key}} - {{story_title}}
+  **Assigned To:** {{user_display_name}}
+
+  **Subtasks to Create (from story tasks):**
+  {{Display parsed tasks - each task becomes a Subtask with its subtasks in description}}
+
+  **Jira Configuration:**
+  - Issue Type: Subtarea ({{subtask_issue_type_id}})
+  - Default Priority: {{default_priority}}
+  - Parent Story: {{story_key}}
+  - Assignee: {{user_display_name}}
+
+  **Total Subtasks to Create:** {{task_count}}
+
+  **Note:** Each story task becomes a Jira Subtask. The original subtasks
+  from the story document will be included in each Subtask's description
+  as a checklist.
+
+  Options:
+  1. Proceed with creation
+  2. Enable dry-run mode (preview only, don't create)
+  3. Modify default priority
+  4. Cancel
+
+  Enter selection (1-4):
+```
+
+### Phase 2: Jira Subtask Creation
+
+#### Step 8: Create Subtasks (from Story Tasks)
+
+**For Each Task in the Story Document:**
+
+```action
+Using MCP Jira Integration:
+1. Create Subtask issue with:
+   - Issue Type: Subtarea ({{subtask_issue_type_id}})
+   - Project: {{project_key}}
+   - Summary: {{task_description}}
+   - Description: |
+     **Story:** [{{story_key}}]({{jira_url}}/browse/{{story_key}})
+     **Acceptance Criteria References:** {{ac_references}}
+
+     ---
+
+     ## Checklist (Subtasks from Story)
+
+     {{for each subtask in task.subtasks}}
+     - [ ] {{subtask_description}}
+     {{end for}}
+
+     ---
+
+     **Implementation Notes:**
+     {{relevant_dev_notes}}
+
+     ---
+     *Source: {{story_file_path}}*
+     *Synchronized by PO Agent - sync-story-to-jira task*
+   - Parent: {{story_key}}
+   - Priority: {{default_priority}}
+   - Assignee: {{user_account_id}} (authenticated Jira user)
+
+2. Store created subtask key (e.g., PM-456)
+3. Record task mapping: Task {{task_number}} → {{jira_subtask_key}}
+```
+
+**Progress Tracking:**
+```output
+Creating Subtasks under Story {{story_key}}...
+
+✓ Task 1: {{task_1_description}} → {{subtask_1_key}} ({{subtask_count_1}} items in checklist)
+✓ Task 2: {{task_2_description}} → {{subtask_2_key}} ({{subtask_count_2}} items in checklist)
+✓ Task 3: {{task_3_description}} → {{subtask_3_key}} ({{subtask_count_3}} items in checklist)
+
+Subtasks Created: {{created_count}}/{{total_task_count}}
+All subtasks assigned to: {{user_display_name}}
+```
+
+### Phase 3: Verification & Documentation
+
+#### Step 9: Verify All Issues Created
+
+**Action:** Validate all subtasks were created successfully
+
+- [ ] Count created subtasks matches expected task count
+- [ ] All subtasks are children of the parent story
+- [ ] All subtasks have the checklist in description
+- [ ] All subtasks assigned to authenticated user
+- [ ] No creation errors or warnings
+
+**Expected Output:**
+```markdown
+## Creation Summary:
+
+✓ All Subtasks Created Successfully
+
+**Parent Story:** {{story_key}} - {{story_title}}
+**Assigned To:** {{user_display_name}}
+
+**Subtasks:**
+| # | Task Description | Jira Key | Checklist Items |
+|---|------------------|----------|-----------------|
+| 1 | {{task_1_description}} | {{subtask_1_key}} | {{subtask_count_1}} |
+| 2 | {{task_2_description}} | {{subtask_2_key}} | {{subtask_count_2}} |
+| 3 | {{task_3_description}} | {{subtask_3_key}} | {{subtask_count_3}} |
+
+**Statistics:**
+- Subtasks Created: {{task_count}}
+- Total Checklist Items: {{subtask_count}}
+- Parent Story: {{story_key}}
+- Project: {{project_key}}
+- All Issues Assigned To: {{user_display_name}}
+
+**Jira Links:**
+- Story: {{jira_url}}/browse/{{story_key}}
+- Subtask 1: {{jira_url}}/browse/{{subtask_1_key}}
+- Subtask 2: {{jira_url}}/browse/{{subtask_2_key}}
+- Subtask 3: {{jira_url}}/browse/{{subtask_3_key}}
+```
+
+#### Step 10: Update Story Document with Jira Links
+
+**CRITICAL:** Always update the story document with Jira references for traceability
+
+**Action:** Add Jira issue keys to the story document
+
+```output
+🔄 Updating story document with Jira links...
+📄 File: {{story_file_path}}
+```
+
+**Update Strategy:**
+
+1. **Add Jira Keys Inline to Tasks:**
+   - Locate each task checkbox in the Tasks / Subtasks section
+   - Append Jira key after task description: `- [ ] **Task N: Description** (AC: X) [{{SUBTASK_KEY}}]`
+   - Example: `- [ ] **Task 1: Create Solution Structure** (AC: 1, 4) [PM-31]`
+
+2. **Keep subtasks as-is** (they are now in the Jira Subtask description)
+
+3. **Add Jira Synchronization Section:**
+   - After the Tasks / Subtasks section, add a new section:
+
+```markdown
+## Jira Synchronization
+
+**Sync Date:** {{current_date}}
+**Parent Story:** [{{story_key}}]({{jira_url}}/browse/{{story_key}})
+**Assigned To:** {{user_display_name}}
+**Project:** {{project_key}}
+
+### Task to Subtask Mappings
+
+| Story Task | Jira Subtask | Link | Checklist Items |
+|------------|--------------|------|-----------------|
+| Task 1: {{task_1_desc}} | {{subtask_1_key}} | [View]({{jira_url}}/browse/{{subtask_1_key}}) | {{count_1}} |
+| Task 2: {{task_2_desc}} | {{subtask_2_key}} | [View]({{jira_url}}/browse/{{subtask_2_key}}) | {{count_2}} |
+| Task 3: {{task_3_desc}} | {{subtask_3_key}} | [View]({{jira_url}}/browse/{{subtask_3_key}}) | {{count_3}} |
+
+**Total Jira Subtasks:** {{task_count}}
+**Total Checklist Items:** {{subtask_count}}
+
+**Important:**
+- After synchronization, Jira becomes the source of truth for task status
+- Each Jira Subtask contains a checklist with the original story subtasks
+- Track progress in Jira and update checkboxes there
+- Update this document only after completing all work
+
+---
+*Synchronized by PO Agent - sync-story-to-jira task on {{current_date}}*
+```
+
+**Expected Output:**
+```output
+✅ Story document updated with Jira links
+✅ Inline keys added to {{task_count}} tasks
+✅ Jira Synchronization section added
+✅ File saved: {{story_file_path}}
+
+Traceability established between story document and Jira subtasks.
+```
+
+#### Step 11: Generate Final Report
+
+```output
+═══════════════════════════════════════════════════════════════
+  JIRA SYNC COMPLETE - Story Tasks Synchronized
+═══════════════════════════════════════════════════════════════
+
+Story: {{story_title}}
+Status: ✓ Synchronized to Jira
+
+Parent Story: {{story_key}}
+Subtasks Created: {{task_count}}
+Checklist Items: {{subtask_count}}
+Assigned To: {{user_display_name}}
+
+Hierarchy in Jira:
+  {{story_key}} (Story) ← Assigned to {{user_display_name}}
+    ├── {{subtask_1_key}} (Subtask) - Task 1
+    ├── {{subtask_2_key}} (Subtask) - Task 2
+    └── {{subtask_3_key}} (Subtask) - Task 3
+
+Next Steps:
+1. Review subtasks in Jira: {{jira_url}}/browse/{{story_key}}
+2. Each subtask has a checklist - use it to track progress
+3. Story is ready for development - use `*develop-story` command with dev agent
+4. Track progress through Jira board
+
+Note: The story document has been updated with Jira mappings.
+      Original subtasks are now checklists within each Jira Subtask.
+      Changes should be made in Jira, which is now the source of truth.
+
+═══════════════════════════════════════════════════════════════
+```
+
+## Success Criteria
+
+The story sync is successful when:
+
+1. Story status validated as "Approved"
+2. All tasks extracted and parsed correctly
+3. Parent story assigned to authenticated user
+4. All tasks created as Jira Subtasks under the story
+5. Each Subtask description contains the original subtasks as a checklist
+6. Story document updated with Jira mappings
+7. Traceability maintained between story document and Jira
+
+## Error Handling
+
+### Story Not Approved
+```output
+❌ ERROR: Story status is "{{current_status}}" but must be "Approved"
+
+Resolution:
+1. Run `*validate-story-draft` to validate the story
+2. Address any validation issues
+3. Update Status to "Approved"
+4. Retry sync operation
+```
+
+### Missing Jira Configuration
+```output
+❌ ERROR: Jira configuration incomplete
+
+Missing: {{missing_config_items}}
+
+Resolution:
+1. Run `*jira-setup` command to configure Jira integration
+2. Ensure docs/jira-conf.md exists with project settings
+3. Retry sync operation
+```
+
+### Parent Story Not Found
+```output
+❌ ERROR: Parent story {{story_key}} not found in Jira
+
+Resolution:
+1. Verify story key is correct
+2. Create parent story in Jira first using PM agent
+3. Or search Jira for existing story
+4. Retry sync with correct story key
+```
+
+### Subtask Creation Failure
+```output
+❌ ERROR: Failed to create subtask: {{task_description}}
+
+Error: {{error_message}}
+
+Resolution:
+1. Check Jira permissions
+2. Verify Subtask issue type ID is correct in jira-preferences.md
+3. Retry failed subtask creation
+4. Contact Jira admin if permissions issue
+```
+
+### Cannot Get Authenticated User
+```output
+❌ ERROR: Unable to retrieve authenticated Jira user
+
+Resolution:
+1. Verify MCP Jira connection is active
+2. Run `/mcp` to reconnect if needed
+3. Ensure your Jira account has proper permissions
+4. Retry sync operation
+```
+
+## Important Notes
+
+- **Status Requirement:** Story MUST be in "Approved" status (not Draft, InProgress, Review, or Done)
+- **Hierarchy Constraint:** Tasks become Subtasks (Jira doesn't allow Tasks as children of Stories)
+- **Subtasks as Checklists:** Original story subtasks are embedded in each Jira Subtask description
+- **Auto-Assignment:** Story is automatically assigned to the authenticated Jira user
+- **One-Way Sync:** This creates Jira issues from story document (not bidirectional)
+- **Source of Truth:** After sync, Jira becomes source of truth for task status
+- **Duplicate Detection:** Task automatically detects previously synced stories and offers skip/force options
+- **Parent Story Required:** Story must exist in Jira before syncing tasks
+- **Dev Agent Requirement:** This is required before dev agent can begin implementation
+
+## Related Commands
+
+- `*validate-story-draft` - Validate story before approval
+- `*create-story` - Create a new story document
+- `*jira-setup` - Configure Jira integration
+- `*develop-story` - Begin development (requires approved story with Jira sync)