siesa-agents 2.1.36 → 2.1.37

package/bmad-core/tasks/sync-stories-batch-to-jira.md

@@ -1,561 +0,0 @@
-<!-- Powered by BMAD™ Core -->
-
-# Sync Stories Batch to Jira Task (Create Subtasks)
-
-## CRITICAL EXECUTION NOTE
-
-**THIS IS AN EXECUTABLE TASK - NOT REFERENCE DOCUMENTATION**
-
-When executing this task, you MUST:
-1. Use Glob tool to search for story files (NOT bash ls/find)
-2. Use Read tool to read each story document (NOT bash cat/grep/awk)
-3. Use MCP Atlassian tools directly: mcp__atlassian__createJiraIssue, mcp__atlassian__atlassianUserInfo, mcp__atlassian__editJiraIssue, etc.
-4. Use Edit/Write tools to update story documents with Jira keys
-
-**DO NOT:**
-- Use bash loops (for, while) to read files
-- Use bash commands (grep, cat, awk, sed) to read or count tasks
-- Create any bash scripts or intermediate processing
-
----
-
-## Purpose
-
-**CREATES SUBTASKS ONLY** - Assumes Epics and Stories already exist in Jira.
-
-Automatically creates Jira Subtasks for multiple user stories based on epic scope. This task searches for story documents in `docs/stories/` directory for a specific epic and for EACH matching story, creates Jira Subtasks from the story's tasks using MCP tools.
-
-## When to Use This Task
-
-**Use this task when:**
-
-- Epics and Stories **ALREADY exist in Jira** (have keys in epic files)
-- You need to create Subtasks for all stories from a specific epic
-- You need batch creation of Subtasks for multiple approved stories in an epic
-
-**Prerequisites:**
-
-- **CRITICAL:** Epics and Stories MUST already exist in Jira with keys in epic files
-- One or more story documents with Status: "Approved" or "Done"
-- Story tasks do NOT have inline Jira keys (if they do, subtasks already created)
-- 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
-
-## Instructions
-
-### Phase 1: Configuration & Scope Identification
-
-#### 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
-
-**Action:** Load and verify Jira configuration files
-
-- [ ] Load `.bmad-core/data/jira-preferences.md` (global preferences)
-- [ ] Load `docs/jira-conf.md` (project-specific settings)
-- [ ] Verify all required fields are present
-
-**If Configuration Missing:**
-```output
-⚠️ Jira configuration incomplete. Please run the `*jira-setup` command first.
-HALT execution until configuration is complete.
-```
-
-#### Step 2: Determine Sync Scope
-
-```elicit
-path: Identify stories to sync
-format: |
-  What epic scope should be synced to Jira?
-
-  The command was invoked with: {{scope_parameter}}
-
-  Interpreting scope:
-  - If scope is "epic-N" (e.g., epic-1, epic-2): Sync stories matching pattern N.*.story.md
-  - If scope is just a number (e.g., 1, 2): Treated as epic-N
-
-  Please confirm the epic number is correct, or provide clarification.
-```
-
-#### Step 3: Search for Epic Stories
-
-**Action:** USE GLOB TOOL to search `docs/stories/` directory for matching story files in the epic
-
-**CRITICAL - Use Glob tool only (NOT bash find/ls):**
-
-```
-Extract epic number from scope (e.g., "epic-1" → epic_number = "1")
-Use Glob tool with pattern: docs/stories/{{epic_number}}.*.story.md
-
-Example: If scope is "epic-1", use pattern "docs/stories/1.*.story.md"
-```
-
-**IMPORTANT:**
-- Use Glob tool with ONE pattern match (NOT bash brace expansion like `{2,3,4,5}`)
-- Store the list of found files - you will iterate over this list in Step 6
-- DO NOT use bash loops or for statements to iterate files
-
-#### Step 4: Filter Valid Stories and Detect Already Synced Subtasks
-
-**Action:** Read each story (EFFICIENTLY - sections only), filter by valid status, and detect if subtasks already created
-
-**CRITICAL - Use Read tool for each story file:**
-- Use Read tool (NOT bash commands like grep, cat, etc.)
-- Read metadata section (first 30 lines): Extract Status field
-- Read Tasks/Subtasks section: Check if tasks have inline Jira keys
-
-**For each story:**
-
-1. **Check Status:** Only include Status: "Approved" OR "Done"
-2. **Check if Story Exists in Jira:**
-   - Extract epic and story numbers from filename
-   - Read epic file: `docs/prd/epic-{{epic_number}}-*.md`
-   - Search for EXACT match: `## Story {{epic}}.{{story}}:.*\[([A-Z]+-\d+)\]`
-   - If NOT found → Story doesn't exist in Jira (SKIP story)
-   - If found → Continue to step 3
-3. **Check if Subtasks Already Created:**
-   - Look in Tasks section for inline Jira keys in format: `**Task N:** Description [PM-XXX]`
-   - Count how many tasks have inline Jira keys
-   - If ALL tasks have keys → Subtasks already created (SKIP story)
-   - If NO keys OR only partial keys → Subtasks NOT created (INCLUDE story)
-4. **Track skipped stories and reasons**
-
-**CRITICAL ASSUMPTION:** Epics and Stories already exist in Jira. This checks if SUBTASKS created, not stories.
-
-**Story Classification:**
-
-| Classification | Criteria | Action |
-|----------------|----------|--------|
-| Ready to Sync | Status: "Approved/Done" AND story exists in Jira AND tasks have NO Jira keys | Include |
-| Not Found | Status: "Approved/Done" BUT story NOT in epic file | Skip |
-| Already Synced | Status: "Approved/Done" AND story exists BUT tasks have Jira keys | Skip |
-| Invalid Status | Status is not "Approved/Done" | Skip |
-
-Display summary: Total found, ready to sync, not found in Jira, already synced, invalid status.
-
-#### Step 5: Confirm Batch Sync Plan
-
-```elicit
-path: Confirm batch synchronization
-format: |
-  SUBTASKS will be created for the following stories:
-  (Epics and Stories already exist in Jira)
-
-  **Scope:** {{scope}}
-  **Project:** {{project_key}}
-  **Stories Ready:** {{ready_count}}
-
-  {{for each ready_story}}
-  {{index}}. {{filename}} - {{title}} ({{task_count}} subtasks to create)
-  {{end for}}
-
-  **Stories Skipped - Not Found in Jira ({{not_found_count}}):**
-  {{for each not_found_story}}
-  ⊘ {{filename}} (Story not found in epic file)
-  {{end for}}
-
-  **Stories Skipped - Subtasks Already Created ({{already_synced_count}}):**
-  {{for each already_synced_story}}
-  ⊘ {{filename}} (Tasks have inline Jira keys)
-  {{end for}}
-
-  **Stories Skipped - Invalid Status ({{invalid_status_count}}):**
-  {{for each invalid_status_story}}
-  ⊘ {{filename}} (Status: {{status}} - requires Approved/Done)
-  {{end for}}
-
-  Options:
-  1. Proceed - Create subtasks (only for stories found in Jira)
-  2. Preview only (dry-run)
-  3. Force ALL - Create subtasks even if already exist (creates duplicates!)
-  4. Cancel
-
-  Enter selection (1-4):
-```
-
-**Behavior Based on Selection:**
-
-- **Option 1 (Proceed):** Create subtasks only for stories without inline Jira keys (recommended)
-- **Option 2 (Preview):** Show what would be created without creating subtasks
-- **Option 3 (Force ALL):** Create subtasks even if already exist (WARNING: creates duplicate subtasks)
-- **Option 4 (Cancel):** Abort operation
-
-### Phase 2: Sequential Subtask Creation
-
-#### Step 6: Create Subtasks for Each Story
-
-**CRITICAL EXECUTION INSTRUCTION:**
-
-For each story in the ready_stories list, create ALL subtasks in Jira using MCP Atlassian tools:
-- Call mcp__atlassian__atlassianUserInfo, mcp__atlassian__editJiraIssue, mcp__atlassian__createJiraIssue directly
-- One tool call per operation
-- Process operations sequentially, one story at a time
-
-```output
-═══════════════════════════════════════════════════════════════
-  BATCH SUBTASK CREATION STARTING
-  Scope: {{scope}}
-  Stories: {{ready_count}}
-═══════════════════════════════════════════════════════════════
-```
-
-**FOR EACH STORY - Execute These Steps:**
-
-```action
-LOOP: For each story in ready_stories list, execute steps A through H:
-
-─────────────────────────────────────────────────────────────
-Processing Story {{index}}/{{total}}: {{filename}}
-─────────────────────────────────────────────────────────────
-
-A. READ STORY DOCUMENT (EFFICIENTLY - SECTIONS ONLY)
-   **Use Read tool - NOT bash commands**
-
-   - Use Read tool to read: docs/stories/{{filename}}
-   - ONLY extract from specific sections:
-     * Metadata: Story title, Status, Jira Issue Key (if exists)
-     * ## Tasks / Subtasks section: Parse tasks and subtasks structure
-   - DO NOT read entire document - focus on these sections only
-
-B. PARSE TASKS STRUCTURE (from Read tool output)
-   - Identify all tasks (top-level checkboxes with **Task N:** pattern)
-   - For each task, identify its subtasks (nested checkboxes indented under task)
-   - Extract AC references from each task
-   - Parse directly from Read tool output (NOT from bash commands)
-   - **IMPORTANT**: Subtasks will be included in the Jira Subtask description as checklist items (NOT as separate Jira issues)
-
-C. LOOKUP JIRA STORY KEY FROM EPIC FILE (exact match only - skip if not found)
-   - Extract epic and story numbers from filename
-     Examples:
-     * "{{epic}}.{{story}}.story.md" → epic number, story number
-     * "{{epic}}.{{story}}.{{multi-level}}.story.md" → epic, story
-
-   - Use Glob to find epic file: docs/prd/epic-{{epic_number}}-*.md
-   - Read the epic file content
-   - Search for EXACT match: "## Story {{epic}}.{{story}}:.*\[([A-Z]+-\d+)\]"
-
-   **CRITICAL - NO FALLBACK:**
-   - Multi-level stories often don't exist in Jira
-   - If story NOT found in epic file → SKIP this story and continue to next
-   - Do NOT create subtasks under parent or sibling stories
-   - Do NOT search for alternatives
-
-   Example: Processing file with multi-level
-   ```
-   Search epic for exact story number → NOT FOUND
-   Action: SKIP this story (doesn't exist in Jira)
-   Display: "⊘ Skipping {{filename}} - story not found in Jira"
-   ```
-
-   Example: Processing standard file
-   ```
-   Search epic for story number → FOUND! [JIRA-KEY]
-   Action: Use JIRA-KEY to create subtasks
-   Display: "✓ Using story {{epic}}.{{story}} (JIRA-KEY) for subtasks"
-   ```
-
-   - If FOUND: Extract Jira key from epic file
-   - If NOT FOUND: SKIP this story with message and CONTINUE to next story in loop
-
-D. GET AUTHENTICATED USER (CRITICAL - Required for story and subtask assignment)
-   - Call mcp__atlassian__atlassianUserInfo (no parameters)
-   - Extract from response:
-     * user_account_id (required for assignments)
-     * user_display_name (for display)
-   - Verify accountId is not null
-
-   If call fails:
-     ❌ SKIP this story: "Unable to get authenticated user info"
-     CONTINUE to next story
-
-E. ASSIGN STORY TO AUTHENTICATED USER (MANDATORY before creating subtasks)
-   - Call mcp__atlassian__editJiraIssue
-   - Parameters:
-     * cloudId: {{cloud_id}}
-     * issueIdOrKey: {{story_key}}
-     * fields: { "assignee": { "accountId": "{{user_account_id}}" } }
-
-   - Verify assignment succeeded
-   - Display: ✓ Story {{story_key}} assigned to {{user_display_name}}
-
-   If assignment fails:
-     ⚠️ WARNING: Story assignment failed but continuing with subtasks
-     Display: ⚠️ Could not assign story {{story_key}} to {{user_display_name}}
-
-F. CREATE SUBTASKS IN JIRA
-   For EACH task parsed from story document:
-
-   **CRITICAL**: Each story TASK becomes a Jira SUBTASK. The original story SUBTASKS (nested checkboxes)
-   are embedded in the Jira Subtask description as a checklist.
-
-   1. Call mcp__atlassian__createJiraIssue
-      Parameters:
-      - cloudId: {{cloud_id}} (from jira-conf.md)
-      - projectKey: {{project_key}} (from jira-conf.md)
-      - issueTypeName: "Subtarea" (or configured subtask type)
-      - summary: "{{task_description}}"
-      - description: |
-          **Story:** [{{story_key}}]({{jira_url}}/browse/{{story_key}})
-          **AC References:** {{ac_refs}}
-
-          ## Checklist (Subtasks from Story)
-          {{for each subtask nested under this task}}
-          - [ ] {{subtask_description}}
-          {{end for}}
-
-          ---
-          *Source: {{story_file_path}}*
-      - parent: {{story_key}}
-      - assignee_account_id: {{user_account_id}}
-
-   2. Store created subtask key from response
-   3. Display: ✓ Task {{n}}: {{description}} → {{subtask_key}} ({{subtask_count}} checklist items)
-
-G. UPDATE STORY DOCUMENT WITH SUBTASK KEYS (CRITICAL - Marks subtasks as synced)
-   - Read story file: docs/stories/{{filename}}
-   - For EACH created subtask, update corresponding task line
-   - Add Jira key inline after task description:
-     **Task 1:** Create authentication component [{{SUBTASK_KEY}}]
-   - Save updated story file
-   - This marks subtasks as synced (prevents duplicate creation on next run)
-   - Story file tasks with inline keys = source of truth for subtask sync status
-
-H. RECORD RESULT
-   - Success: story_key, subtask_count, list of subtask_keys
-   - Failure: error_message
-
-─────────────────────────────────────────────────────────────
-✓ {{filename}} COMPLETE → {{story_key}} ({{subtask_count}} subtasks created)
-✓ Story assigned to: {{user_display_name}}
-✓ All subtasks assigned to: {{user_display_name}}
-─────────────────────────────────────────────────────────────
-
-CONTINUE TO NEXT STORY IN LOOP...
-```
-
-Display progress: `[{{index}}/{{total}}] Processing: {{current_filename}}...`
-
-### Phase 3: Status Update, Summary & Report
-
-#### Step 7: Prompt for Status Update Decision (For Epic Scope Only)
-
-**Condition:** Only execute this step if:
-- Scope is an epic (scope = "epic-N" where N is a number)
-- At least one story was successfully synced (success_count > 0)
-
-**CRITICAL ELICITATION - DO NOT SKIP IF CONDITIONS MET**
-
-**Action:** Ask user if they want to update statuses for the synced stories and subtasks
-
-```output
-═══════════════════════════════════════════════════════════════
-  STATUS UPDATE DECISION
-═══════════════════════════════════════════════════════════════
-
-Epic {{epic_number}} - {{success_count}} stories synced successfully
-Total Subtasks Created: {{total_subtask_count}}
-
-Would you like to update the status of the created subtasks and/or stories?
-
-Options:
-1. Yes - Update statuses (will prompt for target status next)
-2. No - Skip status update (subtasks and stories remain at default status)
-
-Enter selection (1 or 2):
-```
-
-**Wait for User Input - DO NOT PROCEED without selection**
-
-- **Option 1 (Yes):** Continue to Step 8
-- **Option 2 (No):** Skip to Step 9 (inform user can use `*update-epic-status` later)
-
-#### Step 8: Select and Apply Status (Only if Step 7 = Yes)
-
-**Condition:** Only execute this step if user selected "Yes" in Step 7
-
-**CRITICAL:** This step sets the status of ALL created subtasks and optionally their parent stories
-
-**Step 8.1: Load Available Statuses**
-
-- Read `docs/jira-conf.md` → "Available Story Statuses" section
-- If not found: Use MCP `getTransitionsForJiraIssue` on first subtask
-
-**Step 8.2: Prompt User for Target Status**
-
-**CRITICAL ELICITATION - DO NOT SKIP**
-
-```output
-═══════════════════════════════════════════════════════════════
-  TARGET STATUS SELECTION
-═══════════════════════════════════════════════════════════════
-
-Epic {{epic_number}} - {{success_count}} stories synced
-Total Subtasks Created: {{total_subtask_count}}
-
-Available Statuses:
-1. To Do
-2. In Progress
-3. Ready for Review
-4. Done
-
-Select status to apply to ALL subtasks (enter number 1-{{status_count}}):
-```
-
-**Wait for User Input - HALT and WAIT for status selection**
-
-**Step 8.3: Apply Status to ALL Subtasks**
-
-**Action:** For EACH created subtask across ALL stories, update its status
-
-```action
-FOR EACH story → FOR EACH subtask:
-  A. Call mcp__atlassian__getTransitionsForJiraIssue
-     Parameters: cloudId, issueIdOrKey (subtask_key)
-     Extract transition ID for {{selected_status}}
-
-  B. Call mcp__atlassian__transitionJiraIssue
-     Parameters: cloudId, issueIdOrKey (subtask_key), transition: {id: "{{transition_id}}"}
-
-  C. Display: ✓ {{subtask_key}} → {{selected_status}}
-```
-
-Display: `✅ All {{total_subtask_count}} subtasks updated to: {{selected_status}}`
-
-**Step 8.4: Apply Status to Stories (Automatic based on subtasks)**
-
-**Action:** Automatically update story statuses based on subtask statuses
-
-Rule: If ALL subtasks have SAME status → Update story to that status
-
-```action
-FOR EACH story:
-  A. Check if all subtasks have same status
-
-  B. If YES:
-     - Call mcp__atlassian__getTransitionsForJiraIssue
-       Parameters: cloudId, issueIdOrKey (story_key)
-     - Call mcp__atlassian__transitionJiraIssue
-       Parameters: cloudId, issueIdOrKey (story_key), transition: {id: "{{transition_id}}"}
-     - Display: ✓ Story {{story_key}} → {{selected_status}}
-
-  C. If NO: Skip story update
-     Display: ⊘ Story {{story_key}} unchanged (mixed subtask statuses)
-```
-
-Display: `Stories Updated: {{updated_count}}/{{total_stories}}`
-
-#### Step 9: Generate Batch Subtask Creation Report
-
-```output
-═══════════════════════════════════════════════════════════════
-  BATCH SUBTASK CREATION COMPLETE
-═══════════════════════════════════════════════════════════════
-
-Scope: {{scope}}
-Project: {{project_key}}
-Execution Time: {{duration}}
-
-## Results Summary
-
-| # | Story File | Story Key | Subtasks Created | Status |
-|---|------------|-----------|------------------|--------|
-{{for each story}}
-| {{index}} | {{filename}} | {{story_key}} | {{subtask_count}} | {{status_icon}} |
-{{end for}}
-
-## Statistics
-
-- Stories Processed: {{processed_count}}
-- Successful: {{success_count}}
-- Failed: {{failed_count}}
-- Skipped (story not found in Jira): {{not_found_count}}
-- Skipped (subtasks already exist): {{already_synced_count}}
-- Skipped (invalid status): {{invalid_status_count}}
-- Total Subtasks Created: {{total_subtasks}}
-- Subtasks Updated to Status: {{selected_subtask_status}} (Step 8 - if user chose to update)
-- Stories Updated: {{story_updated_count}} (Step 8.4 - automatic if user chose to update)
-
-## Failed Stories (if any)
-{{for each failed story}}
-❌ {{filename}}: {{error_message}}
-{{end for}}
-
-## Skipped - Story Not Found in Jira
-{{for each not_found_story}}
-⊘ {{filename}} (Story not found in epic file)
-{{end for}}
-
-## Skipped - Subtasks Already Created
-{{for each already_synced_story}}
-⊘ {{filename}} (Tasks have inline Jira keys)
-{{end for}}
-
-## Skipped - Invalid Status
-{{for each invalid_status_story}}
-⊘ {{filename}} (Status: {{status}} - requires Approved/Done)
-{{end for}}
-
-## Jira Board Links
-- Project Board: {{jira_url}}/jira/software/projects/{{project_key}}/boards
-- Backlog: {{jira_url}}/jira/software/projects/{{project_key}}/backlog
-
-## Next Steps
-1. Review synced stories and subtasks in Jira
-2. Verify statuses (if updated in Step 8)
-3. Assign to sprint if needed
-4. Ready for development - use dev agent to begin
-
-═══════════════════════════════════════════════════════════════
-```
-
-## Error Handling
-
-**No Stories Found:** Check pattern, directory, and story file naming (N.M.story.md)
-
-**No Valid Stories:** Stories must have Status "Approved" or "Done"
-
-**All Stories Already Synced:** All story tasks have inline Jira keys (subtasks already created). This is normal if already processed.
-
-**Story Not Found in Jira (Skipped):** Story not found in epic file (exact match search). This is normal for multi-level stories that don't exist in Jira. These stories are automatically skipped and processing continues with the next story. Story must exist in Jira and be listed in epic file with format: `## Story N.M: Title [KEY](url)` to be processed.
-
-**Partial Failure:** Review failures, fix issues, retry batch or use `*sync-story-to-jira` for individual stories
-
-## Important Notes
-
-- **CRITICAL ASSUMPTION:** Epics and Stories MUST already exist in Jira. This command creates SUBTASKS only.
-- **MCP Tools:** Uses mcp__atlassian__createJiraIssue, mcp__atlassian__editJiraIssue, mcp__atlassian__atlassianUserInfo, mcp__atlassian__getTransitionsForJiraIssue, mcp__atlassian__transitionJiraIssue
-- **Reading:** Only reads metadata sections (efficient, not full documents)
-- **Task Mapping:** Story TASK → Jira SUBTASK. Story subtasks → checklist in Jira Subtask description
-- **Auto-Assignment:** Story + all subtasks auto-assigned to authenticated MCP user (Step D, E, F)
-- **Jira Key Lookup - Exact Match Only (Step C):**
-  - Multi-level stories often don't exist in Jira
-  - Searches for EXACT match only in epic file
-  - If story NOT found → SKIP that story (no fallback)
-  - Skipped stories are reported in summary and processing continues with next story
-- **Duplicate Detection:** Story file tasks with inline Jira keys = already synced (skip). NO keys = create subtasks.
-- **Sync Marking:** After creating subtasks, updates story file with inline keys (Step G) - prevents duplicate creation
-- **Valid Status:** Only "Approved" or "Done" stories are synced
-- **Status Updates:** Step 7 asks IF update, Step 8 (if yes) asks WHAT status, then updates subtasks + stories
-- **Sequential Processing:** One story at a time to avoid rate limits
-- **Force Option:** Option 3 re-syncs stories (creates duplicate subtasks - caution)
-
-## Related Commands
-
-- `*sync-story-to-jira {story}` - Sync individual story
-- `*sync-epic-to-jira {epic-number}` - Sync all stories from epic (with optional status updates)
-- `*update-epic-status {epic-number}` - Update statuses manually (if declined Step 7)
-- `*validate-story-draft` - Validate story before approval
-- `*jira-setup` - Configure Jira integration