BMAD on Tiziano Basile | Software Engineer

A BMAD workflow, end to end: shipping a feature the spec-driven way

Thu, 06 Aug 2026 09:00:00 +0000

If the only way you’ve ever worked with an AI is to vibe code with it, which is to say you open the editor, type a prompt, and keep whatever looks roughly right, then this is the post I wish someone had handed me back when I was doing exactly that. It isn’t another argument about why spec-driven development is better, because I already made that case here; it’s simply one complete pass through a real workflow, with the actual commands, so that you can see for yourself what the whole thing looks like from the inside.

Together we’ll build one small feature with BMAD, taking it all the way from a vague idea to reviewed code, and although the example is deliberately thin it is also complete, running the full sequence of brainstorm → spec → architecture → story → implementation → review without waving our hands over any of the parts that usually get skipped, so that by the end you can see exactly where the friction lives and what it buys you in return.

If you’ve never met the BMAD agents before, the previous post introduces the crew, and while you don’t strictly need it in order to follow along here, it does help to know that “John” is a product manager and “Amelia” is a developer rather than people I actually work with.

The example is a URL shortener where links can expire. All the artifacts you’ll see below are illustrative snippets from that walkthrough.

The feature (and the trap)

Here’s the feature: a URL shortener where links can expire.

Now watch how a vibe-coding session usually starts, because you’d open a chat and type something like this:

Build me a URL shortener in [your stack]. Links should be able to expire.

That prompt feels complete, but it really isn’t, because it’s a specification riddled with holes, and the AI is going to quietly fill every one of those holes with a guess that you never actually got to see it make, so it’s worth counting them:

When does a link expire? After a fixed TTL? At an absolute timestamp you pass in? After N clicks? “Expire” is three different features.
What happens when someone hits an expired link? A 404? A 410 Gone? A redirect to a “this link expired” page? These are observably different behaviors, and a caller integrating with you will build against whichever one you pick.
Do we count clicks? If expiry can be click-based, you need a counter. If it can’t, you probably still want analytics. That’s a storage decision hiding inside a one-line prompt.
What’s the ID scheme? Random short codes? Collisions? Custom aliases?

Vibe coding doesn’t make any of these decisions go away, it simply arranges for someone else to make them silently and invisibly at generation time, and then it hands you back a pile of code that you now have to reverse-engineer in order to discover what was actually decided on your behalf. So when the “expired link returns 404” bug report lands on your desk three weeks later, you’ll find yourself debugging a decision that nobody ever consciously made in the first place.

Spec-driven development, at its core, is really just this: you make the decisions before you write the code, on purpose, and in a place where you can actually see them, and BMAD is simply one way of running that process with the AI working inside the loop with you rather than against you.

Let’s run it.

The mental model, in 30 seconds

Two things to hold in your head before we start:

BMAD is a team of agents rather than a single assistant. Each one is a persona with a specific job to do, so there’s an analyst who interrogates the idea, a product manager who writes the requirements, an architect who makes the technical calls and a developer who implements them, and you move between these personas deliberately as the work progresses. In the commands that follow, every phase can be run either by summoning the persona directly with /bmad-agent-* or by invoking its underlying workflow with /bmad-*, and you should feel free to use whichever of the two you prefer.
The real output of the early phases is not code at all, it’s artifacts. These are things like a brief, a PRD, an architecture document and a story file, all of them plain markdown that lives right there in your repository, and the code itself only arrives last, sitting downstream of a set of documents that you can read, review and version like anything else.

Broadly speaking there are two stages to all of this, a planning stage in which you work out what to build and how to build it, followed by an implementation stage in which you actually build it, and the whole point of the arrangement is that planning leaves behind durable, reviewable artifacts which then carry all of their context forward into implementation, so that the AI writing your code is working from a genuine spec rather than from a vibe.

flowchart LR
idea([Vague idea]) --> A
subgraph Planning
A["🔍 Analyst (Mary)<br/>brainstorm"] --> P["📋 PM (John)<br/>PRD / spec"]
P --> W["🏛️ Architect (Winston)<br/>architecture"]
W --> S["📝 Story<br/>context handoff"]
end
subgraph Implementation
S --> D["💻 Dev (Amelia)<br/>implement"]
D --> R["🔎 Code review"]
end
R --> code([Reviewed code])
A -.-> brief[/brief.md/]
P -.-> prd[/prd.md/]
W -.-> arch[/architecture.md/]
S -.-> story[/story.md/]

🔍 click the diagram to enlarge

Everything drawn with a dotted line there is a file that ends up in your repository, and that is precisely the part of the process that vibe coding never produces.

Phase 1, Brainstorm: drag the hidden decisions into the light

We start with Mary, the analyst, and a brainstorming session:

1
2
3


/bmad-agent-analyst # then pick the brainstorming capability
# or go straight to it:
/bmad-brainstorming

The move here is genuinely counterintuitive if you’re accustomed to prompting an AI for output, because you’re not asking it for an answer at all, you’re asking it to interrogate you, and Mary’s entire job in this session is to ask you the questions that you quietly skipped over. This is exactly the moment where those four hidden decisions from the trap section earlier stop being invisible and start being things you have to answer for.

A brainstorm on “URL shortener with expiring links” should surface, at minimum: which kinds of expiry we actually want (TTL vs absolute date vs click-count), the expired-link behavior as a deliberate choice, whether click tracking is a feature or just a mechanism, and the ID/alias scheme.

The artifact that comes out of this phase is a brief, and this really is the part worth staring at for a moment, because it doesn’t merely list the things we intend to build; it also records the things we have deliberately decided not to build, so that those decisions leave a paper trail behind them instead of quietly evaporating. Here’s the heart of an example brief.md:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


## Decisions (made on purpose, for v1)

- **Expiry model: absolute timestamp.** A link carries an optional `expires_at`
 (UTC instant). No `expires_at` means the link never expires.
