Bmad Orchestrator

bmad-orchestrator — BMAD Workflow Orchestration with SSD

When to use this skill

• Initializing BMAD in a new project (with or without SSD)
• Running structured TEA cycles within each BMAD phase
• Checking and resuming BMAD/SSD workflow status
• Routing work across Analysis, Planning, Solutioning, and Implementation
• Managing structured handoff and cross-phase traceability between phases

---

What is SSD (Structured System Design)?

SSD is a meta-framework that embeds TEA cycles within each BMAD phase, transforming phase execution from "produce a document" into a structured loop:

T → Task:     Decompose the phase into concrete tasks with assigned agents
E → Execute:  Run tasks in parallel via multi-agent team execution
A → Architect: Validate outputs for coherence, completeness, and cross-phase traceability

Each BMAD phase becomes an independent TEA cycle. The architect validation step produces a PASS, PASS_WITH_WARNINGS, REVISE, or FAIL verdict. Only after PASS (or PASS_WITH_WARNINGS) does the human review gate (plannotator) open. This ensures automated structural correctness before human review.

SSD vs. Standard BMAD

---

Installation

npx skills add https://github.com/akillness/oh-my-skills --skill bmad-orchestrator

Notes for Codex Usage

bmad-orchestrator's default execution path is Claude Code. To run the same flow directly in Codex, we recommend operating BMAD stages via a higher-level orchestration path such as omx/ohmg.

---

Control Model

BMAD phase routing uses the same three-layer abstraction as JEO:

• settings: platform-specific runtime configuration such as Claude hooks, Codex/Gemini instructions, and MCP setup
• rules: phase constraints such as "do not advance before the current phase document is approved" and "do not reopen the same unchanged phase document for review"
• hooks: platform callbacks such as Claude ExitPlanMode, Codex notify, or Gemini AfterAgent

For BMAD phase gates, the intended rule is strict:

• Review the current phase document before moving forward
• If the document hash has not changed since the last terminal review result, do not relaunch plannotator
• Only a revised document resets the gate and permits another review cycle
• With SSD: plannotator gate requires architect_verdict: "PASS" or "PASS_WITH_WARNINGS" in ssd-state.json before opening

---

Platform Support Status

---

Standard BMAD Commands

/workflow-init [--ssd]
/workflow-status

Typical flow:

1. Run /workflow-init to bootstrap BMAD config (add --ssd to also initialize SSD state). 2. Move through phases: Analysis → Planning → Solutioning → Implementation. 3. Run /workflow-status any time to inspect current phase and progress.

---

SSD Commands (TEA Integration)

Use these commands to run structured TEA cycles within each BMAD phase:

SSD Full Flow

/workflow-init --ssd
       |
       v
  ┌─────────────────────────────────────────────────────┐
  │              PHASE N TEA CYCLE                      │
  │                                                     │
  │  /ssd-decompose  (or /ssd-cycle for full auto)      │
  │       |                                             │
  │       v                                             │
  │  [T] Task decomposition                             │
  │       planner/analyst produces task list            │
  │       → ssd-state.json phases[N].tasks updated      │
  │       |                                             │
  │       v                                             │
  │  /ssd-execute                                       │
  │       |                                             │
  │       v                                             │
  │  [E] Multi-agent execution via /team                │
  │       TeamCreate → TaskCreate per subtask           │
  │       Agents: executor, analyst, designer,          │
  │               test-engineer, security-reviewer…     │
  │       → docs/ssd/phase-N/ artifacts produced        │
  │       → Phase document assembled from artifacts     │
  │       |                                             │
  │       v                                             │
  │  /ssd-validate                                      │
  │       |                                             │
  │       v                                             │
  │  [A] Architect validation                           │
  │       fabric -p bmad_ssd_phase_review               │
  │       (fallback: architect agent via TaskCreate)    │
  │       |                                             │
  │       ├── PASS ──────────→ plannotator review       │
  │       │                         |                   │
  │       │                    ┌────┴────┐              │
  │       │                    │ Approve │ Req Changes  │
  │       │                    └────┬────┘     |        │
  │       │                         |     Loop to [E]   │
  │       │                         v     with feedback │
  │       │                    /ssd-advance              │
  │       │                    → phase N+1               │
  │       │                                             │
  │       ├── PASS_WITH_WARNINGS → plannotator (warned) │
  │       │                                             │
  │       ├── REVISE → targeted re-execute specific     │
  │       │             tasks, then re-validate         │
  │       │                                             │
  │       └── FAIL → full re-execute with changes,      │
  │                   then re-validate                  │
  │                   (max 3 cycles, then escalate)     │
  └─────────────────────────────────────────────────────┘

---

TEA Per-Phase Mapping

Phase 1: Analysis

Phase 2: Planning

Phase 3: Solutioning

Phase 4: Implementation

---

Fabric Pattern: bmad_ssd_phase_review

Install this custom pattern for automated architect validation:

mkdir -p ~/.config/fabric/patterns/bmad_ssd_phase_review
cat > ~/.config/fabric/patterns/bmad_ssd_phase_review/system.md << 'EOF'
# IDENTITY AND PURPOSE

You are an expert system architect performing a structured phase review for the BMAD Structured System Design (SSD) framework. Your job is to validate that a phase document is internally coherent, externally consistent with prior phase artifacts, and complete enough to advance to the next phase.

Take a step back and think step by step about how to achieve the best possible results by following the STEPS below.

# STEPS

1. IDENTIFY the current BMAD phase (Analysis, Planning, Solutioning, Implementation) from the input metadata.

2. PARSE the phase document and extract all claims, requirements, design decisions, and deliverables.

3. INTERNAL COHERENCE CHECK:
   - Are there contradictory statements within the document?
   - Are all sections complete (no TODOs, placeholders, or TBDs)?
   - Do quantitative claims have justification?

4. CROSS-PHASE TRACEABILITY CHECK (if prior phase artifacts are provided):
   - Phase 2 (Planning): Does every PRD requirement trace to a product brief goal?
   - Phase 3 (Solutioning): Does the architecture address every PRD functional requirement?
   - Phase 4 (Implementation): Does every story map to an architecture component?
   - Flag any orphaned items.

