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

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

# JIRA Integration for BMAD Method

Seamlessly sync your BMAD stories with JIRA through natural conversation. One unified assistant handles everything from setup to advanced operations.

## Meet Your JIRA Assistant

### 🎯 JIRA Integration Assistant

_Your complete guide for all JIRA operations_

Combining deep technical expertise with agile coaching skills, the JIRA Assistant handles everything from initial setup to advanced synchronization, sprint ceremonies to technical operations - all through a single, intelligent interface.

## Quick Start

```bash
# Install the expansion pack
npx @cloudkinetix/bmad-enhanced install --expansion-packs ck-jira-integration

# Start with the unified JIRA assistant
agent: jira
"setup"  # Guided setup with team discovery
```

## What Can I Do?

Work naturally with a single assistant:

**Core Operations:**

- **"setup"** - Configure JIRA with smart team discovery
- **"sync"** - Sync stories, sprints, or daily updates
- **"daily standup"** - Prepare meeting with three-way sync
- **"sprint planning"** - Plan your next sprint effectively

**Advanced Features:**

- **"sync this story"** - Intelligent story synchronization
- **"bulk sync epic"** - Handle multiple items efficiently
- **"analyze bugs"** - Deep technical analysis
- **"team health"** - Check integration and metrics
- **"roadmap view"** - Strategic planning visualization

The assistant uses numbered options to guide you through complex decisions.

## Key Features

### 🚀 Smart Setup with Team Discovery

The assistant guides you through comprehensive setup including team configuration:

```
"Hi! I'm your JIRA Integration Assistant.
Let me help you set up JIRA integration with smart team discovery.

I'll analyze your Git history to discover team members...
Found 5 active contributors. Let's configure their roles!"
```

### 📊 Visual Sync Dashboard

See your three-way sync health at a glance:

```
Git 🟢 ←→ 🟢 BMAD
     ↘    ↗
      🟡 JIRA
```

### 🎯 Natural Language

No commands needed. Just describe what you want:

- "sync all stories in this epic"
- "prepare tomorrow's standup"
- "show me last sprint's velocity"
- "analyze planning vs execution"

### 📈 Adaptive Intelligence

- **Small teams**: Manual sync, simple workflows
- **Large teams**: Real-time sync, advanced analytics
- **Auto-adjusts** based on your patterns

### 📋 Todo Tool Integration for Complex Tasks

For complex multi-step operations, the JIRA assistant automatically uses todo tools to ensure systematic execution:

```
For complex tasks like setup, sync, or backlog grooming:
1. "use todo_tool" - Automatically breaks down complex workflows
2. Creates specific, actionable subtasks
3. Tracks progress step-by-step
4. Only marks tasks complete when fully validated
```

**Automatically Triggers For:**

- **setup**: Project detection, team configuration, validation (13+ steps)
- **sync**: Three-way synchronization with multiple validation phases
- **jira-operations**: Complex operation routing and data processing
- **backlog**: Multi-dimensional story analysis and refinement

**Universal Keywords** (works across all LLMs):

