DEV Community: Tiziano Basile

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

Tiziano Basile — Fri, 07 Aug 2026 11:36:08 +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.

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:

/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:

## 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:

/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.

/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:

### 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:

/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:

/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:

### 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.

/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:

# 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:

/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.

/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:

-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

/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:

/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.

The year I stopped writing code for fun

Tiziano Basile — Sat, 01 Aug 2026 10:29:01 +0000

Disclaimer: Opinions expressed are solely my own and do not express the views or opinions of my employer

Somewhere in the last six months I stopped opening my editor on a Sunday, and I don't mean the work one, I mean the other one, the editor where the projects nobody asked for live.

There was no burnout and no crisis, nothing you could point at and name, which is exactly why it took me so long to notice at all. Work was good and busy in the way that good work is busy, reviews went fine, features landed, and every metric that measures a software engineer from the outside was pointing up and to the right, so this isn't a story about a job or a team or a workload, and on that front I've been lucky and I still am. Nothing was wrong, something was just gone.

The symptom I ignored

Orgsidian (one of my side projects) sat untouched for months, which on its own means nothing, because side projects die all the time and dying is most of what side projects actually do. What was different this time is that I never decided to stop, because there was no evening where I sat in front of it and thought "this isn't going anywhere", I simply didn't open it, first for a couple of weeks and then for a great deal longer than that.

And when I finally did open it again, the first thing I felt wasn't curiosity about where I'd left off, it was the urge to catch up, to drag the thing back into a state where it was worth having, which isn't the same as wanting to build something and is really just wanting to close a gap.

I told myself I was tired, and maybe it really was just a full stretch of life with more responsibilities than I used to have and less spare attention to spread around them, and reasonable explanations like that were available so I took them, because they were true enough to hold.

Shipping more, enjoying it less

I want to be careful here, because the lazy version of this story is a complaint about AI making the code worse, and that isn't the story I have. The code was fine, most of it is still running, and if you'd asked me during that year whether the tooling was worth it I'd have said obviously yes, and I'd have been right.

What I remember about writing it is nothing. There's no afternoon attached to any of it, no wrong turn I took first, no moment where it clicked, not one detail I could tell you now without going back to look it up, so it exists and my name is on the commits and it left no trace in me whatsoever.

That kept happening, and it wasn't only happening on the clock, it happened just as much on the things I was building for myself, which is the part that should have bothered me a lot sooner than it did.

The pleasure was in the session, not the artifact

Here's what I think I had wrong the whole time: I assumed that what I liked was building things, objects, repos, features, deployed URLs with my name somewhere behind them. I don't think that was ever really it. What I liked was the two hours.

You know the ones I mean. You have a rough idea and no plan, the obvious approach turns out to be wrong in some interesting way, you end up reading the source of a dependency because the docs won't tell you the one thing you actually need to know, and then you look up and it's dark outside and you've got maybe twenty lines to show for the entire evening, and you feel great about it.

AI is very good at compressing exactly that, and it's supposed to be, because optimising for the artifact is the entire product and nobody is hiding it. But when the artifact turns up without the two hours attached to it, you end up with everything you said you wanted and none of the thing you were actually there for.

I wrote about the other half of this a few months ago in AI and the Craft, the half about what you trade away when you let the tool do the thinking for you, and that half is much easier to talk about, because saying you understand your own systems less sounds serious while saying you're not having fun sounds like whining.

It isn't whining, though, it's the reason I have this career in the first place. I didn't arrive here through a plan, I arrived because at fifteen I found this more interesting than anything else on offer, and that kid is why I'm any good at the job now, and nobody was paying him to be interested. Whatever keeps him around seems worth maintaining on purpose, the same way you'd maintain anything else you depend on.

So I'm starting a project with the AI switched off

Not as a protest but as an experiment, with a single question sitting behind it, which is whether the thing I lost is actually gone or has just been crowded out.

The rules are deliberately dumb, because clever rules turn into a system you end up maintaining instead of a project you actually build.

No chat and no agents. I'm not disabling autocompletion, because it's genuinely useful and pretending I'd give it up would turn the whole thing into a performance, but what stops is opening the chat panel to do my thinking for me.
Docs are fine, reading the source of my dependencies is better than fine and actively encouraged, and searching and forums are fine too.
No deadline, no roadmap and no launch, because if it never ships the experiment has still run.
One hour at a time, usually at the weekend, and the session is the unit, not the milestone.