5. COMPLETENESS CHECK against BMAD level expectations:
   - Level 0-1: Minimal viable coverage
   - Level 2: Full requirement coverage with acceptance criteria
   - Level 3: Comprehensive with integration points and risk analysis
   - Level 4: Enterprise-grade with security, performance, and infrastructure coverage

6. RISK ASSESSMENT:
   - Identify assumptions that could invalidate the phase output
   - Flag unresolved dependencies
   - Note scope creep relative to prior phase boundaries

7. PRODUCE a structured verdict.

# OUTPUT INSTRUCTIONS

- Output valid Markdown only.
- Begin with a `## Verdict` section: one of `PASS`, `PASS_WITH_WARNINGS`, `FAIL`, or `REVISE`.
- Follow with `## Internal Coherence` (findings with line references).
- Follow with `## Cross-Phase Traceability` (coverage matrix if applicable).
- Follow with `## Completeness` (missing sections or underspecified areas).
- Follow with `## Risks` (ranked by severity: critical, high, medium, low).
- Follow with `## Required Changes` (concrete, actionable items if verdict is FAIL or REVISE).
- Do not include warnings, disclaimers, or caveats outside the structured sections.

# INPUT

INPUT:
EOF

Usage in /ssd-validate:

# Pipe current phase doc + prior artifacts for cross-phase validation
{
  echo "--- CURRENT PHASE DOCUMENT ---"
  cat "$CURRENT_DOC"
  echo "--- PRIOR PHASE ARTIFACTS ---"
  for prior in "${PRIOR_DOCS[@]}"; do
    echo "--- $(basename "$prior") ---"
    cat "$prior"
  done
} | fabric -p bmad_ssd_phase_review --stream > docs/ssd/phase-N/architect-review.md

# Phase 3 example: validate architecture against PRD
cat docs/architecture-myapp-2026-03-16.md | \
  fabric -p bmad_ssd_phase_review \
  --context "$(cat docs/prd-myapp-2026-03-16.md)" \
  --stream

If fabric is not installed, /ssd-validate falls back to an architect agent:

# In Claude Code session:
ssd validate — run architect review on the current phase document before advancing

---

SSD State File Schema

Location: .omc/state/ssd-state.json

{
  "version": "1.0.0",
  "project_name": "myapp",
  "project_level": 2,
  "active": true,
  "current_phase": 2,
  "created_at": "2026-03-16T10:00:00Z",
  "updated_at": "2026-03-16T14:30:00Z",
  "phases": {
    "1": {
      "name": "analysis",
      "tea_step": "complete",
      "tasks": {
        "decomposed_at": "2026-03-16T10:05:00Z",
        "items": [
          {
            "id": "p1-t1",
            "name": "Market research",
            "agent": "document-specialist",
            "model": "sonnet",
            "status": "completed",
            "output_path": "docs/ssd/phase-1/market-research.md"
          }
        ]
      },
      "architect_review": {
        "verdict": "PASS",
        "method": "fabric",
        "pattern": "bmad_ssd_phase_review",
        "report_path": "docs/ssd/phase-1/architect-review.md",
        "reviewed_at": "2026-03-16T11:00:00Z"
      },
      "plannotator_review": {
        "status": "approved",
        "reviewed_at": "2026-03-16T11:30:00Z",
        "document_hash": "abc123"
      }
    },
    "2": {
      "name": "planning",
      "tea_step": "execute",
      "tasks": {
        "items": [
          {
            "id": "p2-t1",
            "name": "Functional requirements extraction",
            "agent": "analyst",
            "model": "opus",
            "status": "in_progress"
          }
        ]
      },
      "architect_review": null,
      "plannotator_review": null
    }
  },
  "cross_phase_traceability": {
    "phase_1_to_2": { "validated": true, "coverage": 1.0, "orphaned_items": [] },
    "phase_2_to_3": { "validated": false },
    "phase_3_to_4": { "validated": false }
  }
}

`tea_step` values: null → decompose → execute → validate → complete

---

plannotator Integration (Phase Review Gate)

Each BMAD phase produces a key document (PRD, Tech Spec, Architecture). Before transitioning to the next phase, review that document with plannotator.

With SSD enabled, plannotator only opens after /ssd-validate produces architect_verdict: "PASS" or "PASS_WITH_WARNINGS". This ensures automated structural correctness before human review.

Phase Review Pattern

# After /prd → docs/prd-myapp-2026-03-16.md is created
# With SSD: run /ssd-validate first, then phase-gate-review.sh
bash scripts/phase-gate-review.sh docs/prd-myapp-2026-03-16.md "PRD Review: myapp"

# After /architecture → docs/architecture-myapp-2026-03-16.md is created
bash scripts/phase-gate-review.sh docs/architecture-myapp-2026-03-16.md "Architecture Review: myapp"

Or submit the plan directly from your AI session:

# In Claude Code after /prd completes:
planno — review the PRD before we proceed to Phase 3

Phase Gate Flow (with SSD)

/prd completes → docs/prd-myapp.md created
       ↓
 /ssd-validate runs (automated architect review)
       ↓ fabric -p bmad_ssd_phase_review
       ↓
  PASS/PASS_WITH_WARNINGS?
       ↓ yes
 phase-gate-review.sh opens plannotator UI
       ↓
  [Approve]              [Request Changes]
       ↓                        ↓
 Obsidian saved          Agent revises doc
 ssd-state updated       /ssd-execute (targeted)
                         then /ssd-validate again
       ↓
 /ssd-advance → Phase 3

Quick Reference

---

Integration with /team (OMC)

/ssd-execute maps directly to OMC's Team staged pipeline. When you run /ssd-execute:

1. Reads ssd-state.json for the current phase's task list 2. Calls TeamCreate with team name ssd-phase-{N}-{project} 3. Creates tasks via TaskCreate with agent routing from the TEA per-phase table 4. Monitors via TaskList until all tasks reach terminal state 5. Writes outputs to docs/ssd/phase-{N}/ 6. Updates ssd-state.json with execution results

