|
1 | | -# Template Instructions |
| 1 | +# BMad Module Template |
2 | 2 |
|
3 | | -After creating a new repo from the template, in the ide or terminal of your choice, first run npm install (or pnpm install if using that instead of npm). |
| 3 | +A template for creating BMad Method modules that can be published to npm and installed via the BMad installer. |
4 | 4 |
|
5 | | -## Update README.md and docs folders |
| 5 | +## Quick Start |
6 | 6 |
|
7 | | -Update this readme with the real purpose and details of your custom module - remove all of this current info. |
| 7 | +After creating a new repo from this template: |
8 | 8 |
|
9 | | -If you need extensive docs, you can add more to the docs folder at project root. For BMad projects - we will continue to follow the diataxis format with llmstxt and docs published site support. |
| 9 | +```bash |
| 10 | +npm install |
| 11 | +``` |
10 | 12 |
|
11 | | -## Update package.json |
| 13 | +## Setup Checklist |
12 | 14 |
|
13 | | -Aside from potentially adding to the packages.json due to a need for custom installer routines, you need to update the following fields in the file: |
| 15 | +### 1. Update package.json |
14 | 16 |
|
15 | | -name. description, keywords array, repository.url, version |
| 17 | +Replace the placeholder values: |
16 | 18 |
|
17 | | -## Actual Module Contents src Folder |
| 19 | +- `name`: Your package name (e.g., `@bmad-method/your-module`) |
| 20 | +- `description`: What your module does |
| 21 | +- `author`: Your name |
| 22 | +- `repository.url`: Your git repository URL |
| 23 | +- `keywords`: Add relevant search terms |
18 | 24 |
|
19 | | -All module contents goes under src directly by convention. If you plan to house more than one module in the repo though, you can use sub folders (src/module1, src/module2). if not all content goes right under src. |
| 25 | +### 2. Update this README.md |
20 | 26 |
|
21 | | -The src folder |
| 27 | +Remove these template instructions and add: |
| 28 | +- What your module does |
| 29 | +- How to use it |
| 30 | +- Any specific configuration needed |
22 | 31 |
|
23 | | -### src/module.yaml (or src/[module-name]/module.yaml) |
| 32 | +### 3. Add your module content |
24 | 33 |
|
25 | | -This is the same standard convention followed by any BMad module. |
| 34 | +All module content goes under `src/`: |
26 | 35 |
|
27 | | -If you are creating this from scratch, note that the module.yaml aside from making your module installable via the BMad installer, and buildable to other targets and tools, it also serves as the primary mechanism to define what install questions get asked along with what the default values are. |
| 36 | +``` |
| 37 | +src/ |
| 38 | +├── module.yaml # Module metadata and install questions |
| 39 | +├── agents/ # BMad agents |
| 40 | +├── workflows/ # Agent workflows |
| 41 | +└── tools/ # Small reusable tools |
| 42 | +``` |
28 | 43 |
|
29 | | -### All other module conventions still apply: |
| 44 | +## Module Conventions |
30 | 45 |
|
31 | | -- agents folder - All bmad agents go under this folder or a agent named subfolder under the folder |
32 | | -- workflows - All workflows an agent might use or people can call directly go here |
33 | | -- tools - really similar to workflows, the main distinction being more conceptual - tools are small and do 1 thing well and are contained within a single prompt file. |
34 | | - - Consider a tool for when you might have multiple workflows use it. Not required, |
35 | | -- * - you can have any other folders as needed also within the repo, along with other tools |
36 | | -- ensure all content in workflows and agents are using relative paths to each other. This will help with future compatibility to conversion to other formats like Claude skills and similar. |
| 46 | +- **module.yaml**: Defines install questions and defaults |
| 47 | +- **agents/**: All BMad agents go here |
| 48 | +- **workflows/**: Agent workflows or direct-call workflows |
| 49 | +- **tools/**: Small, single-purpose prompt files |
| 50 | +- Use relative paths in all workflows/agents for portability |
| 51 | + |
| 52 | +## Publishing to NPM |
| 53 | + |
| 54 | +### First-time setup |
| 55 | + |
| 56 | +1. Create an npm automation token at <https://www.npmjs.com/settings>/tokens |
| 57 | +2. Add it as a GitHub secret named `NPM_TOKEN` in your repo settings: |
| 58 | + ```bash |
| 59 | + gh secret set NPM_TOKEN --repo YOUR-ORG/YOUR-REPO |
| 60 | + ``` |
| 61 | + |
| 62 | +### Release a new version |
| 63 | + |
| 64 | +The module includes release scripts that handle versioning and publishing: |
| 65 | + |
| 66 | +```bash |
| 67 | +# Patch release (0.1.0 -> 0.1.1) |
| 68 | +npm run release |
| 69 | + |
| 70 | +# Minor release (0.1.0 -> 0.2.0) |
| 71 | +npm run release:minor |
| 72 | + |
| 73 | +# Major release (0.1.0 -> 1.0.0) |
| 74 | +npm run release:major |
| 75 | + |
| 76 | +# Prerelease (0.1.0 -> 0.1.1-0) |
| 77 | +npm run release:prerelease |
| 78 | +``` |
| 79 | + |
| 80 | +These scripts: |
| 81 | +1. Update the version in package.json |
| 82 | +2. Create a git tag |
| 83 | +3. Push the tag to GitHub |
| 84 | +4. Trigger the publish workflow which publishes to npm |
| 85 | + |
| 86 | +### Manual tag release |
| 87 | + |
| 88 | +You can also create tags manually: |
| 89 | + |
| 90 | +```bash |
| 91 | +git tag v0.1.0 |
| 92 | +git push origin v0.1.0 |
| 93 | +``` |
| 94 | + |
| 95 | +## Workflows |
| 96 | + |
| 97 | +The module includes GitHub Actions workflows: |
| 98 | + |
| 99 | +- **publish.yaml**: Automatically publishes to npm when a version tag is pushed |
| 100 | +- **quality.yaml**: Runs linting and formatting checks |
| 101 | +- **docs.yaml**: Builds documentation |
| 102 | +- **discord.yaml**: Posts updates to Discord (configure if needed) |
| 103 | + |
| 104 | +## Development |
| 105 | + |
| 106 | +```bash |
| 107 | +# Run linting |
| 108 | +npm run lint |
| 109 | + |
| 110 | +# Fix formatting |
| 111 | +npm run format:fix |
| 112 | + |
| 113 | +# Run tests |
| 114 | +npm test |
| 115 | +``` |
| 116 | + |
| 117 | +## Module Installation (for users) |
| 118 | + |
| 119 | +Once published, users can install your module via the BMad Method installer or npm: |
| 120 | + |
| 121 | +```bash |
| 122 | +# Via BMad installer |
| 123 | +npx bmad-method install |
| 124 | + |
| 125 | +# Via npm |
| 126 | +npm install your-module-name |
| 127 | +``` |
0 commit comments