Skip to content

Commit e157639

Browse files
Brian MadisonBrian Madison
authored andcommitted
refactor: remove package.json and _module-installer from modules
Security: Remove _module-installer concept entirely - script execution during module installation is a security nightmare for community modules. Simplification: Remove all package.json references. Modules only need: - module.yaml (required) - module-help.csv (optional but powerful for help system) Changes: - Delete module-installer-standards.md - Delete step-04-installer.md - Renumber steps: 04→03, 05→04, 06→05, 07→06, 08→07 - Update all workflow step references - Remove installer checks from validation - Remove package.json from documentation - Remove npm publishing instructions from tutorial - Update module structure examples throughout Modules are now simpler and safer - just module.yaml, your agents/workflows, and optionally module-help.csv for the BMad help system integration.
1 parent ee89ef0 commit e157639

17 files changed

Lines changed: 47 additions & 696 deletions

docs/explanation/module-building-architecture.md

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -64,17 +64,10 @@ your-module/
6464
│ ├── workflows/ # Workflow directory
6565
│ │ └── your-workflow/ # Workflow SPEC files (stubs)
6666
│ │ └── workflow.md
67-
│ └── _module-installer/ # Custom install prompts (if needed)
6867
├── README.md # Documentation template
6968
└── TODO.md # Implementation checklist
7069
```
7170

72-
For npm publishing, add:
73-
```
74-
├── package.json # NPM package config (publishing only)
75-
└── .npmignore # Excludes dev files from npm package
76-
```
77-
7871
**What these SPEC files contain:**
7972
- **Agent specs** — Persona definitions (name, role, voice) as references for workflows
8073
- **Workflow specs** — Outline of steps, goals, structure (not finished workflows)
@@ -166,12 +159,6 @@ wedding-planner/
166159
└── TODO.md
167160
```
168161

169-
For npm publishing, add:
170-
```
171-
├── package.json
172-
└── .npmignore
173-
```
174-
175162
**What the SPEC files contain:**
176163

177164
`budget-specialist.agent.yaml` (spec):
@@ -262,12 +249,6 @@ wedding-planner/
262249
└── TODO.md # ✅ All items checked
263250
```
264251

265-
For npm publishing, add:
266-
```
267-
├── package.json # For npm distribution
268-
└── .npmignore
269-
```
270-
271252
## Why This Architecture Works
272253

273254
| Benefit | Explanation |

docs/reference/builder-commands.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,6 @@ Creates a module from a brief.
173173
**Creates:**
174174
- Module directory structure
175175
- `module.yaml` with configuration
176-
- `_module-installer/` folder (if needed)
177176
- Agent and workflow spec files
178177
- README.md and TODO.md
179178

docs/tutorials/create-your-first-module.md

Lines changed: 9 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@ This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMad in
1414
- How to create a module brief with Morgan (module-builder)
1515
- How to build a complete module from your brief
1616
- How to configure module.yaml and module-help.csv
17-
- How to publish your module to npm
1817

1918
:::note[Prerequisites]
2019
- BMad installed with the BMB module
@@ -24,7 +23,7 @@ This tutorial uses the **BMad Builder (BMB)** module. Make sure you have BMad in
2423
:::
2524

2625
:::tip[Quick Path]
27-
`[PB]` create brief → `[CM]` build module → Configure → Publish to npm.
26+
`[PB]` create brief → `[CM]` build module → Configure.
2827
:::
2928

3029
## Understanding Modules
@@ -43,13 +42,7 @@ your-module/
4342
│ ├── agents/ # Agent definitions (.agent.yaml)
4443
│ ├── workflows/ # Workflow files
4544
│ └── tools/ # Small reusable tools
46-
├── README.md # Module documentation
47-
```
48-
49-
For npm publishing, add:
50-
```
51-
├── package.json # NPM package info (for publishing only)
52-
└── .npmignore # Excludes dev files from npm package
45+
└── README.md # Module documentation
5346
```
5447

5548
### What Makes a Complete Module?
@@ -61,7 +54,6 @@ For npm publishing, add:
6154
| **Agents** | AI assistants with specific roles | ⚪ Optional |
6255
| **Workflows** | Step-by-step processes | ⚪ Optional |
6356
| **Tools** | Reusable prompt files | ⚪ Optional |
64-
| **package.json** | NPM publishing, version info | 📦 For publishing only |
6557

6658
## Why Build Modules?
6759