# Trigger SSD execution for current phase (Claude Code)
ssd execute — run phase 2 planning tasks with multi-agent team

Or use directly with Team:

/team 4:analyst "Execute BMAD Phase 2 planning: functional requirements, non-functional requirements, user stories, acceptance criteria based on product brief at docs/product-brief-myapp.md"

---

Quick Start with SSD

# 1. Initialize BMAD with SSD enabled
/workflow-init --ssd

# 2. Run full TEA cycle for Phase 1 (Analysis)
/ssd-cycle

# 3. Check status after cycle
/ssd-status

# 4. When architect validates PASS, human review opens automatically
# (plannotator UI launches)

# 5. After approval, advance to Phase 2
/ssd-advance

# 6. Repeat for each phase
/ssd-cycle  # Phase 2: Planning
/ssd-cycle  # Phase 3: Solutioning
/ssd-cycle  # Phase 4: Implementation

---

Obsidian Save Format

Approved phase documents are saved to your Obsidian vault:

---
created: 2026-03-16T10:00:00Z
source: plannotator
tags: [bmad, ssd, phase-2, prd, myapp]
ssd_architect_verdict: PASS
ssd_tea_cycle: 1
---

[[BMAD Plans]]

# PRD: myapp
...

---

TOON Format Hook

If ~/.claude/hooks/toon-inject.mjs is installed, the skill catalog is automatically injected into every prompt. See [bmad-orchestrator SKILL.md — TOON Format Integration] for details.

IDENTITY AND PURPOSE

You are an expert system architect performing a structured phase review for the BMAD Structured System Design (SSD) framework. Your job is to validate that a phase document is internally coherent, externally consistent with prior phase artifacts, and complete enough to advance to the next phase.

Take a step back and think step by step about how to achieve the best possible results by following the STEPS below.

STEPS

1. IDENTIFY the current BMAD phase (Analysis, Planning, Solutioning, Implementation) from the input metadata.

2. PARSE the phase document and extract all claims, requirements, design decisions, and deliverables.

3. INTERNAL COHERENCE CHECK:

• Are there contradictory statements within the document?
• Are all sections complete (no TODOs, placeholders, or TBDs)?
• Do quantitative claims (performance targets, story points, timelines) have justification?

4. CROSS-PHASE TRACEABILITY CHECK (if prior phase artifacts are provided):

• Phase 2 (Planning): Does every PRD requirement trace to a product brief goal?
• Phase 3 (Solutioning): Does the architecture address every PRD functional requirement?
• Phase 4 (Implementation): Does every story map to an architecture component?
• Flag any orphaned items (requirements without upstream justification or downstream coverage).

5. COMPLETENESS CHECK against the BMAD level expectations:

• Level 0-1: Minimal viable coverage
• Level 2: Full requirement coverage with acceptance criteria
• Level 3: Comprehensive with integration points and risk analysis
• Level 4: Enterprise-grade with security, performance, and infrastructure coverage

6. RISK ASSESSMENT:

• Identify assumptions that could invalidate the phase output
• Flag dependencies that are unresolved
• Note any scope creep relative to prior phase boundaries

7. PRODUCE a structured verdict.

OUTPUT INSTRUCTIONS

• Output valid Markdown only.
• Begin with a ## Verdict section: one of PASS, PASS_WITH_WARNINGS, FAIL, or REVISE.
• Follow with ## Internal Coherence (findings with line references).
• Follow with ## Cross-Phase Traceability (coverage matrix if applicable).
• Follow with ## Completeness (missing sections or underspecified areas).
• Follow with ## Risks (ranked by severity: critical, high, medium, low).
• Follow with ## Required Changes (concrete, actionable items if verdict is FAIL or REVISE).
• Do not include warnings, disclaimers, or caveats outside the structured sections.

INPUT

INPUT:

BMAD Orchestrator Reference

This document provides detailed reference information for the BMAD Orchestrator skill.

Table of Contents

• Workflow Routing Logic
• Project Level Guidelines
• Status File Structure
• Configuration Details
• File Operations
• Variable Substitution

Workflow Routing Logic

Determination Algorithm

Input: workflow_status array from docs/bmm-workflow-status.yaml
Output: recommended next workflow command

Step 1: Identify current phase
  - Scan workflow_status array
  - Find last completed workflow (status = file path)
  - Determine phase number of last completion

Step 2: Check for required workflows in current/next phase
  - If in Phase 1 (Analysis):
    * If no product-brief: Recommend /product-brief
    * If product-brief complete: Move to Phase 2

  - If in Phase 2 (Planning):
    * Level 0-1:
      - If no tech-spec: Recommend /tech-spec (required)
      - If PRD desired: Suggest /prd (optional)
    * Level 2+:
      - If no PRD: Recommend /prd (required)
      - If tech-spec desired: Suggest /tech-spec (optional)

  - If in Phase 3 (Solutioning):
    * Level 2+:
      - If no architecture: Recommend /architecture (required)
    * Level 0-1:
      - Skip to Phase 4

  - If in Phase 4 (Implementation):
    * If no sprint-status.yaml: Recommend /sprint-planning
    * If sprint active: Recommend /create-story
    * If stories exist: Recommend /dev-story

Step 3: Return recommendation with explanation

Phase Transition Rules

Phase 1 → Phase 2:

• Transition when: Product brief complete OR user explicitly skips analysis
• Required before transition: None (Analysis is optional)

Phase 2 → Phase 3:

• Transition when: PRD or Tech Spec complete
• Required before transition:
• Level 0-1: Tech Spec complete
• Level 2+: PRD complete
• Gate rule: if the current phase document already has a terminal plannotator result for the same document hash, do not relaunch review until the document changes

Phase 3 → Phase 4:

• Transition when: Architecture complete (if required)
• Required before transition:
• Level 0-1: None (skip Phase 3)
• Level 2+: Architecture complete
• Gate rule: phase advancement still requires a reviewed artifact; unchanged reviewed architecture should not be re-opened

