siesa-agents 2.1.36 → 2.1.38

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

@@ -1,628 +0,0 @@
-<!-- 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)