Level 9Lesson 78⏱️ 55 min

BMAD Part 3 - Build a Small App

A complete worked example: take a Habit Tracker from a one-line idea to working, tested code using the full BMAD workflow

The Project: a Habit Tracker

Let's build something small and real, all the way through, so the workflow stops being abstract. Our app: a Habit Tracker - add habits, check them off each day, see a streak. Small enough to follow end to end; real enough to show every BMAD step earning its keep.

How to read this lesson: each section is one BMAD step, with the actual artifact that step produces. You could literally type these into a BMAD-installed project and get this app. Follow along; build it for real if you can.

Step 0 - Install & Set the Constitution

BMAD installs into your project with one command, then you open your AI IDE:

npx bmad-method install
# follow the prompts, then open Claude Code / Cursor in the folder

# It creates a hidden folder of agent definitions, checklists,
# and templates - all plain text you can read and edit.

First, the constitution - the house rules every later step must obey:

# constitution.md
- Stack: Next.js + TypeScript. Local storage only (no backend yet).
- Every feature ships with tests.
- Must work fully offline.
- Keyboard-accessible; usable on mobile.
- Keep it boring: no exotic libraries.

Step 1 - Brief (Analyst)

You tell the Analyst agent the idea; it interviews you and produces:

# brief.md
Problem:   People start habits and lose track after a few days.
Users:     Individuals who want a dead-simple daily check-in.
Solution:  A one-screen tracker: add habits, tap to mark done today,
           see current streak.
Constraints: Offline-only, no accounts, data stays on the device.
Risks:     Losing data if storage is cleared; streak logic across
           time zones / missed days.
Out of scope (v1): reminders, sharing, analytics, multiple devices.
Notice the "Risks" and "Out of scope" lines. The Analyst surfaced the streak/missed-day edge case before anyone wrote code. That's the whole point of planning first.

Step 2 - PRD (Product Manager)

The PM turns the brief into requirements - using EARS from Lesson 74:

# prd.md

## Functional requirements
FR-1  WHEN a user types a name and submits, the app shall add a habit.
FR-2  WHEN a user taps a habit, the app shall toggle it done/undone for today.
FR-3  The app shall show each habit's current streak (consecutive days done).
FR-4  WHEN a user deletes a habit, the app shall remove it and its history.

## Non-functional requirements
NFR-1 The app shall load and be usable offline.
NFR-2 All data shall persist in local storage across refreshes.
NFR-3 Every action shall be reachable by keyboard.

## Epics
EPIC-A Habit management (FR-1, FR-4)
EPIC-B Daily tracking & streaks (FR-2, FR-3)

Step 3 - Architecture (Architect)

# architecture.md

Components:
  <App>          holds state, wires everything
  <AddHabit>     input + button → calls addHabit()
  <HabitList>    renders habits, handles tap-to-toggle
  <StreakBadge>  computes & shows streak for a habit

Data model (one habit):
  { id, name, history: { "2026-06-25": true, ... } }

Storage:  HabitStore module wraps localStorage (load/save).
          Nothing else touches localStorage directly.

Streak logic:  count back from today while history[day] === true.
The Architect made the data model explicit - and put one rule in place ("only HabitStore touches localStorage") that will keep the codebase clean. That rule becomes a constraint in every story.

Step 4 - Alignment (Product Owner)

The Product Owner checks the docs agree and shards the epics into ready-to-build stories:

Alignment check:
  ✓ Every FR maps to a component in architecture.md
  ✓ NFR-2 (persistence) covered by HabitStore
  ⚠ Streak across MISSED days unspecified → ask user
    → Decision: a missed day breaks the streak to 0. Added as FR-3a.

Sharded stories ready for dev:
  STORY-1  Add a habit            (FR-1)
  STORY-2  Persist with HabitStore (NFR-2)
  STORY-3  Toggle done today       (FR-2)
  STORY-4  Show streak             (FR-3, FR-3a)
  STORY-5  Delete a habit          (FR-4)
The alignment step caught a real gap (what happens to a streak on a missed day?) and forced a decision. In vibe coding, you'd discover that bug in production.

Step 5-6 - Story → Implement (one at a time)

The Scrum Master writes STORY-3 as a tight, self-contained file; the Developer builds just that:

# STORY-3: Toggle done today
Why:         FR-2 (prd.md).
Constraints: Update via HabitStore only (architecture.md).
             "Today" = device local date, YYYY-MM-DD.
Acceptance:
  - Tapping a habit marks it done for today; tapping again undoes it.
  - The change persists after refresh.
  - Toggling does not affect other days' history.
Out of scope: streak display (STORY-4).

→ Developer builds on branch "story-3-toggle", writes the tests
  from the Acceptance list, runs them green, opens a PR.
The Developer never saw the whole app at once - just this story's tight context. That's why the output stays focused and correct. Repeat for STORY-1, 2, 4, 5.

Step 7-8 - QA, Merge, Repeat

On each PR:
  ✓ Automated tests run (the ones from the story's Acceptance list)
  ✓ Lint + security scan pass
  ✓ QA agent reviews against the story and the constitution
  ✓ Human approves → merge → STORY-3 done

Then STORY-4 begins. After all five stories: a working, tested,
fully-documented Habit Tracker - and a Git history where every line
traces back to a requirement.

That last sentence is the payoff. Six months later, anyone can ask "why does the streak reset on a missed day?" and follow it straight back to FR-3a and the alignment decision.

Best Practices From the Build

What made this go well (steal these):
  • Keep dev agents lean. Give the Developer only the story + the relevant architecture slice - not the whole repo. Context bloat (Level 8!) kills quality.
  • Plan in a cheap tool. Do the brief/PRD in a flat-rate ChatGPT or Gemini (BMAD "web bundles"), then bring the docs into your coding IDE. Saves real money.
  • Pilot on something small first. Learn the workflow on a low-risk app (like this one) before betting a real project on it.
  • Commit every artifact. Brief, PRD, architecture, stories - all in Git. The docs are the product; treat them like it.
  • Use the control manifest. Set allowed libraries and exclusion zones up front so the agents can't wander.

Hands-On: Run the Whole Thing

Hands-on (25 min): Pick a different tiny app (a water-intake tracker, a flash-card app, a tip splitter). Without installing anything, manually role-play BMAD in any AI chat: produce a brief, then a PRD (with EARS FRs + NFRs), then a short architecture, then shard it into 3-5 stories, then write one full story file. Stop there. You'll have done real agentic planning by hand - and you'll feel exactly how much "build me this app" was leaving to chance. This is the backbone of your capstone.
Lesson 78 Quick Reference
npx bmad-method install

Installs BMAD agent definitions, checklists, and templates into your project as plain text

Plan first, code later

Brief → PRD → architecture → alignment all happen before a single line of code

Alignment catches gaps

The Product Owner check surfaced the missed-day streak decision before it became a bug

One story, tight context

The Developer builds a single sharded story on a branch - never the whole app at once

Keep dev agents lean

Give the Developer only the story + relevant architecture; context bloat kills quality

Plan in a cheap tool

Use BMAD web bundles (flat-rate ChatGPT/Gemini) for planning, then code in your IDE

Traceable history

Every merged line traces back to a requirement - months later you can still answer "why?"

← BMAD Part 2 - The Workflow
Unlocks in ~14 min of reading