End to end: four complete project runs

The map and the command reference are the pieces; this page assembles them. Four runs, start to finish: a greenfield product through the full method, a change to an existing codebase, a one-file quick fix, and an unattended autonomous loop. Each is a real sequence of commands with the artifact each step leaves behind.

One discipline threads through all four: a fresh chat per workflow. State lives in files, not in the conversation, so a clean context window costs nothing and stale conversational residue costs correctness. Start each bmad-* step in a new session and let it read what it needs from disk.

On this page

Run 1: greenfield, idea to shipped (full BMad Method)

The scenario: a new "team task tracker with a public API," a project big enough to have several epics, so it earns the full four phases. The path, phase by phase.

Phase 1, Analysis: turn a hunch into evidence

bmad-help  I have an idea for a team task tracker, where do I start?

bmad-help recommends a starting point. For a fuzzy idea, brainstorm first, then pressure-test the survivor, then research what the decision rests on:

bmad-brainstorming     # 60+ techniques; pulls 100+ ideas out of you, then organizes
bmad-forge-idea        # interrogate the favorite until it hardens (forged-idea.md) or dies
bmad-deep-recon        # decision-grade research on the contested claims (research.md)

Then consolidate into a brief (collaborative) or a PRFAQ (a gauntlet):

bmad-product-brief     # brief.md: a 1-2 page executive summary
# or
bmad-prfaq             # prfaq-{project}.md: write the press release before any code

You leave Phase 1 with research.md, forged-idea.md, and brief.md in _bmad-output/planning-artifacts/, each a reviewed file the next phase reads. (Research itself is the subject of the recon gists; this run just uses it.)

Phase 2, Planning: what to build, and for whom

bmad-prd     # Create intent: coached discovery -> prd.md (FRs, NFRs) + .memlog.md
bmad-ux      # DESIGN.md (visual tokens) + EXPERIENCE.md (behavior, states, journeys)

bmad-prd source-extracts the brief so you do not re-explain the product. It runs in one of three intents: Create (new PRD), Update (reconcile a change, surfacing conflicts first), Validate (critique against a checklist, producing an HTML findings report). The PRD is the contract the architect reads next.

Phase 3, Solutioning: how, then in what units

This is the phase that pays for itself on multi-epic work, because it pre-empts the conflicting decisions that different agents would otherwise make.

bmad-architecture                    # ARCHITECTURE-SPINE.md: explicit decisions (ADRs)
bmad-generate-project-context        # project-context.md from the architecture
bmad-create-epics-and-stories        # epic files, each with implementable stories
bmad-check-implementation-readiness  # PASS / CONCERNS / FAIL gate over the whole chain

The readiness gate is the last cheap checkpoint. A CONCERNS like "story 3 has no guardrail metric" is caught here as a paragraph, not later in code review. Do not start Phase 4 on a FAIL.

Phase 4, Implementation: one story at a time

bmad-sprint-planning     # once: sprint-status.yaml sequences the cycle
# then, per story, each in a fresh chat:
bmad-create-story        # story-{slug}.md with full, focused context
bmad-dev-story           # working code + tests, test-first
bmad-code-review         # approved, or changes requested
# after the epic:
bmad-qa-generate-e2e-tests   # API/E2E tests once the epic's stories are done
bmad-retrospective           # lessons learned

If something big shifts mid-sprint (a requirement changes, an assumption breaks), do not patch downstream files by hand. Run bmad-correct-course, which reconciles the plan and re-routes, then let the change propagate through the artifacts.

The full greenfield trace, in one column:

brainstorm.html/-intent -> forged-idea.md -> research.md -> brief.md
  -> prd.md (+ DESIGN.md/EXPERIENCE.md)
  -> ARCHITECTURE-SPINE.md + project-context.md + epics/
  -> readiness PASS
  -> sprint-status.yaml -> story-*.md -> code+tests -> review -> QA -> retrospective

Run 2: brownfield, a feature in an existing codebase

The scenario: add "saved filters" to an app that already exists and was not built with BMAD. The extra work up front is teaching BMAD your codebase so its research and stories refer to the real system, not an imagined one.

# 1. Make the codebase a source the agents can cite
bmad-document-project            # scans and documents the current system
bmad-generate-project-context    # project-context.md: stack, versions, conventions

