siesa-agents 2.1.28 → 2.1.29

package/bmad-core/tasks/jira-setup.md

@@ -0,0 +1,396 @@
+<!-- Powered by BMAD™ Core -->
+
+# Jira Setup Task
+
+## Purpose
+
+Configure project-specific Jira integration by collecting project information and validating authentication with Jira Cloud. This task interactively guides the user through setup and automatically retrieves project details using the Jira MCP integration.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- Setting up Jira integration for the first time
+- `docs/jira-conf.md` doesn't exist
+- Reconfiguring Jira connection for a different project
+- Jira authentication needs to be validated
+
+**Prerequisites:**
+
+- Jira MCP integration must be available
+- User must have access to a Jira Cloud instance
+- User must know their Jira project key (or be able to find it)
+
+## Instructions
+
+### Phase 1: Pre-Configuration Validation
+
+#### Step 1: Check for Existing Configuration
+
+**Action:** Check if configuration already exists
+
+- [ ] Check if `docs/jira-conf.md` exists
+- [ ] If exists, load current configuration
+- [ ] Display current settings to user
+
+**If Configuration Exists:**
+```elicit
+path: Configuration already exists
+format: |
+  ⚠️ Jira configuration already exists at `docs/jira-conf.md`
+  
+  Current Settings:
+  - Project Key: {{current_project_key}}
+  - Project Name: {{current_project_name}}
+  - Cloud ID: {{current_cloud_id}}
+  
+  Options:
+  1. Keep existing configuration (cancel setup)
+  2. Reconfigure with new project
+  3. Validate and update existing configuration
+  
+  Enter selection (1-3):
+```
+
+**If User Selects Option 1:** Exit task gracefully
+**If User Selects Option 2:** Continue to Step 2
+**If User Selects Option 3:** Skip to Step 4 (validation)
+
+#### Step 2: Elicit Project Key
+
+**CRITICAL:** This step requires user interaction - DO NOT skip or auto-fill
+
+```elicit
+path: Collect Jira project key
+format: |
+  🔧 Jira Project Configuration
+  
+  I need your Jira Project Key to set up the integration.
+  The Cloud ID and Jira URL will be retrieved automatically via MCP.
+  
+  **Jira Project Key**
+  Your project key (e.g., PM, PROJ, SCRUM)
+  
+  💡 Find it in Jira: Project Settings > Details
+  💡 Usually 2-10 uppercase letters
+  
+  Enter Project Key:
+```
+
+**Action:** Validate project key format
+
+- [ ] Ensure not empty
+- [ ] Convert to uppercase if needed
+- [ ] Typically 2-10 characters
+- [ ] Store project key
+- [ ] If invalid, re-prompt user
+
+### Phase 2: Retrieve Project Details via MCP
+
+#### Step 3: Authenticate and Retrieve Cloud ID
+
+**CRITICAL:** Use MCP to authenticate and automatically retrieve Jira Cloud ID
+
+**Note:** If authentication fails here during setup, this is expected for first-time configuration. However, for subsequent operations after setup is complete, always use `validate-jira-auth.md` task to check authentication before proceeding.
+
+**Action:** Use GitKraken MCP to retrieve accessible Jira resources
+
+```output
+🔄 Connecting to Jira via MCP...
+🔄 Retrieving Cloud ID for project: {{project_key}}
+```
+
+**Execute MCP Call:**
+
+```action
+Call MCP Function: mcp_gitkraken_issues_assigned_to_me
+Parameters:
+  - provider: "jira"
+  
+This call will:
+1. Trigger Jira authentication if not already authenticated (browser OAuth flow)
+2. Return issues which contain the cloudId in the response metadata
+3. Extract the Cloud ID from the response
+```
+
+**Expected Outcomes:**
+
+**Authentication Required (First Time):**
+```output
+🔐 Jira Authentication Required
+
+A browser window will open for Jira authentication.
+
+Steps:
+1. Browser opens automatically to Jira login
+2. Log in with your Jira account
+3. Authorize the MCP integration
+4. Return here when authentication is complete
+
+⏳ Waiting for authentication...
+```
+
+**After user authenticates, the MCP call will return with cloudId**
+
+**Success - Cloud ID Retrieved:**
+```output
+✅ Authentication successful!
+✅ Cloud ID retrieved: {{cloud_id}}
+✅ Jira URL detected: {{jira_url}}
+
+Validating project access for: {{project_key}}
+```
+
+**Authentication Failed:**
+```elicit
+path: Authentication failed
+format: |
+  ❌ Failed to authenticate with Jira
+  
+  Error: {{error_message}}
+  
+  Possible causes:
+  - MCP integration not configured
+  - Network issues
+  - Browser blocked OAuth flow
+  - User cancelled authentication
+  
+  Options:
+  1. Retry authentication
+  2. Check MCP server status
+  3. Cancel setup
+  
+  Enter selection (1-3):
+```
+
+**If Option 1:** Retry Step 3
+**If Option 2:** Display MCP troubleshooting help, then retry
+**If Option 3:** Exit task gracefully
+
+#### Step 4: Verify Project Access and Get Project Name
+
+**Action:** Use the retrieved Cloud ID to verify project access and get project details
+
+```output
+🔄 Verifying project access...
+🔄 Retrieving project name for: {{project_key}}
+```
+
+**Execute MCP Call:**
+
+```action
+Call MCP Function: mcp_gitkraken_issues_assigned_to_me
+Parameters:
+  - provider: "jira"
+  
+From the response:
+1. Verify issues from the specified project are accessible
+2. Extract Project Name from issue metadata
+3. Confirm the project exists and user has access
+```
+
+**Alternative - If no issues assigned:**
+```action
+You can also try to search for any issue in the project to verify access.
+The response will contain project metadata including the project name.
+```
+
+**Expected Output:**
+```output
+✅ Project Verification Complete
+
+Retrieved Details:
+- Project Key: {{project_key}}
+- Project Name: {{project_name}} (retrieved from Jira)
+- Cloud ID: {{cloud_id}} (retrieved via MCP)
+- Jira URL: {{jira_url}} (detected from MCP)
+- Access: Confirmed ✓
+
+All information retrieved successfully via MCP.
+```
+
+**Project Not Found:**
+```elicit
+path: Project not accessible
+format: |
+  ❌ Cannot access project: {{project_key}}
+  
+  Possible causes:
+  - Project key is incorrect
+  - User doesn't have access to this project
+  - Project doesn't exist
+  
+  Options:
+  1. Re-enter project key
+  2. Request project access from Jira admin
+  3. Cancel setup
+  
+  Enter selection (1-3):
+```
+
+**If Option 1:** Return to Step 2
+**If Option 2:** Display Jira admin contact info, then exit
+**If Option 3:** Exit task gracefully
+
+### Phase 3: Configuration File Creation
+
+#### Step 5: Create Configuration File
+
+**Action:** Create `docs/jira-conf.md` with validated settings
+
+- [ ] Create `docs/` directory if it doesn't exist
+- [ ] Load template from `.bmad-core/templates/jira-conf-tmpl.md`
+- [ ] Replace placeholders:
+  - `{PROJECT_KEY}` → validated project key
+  - `{PROJECT_NAME}` → project name (or project key if not provided)
+  - `{CLOUD_ID}` → validated cloud ID
+- [ ] Add Jira URL as additional metadata
+- [ ] Write file to `docs/jira-conf.md`
+
+**Template Content:**
+```markdown
+# Jira Project Configuration
+
+**Project Key:** `{{project_key}}`
+**Project Name:** `{{project_name}}`
+**Cloud ID:** `{{cloud_id}}`
+**Jira URL:** `{{jira_url}}`
+
+---
+
+_Note: Cloud ID and Jira URL were automatically retrieved via MCP during `*jira-setup`._
+_Last Updated: {{current_date}}_
+```
+
+#### Step 6: Store Authentication Reference
+
+**Action:** Optionally create a reference file in `.claude/instructions.md` for persistent context
+
+```markdown
+Create or update `.claude/instructions.md` with:
+
+# Instrucciones para Jira - Proyecto {{project_key}}
+
+## Configuracion del Proyecto
+- **Cloud ID:** {{cloud_id}}
+- **Project Key:** {{project_key}}
+- **URL:** {{jira_url}}
+
+## Reglas para crear Issues
+
+### Story (Historia de Usuario)
+Al crear una **Story** en el proyecto {{project_key}}, SIEMPRE debes:
+
+1. Solicitar al usuario los "Criterios de Aceptacion" antes de crear el issue
+2. Incluir el campo personalizado para criterios de aceptacion si está disponible
+
+_(Add project-specific Jira instructions here)_
+```
+
+#### Step 7: Final Confirmation
+
+```output
+═══════════════════════════════════════════════════════════════
+  ✅ JIRA SETUP COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Configuration saved to: `docs/jira-conf.md`
+
+Project Details:
+- Project Key: {{project_key}}
+- Project Name: {{project_name}}
+- Cloud ID: {{cloud_id}}
+- Jira URL: {{jira_url}}
+- Authentication: ✅ Verified
+
+Available Commands:
+- `*sync-prd-to-jira` - Sync PRD epics and stories to Jira
+- `*create-epic` - Create individual epic in Jira
+- `*create-story` - Create individual story in Jira
+- `*sync-story-to-jira` - Sync story tasks/subtasks to Jira
+
+Next Steps:
+1. Use these commands to sync your documentation with Jira
+2. All Jira operations will now use the configured project
+3. Re-run `*jira-setup` anytime to reconfigure
+
+═══════════════════════════════════════════════════════════════
+```
+
+## Success Criteria
+
+The setup is successful when:
+
+1. User provided valid Jira URL, Project Key, and Cloud ID
+2. MCP Jira authentication completed successfully
+3. Project access verified
+4. Configuration file created at `docs/jira-conf.md`
+5. All settings validated and working
+
+## Error Handling
+
+### Invalid URL Format
+```output
+❌ Invalid Jira URL format
+
+Expected: https://yourcompany.atlassian.net
+Received: {{invalid_url}}
+
+Please enter a valid Jira Cloud URL.
+```
+
+### Invalid Cloud ID Format
+```output
+❌ Invalid Cloud ID format
+
+Expected: UUID format (e.g., 3b04e1a3-a260-4679-bdc8-0440507fbe26)
+Received: {{invalid_cloud_id}}
+
+Please enter a valid Cloud ID.
+```
+
+### Authentication Timeout
+```output
+⏱️ Authentication timeout
+
+The authentication process took too long or was cancelled.
+
+Options:
+1. Retry authentication
+2. Check MCP integration status
+3. Cancel setup
+
+Enter selection (1-3):
+```
+
+### MCP Not Available
+```output
+❌ Jira MCP Integration Not Available
+
+The GitKraken MCP integration for Jira is not available.
+
+Please ensure:
+1. MCP is properly installed and configured
+2. GitKraken MCP server is running
+3. Jira provider is enabled in MCP settings
+
+Cannot proceed without MCP integration.
+```
+
+## Important Notes
+
+- **User Input Required:** Only Project Key needs to be provided by user
+- **Automatic Retrieval:** Cloud ID and Jira URL are retrieved automatically via MCP
+- **Authentication:** MCP handles OAuth flow automatically via browser
+- **Project Name:** Retrieved from Jira metadata automatically
+- **Validation:** Always validate authentication before saving configuration
+- **Re-configuration:** Safe to run multiple times - will prompt before overwriting
+- **Template Dependency:** Requires `.bmad-core/templates/jira-conf-tmpl.md`
+- **MCP Dependency:** Requires GitKraken MCP with Jira integration
+
+## Related Commands
+
+- `*sync-prd-to-jira` - Sync PRD to Jira (requires this setup)
+- `*create-epic` - Create Jira epic (requires this setup)
+- `*create-story` - Create Jira story (requires this setup)
+- `*sync-story-to-jira` - Sync story tasks (requires this setup)