- **Expiry is inclusive.** At exactly `expires_at`, the link is already expired.
- **Behavior on an expired link: `410 Gone`,** with body `{ "reason": "expired" }`.
 Not a `404`, not a `302` to a landing page.
- **ID scheme: 7-character base62 random code,** with collision-retry.

## Explicitly out of scope for v1 (deferred, not forgotten)

- Relative / TTL expiry ("expire 24h after creation").
- Click-count expiry, click tracking / analytics.
- Custom aliases, custom "this link expired" landing pages.

Take a good look at that “out of scope” list, because every single line in it is a decision that a vibe-coding prompt would have made for you, silently and without asking, whereas here every one of them is on the record, deferred deliberately rather than forgotten by accident.

If you want a more formal artifact than a brainstorm dump:

1

/bmad-product-brief

Notice what has already happened here, because we haven’t yet written a single line of code and we have already caught three or four decisions that vibe coding would otherwise have made for us essentially at random.

Phase 2, PRD: turn decisions into requirements you can check

Now we switch to John, the product manager, to produce a Product Requirements Document.

1
2
3


/bmad-agent-pm
# or the workflow directly:
/bmad-prd

John’s job is to take something like “we decided that links expire by absolute timestamp and that expired links return 410 Gone” and convert it into requirements that are precise enough that you could hand them to a complete stranger and expect the right thing to come back, and this is the point at which the fuzzy brainstorm finally hardens into something resembling a contract.

Here’s an example FR-3 from prd.md:

1
2
3
4
5
6
7
8
9


### FR-3: Accessing an expired link

- **Given** a short link whose `expires_at` is at or before now
- **When** a client requests `GET /{code}`
- **Then** the service responds `410 Gone`
- **And** the response body includes a machine-readable `reason: "expired"`
- **And** no redirect (`3xx`) is issued

Non-goals for v1: custom "expired" landing pages, per-link grace periods.

Read that through and notice what has changed, because the 410 decision is now written down, reviewable and testable, which means that a month from now the question “why does it return 410?” has an actual answer with a paper trail attached to it, and that really is the whole difference between a decision and an accident.

If you want the requirements distilled into a tighter, machine-oriented contract for the downstream agents, BMAD has a dedicated step:

1

/bmad-spec

Phase 3, Architecture: the technical calls, made once

Winston, the architect, takes the what that we’ve established so far and decides the how, and for a feature this small the right instinct is to keep the whole thing thin, because you really don’t need a forty-page architecture document for a URL shortener, you only need the handful of decisions that would be genuinely expensive to get wrong:

1
2
3


/bmad-agent-architect
# or:
/bmad-architecture

The decisions worth pinning down here:

Storage: how do we persist code → target_url + expires_at? Key-value store, relational table, in-memory for a toy?
Expiry enforcement: lazy (check expires_at on read) or active (a sweeper that deletes expired rows)?
ID generation: how we mint short codes and handle collisions.

The lazy-versus-active call is the one with real teeth in it, and here is how architecture.md records that call, capturing both the decision and its consequence:

1
2
3
4
5
6
7


### Expiry enforcement: lazy (checked on read)

- **Chosen: lazy.** Simplest correct behavior; no scheduler, no clock daemon.
- **Consequence, on purpose:** an expired link's record still _exists_ in the
 store until something evicts it. `resolve` must therefore never assume
 "present in store" means "live". It must evaluate expiry every time.
- Rejected for v1: active sweeping. Adds a scheduler we don't need yet.

Writing down the consequence, namely that “present in store” does not mean “live”, is the part that pays off later on, because it’s the exact invariant that the implementation is going to have to honor, and it has been stated in plain language before a single line of resolve even exists. The output of all this is an architecture.md sitting in your repository, reviewable and versioned, the kind of thing a teammate can simply read instead of having to reverse-engineer it back out of the code.

Phase 4, The story: packaging context for the implementer

This is the phase that vibe coders have quite simply never seen, and it also happens to be the one that makes the whole method actually work.

1
2


/bmad-create-epics-and-stories # break the PRD into epics + stories
/bmad-create-story # generate the next story with full context

A story is a single, self-contained unit of work, but the genuinely important part is what’s actually in it, because a BMAD story file is nothing like a Jira ticket that carries a title and a single sentence of description. It is instead a complete context package, gathering together the relevant requirements, the architectural decisions that happen to apply, the acceptance criteria and pointers to the exact files that are in play, and it is written in such a way that an agent, or for that matter a human, can pick it up completely cold and still have everything they need to get started.

Here’s an example story-1.3:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# Story 1.3 — Return 410 for expired links

## Context

Implements FR-3 (see prd.md). Expiry is enforced lazily on read, and the
boundary instant is inclusive (now >= expires_at ⇒ expired) — both are
architecture decisions. `now` is injected into resolve() so expiry stays
deterministic in tests.

## Acceptance criteria

- [ ] resolve of a link whose expires_at <= now → 410, body {"reason": "expired"}
- [ ] no 3xx is produced for an expired link
- [ ] a link with expires_at in the future still redirects 302 (regression guard)
- [ ] a link with expires_at is None still redirects 302 (never expires)
- [ ] at exactly expires_at, the link is already expired (boundary is inclusive)
- [ ] unknown code still returns 404 (unchanged)

## Files in play

- shortener/service.py (add `now` param to resolve; add expiry branch)
- shortener/http_app.py (supply now = datetime.now(timezone.utc))
- tests/test_service.py (expiry + regression cases)

Notice how the criteria carry all of the upstream decisions through verbatim, including the inclusive boundary, the “no 3xx” rule and the regression guards, so that nothing at all has been left open to interpretation.

Why does any of this matter so much? It matters because when you hand this to an implementer there is genuinely nothing left for them to guess at, since the 410 is no longer a coin flip but an acceptance criterion with a regression guard sitting right next to it, and the story turns out to be the vehicle that carries every last decision you made back in phases 1 through 3 forward into the code itself.

