Playbooks · Coding tasks
Agree what to build before building it: write a short product requirements document with BMad
Written October 28, 2026 · Edited November 10, 2026
For a solo builder or small team who need others to agree on a product before building starts, write a short product requirements document (PRD) with BMad. BMad is a method of agent skills for planning and building software. The document states scope, requirements, and build stages. An epic is a large chunk of the build, made up of smaller slices. Without that agreed document in writing, the build drifts — because scope and requirements were never agreed, and every conversation adds something new.
Before you start
You need an idea clear enough to state in two or three sentences, and a list of the people who must agree on it before building starts. BMad is a method of agent skills for the full software development lifecycle, from idea to shipped code. Its planning skills include a product requirements document (PRD) skill — John, the Product Manager (bmad-agent-pm) — with three jobs: create a PRD, update one that already exists, and validate one. On v7, the PRD lands in _bmad-output, inside the active initiative's folder when one is set, and validation writes its findings to review-*.md files beside the PRD. (On v6, the skill writes the document as prd-<slug>.md, keeps a change log inside it, and files later changes as an addendum rather than rewriting history.)
A PRD earns its keep when more than one person must agree on what gets built, or when the build will run to more than one epic and the epics must not drift apart. For a solo build that fits in one epic, the PRD is overhead: write the requirements with the product-owner skill instead and start building. BMad's own planning guide draws that line, and this playbook follows it. If your idea is still vague — a problem area rather than a product — do not start with the PRD. Start with a brief: the brainstorming, idea-forging, and product-brief skills exist to turn a vague idea into something a PRD can describe.
Two versions of BMad exist side by side. The stable release is v6.12: with Node.js 20.12+, Python 3.10+ and uv installed, run npx bmad-method install in your project. The v7 preview installs a different way: two module commands. With Node.js and npm plus Git and a coding tool that supports skills, run npx skills add bmad-code-org/BMAD-METHOD/skills/core-tools --skill '*' and npx skills add bmad-code-org/BMAD-METHOD/skills/method --skill '*' — one command per module, and core tools hold the bmad setup and help skill, so every install needs them. The full install steps are on the BMad install page. The skill names and commands below are the v7 forms from BMad's documentation; the v6 forms differ, so follow the install instructions on the BMad README for the version you pick, and use the skill names that version shows you.
What "done" looks like
At the end of one sitting you have a PRD in _bmad-output that states the problem, the users, the scope, and the requirements in language the people who must agree on it can read; a validation pass recorded against it; and a handoff to the build: epics and slices written from the PRD, not from memory. Nobody has written production code yet. That is the point: the PRD is the agreement, and the build follows the agreement.
Steps
- Decide whether the document is a PRD or a brief. Ask who must agree before building starts. If the answer is "just me, and the build fits in one sitting or one epic," skip the PRD and go to the product-owner skill. If the answer names other people, or the build will span several sessions, a PRD is the right document. If the idea itself is vague, ask Mary, the Business Analyst (
bmad-agent-analyst), to write a product brief first: a brief states the problem, the audience, and the outcome, and the PRD skill takes a brief as its starting input. Starting the PRD from a vague idea produces a long document that agrees with itself and nobody else. - Install BMad and confirm the PRD skill is present. Follow the install path for your version on the BMad README. On v7, ask the
bmadskill to runbmad setup, thenbmad statusto check versions and see what to run next. The PRD skill on v7 is John, the Product Manager (bmad-agent-pm) — if your install does not offer it, the install did not complete: re-run it rather than improvising a PRD prompt of your own. The skill carries the document shape, the validation questions, and the handoff format; a freehand prompt produces a document only you recognize. - Run the PRD skill with the create intent, and hand it the brief. Ask John, the Product Manager (
bmad-agent-pm), to create the PRD with the idea and, when you have one, the product brief. Give it the constraints that actually bind the product: who uses it, what it must not do, and any deadline or platform limit that is already fixed. Do not give it a feature list and ask for prose around it: the skill's job is to turn the idea and the constraints into requirements, and a feature list handed in as fact skips the step where requirements get questioned. - Read the draft as one of the people who must agree. Read the PRD from the top, looking for three defects: requirements that no named person asked for, scope that the brief never mentioned, and sentences that two reasonable readers would understand differently. Mark each one and send the draft back through the skill with the update intent, which reconciles the change with earlier decisions before applying it. A PRD edited by hand outside the skill is not reconciled against earlier decisions, and the next reader cannot tell what changed or why.
- Run the validate intent before anyone builds from the document. The validate intent reads the PRD back against its own rules and reports gaps: missing requirements, untestable statements, and sections that contradict each other. It writes its findings to
review-*.mdfiles beside the PRD. Treat its report as a punch list, not a verdict: fix the gaps through the update intent, then validate again. A PRD that has not been validated is a draft with a confident filename. - Hand the PRD to the product-owner skill for epics and slices. The build side of BMad starts from the PRD: Sofia, the Product Owner (
bmad-agent-po), writes epic requirements and slices, and each slice is built in its own session. Do not hand the builder the brief, the chat history, or your memory of the discussion. The PRD is the single source the slices are written from; anything the PRD does not say is a question to answer through the update intent, not a gap for the builder to fill in on its own. - Close with a retrospective when the last epic lands. BMad's retrospective skill (
bmad-retrospective) reviews the finished epic against the PRD: what shipped, what changed, and what the next epic should carry forward. File the retrospective with the PRD, and record any requirement that changed during the build through the update intent. The PRD is then a record of what was agreed, what changed, and why — which is what makes the next PRD faster to write.
Check the agent's work
- Check that every requirement in the PRD traces to the brief, a named stakeholder, or a constraint you gave the skill. A requirement with no source is invented, however reasonable it reads.
- Check that the scope section names what is out of scope, not just what is in. A PRD without exclusions grows with every conversation.
- Check that the validate intent was run and its gaps were fixed through the update intent, with the
review-*.mdfindings addressed. - Check that the epics and slices name the PRD sections they come from. A slice with no PRD source is a build from memory.
- Check that later changes went through the update intent, not silent edits to the original text.
What can go wrong
- Writing a PRD for a one-epic solo build. The document costs more than the build. The planning guide's rule is the test: more than one person agreeing, or more than one epic, earns a PRD; anything smaller goes straight to requirements and building.
- Starting from a vague idea. The PRD skill cannot invent the product for you. A brief first — problem, audience, outcome — is what turns a vague idea into an input the skill can work with.
- Mixing v6 and v7 skill names. The two versions install differently and name skills differently. Follow the README for the version you installed, and do not paste a v6 command into a v7 setup or the reverse.
- Hand-editing the PRD outside the skill. The update intent is what reconciles a change with earlier decisions. Hand edits bypass it, and the next disagreement has no record to settle it.
- Building from the chat instead of the PRD. The builder follows what it is handed. Hand it the PRD, and route anything missing back through the update intent, or the build quietly diverges from the agreement.
Limits
- This workflow produces the agreement, not the product. Nothing here writes production code, and a validated PRD is not evidence the product will work.
- The PRD skill works from what you give it. A brief that omits the real constraint — a deadline, a platform limit, a person whose approval is required — produces a PRD that omits it too.
- BMad v7 is a preview release. Skill names, commands, and file layouts can move between preview releases; the README for the version you installed is the authority when this page and the installed skill disagree.
Related playbooks
- BMad v7 is a preview, not the stable release: what changes, and whether to try it before it ships
- Move a v6 BMad project to the v7 preview
- Write release notes with Claude Code, and only claim what shipped
- Have one agent write the code and a second agent check it in the background
Sources
Sources: BMAD-METHOD README, Choose a Planning Path — BMad docs, BMad documentation.
Back to: Coding playbooks hub · Also: BMad skill page · Start work on a codebase you inherited without breaking what already works