Architecture¶

How BMAtlassian is structured internally.

Directory Structure¶

_bmad/atlassian/
├── agents/                    # Agent persona definitions (9 YAML files)
│   ├── analyst.agent.yaml
│   ├── pm.agent.yaml
│   ├── ux-designer.agent.yaml
│   ├── architect.agent.yaml
│   ├── sm.agent.yaml
│   ├── dev.agent.yaml
│   ├── qa.agent.yaml
│   ├── quick-flow.agent.yaml
│   └── tech-writer.agent.yaml
├── checklists/                # Validation checklists (6 files)
├── data/
│   ├── .jira-key-map.yaml    # Runtime key map (Jira keys ↔ BMAD IDs)
│   └── workflow-manifest.csv  # Phase-sequenced workflow catalog
├── orchestrator/              # Automated dispatch system
│   ├── jira-state-reader.md   # Polls Jira/Confluence state
│   └── agent-dispatch-rules.md # Priority-ordered dispatch rules
├── tasks/                     # Reusable task procedures (13 files)
├── templates/                 # Document templates (8 files)
├── workflow-overrides/        # Phase-organized workflow instructions
│   ├── 0-quick-flow/
│   ├── 1-analysis/
│   ├── 2-plan-workflows/
│   ├── 3-solutioning/
│   └── 4-implementation/
├── artefact-mapping.yaml      # Artefact → MCP tool routing
└── module.yaml                # Project configuration

Key Concepts¶

Key Map¶

The .jira-key-map.yaml file maps BMAD artefact identifiers to Jira issue keys and Confluence page IDs. This is the runtime state file that enables agents to find each other's output without searching:

epics:
  epic-1: PROJ-10
  epic-2: PROJ-11
stories:
  1-1-user-auth: PROJ-12
  1-2-api-endpoints: PROJ-13
confluence_pages:
  prd: "12345"
  architecture: "12346"
pull_requests:
  PROJ-12: { number: 1, url: "..." }

Agent Locking¶

The agent-active label acts as a mutex on Jira issues. Before modifying an issue, agents invoke lock-issue to apply the label. On completion, they remove it. The orchestrator's state reader detects stale locks (>1 hour with no activity) and clears them, flagging the issue for user attention.

Handoff Labels¶

When an agent completes its workflow, it applies a bmad-handoff-{target} label (e.g., bmad-handoff-dev). The orchestrator scans for these labels and dispatches the target agent with context from the handoff comment. This enables explicit agent-to-agent communication.

Review Failure Loop¶

When QA fails a code review:

review-failed label is applied to the Story
Story transitions back to In Progress
Dev reads review findings from Jira comments
Dev fixes issues and re-submits for review
If git is enabled, the same branch and PR are reused

Issue Linking¶

Stories are linked to parent Epics via the parent field. The link-issues task creates directional links (Blocks, Relates To) between issues. The orchestrator checks blocking relationships before dispatching Dev to a story.

Reusable Tasks¶

Tasks are self-contained procedures invoked by agents during workflows. They handle common operations (transitions, locking, writing to Confluence) so that each agent doesn't need to duplicate this logic.

Artefact Mapping¶

The artefact-mapping.yaml file is the authoritative routing table. It maps each BMAD artefact type to its destination (Jira or Confluence), MCP tool, labels, and key map entry. Agents consult this file to determine where to write output.

Differences from BMAD-METHOD¶

BMAtlassian extends the BMAD-METHOD for Atlassian environments:

Aspect	BMAD-METHOD	BMAtlassian
Output	Local markdown files	Jira issues + Confluence pages
Tracking	File-based task lists	Jira status transitions
Communication	Shared files in `_bmad/`	Jira comments + handoff labels
State	File system	JQL queries + Confluence label search
Orchestration	Manual	Automated via Jira state polling
Git	Not integrated	Optional branch/commit/PR alignment
Sprint Management	Not applicable	Jira sprint tools with fallback
Review Cycle	File-based	Jira transitions + PR review

MCP Tool Precedence¶

BMAtlassian supports two MCP configurations:

Standalone mcp-atlassian server -- full feature set including sprint tools
Claude Code Atlassian plugin -- core Jira/Confluence tools (no sprint tools)

Agents detect which tools are available and fall back gracefully. Sprint operations fall back to JQL queries and user guidance when sprint-specific tools aren't available.

For Git/GitHub operations, the fallback chain is:

GitHub MCP plugin (if available)
gh CLI (if installed and authenticated)
Raw git (always available)