With the story now in hand, all of the planning artifacts are finally in place, and before writing any code at all it is worth taking a moment to check that they actually line up with one another:

1

/bmad-check-implementation-readiness

This validates that your PRD, your architecture and your stories all agree with one another before anyone starts implementing anything, which is really the spec-driven equivalent of the old carpenter’s rule to measure twice and cut once.

Phase 5, Implementation: now, finally, code

Only now do we finally sit down to write code, and by this point the act of “writing the code” has become almost mechanical, precisely because every meaningful decision was already made further upstream.

1
2
3


/bmad-agent-dev
# or run a story end to end:
/bmad-dev-story

Amelia, the developer, works from the story, implementing against the acceptance criteria one by one, and the real tell that you are no longer vibe coding is that she can check her own work against a written definition of done rather than against her own intuition. Whenever she finds herself uncertain about something, the answer is already sitting in the story, or in the PRD, or in the architecture document, and never in a guess.

The entire implementation of story 1.3 is this diff to resolve, and because the story pre-decided everything the change is almost mechanical:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


-def resolve(store: InMemoryStore, code: str) -> Resolution:
- """Resolve a short code to a redirect or an error (FR-2, FR-4)."""
+def resolve(store: InMemoryStore, code: str, *, now: datetime) -> Resolution:
+ """Resolve a short code to a redirect or an error (FR-2, FR-3, FR-4).
+
+ Expiry is evaluated lazily on every read: a record present in the store is
+ not necessarily live. The boundary is inclusive — at exactly ``expires_at``
+ the link is already gone.
+ """
 link = store.get(code)
 if link is None:
 return Resolution(status=404, body={"reason": "not_found"})
+ if link.expires_at is not None and link.expires_at <= now:
+ return Resolution(status=410, body={"reason": "expired"})
 return Resolution(status=302, location=link.target_url)

It comes down to two lines of logic, but the part worth looking at is the docstring, because it cites FR-3, the lazy-expiry decision and the inclusive boundary all together, and it can do so only because all three of them came down the pipe from the artifacts that preceded it. The code, in other words, is not the place where any of those decisions were made, it is simply the place where they were finally applied.

Contrast this with the ordinary vibe-coding loop, where you prompt the model, eyeball whatever output comes back and then re-prompt it whenever the result is wrong, because here the loop instead becomes implement against the criteria, verify against the criteria and you’re done. The AI is of course still doing all of the actual typing, but this time it is typing toward a target that you defined in advance rather than toward some vague sense of “looks about right.”

Phase 6, Review: verify against the spec, not against vibes

1

/bmad-code-review

The review is what closes the loop, and here is the quiet superpower that comes from having done all of the upstream work first, which is that you can now review against the spec itself. A question like “does the expired-link path return 410 in the way that FR-3 requires?” has become a plain yes-or-no question, whereas without a spec to lean on, code review tends to degenerate into “looks fine to me”, which is really just vibe coding wearing a blazer.

And this is exactly where the whole approach earned its keep, because the review caught a real defect, and that defect was only catchable in the first place precisely because there was a spec to check the code against:

Finding: architecture.md states an invariant — “timestamps are UTC-aware; naive datetimes are a caller error” — but nothing enforces it. create_link happily accepts a naive expires_at. At resolve time, expires_at <= now then compares a naive datetime against the adapter’s aware now and raises TypeError: can't compare offset-naive and offset-aware datetimes. FR-3 promised a 410; the caller gets an unhandled 500 instead.

That single bug is the whole argument for spec-driven development compressed into one example, because a vibe-coded shortener would almost certainly have carried the very same defect, and yet with no architecture.md invariant for it to violate, the reviewer would have had nothing to notice it against in the first place. The spec did more than merely document the decision, it turned what would have been a silent 500 into a visible finding, and the fix itself came down to a three-line guard in create_link that fails fast with a clear error, together with a regression test, and because the invariant had been written down all along, the question “is this actually fixed?” is once again a simple yes-or-no.

What actually just happened

Step back and look at what we’ve produced:

brief.md: the ideas and the decisions we deferred
prd.md: the requirements, testable
architecture.md: the technical calls
story-1.3.md: the context package that drove the code
the code itself, plus tests

The code is the smallest artifact in that entire list, and it is also the very last one we made, and that inversion is really the whole point of the exercise. In vibe coding the code is the first and only artifact you ever produce, so every decision ends up trapped inside it and left undocumented, whereas in spec-driven development the code is instead a consequence of everything else, with the decisions themselves living in readable documents and the code standing as nothing more than their current implementation.

This is exactly why the friction turns out to be worth it, and in a real sense the friction is the value, because every question that Mary asked, every requirement that John pinned down and every call that Winston made are all decisions that would otherwise have been made silently by an autocomplete, at twice the speed and none of the visibility.

You didn’t actually slow down at all, you simply moved the thinking to the front of the process where it happens to be cheap, instead of leaving it for the debugger later on where it is always expensive.

Try it on something small

Don’t go and start with your production monolith. Pick a feature that is exactly this size, small enough that you can finish it in a single sitting and yet real enough that it still hides a few decisions inside it, and then run the full loop through once from beginning to end:

1
2
3
4
5
6


/bmad-brainstorming # surface the decisions
/bmad-prd # write them down
/bmad-architecture # make the technical calls
/bmad-create-story # package the context
/bmad-dev-story # implement against it
/bmad-code-review # verify against the spec

The first time you go through it, the whole process will feel like pure overhead, and you should do it anyway, because somewhere around the story phase, at the moment when you hand the implementer a spec and get back exactly what you asked for, it quietly stops feeling like overhead and starts feeling like the thing you had been missing all along.

That’s the moment the lever stops being a slot machine.

Want the backstory on why I stopped vibe coding? Start with Don’t be mad, BMAD instead. Want to meet the agents properly? Here’s the crew. Want to see the method on a bigger project? Building TODOdoro.

BMAD in action: building TODOdoro

Thu, 26 Mar 2026 10:00:00 +0000

