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
| Aspect |
Standard BMAD |
BMAD + SSD |
| Phase execution |
Document production (opaque) |
TEA cycle: Decompose → Execute → Validate |
| Task decomposition |
None |
Explicit per-phase task lists with agent assignments |
| Execution surface |
Manual / single-agent |
Multi-agent Team execution (/team) |
| Validation |
Human plannotator review |
Automated architect review → then plannotator |
| Cross-phase traceability |
None |
Requirement coverage matrix per phase transition |
| State tracking |
bmm-workflow-status.yaml |
+ .omc/state/ssd-state.json with task-level granularity |
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 setuprules: 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
| Platform |
Current support mode |
Requirements |
| Gemini CLI |
Native (recommended) |
Register the bmad keyword, then run /workflow-init |
| Claude Code |
Native (recommended) |
Install skill + remember pattern |
| OpenCode |
Orchestration integration |
Use an omx/ohmg-style bridge |
| Codex |
Orchestration integration |
Use an omx/ohmg-style bridge |
Standard BMAD Commands
/workflow-init [--ssd]
/workflow-status
Typical flow:
- Run
/workflow-init to bootstrap BMAD config (add --ssd to also initialize SSD state).
- Move through phases: Analysis → Planning → Solutioning → Implementation.
- Run
/workflow-status any time to inspect current phase and progress.
| Action |
Command |
| Initialize BMAD |
/workflow-init |
| Initialize BMAD + SSD |
/workflow-init --ssd |
| Check BMAD/SSD status |
/workflow-status |
SSD Commands (TEA Integration)
Use these commands to run structured TEA cycles within each BMAD phase:
| Command |
TEA Step |
Purpose |
/ssd-init |
Setup |
Initialize .omc/state/ssd-state.json alongside BMAD (called automatically by /workflow-init --ssd) |
/ssd-decompose |
Task |
Decompose current phase into concrete tasks with agent assignments |
/ssd-execute |
Execute |
Dispatch decomposed tasks to agents via /team (multi-agent parallel execution) |
/ssd-validate |
Architect |
Validate phase outputs for coherence, completeness, and cross-phase traceability |
/ssd-cycle |
T+E+A |
Run the full TEA cycle for the current phase (decompose → execute → validate) |
/ssd-advance |
Transition |
Advance to next phase after TEA cycle passes architect validation |
/ssd-status |
Status |
Show SSD-enriched status: phase + TEA step + task progress + validation verdict |
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
| TEA Step |
Action |
Agents |
Output |
| Task |
Decompose into: market research, user persona definition, competitive landscape, value proposition, constraint identification |
explore (haiku) + analyst (opus) |
Task list in ssd-state.json |
| Execute |
Run tasks in parallel: research, persona, competitive data |
document-specialist, analyst, scientist via Team |
docs/ssd/phase-1/*.md |
| Architect |
Validate: personas match value prop? Constraints conflict? Competitive gap real? |
architect (opus) + fabric bmad_ssd_phase_review |
Coherence report + PASS/FAIL/REVISE |
Phase 2: Planning
| TEA Step |
Action |
Agents |
Output |
| Task |
Decompose into: functional requirements, non-functional requirements, user stories, acceptance criteria, UX specification |
planner (opus) |
Task list |
| Execute |
Write functional/non-functional reqs from product brief; produce UX flows; draft acceptance criteria |
analyst, designer, test-engineer via Team |
PRD sections |
| Architect |
Validate: requirements trace to product brief? Acceptance criteria testable? UX covers all user stories? |
architect (opus) + fabric bmad_ssd_phase_review |
Traceability matrix + verdict |
Phase 3: Solutioning
| TEA Step |
Action |
Agents |
Output |
| Task |
Decompose into: component design, API contracts, data model, integration design, security design, performance design, technology selection |
architect (opus) |
Task list |
| Execute |
Component/integration design; security design; performance design; technology evaluation |
architect, security-reviewer, quality-reviewer, document-specialist via Team |
Architecture sections |
| Architect |
Validate: architecture fulfills PRD? API contracts consistent with user stories? Security design matches threat model? Run cross-phase traceability. |
architect (opus) + critic (opus) + fabric bmad_ssd_phase_review |
Architecture review + requirement coverage matrix |
Phase 4: Implementation
| TEA Step |
Action |
Agents |
Output |
| Task |
Decompose sprint: epics → stories → implementation tasks (code, test, docs) |
planner (opus) |
Sprint plan with task breakdown |
| Execute |
Implement code; write tests; update docs; resolve build issues |
executor, test-engineer, writer, build-fixer via Team |
Code, tests, docs per story |
| Architect |
Validate: implementation matches architecture? Tests cover acceptance criteria? API contract honored? |
verifier (sonnet) + code-reviewer (opus) + fabric bmad_ssd_phase_review |
Implementation coherence report |
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:
{
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
