Brian
c23f23400d
* feat: streamline core to a 5-skill kernel with standalone skill modules
Core installs 14 -> 5 catalog-visible skills; atoms exit to standalone
modules; installer gains real dependency resolution; zero npm deps.
- Merge bmad-editorial-review-prose/-structure into bmad-editorial-review
(structure models JIT-loaded, new customize.toml)
- Merge bmad-review-adversarial-general/-edge-case-hunter/-verification-gap
into bmad-review as selectable lenses; hidden husk-forwarders remain at
the old IDs (no catalog rows) so gds/loop/os-utils keep working
- Move bmad-brainstorming, bmad-party-mode, bmad-forge-idea out of core to
src/standalone-skills/ as single-skill modules; add bmad-analysis bundle
module (curated dependency list over the atoms)
- Move bmad-spec into bmm (2-plan-workflows)
- Modernize bmad-advanced-elicitation: uv run, customize.toml, methods
pick offloaded to scripts/pick_methods.py (with tests)
- Delete bmad-index-docs, bmad-shard-doc (removes the tree's only external
npm dependency), and the four deprecation shims (bmad-create-prd,
bmad-edit-prd, bmad-validate-prd, bmad-create-architecture); all added
to removals.txt
- Installer: activate the dependencies field (recursive union into
selectedModules, cycle-guarded, warn on unknown), config-driven picker
visibility; core stays force-installed
- bmm module.yaml declares deps on the three atoms
- Docs updated across all locales; new reference/standalone-skills.md;
shard-doc how-tos removed
* Restore original critical wording lost in the review/editorial merges
The merges into bmad-review and bmad-editorial-review were meant to keep
the source skills' critical wording behind progressive disclosure, not
paraphrase it away. Restore what was lost:
- lens-adversarial: clueless-weasel framing, extreme-skepticism wording,
the at-least-ten-issues quota, and zero-findings-is-suspicious (the
merge had inverted this to zero-is-valid)
- bmad-review SKILL: zero-findings stance is now per-lens
- lens-edge-case: mandatory exact-order step enforcement
- lens-verification-gap: exact 'No verification gaps found.' clean line
- editorial-review: full Human/LLM reader principles restored to new
references/reader-principles.md; structure-pass HIGH-VALUE DENSITY
role, front-load-value, anti-patterns, pacing check, and length_target
assessment; prose-pass role sentence, analyze-style-first step, and
merge-overlapping-fixes rule; output summary block and min-3-words HALT
* feat(installer): promote bmad-analysis bundle to src/bmad-analysis-skills
Move the bmad-analysis bundle module out of src/standalone-skills/ into its
own src/bmad-analysis-skills root, teach the installer to resolve it there
(getModulePath, official-modules listing, isBuiltInModule helper), and
update the marketplace manifest and standalone-skills docs to match.
* refactor(bmad-review): rename edge-case lens to edge-case-hunter
Rename the lens code and reference file (lens-edge-case.md ->
lens-edge-case-hunter.md), add explicit when = "always" to the shipped
lenses, and tighten the lens-selection wording in SKILL.md.
* feat(bmad-editorial-review): configurable style guide + analysis-driven rework
Apply the workflow-builder analysis recommendations:
- Make the baseline style guide configurable: style_guide in customize.toml
now IS the baseline (default "Microsoft Writing Style Guide") instead of
an empty override slot; SKILL.md no longer hardcodes the guide.
- Inline reader-principles.md into SKILL.md and delete the reference (it
loaded on every run and was half-duplicated inline).
- Complete the customization surface: activation_steps_prepend/append,
persistent_facts (project-context glob), on_complete, and a
review_output_path scalar split out of output_preferences; add a
file:-load fallback convention.
- Ground word metrics: new scripts/word_metrics.py (stdlib, PEP 723, tests)
emits total/per-section word counts so impact estimates and the reduction
summary use exact numbers.
- Cross-pass dedup: prose pass skips CUT-tagged passages and re-attaches
fixes in MERGE'd ones; output ranks by impact with a long-tail rollup.
- Polish: HALT threshold replaced with plain outcome, duplicate LLM-reader
bullets merged, all-caps lowered, literal Overview heading added.
* fix(installer): stop cache-refresh git commands from escaping to the parent repo
Two compounding bugs let a pre-commit test run shallow-fetch and hard-reset
the developer's own repository:
1. Git spawns in custom-module-manager and external-manager inherited the
hook environment. Git exports GIT_DIR (absolute, in worktree checkouts)
into pre-commit hooks; a child git then targets the hook's repo regardless
of cwd, and treats its cwd — the module cache dir — as the work tree. The
cache refresh's 'git fetch --depth 1' + 'git reset --hard origin/main'
therefore shallowed the shared .bare and moved the checked-out branch.
New git-env.js strips repo-targeting GIT_* vars from every git spawn in
both managers, including calls that previously inherited process.env
implicitly.
2. Test suite 51 (quickUpdate dependency expansion) ran the real
CustomModuleManager lookup, which scans ~/.bmad/cache/custom-modules and
network-refreshes every cached clone — real user state. The suite now
stubs findModuleSourceByCode.
Verified by rerunning the suite with GIT_DIR pointed at the repo and a PATH
shim blocking fetch/reset/clone: 432 passing, zero blocked calls.
* De-scope standalone-skills mechanism: atoms return to core, shims reinstated
Shrink the PR to its heart — the skill merges — and defer the module
mechanics to a follow-up where all skills become module-driven:
- bmad-brainstorming, bmad-party-mode, bmad-forge-idea move back to
src/core-skills/ as ordinary core skills with their catalog rows
restored; src/standalone-skills/ and the bmad-analysis bundle module
are removed
- Installer reverted to main: standalone discovery, hidden-module
filtering, dependency resolution, manifest changes (test suites 49-51
removed with the code); the cache-refresh git fix is retained
- The four bmm deprecation shims (create/edit/validate-prd,
create-architecture) are reinstated so enterprise installs that
invoke the old IDs or carry _bmad/custom overrides keep working;
descriptions trimmed to the short husk style; their removals.txt
entries dropped (removal rides the v7 cut as their frontmatter
promises)
- marketplace.json keeps the five plugin entries with atom paths
pointing at src/core-skills/
- Docs (en/cs/fr/vi/zh) reframe the three skills as core thinking
skills; standalone-skills.md reference page removed
* Fix all findings from the max-effort adversarial review
Correctness:
- Finish the edge-case -> edge-case-hunter lens rename at every caller:
the forwarder husk, the code-review/dev-auto/quick-dev review layers,
the renderer test assertion, and the stale example path in
bmad-review/SKILL.md
- marketplace.json: ship the five core kernel skills with
bmad-method-lifecycle so its skills' bmad-review/bmad-editorial-review/
bmad-help/bmad-advanced-elicitation invocations resolve in a
marketplace install
- pick_methods.py / word_metrics.py: force UTF-8 stdout (Windows locale
code pages crashed on the catalog's arrows and CJK headings)
- word_metrics.py: pair fences CommonMark-style so 4-backtick fences can
embed 3-backtick examples without corrupting sections; count CJK
characters as words
- pick_methods.py: validate --extra entries are JSON objects (was an
uncaught AttributeError); read catalogs with utf-8-sig (BOM'd CSVs
silently blanked every num)
- bmad-spec: activation now resolves {output_folder} (which the
Workspace uses) instead of the unused {planning_artifacts}; drop the
stale core-only-installs comment
- Editorial husks: pin the legacy output contracts (three-column table /
Document Summary report and exact empty-state lines) like the review
husks do
- PRD shims: advertise the real bmad-prd customize keys
(validation_checklist_template, prd_output_path, run_folder_pattern,
finalize_reviewers) instead of three that don't exist
- bmad-prd: add the forwarded-activation clause its shims rely on
(ported from bmad-architecture)
- Locale workflow-maps (fr/cs/vi/zh): add the bmad-spec Phase-2 row the
English map gained, which every locale's core-tools note points at
- git-env.js: also strip GIT_CONFIG_PARAMETERS and the
GIT_CONFIG_COUNT/KEY_n/VALUE_n family; pass gitEnv() to the three npm
install spawns whose transitive git calls inherited hook vars
Consistency:
- brain.py --extra overlay now replaces-by-name like pick_methods.py
(same customize.toml additional_* semantics across sibling skills),
with a regression test
* Fix prettier formatting in marketplace.json
* Apply valid CodeRabbit findings
- brain.py: catch malformed --extra overlays (bad JSON, non-array root,
non-object entries) into the clean error path instead of a raw
traceback, with a regression test; read catalogs and overlays with
utf-8-sig; normalize ALL CSV fields (required ones were unstripped and
could arrive as None from short rows)
- brain-selector: clamp the random-technique count to what the pool can
supply so the Total badge matches the actual draw (template +
regenerated assets/brain-selector.html)
- bmad-editorial-review: word_metrics command now uses the explicit
{skill-root}/ prefix
- resolve_party.py / resolve_personas.py: custom member overrides now
start from the installed entry, so omitted fields (icon, title,
description, module, team) survive; non-string member tokens land in
unresolved instead of raising TypeError; party's member loop gains the
isinstance guards its personas twin already had
- bmad-brainstorming: fix the SKILL.md claim that headless is the only
context for self-generated ideas (autonomous mode is interactive);
autonomous mode honors user-supplied techniques before self-selecting
- Docs: drop duplicate 'only' in the spec template; align zh-cn
forge-idea's bmad-review description with the English wording
* Create only the output folder at install time
bmm no longer pre-creates planning_artifacts, implementation_artifacts,
and project_knowledge — the last of which put an empty docs/ at every
project root. Skills create those lazily on first write. core now
declares {output_folder} in its directories block, which was previously
created only as a side effect of the artifact folders nesting under it.
13 KiB
title, description
| title | description |
|---|---|
| Getting Started | 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, forge idea, product brief or PRFAQ (optional) |
| 2 | Planning | Create requirements and design PRD, UX, SPEC |
| 3 | Solutioning | Design architecture spine or detailed project or system architectures |
| 4 | Implementation | Build epic by epic, story by story with quick dev or automated epic delivery |
Open the Workflow Map 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:
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.
:::
Phase 1: Analysis (Optional)
All workflows in this phase are optional. Not sure which to use?
- brainstorming (
bmad-brainstorming) — Guided ideation - forge-idea (
bmad-forge-idea) — Pressure-test an idea until it hardens or dies cheaply - 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 your product concept customer-first
Phase 2: Planning (Required)
For BMad Method and Enterprise tracks:
- Run
bmad-prdin a new chat — state your intent (Create / Update / Validate) or let the skill ask - Output:
prd.md,addendum.md,.memlog.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
- Invoke the Architect agent (
bmad-agent-architect) in a new chat - Run
bmad-architecture(bmad-architecture) - 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. :::
- Invoke the PM agent (
bmad-agent-pm) in a new chat - Run
bmad-create-epics-and-stories(bmad-create-epics-and-stories) - The workflow uses both PRD and Architecture to create technically-informed stories
Implementation Readiness Check (Highly Recommended)
- Invoke the Architect agent (
bmad-agent-architect) in a new chat - Run
bmad-check-implementation-readiness(bmad-check-implementation-readiness) - 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:
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-architecture |
bmad-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 (#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.