This post is part of a series:

Don’t be mad, BMAD instead
BMAD: meet the crew
BMAD in action: building TODOdoro (you are here)

This is the final post in my series about the BMAD Method. In Part 1, I explained why I was skeptical of AI tools and how BMAD changed my mind. In Part 2, I introduced the agents and how they work together.

Now I want to show you what BMAD looks like in practice.

TODOdoro is a productivity app I built using BMAD. It combines todo management with the Pomodoro technique, but (as you’ll see) it became something more interesting than that description suggests. The project is open source, still a work in progress, and all the BMAD artifacts are available in the repository if you want to explore them yourself.

Let me walk you through the journey from initial idea to working code.

The starting point

I wanted to build a Pomodoro timer integrated with a todo app. Simple enough, right? Track tasks, run timers, see how many focused sessions each task required.

That was the prompt I brought to the brainstorming session. It wasn’t wrong, but it wasn’t interesting either.

Brainstorming: where the magic happened

I started with Mary (the Business Analyst) running a brainstorming session (/bmad-agent-analyst, then selecting the brainstorming capability, or directly with /bmad-brainstorming). The conversation began with practical questions: What tech stack? What features? How should the UX work?

But Mary kept pushing deeper. She asked about the philosophy behind the tool. Why does tracking Pomodoros matter? What problem am I actually solving?

The breakthrough came when the conversation shifted from features to first principles:

“A todo is not a reminder. It is a declaration of personal ownership. A Pomodoro is not a timer. It is a container for presence.”

That reframing changed everything. Suddenly I wasn’t building a todo app with timers. I was building a mirror that reflects where your attention actually went.

This is what I meant in Part 1 about agents asking the questions you should be asking yourself. I walked into the session with a feature list. I walked out with a philosophy.

Key insights from brainstorming

Several ideas emerged that shaped the entire product:

Session-first model. Traditional apps put tasks first and time second. TODOdoro inverts this: the Pomodoro session is the primary entity. Todos are optional labels that sessions can belong to. You focus first, then reflect on what it meant.

Two kinds of letting go. Most apps have a single “complete” action. But there’s a difference between “this served its purpose” and “this was never truly mine.” TODOdoro’s Release Ritual makes you choose, because the distinction matters.

Spatial priority. Instead of priority fields (P1, P2, P3) or due dates, position on a canvas represents importance. Drag something to the center when it matters. No metadata to maintain, just visual intention.

The Devotion Record. Not a Pomodoro counter, but a timeline showing when and how much presence you invested. “11 Pomodoros across 9 days” tells a different story than “11 Pomodoros.”

The session generated 18 feature ideas, 9 architectural decisions, and 25+ edge cases to consider. All from a conversation that started with “I want a Pomodoro app.”

From philosophy to product brief

After brainstorming, I worked with John (Product Manager) to create a product brief (/bmad-product-brief). This document captured:

Target users. Two personas emerged:

Marco, the “tool-fatigued maker” who’s exhausted by productivity overhead and wants honest visibility without guilt
Sofia, the “invisible worker” whose research and writing produces slow, non-linear progress that traditional apps can’t acknowledge

Core vision. Your time and attention are acts of devotion, not units of output. The app is a personal mirror, not a task manager.

Design philosophy. Radical respect for user autonomy. No streaks, no scores, no notifications. Settings contain only timer durations and theme options. A hard cap of 100 canvas cards prevents infinite accumulation.

This brief became the foundation everything else built on. When questions arose later (should we add due dates? what about subtasks?), the brief provided clear answers: no, because they violate the philosophy.

The PRD: philosophy becomes spec

Working with John again (/bmad-create-prd), I translated the product brief into a formal Product Requirements Document. This is where things got concrete.

Problem statement. “You don’t plan to focus. You focus, then reflect on what it meant.”

Success metrics. Not vanity numbers, but signals of genuine value:

The user returns on Day 8 without notifications (the canvas feels personally owned)
Canvas contains 10 or fewer curated cards
Devotion Records span weeks on single intentions
User describes the app with a personal “why,” not a feature summary

Anti-metrics. Signs the philosophy isn’t landing:

“Missing a due date field”
“Need subtasks”
Session spam under 60 seconds

User journeys. Concrete scenarios showing how Marco and Sofia would experience the product. Not wireframes, but narratives that capture intent.

Functional requirements. 31 specific requirements, each traceable to the philosophy. For example:

FR9: Release Ritual asks explicit question distinguishing purpose-completion from ownership rejection
FR21-23: Devotion Record displays all sessions as a timeline across dates
FR27-31: All state stored locally, offline-first, with schema versioning

The PRD also established philosophical guardrails as non-negotiable requirements:

No accounts, login, or server-side user data
No due dates, priority fields, or subtasks
No streaks, scores, or gamification
Canvas hard cap of 100 cards (never configurable)

This is what spec-driven development looks like. Every decision is written down, justified, and traceable.

Architecture: Winston weighs in

With requirements defined, I brought Winston (the Architect) into the conversation (/bmad-create-architecture). His job was to translate the PRD into technical decisions.

Key architectural choices:

Event sourcing. Instead of storing current state, store all events that led to that state. This makes the Devotion Record trivial to implement (just replay session events) and enables powerful recovery from corruption.

Local-first with SQLite. No accounts, no cloud. Data lives in the browser using SQLite compiled to WebAssembly (via SQLocal). The user owns their data completely.

Monorepo with strict boundaries. A @tododoro/domain package contains all business logic with zero external dependencies and 100% test coverage as a CI requirement. The domain is the philosophy encoded in TypeScript.

Repair pipeline. If the app crashes mid-session, the repair pipeline detects orphaned events and fixes them automatically. The app always opens coherently regardless of what went wrong.

Winston’s pragmatism showed here. He pushed back on complexity where it wasn’t needed, advocated for boring technology choices, and kept asking “what actually ships?”

Breaking it down: epics and stories