Phase 4 completion:

• All stories in sprint-status.yaml marked as "done"
• Final review/retrospective complete

Project Level Guidelines

Level 0: Single Atomic Change (1 story)

Characteristics:

• Bug fix
• Small configuration change
• Single file modification
• No breaking changes

Required workflows:

• Tech Spec (brief, 1-2 pages)
• Single story
• Direct implementation

Skip:

• Product brief (unless complex bug)
• PRD
• Architecture
• Sprint planning

Typical timeline: Hours to 1 day

Level 1: Small Feature (1-10 stories)

Characteristics:

• New small feature
• Limited scope
• 1-3 files affected
• Minimal dependencies

Required workflows:

• Tech Spec
• Sprint planning (simple)

Optional but recommended:

• Product brief (if feature requires context)
• PRD (if stakeholder alignment needed)

Skip:

• Architecture (unless significant design needed)

Typical timeline: 1-5 days

Level 2: Medium Feature Set (5-15 stories)

Characteristics:

• Multiple related features
• 5-20 files affected
• Some dependencies
• Database changes likely

Required workflows:

• PRD
• Architecture
• Sprint planning

Optional:

• Product brief (recommended)
• Tech spec (for complex components)

Typical timeline: 1-3 weeks

Level 3: Complex Integration (12-40 stories)

Characteristics:

• System integration
• Multiple subsystems
• 20-50 files affected
• API contracts
• Third-party integrations

Required workflows:

• Product brief (strongly recommended)
• PRD (detailed)
• Architecture (comprehensive)
• Sprint planning (multiple sprints)

Typical timeline: 3-8 weeks

Level 4: Enterprise Expansion (40+ stories)

Characteristics:

• Major system overhaul
• 50+ files affected
• Multiple teams
• Platform changes
• Infrastructure updates

Required workflows:

• Product brief (required)
• PRD (extensive)
• Architecture (system-wide)
• Sprint planning (multiple sprints)
• Gate checks

Typical timeline: 2-6 months

Status File Structure

Workflow Status Schema

# docs/bmm-workflow-status.yaml

project_name: "string"
project_type: "web-app|mobile-app|api|game|library|other"
project_level: 0-4
communication_language: "string"
output_language: "string"
last_updated: "ISO-8601 timestamp"

workflow_status:
  - name: "workflow-name"
    phase: 1-4
    status: "optional|recommended|required|{file-path}|skipped"
    description: "Brief description"
    # Added by phase-gate-review.sh when plannotator approves the document:
    plannotator_review: "approved"       # set on plannotator Approve click
    reviewed_at: "ISO-8601 timestamp"   # timestamp of approval

Status Values

• "optional" - Workflow can be skipped without impact
• "recommended" - Strongly suggested but not blocking
• "required" - Must be completed to proceed
• "conditional" - Required based on project level (replaced during init)
• "{file-path}" - Completed, shows output file location
• "skipped" - User explicitly chose to skip

plannotator Review Fields

Written by scripts/phase-gate-review.sh when a phase document is approved via plannotator:

• `plannotator_review` - "approved" when the document passed plannotator gate review
• `reviewed_at` - ISO-8601 timestamp of when the review was approved

These fields are optional — they are only present on workflow entries that have been reviewed. Use them to audit which phase documents were human-reviewed before phase transition. If you persist a document hash alongside them, the recommended policy is "same hash, same decision, no re-entry".

Updating Status

When a workflow completes: 1. Read docs/bmm-workflow-status.yaml 2. Find workflow by name 3. Update status to file path: "docs/prd-myapp-2025-01-11.md" 4. Update last_updated timestamp 5. Write updated file

Example Edit operation:

# Before
- name: prd
  phase: 2
  status: "required"
  description: "Product Requirements Document"

# After
- name: prd
  phase: 2
  status: "docs/prd-myapp-2025-01-11.md"
  description: "Product Requirements Document"

Configuration Details

Project Config (bmad/config.yaml)

Complete schema:

# Project identification
project_name: "string"
project_type: "web-app|mobile-app|api|game|library|other"
project_level: 0-4

# Output settings
output_folder: "docs"  # relative to project root
stories_folder: "docs/stories"

# Language settings
communication_language: "English|Spanish|French|etc"
document_output_language: "English|Spanish|French|etc"

# BMAD version
bmad_version: "6.0.0"

# Optional: Custom overrides
agent_overrides_folder: "bmad/agent-overrides"

Global Config (~/.claude/config/bmad/config.yaml)

version: "6.0.0"
ide: "claude-code"

# User defaults
user_name: "string"
user_skill_level: "beginner|intermediate|expert"

# Communication defaults
communication_language: "English"
document_output_language: "English"

# Default paths
default_output_folder: "docs"

# Enabled modules
modules_enabled:
  - core
  - bmm
  # - bmb (optional)
  # - cis (optional)

# Advanced settings
auto_update_status: true
verbose_mode: false

Config Priority

1. Project config (bmad/config.yaml) - highest priority 2. Global config (~/.claude/config/bmad/config.yaml) - default values 3. Built-in defaults - fallback

File Operations

Reading Config Files

Load project config:

Tool: Read
Path: {project-root}/bmad/config.yaml
Parse: YAML
Extract: project_name, project_type, project_level, output_folder

Load global config:

Tool: Read
Path: ~/.claude/config/bmad/config.yaml
Parse: YAML
Extract: user_name, communication_language, default_output_folder

Merge configs:

Result = Global config + Project config (project overrides global)

Writing Status Files

Create workflow status:

Tool: Write
Path: {project-root}/{output_folder}/bmm-workflow-status.yaml
Content: Processed template with variables substituted

Update workflow status:

Tool: Edit
Path: {project-root}/{output_folder}/bmm-workflow-status.yaml
Old: status: "required"
New: status: "docs/prd-myapp-2025-01-11.md"

Directory Creation

Initialize project structure:

Tool: Bash
Commands:
  mkdir -p bmad/agent-overrides
  mkdir -p docs/stories
  mkdir -p .claude/commands/bmad

Variable Substitution