That last one is the whole point, because if the session is the unit then an hour spent reading with nothing committed at the end of it still counts, whereas under the old accounting that hour was simply wasted.

What I expect to go wrong

I haven't started yet, and this is the last thing I'm writing before I do, so everything below is a guess, and guesses about your own future behaviour are worth roughly what you'd expect them to be worth.

The one I'm most confident about is the reaching. I know that reflex is there because I caught it earlier this year with autocomplete, opening a file and then waiting for the suggestion before I'd finished deciding what I wanted, so I don't think the first thing I notice will be the slowness, I think it'll be my hand going for the shortcut the way you reach for your phone in a lift. And it won't happen on the hard parts either, it'll happen on the small annoying ones, because the reflex has very little to do with difficulty and a great deal to do with not wanting to sit inside a pause.

Then the slowness, which will be real and which I'm not going to dress up as something it isn't. Some of it is just dull, because reading a changelog to find one flag isn't craft, it's admin, and doing it by hand doesn't make it noble.

And then the likeliest outcome of all, which is that I do two or three sessions and quit, not dramatically, but in exactly the way Orgsidian ended, by not being opened. If that's what happens I'll write that one down too, which is a much easier promise to make now, while I still think it's unlikely.

What I'm not claiming

This isn't an argument, it's one person and one project that hasn't even started yet.

I haven't stopped using AI, I use it at work every day and I do it on purpose and I'd defend that, because refusing a tool that demonstrably works just because using it feels bad is superstition, and shipping is still the job.

I'm not telling you to try this either. There's a version of this post that ends in five bullet points about reclaiming your craft and I'd rather not write it, partly because I don't know that any of this generalises and partly because I don't know yet whether it'll work on me.

I'm also fairly suspicious of the nostalgia running through all of this, because it's very easy to mix up "coding was more fun before AI" with "coding was more fun when I was younger and had fewer responsibilities", and some of what I've described here is probably the second one wearing the costume of the first, and since I can't separate them cleanly I'm not going to pretend that I can.

What I'll say instead is narrower than all of that. What I lost wasn't skill and it wasn't time, it was the part of the work that happens while you're doing it, and that turns out to be the part I was in it for.

The trap I can already see

There's one failure mode worth naming now, while it's still theoretical, and it's that the pleasure quietly relocates, so that six months from now the good feeling starts arriving from writing about the sessions rather than from the sessions themselves, which would be the same substitution I've just spent an entire post describing, one level up, except that this time the artifact is the post.

From the outside that would look identical to this going well, with output and consistency and a growing body of work to point at, and you'd only ever catch it from the inside, and probably late.

So, for the record, the sessions are the project, and this is a note about them written before the first one.

BMAD in action: building TODOdoro

Tiziano Basile — Mon, 20 Apr 2026 06:51:18 +0000

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

Tiziano Basile — Mon, 20 Apr 2026 06:00:00 +0000

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:

Crossposting without the copy-paste: a GitHub Action from Hugo to dev.to

Tiziano Basile — Sat, 18 Apr 2026 13:21:57 +0000

My blog runs on Hugo. I also recently discovered I can cross-post to dev.to, because that's where a lot of the conversation actually happens. For a while, my workflow was the obvious one: write the post, publish it here, open dev.to, paste it in, fix the frontmatter, fix the links, hit publish.

It worked. I also stopped doing it after the second post.

Copy-paste friction is the kind of chore that silently kills a publishing habit. So I did what most developers do when a task becomes repetitive: I automated it. And then I kept refining the automation until it was worth giving away.

The result is basteez/hugo-to-devto-action, now published on the GitHub Marketplace.

What it does

It's a composite GitHub Action. On every push to your blog repo, it looks at what changed in the push range, finds new Hugo posts under your content/post directory, and creates a corresponding draft on dev.to for each one that is marked draft: false locally.

Key behaviours, chosen deliberately:

Drafts, not published posts. The action never hits publish on dev.to for you. It mirrors content, but you stay in control of when it goes live on the other platform. This is intentional: dev.to has its own audience, its own timing, and its own editorial choices (cover image, tags, canonical URL). I want a starting point there
Dedup by title. Before creating a draft, the action queries your dev.to account and skips anything whose title already exists. That means you can safely re-run on any push without ending up with duplicates, and editing a post on dev.to directly doesn't get overwritten.
Push-range aware. It uses git diff across github.event.before..github.event.after to find what actually changed, rather than scanning the whole repo every time. New posts get mirrored; edits to old posts don't trigger spurious drafts.
Stateless. There is no database, no cache, no state file in your repo. dev.to is the source of truth for "does this already exist?" If you ever want to start fresh, you can.