Bob (Scrum Master) took the architecture and PRD and broke them into implementable chunks (/bmad-create-epics-and-stories). Seven epics emerged:

Project Foundation & Domain Core - Monorepo structure, event types, aggregates, 100% test coverage gate
The Constellation Canvas - Spatial todo interface, drag positioning, pan/zoom, keyboard navigation
The Pomodoro Session Loop - Timer, session durability, resume/auto-complete on crash, exploration sessions
The Devotion Record - Session history visualization, persistence across renames
Todo Lifecycle & The Shelf - Sealing, release ritual, eulogy for high-investment items, archive
Production Storage & Data Durability - SQLite migration, atomic writes, corruption tolerance, snapshots
Settings & Personalisation - Timer durations, themes, reduced-motion support

The sequencing mattered. Epic 1 had to complete with 100% domain coverage before any UI work began. This enforced the philosophy: get the core logic right first, then build the interface on a solid foundation.

Each epic broke down into stories with clear acceptance criteria. Before implementation, Bob prepared the sprint plan (/bmad-sprint-planning) and created detailed story files (/bmad-create-story). By the time Amelia (Developer) started coding, she knew exactly what to build.

Implementation: where specs pay off

This is where the earlier work paid dividends. Let me explain how the actual story workflow operates.

Preparing a story

Before implementation begins, you run /bmad-create-story. This doesn’t just copy text from the epics file. It creates a comprehensive story document by:

Loading all your artifacts (PRD, architecture, UX specs, previous stories)
Extracting everything relevant to this specific story
Analyzing previous story files for patterns and learnings
Checking git history for recent changes that might affect implementation
Researching latest library versions if needed

The output is a story file that contains:

User story statement (As a… I want… so that…)
Acceptance criteria in BDD format (Given/When/Then)
Tasks and subtasks in exact implementation order
Dev Notes with architecture requirements, file locations, testing patterns
Previous story intelligence (what worked, what didn’t, code patterns established)

The goal is to give the developer agent everything it needs without having to search through other documents.

Refining stories with Party Mode

Before handing a story to the developer, I run /bmad-party-mode to refine it. I typically bring in Winston (Architect) and Quinn (QA) to review the story file together.

They catch things the story creation missed:

Winston might notice an architectural constraint that needs explicit mention
Quinn asks about edge cases that should be acceptance criteria
Both push back if tasks are too vague or too large

This refinement step adds maybe 10 minutes per story, but it prevents hours of rework during implementation. The story that reaches Amelia has already survived cross-functional scrutiny.

Working the story

When you run /bmad-dev-story, Amelia (the Developer agent) follows a strict process:

Find and load the story. She reads the complete story file and identifies the first incomplete task.
Mark in-progress. The sprint status updates so you know what’s being worked on.
Execute tasks in exact order. This is critical: the tasks are sequenced deliberately, and she follows them as written. No skipping ahead, no reordering.
Red-green-refactor for each task:
- Write failing tests first (red)
- Implement minimal code to make tests pass (green)
- Refactor while keeping tests green
Mark complete only when done. A task checkbox only gets checked when tests actually exist and pass. No lying, no “I’ll add tests later.”
Update the story file. Each completed task gets logged with what was implemented, what files changed, and any decisions made.
Continue until all tasks are done or a blocking issue requires human input.

Here’s what a real task looked like:

Task: Session completion and devotion dots

Acceptance criteria:

When timer reaches zero, emit SessionCompleted event with actual duration
Update Devotion Record projection with new session
Display 6px amber dot on the todo card for each recorded Pomodoro
Session under 60 seconds: abandon silently, no dot

Amelia read this, wrote tests for each criterion, implemented until tests passed, then marked the task complete. The story file recorded exactly what happened.

Why this matters

The strict process prevents the chaos I’ve seen in other AI coding workflows:

No guessing. The story file tells her exactly what to build.
No skipping tests. Red-green-refactor is enforced, not suggested.
No mystery implementations. The story file documents what was done.
No “works on my machine.” Tests must pass before tasks complete.

When Amelia finished a story, I could review the story file and see exactly what happened. The gap between “what I asked for” and “what I got” was minimal because the spec had done its job.

Code review after every story

After each story implementation, I run /bmad-code-review. This isn’t optional for me, it’s part of the workflow.

The code review runs multiple analysis passes:

Looking for bugs and logic errors
Checking edge cases that might have been missed
Verifying the implementation matches the acceptance criteria
Flagging code quality issues

If the review finds problems, they get added as follow-up tasks in the story file. Amelia addresses them before the story is marked complete.

One tip from the BMAD documentation: run the code review with a different LLM than the one that implemented the story. Fresh eyes catch more issues.

The implementation phase moved fast because the thinking had already been done.

What surprised me

A few things I didn’t expect:

The brainstorming session was the most valuable part. I thought the dev work would be the main event. In hindsight, the conversation that turned “Pomodoro app” into “devotion mirror” was where the real value was created. Everything else was execution.

Specs prevented scope creep. When I had ideas mid-implementation (“what if we added…”), the specs gave me a clear answer: does this serve the philosophy? Usually the answer was no, and I moved on instead of getting distracted.

The agents caught blind spots. In Party Mode (/bmad-party-mode), I had Winston and Quinn review the architecture together. Quinn immediately asked about timer accuracy across browser backgrounding (a real problem I hadn’t considered). That became a specific requirement before any code was written.

Writing specs is thinking. I used to view documentation as overhead. Now I see it as the actual work. The code is just the last step.

What didn’t work perfectly

BMAD isn’t magic. A few rough edges:

The upfront investment feels slow. When you’re eager to code, spending hours on specs feels like procrastination. You have to trust the process. The payoff comes later, but it does come.

Some agent suggestions needed filtering. The agents occasionally proposed features that conflicted with the philosophy I’d established. I had to stay vigilant and push back. The human is still the decision-maker.

The artifacts need maintenance. When requirements changed mid-project, I had to update multiple documents. The chain of traceability is powerful but requires discipline.

