bmod.toml
[bmod]
code = "core-tools"
version = "6.13.0-next"
update_source = "github:bmad-code-org/BMAD-METHOD/skills"
skills = [
"bmad",
"bmad-advanced-elicitation",
"bmad-brainstorming",
"bmad-customize",
"bmad-deep-recon",
"bmad-facilitate",
"bmad-forge-idea",
"bmad-ingest",
"bmad-party-mode",
"bmad-review",
"bmad-shard-pro",
]
required_skills = ["bmad"]
pre_install_message = '''
Agile AI-Driven Development. Powered by BMad Core and a growing module ecosystem.
🌟 100% free. 100% open source. Always. No paywalls. No gated content. Knowledge shared, not sold.
🐍 REQUIRED: uv (https://docs.astral.sh/uv/) runs the Python scripts BMad skills rely on (`uv run <script>`) and provisions the interpreter itself. Without it, `bmad setup` cannot run and skills that use scripts halt. If it's not set up yet, ask your AI agent to "install and set up uv for me".
🌐 CONNECT:
Website: https://bmadcode.com/
Discord: https://discord.gg/gk8jAdXWmj
YouTube: https://www.youtube.com/@BMadCode
X: https://x.com/BMadCode
Facebook: https://facebook.com/@BMadCode
⭐ SUPPORT THE PROJECT:
Star us: https://github.com/bmad-code-org/BMAD-METHOD/
Donate: https://buymeacoffee.com/bmad
Corporate sponsorship and speaking inquiries: contact@bmadcode.com
'''
post_install_message = '''
BMad is ready. You can ask bmad for help or suggestions at any time, and if you add modules or want to check for updates in the future, just ask the bmad agent to update.
'''
help/advanced-elicitation.md
# Advanced elicitation
Open this when the user asks what `bmad-advanced-elicitation` is for, how it differs from the version in earlier BMad releases, how to start it or aim it, which methods it runs, how to set default methods, or whether a plain "push harder" would do.
## What it is for
It pushes a piece of work off its first answer and proposes one revision. A model's first draft is its most likely draft: centered, agreeable, biased toward adding. The skill runs critique methods against the work, such as a pre-mortem, steelmanning, first principles or subtraction, and merges what they find into changes the user accepts or rejects. Nothing changes until the user accepts.
The work can be anything in the conversation: a choice the model just made, a section of a document, a whole PRD or plan, or a draft the user wrote.
## What changed from the earlier version
The version that shipped from v2 through v6 offered a menu of five methods from a catalog of 71 in 12 categories, ran each chosen method itself in the conversation, and stopped for Apply or skip after every method, so a session took many turns and the author critiqued its own reasoning. The rebuild:
- Starts with one command and returns results in the same turn; a session is two turns, the call and the decision on the revision.
- Runs each method as an independent reader with a short brief, so the method is not anchored to the first answer and its reasoning stays out of the conversation.
- Merges every push into one revision of numbered, tagged changes instead of one Apply per method, and leaves decisions already made alone.
- Starts only when named, so it no longer fires on any critique request.
- Was tested in Claude Code and Codex, where blind judges ranked it above the old version and above a plain "push harder" on sections and documents.
- Keeps 48 methods in six directions; renamed methods still answer to their old names. The customization key `preferences` is now `persistent_facts`.
## Starting and aiming it
It starts only when named. "Push harder" or "pre-mortem this" without the name does not start it.
- "advanced elicitation" alone pushes what the last exchange was about, at its own size. If the model just suggested Postgres, it pushes that choice, not the whole architecture, while still using everything in the conversation.
- To aim it at something bigger or different, say so: "advanced elicitation on section 4", "advanced elicitation on docs/prd.md".
- To choose the methods, name them: "advanced elicitation with pre-mortem and red team". Named methods run as named.
- Other skills, such as the planning skills and agent personas, can call it by name on what they just drafted.
It starts work in the same turn. Its first message names the target and the methods it chose, so the user can stop it if the target is wrong.
## What runs when the user names no methods
Three pushes, each from a different direction: what is wrong, what is missing, the premise, simplicity, the future, the other side.
- The method that best fits where the work looks weak.
- A wildcard chosen to take the work somewhere unexpected, from any of the methods.
- For a single choice or a few lines, an open push to reconsider the work with everything the conversation holds. For a section or document, a second method against another weak spot.
Each method runs as an independent reader that sees only a short brief, never the author's reasoning, so it is not anchored to the first answer. The brief lists what is already decided, so the readers do not reopen it.
## What comes back
One message: a headline from each push, the revision as numbered changes tagged with the push behind each, decisions only the user can make, and any findings set aside. The user applies all, some by number, rejects, reruns a push with direction, or asks for another round. A typical session is two user turns: the call, then the decision.
Each session keeps a report with every round's full revision and findings under `{output_folder}/{active_initiative}/elicitation-<topic>/`, or under `{output_folder}/` for loose work.
## When a plain "push harder" is enough
Pushing a section or document takes several minutes, because each reader works through it on its own. On one quick choice with a strong model, asking it to push harder and consider alternatives is often as good and much faster, though less consistent. Recommend the skill when the work matters, when it is a section or document, or when the model tends to keep its first answer when asked to reconsider.
## Methods and defaults
- The catalog holds 48 methods in the six directions, 22 of them recommended. The user can ask the skill to list them, or to list one direction.
- Methods renamed in the rebuild still answer to their old names.
- Default methods for every call are set with `bmad-customize` as `default_methods`. A team file and a personal file both add to the list, so both sets run.
- A team can add its own methods with `additional_methods` and use them as defaults. See `help/customization.md` for how overrides merge.
help/customization.md
# How customization works
Open this when the user asks where an override goes, how it merges, why it is not applied, or how to change central config. To change one skill or agent, recommend `bmad-customize`. For team-wide rules see `help/team-adoption.md`.
## The layers for one skill
A skill is customizable only if its folder holds a `customize.toml`, which lists every field that can change. Updates overwrite it, so nobody edits it. Overrides live in `{project-root}/_bmad/custom/`, named after the skill folder.
| Priority | File | For | Committed |
|---|---|---|---|
| 1 (wins) | `<skill>.user.toml` | One person: tone, private facts | No |
| 2 | `<skill>.toml` | The team: policy, conventions | Yes |
| 3 | the skill's `customize.toml` | Shipped defaults | With the skill |
`bmad setup` writes `_bmad/custom/.gitignore` with `*.user.toml` when none exists.
## Merge rules
The value's shape decides the merge. The field name does not.
| Shape | Rule |
|---|---|
| Scalar | The override wins. |
| Table | Merged key by key, by these same rules. |
| Array of tables where every item has `code`, or every item has `id` | A matching key replaces that item. A new key appends. |
| Any other array | Appended: shipped, then team, then user. |
## Limits
- An override cannot remove a shipped item. Replace a keyed item with one that does nothing.
- It cannot change step logic or any field `customize.toml` does not list. Never invent a field. Offer `activation_steps_prepend`, `activation_steps_append` or `persistent_facts` instead, or a feature request.
- On an agent skill, `agent.name` and `agent.title` are metadata. Overriding them does nothing.
- Write only the changed fields. A full copy of `customize.toml` blocks later shipped defaults.
## Agent or workflow
The top table in `customize.toml` is `[agent]` or `[workflow]`. Override fields go under the same table. A rule for every workflow an agent runs goes on the agent skill: persona, style, principles, facts, menu. A rule for one workflow goes on that workflow skill: templates, output paths, `on_complete`, step hooks.
## Central config
It holds `[core]` values such as `output_folder`, module answers under `[modules.<code>]`, and optional `[agents.<code>]` tables that add an agent of the user's own or add details such as `team` to an installed one. An installed agent's name, title, and icon come from its own skill and its override file, not from here. Three files merge by the same rules, highest first:
1. `_bmad/custom/config.user.toml`: personal. `bmad setup` writes user answers here. Not committed.
2. `_bmad/custom/config.toml`: team pins. Written by hand only. Committed.
3. `_bmad/config.toml`: created by `bmad setup`, which writes team answers here.
All three may be hand-edited. `bmad setup` never changes an existing value, so to change an answer, edit its key in the file `bmad setup` reports for it. `bmad-customize` does not write central config: help the user edit the TOML.
## Check the merged result
`bmad-customize` shows the merged result after it writes. `_bmad/scripts/resolve_customization.py` (one skill) and `resolve_config.py` (central config) print the merged values as JSON. If a script is missing, recommend `bmad setup`.
## An override is not applied
1. The file is in `_bmad/custom/` and named exactly after the skill folder.
2. The TOML parses. The resolver errors and names a broken file.
3. Fields sit under `[agent]` or `[workflow]` and exist in `customize.toml`.
4. The shape matches, and a replaced item uses the same `code` or `id`.
5. No user file overrides the team value.
6. `uv` runs. Without the resolver, many skills use shipped defaults.
## Reset
Delete the override file, or the one field. The skill uses shipped defaults on its next run.
help/facilitate.md
# Facilitated documents from templates
Open this when the user asks what `bmad-facilitate` can write, how to call it without an agent, or how a team adds its own document templates.
## What it is for
It coaches the user through one document from a template, and later updates or validates it. Any document works, software or not. The user supplies what only they know; the skill reads their inputs, finds facts, reviews the draft and polishes it. Rigor follows the stakes the user states, from a hobby project to regulated or contracted work. A PRD or product brief goes to John (`bmad-agent-pm`).
- Coaching is the default: a conversation that steers back to the sections still unfilled.
- The fast path asks what the template requires plus up to three high-impact questions, drafts with the rest tagged as assumptions, then offers to walk the user through those.
- It skips questions only when the user says headless or autonomous, or hands over material and asks for the document. It then fills gaps with tagged best guesses.
- Unfinished runs resume.
- With no fitting template it builds a structure for the document type, says so, and at close offers to save it as a template.
## Templates the modules ship
Core tools ships no templates. Each module's templates are in `templates` in `knowledge.py`'s output once it is installed, so recommend a module when the user wants one it holds:
| id | Module | Recommend when |
|---|---|---|
| `decision-record` | Method | Any decision worth recording: context, options, choice, consequences. |
| `postmortem` | Method | Something went wrong and the team needs causes and actions, blamelessly. The timeline is drawn as a diagram, and it also writes a customer notice when customers were told. |
| `security-review` | Method | Reviewing a system against the OWASP Top 10 or STRIDE. The standard's items drive the questions; another standard needs its rows added to the catalog first. |
| `proposal` | Founder | Asking for money, time or approval: a grant, a bid, an internal request. The reader's own guidelines replace its headings. |
| `pitch-deck` | Founder | A talk or pitch that needs a story and slides. It always renders as an HTML slide view unless the team turned views off. |
| `character` | Creative Intelligence Suite 0.4.0 and later | A fictional character for a story, game or campaign. The coach proposes options, and each character gets its own one-page HTML sheet unless the team turned views off. |
Method also ships John's planning templates and `brd`, which Method's own help covers.
## Listing what it can coach
When the user asks what it can coach them through or which templates exist, list them instead of answering from this file, because `templates` in `knowledge.py`'s output covers only what installed modules ship, and a team's own templates appear nowhere else.
1. Run `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill <bmad-facilitate's folder> --project-root {project-root} --key workflow` and take `template_libraries`. Do the same for each installed agent whose `customize.toml` sets it. `bmad-ingest`'s library holds another kind of template, so leave it out.
2. Fill `{project-root}` and `{skill-root}` in those entries, then run `uv run {project-root}/_bmad/scripts/list_templates.py <entries> --root <folder>`, this skill's entries first, with one `--root` for each skills folder the host has active, project folders first.
3. Group `templates` by `source`, saying what each is for and naming its `extensions`. Name anything `shadowed`, `orphaned` or `unreachable`, and follow any `tool_sources`. The two default folders showing as `missing` is normal.
## Calling it directly
The user says what they want in plain words: the topic, a template (an id, a file path or a URL), an output folder, the stakes, and whether to run without questions. For example: "bmad-facilitate coach me through a security review covering the OWASP Top 10, output to docs/owasp". It infers what is missing. "Update" or "validate" with a document's path revises it or reviews it without changes. A document written without a template works too: it finds the closest template and uses that as the bar, then offers suggestions or a reshape.
## A team's own templates
Templates are files in `_bmad/custom/facilitate-templates/`. For settings, recommend `bmad-customize` on `bmad-facilitate`; the team file `_bmad/custom/bmad-facilitate.toml` is committed so everyone gets it.
- Add a template: a file in that folder with `template` and `description` in its frontmatter, and any rubric beside it. A `companions` comment asks for more files beside the document. A plain markdown file of headings works; each heading becomes a required section. A bare `## Table of Contents` heading after the title makes the skill fill and check one.
- Replace or edit a shipped template: copy it from `doc-templates/` in the record of the module that ships it into that folder and keep its `template` id. The project's copy wins.
- A module adds templates through `doc-templates/` in its record folder; no setting is needed. An `agents:` frontmatter list names the skills that run one, so help can say who offers it.
- Keep personal templates for every project in `~/.bmad/facilitate-templates/`. The project's folder is searched first.
- Use a shared library: add a folder or a pinned GitHub URL to `template_libraries`, in the `.user.toml` when it is private. Only sources the team controls, because a template overrides the skill.
- Add to a template without copying it: a file with `extends: <id>` in its frontmatter, holding the extra sections and comments. It applies on every run of that template, and updates to the original still arrive. For example, an `extends: proposal` file at Fernhollow Bank, a fictional company, adds a required Approval Track with three fixed choices and an empty Review Comments section.
- An organization can keep templates and extensions in its own modules, one per program if it likes, such as `bmod-fernhollow-cards`. A module adds new ids or extends existing ones; only a project's folder or a library replaces an id.
- `style` sets the look of every rendered view; `html_view` is `offer`, `always` or `never`. A template's `view` can name an HTML file beside it, filled the same way every time, and a `view` comment instead has a page written for each document, from that file as a starter or from the brief alone. The coaching stays in the markdown template.
The file format and worked examples are at `https://docs.bmad-method.org/customize/write-a-document-template/`.
help/help.md
# BMad Core Tools knowledge
This document covers the skills of the `core-tools` module: what each one is for and when to recommend it.
## How the core tools fit
The core tools belong to no phase and no path. Each stands alone and works with or without any other module. Suggest one whenever it would help: before, during, after, or entirely outside another module's flow. Never present one as a required step. A project may hold only some of these skills: recommend from what is installed.
## Initiatives
An initiative is one body of work of any kind: a product, a feature, a book, a set of art assets. Its folder under `output_folder` holds what every module's skills write for that work. `active_initiative` under `[core]` in `_bmad/custom/config.user.toml` names the folder in use; the file is personal, so each person can work on a different one. With none active, work is written loose to `{output_folder}/`, and some skills first ask whether it belongs to an initiative. The `bmad` skill shows, switches, creates, or clears the active initiative. What goes inside the folder is up to each module: its help says.
## Start here
- No idea yet, or wants more and better ideas on a topic → `bmad-brainstorming`.
- Has an idea and is not sure it holds up → `bmad-forge-idea`.
- Needs facts from outside before deciding (a market, a technology, competitors, what users say), has a research report to make usable, or wants their own code researched (how something works, why it is built that way, the code a ticket depends on) → `bmad-deep-recon`.
- Needs to write a document: a decision record or ADR, a postmortem, a proposal or grant application, a security review or threat model, a pitch deck or talk, or any document from the team's own template → `bmad-facilitate`. A PRD or product brief goes to John (`bmad-agent-pm`).
- Has a piece of work and wants it better:
- They have a draft in front of them (theirs or the model's) and want it pushed further, or want a critique method run on it → `bmad-advanced-elicitation`. It starts only by name: tell them to say "advanced elicitation", with the method if they have one in mind.
- They ask for a review of a diff, a file, or a document → `bmad-review`.
- They want several points of view arguing it out, a roundtable, or a focus group of their customers → `bmad-party-mode`.
- Has large or raw input:
- A transcript, a chat or email thread, a voice memo, or a long document they want what matters from (decisions, action items, key points) → `bmad-ingest`.
- A long document the team will keep and agents will work from (a large PRD, architecture or manual), or one already sharded that they want to change → `bmad-shard-pro`.
- About to start a PRD, brief, architecture or tickets with large inputs: suggest preparing them first, raw inputs through `bmad-ingest` and long documents through `bmad-shard-pro`, so the planning skill reads short notes and only the parts it needs.
- A sharded document is the input to another skill: give that skill the folder's main file, named after the folder, which links to every shard.
- BMad itself needs attention:
- Something was installed or updated, or a skill reports that BMad is not set up or a BMad script was not found → `bmad setup`.
- "What do I have, and is it current?" → `bmad status`.
- Which initiative is active, or they want to switch, create, or clear one → `bmad`.
- They want a skill or an agent to behave differently, or to use the team's template → `bmad-customize`.
- They ask what a BMad module is or how to make one → `help/modules.md`.
## The skills
| Skill | For | Good to know | Writes |
|---|---|---|---|
| `bmad-brainstorming` | A coached session that pushes well past the obvious ideas. | The user picks who supplies the ideas: themselves, both, or the skill alone. It does not judge ideas until asked to converge. Sessions resume. | `{output_folder}/{active_initiative}/brainstorm-<topic>/`, or under `{output_folder}/` for loose work, with `brainstorm.html` and, on request, `brainstorm-<topic>.md`: the chosen ideas, ready as input to any installed planning skill. |
| `bmad-forge-idea` | Questions one half-formed idea hard until the user can act on it or drop it. | Any idea, not only products, including a change to an existing project. It ends hardened, killed, or clearer, and all three are good outcomes. Not for generating ideas or for outside facts. | `{output_folder}/{active_initiative}/forge-<slug>/`, or under `{output_folder}/` for loose work, with `forge-report.html` and, when the idea hardens, `forge-<slug>.md`: the surviving decisions, ready as input to any installed planning or build skill. |
| `bmad-deep-recon` | Research that serves a decision, with cited sources found now, never from memory. | It can draft a prompt for the user's own research tool, process a finished report, or run the research here. It can also choose between candidates, or answer questions about this repository from its code and git history. | `{output_folder}/{active_initiative}/research-<topic>/`, or under `{output_folder}/` for loose work, with `brief.md` and `research-<topic>.md`, which is input for whatever skill acts on the decision. Codebase research also writes each ADR the user approves, beside the code it governs. |
| `bmad-facilitate` | Coaches the user through one document from a template library, then updates or validates it later. | Its templates come from installed modules: Method's `decision-record`, `postmortem` and `security-review`, Founder's `proposal` and `pitch-deck`, and the Creative Intelligence Suite's `character`, from CIS 0.4.0. A team adds or replaces templates and adds rules to shipped ones. Rigor follows the stakes the user states. Unfinished runs resume. With no fitting template it builds a structure and offers to save it. | `{output_folder}/{active_initiative}/<id>-<slug>/`, or under `{output_folder}/` for loose work, with `<id>-<slug>.md`, `.memlog.md`, review files and, when rendered, `<id>-<slug>.html`. |
| `bmad-advanced-elicitation` | Pushes a draft off its first answer and proposes a revision. | It names the draft and where it is weak and starts right away: a best-fit critique method and a wildcard (pre-mortem, steelman, first principles, red team, and more) as independent readers, plus an open push for a single choice or a second method for a document, then one proposed revision with each push's findings. Nothing changes unless the user accepts. It starts only when named, and a method named when invoking it runs straight away. | `{output_folder}/{active_initiative}/elicitation-<topic>/`, or under `{output_folder}/` for loose work, with each push's findings and a report of every round. The work itself changes only where the user accepts. |
| `bmad-review` | Independent review lenses over any diff or document: adversarial, edge cases, verification gaps, structure, prose. | It runs only when the user asks and says "review". Acting on earlier findings is a change, not a review. No severity ranking. | The report in chat, or a file when the project sets a report path. |
| `bmad-party-mode` | A group conversation between agents or personas, with the user in the room. | It works alone or beside any skill. Custom parties, a default party, and memory are all configurable, and a module can ship a cast. It debates and does not verify. | On request, a keepsake `{output_folder}/{active_initiative}/party-<slug>/party-<slug>.html`, or under `{output_folder}/` for loose work. Memory under `{output_folder}/party-mode/memories/`. |
| `bmad-shard-pro` | Makes a long markdown or text document cheap for an agent to navigate: leaves it, adds a contents list, or splits it word for word into shards. | It may recommend not splitting, and never rewrites content. Later changes go through the skill. | In the document's own folder: a main file named after the folder that links to every shard, the shards, and the frozen original in `.source/`. |
| `bmad-ingest` | Turns raw input into a cited note an agent or person acts on instead of the raw: decisions, action items, open questions, key points. | The note's shape comes from a template; teams and modules add their own. Every item points back to the raw, and a review pass checks it. Other skills can call it on their inputs. | The original, unchanged, in `{output_folder}/raw/`; the note in the calling skill's folder, such as a PRD's `sources/`, else `{output_folder}/notes/`. |
| `bmad-customize` | Changes how an installed skill or agent behaves without editing it: persona, standing facts, templates, output paths, steps on completion. | Team overrides are committed and shared; personal ones are not. It offers only what the target skill exposes. Central config is edited by hand. | `{project-root}/_bmad/custom/{skill-name}.toml` for the team, `{skill-name}.user.toml` for one person. |
## `bmad`: setup, status, and help
- `bmad setup` creates and repairs `{project-root}/_bmad`, including the shared scripts other skills call, and asks each installed module's new configuration questions. Recommend it after anything is installed or updated.
- `bmad status` changes nothing. It reports what is installed, what is missing or out of date, and the one command to run next.
- Either takes a module code, such as `bmad setup core-tools`, to cover that module only.
- To add a module that is not installed, such as the Test Architect, run `npx skills add bmad-code-org/bmad-method-test-architecture-enterprise`, then `bmad setup tea`.
- BMad is installed per project. To use it in another repository, run `npx skills add bmad-code-org/BMAD-METHOD` there, then `bmad setup`.
## More detail
This document should be enough to route the user and say what to do next. Each topic file below sits in this folder and goes deeper on one subject. Read one only when the question is about that subject, using the path the knowledge script lists for it. For how one skill behaves in detail, that skill's own files are the last resort.
| Topic file | Read when the user asks about |
|---|---|
| `help/advanced-elicitation.md` | How to start and aim `bmad-advanced-elicitation`, what it runs when no methods are named, what comes back, default and custom methods, when a plain "push harder" is enough. |
| `help/party-mode.md` | What party mode is good for alone or with other skills, custom parties, the default party, memory, parties that come with a module. |
| `help/research.md` | Getting the most from `bmad-deep-recon` and which of its services to use. |
| `help/facilitate.md` | What `bmad-facilitate` can write and how to list every template available here, so open it before saying what the user can be coached through. Also its shipped templates, calling it directly, a team's own templates and extensions. |
| `help/customization.md` | How overrides work: team or personal file, how they merge, central config, an override that is not applied, resetting. |
| `help/team-adoption.md` | Making a whole team's BMad follow shared rules, tools, templates, and publishing steps. |
| `help/ingest.md` | Processing transcripts, threads, recordings or long reports, ingest's templates and adding them, where the original and the note go, ingest inside a PRD or other work, sensitive recordings. |
| `help/shard-pro.md` | Whether to shard a document, contents list or split, how a sharded document works, `.source/`, changing one, handing one to another skill. |
| `help/modules.md` | What a BMad module is, each file in one, a single-skill module, a module that only ships personas and parties, building one. |
## When this document is not enough
For a `core-tools` question this document, its topic files, and the installed skills cannot answer, fetch the documentation site at `https://docs.bmad-method.org/` and follow the pages relevant to the question. The source repository it links to is the final authority on how anything actually behaves.
help/ingest.md
# Raw input with ingest
Open this when the user asks how to process a transcript, thread, recording or long document, where ingest puts things, how its templates work, or how to use it inside other work.
## When to suggest it
- The user has a meeting transcript, a chat or email thread, a voice memo, or a long report and wants what matters in it: decisions, action items, open questions, key points.
- The user is about to start a process, such as a PRD, a brief, an architecture or Sofia's tickets, and has large raw inputs. Ingesting them first means the planning skill works from short, cited notes instead of re-reading hours of transcript, and every later session starts from the same notes.
- A skill the user is working with asks for inputs and they hand it a raw transcript. The skill can pass it through ingest and link the note.
For a long document the team will keep and agents will work from, such as a PRD or an architecture, suggest `bmad-shard-pro` instead: ingest pulls out what matters, shard pro makes the whole document easy to navigate.
## What it produces
- The original, unchanged, in `{output_folder}/raw/`, so the note can link it by a relative path that holds in source control. An original already inside the project stays where it is.
- A note in the folder of the work it serves, such as a PRD's `sources/` folder, else `{output_folder}/notes/`. Every item in the note points to where it sits in the raw: a timestamp, a section or a message. Owners and dates appear only when the raw states them, and what the raw leaves unclear is listed as unclear.
- Before it finishes, a review pass checks the note against the raw for anything missed or misstated.
When the note feeds another document, that document links the note, and the note links the raw.
## Templates
The note's shape comes from a template, picked by its description or named by the user.
- Core tools ship `meeting`, `thread`, `voice-memo`, `document` and `one-on-one`.
- The BMad Method adds `standup`, `retrospective`, `sprint-review`, `discovery-workshop` and `user-interview`. Its `retrospective` is for a retro meeting; reviewing a finished epic is `bmad-retrospective`.
- A team adds or replaces templates in `_bmad/custom/ingest-templates/`, a person adds their own for every project in `~/.bmad/ingest-templates/`, and any module can ship some. A project's template wins over a personal one with the same id. A template can also extend another, such as a sales call with a team's qualification headings.
## Settings
Change where originals or notes go, or add a template library such as a GitHub folder, with `bmad-customize`. Recordings that hold private material should go to a raw folder outside source control, set once for the project.
It can run with no one present, for example started by an inbox watcher: it asks nothing and ends with a short summary of the note and raw paths.
help/modules.md
# BMad modules
Open this when the user asks what a BMad module is, what is in one, how to make or share one, or how to package agents and parties for others.
## What a module is
A module is a set of skills that belong together, plus one folder that tells `bmad` about them. There is no installer plugin, registry, or build step. A module is installed with `npx skills add <owner>/<repo>`, and `bmad` finds it on its next run. For example, add the Test Architect with `npx skills add bmad-code-org/bmad-method-test-architecture-enterprise`, then run `bmad setup tea`. In return the module gets setup and config questions, help that `bmad` answers from, agents and parties in party mode, dependency prompts, and update checks.
## The module folder
One skill folder named `bmod-<code>`, for example `bmod-method`. Nobody runs it; `bmad` reads it. Its files:
| File | What it is |
|---|---|
| `bmod.toml` | The module record, under a `[bmod]` table: the module's code, version, where updates come from, the list of its skills, the skills it requires or recommends, and any questions `bmad setup` should ask. |
| `SKILL.md` | A stub that marks the folder as a skill so it installs with the others. It says never to invoke it. |
| `help/help.md` | What `bmad` reads to guide users: what each skill is for, when to recommend it, what comes next. Written for an agent, short. |
| `help/<topic>.md` | Optional deeper files on one subject each. `help.md` says what each covers, and `bmad` opens one only when a question needs it. |
| `roster.toml` | Optional. The personas the module offers and the parties they form, for `bmad-party-mode` and any skill that casts personas. |
| `retired.toml` | Optional. Skills the module no longer ships: `renamed` as `{ from, to }` pairs and `removed` as names. After an update, `bmad setup` offers to delete old copies still installed and moves a renamed skill's `_bmad/custom/` files to the new name. A retired name is never reused. |
## Install messages
A module record can carry two messages in `[bmod]`, shown each time the module is installed or updated through `bmad`. An empty or missing message is not shown.
- `pre_install_message`: shown before the install or update, read from the module's source. Use it for what the module needs, such as a tool to install first.
- `post_install_message`: shown after the install or update, once setup has run. Use it for where to start.
## Each skill in the module
Every member skill carries its own small `bmod.toml` with a `[skill]` table naming its module folder and source. It can also list skills that this one skill requires or recommends. A skill belongs to one module. Depending on a skill from another module is fine.
## A module that is one skill
A standalone skill can be its own module: one `bmod.toml` holding both `[bmod]` and `[skill]`, with no separate `bmod-` folder. That is how a single skill brings its own config questions and help.
## A module that only adds personas and parties
A module with no skills is valid. A `bmod-<code>` folder holding `bmod.toml`, the stub `SKILL.md`, `help/help.md`, and a `roster.toml` is enough to distribute a cast.
- A roster member has a `code`, `name`, `icon`, `title`, and a `persona` paragraph. A member with a `skill` is an agent and appears only while that skill is installed. A member without one is a guest, available to parties.
- A roster group is a party: an `id`, a `name`, a `scene` describing how the room behaves, and its `members` by code.
- Once installed, the personas and parties appear in party mode with no setup. For a cast used in one repository or one team, a party saved through customization is simpler (`help/party-mode.md`).
## Setup and config questions
A module can declare questions in its `bmod.toml`. `bmad setup` asks them once: a team answer goes to the committed `_bmad/config.toml`, a personal answer to `_bmad/custom/config.user.toml`. A skill reads an answer without needing to know which file holds it.
## Building one
The BMad Builder module has skills for authoring modules, agents, and workflows. Recommend it when installed. Otherwise the file list above is the whole contract, and an existing `bmod-*` folder is a working example to copy.
help/party-mode.md
# Party mode
Open this when the user asks what `bmad-party-mode` is good for, how to use it with other skills, or how parties, memory, and sharing a party work.
## What it is for
Several distinct voices argue a question out with the user in the room, so an angle surfaces that one voice would miss. It works alone or beside any other skill, at any point. It debates; it does not verify facts or rank findings.
- Before planning: "get the team's take on this idea" before writing a brief or a spec.
- Mid-decision: two options for a stack or a scope cut, argued by the people who would live with each.
- On a draft: have the room react to a PRD, a design, or a plan, then carry the best objections back to the skill that owns the document.
- A focus group: a panel of customer personas reacts to a feature or a pitch.
- After the work: a team discussion of what a finished epic taught.
- For its own sake: a writers' room, a debate, a panel of invented experts on any topic.
Other skills can pull the same cast in. `bmad-brainstorming` mentions party mode when it is installed, `bmad-advanced-elicitation` gives an installed agent's persona to a push that needs that voice, and `bmad-forge-idea` uses the same personas and parties as its challengers.
## Who is in the room
- The default room is the installed agents. With none installed, a shipped party or a cast the user names inline ("party mode with a skeptical CFO and a first-time user") works.
- A party is a saved cast with a scene that sets how the room behaves. Two ship with the skill: `code-review-crew` and `anti-consensus-club`.
- An installed module can bring its own personas and parties. They appear in party mode as soon as the module is installed, with no setup.
- The user can set which party opens by default (`default_party`), or name one when starting.
## Custom parties
The user can tell party mode to help define a party: "party mode, create a new party", or "build a focus group from these interview notes". It drafts the personas with the user and saves them as a customization:
- In the user's own customization, for a personal party.
- In the team's committed customization, so the whole organization gets the party on pull.
It can also save someone who joined a session on the fly.
## Memory
- A party can remember earlier sessions as a short log of outcomes and memorable moments, not a transcript.
- The default room remembers unless memory is turned off. A saved party remembers only when its memory is turned on. Shipped parties start fresh each time.
- Memory is toggled through customization, for the default room and per party. To wipe it, delete the party's folder under `{output_folder}/party-mode/memories/`.
## Independent voices
One model voicing every persona tends to make them agree. When divergent views are the point, such as a review or a focus group, recommend running each persona as its own agent ("party mode with subagents"). It costs more tokens and time.
## Sharing a party as a module
To distribute personas and parties beyond one repository, package them as a BMad module. A module with a `roster.toml` and no skills is valid: it adds guests and parties to party mode for everyone who installs it. See `help/modules.md`.
help/research.md
# Research with deep recon
Open this when the user asks how to get the most from `bmad-deep-recon` or which of its services to use.
## Start from the decision
Every run serves a decision: enter a market, pick a library, scope a product. Have the user state it first. When the idea itself is still loose, recommend `bmad-forge-idea` before any research.
## Which service
| Service | Recommend when |
|---|---|
| Draft: writes a prompt for the user's own deep-research tool | The user subscribes to ChatGPT, Gemini, Perplexity, or similar. It is the cheap option and often covers more public sources. |
| Process: turns a finished report into a short cited summary | The user has any report, from a tool or an analyst. Draft then Process is the usual pairing. |
| Run: researches here with parallel web searches | The user wants results in one sitting, or the research needs sources only this session can reach. It costs tokens and minutes and needs web access. |
## What to tell the user
- It can go quick or deep: a quick pass for a narrow question, a deep pass with stronger verification when the decision is costly to reverse. The user just says so.
- "Help me choose between A and B" works with any research type. It agrees the requirements first and ends with a pick, a runner-up, and the strongest argument against the pick.
- Research types cover market, domain, technical, competitive, user voice, and academic literature. A team adds its own through `bmad-customize`.
- Conclusions come only from sources retrieved during the run, with citations. The model's memory and the project's files only shape the questions. Thin evidence is reported as thin.
- A report ages. An existing run can be refreshed, which re-checks only the claims likely to be stale, or deepened in one area. When a run on the topic exists, recommend resuming it.
- The result is `research-<topic>.md`, a cited summary other skills take as input without reprocessing.
## Research on the project's own code
Recommend `bmad-deep-recon` when the user asks how something works in their code, why it is built that way, or wants the code researched before a ticket. The user just asks: the skill sees that the subject is the repository, the current one or a path they name, so there is no decision to state and no service to choose. It needs git, not web access. It is not for a quick question one file answers, and an ask as broad as "document the whole project" gets a list of narrower asks instead.
- The ask, whether a question, a ticket or a goal, becomes a short set of factual questions the user approves or edits before any research starts.
- The evidence is the code at one commit and its git history. Researchers see only the approved questions, never the goal or the ticket, so they report what the code does rather than what it should do.
- The result is one document, `research-<subject>.md` in the initiative folder, every claim cited to a line or a commit and no recommendation in it: what to change is the reader's choice.
- Decisions found in the history are offered as ADRs when they are hard to reverse, surprising without context, and the result of a real trade-off. One is written only when the user approves it, and the user commits it.
- `bmad-build` reads the document as evidence when it plans the ticket it was run for.
- Refresh and deepen do not apply: the document describes one commit, and a later ask is a new run that can follow up on it.
help/shard-pro.md
# Long documents with shard pro
Open this when the user asks whether to shard a document, how a sharded document works, how to change one, or how to hand one to another skill.
## When to suggest it
- A planning skill just wrote a large document (a PRD, an architecture, a long spec), and agents will work from it in later sessions.
- Agents miss things in a long document, read only its first part, or run slowly or expensively because of it.
- The user is about to start a process, such as a PRD, from a large existing document, like an old spec or a vendor manual. Preparing it first means every later read is cheaper.
It works on markdown and plain text. A `.docx`, PDF or HTML file is converted to markdown first, by a tool the user has or by asking the agent. A transcript, chat export or email thread is not a document to shard: suggest `bmad-ingest`, which turns it into a note.
## What it does
It assesses the document and recommends one of three outcomes. Leaving it alone is a good result, not a failure.
| Outcome | Fits when |
|---|---|
| Leave it | It is short enough to read whole, or already well signposted. |
| Contents list | Readers search or follow line ranges, or tools and skills expect one file. The file stays one file and gains a detailed contents list near the top. |
| Split | Readers load whole files, or the document is maintained piece by piece. It is cut word for word into shards with a map. |
Nothing is rewritten. A script does the cutting and checks that the shards join back into the original exactly.
## A sharded document
- The folder always has one main file, named after the folder, such as `prd-billing/prd-billing.md`. It opens with a short note saying the document is sharded, then a map linking to every shard with a one-line summary. A very long map moves into a few map pages linked from the main file.
- The shards are now the document. They are what gets read and kept up to date.
- `.source/` holds the original as it was before the split. It is frozen and out of date: never load it and never edit it. Keep it, because the checks compare against it.
- When a skill asks for inputs, such as a PRD, an architecture or Sofia's tickets, give it the main file. The agent reads the map and opens only the shards it needs. Do not hand over every shard or `.source/`.
## Changing it
Changes go through `bmad-shard-pro` again: it adds content to the right shard, splits one that grows too big, rewrites the map and reruns the checks. Edits made by hand to a shard are kept, but the map does not learn about new sections until the skill runs. A contents list is refreshed the same way.
After a split, links in the source that pointed at nearby files or at headings now in another shard may no longer resolve. Shard pro reports them and leaves them for the user, since it keeps the source's words exactly.
help/team-adoption.md
# Making a team's BMad follow shared rules
Open this when a lead wants every teammate's BMad to use the same rules, tools, templates, publishing targets, or paths. `bmad-customize` writes each change; this file is for choosing where a rule goes. How overrides merge is in `help/customization.md`.
## Pick the place by scope
| The rule applies to | Put it in |
|---|---|
| Every workflow one agent runs | That agent skill's team override |
| One workflow | That workflow skill's team override |
| Several workflows | One override per workflow |
| A shared path or a setup answer | Central config, `_bmad/custom/config.toml`, edited by hand |
| Every session, even with no skill active | The repository's `AGENTS.md`, kept short |
Team override files live under `_bmad/custom/` and are committed, so teammates get a change on their next pull. Personal `.user.toml` files stay out of git and win over the team file. Remind the user to commit after `bmad-customize` writes a team file.
## What a team can set
- **Standing facts.** Sentences every run must respect ("Our org is AWS-only"), or a pointer to a standards document the team already maintains, which is better than copying it.
- **Required tools.** Name the exact tool and when to call it. Teammates need that tool connected.
- **Publishing on completion.** Instructions that run once after a skill writes its output, such as posting the document to a wiki or opening a ticket. They should ask before any action teammates will see.
- **Writing standards and knowledge sources**, on the skills that expose them.
- **Templates.** Point a skill at the team's own template, kept in the repository. Start from a copy of the shipped one and keep its headings. `bmad-facilitate` reads libraries instead: add or replace a file in `_bmad/custom/facilitate-templates/`, or add rules to a shipped template (`help/facilitate.md`).
- **Output locations and shared paths**, pinned in central config. Pin only what the whole team must share.
Not every skill exposes every one of these. `bmad-customize` lists what a given skill allows and never invents a field.
ingest-templates/template-document.md
---
template: document
category: general
description: "A long written document: a report, article, paper, contract, specification or slide deck."
---
<!-- purpose: Give a reader what the document says and asks, with where each point sits, so they can go to the passage when it matters. -->
<!-- done when: Every ask, obligation and deadline in the document is listed, and every figure matches the document. -->
# {title}
## Summary
<!-- What it is, who wrote it and when, and its main argument or purpose. -->
## Key points
<!-- The claims, findings and figures. -->
## Asks and obligations
<!-- What the document asks of its reader or binds them to, with dates. -->
## Terms
<!-- Optional: terms the document defines or uses in its own sense. -->
ingest-templates/template-meeting.md
---
template: meeting
category: general
description: "Any meeting or call between several people, from a transcript, a recording's notes or someone's write-up."
---
<!-- purpose: Give someone who missed the meeting what was decided, who does what next, and what is still open. -->
<!-- done when: Every decision and commitment in the raw is listed with its owner and any condition, nothing proposed or merely offered is shown as decided or assigned, and every reversal shows its final state. -->
# {title}
## Summary
<!-- Three to five sentences: why the meeting happened, who took part, and what came of it. -->
## Decisions
## Action items
<!-- One line each: the action, then its owner and due date. -->
## Open questions
<!-- Raised in the meeting and not answered there. -->
## Discussion
<!-- By topic, not in the order spoken: the points, figures and positions a reader needs, each with its speaker. -->
ingest-templates/template-one-on-one.md
---
template: one-on-one
category: people
description: "A recurring private conversation about work, growth and support, usually between a manager and a report."
---
<!-- purpose: Keep both people's commitments and the threads that carry over to the next one-on-one. -->
<!-- done when: Every commitment from either person is listed under its owner, and nothing said off the record appears. -->
<!-- privacy: Leave out anything either person asked to keep off the record, and say once that something was left out. -->
# {title}
## Topics
<!-- Each topic, who raised it, and where it ended. -->
## Commitments
<!-- Grouped by person. -->
## Follow-ups from last time
<!-- Optional: when they went back over earlier commitments, each one and what was said about it. -->
## For next time
ingest-templates/template-thread.md
---
template: thread
category: general
description: "An email thread, a chat channel export or a message thread. Choose it for written back-and-forth, where a later message may overturn an earlier one."
---
<!-- purpose: Say where the thread stands now, so a reader need not read it in order. -->
<!-- done when: The state at the last message is clear, every open commitment and unanswered question is listed, and nothing later overturned is shown as current. -->
# {title}
## Where it stands
<!-- The state as of the last message, in a few sentences, with that message's date. -->
## Decisions
<!-- Those still in force at the last message. -->
## Commitments
<!-- Those still open at the last message: who said they would do what, and by when. -->
## Waiting on an answer
<!-- Questions and requests no later message answers: who asked whom. -->
## Superseded
<!-- Optional: earlier positions the thread moved away from, when a reader who saw only the early messages would act on them. -->
ingest-templates/template-voice-memo.md
---
template: voice-memo
category: general
description: "One person thinking aloud: a voice memo, a dictated note, a recorded walk. Not for a conversation between several people."
---
<!-- purpose: Keep the speaker's ideas and to-dos so nothing said in passing is lost. -->
<!-- done when: Every to-do the speaker said is listed, and no idea is shown as a decision. -->
# {title}
## Summary
<!-- What the memo is about, in two or three sentences. -->
## To-dos
<!-- Everything the speaker said they or someone should do. -->
## Ideas
<!-- Grouped by topic. -->
## Questions
<!-- What the speaker wondered about or wanted to find out. -->
retired.toml
# Skills this module no longer ships. `bmad setup` offers to delete any still installed and moves a renamed
# skill's `_bmad/custom/` files to the new name. A retired name is never reused.
renamed = [{ from = "bmad-help", to = "bmad" }]
removed = ["bmad-distillator", "bmad-index-docs", "bmad-init", "bmad-shard-doc"]
SKILL.md
---
name: bmod-core-tools
description: Required bmod metadata. Never invoke this skill.
---
This folder is the BMad Core Tools module's record, not something to run. Invoke the `bmad` skill with `setup core-tools`; it sets the module up if it never was, and otherwise reports its state. If there is no `bmad` skill, say so and offer `npx skills add bmad-code-org/BMAD-METHOD --skill bmad`.