Using it

The minimum viable workflow is about fifteen lines:

name: Crosspost to dev.to

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  crosspost:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: basteez/hugo-to-devto-action@v1
        with:
          devto-api-key: ${{ secrets.DEVTO_API_KEY }}
          before: ${{ github.event.before }}
          after: ${{ github.event.after }}

Two things to watch for:

fetch-depth: 0 is not optional. The default shallow checkout doesn't contain the before SHA of a real push, so git diff has nothing to compare against. If you leave this out, the action will fail quickly and loudly. That failure mode is well understood; don't go hunting for a mysterious bug.
DEVTO_API_KEY lives in repo secrets. Grab a Personal API Key from dev.to (Settings → Extensions → DEV Community API Keys) and add it as DEVTO_API_KEY under your repo's secrets. The action forwards it into the child process; it's never logged.

If your posts live somewhere other than content/post, pass post-dir: with the path. If you want to see what would happen without actually creating drafts, pass dry-run: 'true'. That's the whole surface area.

A word on versioning

I went with the GitHub convention of three pin styles:

@v1 — a moving tag that tracks the latest non-breaking release. Bug fixes and additive features land automatically. This is what most people want.
@v1.x.y — a full semver pin if you need an immutable reference.
@<commit-sha> — a 40-character SHA for organisations that mandate commit-level pinning.

The v1 tag will never be force-updated to a breaking release. Breaking changes bump to @v2. That way, the convenient default is also the safe default.

Why bother extracting it

This started life as a script in this blog's own repo. It worked fine there. Extracting it into a standalone action was more work than copy-pasting a script into other Hugo repos would have been.

I did it anyway, for three reasons.

First, separation of concerns. The crosspost logic has nothing to do with my blog content. Keeping them in the same repo was mixing "what I publish" with "how I publish it," and every time I touched one, I had to reason about the other.

Second, reuse. I'm not the only person running a Hugo blog who'd like to mirror to dev.to. If the tool exists in a shareable form, other people can use it without forking my blog.

Third, and this is the part I didn't expect, extraction forces clarity. When code is hiding inside your own repo, you get to take a lot of context for granted. The directory layout, the branching model, the workflow triggers, the assumptions about what's already installed. Turning it into a public action meant writing all of that down as explicit inputs, documented defaults, and failure modes. The code ended up smaller and sharper.

That last point keeps showing up in my work, and I think it's worth naming: the act of making something reusable is often more valuable for the original project than for anyone who'll reuse it.

What's next

A few directions I'm considering, in rough priority order:

Optional publish mode, for people who genuinely do want one-click mirroring.
Better handling of images and relative links, which is currently the biggest rough edge.
Support for other destinations (Hashnode, Medium), though I'd rather keep this action focused and spin up siblings than turn it into a universal crossposter.

If any of this is useful to you, grab it from the Marketplace or reference it directly as basteez/hugo-to-devto-action@v1. Bug reports and PRs are welcome on GitHub.

And if this post shows up on my dev.to profile before I get around to publishing it there, you'll know the action works.

How to Use SonarQube and SonarScanner Locally to Level Up Your Code Quality

Tiziano Basile — Fri, 17 Apr 2026 17:35:03 +0000

Code quality tools can make a huge difference in improving your coding skills by helping you identify code smells, bugs, and potential vulnerabilities.

In this guide, we’ll explore how to set up SonarQube and SonarScanner locally. This allows you to analyze your code for potential improvements right on your machine.

Step 1: Setting Up SonarQube with Docker

First, ensure you have Docker installed. With Docker, getting SonarQube up and running is straightforward:

Pull the SonarQube image:

docker pull sonarqube
Run SonarQube:

docker run -d --name sonarqube -p 9000:9000 -p 9092:9092 sonarqube

This command runs SonarQube in the background, mapping port 9000 (for the SonarQube web interface) and 9092 (optional).

Step 2: Accessing SonarQube

With SonarQube running, open your browser and go to http://localhost:9000. Enter the default credentials:

Username: admin
Password: admin

Once logged in, you will be prompted to change the default password.

Step 3: Generate an Authentication Token

To allow SonarScanner to connect to SonarQube, you need to create an authentication token.

