@cloudkinetix/bmad-enhanced/expansion-packs/ck-jira-integration/tasks/setup.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# setup

Streamlined setup wizard that auto-detects JIRA project keys and Git repositories. Assumes Atlassian MCP is already configured.

## TODO TOOL INTEGRATION - MANDATORY FOR COMPLEX SETUP

[[LLM: CRITICAL - This is a complex multi-step task requiring todo tool usage:

MANDATORY TODO TOOL ACTIVATION:
Before starting setup, MUST use todo_tool to break down the complex workflow:

1. ALWAYS say "use todo_tool" or "break down this task step by step" first
2. Create specific, actionable subtasks for:
   - JIRA project detection and validation
   - Git repository discovery and configuration
   - Team member analysis and role assignment
   - Configuration file generation and validation
   - Initial sync testing and verification
3. Execute tasks one by one, updating status as you progress
4. Only mark tasks complete when fully accomplished with all validation steps done

Keywords that trigger planning mode:

- "use todo_tool"
- "break down this task step by step"
- "create a step-by-step plan"
- "use planning tool"
- "decompose this complex task"

This ensures systematic execution and prevents missing critical setup steps.
]]

[[LLM: CRITICAL REQUIREMENT - This setup MUST detect and configure Git repositories!
The setup will FAIL if Git repositories are not properly detected and configured.
You MUST run actual Git commands using the Bash tool to detect repositories.
DO NOT skip the Git detection step or create empty repository configurations!]]

## Core Philosophy

Make JIRA setup fast and intelligent:

1. **Auto-detect JIRA project keys** from git commits and branches
2. **Confirm project key** with user (no authentication needed)
3. **Detect Git repositories** in workspace
4. **Test MCP connectivity** by validating project
5. **Configure field mappings** automatically
6. **Create project mapping file** for all operations

**Key Assumption**: Atlassian MCP is already installed and configured with JIRA credentials. We only need to know which project and repositories to work with.

## Natural Language Triggers

- "setup jira"
- "configure jira"
- "jira setup"
- "connect to jira"
- "initialize jira"
- "jira configuration"

## Intelligent Setup Flow

### Phase 1: Auto-Detection First

[[LLM: Before asking ANY questions, perform comprehensive detection:

1. JIRA Project Key Detection:
   - Scan git commits for patterns like [A-Z]+-\d+ (e.g., AUTH-123, CORE-456)
   - Extract unique project keys and count occurrences
   - Check branch names for project key patterns
   - Scan BMAD stories for JIRA references in metadata
   - Identify most common project key as primary

2. Git Repository Detection:
   - Current repository (always included)
   - Use `git rev-parse --show-toplevel` to get repo root
   - Use `git remote -v` to get remote URLs
   - Check parent directory for other git repos
   - Look for monorepo structure (multiple projects in subdirs)
   - Scan for workspace/project configuration files
   - Check git submodules with `git submodule status`
   - Detect default branch with `git symbolic-ref refs/remotes/origin/HEAD`
   - Check for git flow branches (master/main, develop)
   - Look for references to other repos in docs/configs

3. Additional Detection:
   - JIRA URLs in commits/docs
   - Team size from contributors
   - Existing config files
   - MCP tool availability

4. Learning Tracking:
   - Log: setup_start event with timestamp
   - Track: auto_detection_success rate
   - Monitor: time spent in detection phase
   - Record: detected_items_count
     ]]

### Phase 2: Streamlined Setup

#### Opening Greeting