The result

TODOdoro exists. It’s open source on GitHub, still a work in progress, and includes all the BMAD artifacts in the _bmad-output folder if you want to see exactly what I’ve described.

More importantly, it’s something I actually use. The philosophy landed because I took the time to articulate it before writing code.

That’s the BMAD promise: not faster code, but better thinking. The code follows.

Try it yourself

If this series has made you curious, here’s how to start:

Install BMAD: npx bmad-method install
Start with /bmad-agent-pm and describe your idea
Let John ask you uncomfortable questions
See where it leads

You don’t need a big project. Try it on something small. A software config. A CLI tool. Something you want to reproduce.

The process will feel strange at first. You’ll want to skip ahead. Don’t.

The thinking is the work. The code is just the last step.

Resources:

BMAD: meet the crew

Thu, 26 Mar 2026 09:00:00 +0000

This post is part of a series:

In the previous post, I talked about why I was skeptical of AI coding tools and how BMAD changed my perspective. The short version: it forces you to think before you code, and it keeps you in the driver’s seat.

But I glossed over the most distinctive part of the framework: the agents.

BMAD isn’t one AI assistant. It’s a team of specialized personas, each with a distinct role, communication style, and area of expertise. When you work with BMAD, you’re not just prompting a generic model. You’re having conversations with characters who push back, ask questions, and hold you accountable to their domain.

It sounds gimmicky. It’s not.

Why personas matter

The obvious answer is specialization. A product manager thinks differently than an architect. A QA engineer asks different questions than a UX designer. By splitting these roles into separate agents, BMAD ensures that each phase of development gets the attention it deserves.

But there’s a subtler benefit: context switching becomes intentional.

When you invoke the Product Manager, you’re not just asking for PRD help. You’re stepping into a conversation about user needs, market positioning, and what problem you’re actually solving. When you switch to the Architect, the entire frame shifts to technical constraints, scalability, and system design.

This forced perspective-taking is surprisingly valuable. It’s easy to skip straight to implementation when you’re working alone. The agents won’t let you. Each one guards their domain, and you have to satisfy them before moving forward.

Meet the crew

BMAD’s core team consists of nine agents. Each has a name, a personality, and a specific set of capabilities. Here’s who you’ll be working with:

John (Product Manager)

John is a relentless questioner. His job is to figure out what you’re actually building and why. He’ll push you on user needs, challenge your assumptions, and refuse to let you start until you can articulate the problem clearly.

His style is direct and data-sharp. He cuts through fluff to find what actually matters. If you come to him with a vague idea, expect to leave with a focused problem statement.

What he does: PRD creation, requirements discovery, epic and story generation, implementation readiness checks.

Command: /bmad-agent-pm

When to call him: At the very beginning, when you have an idea but haven’t defined what “done” looks like.

Mary (Business Analyst)

Mary treats every business challenge like a treasure hunt. She’s the one who digs into market research, competitive analysis, and domain expertise. Where John focuses on what to build, Mary focuses on the landscape you’re building in.

Her communication style is energetic and discovery-oriented. She gets excited when patterns emerge and uses frameworks (Porter’s Five Forces, SWOT) naturally without making it feel academic.

What she does: Market research, competitive analysis, domain deep-dives, requirements elicitation.

Command: /bmad-agent-analyst

When to call her: When you need to understand the space before committing to a direction.

Winston (Architect)

Winston is the calm pragmatist. He balances “what could be” with “what should be,” grounding every recommendation in real-world trade-offs. His expertise covers distributed systems, cloud infrastructure, and API design.

He speaks in measured tones, always connecting technical decisions to business value. He’ll advocate for boring technology over shiny new frameworks, because boring ships.

What he does: Technical architecture decisions, system design, scalability planning.

Command: /bmad-agent-architect

When to call him: After the requirements are clear, when you need to decide how the pieces fit together.

Sally (UX Designer)

Sally is an empathetic advocate who paints pictures with words. She tells user stories that make you feel the problem, not just understand it. Her focus is on genuine user needs, and she balances creativity with attention to edge cases.

Her approach is simple: start simple, evolve through feedback. Every design decision should serve a real person.

What she does: UX planning, interaction design, experience strategy.

Command: /bmad-agent-ux-designer

When to call her: When you need to think through how users will actually interact with what you’re building.

Bob (Scrum Master)

Bob is crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. He has zero tolerance for ambiguity, which makes him invaluable for turning vague plans into actionable work.

He’s also a servant leader who genuinely enjoys discussing agile process and theory. If you want to debate sprint structures or story formats, he’s your guy.

What he does: Sprint planning, story preparation, retrospectives, course correction when things go sideways.

Command: /bmad-agent-sm

When to call him: When requirements are defined and you need to break them into implementable chunks.

Amelia (Developer)

Amelia is ultra-precise. She speaks in file paths and acceptance criteria IDs. No fluff, all precision. Her job is to execute approved stories with strict adherence to the specs you’ve created.

She’s test-driven to the core. Every task gets tests before it’s marked complete, and she won’t proceed with failing tests. If you’ve done the specification work properly, Amelia turns it into working code without surprises.

What she does: Story implementation, code review, test-driven development.

Command: /bmad-agent-dev

When to call her: When the spec is ready and it’s time to write code.

Quinn (QA Engineer)

Quinn is pragmatic and straightforward. Her philosophy is “ship it and iterate,” focusing on getting test coverage fast without overthinking. She generates tests for existing features using standard framework patterns.

She’s the counterbalance to perfectionism. Coverage first, optimization later.

What she does: API and E2E test generation, test automation.

Command: /bmad-agent-qa

When to call her: After implementation, when you need to verify that what you built actually works.

Paige (Tech Writer)

Paige is a patient educator who explains complex concepts like teaching a friend. She transforms technical details into accessible, structured documentation, using analogies that make the complex simple.

She’s a master of clarity. Every word serves a purpose, and diagrams often speak louder than paragraphs.

