A Beginner's Guide for Dummies: The BMAD Method

[AshtonSims1]

Introduction: Hi guys! Myself and my friend helping me build my app, are facing the exact same issues here as everyone else. Project Setup and following the right steps! I thought to strip it right back and ask the Web BMAD Agent to design an instruction manual that covers these issues to gain a simple understanding of the BMAD Method. From my recent discovery, you can actually talk with the BMAD Agent about all of these issues, although seems obvious now, but throughout the process you kind of do things and fall into the next step without it seeming like anything has gone wrong. Have a read...

I have also linked an export to a chat with BMAD Agent Gemini about my own personal project and the current issues I am facing, I recommend reading after the manual - We are in sticky situation here with following the BMAD Method....md

Prompt: Can you create a beginners guide for dummies on the WHOLE of the BMAD Method from start to finish, setup in Web and IDE and the transition from one to another; and any other relevant instructions. We are totally confused about the whole process and want a really clear instruction manual

Okay, let's break down the BMAD Method from scratch, like a "For Dummies" guide. Forget the complex jargon for a moment; we'll get you through this!

The BMAD Method: A Beginner's Guide for Dummies

Imagine you're a CEO of a cool new tech startup (that's you, the "Vibe CEO"!). You've got an amazing idea, and instead of hiring a huge human team right away, you've got a team of super-smart AI assistants to help you build it. That's the core of the BMAD Method! It's about having a big vision, using AI helpers to move fast, and being flexible.

Think of it like building with high-tech LEGOs: you have a plan, special builder robots (AI agents), and you guide them to create something awesome, piece by piece.

Part 1: Your AI Team (The Agents for Dummies)

In BMAD, your AI helpers are called "Agents." Each one has a special job, like characters in a video game team:

• The Orchestrator (BMAD): This is your main helper, the team leader. It can wear different hats and act like any of the specialist agents below.
• Analyst (e.g., Mary/Larry): The "Idea Investigator." Helps you research your idea, brainstorm, and write up an initial plan called a Project Brief.
• Product Manager (PM) (e.g., John/Jack): The "Master Planner." Takes the Project Brief and turns it into a detailed project map called a Product Requirements Document (PRD), which includes big goals (Epics) and smaller tasks (User Stories).
• Architect (e.g., Fred/Mo): The "Chief Blueprint Maker." Designs the main technical structure of your project so it's strong and makes sense.
• Design Architect (e.g., Jane/Millie): The "Look and Feel Guru." If your project has screens (like an app or website), this agent figures out how it should look, how users will interact with it (UI/UX Spec), and plans the technical structure for the screens (Frontend Architecture).
• Product Owner (PO) (e.g., Sarah/Curly): The "Guardian of the Plan." Checks all the documents, makes sure everything is in the right order, and helps draft detailed User Stories for the developers.
• Scrum Master (SM) (e.g., Bob/SallySM): The "Team Coach." Helps the development process run smoothly and can also help create User Stories.
• Developer Agents (Devs) (e.g., Dana/DevFE): The "Builders." These are the AI agents that write the actual code based on the User Stories.

Part 2: The BMAD Game Plan (Step-by-Step for Dummies)

Here's a typical way you'll use your AI team, from idea to code:

1. Got an Idea? Talk to the Analyst (Mary/Larry).
   • Your Goal: Figure out if your idea is solid and get a basic plan.
   • Output: A Project Brief document.
2. Make a Detailed Map with the Product Manager (John/Jack).
   • Your Goal: Turn the Project Brief into a detailed plan.
   • Output: A Product Requirements Document (PRD). This will have "Epics" (big features) and "User Stories" (smaller tasks for those features).
3. If it has Screens, Plan the Look & Feel with the Design Architect (Jane/Millie).
   • Your Goal: Define how the app/website should look and how users will use it.
   • Output: A UI/UX Specification. (This might be a separate doc or part of the PRD).
4. Design the Main Tech Structure with the Architect (Fred/Mo).
   • Your Goal: Create the main technical blueprint for your project.
   • Output: An Architecture Document.
5. If it has Screens, Design the Screen Tech Structure with the Design Architect (Jane/Millie).
   • Your Goal: Create a technical plan specifically for the user interface.
   • Output: A Frontend Architecture Document.