@@ -150,7 +142,6 @@ Morgan then builds your module structure:
150142
| Component | What Morgan Creates |
151143
|-----------|---------------------|
152144
| **module.yaml** | Module metadata, install questions, configuration |
153-
| **_module-installer/** | Custom install prompts (if needed) |
154145
| **Agent specs** | Placeholder/spec files for each agent |
155146
| **Workflow specs** | Placeholder/spec files for each workflow |
156147
| **README.md** | Module documentation template |
@@ -200,29 +191,6 @@ your-module,discovery,"Your Workflow Name",your-workflow,10,workflows/your-workf
200191
In a future release, `module-help.csv` will be auto-generated from workflow and agent metadata. For now, it's the manual way to tap into the power of the BMad help system.
201192
:::
202193

203-
### package.json (For npm Publishing Only)
204-
205-
If you plan to publish your module to npm, create `package.json`:
206-
207-
```json
208-
{
209-
"name": "@your-username/your-module",
210-
"version": "0.1.0",
211-
"description": "Your module description",
212-
"keywords": ["bmad", "bmad-module"],
213-
"author": "Your Name",
214-
"license": "MIT"
215-
}
216-
```
217-
218-
:::note[Package Naming]
219-
Use scoped naming (`@username/module-name` or `@bmad-code-org/` for official modules).
220-
:::
221-
222-
:::note[Local Modules Don't Need package.json]
223-
If you're only using your module locally or sharing it directly (folder, git repo), you can skip `package.json` entirely. It's only required for npm publishing.
224-
:::
225-
226194
## Step 4: Implement Your Agents and Workflows
227195

228196
Morgan created spec files during the build step. Now implement your agents and workflows:
@@ -237,7 +205,7 @@ For details on creating agents and workflows, see:
237205

238206
## Step 5: Validate Your Module
239207

240-
Before publishing, validate your module:
208+
Before sharing, validate your module:
241209

242210
```
243211
[VM] or "validate-module"
@@ -252,36 +220,6 @@ Morgan checks:
252220

253221
Fix any issues Morgan identifies, then re-validate.
254222

255-
## Step 6: Publish Your Module
256-
257-
When your module is ready to share:
258-
259-
### Option A: Quick Release
260-
261-
```bash
262-
npm run release # Patch (0.1.0 → 0.1.1)
263-
npm run release:minor # Minor (0.1.0 → 0.2.0)
264-
npm run release:major # Major (0.1.0 → 1.0.0)
265-
```
266-
267-
This updates the version, creates a git tag, and pushes to trigger GitHub Actions publishing.
268-
269-
### Option B: Manual Publishing
270-
271-
```bash
272-
cd /path/to/your-module
273-
npm publish
274-
```
275-
276-
You may be prompted for OTP if you have 2FA enabled on your npm account.
277-
278-
:::note[First-Time Setup]
279-
If you're publishing for the first time:
280-
1. Create an npm account at https://www.npmjs.com
281-
2. Create an automation token at https://www.npmjs.com/settings/tokens
282-
3. Add as GitHub secret: `gh secret set NPM_TOKEN --repo your-repo`
283-
:::
284-
285223
## What You've Accomplished
286224

287225
You've created a complete BMad module with:
@@ -305,26 +243,24 @@ Your module is now ready to:
305243
| Build module | `[CM]` or `create-module` |
306244
| Validate | `[VM]` or `validate-module` |
307245
| Edit module | `[EM]` or `edit-module` |
308-
| Quick release | `npm run release` |
309-
| Manual publish | `npm publish` |
310246

311247
## Common Questions
312248

313249
**Should I use bmad-module-template?**
314250

315-
Yes! The [bmad-module-template](https://github.com/bmad-code-org/bmad-module-template) provides a starting point with proper structure, npm setup, and GitHub Actions. You can also use Morgan to generate a module from scratch.
251+
Yes! The [bmad-module-template](https://github.com/bmad-code-org/bmad-module-template) provides a starting point with proper structure. You can also use Morgan to generate a module from scratch.
316252

317253
**What's the difference between the brief and the module?**
318254

319255
The brief is a **vision document** created through creative discovery. The module is the **implementation** built from that brief. Think of it as: brief = blueprint, module = building.
320256

321-
**Can I update my module after publishing?**
257+
**Can I update my module after sharing it?**
322258

323-
Yes! Use `npm run release` to bump the version and publish updates. Users can update with `npm update @your-username/your-module`.
259+
Yes! Share the updated module folder or repository. Users can reinstall to get the latest version.
324260

325261
**How do I share my module privately?**
326262

327-
Don't publish to npm. Share the module folder directly, or host it in a private Git repository. Users can install from a local path.
263+
Share the module folder directly, or host it in a private Git repository. Users can install from a local path.
328264

329265
## Getting Help
330266

@@ -342,6 +278,6 @@ Don't publish to npm. Share the module folder directly, or host it in a private
342278
:::tip[Key Takeaways]
343279
- **Plan first** — The brief ensures your module has a clear vision
344280
- **Structure matters** — Follow the standard module structure for compatibility
345-
- **Validate before publishing** — Use `[VM]` to check your work
346-
- **Share your work**Publishing to npm makes your module available to the community
281+
- **Validate before sharing** — Use `[VM]` to check your work
282+
- **Share your work**Modules can be shared via folders, git repos, or the community
347283
:::

0 commit comments

Comments
 (0)