Standard Variables

Used in templates during initialization:

{{PROJECT_NAME}}           → config: project_name
{{PROJECT_TYPE}}           → config: project_type
{{PROJECT_LEVEL}}          → config: project_level
{{USER_NAME}}              → global config: user_name
{{DATE}}                   → current date (YYYY-MM-DD)
{{TIMESTAMP}}              → current timestamp (ISO 8601)
{{OUTPUT_FOLDER}}          → config: output_folder

Conditional Variables

Based on project level:

{{PRD_STATUS}}             → "required" if level >= 2
                           → "recommended" if level == 1
                           → "optional" if level == 0

{{TECH_SPEC_STATUS}}       → "required" if level <= 1
                           → "optional" if level >= 2

{{ARCHITECTURE_STATUS}}    → "required" if level >= 2
                           → "optional" if level <= 1

Substitution Process

1. Load template file 2. Collect variable values from:

• Project config
• Global config
• Current date/time
• User input

3. Replace all {{VARIABLE}} occurrences 4. Validate no unreplaced variables remain 5. Return processed content

Example:

# Template
project_name: "{{PROJECT_NAME}}"
project_level: {{PROJECT_LEVEL}}

# After substitution with project_name="MyApp", project_level=2
project_name: "MyApp"
project_level: 2

File Path Standards

Standard Paths

Project root: {project-root}/
Config: {project-root}/bmad/config.yaml
Status: {project-root}/{output_folder}/bmm-workflow-status.yaml
Sprint: {project-root}/{output_folder}/sprint-status.yaml
Stories: {project-root}/{output_folder}/stories/
Templates: {project-root}/bmad/agent-overrides/ (optional)

Output File Naming

Convention: {workflow-name}-{project-name}-{date}.md

Examples:

docs/product-brief-myapp-2025-01-11.md
docs/prd-myapp-2025-01-11.md
docs/architecture-myapp-2025-01-11.md
docs/tech-spec-myapp-2025-01-11.md

Story File Naming

Convention: story-{epic-id}-{story-id}.md

Examples:

docs/stories/story-E001-S001.md
docs/stories/story-E001-S002.md
docs/stories/story-E002-S001.md

Error Handling Patterns

Missing Config File

Error: bmad/config.yaml not found

Response:
  1. Inform user project not initialized
  2. Display: "BMAD not detected in this project."
  3. Ask: "Would you like to initialize BMAD with /workflow-init?"
  4. Do NOT proceed with operation

Invalid YAML

Error: YAML parsing failed

Response:
  1. Show error message
  2. Display file path
  3. Show line number if available
  4. Options:
     a. "I can try to fix the YAML syntax"
     b. "You can manually edit the file"
     c. "I can reinitialize with /workflow-init (will overwrite)"

Inconsistent Status

Error: Status file doesn't match project level

Example: Level 2 project but PRD marked as "optional"

Response:
  1. Explain inconsistency
  2. Show expected vs actual
  3. Offer: "I can regenerate the status file to match your project level"

Missing Template

Error: Template file not found

Response:
  1. Log warning (if verbose mode)
  2. Use inline fallback template
  3. Continue operation
  4. Note: "Using default template"

Display Formatting

Status Display Format

Project: {project_name} ({project_type}, Level {level})

✓ Phase 1: Analysis
  ✓ product-brief (docs/product-brief-myapp-2025-01-11.md)
  - research (optional)

→ Phase 2: Planning [CURRENT]
  ⚠ prd (required - NOT STARTED)
  - tech-spec (optional)

Phase 3: Solutioning
  - architecture (required)

Phase 4: Implementation
  - sprint-planning (required)

Symbols Used

• ✓ - Completed
• ⚠ - Required but not started
• → - Current phase indicator
• - - Optional or not applicable

Color Coding (if supported)

• Green: Completed workflows
• Yellow: Required but incomplete
• Gray: Optional workflows
• Blue: Current phase

Best Practices

For Initialization

1. Always collect project info before creating files 2. Validate project level is 0-4 3. Create all directories before files 4. Use absolute paths for file operations 5. Confirm successful creation to user

For Status Checks

1. Load config first to get output_folder path 2. Check if status file exists before reading 3. Parse YAML carefully with error handling 4. Display in clear, hierarchical format 5. Always provide actionable next step

For Routing

1. Check current phase before recommending 2. Consider project level in recommendations 3. Explain why a workflow is recommended 4. Offer to execute recommended workflow 5. Allow user to choose different path

For Updates

1. Read current file before editing 2. Update timestamp when modifying 3. Validate YAML after changes 4. Confirm update to user 5. Update related files if needed (e.g., sprint-status)

---

SSD (Structured System Design) Reference

SSD embeds TEA (Task-Execute-Architect) cycles within each BMAD phase. This section documents the state schema, TEA transitions, and command reference.

SSD State File

Location: .omc/state/ssd-state.json

{
  "version": "1.0.0",
  "project_name": "string",
  "project_level": 0,
  "active": true,
  "current_phase": 1,
  "created_at": "ISO-8601",
  "updated_at": "ISO-8601",
  "phases": {
    "1": {
      "name": "analysis | planning | solutioning | implementation",
      "tea_step": "null | decompose | execute | validate | complete",
      "tasks": {
        "decomposed_at": "ISO-8601 | null",
        "items": [
          {
            "id": "p{N}-t{N}",
            "name": "string",
            "agent": "string",
            "model": "haiku | sonnet | opus",
            "status": "pending | in_progress | completed | failed",
            "output_path": "string | null"
          }
        ]
      },
      "architect_review": {
        "verdict": "PASS | PASS_WITH_WARNINGS | REVISE | FAIL",
        "method": "fabric | agent",
        "pattern": "bmad_ssd_phase_review",
        "report_path": "string",
        "reviewed_at": "ISO-8601"
      },
      "plannotator_review": {
        "status": "approved | changes_requested | pending",
        "reviewed_at": "ISO-8601 | null",
        "document_hash": "string"
      }
    }
  },
  "cross_phase_traceability": {
    "phase_1_to_2": { "validated": false, "coverage": 0.0, "orphaned_items": [] },
    "phase_2_to_3": { "validated": false },
    "phase_3_to_4": { "validated": false }
  }
}