[[LLM: Start with project detection:
"I'll set up JIRA integration for your workspace. Let me detect your project structure...

🔍 Scanning for JIRA project keys in your codebase..."

[[LLM: Wait 1-2 seconds for effect, then show results]]

{{IF project_keys_found}}
"🎯 Found these JIRA project keys:
{{#each detected_keys}}
• **{{key}}** ({{count}} references in commits/branches)
{{/each}}

📦 I'll use **{{most_common_key}}** as your primary project."
{{ELSE}}
"🤔 I didn't find any JIRA project keys in your commits or branches.

What's your JIRA project key? (e.g., PROJ, AUTH, CORE)"
{{/IF}}
]]

**Example Output:**

```
I'll help you set up JIRA integration! Let me analyze your workspace...

🔍 Scanning for JIRA project keys and Git repositories...

📋 **JIRA Project Keys Found:**
   - AUTH (47 references)
   - CORE (12 references)
   - WEB (3 references)

**Primary Project**: AUTH

🗂️ **Git Repositories Detected:**
   1. /Users/dev/auth-service
      └─ git@github.com:company/auth-service.git
   2. /Users/dev/core-platform
      └─ git@github.com:company/core-platform.git
   3. /Users/dev/web-frontend
      └─ git@github.com:company/web-frontend.git

🌐 **JIRA Instance**: https://company.atlassian.net

✅ MCP tools: Installed

Is this correct? Let me confirm before we proceed:
```

#### Step 1: Quick Confirmation

{{IF project_keys_found}}
"Is **{{most_common_key}}** correct? (y/n)"

[[LLM:

- If 'y': Store project key and continue
- If 'n': "What's your project key?"
  ]]
  {{ELSE}}
  [[LLM: Wait for user to provide project key]]
  {{/IF}}

#### Step 2: Git Repository Detection

[[LLM: ABSOLUTELY MANDATORY - You MUST run these Git commands NOW using the Bash tool:

STOP AND RUN THESE COMMANDS BEFORE CONTINUING:

1. First, get current repository information:

```bash
echo "=== Current Repository ==="
pwd
git rev-parse --show-toplevel 2>/dev/null || echo "Not a git repository"
git remote -v 2>/dev/null || echo "No remotes configured"
git branch -r 2>/dev/null | head -5 || echo "No remote branches"
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
```

2. Check for submodules:

```bash
echo "=== Submodules ==="
git submodule status 2>/dev/null || echo "No submodules"
```

3. Look for other repositories in parent directory:

```bash
echo "=== Scanning for other repositories ==="
parent_dir=$(dirname $(pwd))
find "$parent_dir" -maxdepth 2 -name ".git" -type d 2>/dev/null | grep -v "$(pwd)/.git" | while read gitdir; do
  repo_path=$(dirname "$gitdir")
  echo "Found: $repo_path"
  cd "$repo_path" && git remote -v | head -1
done
```

DO NOT PROCEED until you have run ALL these commands and collected the Git repository data!
]]

"I'm detecting your Git repositories now...

[[LLM: You MUST show the ACTUAL bash output from running the commands above!
Example of what you should see and display:

=== Current Repository ===
/Users/dev/my-project
/Users/dev/my-project
origin git@github.com:company/my-project.git (fetch)
origin git@github.com:company/my-project.git (push)
origin/develop
origin/main
origin/feature/auth
main

=== Submodules ===
160000 abc123... 0 libs/shared-utils (v1.2.3)

=== Scanning for other repositories ===
Found: /Users/dev/api-service
origin git@github.com:company/api-service.git (fetch)
]]

Based on my Git detection:

🗂️ **Current Repository:**
Path: {{current_repo_path}}
Remote: {{primary_remote_url}}
Main branch: {{detected_main_branch}}
Develop branch: {{detected_develop_branch or 'not found'}}

{{IF other_repos_found}}
📦 **Additional Repositories Found:**
{{#each other_repos}}
{{number}}. {{name}}
Path: {{path}}
Remote: {{remote_url}}
{{/each}}
{{/IF}}

{{IF submodules_found}}
📎 **Submodules Detected:**
{{#each submodules}}

- {{name}} ({{path}})
  {{/each}}
  {{/IF}}

**Include all repositories for {{project_key}}?** (y/n/custom)"

[[LLM:

- If 'y': Include all detected repositories
- If 'n': "Using only the current repository: {{current_path}}"
- If 'custom': "Which repositories should I include? (comma-separated numbers)"
- REQUIRED: At least one repository must be configured
  ]]

#### Step 3: Project Validation

"Validating '{{confirmed_project_key}}' with JIRA..."

[[LLM: Use mcp__mcp-atlassian__jira_search with JQL: "project = {{confirmed_project_key}}"]]

{{IF mcp_call_successful}}
{{IF results_found}}
"✅ Connected! Found {{issue_count}} issues in {{confirmed_project_key}}."
{{ELSE}}
"⚠️ Project '{{confirmed_project_key}}' exists but has no issues yet."
{{/IF}}
{{ELSE}}
"❌ Cannot connect to JIRA. The Atlassian MCP needs to be configured.

To set up the MCP:

1. Install: `mcp install @modelcontextprotocol/atlassian`
2. Configure with your JIRA URL and API token
3. Restart your IDE
4. Run setup again

Would you like detailed instructions? (y/n)"
{{/IF}}

[[LLM: Continue only if MCP connection successful]]

#### Step 4: Team Configuration (CRITICAL)

[[LLM: IMPORTANT - This is a CRITICAL setup step that should NEVER be skipped!
The feedback shows users need comprehensive team configuration early in the setup process.]]

"🎯 **Team Configuration** - This is essential for effective JIRA integration!

Let me analyze your team structure for smart assignments and role-based workflows..."

[[LLM: MANDATORY Team Discovery Process:

1. Git History Analysis - ALWAYS run these commands:

   ```bash
   echo "=== Analyzing team contributors ==="
   git log --format='%ae|%an' --since='90 days ago' | sort | uniq -c | sort -rn | head -20
   echo "\n=== Component ownership patterns ==="
   git log --format='%an' --since='90 days ago' -- src/frontend | sort | uniq -c | sort -rn | head -5
   git log --format='%an' --since='90 days ago' -- src/backend | sort | uniq -c | sort -rn | head -5
   git log --format='%an' --since='90 days ago' -- infrastructure | sort | uniq -c | sort -rn | head -5
   ```

2. Show discovered team members immediately:
   "📊 **Team Analysis Results**:

   Found {{contributor_count}} active contributors:
   {{#each contributors}}
   • {{name}} ({{email}}) - {{commit_count}} commits
   Primary areas: {{detected_components}}
   {{/each}}"

3. JIRA account matching:
   - Query JIRA for project members
   - Match emails to JIRA usernames
   - Show matching confidence
     ]]

"Now let's configure your team roles. This helps with:
✅ Automatic story assignment based on expertise
✅ Component ownership for better routing
✅ Sprint role assignments (PO, SM, Tech Lead)
✅ Workload balancing and capacity planning

**Team Role Configuration**:"

[[LLM: Interactive team configuration:

1. For each discovered member, ask:
   "{{name}} ({{email}}):
   - JIRA username: [auto-detected: {{jira_username}} or ask]
   - Primary role: (1) Frontend (2) Backend (3) Full-stack (4) DevOps (5) QA (6) Other
   - Component ownership: {{suggested_components}}
   - Sprint role: (1) Developer (2) Tech Lead (3) Product Owner (4) Scrum Master
     Correct? (y/n/edit)"

2. Component ownership mapping:
   "Let's map component ownership for automatic assignment:

   Frontend → {{suggested_frontend_lead}}
   Backend → {{suggested_backend_lead}}
   Infrastructure → {{suggested_infra_lead}}

   Add more components? (y/n)"

3. Sprint roles:
   "Who fills these key sprint roles?
   - Product Owner: {{suggested_po or 'Not set'}}
   - Scrum Master: {{suggested_sm or 'Not set'}}
   - Tech Lead: {{suggested_tech_lead or 'Not set'}}
     These help with meeting agendas and reports."
     ]]

{{IF no_team_members_configured}}
"⚠️ **WARNING**: No team members configured!

This will limit JIRA integration features:

- No automatic assignment
- Generic reports without ownership
- Manual work distribution

Are you sure you want to skip team configuration? (y/n)"

[[LLM: If user insists on skipping:

- Log: team_config_skipped event
- Add note to remind them later
- Continue but mark as incomplete setup]]
  {{/IF}}

#### Step 5: Smart Field Mapping

"Now I'll set up field mappings. I'll detect your JIRA's custom fields...

✓ Found Epic Link field (customfield_10014)
✓ Found Story Points field (customfield_10016)
✓ Found Sprint field (customfield_10020)

I'll map these automatically. Want to see advanced options? (y/n)"

[[LLM: Auto-detect and map fields intelligently]]

**Common Mappings**:

```yaml
field_mappings:
  epic_link: customfield_10014
  story_points: customfield_10016
  sprint: customfield_10020
  acceptance_criteria: customfield_10035
```

#### Step 6: Advanced Team Features

"Would you like to configure advanced team features?

1. **Skill Matrix**: Track team skills and expertise areas
2. **Capacity Planning**: Set weekly hour allocations
3. **Notification Preferences**: Who gets notified for what
4. **Auto-assignment Rules**: Complex routing based on skills

Configure now? (y/n/later)"

[[LLM: These are optional enhancements that can be configured later]]

#### Step 7: Sync Preferences

"How should I sync your work?

1. 🚀 Real-time (sync on every change)
2. ⏰ Scheduled (sync every hour)
3. 🤚 Manual (sync when you ask)

Most teams prefer scheduled. Sound good? (y/n)"

### Phase 3: Final Configuration

#### Configuration Summary

"Here's your JIRA integration configuration:

📋 **JIRA Project**: {{project_key}} - {{project_name}}

🗂️ **Git Repositories** ({{repo_count}} total):
Primary: {{primary_repo_name}} ({{primary_repo_path}})
{{#each additional_repos}}

- {{name}} ({{path}})
  {{/each}}
  {{#if submodules}}
  Submodules: {{submodule_count}} detected
  {{/if}}

🌿 **Git Flow**:
Main branch: {{main_branch}}
Develop branch: {{develop_branch}}

⚙️ **Sync Mode**: {{sync_mode}}

👥 **Team Members**: {{team_member_count}} discovered
{{#each team_members_summary}}

- {{display_name}} ({{primary_role}})
  {{/each}}

✅ All required fields configured and validated!"

#### Preview Mode

"Want to see what would sync? (Recommended for first time)

Found in BMAD docs:

- 12 stories not in JIRA
- 3 stories needing updates
- 5 completed stories to close

Preview the sync plan? (y/n)"

### Phase 4: Create Configuration Files

[[LLM: Understand team's workflow:

1. Get issue types: Story, Task, Bug, Epic
2. Get statuses: To Do, In Progress, Done, etc.
3. Map BMAD states to JIRA workflow
4. Configure transition names
   ]]

**Workflow Config**:

```yaml
workflows:
  story_states:
    draft: "To Do"
    ready: "To Do"
    assigned: "In Progress"
    complete: "Done"

  transitions:
    start_work: "Start Progress"
    complete: "Resolve Issue"
```

### Step 8: Git Flow Configuration

[[LLM: Configure Git flow branches]]

"Let me confirm your Git flow configuration:

**Main/Master branch**: {{detected_main_branch}} ✓
**Develop branch**: {{detected_develop_branch or 'develop (not found)'}}

Is this correct? (y/n/custom)"

[[LLM:

- If 'y': Use detected branches
- If 'n' or 'custom':
  - "What's your main branch name? (e.g., main, master)"
  - "What's your develop branch name? (e.g., develop, dev)"
- Store branch configuration for git analysis
  ]]

**Create Project Mapping File**:
[[LLM: Use jira-expansion-config-tmpl.yaml template to create configuration]]
`.bmad-workspace/ck-jira-integration/config/jira-expansion-config.yaml`

```yaml
jira:
  project_key: {{project_key}}
  project_name: {{project_name}}
  instance_url: {{instance_url}}

git:
  flow:
    main_branch: {{main_branch}}
    develop_branch: {{develop_branch}}

  primary:
    path: {{current_directory}}
    remote_url: {{primary_remote}}
    name: {{repo_name}}

  repositories:
    {{#each additional_repos}}
    - name: {{name}}
      path: {{path}}
      remote_url: {{remote_url}}
    {{/each}}

  {{IF submodules}}
  submodules:
    {{#each submodules}}
    - name: {{name}}
      path: {{path}}
    {{/each}}
  {{/IF}}

# Team configuration (REQUIRED)
team:
  discovery:
    enabled: true
    git_history_days: 90
    auto_role_detection: true

  size: "{{team_size}}"
  distributed: {{is_distributed}}

  # Sprint roles
  sprint_roles:
    product_owner: "{{product_owner_username}}"
    scrum_master: "{{scrum_master_username}}"
    tech_lead: "{{tech_lead_username}}"

  # Component ownership
  component_owners:
    {{#each components}}
    {{name}}: "{{owner_username}}"
    {{/each}}

  # Team members with roles
  members:
    {{#each team_members}}
    - jira_username: "{{jira_username}}"
      display_name: "{{display_name}}"
      git_emails:
        {{#each git_emails}}
        - "{{this}}"
        {{/each}}
      primary_role: "{{primary_role}}"
      technical_role: "{{technical_role}}" # frontend, backend, fullstack, devops, qa
      confidence: {{role_confidence}}
      specializations:
        {{#each specializations}}
        - "{{this}}"
        {{/each}}
      component_ownership:
        {{#each owned_components}}
        - "{{this}}"
        {{/each}}
    {{/each}}

  # Auto-assignment rules
  assignment_rules:
    by_component: true
    by_expertise: true
    load_balancing: true

# Features configuration
features:
  team_discovery: true
  smart_assignment: true
  role_based_reports: true
```

[[LLM: CRITICAL - Validate configuration before saving:

STOP! CHECK THESE REQUIRED FIELDS:

1. ❌ REQUIRED: jira.project_key must be set and not empty
2. ❌ REQUIRED: git.primary.path must be set to actual git repository path
3. ❌ REQUIRED: git.primary.remote_url must be set from git remote -v output
4. ❌ REQUIRED: git.flow.main_branch must be set (detected or confirmed)
5. ❌ REQUIRED: At least git.primary OR git.repositories must have entries

ERROR MESSAGES if validation fails:

- If git.primary.path is empty: "❌ ERROR: No Git repository detected. Please run this command from inside a Git repository."
- If git.primary.remote_url is empty: "❌ ERROR: No Git remote found. Please ensure your repository has a remote configured."
- If no repositories: "❌ ERROR: At least one Git repository must be configured."

DO NOT CREATE THE FILE if any validation fails!
Instead, show the error and guide the user to fix it.
]]

### Step 9: Validate Team Configuration

[[LLM: Validate the team setup:

1. Verify all JIRA usernames exist in the project
2. Check component assignments have owners
3. Confirm sprint roles are filled
4. Test auto-assignment rules
5. Generate team roster report
   ]]

"Let me validate your team configuration...

✅ Team members verified in JIRA: {{verified_count}}/{{total_count}}
✅ Components with owners: {{owned_components}}/{{total_components}}
✅ Sprint roles configured: {{configured_roles}}/3
✅ Auto-assignment rules: {{enabled_rules}}

Your team is ready for smart JIRA integration!"

### Step 7: Initial Sync Test

[[LLM: Validate setup with test sync:

1. Create test story in BMAD
2. Sync to JIRA using configured mappings
3. Verify all fields mapped correctly
4. Test status transitions
5. Clean up test data
   ]]

### Step 8: Three-Way Validation

**Verify Complete Integration**:

1. BMAD → JIRA: Story creation works
2. JIRA → BMAD: Updates reflect back
3. Git → JIRA: Commits link to tickets
4. Full correlation health check

## Smart Error Recovery

### MCP Not Installed

[[LLM: Log learning event - MCP installation struggle]]

"The JIRA MCP tools aren't installed yet. Here's how to fix it:

1. Run: npm install -g @modelcontextprotocol/atlassian
2. Restart your IDE
3. Run 'setup jira' again

Need help with installation? (y/n)"

### Authentication Failed

[[LLM: Log learning event - authentication difficulty, track retry count]]

"Hmm, I couldn't connect to JIRA. This usually happens when:

• The API token was copied incorrectly (most common!)
• The JIRA URL needs tweaking
• Your network has restrictions

Let's fix it:

1. First, check if {{jira_url}} opens in your browser
2. Make sure you copied the entire API token
3. Try again - I'll help you through it!"

### Permission Issues

"I can connect but lack permissions for:

- Creating issues
- Viewing custom fields

Please ask your JIRA admin to grant 'Browse Projects' and
'Create Issues' permissions for your account."

## Configuration Management

### File Structure

```
.bmad-workspace/ck-jira-integration/
└── config/
    ├── jira-expansion-config.yaml  # Main configuration with team data
    ├── field-mappings.yaml   # Field mappings
    ├── workflow-rules.yaml   # Workflow configuration
    └── team-roster.yaml      # Detailed team configuration backup
```

[[LLM: CRITICAL PATH VALIDATION
Always create configuration in the correct location:
✅ CORRECT: .bmad-workspace/ck-jira-integration/config/
❌ WRONG: .jira-config/
❌ WRONG: .bmad-workspace/config/

If directories don't exist, create them with proper structure!]]

### Configuration Validation

[[LLM: After each change:

1. Validate YAML syntax
2. Test configuration works
3. Backup previous config
4. Log configuration changes
   ]]

## Advanced Setup Options

### Multi-Project Setup

- Configure multiple JIRA projects
- Set project selection rules
- Map BMAD folders to projects

### Custom Field Handlers

- Complex field type mappings
- Calculated field values
- Field transformation rules

### Automation Rules

- Auto-sync triggers
- Batch sync schedules
- Webhook configurations

### Phase 5: Success & Next Steps

[[LLM: Log successful setup with timing and path taken]]

"✅ JIRA integration configured successfully!

You can now:

1. 'sync' - Start syncing stories
2. 'jira status' - Check sync health
3. 'create standup' - Generate team updates
4. 'help jira' - See all commands

Want me to do a test sync of one story? (y/n)"

[[LLM: Check if this is a good moment for feedback reminder - successful setup is a natural break]]

## Advanced Setup Modes

### Reconfiguration Mode

When config exists:
"I see you have JIRA configured already.

Current setup:

- URL: {{current_url}}
- Project: {{current_project}}
- Last sync: {{last_sync}}

What would you like to change?

1. Different project
2. Update credentials
3. Change sync settings
4. Start fresh"

### Team Setup Mode

"Setting up for a team? I'll help with:

- User mapping (Git ↔ JIRA accounts)
- Permission validation
- Workflow standardization
- Team notifications

How many team members? {{team_size}}"

## Reconfiguration

### Updating Settings

- "setup jira fields" → Just field mapping
- "setup jira workflow" → Just workflow
- "setup jira team" → Just team config

### Reset Options

- "reset jira setup" → Start over
- "validate jira setup" → Health check
- "test jira connection" → Connection only

## Smart Defaults & Success Patterns

### Quick Setup (2 minutes)

1. Auto-detect most settings
2. Confirm 3-4 key values
3. Use all defaults
4. Test with preview
5. Save and done

### Team Migration (15 minutes)

1. Review auto-detected values
2. Map team members
3. Set preferences
4. Test thoroughly
5. Generate team guide

## Examples

### Minimal Setup

User: "setup jira"
_Auto-detects everything, confirms 3 values, done!_

### Fixing Issues

User: "jira setup is broken"
_Diagnoses current setup, identifies issues, fixes step-by-step_

### Team Onboarding

User: "setup jira for our team"
_Guides through user mapping, permissions, documentation_

This conversational wizard makes JIRA setup feel like chatting with a helpful expert rather than wrestling with configuration files.