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

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

# sync

Intelligent team synchronization with powerful three-way sync analysis (Git + JIRA + BMAD) that adapts to your needs - from daily standups to global team coordination, automatically selecting the right format based on context while maintaining complete visibility across all three systems.

## TODO TOOL INTEGRATION - MANDATORY FOR COMPLEX SYNC

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

MANDATORY TODO TOOL ACTIVATION:
Before starting sync operations, 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:
   - Project mapping validation and configuration loading
   - Time accuracy checks and timezone handling
   - JIRA MCP connectivity verification
   - Three-way data collection (Git + JIRA + BMAD)
   - Sync health analysis and correlation scoring
   - Report generation and hyperlink creation
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 sync failures or incomplete data.
]]

## MCP Tool Requirements

[[LLM: CRITICAL - Before any sync operation:

1. PROJECT MAPPING VALIDATION:
   - Check if `.bmad-workspace/ck-jira-integration/config/jira-expansion-config.yaml` exists
   - If NOT exists, check legacy `.bmad-workspace/config/jira-expansion-config.yaml`
   - If NOT exists:
     - ERROR: "❌ JIRA expansion config not configured. Please run 'setup' first."
     - Guide user to run setup task
     - DO NOT proceed with sync
   - If exists:
     - Load configuration to get:
       - JIRA project key for queries
       - All git repository paths to analyze
       - Story paths to scan
     - Display active configuration:
     ```
     🔄 Sync Configuration:
     JIRA: {{project_key}} ({{instance_url}})
     Git: {{repository_count}} repositories
     ```

2. TIME ACCURACY CHECK:
   - Check if `mcp__MCP_DOCKER__get_current_time` is available
   - If available: Use with timezone "America/Los_Angeles" as default
   - For multi-timezone: Use `mcp__MCP_DOCKER__convert_time` for regional times
   - If NOT available: Add warning: "⚠️ TIME ACCURACY WARNING: Real-time data unavailable"

3. JIRA DATA CHECK:
   - List available tools and filter for prefix 'mcp**mcp-atlassian**'
   - If MCP tools are available, proceed with JIRA data collection
   - If NOT available: - Inform user that JIRA MCP is not configured - Offer to continue with git and BMAD data only
     ]]

## Core Philosophy

One sync command that intelligently adapts to what your team needs right now. The LLM should:

1. **Auto-detect sync type** from context and timing
2. **Always use three-way data** (Git + JIRA + BMAD) for complete visibility
3. **Scale detail level** to match urgency and audience
4. **Focus on actionability** with sync health prominently displayed
5. **Maintain three-way alignment** visibility always
6. **Highlight discrepancies** between systems proactively
7. **Optimize for your timezone** with global awareness

## Natural Language Triggers

### Universal Sync

- "sync"
- "sync team"
- "team sync"
- "sync up"
- "team update"

### Standup Specific

- "standup"
- "daily standup"
- "scrum"
- "daily scrum"
- "morning sync"

### Periodic Syncs

- "weekly sync"
- "sprint sync"
- "monthly sync"
- "quarterly review"

### Special Situations

- "emergency sync"
- "urgent update"
- "global sync"
- "distributed team sync"
- "executive sync"

## Intelligent Sync Detection

[[LLM: Automatically determine sync type:

1. Check Current Time:
   - Morning (6-10 AM PT) → Daily standup
   - Monday morning → Weekly sync
   - Sprint boundaries → Sprint sync
2. Parse Keywords:
   - "daily", "standup" → Daily format
   - "weekly", "sprint" → Comprehensive format
   - "emergency", "urgent" → Crisis format
   - "global", "distributed" → Multi-timezone format

3. Analyze Context:
   - Team size and distribution
   - Recent sync history
   - Current sprint phase
   - Active incidents
     ]]

## Daily Standup Mode

### Activation

- Morning requests
- "Daily" or "standup" keywords
- No sync in last 20 hours

[[LLM: Log: standup_initiated event with type='daily']]
[[LLM: Track: time_of_day and day_of_week patterns]]

### Data Collection

