mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-11-03 22:12:12 +08:00
Brian
fc6a41c673
* feat(toolsmith): make a single-skill module the default for one skill Registration is settled from the registry and shown in the read-back instead of asked. A skill joins a module only when the user is working on that module, named it, or chose its prefix. A bmod-<code> record folder is never written for one skill. * fix(toolsmith): ask whether a skill is part of a module Single-skill module stays the offered guess, but discovery now asks whether the skill joins a module or more skills are planned. A planned module settles its code and prefix on the first skill, so nothing is renamed later. * feat(toolsmith): read any agent's session logs and offer customization in from-logs The agent finds its own logs and confirms the location instead of assuming Claude Code. A corrected installed skill can be offered as a bmad-customize change instead of a new skill. * refactor(toolsmith): split discover into short sections and cut what a model infers Registration gets its own section, the five things and other enumerable items become lists, and the read-back carries the consumer and bar. * feat(toolsmith): start prose from one sentence and hold one topic to a paragraph The canon, leanness lens and cut roles now default to the one-sentence version of a passage and split mixed topics. The pre-pass reports long paragraphs and sentences. * refactor(toolsmith): cut prompt files to one topic per paragraph and inline ecosystem into ship Every route, mode and shape file is split into short paragraphs, bullets and cases, with what a model would infer removed. ecosystem.md only ever loaded from ship.md, so its content now lives there. * feat(toolsmith): let a memory agent add its name to its description at First Breath * fix(toolsmith): close a Markdown fence only on its own marker in the pre-pass * fix(toolsmith): let a single-skill module grow into a multi-skill module * fix(toolsmith): write dependencies to the table the module shape uses * feat(toolsmith): restore a memory agent's name after an update and skip global installs * docs(toolsmith): bring the help up to date and route to cut mode * refactor(toolsmith): call the read-back the Smithy execution plan and add help on sharing and subagents * docs(toolsmith): write the Toolsmith docs to replace the builder site
182 lines
6.7 KiB
Markdown
182 lines
6.7 KiB
Markdown
---
|
|
title: Module Files
|
|
description: 'The files that make a BMad module: bmod.toml, roster.toml, retired.toml, migration files, and help, with every key and rule.'
|
|
sidebar:
|
|
order: 2
|
|
---
|
|
|
|
Use this page for the exact keys in a module's files. For what a module is and how to choose a registration, see [Modules and Registration](../toolsmith/modules.md). Smithy writes these files for you, and `validate_manifests.py` checks them.
|
|
|
|
## Where the Files Live
|
|
|
|
| File | Multi-skill module | Single-skill module |
|
|
| --- | --- | --- |
|
|
| `bmod.toml` with `[bmod]` | In the `bmod-<code>` record folder | In the skill's folder |
|
|
| `bmod.toml` with `[skill]` | In each member's folder | The same file, with `[skill]` empty |
|
|
| `help/help.md` | In the record folder | In the skill's folder |
|
|
| `SKILL.md` | The record has one that only redirects to `bmad setup <code>` | The skill's own |
|
|
| `roster.toml`, `retired.toml`, `migration-<n>.toml` | In the record folder | Beside `bmod.toml` |
|
|
|
|
`bmad` finds a module by its `[bmod]` table. Validation requires a multi-skill record folder to be named `bmod-<code>`, and a single-skill module's folder keeps the skill's name.
|
|
|
|
## `bmod.toml`
|
|
|
|
A file holds a `[bmod]` table, a `[skill]` table, or both.
|
|
|
|
### `[bmod]`
|
|
|
|
| Key | Required | Meaning |
|
|
| --- | --- | --- |
|
|
| `code` | Yes | Configuration namespace and the name in `bmad setup <code>`. Cannot be `_config`, `custom`, `modules`, or `scripts` |
|
|
| `version` | Yes | The module's version, compared with its source to offer updates |
|
|
| `update_source` | Yes | Where updates come from. Starts with `github:`, `https://`, `file:`, or `plugin:` |
|
|
| `skills` | Multi-skill | Every member skill |
|
|
| `required_skills` | No | Skills the module needs, see [Dependencies](#dependencies) |
|
|
| `recommended_skills` | No | Skills that help beside it. Setup reports them and does not insist |
|
|
| `pre_install_message` | For validation | Shown before an update, or before `bmad` installs the record itself |
|
|
| `post_install_message` | For validation | Shown after installing |
|
|
|
|
Setup accepts a record without the install messages, but `validate_manifests.py` requires both keys, empty if unused.
|
|
|
|
A `github:` source is `github:<owner>/<repo>/<path>`, where `<path>` is the folder holding the skill folders, such as `skills`. With no path, the repository root is the skill. Update checks read `bmod.toml` from the `main` branch.
|
|
|
|
### `[[bmod.config_questions]]`
|
|
|
|
Each entry is one question for `bmad setup <code>`, asked in file order.
|
|
|
|
| Key | Required | Meaning |
|
|
| --- | --- | --- |
|
|
| `key` | Yes | Dotted key, read as `modules.<code>.<key>`. Must not be the code or start with `<code>.` |
|
|
| `prompt` | Yes | The question text |
|
|
| `default` | Yes | The default answer, with `{project-root}` kept literal |
|
|
| `scope` | No | `team`, the default, or `user` for a personal answer that is not committed |
|
|
|
|
No other keys are allowed.
|
|
|
|
### `[[bmod.knowledge]]`
|
|
|
|
Optional. Lists extra help documents inside the record folder, with `path` and `skills`. `skills` is `"*"`, the default, or a list of skill names.
|
|
|
|
### `[skill]`
|
|
|
|
| Key | Required | Meaning |
|
|
| --- | --- | --- |
|
|
| `bmod` | In a member file | The record folder, such as `bmod-acme` |
|
|
| `source` | In a member file | Must equal the record's `update_source` |
|
|
| `required_skills` | No | What this skill alone requires |
|
|
| `recommended_skills` | No | What helps beside this skill |
|
|
| `scripts` | No | Paths written like `scripts/foo.py` that setup installs to `_bmad/<code>/scripts/` |
|
|
|
|
In a single-skill module, leave `[skill]` empty unless it declares `scripts`, because the record in the same file already names the module's one skill.
|
|
|
|
### Dependencies
|
|
|
|
A plain name is a skill from the same source. A table names a skill from elsewhere.
|
|
|
|
```toml
|
|
required_skills = [
|
|
"acme-release-notes",
|
|
{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" },
|
|
]
|
|
```
|
|
|
|
`version` is optional. Module-wide needs go in `[bmod]`, including all of a single-skill module's needs. One member's needs go in its `[skill]` table.
|
|
|
|
### Examples
|
|
|
|
A record:
|
|
|
|
```toml
|
|
[bmod]
|
|
code = "acme"
|
|
version = "1.0.0"
|
|
update_source = "github:acme/skills/skills"
|
|
skills = ["acme-release-notes", "acme-agent-scout"]
|
|
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]
|
|
pre_install_message = ""
|
|
post_install_message = ""
|
|
|
|
[[bmod.config_questions]]
|
|
key = "release_folder"
|
|
prompt = "Where should release notes go?"
|
|
default = "{project-root}/docs/releases"
|
|
```
|
|
|
|
A member:
|
|
|
|
```toml
|
|
[skill]
|
|
bmod = "bmod-acme"
|
|
source = "github:acme/skills/skills"
|
|
```
|
|
|
|
A single-skill module:
|
|
|
|
```toml
|
|
[bmod]
|
|
code = "acme"
|
|
version = "0.1.0"
|
|
update_source = "github:acme/acme-release-notes/skills"
|
|
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]
|
|
pre_install_message = ""
|
|
post_install_message = ""
|
|
|
|
[skill]
|
|
```
|
|
|
|
## Reading Answers
|
|
|
|
A skill reads a setup answer with one call, listing every key it needs.
|
|
|
|
```bash
|
|
uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key modules.acme.release_folder
|
|
```
|
|
|
|
## `roster.toml`
|
|
|
|
Required when a member is an agent. It is how `bmad` and party mode know who is available. A member with `skill` is an agent, present only while that skill is installed. A member without `skill` is a guest who exists only in groups.
|
|
|
|
```toml
|
|
[[members]]
|
|
code = "acme-agent-scout"
|
|
skill = "acme-agent-scout"
|
|
name = "Scout"
|
|
icon = "🔭"
|
|
title = "Release Scout"
|
|
persona = "Two sentences on who this agent is."
|
|
|
|
[[groups]]
|
|
id = "release-team"
|
|
name = "Release Team"
|
|
scene = "A release readiness meeting."
|
|
members = ["acme-agent-scout"]
|
|
memory = false
|
|
```
|
|
|
|
## `retired.toml`
|
|
|
|
Lists skills the 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, and a name can appear only once.
|
|
|
|
```toml
|
|
renamed = [{ from = "acme-notes", to = "acme-release-notes" }]
|
|
removed = ["acme-old-check"]
|
|
```
|
|
|
|
## `migration-<n>.toml`
|
|
|
|
A module ships a migration beside its `bmod.toml`, and `bmad migrate` runs them in `<n>` order. The file has a `[migration]` table with `module`, `from`, `to`, `title`, `summary`, `detect`, `guide`, and a `checklist` array. A file missing any of these is not listed. The file holds the rules, and `bmad` follows them.
|
|
|
|
## Help Files
|
|
|
|
`help/help.md` covers the whole module and is read by the `bmad` skill. Every other `help/*.md` is a topic file, read only when `help.md` names it. See [Write the Help](../toolsmith/modules.md#write-the-help).
|
|
|
|
## Validate
|
|
|
|
In a repository with `skills/*/bmod.toml`:
|
|
|
|
```bash
|
|
uv run {project-root}/_bmad/scripts/validate_manifests.py --project-root <repo>
|
|
```
|
|
|
|
It covers manifests, membership, versions, retired names, help topics, and the roster.
|