Skip to content

Workflow Guide

BMAtlassian organizes work into a 4-phase workflow, from initial idea to completed implementation. Each phase builds on the previous one, with clear handoffs between agents.

Phase Overview

Phase 0: Setup          → Configure Jira transitions and (optionally) Git
Phase 1: Analysis       → Research, brainstorm, create product brief
Phase 2: Planning       → PRD, UX design, validate requirements
Phase 3: Solutioning    → Architecture, epics/stories, readiness check
Phase 4: Implementation → Sprint, dev, review, test, retrospective

Phase 0 -- Setup

Run once per project to configure BMAtlassian for your Jira environment.

Transition Discovery (required)

/bmad-atlassian-transition-discovery

Discovers your Jira project's transition IDs and board ID. These IDs vary per project -- never copy them from another project. Writes results to module.yaml.

Git Discovery (optional)

/bmad-atlassian-git-discovery

Detects your Git/GitHub environment and configures branch naming, commit format, and PR behavior. See the Git Integration Guide for details.

Phase 1 -- Analysis

The Analyst (Mary) explores the problem space and produces research and product briefs on Confluence.

  1. Brainstorm (/bmad-atlassian-brainstorming) -- generate diverse ideas interactively
  2. Research (optional) -- one or more of:
    • /bmad-atlassian-market-research -- competitive landscape
    • /bmad-atlassian-domain-research -- industry deep dive
    • /bmad-atlassian-technical-research -- feasibility analysis
  3. Create Brief (/bmad-atlassian-create-brief) -- synthesize findings into an executive product brief

Output

All artefacts are written to Confluence pages in your configured space, labelled for discovery by downstream agents.

Skip Conditions

If you already have a clear product vision, you can skip directly to Phase 2 (Create PRD). The Analyst phase is most valuable for new or ambiguous projects.

Phase 2 -- Planning

The PM (John) creates the PRD and the UX Designer (Sally) optionally creates UX design specifications.

  1. Create PRD (/bmad-atlassian-create-prd) -- facilitated PRD creation on Confluence
  2. Validate PRD (/bmad-atlassian-validate-prd) -- quality check with inline comments
  3. Edit PRD (/bmad-atlassian-edit-prd) -- address validation feedback
  4. Create UX Design (/bmad-atlassian-create-ux-design) -- if the project has a significant UI component

Output

  • PRD on Confluence (labelled bmad-prd)
  • UX Design on Confluence (labelled bmad-ux)
  • PRD validation findings as Confluence inline comments

Key Notes

  • The PRD is the anchor document -- all downstream agents reference it
  • UX Design is optional but recommended if a UI is a primary piece of the product
  • PRD validation can be re-run after edits

Phase 3 -- Solutioning

The Architect (Winston) creates the technical design, the PM (John) creates Jira Epics/Stories, and the readiness check validates alignment.

  1. Create Architecture (/bmad-atlassian-create-architecture) -- technical decision document on Confluence
  2. Create Epics and Stories (/bmad-atlassian-create-epics-stories) -- Jira Epics and Stories from the PRD
  3. Implementation Readiness (/bmad-atlassian-implementation-readiness) -- cross-reference PRD, architecture, and stories

Output

  • Architecture Decision Document on Confluence (labelled bmad-architecture)
  • Jira Epics with linked Stories (acceptance criteria in Given/When/Then)
  • Readiness Report on Confluence with inline feedback on PRD/Architecture pages

Key Notes

  • Architecture and Epic URLs are cross-linked in Jira Epic descriptions
  • Stories are linked to parent Epics via the parent field
  • All created keys are stored in .jira-key-map.yaml for downstream lookups

Phase 4 -- Implementation

The SM (Bob) manages sprints and prepares stories. The Dev (Amelia) implements code. The QA (Quinn) reviews and tests.

  1. Sprint Planning (/bmad-atlassian-sprint-planning) -- create sprint, sequence stories
  2. Create Story (/bmad-atlassian-create-story) -- enrich story with dev context and subtasks
  3. Dev Story (/bmad-atlassian-dev-story) -- implement with TDD, track via Jira
  4. Code Review (/bmad-atlassian-code-review) -- adversarial review, post findings to Jira
  5. QA Testing (/bmad-atlassian-qa-testing) -- generate test coverage
  6. Repeat steps 2-5 for each story
  7. Retrospective (/bmad-atlassian-retrospective) -- review completed epic

Story Lifecycle

Backlog → Ready for Dev → In Progress → Review → Done
                              ↑                    │
                              └── (review failed) ──┘
  • SM prepares stories (Backlog → Ready for Dev)
  • Dev implements (Ready for Dev → In Progress → Review)
  • QA reviews (Review → Done, or Review → In Progress for re-work)
  • When all stories in an Epic are Done, the Epic is transitioned to Done

Review Failure Loop

If QA finds issues during code review:

  1. Story transitions back to In Progress with review-failed label
  2. Dev picks up the story, reads review findings from Jira comments
  3. Dev addresses findings and re-submits for review
  4. If git is enabled, the existing branch and PR are reused

Git Integration

When git_enabled is true, Phase 4 also includes:

  • Branch creation aligned with Jira issue keys
  • Commits with issue key prefixes
  • Draft PR creation linking back to Jira
  • PR approval/rejection tied to code review outcomes

See the Git Integration Guide for configuration details.

Anytime Workflows

These workflows can be invoked at any point, independent of the phase sequence:

Command Description
/bmad-atlassian-quick-spec One-off tech spec as a Jira Story
/bmad-atlassian-quick-dev Implement a quick-spec story directly
/bmad-atlassian-correct-course Navigate mid-implementation changes
/bmad-atlassian-generate-project-context Scan codebase for LLM context
/bmad-atlassian-document-project Produce documentation on Confluence
/bmad-atlassian-write-document Multi-turn authoring of technical documentation
/bmad-atlassian-mermaid-generate Create Mermaid diagrams through conversation
/bmad-atlassian-validate-doc Review document quality and standards
/bmad-atlassian-explain-concept Technical explanations with examples
/bmad-atlassian-project-dashboard Project status dashboard on Confluence
/bmad-atlassian-adversarial-review Cynical review of any document
/bmad-atlassian-editorial-prose Review prose clarity and tone
/bmad-atlassian-editorial-structure Review document organization
/bmad-atlassian-edge-case-hunter Find unhandled edge cases
/bmad-atlassian-party-mode Multi-agent discussion
/bmad-atlassian-orchestrate Auto-pilot mode
/bmad-help Context-aware help and next steps