[[LLM: CRITICAL - Daily standup MUST include three-way sync analysis:

1. Load jira-expansion-config.yaml configuration
2. Collect data from ALL three sources (Git, JIRA, BMAD)
3. Correlate findings for complete picture
4. Generate hyperlinks for all references:
   - JIRA tickets: [{{key}}]({{instance_url}}/browse/{{key}})
   - BMAD stories: [{{story_name}}]({{relative_path_from_project_root}})
     Example: [Login Story](./docs/epics/auth/login.md) NOT file:// paths
   - Git commits: Include commit hash with branch context

This is NOT optional - three-way sync is the core value of this integration!
]]

**JIRA Data**:

- [[LLM: Use `mcp__mcp-atlassian__jira_search` with JQL: "project = {{project_key}} AND updated >= -1d"]]
- Yesterday's ticket updates (status changes, comments, assignments)
- Today's planned work (in progress, ready for dev)
- Current blockers (impediment flag, blocked status)
- Sprint burndown status

**Git Analysis**:
[[LLM: MANDATORY - Use JIRA expansion config for Git analysis:

1. Load all repositories from jira-expansion-config.yaml
2. For EACH repository, run the following commands:
   ]]

```bash
# For each repository in config:
cd {{repo_path}}

# Yesterday's commits per developer
git log --since="1 day ago" --author="{{dev}}" --oneline

# Active branches (check against configured flow branches)
git branch -r --no-merged {{main_branch}}
git branch -r --no-merged {{develop_branch}}

# Recent JIRA-related commits
git log --oneline --grep="{{project_key}}-" --since="1 day ago"
```

**BMAD Story Analysis**:

- [[LLM: Scan configured story paths from jira-expansion-config.yaml]]
- Stories updated in last 24 hours
- Story status changes (draft → ready → assigned)
- New acceptance criteria or changes
- Story point adjustments

### Three-Way Correlation

[[LLM: MANDATORY - Perform correlation analysis:

CRITICAL IMPLEMENTATION STEPS:

1. Use the universal-sync-analysis utility functions
2. Use the correlation-analysis utility algorithms
3. ACTUALLY CALCULATE the sync scores - don't just display placeholders!

DETAILED ANALYSIS REQUIRED:

1. **Git ↔ JIRA**: Match commits to tickets
   - Run: git log --oneline --grep="{{project_key}}-" --since="1 day ago" for EACH repo
   - Count commits with JIRA references vs total commits
   - Identify JIRA tickets in "Done" status without recent commits (phantom progress)
   - Calculate: (Commits with JIRA refs / Total commits) × 100

2. **JIRA ↔ BMAD**: Story alignment
   - List all BMAD stories in configured paths
   - Check each story for JIRA ticket reference in metadata
   - Verify JIRA ticket exists and matches story status
   - Calculate: (Stories with valid JIRA tickets / Total stories) × 100

3. **Git ↔ BMAD**: Implementation tracking
   - For each BMAD story, search for related commits
   - Match by: story filename, component paths, keywords
   - Assess implementation completeness
   - Calculate: (Stories with git activity / Total stories) × 100

4. **Sync Health Score**: Calculate ACTUAL percentages
   - Overall = (Git↔JIRA + JIRA↔BMAD + Git↔BMAD) / 3
   - Display actual calculated numbers, not placeholders
   - Green (>90%): Well synchronized
   - Yellow (70-90%): Minor discrepancies
   - Red (<70%): Needs attention

REMEMBER: The whole point of this expansion pack is three-way sync!
If you don't calculate real scores, the feature is useless!
]]

### Output Format

[[LLM: Use ACTUAL CALCULATED VALUES, not template placeholders!]]

