skills/bmad-code-org__bmad-method
1
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-19 08:11:52 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
config-improvements
bmad-code-org__bmad-method/docs/tutorials/getting-started.md
T
Brian ee47e30cf6 refactor(bmad-ux): spine-based UX skill (DESIGN.md + EXPERIENCE.md) (#2413) 
* refactor(bmad-ux): replace bmad-create-ux-design with lean spine-based bmad-ux

* refactor(bmad-ux): adopt DESIGN.md spec, split into two-file spine, align prd/brief

DESIGN.md (visual identity per the Google Labs spec) and EXPERIENCE.md
(behavior, flow, IA) replace the single design.md spine. EXPERIENCE.md
cross-references DESIGN.md tokens via the spec's {path.to.token} syntax.

Example suite restructure
- 3 DESIGN.md examples: editorial (Stitch source / Linen & Logic), calm
  native mobile (Quill), shadcn-on-Tailwind web SaaS (Drift)
- 2 paired EXPERIENCE.md examples (Quill, Drift); Linen & Logic unpaired
  to model the Stitch handoff scenario
- Replaces the prior 2-example combined spine set

Discovery additions (outcome-driven, one line each)
- Source scan: glob {planning_artifacts}/ for candidates, parent never reads
- Form-factor: resolve before IA closes; journeys often derive it
- Surface closure: every stated need has a surface, every surface a journey
- Named-protagonist journeys (Mary, not "the user")
- Design handoff working mode (extensible producer registry, default: Stitch)

PRD and brief alignment with same insights
- bmad-prd: dropped standalone Primary Persona section from template;
  renamed "Personas + Journeys" entry to "Journey-led"; named-protagonist
  rule on UJs; form-factor probe; validation checklist updated
- bmad-product-brief: form-factor surfaced in Discovery topics

Quality scan fixes
- Added ## Overview heading; renamed ## Activation to ## On Activation
- Replaced ../ paths in example assets with {planning_artifacts}/
- Sources section compressed (abstract delta-only rule)
- Working mode aligned to "Fast path" / "Coaching path" BMad-wide convention

New
- references/design-md-spec.md: working summary of the spec for the LLM
- customize.toml: design_md_examples, experience_md_examples,
  design_handoffs registries
- .prettierignore: ignore .analysis/ quality-scan artifacts repo-wide

* refactor(bmad-ux): activation parity with prd/brief, opt-in reviewer gate, no headline grade

- Restructure On Activation as numbered six-step list mirroring bmad-prd
  and bmad-product-brief, restoring the explicit key-resolution list that
  earlier crammed-paragraph form had dropped (planning_artifacts and
  friends were silently unresolved at Create).
- Make Reviewer Gate opt-in and lens-selectable. At Finalize, ask before
  spending tokens on parallel reviewer subagents; at Validate intent,
  skip that question but still confirm lens picks. Stops the auto-run
  WCAG audit on hobby-stakes work.
- Drop the overall validation grade. Per-category verdicts and severity
  counts already say what is true; a single headline grade conflated
  design rigor with release readiness and led "POOR" pills landing on
  reports whose own bodies described the work as strong. Removed from
  references/validate.md (ladder rule + markdown twin), HTML template
  (grade pill div + CSS vars + classes).
- Trim creative-tools.md: drop the Custom entries section. Runtime
  prompt files should only carry what the LLM needs to act in this
  moment; how-to-extend-via-TOML is setup-time human documentation
  already covered by customize.toml comments.

* fix(bmad-ux): align validation report template with 8-category rubric

Template placeholders referenced 'Decision-readiness' and 'seven dimensions'
from the prior rubric. Replace with TEMPLATE_CATEGORY_NAME and inline the
eight canonical categories from references/validate.md so the synthesis pass
names them verbatim.

* fix(validate-skills): remove stale WF-01/WF-02 rules

WF-01/WF-02 were originally scoped to workflow.md files (now mostly gone)
but had been generalized to flag name/description in any non-SKILL.md
markdown. That over-captured legitimate spec files — e.g. DESIGN.md
examples in bmad-ux/assets/ that carry name/description per the Google
Labs DESIGN.md spec.

Step files are already covered by STEP-06. Rule count: 14 → 12.

* fix(bmad-ux): address PR review followups

- validation-report-template.html: severity badge class is badge-sev-*,
  not sev-* (the comment misled the synthesis pass).
- Sweep dangling bmad-create-ux-design references: module-help.csv,
  bmad-agent-ux-designer/customize.toml, bmad-prd/SKILL.md handoff list,
  workflow-map.md (en + 4 translations), getting-started.md (en + 4
  translations). Workflow-map output column updated to DESIGN.md +
  EXPERIENCE.md.
- references/validate.md: Markdown capitalized as a proper noun.
2026-05-22 23:16:06 -05:00

293 lines
13 KiB
Markdown
Raw Permalink Blame History

---
title: 'Getting Started'
description: Install BMad and build your first project
---
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
## What You'll Learn
- Install and initialize BMad Method for a new project
- Use **BMad-Help** — your intelligent guide that knows what to do next
- Choose the right planning track for your project size
- Progress through phases from requirements to working code
- Use agents and workflows effectively
:::note[Prerequisites]
- **Node.js 20.12+** — Required for the installer
- **Git** — Recommended for version control
- **AI-powered IDE** — Claude Code, Cursor, or similar
- **A project idea** — Even a simple one works for learning
:::
:::tip[The Easiest Path]
**Install** → `npx bmad-method install`
**Ask** → `bmad-help what should I do first?`
**Build** → Let BMad-Help guide you workflow by workflow
:::
## Meet BMad-Help: Your Intelligent Guide
**BMad-Help is the fastest way to get started with BMad.** You don't need to memorize workflows or phases — just ask, and BMad-Help will:
- **Inspect your project** to see what's already been done
- **Show your options** based on which modules you have installed
- **Recommend what's next** — including the first required task
- **Answer questions** like "I have a SaaS idea, where do I start?"
### How to Use BMad-Help
Run it in your AI IDE by invoking the skill:
```
bmad-help
```
Or combine it with a question for context-aware guidance:
```
bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started?
```
BMad-Help will respond with:
- What's recommended for your situation
- What the first required task is
- What the rest of the process looks like
### It Powers Workflows Too
BMad-Help doesn't just answer questions — **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs — just clear guidance on the next required workflow.
:::tip[Start Here]
After installing BMad, invoke the `bmad-help` skill immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
:::
## Understanding BMad
BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
| Phase | Name | What Happens |
| ----- | -------------- | ------------------------------------------------------------ |
| 1 | Analysis | Brainstorming, research, product brief or PRFAQ _(optional)_ |
| 2 | Planning | Create requirements (PRD or spec) |
| 3 | Solutioning | Design architecture _(BMad Method/Enterprise only)_ |
| 4 | Implementation | Build epic by epic, story by story |
**[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
Based on your project's complexity, BMad offers three planning tracks:
| Track | Best For | Documents Created |
| --------------- | ------------------------------------------------------ | -------------------------------------- |
| **Quick Flow** | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only |
| **BMad Method** | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX |
| **Enterprise** | Compliance, multi-tenant systems (30+ stories) | PRD + Architecture + Security + DevOps |
:::note
Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
:::
## Installation
Open a terminal in your project directory and run:
```bash
npx bmad-method install
```
If you want the newest prerelease build instead of the default release channel, use `npx bmad-method@next install`.
When prompted to select modules, choose **BMad Method**.
The installer creates two folders:
- `_bmad/` — agents, workflows, tasks, and configuration
- `_bmad-output/` — empty for now, but this is where your artifacts will be saved
:::tip[Your Next Step]
Open your AI IDE in the project folder and run:
```
bmad-help
```
BMad-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?"
:::
:::note[How to Load Agents and Run Workflows]
Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-agent-pm` for the PM agent).
:::
:::caution[Fresh Chats]
Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
:::
## Step 1: Create Your Plan
Work through phases 1-3. **Use fresh chats for each workflow.**
:::tip[Project Context (Optional)]
Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `bmad-generate-project-context`. [Learn more](../explanation/project-context.md).
:::
### Phase 1: Analysis (Optional)
All workflows in this phase are optional. [**Not sure which to use?**](../explanation/analysis-phase.md)
- **brainstorming** (`bmad-brainstorming`) — Guided ideation
- **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) — Market, domain, and technical research
- **product-brief** (`bmad-product-brief`) — Recommended foundation document when your concept is clear
- **prfaq** (`bmad-prfaq`) — Working Backwards challenge to stress-test and forge your product concept
### Phase 2: Planning (Required)
**For BMad Method and Enterprise tracks:**
1. Run `bmad-prd` in a new chat — state your intent (Create / Update / Validate) or let the skill ask
2. Output: `prd.md`, `addendum.md`, `decision-log.md`
:::note[`bmad-prd` intents]
- **Create** — coached discovery from scratch; the skill names the workspace folder and guides you to a PRD you're proud of
- **Update** — point it at an existing PRD and a change signal; it surfaces conflicts before applying changes
- **Validate** — critique a finished PRD against a checklist and produce an HTML findings report
:::
**For Quick Flow track:**
- Run `bmad-quick-dev` — it handles planning and implementation in a single workflow, skip to implementation
:::note[UX Design (Optional)]
If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-ux`) after creating your PRD.
:::
### Phase 3: Solutioning (BMad Method/Enterprise)
**Create Architecture**
1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat
2. Run `bmad-create-architecture` (`bmad-create-architecture`)
3. Output: Architecture document with technical decisions
**Create Epics and Stories**
:::tip[V6 Improvement]
Epics and stories are now created _after_ architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
:::
1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat
2. Run `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`)
3. The workflow uses both PRD and Architecture to create technically-informed stories
**Implementation Readiness Check** _(Highly Recommended)_
1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat
2. Run `bmad-check-implementation-readiness` (`bmad-check-implementation-readiness`)
3. Validates cohesion across all planning documents
## Step 2: Build Your Project
Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
### Initialize Sprint Planning
Invoke the **Developer agent** (`bmad-agent-dev`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
### The Build Cycle
For each story, repeat this cycle with fresh chats:
| Step | Agent | Workflow | Command | Purpose |
| ---- | ----- | ------------------- | ------------------- | ---------------------------------- |
| 1 | DEV | `bmad-create-story` | `bmad-create-story` | Create story file from epic |
| 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | Implement the story |
| 3 | DEV | `bmad-code-review` | `bmad-code-review` | Quality validation _(recommended)_ |
After completing all stories in an epic, invoke the **Developer agent** (`bmad-agent-dev`) and run `bmad-retrospective` (`bmad-retrospective`).
## What You've Accomplished
You've learned the foundation of building with BMad:
- Installed BMad and configured it for your IDE
- Initialized a project with your chosen planning track
- Created planning documents (PRD, Architecture, Epics & Stories)
- Understood the build cycle for implementation
Your project now has:
```text
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── planning-artifacts/
│ │ ├── PRD.md # Your requirements document
│ │ ├── architecture.md # Technical decisions
│ │ └── epics/ # Epic and story files
│ ├── implementation-artifacts/
│ │ └── sprint-status.yaml # Sprint tracking
│ └── project-context.md # Implementation rules (optional)
└── ...
```
## Quick Reference
| Workflow | Command | Agent | Purpose |
| ------------------------------------- | ------------------------------------- | --------- | ------------------------------------------ |
| **`bmad-help`** ⭐ | `bmad-help` | Any | **Your intelligent guide — ask anything!** |
| `bmad-prd` | `bmad-prd` | Any | Create, update, or validate a PRD |
| `bmad-create-architecture` | `bmad-create-architecture` | Architect | Create architecture document |
| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Create project context file |
| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | Break down PRD into epics |
| `bmad-check-implementation-readiness` | `bmad-check-implementation-readiness` | Architect | Validate planning cohesion |
| `bmad-sprint-planning` | `bmad-sprint-planning` | DEV | Initialize sprint tracking |
| `bmad-create-story` | `bmad-create-story` | DEV | Create a story file |
| `bmad-dev-story` | `bmad-dev-story` | DEV | Implement a story |
| `bmad-code-review` | `bmad-code-review` | DEV | Review implemented code |
## Common Questions
**Do I always need architecture?**
Only for BMad Method and Enterprise tracks. Quick Flow skips from spec to implementation.
**Can I change my plan later?**
Yes. The `bmad-correct-course` workflow handles scope changes mid-implementation.
**What if I want to brainstorm first?**
Invoke the Analyst agent (`bmad-agent-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD.
**Do I need to follow a strict order?**
Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
## Getting Help
:::tip[First Stop: BMad-Help]
**Invoke `bmad-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
- "What should I do after installing?"
- "I'm stuck on workflow X"
- "What are my options for Y?"
- "Show me what's been done so far"
BMad-Help inspects your project, detects what you've completed, and tells you exactly what to do next.
:::
- **During workflows** — Agents guide you with questions and explanations
- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
## Key Takeaways
:::tip[Remember These]
- **Start with `bmad-help`** — Your intelligent guide that knows your project and options
- **Always use fresh chats** — Start a new chat for each workflow
- **Track matters** — Quick Flow uses `bmad-quick-dev`; Method/Enterprise need PRD and architecture
- **BMad-Help runs automatically** — Every workflow ends with guidance on what's next
:::
Ready to start? Install BMad, invoke `bmad-help`, and let your intelligent guide lead the way.
Reference in New Issue View Git Blame Copy Permalink