# 2. Then plan the change at whatever depth it needs
bmad-prd                         # Update intent if a PRD exists, else Create, scoped to the feature
bmad-architecture                # only if the change crosses epic boundaries
bmad-create-epics-and-stories
bmad-check-implementation-readiness

# 3. Implement as in Run 1
bmad-sprint-planning -> bmad-create-story -> bmad-dev-story -> bmad-code-review

Two brownfield specifics. First, bmad-quick-dev (Run 3) works on existing projects too: it auto-detects the stack, reads existing patterns, and asks "should I follow these existing conventions?" Answer yes to stay consistent, no to establish new standards (and document why in the spec). BMAD respects the choice; it will not force modernization but it will offer it. Second, if you are unsure whether you even need document-project, run it anyway; it is safe to run at any time to keep docs current, and cheap insurance against agents inventing an architecture you do not have.

Run 3: a quick fix (Quick Flow)

The scenario: a bug, or a one-file feature, small and well understood. The full method would be ceremony. Quick Flow compresses clarify, plan, implement, review, and present into a single skill that runs longer between checkpoints.

bmad-quick-dev
> Fix the off-by-one in pagination: the last page shows one duplicate row.

Intent can be a phrase, a bug-tracker link, a GitHub issue URL, output from plan mode, or a story number from epics.md. Quick Dev then:

  1. Compresses intent into one coherent, contradiction-free goal, asking clarifying questions if needed. (Intent clarification is one of its three high-value human moments.)
  2. Routes to the smallest safe path. A zero-blast-radius change can go straight to implementation; anything larger gets a spec first, which becomes the boundary it executes against. (Spec approval is the second human moment.)
  3. Implements and self-reviews, deferring incidental findings not tied to the change into deferred-work.md rather than flooding you with nitpicks.
  4. Commits locally and offers a push or PR. (Reviewing the result is the primary, third human moment.)

To hand the finished change to a human reviewer in comprehension order rather than file order, say checkpoint: bmad-checkpoint-preview walks the change by concern, flags the two to five highest-blast-radius spots, and suggests how to observe the change manually. Roll back a Quick Dev with git revert HEAD.

Run 4: the autonomous loop (human on the loop)

The scenario: an epic of well-specified stories you want implemented unattended, with a human watching rather than approving each step. This is the third of BMAD's "three flows" (Full Method, Quick Dev, and BMad Loop), and it shifts you from human in the loop to human on the loop.

The unit of unattended work is bmad-dev-auto: one iteration that clarifies intent, creates or resumes a spec, implements, reviews, and writes a terminal status to the spec's frontmatter. It requires the ability to spawn subagents, and (strongly recommended) a clean git tree. Its spec status is the machine-readable state an orchestrator drives on:

statusmeaningorchestrator action
draftspec exists, not yet validatedresume at planning
ready-for-devcomplete enough to buildresume at implement
in-progressimplementation underwayresume at implement
in-reviewreview underwayresume at review
donecompleted; writes an Auto Run Result and commits (never pushes)move to next story
blockedcannot safely continuea human or another workflow takes over

To run a whole epic, first break the spec into an ordered stories.yaml (produced on request by bmad-spec), then dispatch each story. You can do this by hand ("implement stories 2 to 10, using a subagent running bmad-dev-auto for each"), or let the BMad Loop module drive it deterministically:

bmad-loop-setup            # one-time: install the orchestrator and per-project hooks
bmad-loop run              # deterministic Python drives pick -> implement -> review -> verify -> commit
bmad-loop status | tui     # watch it; sprint-status.yaml is the single ledger
bmad-loop resolve <story>  # step in when a run pauses on a CRITICAL escalation

The loop keeps no LLM in the control path: plain Python sequences the steps while fresh-context coding-agent sessions do the creative work, dev and review in separate sessions so no anchoring bias carries over. You set how much oversight you want with gates.mode: none runs whole epics unattended, per-epic pauses between epics, per-story-spec-approval pauses for you to approve each spec before code. blocked is a routing signal, not just a failure: it usually means unattended execution would be unsafe and a human should look.

Hands-on: the greenfield flow, command by command

