Skip to content

Orchestrator

The orchestrator (/bmad-atlassian-orchestrate) is BMAtlassian's automated dispatch system. It polls Jira state via JQL, evaluates dispatch rules, and invokes the correct agent -- enabling autonomous project progression without manual intervention.

How It Works

The orchestrator runs a continuous loop:

  1. Poll -- the Jira State Reader queries Jira and Confluence for current project state
  2. Evaluate -- dispatch rules are checked in priority order against the state
  3. Dispatch -- the first matching rule determines which agent and workflow to invoke
  4. Wait -- after the agent completes, the loop returns to step 1
  5. Stop -- when the project is complete or user intervention is needed
┌─────────────────┐
│  State Reader    │──→ Polls Jira/Confluence via MCP
└────────┬────────┘
         │ ProjectState
         ▼
┌─────────────────┐
│  Dispatch Rules  │──→ Evaluates 18 rules in priority order
└────────┬────────┘
         │ Agent + Workflow
         ▼
┌─────────────────┐
│  Agent Execution │──→ Agent runs workflow, updates Jira
└────────┬────────┘
         │ Complete
         ▼
      Loop back

Jira State Reader

The state reader builds a ProjectState object by querying:

Query What It Checks
Confluence label search Planning artefacts (brief, PRD, UX, architecture, readiness)
JQL: issuetype = Epic Epic count and status breakdown
JQL: issuetype = Story Story count, status breakdown, review failures
JQL: labels = "agent-active" Locked issues and stale locks (>1 hour)
JQL: labels in ("bmad-handoff-*") Pending handoff signals between agents
JQL: labels = "bmad-needs-attention" Issues needing user review
Sprint tools or JQL Active sprint status
Git commands (if enabled) Current branch, uncommitted changes, open PRs

The state reader also:

  • Clears stale locks -- if an issue has been locked for >1 hour with no activity, the lock is removed and the issue is flagged for attention
  • Syncs the key map -- rebuilds .jira-key-map.yaml from Jira/Confluence discovery if it's missing or stale

Dispatch Rules

Rules are evaluated in priority order. The first matching rule fires:

Priority Rule Condition Action
0 Handoff Signal bmad-handoff-* label exists Dispatch target agent
1 Attention Required bmad-needs-attention label Ask user
2 Agent Active Issues locked (non-stale) Wait 30s and re-poll
3 Brief Needed No product brief Analyst: Create Brief
4 PRD Needed Brief exists, no PRD PM: Create PRD
5 UX Design Needed PRD exists, no UX UX Designer: Create UX
6 Epics Needed PRD exists, no epics PM: Create Epics/Stories
7 Architecture Needed Epics exist, no architecture Architect: Create Architecture
8 Readiness Check Architecture exists, stories in backlog Architect: Implementation Readiness
9 Sprint Planning No active sprint, stories in backlog SM: Sprint Planning
10 Story Preparation Stories in backlog, none ready SM: Create Story
11 Development Stories ready for dev Dev: Dev Story
12 Re-implementation Review-failed stories exist Dev: Dev Story (address findings)
13 Code Review Stories in review QA: Code Review
14 Parallel Story Prep Backlog stories while dev is busy SM: Create Story
15 Epic Retrospective All epic stories done SM: Retrospective
16 Project Complete All epics done Stop
17 Fallback No rule matched Ask user

Handoff Signals

Handoff labels take absolute priority over state-based rules. When an agent completes its workflow:

  1. The agent posts a structured handoff comment with context (decisions, open questions, artefact references)
  2. The agent applies a bmad-handoff-{target} label (e.g., bmad-handoff-dev)
  3. The orchestrator detects the label in the next poll cycle
  4. The orchestrator reads the handoff comment for context
  5. The target agent is dispatched with the loaded context
  6. The handoff label is removed after dispatch

This ensures explicit agent-to-agent communication rather than relying purely on inferred state.

Context Loading

Before dispatching an agent, the orchestrator loads relevant context:

  • Confluence pages -- PRD, architecture, UX design (via page IDs from the key map)
  • Jira issues -- stories, epics, comments (via JQL queries)
  • Handoff comments -- decisions and open questions from the previous agent
  • Git state -- current branch, open PRs (when git is enabled)

This keeps each agent's context window focused on what it needs for the current task.

Running the Orchestrator

/bmad-atlassian-orchestrate

The orchestrator will:

  1. Poll your Jira project state
  2. Display the current status summary
  3. Recommend the next action
  4. Ask for confirmation before dispatching (or run autonomously)

You can interrupt at any time to override the automated dispatch or switch to manual mode.

Start manually first

Run individual workflows manually (/bmad-help for guidance) until you're comfortable with the flow. Use the orchestrator once your project has established artefacts and you want autonomous progression.

Source Files

  • State Reader: _bmad/atlassian/orchestrator/jira-state-reader.md
  • Dispatch Rules: _bmad/atlassian/orchestrator/agent-dispatch-rules.md