TEA Step Values and Transitions

tea_step progresses through the following states for each phase:

Architect verdict values:

/ssd-* Command Reference

Agent Routing per Phase (TEA Execute Step)

Architect validation agents:

• Phases 1–2: architect (opus)
• Phase 3: architect (opus) + critic (opus)
• Phase 4: verifier (sonnet) + code-reviewer (opus)

Cross-Phase Traceability

The cross_phase_traceability object tracks coverage between adjacent phases:

phase_1_to_2: product brief goals → PRD requirements
phase_2_to_3: PRD requirements → architecture components
phase_3_to_4: architecture components → implementation stories

coverage is a float 0.0–1.0 representing the fraction of upstream items with a downstream mapping. orphaned_items lists upstream item IDs with no downstream reference. Populated and validated during /ssd-validate for phases 2, 3, and 4.

Fabric Pattern: bmad_ssd_phase_review

The pattern file is bundled at:

.agent-skills/bmad-orchestrator/patterns/bmad_ssd_phase_review/system.md

To install globally for use with fabric:

mkdir -p ~/.config/fabric/patterns/bmad_ssd_phase_review
cp .agent-skills/bmad-orchestrator/patterns/bmad_ssd_phase_review/system.md \
   ~/.config/fabric/patterns/bmad_ssd_phase_review/system.md

If fabric CLI is not available, /ssd-validate falls back to spawning an architect agent via TaskCreate with the phase document as context.

BMAD Workflow Phases Reference

Complete reference for all 4 BMAD phases, workflows, and project levels.

Phase 1: Analysis (Optional)

Purpose: Understand the problem space, research market/competitors, and define product vision.

When to use: Starting new products, major features, or when requirements are unclear.

When to skip: Bug fixes, well-defined features, or urgent implementations.

Phase 1 Workflows

Product Brief (/product-brief)

Purpose: Create comprehensive product vision and high-level requirements.

Output: Product brief document with:

• Problem statement
• Target users
• Value proposition
• Key features
• Success metrics
• Constraints

Duration: 1-2 hours

Recommended for: Level 1+ projects

Required for: Level 3+ projects

Brainstorm (/brainstorm)

Purpose: Structured ideation session for features and solutions.

Output: Brainstorming session notes with:

• Problem exploration
• Solution ideas
• Feature concepts
• Technical approaches

Duration: 30-60 minutes

Optional for: All levels

Research (/research)

Purpose: Market analysis, competitive research, technical investigation.

Output: Research report with:

• Market analysis
• Competitor comparison
• Technical feasibility
• Recommendations

Duration: 2-4 hours

Optional for: All levels (recommended for Level 2+)

---

Phase 2: Planning (Required)

Purpose: Define detailed requirements and technical specifications.

Critical: Every project must complete at least ONE planning workflow (PRD or Tech Spec).

Phase 2 Workflows

PRD - Product Requirements Document (/prd)

Purpose: Comprehensive product requirements for multi-feature projects.

Output: PRD document with:

• Executive summary
• User stories
• Functional requirements
• Non-functional requirements
• Success criteria
• Acceptance criteria

Duration: 2-4 hours

Required for: Level 2+ projects

Recommended for: Level 1 projects

Optional for: Level 0 projects

When to choose PRD over Tech Spec:

• Multiple features
• Stakeholder alignment needed
• Product perspective important
• Business requirements complex

Tech Spec - Technical Specification (/tech-spec)

Purpose: Technical design for single features or components.

Output: Tech spec document with:

• Technical overview
• Implementation approach
• API contracts
• Data models
• Testing strategy

Duration: 1-2 hours

Required for: Level 0-1 projects

Optional for: Level 2+ projects (supplement to PRD)

When to choose Tech Spec over PRD:

• Single feature
• Technical focus
• Limited scope
• Developer-centric work

UX Design (/create-ux-design)

Purpose: Design user interface and user experience.

Output: UX design document with:

• User flows
• Wireframes
• UI mockups
• Interaction patterns
• Design system references

Duration: 2-6 hours

Optional for: Projects with UI components

Recommended for: User-facing features

---

Phase 3: Solutioning (Conditional)

Purpose: Design system architecture for medium+ complexity projects.

Required for: Level 2+ projects

Skip for: Level 0-1 projects (unless significant architectural changes)

Phase 3 Workflows

Architecture (/architecture)

Purpose: Design system architecture, components, and integrations.

Output: Architecture document with:

• System overview
• Component design
• Data flow
• API contracts
• Integration points
• Technology decisions
• Security considerations
• Performance requirements

Duration: 2-6 hours

Required for: Level 2+ projects

Optional for: Level 0-1 with architectural impact

Content varies by level:

• Level 2: Component architecture, basic integrations
• Level 3: Comprehensive system design, multiple integrations
• Level 4: Enterprise architecture, platform design, infrastructure

Solutioning Gate Check (/solutioning-gate-check)

Purpose: Validate architecture against requirements before implementation.

Output: Gate check report with:

• Requirements coverage
• Risk assessment
• Technical debt analysis
• Readiness score

Duration: 30-60 minutes

Optional for: Level 2+ projects

Recommended for: Level 3+ projects

---

Phase 4: Implementation (Required)

Purpose: Execute development through sprints and stories.

Required for: All projects (even Level 0 creates at least 1 story)

Phase 4 Workflows

Sprint Planning (/sprint-planning)

Purpose: Break down requirements into epics and stories, plan sprints.

Output:

• Sprint plan with epics and stories
• sprint-status.yaml tracking file
• Story files in docs/stories/

Duration: 1-3 hours

Required for: Level 1+ projects

Simplified for: Level 0 (single story, no sprint)

Generates:

• Epics (Level 1+)
• User stories with acceptance criteria
• Story point estimates
• Sprint assignments

Create Story (/create-story)

Purpose: Create individual user story with details.