```markdown
# Daily Standup - {{date}} {{time}}

{{#if time_accuracy_warning}}
⚠️ TIME ACCURACY WARNING: Real-time data unavailable
{{/if}}

## 📊 Three-Way Sync Health: {{ACTUAL_CALCULATED_PERCENTAGE}}% {{sync_indicator}}

### 🔄 Sync Status (with REAL numbers!)

- Git ↔ JIRA: {{ACTUAL_GIT_JIRA_PERCENTAGE}}% {{git_jira_status}}
  - Commits with JIRA refs: {{actual_count}} of {{total_commits}}
  - Orphaned commits: {{orphaned_count}}
  - Phantom tickets: {{phantom_count}}
- JIRA ↔ BMAD: {{ACTUAL_JIRA_BMAD_PERCENTAGE}}% {{jira_bmad_status}}
  - Stories with tickets: {{stories_with_tickets}} of {{total_stories}}
  - Missing tickets: {{missing_tickets_count}}
  - Status mismatches: {{mismatch_count}}
- Git ↔ BMAD: {{ACTUAL_GIT_BMAD_PERCENTAGE}}% {{git_bmad_status}}
  - Stories with commits: {{stories_with_commits}} of {{total_stories}}
  - Documentation drift: {{drift_count}}
  - Scope creep: {{scope_creep_count}}

{{#if sync_issues}}

### ⚠️ Sync Issues Detected

{{#each sync_issues}}

- {{this}}
  {{/each}}
  {{/if}}

### 👥 Team Updates

{{#each team_members}}

#### {{name}}

**Yesterday** {{emoji}}:

- JIRA: {{jira_updates_with_links}}
  Example: Updated [AUTH-123](https://company.atlassian.net/browse/AUTH-123), Closed [AUTH-124](https://company.atlassian.net/browse/AUTH-124)
- Git: {{commit_summary_with_hashes}}
  Example: 3 commits (abc123, def456) on feature/auth-service
  [[LLM: IMPORTANT - Show which commits have JIRA refs: "2 of 3 commits reference JIRA tickets"]]
- BMAD: {{story_updates_with_links}}
  Example: Updated [Login Flow Story](./docs/epics/auth/login-flow.md)
  [[LLM: Show correlation: "Story has ticket AUTH-123, commits found: abc123, def456"]]

**Today**:

- {{planned_work}}

**Blockers**:

- {{blockers}}

{{/each}}

### 📈 Sprint Progress

- Burndown: {{burndown_status}}
- Velocity: {{current_velocity}} vs {{average_velocity}}
- At Risk: {{at_risk_items}}

### 🔗 Dependencies & Handoffs

{{dependencies}}
```

- **Duration**: 1-2 pages with sync analysis
- **Structure**: Sync health first, then by team member
- **Content**: Three-way visibility into all work
- **Special**: Highlight sync discrepancies

[[LLM: EXAMPLE CALCULATION for clarity:

If you find:

- 15 total commits yesterday across all repos
- 12 commits have JIRA ticket references (AUTH-123, etc.)
- 8 BMAD stories in docs/epics/
- 6 stories have JIRA ticket references in metadata
- 5 stories have related git commits

Then calculate:

- Git ↔ JIRA: (12/15) × 100 = 80%
- JIRA ↔ BMAD: (6/8) × 100 = 75%
- Git ↔ BMAD: (5/8) × 100 = 62.5%
- Overall: (80 + 75 + 62.5) / 3 = 72.5%

Display as:

## 📊 Three-Way Sync Health: 73% ⚠️

DO NOT use placeholder values like {{sync_score}} - calculate real numbers!
]]

### File Output

`.bmad-workspace/ck-jira-integration/sync/daily/standup-YYYY-MM-DD-HHMM.md`

[[LLM: Log: standup_completed event with:

- participant_count
- blocker_count
- generation_time
- If <2min, log: quick_standup_success
  ]]

## Weekly Sync Mode

### Activation

- Monday requests
- "Weekly" keyword
- Sprint ceremonies

[[LLM: Log: sync_initiated event with type='weekly']]
[[LLM: Track: whether triggered by schedule vs manual request]]

### Comprehensive Analysis

- Sprint progress (velocity, burndown)
- Team achievements
- Upcoming milestones
- Process improvements
- Risk assessment

### Output Format

- **Duration**: 2-3 pages
- **Structure**: By theme/epic
- **Content**: Progress, risks, decisions
- **Special**: Trend analysis

### File Output

`.bmad-workspace/ck-jira-integration/sync/weekly/weekly-sync-YYYY-MM-DD.md`

## Sprint Sync Mode

### Activation