Pick a genuinely small project, one epic's worth, so the loop finishes in an afternoon. Open a fresh chat for each bmad-* line below, in this order. State lives on disk, so every new session reads the files the last one wrote; the comment on each line names the file it produces.

# Phase 1, Analysis (fresh chat each)
bmad-brainstorming                   # brainstorm.html: raw ideas, then organized
bmad-forge-idea                      # forged-idea.md: the survivor, pressure-tested

# Phase 2, Planning
bmad-prd                             # prd.md (+ .memlog.md): FRs, NFRs
bmad-ux                              # DESIGN.md + EXPERIENCE.md: tokens + behavior

# Phase 3, Solutioning
bmad-architecture                    # ARCHITECTURE-SPINE.md: decisions as ADRs
bmad-generate-project-context        # project-context.md: stack, conventions
bmad-create-epics-and-stories        # epics/ + stories: the work, in units
bmad-check-implementation-readiness  # readiness-report.md: PASS / CONCERNS / FAIL

# Phase 4, Implementation (per story, fresh chat each)
bmad-create-story                    # stories/story-{slug}.md: focused context
bmad-dev-story                       # working code + tests, test-first
bmad-code-review                     # approved, or changes requested

# Close the epic
bmad-retrospective                   # retrospective.md: lessons learned

For a project this small the sequence drops three optional steps from Run 1: bmad-deep-recon (research.md) and bmad-product-brief (brief.md) earn their place only when a decision needs evidence, and bmad-sprint-planning (sprint-status.yaml) pays off once there is more than one story stream to sequence. Add them back the moment the scope grows. Note that bmad-check-implementation-readiness writes no code; it emits a verdict, so stop and fix on a FAIL before any story starts.

After a clean run over three stories, _bmad-output/ looks like this:

Illustrative (run it in your own repo; not machine-verified here).

_bmad-output/
├── planning-artifacts/
│   ├── brainstorm.html
│   ├── forged-idea.md
│   ├── prd.md
│   ├── .memlog.md
│   ├── DESIGN.md
│   ├── EXPERIENCE.md
│   ├── ARCHITECTURE-SPINE.md
│   ├── project-context.md
│   └── readiness-report.md
├── epics/
│   └── epic-1-core-tasks.md
├── stories/
│   ├── story-create-task.md
│   ├── story-list-tasks.md
│   └── story-public-api.md
└── retrospective.md

Read the tree top to bottom and you are reading the method: each file is the reviewed input to the workflow below it, from a raw brainstorm down to the retrospective that closes the epic. Paste the sequence, and watch the chain grow one reviewed file at a time.

Under Claude Code: running the four flows

The four runs map onto one control: the permission mode, the per-phase autonomy dial. It goes from default (read tools only) up through acceptEdits, plan, auto, to bypassPermissions (every tool, no prompt). Shift+Tab cycles it live.

Greenfield. Run the planning phases in plan mode: Shift+Tab to plan, where Claude reads and proposes but edits nothing until you approve the ExitPlanMode plan. Analysis, PRD, and architecture all fit that read-and-propose shape. When one story is genuinely hard, escalate the model for that session with /model opus, then drop back.

Brownfield. The existing monolith sits outside the project root, so grant access with /add-dir <path> (or launch with --add-dir <path>). Claude can then cite the real system, and it also loads that directory's .claude/skills/.

Quick fix. Launch with --permission-mode acceptEdits so file edits land without a prompt while you review; Bash still gates by command.

Autonomous. Go headless:

claude -p "run the story" --bare --permission-mode acceptEdits \
  --max-budget-usd 5 --max-turns 40 --output-format json

--bare strips hooks, skills, MCP, and CLAUDE.md for a clean run; --max-budget-usd and --max-turns bound it; the JSON result carries per-turn token usage.

Between phases, /clear opens a fresh window (state lives in files) or --resume <id> / --continue carries context forward. A wrong turn rewinds with /rewind, which restores Claude's file edits and the conversation but not committed git history or Bash side effects. For those, use git.

Whichever run you are on, the through-line is the same: a reviewed artifact at every boundary, with the human's attention spent where it counts most, framing the work and judging the result, not typing every step. The next page is about the files that make that possible across sessions: how BMAD saves memory, and how to measure whether it is actually helping. 👉