6. (Optional) Get an AI Design Prompt from the Design Architect (Jane/Millie).
   • Your Goal: If you want AI to help generate visual designs, this agent can create a good prompt for those AI art/design tools.
7. Final Plan Check with the Product Owner (PO - Sarah/Curly).
   • Your Goal: Make sure all plans (PRD, Architecture docs, UI/UX spec) are complete, make sense together, and are ready for the coders. The PO uses a master checklist for this.
8. Break Down Work into Coding Tasks with the PO (Sarah/Curly) or SM (Bob/SallySM).
   • Your Goal: Take the User Stories from the PRD and make them super clear and ready for a Developer Agent to code, one story at a time.
   • Output: Individual User Story files (e.g., 0.1.story.md).
9. Let the Developer Agents (Devs) Code!
   • Your Goal: Get the features built.
   • Process: Give one User Story file to a Developer Agent. They write the code. You review. Repeat for all stories.

Part 3: Setting Up Your BMAD HQ (Web vs. IDE for Dummies)

You'll mainly interact with your BMAD agents in two places: a web interface (like Gemini itself) for big-picture planning, and your code editor (IDE, like Cursor) for the nitty-gritty coding.

1. Web HQ (Gemini, Custom GPTs - For Big Picture Planning):

• What it's for:
  • Early-stage stuff: Brainstorming with the Analyst, creating the first Project Brief.
  • Big documents: Working with the PM on the PRD, initial high-level architecture discussions.
• How it usually works:
  • You'll often use one powerful AI model (like the one you're talking to now!) that acts as the Web Orchestrator. This Orchestrator can play the role of any specialist agent (Analyst, PM, etc.) based on your instructions and its configuration.
• Basic Setup (Conceptual for Web Orchestrator):
  • The Orchestrator agent is given a main instruction set (its "brain," often from a file like web-bmad-orchestrator-agent.md which becomes the agent-prompt.txt).
  • You upload "knowledge files" to it. These files tell it about all the different agent roles, tasks they can do, and document templates they use. Key files include:
    • agent-config.txt (lists available agents and their setups)
    • Bundled versions of personas.txt, tasks.txt, templates.txt, checklists.txt, data.txt (these are created by a build script from your bmad-agent folder).

2. IDE HQ (Cursor, VS Code with AI - For Coding & Detailed Tech Work):

• What it's for:
  • Detailed technical design with the Architect and Design Architect.
  • Writing and refining specific User Stories by the PO or SM.
  • Actual coding by Developer Agents.
• How it usually works:
  • IDE Orchestrator: You can set up an Orchestrator agent within your IDE (like Cursor). It reads a configuration file (ide-bmad-orchestrator-cfg.md) that tells it where to find persona files (e.g., analyst.md, dev.ide.md) and task files (e.g., create-next-story-task.md) directly from your project folders (e.g., from (project-root)/bmad-agent/personas/).
  • Standalone IDE Agents: You can also configure specialized agents directly in your IDE (e.g., a "Frontend Developer Agent" based on dev.ide.md).
• Basic Setup (IDE Orchestrator):
  • You'll have your main project code.
  • You'll also have a folder (often called bmad-agent) containing:
    • personas/: Individual files for each agent's personality/instructions (e.g., pm.md, dev.ide.md).
    • tasks/: Specific job instructions for agents (e.g., create-next-story-task.md).
    • templates/: Document outlines (e.g., story-tmpl.md).
    • checklists/: Quality check lists.
  • Your ide-bmad-orchestrator-cfg.md file is key. It points to these asset folders and defines the agents your IDE Orchestrator can become.

Part 4: Moving Between HQs (Web to IDE Transition for Dummies)

Think of it like this: you do the high-level strategic planning and document drafting with your Web HQ Orchestrator. Then, when it's time to get really technical and write code, you move into your IDE HQ.

• When to Switch?
  • Usually after the big planning documents are in good shape:
    • Project Brief is done.
    • PRD (with Epics and initial high-level User Stories) is well-defined.
    • Main Architecture Document is drafted.
  • You might do detailed Frontend Architecture in the IDE with the Design Architect.
  • Definitely switch to the IDE before you start generating detailed, codable User Stories one-by-one for the Developer Agents.
