DEV Community: Tiziano Basile

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

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`