@groupby/bmad-plugin-atlassian-orchestrator

v2.0.2

Published

a month ago

BMAD plugin for intelligent Jira/Confluence sync - transforms BMAD-generated docs into structured backlog with smart documentation organization

Atlassian Orchestrator 🎯

Version: 2.0.0
Type: BMAD Plugin + Expert Agent
Status: Production Ready
NPM: @groupby/bmad-plugin-atlassian-orchestrator

An autonomous Atlassian orchestrator that bridges BMAD documentation, Jira backlog structure, and Confluence knowledge base with intelligent analysis and organization.

🔌 BMAD Plugin: This repo is structured as an installable BMAD plugin. See PLUGIN-README.md for installation and distribution details.

What Is This?

The Atlassian Orchestrator transforms PM input into:

Structured Jira hierarchy (Initiative → Epic → Story → Subtask)
Intelligent Confluence documentation (organized by information type)
Seamless integration (Jira tickets linked to relevant docs)

All via MCP-only communication with zero scripts or manual API calls.

Installation

As BMAD Plugin (Recommended)

Install into any BMAD project:

# From your BMAD project root
npx @groupby/bmad-plugin-atlassian-orchestrator install

This automatically:

✅ Installs plugin to .bmad/extensions/atlassian-orchestrator/
✅ Includes agent, workflows, and post-workflow hook
✅ Auto-activates after *create-epics-and-stories

See PLUGIN-README.md for complete plugin documentation.

Standalone Agent

Copy the agent folder directly:

cp -r /path/to/plugin/agents/atlassian-orchestrator /path/to/your/project/.bmad/extensions/atlassian-orchestrator/agents/

Key Features

🎯 BMAD Integration

Recognizes BMAD-generated docs (PRD, Architecture, Epics) as primary sources
Agent-generated _docs/ folders enrich BMAD docs with implementation context
All assumptions reference BMAD documentation for traceability

📚 Intelligent Confluence Organization

Hybrid structure: Initiative hierarchy + smart doc grouping
Consolidates similar docs (all decision logs → one Decisions page)
Navigation aids, TOCs, and cross-links throughout
No backlog clutter (Initiative/Epic overview only)

🔗 Jira-Confluence Link Enrichment

Asks where Initiative should live in Confluence (parent page clarification)
Creates Confluence pages BEFORE Jira sync (get page IDs first)
Enriches Jira ticket descriptions with relevant Confluence links
Single Jira sync pass - tickets created complete with all documentation

⚡ Optimized Workflow

Generate Jira structure locally
Analyze documentation landscape (BMAD + agent _docs/)
Organize for Confluence (smart grouping)
Sync to Confluence (get page IDs)
Enrich Jira descriptions with doc links
Final Jira sync (single batch)
Report summary

��️ MCP-Only Communication

All Atlassian operations via MCP tools
No scripts, no direct API calls
Batched operations for efficiency

Quick Start

1. Configure

Edit .bmad/extensions/atlassian-orchestrator/agents/atlassian-orchestrator/config.yaml:

user:
  name: "Your Name"

atlassian:
  instance: "your-instance"
  
jira:
  default_project: "PROJ"
  
behavior:
  mode: "autonomous"
  auto_sync: true

2. Activate Agent

@workspace Use .bmad/extensions/atlassian-orchestrator/agents/atlassian-orchestrator/

Or wait for auto-activation after *create-epics-and-stories

3. Provide Input

Create authentication epic with SSO and 2FA

The agent will:

Load BMAD docs (PRD, Architecture) if they exist
Detect scope & generate Jira structure
Create Confluence documentation
Ask where to place in Confluence
Sync to Confluence → Get page IDs
Enrich Jira tickets → Add doc links
Final Jira sync → All tickets complete!

Structure

.agent/
├── config.yaml                          # Plugin configuration (optional)
└── confluence-general-instructions.md   # Confluence guidelines (optional)