- `"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 no critical steps are missed and provides clear progress tracking for complex JIRA operations.

## Framework-Compliant Architecture

### Quality Assurance Integration

Every major operation is validated with multi-level checklists:

- **Sprint Readiness**: Before starting new sprints
- **Sync Quality**: After synchronization operations
- **Integration Health**: Weekly system checkups

### Unified Workflow Management

The assistant seamlessly handles all workflows:

- Decision trees for different scenarios
- Intelligent operation selection based on context
- Quality gates at each step
- Team-aware automation

## Core Capabilities

### 1. Story Synchronization

Keeps BMAD stories and JIRA tickets in perfect sync:

- Bi-directional updates
- Bulk operations
- Smart field mapping
- Conflict resolution

### 2. Team Coordination

Run better meetings with AI assistance:

- Daily standups with git evidence
- Sprint planning and reviews
- Multi-timezone support
- Automated meeting notes

### 3. Analytics & Reporting

Get insights without the spreadsheets:

- Sprint health dashboards
- Velocity trends
- Bug analysis
- Roadmap visualization

### 4. Backlog Management

Keep your backlog healthy:

- Story readiness assessment
- Grooming session prep
- Estimation assistance
- Priority optimization

## Enhanced LLM-Native Capabilities (v1.3.0)

### 🧠 Advanced Context Management

The JIRA assistant now remembers your conversation context:

- **Session Memory**: Continues where you left off
- **Entity Understanding**: Knows "the story" means the one you're working on
- **Pattern Learning**: Adapts to your preferences (e.g., always includes subtasks)
- **Smart Suggestions**: Proactively offers relevant actions

Example:

```
You: "sync the epic"
Assistant: "I'll sync PAYMENT-100 that we discussed earlier..."
```

### ⚡ Intelligent Prompt Optimization

Dynamically optimizes JIRA operations for speed and accuracy:

- **Context-Aware Queries**: Enhances prompts with session data
- **Performance Tracking**: Learns which approaches work best
- **Adaptive Complexity**: Simplifies for beginners, streamlines for experts
- **Continuous Improvement**: A/B tests prompt variations

### 💬 Multi-Turn Reasoning

Complex operations now feel like natural conversations:

- **Progressive Disclosure**: Reveals complexity gradually
- **Guided Decisions**: Helps navigate choices step-by-step
- **Checkpoint Recovery**: Resume interrupted operations seamlessly
- **Natural Flow**: No more command memorization

Example Epic Breakdown:

```
Turn 1: "I've analyzed the epic - it's large with 8-12 potential stories"
Turn 2: "How would you like to break it down? By feature? By risk?"
Turn 3: "Here are the stories I generated. Want to refine any?"
Turn 4: "Great! Creating them in JIRA now..."
```

### 🔄 Intelligent Recovery

Never lose work due to interruptions:

- **Auto-Checkpointing**: Saves progress automatically
- **Seamless Resume**: Continue exactly where you left off
- **Context Restoration**: Remembers all decisions made
- **User-Friendly**: Natural conversation continuation

```
Next day: "Welcome back! You were syncing 15 stories and completed 8. Continue?"
```

### 📊 Adaptive Learning

Improves while preserving privacy:

- **Pattern Recognition**: Learns your team's workflows
- **Success Tracking**: Identifies what works well
- **Anonymous Metrics**: No personal data collected
- **Continuous Optimization**: Better with every use

## Getting Started

### Prerequisites

- JIRA access (any plan)
- API token from your JIRA profile
- BMAD Method installed

### First Time Setup

1. Say **"setup"** to the JIRA agent
2. Follow the 2-minute wizard
3. Test with one story
4. You're ready!

💡 **Tip**: Not ready to connect? Say **"show me what you can do"** for a demo!

## Common Workflows

### Daily Standup

```
"create standup"
```

Generates agenda with:

- Yesterday's git commits
- Today's planned work
- Current blockers
- Sprint burndown

### Sprint Planning

```
"analyze backlog for next sprint"
```

Shows:

- Story readiness scores
- Capacity recommendations
- Risk assessment
- Suggested sprint scope

### Bug Investigation

```
"analyze AUTH-123"
```

Provides:

- Root cause analysis
- Related commits
- Test suggestions
- Fix verification

## Tips & Tricks

### For New Users

Start simple:

1. Setup connection
2. Sync one story
3. Create a standup
4. Explore from there

### For Power Users

- Use JQL directly: `"find assignee = me AND sprint = current"`
- Bulk operations: `"sync all stories in epic AUTH-EPIC"`
- Custom reports: `"velocity trend last 6 sprints"`
- Automation: `"setup hourly sync"`

## Privacy & Feedback

This expansion pack includes a privacy-first learning system:

- Tracks anonymous usage patterns (no personal/project data)
- Helps improve the tool for everyone
- Gentle reminders to share feedback (max once/30 days)
- Review anytime: `.bmad-workspace/feedback/jira-expansion-learnings.md`

## Troubleshooting

### "JIRA not connected"

Run `"setup"` again - the wizard will fix it

### "Can't find my project"

The AI will list available projects after connecting

### "Sync seems slow"

Check your team size defaults - might need adjustment

## Recent Improvements (Based on User Feedback)

### v1.3.1 - Framework Compliance & UX Enhancements

- **Character Personas**: Meet Alex and Sarah, your dedicated integration team
- **Team Configuration**: Comprehensive team discovery during setup
- **Wiki Markup Conversion**: Automatic Markdown to JIRA formatting
- **Quality Checklists**: Multi-level validation for all operations
- **Correct Config Path**: Fixed to use `.bmad-workspace/ck-jira-integration/config/`

### v1.3.0 - LLM-Native Intelligence

- **Context Management**: Remembers conversation state
- **Prompt Optimization**: Faster, smarter operations
- **Checkpoint Recovery**: Resume interrupted work
- **Natural Language**: Even more intuitive

### v1.2.0 - Simplified Architecture

- **5 simple tasks** instead of 16 confusing ones
- **6 adaptive templates** that adjust to your needs
- **2-minute setup** with auto-detection
- **Visual dashboards** for instant understanding
- **Learning system** for continuous improvement

## Need Help?

- In-app: Just say **"help"**
- Issues: github.com/cloudkinetix/bmad-enhanced/issues
- Docs: docs.anthropic.com/en/docs/claude-code

---

_JIRA Integration v1.2.0 - Part of BMAD Method by Cloud Kinetix_