Output: Story file (docs/stories/story-{epic}-{id}.md) with:

• User story format
• Acceptance criteria
• Tasks breakdown
• Estimates
• Dependencies

Duration: 15-30 minutes per story

Required for: All projects

Used when: Adding stories to existing sprint

Dev Story (/dev-story)

Purpose: Implement a specific story with code generation.

Output:

• Code implementation
• Tests
• Documentation
• Story marked complete

Duration: 30 minutes - several hours

Required for: Story implementation

Process: 1. Read story file 2. Implement code 3. Write tests 4. Update documentation 5. Mark story complete

Code Review (/code-review)

Purpose: Review implemented code for quality and standards.

Output: Review findings and recommendations

Duration: 30-60 minutes

Optional for: All implementations

Recommended for: Level 2+ projects

---

Project Level Decision Matrix

Level 0: Single Atomic Change (1 story)

Typical flow: Tech Spec → Single Story → Implementation

Example projects:

• Bug fix
• Configuration change
• Small UI tweak
• Single function addition

---

Level 1: Small Feature (1-10 stories)

Typical flow: Product Brief → Tech Spec → Sprint Planning → Stories → Implementation

Example projects:

• New API endpoint
• User profile page
• Data export feature
• Email notifications

---

Level 2: Medium Feature Set (5-15 stories)

Typical flow: Product Brief → PRD → Architecture → Sprint Planning → Stories → Implementation

Example projects:

• User authentication system
• Payment integration
• Dashboard with multiple widgets
• Content management features

---

Level 3: Complex Integration (12-40 stories)

Typical flow: Product Brief → Research → PRD → Architecture → Gate Check → Multiple Sprints → Implementation

Example projects:

• Third-party API integration
• Multi-tenant system
• Real-time collaboration features
• Analytics platform

---

Level 4: Enterprise Expansion (40+ stories)

Typical flow: Product Brief → Research → PRD → UX Design → Architecture → Gate Check → Many Sprints → Implementation → Reviews

Example projects:

• Platform migration
• Microservices architecture
• Enterprise SaaS product
• Major system overhaul

---

Phase Transition Criteria

Phase 1 → Phase 2

Can transition when:

• Product brief completed (if created), OR
• User explicitly skips Phase 1

Blocking issues:

• None (Phase 1 is optional)

Recommendation: Complete product brief for Level 2+ projects

---

Phase 2 → Phase 3

Can transition when:

• PRD completed (Level 2+), OR
• Tech Spec completed (Level 0-1)

Blocking issues:

• No planning document created
• Planning document incomplete or invalid

Recommendation: Complete appropriate planning doc before proceeding

---

Phase 3 → Phase 4

Can transition when:

• Architecture completed (Level 2+), OR
• Project is Level 0-1 (skip Phase 3)

Blocking issues:

• Level 2+ project without architecture
• Architecture incomplete or not validated

Recommendation: Complete architecture for medium+ projects

---

Phase 4 Complete

Can transition when:

• All stories marked "done" in sprint-status.yaml
• Code reviewed (if required)
• Tests passing

Blocking issues:

• Incomplete stories
• Failing tests
• Unresolved blockers

Recommendation: Complete all stories before closing project

---

Workflow Dependencies

Must Complete Before

Product Brief → No dependencies (can be first)
Research → No dependencies (can be first)
Brainstorm → No dependencies (can be first)

PRD → Product Brief (recommended, not required)
Tech Spec → Product Brief (recommended, not required)
UX Design → Product Brief or PRD (recommended)

Architecture → PRD or Tech Spec (required)
Gate Check → Architecture (required)

Sprint Planning → PRD or Tech Spec (required), Architecture (if Level 2+)
Create Story → Sprint Planning (required)
Dev Story → Story created (required)
Code Review → Dev Story (required)

Can Work in Parallel

Product Brief + Research
PRD + UX Design (with coordination)
Multiple Dev Stories (different epics)

Sequential Requirements

Sprint Planning → Create Stories → Dev Stories → Code Review

---

Common Workflow Paths

Fast Track (Level 0-1)

Tech Spec → Sprint Planning → Story → Implementation → Done

Duration: Hours to days

Use when: Small, well-defined changes

---

Standard Feature (Level 1-2)

Product Brief → PRD or Tech Spec → Architecture (if Level 2) →
Sprint Planning → Stories → Implementation → Review → Done

Duration: Days to weeks

Use when: Normal feature development

---

Enterprise Project (Level 3-4)

Product Brief → Research → PRD → UX Design → Architecture →
Gate Check → Sprint Planning → Stories → Implementation →
Code Review → Iteration → Done

Duration: Weeks to months

Use when: Complex, multi-team projects

---

Selection Guidance

When unclear about level, ask:

1. How many files will change?

• 1-3 files: Level 0-1
• 3-20 files: Level 1-2
• 20-50 files: Level 2-3
• 50+ files: Level 3-4

2. How many stories estimated?

• 1 story: Level 0
• 1-10 stories: Level 1
• 5-15 stories: Level 2
• 12-40 stories: Level 3
• 40+ stories: Level 4

3. Is architecture design needed?

• No: Level 0-1
• Some: Level 2
• Significant: Level 3
• Extensive: Level 4

4. How long will development take?

• Hours-1 day: Level 0
• 1-5 days: Level 1
• 1-3 weeks: Level 2
• 3-8 weeks: Level 3
• 2+ months: Level 4

When unclear about workflow, ask:

1. Is this a new project or existing codebase?

• New: Start with Product Brief
• Existing: Start with Tech Spec or PRD

2. Do you need stakeholder approval?

• Yes: Use PRD
• No: Use Tech Spec

3. Is this primarily product or technical?

• Product: Use PRD
• Technical: Use Tech Spec

4. Do you have clear requirements?

• Yes: Skip to Planning
• No: Start with Analysis

---

Quick Reference Table

BMAD Orchestrator — Setup Guide

BMAD Method v6 + plannotator integration

Structured AI-driven development with visual plan review at every phase gate.

---

What You Get