.bmad/
└── extensions/
    └── atlassian-orchestrator/          # Plugin installation
        ├── agents/
        │   └── atlassian-orchestrator/  # Expert agent with sidecar files
        │       ├── atlassian-orchestrator.agent.yaml
        │       ├── config.yaml
        │       ├── doc-type-mapping.yaml
        │       ├── confluence-structure-template.md
        │       ├── confluence-page-templates/
        │       └── README.md
        └── workflows/
            └── 3-solutioning/
                └── create-epics-and-stories/
                    └── post-workflow.yaml    # Auto-activation hook

docs/
├── product-brief-jira-requirements-2025-11-20.md
├── prd.md
├── implementation-guide.md
├── README.md
└── archive/                             # Historical planning docs

jira/
├── _templates/                          # Templates for Jira structure
└── README.md                            # Usage examples

Agent Capabilities

✅ BMAD documentation recognition and integration
✅ Scope detection (Initiative/Epic/Story/Task/Bug/Subtask)
✅ Folder generation with fractal _docs/ at all 5 levels
✅ Autonomous assumption-making with confidence levels
✅ Intelligent Confluence organization and sync
✅ Jira-Confluence link enrichment
✅ MCP Atlassian integration (Jira + Confluence)
✅ Multi-context entry (NEW, IMPORT, CONTINUE modes)
✅ Iteration support (corrections, regeneration, change detection)

Three Entry Modes

NEW Mode

Fresh PM input → Generate complete structure from scratch

IMPORT Mode

Import existing Jira ticket by key → Create local structure

CONTINUE Mode

Add to existing structure → Maintain consistency with parent

Output Structure

Jira Hierarchy

docs/jira/{atlassian_instance}/{project}/
└── {initiative}/
    ├── _initiative.md
    ├── _docs/
    └── {epic}/
        ├── _epic.md
        ├── _docs/
        └── {story}/
            ├── {story}.md
            ├── _docs/
            └── {subtask}/
                ├── {subtask}.md
                └── _docs/

Confluence Documentation

docs/confluence/{atlassian_instance}/{space}/
└── {initiative-name}/
    ├── index.md                          # Initiative Overview
    ├── strategic-context/
    │   └── index.md                      # BMAD PRD + context
    ├── technical-architecture/
    │   └── index.md                      # BMAD Architecture + tech notes
    ├── decisions/
    │   └── index.md                      # All decision logs consolidated
    ├── research-and-findings/
    │   └── index.md                      # UX docs + user research
    └── implementation-guidance/
        └── index.md                      # High-value technical guides

MCP Tools Required

Jira

mcp_atlassian-rov_createJiraIssue
mcp_atlassian-rov_getJiraIssue
mcp_atlassian-rov_editJiraIssue
mcp_atlassian-rov_searchJiraIssuesUsingJql

Confluence

mcp_atlassian-rov_createConfluencePage
mcp_atlassian-rov_getConfluencePage
mcp_atlassian-rov_updateConfluencePage
mcp_atlassian-rov_getConfluenceSpaces
mcp_atlassian-rov_searchConfluenceUsingCql

Documentation

Agent Documentation - Complete agent guide
Product Brief - Product vision
PRD - Requirements specification
Implementation Guide - How-to guide
Confluence Guidelines - Confluence best practices

Version History

v2.0.0 (2025-11-27) - Atlassian Orchestrator with BMAD integration and intelligent Confluence
- Expert agent with sidecar files
- MCP-only communication
- Optimized workflow (Confluence before Jira)
- Smart documentation organization
- Jira-Confluence link enrichment
v1.0.0 (2025-11-20) - Initial release (archived)
- Simple agent, Jira-only functionality

Framework

Built on BMAD Method (.bmad/)
Uses Model Context Protocol (MCP) for Atlassian integration

License

Private - Internal Tool

Status: ✅ Ready for Production
Last Updated: 2025-11-27
Agent Path: .bmad/extensions/atlassian-orchestrator/agents/atlassian-orchestrator/