Using SpecMarket with BMAD

BMAD and SpecMarket solve different problems.

BMAD (Brain Manager Agent Design) is a method for structuring multi-agent workflows. It gives you a role-based architecture — a Brain orchestrator, specialized sub-agents, and a clear task delegation model. If you build with BMAD, you’ve already done the hard work: you have a well-organized multi-agent workflow with defined roles, handoff points, and success expectations.

SpecMarket is the execution and distribution layer. It takes your workflow spec, runs it in a sandboxed environment, verifies the output against your success criteria, and makes it available to other developers. If you’ve built something useful with BMAD, SpecMarket is how other people find and run your work without rebuilding the agent architecture from scratch.

This guide shows you how to use both together.

What Each Tool Does

They don’t fully overlap. BMAD makes you a better multi-agent architect. SpecMarket makes your workflow available, executable, and observable at scale.

The Workflow

Design workflow in BMAD → Package as a SpecMarket spec → Test with CLI → Publish to registry

Step 1: Design Your Workflow with BMAD

BMAD workflows are built around role files. A typical BMAD project includes:

my-research-workflow/
├── bmad-agent/
│   ├── brain.md            # Brain orchestrator: coordinates all agents
│   ├── researcher.md       # Researcher agent: web research + synthesis
│   ├── analyst.md          # Analyst agent: data interpretation
│   └── writer.md           # Writer agent: final output generation
├── tasks/
│   └── research-pipeline.md  # Task definition: what the workflow produces
├── templates/
│   └── output-format.md    # Expected output structure
└── SUCCESS_CRITERIA.md     # What "done" looks like (add this for SpecMarket)

The most important addition for SpecMarket compatibility: a SUCCESS_CRITERIA.md file. BMAD workflows often have implicit success conditions (“the output should be good”). SpecMarket needs explicit, testable criteria.

Write testable success criteria. For a research workflow:

# SUCCESS_CRITERIA.md
 
## Required outputs
- [ ] Final report is a markdown document with a minimum of 800 words
- [ ] Report contains at least 5 cited sources with URLs
- [ ] All cited URLs return 200 (no dead links)
- [ ] Executive summary section is present (≥100 words, ≤300 words)
- [ ] Recommendations section contains at least 3 actionable items
 
## Format requirements
- [ ] Delivered as REPORT.md in the workspace root
- [ ] Headings follow the provided output-format.md template

Vague criteria (“the output should be comprehensive”) produce low success rates. Specific, machine-checkable criteria produce reliable runs. See Advanced Authoring for patterns.

Step 2: Create a SPEC.md for the Workflow

SpecMarket runners need to understand what the workflow does before they run it. Create a SPEC.md that describes the workflow purpose and inputs:

# Research Pipeline Spec
 
## What this workflow does
Runs a multi-agent research pipeline using BMAD orchestration:
- Brain agent coordinates sub-agents
- Researcher agent performs web research on the provided topic
- Analyst agent synthesizes findings
- Writer agent produces a structured report
 
## Inputs
- `TOPIC`: Research topic (string, required)
- `DEPTH`: "shallow" | "standard" | "deep" (default: "standard")
 
## Outputs
- `REPORT.md`: Final research report in the workspace root
 
## Estimated cost
$0.80–$2.40 per run depending on topic depth and source count.

Step 3: Add SpecMarket Metadata

Add a specmarket.yaml file to your workflow directory:

# specmarket.yaml
name: "@yourname/research-pipeline"
displayName: "Multi-Agent Research Pipeline (BMAD)"
description: "BMAD-orchestrated research workflow. Produces structured reports with citations. Replaces manual research + synthesis for recurring intelligence needs."
replacesSaaS: "perplexity-pro"
monthlyCostBefore: 20
infraCost: 120
tags:
  - research
  - multi-agent
  - bmad
  - synthesis
serviceCategory: productivity
primaryStack: python
specFormat: bmad

The specFormat: bmad tag helps SpecMarket display appropriate context in the registry and helps runners understand what architecture they’re running.

Step 4: Test with the SpecMarket CLI

Before publishing, run your workflow locally to verify it works end-to-end:

specmarket run ./my-research-workflow

The CLI runs the workflow in a sandboxed environment, lets all agents complete their tasks, then validates against your SUCCESS_CRITERIA.md. Sample output:

Running @yourname/research-pipeline...
  ✓ SPEC.md loaded
  ✓ BMAD agent files detected (brain.md, researcher.md, analyst.md, writer.md)
  ✓ Brain agent started orchestration
  ✓ Researcher agent: 8 sources collected
  ✓ Analyst agent: synthesis complete
  ✓ Writer agent: report generated (1,240 words)