Your AI Agent
     │
     ▼
 /workflow-init          ← bootstrap project
     │
     ▼
 Phase 1: Analysis       ← /product-brief, /research
     │
     │  [plannotator review] ← approve before advancing
     ▼
 Phase 2: Planning       ← /prd or /tech-spec
     │
     │  [plannotator review]
     ▼
 Phase 3: Solutioning    ← /architecture  (Level 2+ only)
     │
     │  [plannotator review]
     ▼
 Phase 4: Implementation ← /sprint-planning → /dev-story

plannotator opens a visual browser UI after each phase document is created. You annotate, approve, or request changes — then your agent continues to the next phase. Use the same cross-platform control model as JEO: settings configure the platform, rules prevent invalid phase transitions, and hooks enforce them.

---

Quick Start (3 steps)

Step 1 — Install

bash scripts/install.sh

This installs plannotator CLI and configures the Claude Code ExitPlanMode hook. Restart Claude Code after running this.

Options:

bash scripts/install.sh --init-project       # Also initialize BMAD in current directory
bash scripts/install.sh --skip-plannotator   # BMAD scripts only, no plannotator
bash scripts/install.sh --dry-run            # Preview without making changes

Step 2 — Initialize your project

Run this inside your AI session (Claude Code, Gemini CLI, etc.):

/workflow-init

Your agent will ask three questions:

• Project name — e.g. my-app
• Project type — web-app, mobile-app, api, game, library, other
• Project level — 0 to 4 (see level guide below)

This creates:

bmad/config.yaml                    ← project configuration
docs/bmm-workflow-status.yaml       ← workflow tracking
docs/stories/                       ← story files will go here

Step 3 — Start working

/workflow-status

Your agent shows your current phase, what's done, and exactly what to run next.

---

Project Level Guide

Choose the level that matches your project size:

Quick decision:

• Bug fix or config change → Level 0
• New API endpoint or small UI feature → Level 1
• User auth system or payment integration → Level 2
• Third-party platform integration → Level 3
• Major system overhaul → Level 4

---

plannotator Phase Gate Review

After each phase document is created, submit it for review before moving on:

# After /prd creates docs/prd-myapp-2026-02-25.md
bash scripts/phase-gate-review.sh docs/prd-myapp-2026-02-25.md "PRD Review: myapp"

# After /architecture creates docs/architecture-myapp-2026-02-25.md
bash scripts/phase-gate-review.sh docs/architecture-myapp-2026-02-25.md

Or trigger it from inside your AI session:

planno — review the PRD before we proceed to Phase 3

What happens in the review UI

1. plannotator opens in your browser automatically

• unless the same document hash already has a terminal review result, in which case the gate is skipped

2. Read through the document 3. Annotate specific sections:

• delete — remove a risky or unnecessary element
• insert — add something missing
• replace — correct an approach
• comment — clarify constraints

4. Choose an outcome:

• Approve → your agent advances to the next phase; doc saved to your configured destination (Obsidian or Bear)
• Request Changes → annotations sent back; agent revises and re-submits

Phase gate reference

---

Common Commands

Check status anytime

/workflow-status

Output example:

Project: my-app (web-app, Level 2)

✓ Phase 1: Analysis
  ✓ product-brief (docs/product-brief-my-app-2026-02-25.md)

→ Phase 2: Planning [CURRENT]
  ⚠ prd (required - NOT STARTED)

  Phase 3: Solutioning
  - architecture (required)

  Phase 4: Implementation
  - sprint-planning (required)

Recommended next step: Run /prd to continue

Validate your config

bash scripts/validate-config.sh

Check BMAD + plannotator status

bash scripts/check-status.sh

---

Workflow by Project Level

Level 0–1 (Fast Track)

/workflow-init  →  /tech-spec
     ↓
planno review
     ↓
/sprint-planning  →  /dev-story

Level 2 (Standard Feature)

/workflow-init  →  /product-brief  →  /prd
                                        ↓
                               planno review (Phase 2 gate)
                                        ↓
                               /architecture
                                        ↓
                               planno review (Phase 3 gate)
                                        ↓
                               /sprint-planning  →  /dev-story

Level 3–4 (Enterprise)

/workflow-init  →  /product-brief  →  /research
                                        ↓
                                      /prd  →  /create-ux-design
                                        ↓
                               planno review (Phase 2 gate)
                                        ↓
                               /architecture  →  /solutioning-gate-check
                                        ↓
                               planno review (Phase 3 gate)
                                        ↓
                               /sprint-planning  →  /create-story  →  /dev-story
                                        ↓
                               /code-review  (per sprint)

---

Notes Auto-Save: Obsidian or Bear (Optional)

Approved phase documents can be auto-saved with YAML frontmatter and [[BMAD Plans]] backlinks.

Setup (choose one or both): 1. Open any plannotator review in your browser 2. Click ⚙️ Settings → Saving tab 3. Toggle ON Obsidian Integration and/or Bear Notes 4. For Obsidian: select your vault from the dropdown 5. For Bear: verify callback works first:

   open "bear://x-callback-url/create?title=Test&text=OK"

Each approved document saves as:

vault/plannotator/PRD Review myapp - Feb 25, 2026 10-30pm.md

With frontmatter:

---
created: 2026-02-25T22:30:00.000Z
source: plannotator
tags: [bmad, phase-2, prd, my-app]
---

[[BMAD Plans]]

# PRD: my-app
...

---

Scripts Reference

---

Troubleshooting

BMAD not detected:

# Check if config exists
ls bmad/config.yaml

# Re-initialize if missing
/workflow-init

plannotator doesn't open:

# Check installation
plannotator --version

# Re-install
curl -sSfL https://plannotator.ai/install.sh | sh

Hook not firing on plan exit:

# Re-run hook setup (from plannotator skill)
bash .agent-skills/plannotator/scripts/setup-hook.sh

# Restart Claude Code after this

Status file out of sync:

# Validate config
bash scripts/validate-config.sh

# Manually edit status
# File: docs/bmm-workflow-status.yaml

---

Related Skills

---

Source: BMAD Method · plannotator · skills-template