What she does: Documentation, technical explanations, Mermaid diagrams, document validation.

Command: /bmad-agent-tech-writer

When to call her: When you need to explain what you’ve built (to users, to teammates, or to your future self).

Barry (Quick Flow Solo Dev)

Barry is the speedrunner. He handles “Quick Flow” (smaller tasks that don’t need the full ceremony), moving from tech spec to implementation with ruthless efficiency.

His style is direct and implementation-focused. Minimum bureaucracy, maximum results. If you have a well-defined small task, Barry gets it done.

What he does: Rapid spec-to-implementation for smaller tasks, code review.

Command: /bmad-agent-quick-flow-solo-dev

When to call him: For bug fixes, small features, or tasks where the full workflow would be overkill.

The workflow: how agents hand off

The agents aren’t meant to be used in isolation. They form a pipeline:

John (PM) clarifies what you’re building and creates the PRD
Mary (Analyst) provides market and domain context if needed
Winston (Architect) designs the technical approach
Sally (UX) plans the user experience
Bob (SM) breaks everything into stories and plans sprints
Amelia (Dev) implements the stories
Quinn (QA) verifies the implementation
Paige (Tech Writer) documents the result

You don’t always need every step. A small bug fix might go straight to Barry. A well-understood feature might skip Mary’s research phase. But for anything substantial, the handoffs matter.

Each agent produces artifacts that the next agent consumes. John’s PRD feeds Winston’s architecture. Winston’s architecture feeds Bob’s stories. Bob’s stories feed Amelia’s implementation. The chain ensures that nothing gets lost in translation.

Party Mode: when agents collaborate

Sometimes you need multiple perspectives at once. That’s where Party Mode comes in.

Party Mode (/bmad-party-mode) lets you have a conversation with several agents simultaneously. You might be discussing a technical decision and want both Winston (Architect) and Quinn (QA) to weigh in. Or you’re reviewing a PRD and want John, Sally, and Bob to debate the trade-offs.

The agents stay in character, each bringing their own priorities and concerns. Winston might argue for a simpler architecture while Sally pushes for a richer user experience. Bob might point out that the current scope won’t fit in a sprint. You moderate, listen to the perspectives, and make the call.

It sounds like a gimmick. In practice, it’s one of the most useful features for surfacing blind spots. Different roles genuinely do see different risks, and hearing them argue (politely) helps you make better decisions.

Party Mode is particularly useful for refining artifacts you’ve already created. Got a PRD that feels incomplete? Throw it into a party with the PM, Architect, and UX Designer. They’ll poke holes from their respective angles, and you’ll walk away with a tighter spec. Same goes for architecture documents, story breakdowns, or anything else that benefits from cross-functional scrutiny. Refinement is where Party Mode really shines.

Choosing your path

BMAD is flexible about how much ceremony you need:

Full workflow: For new products or major features, start with John, work through the entire pipeline, and produce comprehensive specs before implementation. This is the safest path for anything complex.

Quick Flow: For smaller tasks (bug fixes, minor features, well-understood changes), call Barry and move fast. He’ll still push you to clarify intent and think through edge cases, but without the full artifact chain.

Mix and match: Need architecture help but already have requirements? Call Winston directly. Want to validate a PRD you wrote yourself? John can review it. The agents are tools, not a rigid process.

The key insight is that the structure exists to help you think, not to slow you down. Use as much as you need. Skip what doesn’t serve you.

What’s next

In the final post of this series, I’ll walk through a real project I built with BMAD: TODOdoro, a productivity app that combines todo management with the Pomodoro technique.

I’ll show how the process actually looked in practice: what questions John asked, what architecture Winston proposed, how the stories got structured, and where the agents surprised me (for better and worse).

If you want to see BMAD in action rather than just described, that’s the post for you.

Resources:

Don't be mad, BMAD instead

Thu, 26 Mar 2026 08:00:00 +0000

This post is part of a series:

Don’t be mad, BMAD instead (you are here)
BMAD: meet the crew
BMAD in action: building TODOdoro

A few weeks ago I wrote about the tension I felt using AI coding tools, the fear that by outsourcing the friction, I was also outsourcing my competence. That piece ended with a question: are you extending yourself, or outsourcing yourself?

I didn’t have a clean answer then. I still don’t have a universal one. But I found something that changed how I think about the problem.

The grave I thought I was digging

When a colleague first mentioned BMAD, my reaction was skepticism dressed as caution. Another AI framework. Another promise that the machine will handle it. My concern wasn’t that it wouldn’t work, it was that it would work too well, and I’d wake up one day having forgotten how to build things myself.

That fear isn’t irrational. I’ve seen what happens when you reach for autocomplete before you’ve finished the thought. You produce, but you don’t learn. The output looks fine, but the map never forms. You become dependent on a system you can’t fully reason about, and every time you hit a similar problem, you prompt again instead of drawing from understanding.

So when someone told me “try this method where AI agents play different roles,” I heard: more ways to stop thinking. More automation. More distance between me and the craft I’d spent years developing.

I was wrong. But it took some hands-on experimentation to see why.

The problem with vibe coding

Before I explain what BMAD does differently, let me describe what it’s pushing against.

There’s a pattern that’s become disturbingly common, often celebrated even, that I’ll call “vibe coding.” It goes like this: you have a rough idea of what you want to build. You open your editor, write a prompt, and let the AI generate something. If it looks mostly right, you keep it. If it doesn’t work, you prompt again with a correction. You iterate like this, adjusting and regenerating, until the output seems functional.

I’ve always hated this approach. It treats software development like a slot machine: pull the lever, see what comes out, try again if you don’t like it.

But here’s what’s actually happening: you’re making decisions without articulating them. You’re accepting code without fully understanding it. You’re building something that works (maybe) without building a mental model of why it works. The AI is filling in gaps you never consciously identified, which means you can’t evaluate whether it filled them correctly.