Click the A icon in the top-right corner and select My Account.
Navigate to the Security tab and click Generate a token.
Name your token (it can be user-specific or global) and save it somewhere secure, as it will only be displayed once.

Step 4: Configure `sonar-project.properties`

Next, set up a configuration file to define key project properties SonarQube will use to analyze your code. In the root directory of your project, create a file named sonar-project.properties and add the following content:

sonar.projectKey=my:project # Must be unique 
sonar.projectName=my project name 
sonar.projectVersion=1.0 sonar.sources=src/main/java # Adjust based on your source directory 
sonar.java.binaries=target/classes  # Adjust based on your compiled classes 
sonar.tests=src/test/java # Adjust based on your test directory

This configuration file tells SonarQube about the structure and setup of your project.

Step 5: Run SonarScanner

With everything set up, it’s time to analyze your project. Open a terminal at the root of your project and execute the following command:

mvn clean install && \
mvn dependency:copy-dependencies && \
docker run \
    --rm \
    --network host \
    -e SONAR_HOST_URL="http://{YOUR LOCAL IP}:9000" \
    -e SONAR_TOKEN="{YOUR SONARQUBE TOKEN}" \
    -v "$(pwd):/usr/src" \
    sonarsource/sonar-scanner-cli

This command does the following:

Cleans and builds your project using Maven (mvn clean install).
Copies dependencies needed for analysis.
Runs SonarScanner in a Docker container and connects it to your local SonarQube instance.

Replace {YOUR LOCAL IP} with your machine’s local IP address and {YOUR SONARQUBE TOKEN} with the token you generated in Step 4.

Step 6: Review the Analysis Results in SonarQube

Once SonarScanner completes its run, return to http://localhost:9000 and navigate to your project dashboard. Here, you’ll see a detailed report on:

Code smells: Areas of the codebase that could benefit from refactoring.
Bugs: Logical errors or anomalies in the code.
Vulnerabilities: Security-related issues.

Conclusion

Setting up SonarQube and SonarScanner locally allows you to take your code quality analysis into your own hands. Regularly reviewing these reports can help you develop better habits, improve your understanding of code quality principles, and ultimately level up your coding skills.

Don't be mad, BMAD instead

Tiziano Basile — Fri, 17 Apr 2026 10:06:47 +0000

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:

DEV Community: Tiziano Basile

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

The feature (and the trap)

The mental model, in 30 seconds

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

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

Phase 3, Architecture: the technical calls, made once

Phase 4, The story: packaging context for the implementer

Phase 5, Implementation: now, finally, code

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

What actually just happened

Try it on something small

The year I stopped writing code for fun

The symptom I ignored

Shipping more, enjoying it less

The pleasure was in the session, not the artifact

So I'm starting a project with the AI switched off

What I expect to go wrong

What I'm not claiming

The trap I can already see

BMAD in action: building TODOdoro

The starting point

Brainstorming: where the magic happened

Key insights from brainstorming

From philosophy to product brief

The PRD: philosophy becomes spec

Architecture: Winston weighs in

Breaking it down: epics and stories

Implementation: where specs pay off

Preparing a story

Refining stories with Party Mode

Working the story

Why this matters

Code review after every story

What surprised me

What didn't work perfectly

The result

Try it yourself

BMAD: meet the crew

Why personas matter

Meet the crew

John (Product Manager)

Mary (Business Analyst)

Winston (Architect)

Sally (UX Designer)

Bob (Scrum Master)

Amelia (Developer)

Quinn (QA Engineer)

Paige (Tech Writer)

Barry (Quick Flow Solo Dev)

The workflow: how agents hand off

Party Mode: when agents collaborate

Choosing your path

What's next

Crossposting without the copy-paste: a GitHub Action from Hugo to dev.to

What it does

Using it

A word on versioning

Why bother extracting it

What's next

How to Use SonarQube and SonarScanner Locally to Level Up Your Code Quality

Step 1: Setting Up SonarQube with Docker

Step 2: Accessing SonarQube

Step 3: Generate an Authentication Token

Step 4: Configure sonar-project.properties

Step 5: Run SonarScanner

Step 6: Review the Analysis Results in SonarQube

Conclusion

Don't be mad, BMAD instead

The grave I thought I was digging

The problem with vibe coding

What spec-driven development actually means

What BMAD actually is

Why this feels different

Orchestrator, not passenger

The dopamine is real (and so is the fun)

What's next

Step 4: Configure `sonar-project.properties`