- Sprint start/end
- "Sprint" keyword
- Ceremony timing

### Sprint Analytics

- Velocity analysis
- Story completion
- Bug trends
- Team capacity
- Retrospective items

## Global Team Mode

### Activation

- "Global" keyword
- Multiple timezones detected
- Large team size

### Regional Sections

**Per Region**:

- Current time display
- Active work summary
- Handoff items
- Regional blockers

### Special Features

- Timezone conversion tables
- Handoff checklists
- Cultural considerations
- Async collaboration health

## Emergency Sync Mode

### Activation

- "Urgent"/"Emergency" keywords
- Critical issue detected
- Incident response

### Focused Content

- Critical issues only
- Immediate actions
- Resource availability
- Decision points
- Next sync timing

### Output Format

- **Duration**: Half page
- **Structure**: Priority order
- **Content**: Actions only
- **Special**: Contact info

## Data Source Intelligence

### Adaptive Selection

[[LLM: Choose data sources based on:

- JIRA + Git: Full picture (preferred)
- Git only: Development focus
- JIRA only: Planning focus
- Add warnings if data limited
  ]]

### Three-Way Health

**Always Include**:

- Git ↔ JIRA alignment
- JIRA ↔ BMAD sync status
- Git ↔ BMAD correlation
- Overall health score

## Quality Features

### Smart Summarization

- Key points first
- Progressive detail
- Clear ownership
- Next steps always

### Multi-Format Output

- Markdown report (default)
- Slack-friendly version
- Email template
- Dashboard metrics

### Timezone Intelligence

- Convert all times to local
- Show global time table
- Highlight overlap windows
- Respect work hours

## Output Management

### Directory Structure

```
.bmad-workspace/ck-jira-integration/sync/
├── daily/       # Standups
├── weekly/      # Weekly syncs
├── sprint/      # Sprint syncs
├── global/      # Global syncs
├── emergency/   # Urgent syncs
└── dashboards/  # Visual sync dashboards
```

### File Naming

[[LLM: Consistent naming:

- Type: daily, weekly, sprint, global, emergency
- Date: YYYY-MM-DD
- Time: HHMM (if multiple per day)
  ]]

### Success Confirmation

Always confirm: "✅ Sync report saved to: {{path}}"

[[LLM: Log successful sync completion - good moment to check reminder conditions]]

## Visual Sync Dashboard

### Activation

- "visual sync"
- "sync dashboard"
- "show sync health"
- "sync visualization"

### Dashboard Generation

[[LLM: Generate interactive HTML dashboard:

1. Use `dashboard-adaptive-tmpl.md` with sync focus
2. Create standalone HTML with inline CSS/JS
3. Show three-way sync health (Git-BMAD-JIRA)
4. Include one-click sync actions
5. Save to `.bmad-workspace/ck-jira-integration/sync/dashboards/`
   ]]

### Visual Elements

- **Health Score**: Large 0-100% indicator
- **System Status**: Green/Yellow/Red cards
- **Connection Diagram**: Visual flow between systems
- **Action Queue**: Prioritized sync recommendations
- **Timeline**: Recent sync events
- **Heatmap**: Divergence by epic/component

### Interactive Features

- Click to drill down
- One-click sync execution
- Auto-refresh every 30 seconds
- Dark mode support
- Mobile responsive

## Advanced Features

### Historical Intelligence

- Compare to previous syncs
- Trend identification
- Pattern recognition
- Improvement tracking

### Predictive Elements

- Sprint completion probability
- Risk materialization likelihood
- Resource bottleneck prediction
- Timeline confidence

### Team Insights

- Collaboration patterns
- Communication health
- Workload balance
- Skill utilization

## Examples

### Minimal

User: "sync"
_Morning time detected → generates daily standup_

### Specific

User: "weekly team sync"
_Generates comprehensive weekly report_

### Contextual

User: "sync our distributed team"
_Activates global mode with timezone sections_

### Urgent

User: "emergency sync - production down"
_Crisis mode with only critical info_

This unified task replaces sync-team-status and sync-daily-standup, providing one intelligent sync command that adapts to any team coordination need.