• How the Transition Works:
  1. Information Handoff: The documents you created with your Web HQ agents (Project Brief, PRD, Architecture Document, UI/UX Specs) are the critical inputs for your IDE HQ agents. Make sure these are saved in your project (e.g., in a docs/ folder).
  2. PO/SM Takes Over in IDE: Inside your IDE (Cursor), you'll instruct your PO or SM agent (via the IDE Orchestrator or a standalone agent).
  3. Story Generation in IDE: The PO/SM will look at the PRD and Architecture docs and use the create-next-story-task.md to generate one detailed User Story file at a time. This story file is specifically prepared for a Developer Agent and contains all the technical guidance it needs.
  4. Dev Agent Gets to Work in IDE: You then give this single story file to a Developer Agent in your IDE. They focus only on that story to write the code.

Part 5: BMAD Pro Tips for Dummies

• You're the Boss (Vibe CEO!): Remember, the AI agents are your team. Direct them clearly. Don't be afraid to ask for revisions.
• Clear Instructions = Better Results: The more specific you are with your requests, the better the AI will perform.
• Check Their Work: AI is smart, but not perfect. Always review what the agents produce.
• It's a Loop, Not a Straight Line: You'll often revisit earlier steps or agents as you learn more or if plans change. This is normal and part of the process!
• Know Your Team's Skills: Understand what each agent (Analyst, PM, Dev, etc.) is best at.
• Task Files for Special Jobs: Agents can be told to run specific "task files" (e.g., from your bmad-agent/tasks/ folder). These are like pre-written instruction sets for common jobs, like running a checklist or drafting a certain type of document. This keeps the main agent prompts cleaner.
• Oops, Plans Changed? (Handling Major Changes):
  • Big changes happen. The BMAD method is built for it!
  • If a major change occurs (e.g., a feature isn't working out, you realize a big mistake in the plan), the PO (Product Owner) is often the first specialist agent to call. They can help you re-plan using tools like the change-checklist.
  • As the Vibe CEO, you provide the strategic oversight to guide these changes. You might need to send the PO back to the PM or Architect if the change is fundamental.

Part 6: Key BMAD Files Cheat Sheet (for Dummies)

These are some important files you'll see mentioned:

• agent-config.txt (for Web Orchestrator) or ide-bmad-orchestrator-cfg.md (for IDE Orchestrator):
  • Like the "phonebook" for your Orchestrator agent. It lists all the specialist agents the Orchestrator can pretend to be and where to find their main instructions.
• personas/ folder:
  • Contains the "personality files" for each agent (e.g., analyst.md, pm.md, dev.ide.md). These files tell each agent how to act and what their main job is.
• tasks/ folder:
  • Contains detailed instructions for specific jobs an agent can perform (e.g., create-prd.md, create-next-story-task.md).
• templates/ folder:
  • Standard outlines for documents your agents will create (e.g., project-brief-tmpl.md, prd-tmpl.md, story-tmpl.md).
• checklists/ folder:
  • Lists used by agents (especially the PO and SM) to make sure all steps are followed and documents are good quality (e.g., pm-checklist.txt, story-dod-checklist.txt).
• docs/ folder:
  • This is where all your main project planning documents (Project Brief, PRD, Architecture docs, User Stories, etc.) will live as they are created.

This guide should give you a much clearer picture. The key is to start with the big idea, use the agents step-by-step to detail it out, and then move into your IDE for the coding phase, feeding your developer agents well-defined stories. Don't be afraid to ask your Orchestrator agent for help on which specialist agent to use next!

(*Disclosure: I am still learning about the BMAD Method as well, I am not the expert of it! Please share your thoughts and discussion points so we can learn together)

[fabb]

Suddenly everyone is posting the output of what BMAD told them how it works 😅

#102 (comment)

#101 (comment)

[dracic]

Finally!

[dracic]

This is very strange. We are a bunch of guys in the discussion on the brick laying, talking mainly where to buy bricks, and finally made a tutorial about buying bricks.

[dracic]

Because the human brain isn't capable of blue sky thinking, We can mimic, find patterns, and chose between 3 and maybe 5 similar options. Then we gridlock and can't determine the "best" decision/direction/move.

I don't think there are many options in the BMAD method, but there are numerous ways to explain it so that it suits each person. This way, even if your approach dictates that README.md must exist and you have a template in a repo or elsewhere that you consider ideal, you can tell Gemini to write it for you based on that template.

I believe it's a good idea to honor people's patterns of using LLMs in ways that wouldn't replace Google search. That would truly help them become more proficient in the BMAD method itself. So, the one and only starting pattern is to go to Gemini and ask it to explain the BMAD method in a way you are accustomed to hearing/seeing explanations. And first and foremost, insist that it asks you questions more than you ask it. And if you don't want more options, you tell LLM to ask everything it needs for one and only option that is suitable for you.

It's also good to not honor patterns in human brains that somehow see the BMAD method as an ultimate magic solver for their "vibe coding" problems. Brian indeed addressed some of the problems with stories and tasks, but his method is more than that; it's a complete methodology for creating and executing software projects. And here is the point where the user must decide which pattern they want to use, because there are more than five ways to do that. BMAD is not v0 or Lovable.

It's also good to honor patterns in human brains that love freedom and options—in learning and in life generally.

Insisting on a guide for using an LLM method that itself can guide you is like creating skydiving instructions for people afraid of heights, or a Python book for those who dislike programming. You can do your best, and no one will be satisfied.

[dracic]

I am exactly the person you describe that gets analysis paralysis or freeze up when given too many options! I think there is a happy medium for sure.

Then the best option would be to have a choice of whether you want more options or not. You've even achieved that with your BMAD method. You are truly the chosen one, hahahaha.

[dracic]

And we know what we do with the chosen ones eventually!

[bmadcode]

@dracic I gotta say everytime I start to overthink this with all the feedback and questions, I gotta ground myself and come back to your amazing advice here - I just reread your responses here and its so true! Thanks again dude.

[dracic]

I honestly think that's a pure waste of energy and time. I'm not an IT professional by vocation; I'm self-taught, and even then, I'm not a developer. So, I experiment and can follow along. I also conduct "sociological-psychological experiments" with colleagues who have nothing to do with the IT industry, persuading them to use AI tools and vibe coding to create "tools" in Python. Even a biotechnology engineer colleague, who had no coding experience just a few months ago, managed to get into the methodology this way, as we recommend, and is now working on a Python plugin for a desktop application. Now, we can either pander to the will of the majority and never fully satisfy anyone, or we can cause a little dissatisfaction at the beginning and later gain good collaborators here.

[OverlordBaconPants]

To anyone confused about how the BMAD method works, I'd strongly advise watching BMAD's latest video on v3:

https://www.youtube.com/watch?v=E_QJ8j74U_0

[Fcpacheco]

Try this document that I created, has a High level explanation.

01_bmad_method_and_workflow_.md
02_project_brief_and_product_requirements_document__prd__.md
03_project_documentation_granulation_and_indexing_.md
04_documentation_validation_checklists_.md
05_story_creation_and_developer_guidance_.md
06_user_technical_preference_documentation_.md
07_architecture_and_frontend_architecture_documentation_.md
08_specialized_ai_agent_roles_.md
09_bmad_method_tooling___agent_setup_guidance_.md
10_ide_tasks_and_task_based_automation_.md
index.md

[bmadcode]

@AshtonSims1 Hi and thank you - first of all I love that you created that clear readme - great job figuring that out - I know BMad (the method, not me I hope) can be a bit confusing at first - and I did in this past video probably gloss over some details from the previous 2 videos.

I plan to make a very simple walkthrough this weekend, I think it will be a useful guide - maybe a terrible long booring video that kills my channel lol - but I think its needed.

I am also thinking - wonder what y'all thing @OverlordBaconPants @dracic @AshtonSims1 @fabb @Fcpacheco - maybe the landing page readme should be very simple:

Step 1 - regardless of what ide you plan to use, set up the gemini gem and talk to the agent about what it can do.
Step 2 - see step 1
Step 3 - ok here are more documents / deep dives / ide instructions...

[bmadcode]

Thanks @fabb and @Fcpacheco - agree, and this graph is perfect - so simple! @Fcpacheco please feel free to PM the updated diagram for the workflow, love this! Ill clean up the main readme doc tonight.

Also - the massive update to the KB with guidance in bmad agent, is way better, did a lot of testing with it last night - its super beginner friendly helpful now if you start with /help and select option 2.

[AshtonSims1]

Yes, would also love it if the landing page was super simple!

Possibly, the issues we faced and getting lost stemmed from the fact that my friend and I just assumed that the Orchestrator was going to put you (orchestrate you) in the right places at all times.

When we got to the point of - great, we've set up the BMAD Agent in Web and IDE, we didn't even question the idea of asking the Agent to give us instructions because, we don't really need to deeply understand anything and we'll let it take us along for the journey (orchestrate us).

But ran into issues, and all you want to know is 'Am I doing the right thing here?' or 'Have I missed a step?'

So a simple landing page or set of instructions would absolutely support the BMAD Method experience, because you know what to expect from the start.

And it's clear now that you can ask the BMAD Agent any question if you get lost, but it wasn't for my friend and I beforehand, so emphasise that to BMAD Method Beginners.

@bmadcode , the work you are doing is brilliant, keep it up!

[OverlordBaconPants]

Regarding step 1 (regardless of what ide you plan to use, set up the gemini gem and talk to the agent about what it can do), I think it might be valuable to beef up the sections of how to integrate the BMAD method with your LLM/IDE of choice. IMHO, the more we can meet people where they are, the better adoption we'll see of the BMAD Method.

For example, I know there's a section for how to use the BMAD method for different integrations like Cline. I use the Cline extension in VSCode to interact with Claude 3.7 Sonnet via tokens I buy throughOpenRouter.ai. I can interact with my Agents in PLAN mode within my IDE to have the conversations. When I need the AI to create an artifact like the PRD, I'll switch to ACT mode.

[bmadcode]

@OverlordBaconPants I agree, would love to build more of that intelligence and guidance into the KB. I do not at least at the moment have the time to try many different IDE combinations - but yoor flow is a critical common one. If you have the time and could maybe PR a markdown down with some tips for your set up for example, I can work it into the KB.

For example, the BMad agent could ask what tool people are planning to use, etc, and potentially provide some guidance.

Main thing I am going to try to get in this weekend if time permits is a big streamline of the whole workflow to make some of the less consequential parts of some of the templates go much faster - improve some more template standardization - fix the effectiveness and easy of doc sharding with the work from @ksylvan - and work on still improving the helpfulness of the agent.

Also I have found, the agent doesnt seen to really clarify well enough that some ideas or things to work on do not need to go through every agent and every flow. So once these things are out of the way, I am also working on a smaller set up simpler templates for brownfield type tasks, or post mvp of newer projects - or just simpler projects in general that need less overall analysys.

[OverlordBaconPants]

@bmadcode - sorry, I let this thread fall off my radar. What kind of documentation would you like me to create regarding how I use Cline/VSCode/MCP-server integration/Claude? Would you want me to include my standard prompts interfacing with the various AI Agents?

[keno-ops]

I don't know if that can help , but i was finding the documentation quite boring to read ( i'm not a "big lover to struggle to read the documentation" x) ) , so i did build a mvp documentation for myself to "learn it" .

