bmod-core-tools

[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-forge-idea",
  "bmad-party-mode",
  "bmad-review",
]
required_skills = ["bmad"]

# 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.

# 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.

## 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), or has a research report to make usable → `bmad-deep-recon`.
- Has a piece of work and wants it better:
  - It was just produced in this conversation and they want it pushed further, or they name a critique method → `bmad-advanced-elicitation`.
  - 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`.
- 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`.
  - 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}/brainstorming/brainstorm-{topic_slug}-{date}/`, with `brainstorm.html` and, on request, `brainstorm-intent.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. | A folder under `{output_folder}/forge/` with `forge-report.html` and, when the idea hardens, `forged-idea.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. | `{planning_artifacts}/research/{research_type}-{topic_slug}-{date}/` with `brief.md` and `research.md`, which is input for whatever skill acts on the decision. |
| `bmad-advanced-elicitation` | Pushes the most recent output to be reconsidered and improved. | It offers critique methods such as socratic questioning, first principles, pre-mortem, and red team. Nothing changes unless the user accepts. Other skills call it at their pauses. | Nothing. It improves the work in place. |
| `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 `.html` in `{output_folder}/party-mode/`. Memory under `{output_folder}/party-mode/memories/`. |
| `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.
- 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/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/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/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.

# 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. 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. |

## 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.

# 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` and `bmad-advanced-elicitation` mention party mode when it is installed, 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`.

# 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. A vague question gives vague research, so when the idea itself is still loose, recommend `bmad-forge-idea` first.

## 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. Suggest a quick pass for a narrow question, and 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" is supported for 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 can add 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 most likely to be stale, or deepened in one area. When a run on the topic already exists, recommend resuming it.
- The result is `research.md`, a cited summary other skills can take as input without reprocessing.

# 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.
- **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.

---
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`.