BMAD in Practice: Two Specs, One Method, Zero Blank YAML Files¶

Last month I wrote about BMAD the method. This post is BMAD the practice.

Here's the setup. In the 66/7 gap post I argued that the reason two-thirds of GenAI runs on Kubernetes while only 7% of orgs can ship models daily is a missing paved road: no standard pipeline from model registry to production traffic. Which raises the obvious follow-up question. Fine, someone has to build that golden path. How?

The honest answer for most platform teams: open a blank YAML file and start typing, with the architecture decisions happening implicitly, one resource at a time, in whatever order the YAML demands them. Three weeks later you discover that nobody decided what happens when the eval gate fails at 2am, because no artifact ever forced that question.

So I ran the build through BMAD instead. Twice, actually: once for the model-serving golden path, and once for a completely different problem, an incident runbook feedback loop, to test whether the method transfers or whether it only works on the thing I designed it around.

What the spec caught before the YAML existed

The upstream phase surfaced nine decisions for the golden path that would otherwise have been made implicitly mid-YAML — including the one that matters most in production: who gets paged when a model passes canary but fails the eval gate. Nobody had an answer. Now it's in the PRD, and the on-call rota knows.

C4 Architecture Diagram

The Task: A Golden Path, Which Is Already a Spec¶

Golden paths are a natural fit for spec-first work, and it took me embarrassingly long to notice why. A golden path is a spec. It's a promise to developers: follow this route and these things are guaranteed. If you can't write down what's guaranteed, you don't have a golden path, you have a wiki page with YAML on it.

The build target, in one sentence: an ML engineer publishes an evaluated model version to the registry, and everything from there to production traffic is automated behind one PR merge.

You could start Helm-charting that today. Instead, the BMAD sequence: Preston (PM agent) turns the idea into a PRD by interrogating you. Winston (architect) turns the PRD into architecture decisions. Sam (platform engineer agent) turns the architecture into GitOps-native YAML. Quinn reads the output against the spec and flags drift. All four artifacts get committed to the repo.

The agents, thirty seconds

BMAD v6.8 installs with npx bmad-method@latest install and drops agent personas into .bmad/. For platform work you want Preston, Winston, Sam, and Quinn as a minimum. The original BMAD post covers setup, IDE integration, and how the agents differ from GitHub's spec-kit.

Upstream: What Preston Refused to Let Me Skip¶

I gave Preston two sentences, roughly the build target above. What came back was questions, and the questions are the product.

Which teams deploy models, and do they all get the same guarantees? What's the maximum acceptable time from registry publish to production traffic? When the eval gate fails, does the rollout freeze, roll back, or page someone? Is there a GPU budget ceiling a canary is allowed to consume? Who owns the golden dataset the eval runs against, and how often is it refreshed?

That last one stopped me. The eval gate is the load-bearing element of the whole pipeline — I'd written that myself in the 66/7 post — and I had no answer for who maintains the dataset it evaluates against. An eval gate scoring against a stale dataset is worse than no gate, because it converts "we don't check quality" into "we check quality wrong, confidently."

The PRD that came out, condensed:

# Model-Serving Golden Path — PRD v1.0

## Problem
Model deploys are artisanal: notebook-driven, single-person,
unmeasured. Target state: registry publish → production traffic
via one reviewed PR merge, with quality gating.

## Users
ML engineers (deploy models), platform team (own the path),
on-call (respond to gate failures).

## Success metrics
- Model deploys per week (primary — DORA frequency for models)
- Registry-publish-to-prod lead time < 4h
- Zero ungated production model changes

## Out of scope (v1)
Training pipelines, multi-region failover, non-HTTP inference.

## Constraints
- Eval gate mandatory for prod; golden dataset owned by ML team,
  refreshed monthly, versioned in Git next to environment config
- Canary GPU budget: max 1 additional replica per rollout
- Gate failure → automatic rollback + page model owner (not platform)

Steal the success metrics section

Whatever you build, the metric trio of frequency, lead time, and gated-change percentage transfers to any platform capability. If your PRD's success section says "improve developer experience," Preston would bounce it back. Numbers or it didn't happen.

Architecture and YAML: Winston Decides, Sam Builds¶

Winston's job is turning the PRD into decisions with reasons attached. Three of the nine mattered most.

KServe over raw vLLM deployments — because the PRD guarantees the path to any team, and KServe's InferenceService gives a uniform surface across model formats. Teams with exotic needs can eject; ejecting is leaving the golden path, which is allowed and visible.

Argo Rollouts with an eval AnalysisTemplate over Flagger — because the eval gate needs a custom Prometheus metric as a promotion condition, and the PRD's rollback-plus-page behaviour maps directly onto Rollouts' failure handling.

Registry refs pinned in Git, bot-opened bump PRs — the merge is the human act; everything downstream is machinery. Same shape as the drift detection pattern, pointed at model versions.

Sam turned those into the working set. The centrepiece, condensed:

# gitops/apps/model-serving-appset.yaml — one Application per model, per env
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: model-serving
spec:
  generators:
    - git:
        repoURL: https://github.com/polarpoint-io/platform-config
        revision: main
        directories:
          - path: models/*/envs/*
  template:
    metadata:
      name: "{{path[1]}}-{{path[3]}}"
    spec:
      project: model-serving
      source:
        repoURL: https://github.com/polarpoint-io/platform-config
        path: "{{path}}"
      destination:
        name: "{{path[3]}}"
      syncPolicy:
        automated: { prune: true, selfHeal: true }

# models/support-summariser/envs/prod/rollout-analysis.yaml — the gate
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: eval-gate
spec:
  metrics:
    - name: eval-score
      interval: 5m
      failureLimit: 1
      provider:
        prometheus:
          address: http://prometheus.monitoring:9090
          query: avg(model_eval_score{model="support-summariser",track="canary"})
      successCondition: result[0] >= 0.87

Then Quinn earned its place in the roster. Reading Sam's output against the PRD, it flagged that the notification route on gate failure pointed at the platform team's Slack channel. The PRD says gate failures page the model owner. That's exactly the class of quiet drift that turns into "why did platform get paged for the ML team's regression" three months in. One line fixed, before merge, because a review agent had a spec to review against.

Same Method, Different Problem: The Runbook Loop¶

One worked example proves BMAD works on the problem you designed the walkthrough around. So here's the transfer test, compressed.

The problem: HolmesGPT investigation logs reveal runbook gaps — every failed knowledge lookup during an incident is a missing runbook section. And merge-triggered doc agents can keep docs current with code. The build: connect them, so incident investigations automatically become drafted runbook PRs.

Preston's interrogation surfaced a different set of landmines. Who reviews a runbook PR drafted from a 2am incident, and how fast? (On-call's incident buddy, within the post-incident review window.) Does a drafted runbook section go live before a human has executed it once? (No. A verified: false frontmatter flag gates it out of HolmesGPT's retrieval until someone confirms the steps work.) What stops the loop flooding the docs repo after a chaotic incident? (Clustering: one PR per incident, not per failed lookup.)

Winston's decisions: investigation logs land in a queue, a nightly job clusters them by service, Claude drafts sections against the affected runbook, PRs open with the incident timeline attached as review context. Sam's output is a CronJob, a workflow file, and a routing map addition to AGENTS.md. About 140 lines total.

The method held. Different domain, different failure modes, same shape: the questions got asked while they were cheap.

The tell that you skipped upstream

Both builds had a moment where the PRD forced a decision I'd have deferred: the golden dataset owner, the verified-flag gate. If your last platform project contains a decision you can't name the owner of, that decision was made implicitly by whoever wrote the YAML that day. That's the gap BMAD closes.

What Actually Changed vs. YAML-First¶

Total elapsed time for the golden path, idea to reviewed YAML: about a day, of which the upstream session was maybe ninety minutes. The runbook loop was an afternoon. Neither is faster than an experienced engineer winging it. That's not the claim.

The claim is about what exists afterwards. docs/prd.md and docs/architecture.md are in the repo, so the next engineer (or the next agent — this is exactly the context your AGENTS.md should route to) reads why the path works this way before touching it. The nine decisions have owners. And Quinn's compliance check means the spec isn't aspirational documentation; it's enforced.

Would I run BMAD for every task? No. A one-file fix doesn't need a PRD, and pretending it does is how methods die. The threshold I'd use: if the thing you're building makes promises to other teams, spec it. Golden paths, self-service APIs, incident tooling — those all qualify.

FAQ¶

Isn't this just writing design docs with extra steps?

The difference is enforcement and interrogation. A design doc is whatever you thought to write down; Preston asks the questions you'd have skipped, and Quinn checks the output against the doc before merge. The doc also lives in the repo where agents load it as context, not in a wiki where it goes to die.

How long does the upstream phase actually take?

Ninety minutes for the golden path PRD and architecture, including the back-and-forth. The honest overhead comparison isn't against "just writing YAML" — it's against the rework when an implicit decision turns out wrong. One avoided who-gets-paged incident pays for a lot of ninety-minute sessions.

Do you need all four agents?

Preston and Sam are the minimum useful pair: interrogated requirements, then implementation. Winston earns his place when there are real architecture choices (KServe vs vLLM was one). Quinn is the one teams skip and shouldn't — the compliance check is what makes the spec mean something after the build starts.

Does BMAD work with Claude Code specifically?

Yes — the installer targets Claude Code, Cursor, Copilot, and Gemini CLI. In Claude Code the agents arrive as personas your session can invoke, and the .bmad/context/ directory rides along in project context. Pair it with a tight CLAUDE.md so the agents inherit your platform conventions.

The blank YAML file is the most expensive text editor state in platform engineering, because every keystroke into it is a decision nobody wrote down. Both of these builds shipped with their decisions attached. That's the whole trade.

Walkthrough files¶

The full worked example, including the PRD sections, the eval-gate AnalysisTemplate, and the when-to-spec threshold, is in the ai-capabilities repo.

File	What it is
`examples/bmad-golden-path.md`	The BMAD pipeline applied to the model-serving golden path — workflow, inputs/outputs, PRD sections that do the work
`templates/github-issue-agent-task.md`	Issue template that enforces scope and success criteria before any agent picks up a task

For the method itself: Spec First, GitOps Second: The Platform Engineer's Guide to BMAD. For why the golden path matters: 66% of GenAI Runs on Kubernetes. Only 7% Can Ship Daily.. For the runbook loop this extends: HolmesGPT Knows What Your Runbooks Are Missing.