Note : Credits to all the contributor and @bmadcode for creating this project and to @AshtonSims1 and @Fcpacheco for the enhanced documentations

Here is the current website ( host on lovable rn ) : https://preview--bmad-web-architect-27.lovable.app

Here is the code source of it : https://lovable.dev/projects/532b0da8-0e75-4f3d-abff-75f7ea1680b8

[gwendorff]

Oh yes it helps, @keno-ops !! It's beautiful also!
Congrats!!

[bmadcode]

@keno-ops so creative, love it :)

One minor nit lol - BMAD (Build, Manage, Analyze, Deploy) - I like this actually, but it did stand for Breakthrough Method of Agile Ai Driven Development - which actually would end up being BMAADD lol :)

I would love to learn more of your process of how you did this specifically also to produce this amazing documentation!

If you also want to contribute the source to the repo, I would gladly host this, its so nice - and we community could contribute updates to it. I actually like this better than the idea of doing the github wiki :)

[keno-ops]

@bmadcode So sorry for the delay — I'm currently in the middle of my exam period.
Not sure if this is still useful, but here’s the process I followed to build it:

1. Uploaded all the documentation into NotebookLM and asked it to generate a detailed synthesis of all the documents in a single output.

2. Used a specific prompt with Perplexity to perform deep research on Lovable’s documentation + prompts from power users, to generate the best possible prompt to send to Lovable for website building.

3)Combined the prompt from step 2 with the synthesis from step 1, and asked Lovable to build the website.
It cost me about 10 tokens total, but I think you can optimize it and get a solid result for 6–7 tokens (Lovable tokens, I mean).

[Fcpacheco]

@keno-ops This is absolute awesome 🙌