Quality & Testing

Most teams test the way they brush their teeth: the same way, every time, whether or not it's warranted. That feels responsible. It isn't. Uniform test effort spends your scarcest resource — attention — evenly across code that carries wildly uneven risk. The login flow and the tooltip copy get the same five test cases. One of those can lose you a customer; the other can't.

The BMAD method takes the opposite stance, and it has a name and a face: Murat 🧪, the Master Test Architect — the TEA module. Murat's whole job is to point test effort at where the risk actually is, then get out of the way. Quality here is a gate the work passes through, not a folder of paperwork you assemble after the fact.

The one line to remember: spend test effort where the risk is. Cover the release-blocking paths to the hilt; let the low-risk surface area breathe.

The philosophy: risk-based testing

Every acceptance criterion carries a priority. The TEA workflows lean on a simple, honest ranking:

• P0 — release-blocking. If this breaks, you don't ship. Target: 100% coverage. No exceptions, no negotiation.
• P1 — important. Real user pain if it fails, but not a ship-stopper. Target: ~90% coverage. This is the threshold that does the work — it's high enough to keep you honest and low enough to admit you can't test everything.
• P2 and below — nice to have. Cover opportunistically. Over-testing here is a cost, not a virtue.

Overall coverage has a floor too (think ~80%), but the priority split is what matters. A suite that's 100% on P0 and 92% on P1 is healthier than one that's a flat 95% everywhere — because the flat number is hiding an untested release-blocker somewhere in the average.

This is the whole game: calculate the risk, then invest to match it. Strong opinions, weakly held — if the risk profile changes, the test plan changes with it.

Where testing lives across the method

Testing is not a phase that happens at the end. It's a thread woven through the whole method — design early, acceptance before code, automation during the build, and a traceability check at epic close.

1. Test design — early, from the plan. The moment the architecture and epics/stories exist (Phase 3, Solutioning), the TEA reads them and produces a risk-based test plan before a line of feature code is written. Designing tests against the plan surfaces ambiguity in the plan — the cheapest possible time to find it.
2. ATDD — acceptance tests before code, where it pays off. In Implementation, for stories where correctness is expensive to get wrong, the TEA writes red-phase acceptance tests first. The developer agent (Amelia) then writes just enough code to turn them green. The test is the specification.
3. Automation — during the build. As stories land, coverage expands to match what actually got built — unit, integration, E2E, API.
4. Traceability + quality gate — at epic close. When the epic's stories are done, the TEA maps every acceptance criterion to the tests that cover it and renders a single gate decision. That decision is the subject of most of this page.

Note: Not every story needs every step. ATDD earns its keep on high-risk, correctness-critical work; a copy tweak doesn't need a red-phase scaffold. The TEA calibrates — that's the job.

The TEA workflows

Each of these is a BMAD slash command you launch from the terminal. They talk to Murat, the Test Architect. Full syntax lives in the slash-command reference.

Tip: These compose in a natural order — test-design → framework → ci set the stage; atdd → automate → nfr do the per-story work; test-review audits the tests; trace renders the verdict. You don't have to run all of them, but that's the grain to run with.

The epic TEA quality gate

At the end of an epic, /bmad-testarch-trace writes one machine-readable artifact — the gate decision — to:

_bmad-output/test-artifacts/traceability/gate-decision-<epic>.json

BMAD Board reads that file and surfaces the verdict on the epic itself, rendered as a card just before the Retrospective at close-out. It's the last quality checkpoint before you call the epic done.

The five canonical verdicts

The gate collapses all the coverage math into exactly one of these — and only these close the gate:

Anything else — a malformed file, a missing gate_status, a verdict the model invented — resolves to no gate yet, on purpose. The board would rather show you an open, actionable gate than a green one it can't stand behind.

What the card carries

A resolved gate decision includes a rationale — the human-readable why. Here's a real one:

{
  "gate_status": "PASS",
  "rationale": "P0 coverage 100% (3/3), P1 coverage 100% (4/4, target 90%),
                overall 100% (7/7 FULL, min 80%). 32 active tests across 4
                files, 0 skipped. All release-blocking criteria met.",
  "links": {
    "trace_report_path":
      "_bmad-output/test-artifacts/traceability/traceability-matrix-<epic>.md"
  }
}

On the epic card, the board:

• colour-codes the seal icon by verdict (green pass, amber concerns, red fail, muted for waived / not-evaluated) — the risk signal is visible at a glance;
• shows the rationale inline so you read the why, not just the badge;
• offers Open report (when the traceability matrix exists on disk) to jump into the full breakdown;
• offers Re-run — re-fires /bmad-testarch-trace; once a fresh artifact lands and the project rescans, the stale verdict is replaced.

It's advisory — by design

This is the part people get wrong about quality gates, so let's be explicit: the TEA gate informs, it does not hard-block. It is advisory and ephemeral.

• A FAIL does not lock the epic. You, the agile lead, can proceed with eyes open.
• The right move on a CONCERNS or FAIL you accept is to WAIVE it — with a rationale on the record. A waiver is a decision you can defend later, not a bug you hid.
• Skipping the gate is per-session and does not mark the epic done (unlike skipping the retrospective) — because an advisory signal you chose not to look at shouldn't masquerade as a passed check.
• The done state always keeps an affordance (Open report, Re-run). The gate never traps you on a verdict.

Note: The only persisted state is the gate-decision artifact on disk. There's no hidden gate database — what you see is that JSON file, rendered.

How to run it in BMAD Board

Everything above is driven from the embedded terminal:

1. From a story's QA step — while working a story in Implementation, launch the relevant /bmad-testarch-* command (e.g. /bmad-testarch-atdd before dev, /bmad-testarch-automate after). BMAD Board opens a terminal running that command against your project.
2. At epic close — run /bmad-testarch-trace. It writes the gate-decision artifact, and the verdict then appears on the epic card just before the retrospective.
3. Read, then decide — open the report, read the rationale, and PASS through, WAIVE with a reason, or Re-run after you've closed a gap.

You can launch these commands with any terminal coding agent that supports the BMAD method — Claude Code, Codex, Gemini, Cursor, Aider, Open Code, and others — the same as any other BMAD command.

Where not to over-test

Strong opinions, weakly held — here's where I'd tell you to spend less:

• Trivial, low-blast-radius code. Getters, one-line formatters, static copy. The cost of a test exceeds the cost of the bug. Skip it.
• Volatile UI that's still churning. Pinning down pixel-perfect assertions on a screen the UX designer is still iterating on just manufactures red builds and maintenance. Test the behaviour, defer the chrome.
• Third-party code you don't own. Test your integration boundary — the contract — not the library's internals. That's their P0, not yours.
• Everything, uniformly, to hit a coverage number. A 95% flat coverage badge that leaves one P0 path untested is worse than an honest 82% that covers every release-blocker. The badge is not the goal; the risk profile is.

Every test you write is a small liability you maintain forever. Write the ones that buy down real risk. Delete the ones that don't. That's not cutting corners — that's the whole discipline.

Next steps

• Implementation → the story cycle — see where ATDD and automation slot into building a story.

See also

• The method: overview — the four phases and how quality threads through all of them.
• Slash-command reference — full syntax for every /bmad-testarch-* command.