Running success criteria...
  ✓ REPORT.md present in workspace root
  ✓ Word count: 1,240 (≥800 required)
  ✓ Citations: 8 (≥5 required)
  ✓ URL check: 8/8 return 200
  ✓ Executive summary: 187 words (100–300 range)
  ✓ Recommendations: 5 items (≥3 required)

6/6 criteria passed. Ready to publish.

If criteria fail, the output tells you which check failed and what was observed. Fix the workflow or tighten the spec, then re-run.

Step 5: Validate and Publish

# Security validation
specmarket validate ./my-research-workflow
 
# Publish to registry
specmarket publish

Your workflow appears in the SpecMarket registry. Other developers can find and run it without rebuilding the BMAD architecture:

# Another developer
specmarket search multi-agent research
specmarket run @yourname/research-pipeline

BMAD File Compatibility

SpecMarket reads BMAD files directly — no conversion step needed:

If your BMAD project uses different file naming conventions, specify them in specmarket.yaml:

# specmarket.yaml — custom file layout
agentFiles:
  brain: "orchestrator.md"
  roles: "agents/*.md"
specFile: "workflow-spec.md"

Handling Multi-Agent State

BMAD workflows often produce intermediate state between agents. SpecMarket’s sandbox preserves this correctly:

• Shared workspace — All agents read/write to the same /workspace directory in the sandbox
• State files — Brain-to-agent handoffs written as files are preserved across agent transitions
• No memory across runs — Each run starts clean. Don’t rely on state from a previous run.
• External dependencies — Web requests work; database connections require explicit setup in SPEC.md

If your BMAD workflow relies on a database, document the setup requirements in SPEC.md under a ## Dependencies section. SpecMarket displays these requirements to runners before they execute.

Success Rate and Quality

Once published, your workflow accumulates performance data:

• Success rate — % of runs that pass all success criteria
• Average cost — Average API cost per complete run
• Average completion time — From start to verified output
• Steering frequency — How often human steering was needed

BMAD workflows tend to have more variability than single-agent specs because more agents means more failure surfaces. Common causes of sub-90% success rates in BMAD workflows:

1. Brain agent instructions are too vague — Sub-agents wait for handoffs that never come
2. Success criteria test intermediate state — Check final output only, not in-flight state
3. Agent role files have conflicting instructions — Agents stall when instructions contradict
4. External dependencies are implicit — A researcher agent that assumes internet access will fail if not declared

The Advanced Authoring guide has patterns for writing multi-agent specs that stay above 85%.

Distributing a BMAD Template

If you’ve built a BMAD workflow template (not a complete spec, but a reusable architecture), publish it as a template spec with a note in SPEC.md:

## Template note
This spec is a BMAD workflow template. Before running, customize:
- `brain.md`: Replace the research domain with your target domain
- `SUCCESS_CRITERIA.md`: Update output requirements for your use case

Template specs tend to have lower inherent success rates because they’re intentionally general. Document this expectation in SPEC.md so runners understand what they’re getting.

FAQ

Q: Do I need to use a specific BMAD version? SpecMarket doesn’t enforce a BMAD version. Your agent files are read as plain markdown, so any version of BMAD that produces readable role files is compatible.

Q: My BMAD workflow uses external APIs. Will that work? Yes, but document them. External HTTP requests work in the sandbox. If your researcher agent calls the Brave Search API, add a ## Dependencies section to SPEC.md listing the API key requirement. SpecMarket displays this to runners before they execute.

Q: Can I publish a BMAD workflow that I didn’t write? Only if the license permits it. If you’re publishing a modified version of an existing BMAD template, include attribution in SPEC.md and verify the original license allows redistribution.

Q: How do I handle BMAD workflows that require human input mid-run? SpecMarket’s sandbox supports steering — human input during a run. Document the expected steering points in SPEC.md. Runs that require steering are tracked separately from pure automated runs in your success metrics.

Q: My workflow produces different outputs every run. How do I write consistent success criteria? Test structural properties, not content. “Report contains ≥5 headers” is testable. “Report covers all relevant angles” is not. Structure your success criteria around format, length, presence of required sections, and verifiable facts — not subjective quality.

Next Steps

• Publishing Existing Specs — Overview of all supported spec formats
• Advanced Authoring — Patterns for high-success-rate specs, including multi-agent tips
• Spec Kit Integration — If you use Spec Kit for BMAD spec documentation
• Getting Started — If you’re new to the SpecMarket CLI