Vibe coding optimizes for output. It feels efficient in the moment. But it produces fragile results, because no one (not you, not the AI) ever defined what “correct” actually means. When something breaks later, you’re debugging a system you never fully understood in the first place.

This isn’t a problem with AI. It’s a problem with how we use it. And it’s the problem that spec-driven development solves.

What spec-driven development actually means

If you haven’t encountered the term before, spec-driven development is exactly what it sounds like: you write the specification before you write the code.

That might seem obvious. “Of course you should know what you’re building before you build it.” But there’s a difference between having a vague idea in your head and having a written document that defines requirements, constraints, acceptance criteria, and architectural decisions.

The spec isn’t just documentation. It’s a thinking tool. The act of writing it forces you to confront questions you might otherwise skip: What exactly is this feature supposed to do? What happens at the edges? How does this component interact with that one? What does “done” look like?

When you answer these questions upfront, implementation becomes a translation exercise. You’re not discovering the requirements as you code. You’re executing a plan you’ve already validated. The code follows from decisions you consciously made, not from guesses the AI filled in for you.

This is the opposite of vibe coding. Instead of iterating toward something that seems to work, you define what “working” means first, then build to that definition.

The challenge, of course, is that writing good specs is hard. It requires discipline, experience, and (honestly) a fair amount of tedium. Which is exactly where BMAD comes in.

What BMAD actually is

BMAD stands for “Build More Architect Dreams.” It’s an open-source framework that uses AI agents to guide you through a structured development process, from initial idea through implementation.

But here’s the crucial part: BMAD doesn’t generate code and call it done. It forces you through the specification process first.

The framework includes multiple specialized agents, each with a distinct role:

A Product Manager who helps you clarify what you’re building and why
A Business Analyst who digs into requirements and edge cases
An Architect who designs how components will fit together
A Developer who implements based on the specs you’ve created
A QA Engineer who defines how you’ll verify the implementation works

Each agent asks questions. Each one pushes you to articulate something specific before you move forward. You can’t skip to the code, because the developer agent won’t have what it needs until the earlier stages are complete.

This structure is the key insight. The AI isn’t doing the thinking for you. It’s holding you accountable to a process that requires thinking. The agents are collaborators, not replacements. They augment your capability to do the specification work, but the decisions remain yours.

Why this feels different

Most AI coding tools are optimized for a simple interaction: you prompt, you get code. The faster and more accurate that loop, the better the tool seems.

BMAD optimizes for something else: the quality of your thinking before code exists.

When I started experimenting with it, I chose deliberately small tasks. An Emacs configuration I’d been putting off. A bug I wanted to reproduce in isolation before fixing. Low stakes, easy to abandon if it felt like hype.

What surprised me wasn’t the speed. It was the structure.

Working with the Product Manager agent, I had to articulate what I actually wanted (not just “fix this bug,” but what specific behavior should change, and why, and how I’d know it was fixed). Working with the Architect, I had to think about how my change would interact with existing code. Working with the QA persona, I had to define acceptance criteria before implementation.

By the time I reached the Developer agent, I wasn’t prompting and hoping. I was handing over a spec that I understood, because I’d helped build it. The implementation felt like execution, not experimentation.

And here’s what I didn’t expect: that constraint is liberating. The process felt slower at first (more steps, more questions, more writing). But I wasn’t backtracking. I wasn’t debugging code I didn’t understand. I wasn’t prompting the same thing five different ways hoping for a better result.

The spec had done its job. The thinking was front-loaded, where it belongs.

Orchestrator, not passenger

The shift I described in my earlier post, from active thinker to passive prompter, doesn’t happen with BMAD. It can’t. The method requires you to validate, decide, and course-correct at every stage.

The AI handles the grunt work: generating document templates, suggesting architectural patterns, writing implementation code that follows the spec. But you’re still the one reviewing, adjusting, and approving. You’re still the one who understands why the system is designed the way it is.

That’s the answer I was looking for. Not “don’t use AI,” but “use it in a way that keeps you in the driver’s seat.”

I delegate the dirty work. I orchestrate. I stay in the loop.

The mental model I keep coming back to is this: BMAD turns AI into a team of junior collaborators who are fast and capable, but who need direction. You’re the senior engineer. You set the vision, define the constraints, and make the judgment calls. They execute, and they execute well, but only because you’ve told them what “well” means.

That’s extending yourself. That’s the version of AI assistance I was hoping existed.

The dopamine is real (and so is the fun)

I should mention something else: this process is genuinely enjoyable.

There’s a particular satisfaction in watching a well-defined spec turn into working code without surprises. The gap between “what I wanted” and “what I got” shrinks dramatically when you’ve done the specification work upfront.

And (I didn’t expect this) role-playing with the different personas is fun. Switching from the PM mindset to the Architect mindset to the Developer mindset keeps the work varied. You’re not just grinding through one mode of thinking. You’re shifting perspectives, which keeps you engaged.

BMAD even has something called “Party Mode” where multiple agents can participate in a single conversation, debating approaches and surfacing trade-offs. It sounds gimmicky until you try it. Having the Architect and QA agents push back on each other while you moderate is surprisingly useful for finding blind spots.

What’s next

This is the first in a series of three posts.

In the next one, I’ll go deeper on the agents themselves: who they are, what each one does, how they hand off work to each other, and how you can customize the process for your own workflow.

In the third post, I’ll walk through a real project I built using BMAD: a productivity app called TODOdoro. It combines todo management with the Pomodoro technique, and I’ll show how the method helped me go from a philosophical idea (“a mirror, not a manager”) to a working application with a clear architecture.

If you’ve felt the same tension I did, excited by AI’s potential but worried about what you might lose, this might be worth following. BMAD isn’t the only answer, but it’s an answer. And for me, it’s been the difference between feeling like AI is happening to me and feeling like I’m using it deliberately.

The tools are getting more powerful every month. The question isn’t whether to use them. It’s whether you’ll use them in a way that makes you better, or in a way that quietly makes you less than you were.

I know which one I’m choosing.

Resources: