SurfSense/_bmad/bmb/workflows/module/data/module-standards.md

# Module Standards

**Purpose:** Defines what a BMAD module is, its structure, and the three types of modules.

---

## What is a BMAD Module?

A **BMAD module** is a self-contained package of functionality that extends the BMAD framework. Modules provide:
- **Agents** — AI personas with specialized expertise and menu-driven commands
- **Workflows** — Structured processes for accomplishing complex tasks
- **Configuration** — module.yaml for user customization
- **Installation** — Optional installer.js for setup logic

---

## Module Types

### 1. Standalone Module

A new, independent module focused on a specific domain.

**Characteristics:**
- Own module code (e.g., `healthcare-ai`, `legal-assist`)
- Independent of other modules
- Can be installed alongside any other modules
- Has its own agents, workflows, configuration

**Location:** `src/modules/{module-code}/`

**Example:** CIS (Creative Innovation Suite) — a standalone module for innovation workflows

---

### 2. Extension Module

Extends an existing BMAD module with additional functionality.

**Characteristics:**
- Builds upon an existing module's agents and workflows
- May add new agents or workflows that complement the base module
- Shares configuration context with the extended module
- Typically installed alongside the module it extends

**Location:** `src/modules/{base-module}/extensions/{extension-code}/`

**Example:** An extension to BMM that adds specialized security review workflows

---

### Extension Module: Override & Merge Pattern

When an extension module is installed, its files merge with the base module following these rules:

#### Code Matching

The extension's `module.yaml` `code:` field matches the base module's code:

```yaml
# Base module: src/modules/bmm/module.yaml
code: bmm

# Extension: src/modules/bmm/extensions/security/module.yaml
code: bmm  # SAME CODE — extends BMM
```

The **folder name** is unique (e.g., `bmm-security`) but the `code:` matches the base module.

#### File Merge Rules

| File Type | Same Name | Different Name |
|-----------|-----------|----------------|
| Agent file | **OVERRIDE** — replaces the base agent | **ADD** — new agent added |
| Workflow folder | **OVERRIDE** — replaces the base workflow | **ADD** — new workflow added |
| Other files | **OVERRIDE** — replaces base file | **ADD** — new file added |

#### Examples

**Override scenario:**
```
Base module (BMM):
├── agents/
│   └── pm.agent.yaml          # Original PM agent

Extension (bmm-security):
├── agents/
│   └── pm.agent.yaml          # Security-focused PM — REPLACES original

Result after installation:
├── agents/
│   └── pm.agent.yaml          # Now the security version
```

**Add scenario:**
```
Base module (BMM):
├── agents/
│   ├── pm.agent.yaml
│   └── architect.agent.yaml

Extension (bmm-security):
├── agents/
│   └── security-auditor.agent.yaml  # NEW agent

Result after installation:
├── agents/
│   ├── pm.agent.yaml
│   ├── architect.agent.yaml
│   └── security-auditor.agent.yaml  # ADDED
```

**Mixed scenario:**
```
Extension contains both overrides and new files — applies rules per file
```

---

### 3. Global Module

Affects the entire BMAD framework and all modules.

**Characteristics:**
- Core functionality that impacts all modules
- Often provides foundational services or utilities
- Installed at the framework level
- Use sparingly — only for truly global concerns

**Location:** `src/modules/{module-code}/` with `global: true` in module.yaml

**Example:** A module that provides universal logging or telemetry across BMAD

---

## Required Module Structure

```
{module-code}/
├── module.yaml                 # Module configuration (REQUIRED)
├── README.md                   # Module documentation (REQUIRED)
├── agents/                     # Agent definitions (if any)
│   └── {agent-name}.agent.yaml
├── workflows/                  # Workflow definitions (if any)
│   └── {workflow-name}/
│       └── workflow.md
├── _module-installer/          # Installation logic (optional)
│   ├── installer.js
│   └── platform-specifics/
│       ├── claude-code.js
│       ├── windsurf.js
│       └── ...
└── {other folders}             # Tasks, templates, data as needed
```

---

## Required Files

### module.yaml (REQUIRED)

Every module MUST have a `module.yaml` file with at minimum:

```yaml
code: {module-code}
name: "Module Display Name"
header: "Brief module description"
subheader: "Additional context"
default_selected: false
```

See: `module-yaml-conventions.md` for full specification.

---

### README.md (REQUIRED)

Every module MUST have a README.md with:
- Module name and purpose
- Installation instructions
- Components section (agents, workflows)
- Quick start guide
- Module structure diagram
- Configuration section
- Usage examples
- Author information

---

## Optional Components

### Agents

Agents are AI personas with:
- Metadata (id, name, title, icon, module)
- Persona (role, identity, communication_style, principles)
- Menu (trigger → workflow/exec mappings)

See: `agent-architecture.md` for design guidance.

---

### Workflows

Workflows are structured processes with:
- workflow.md (entry point)
- steps/ folder with step files
- data/ folder with shared reference
- templates/ folder if needed

---

### _module-installer/

Optional installation logic for:
- Creating directories
- Copying assets
- IDE-specific configuration
- Platform-specific setup

See: `module-installer-standards.md` for patterns.

---

## Module Type Decision Tree

```
START: Creating a module
│
├─ Is this a brand new independent domain?
│  └─ YES → Standalone Module
│
├─ Does this extend an existing module?
│  └─ YES → Extension Module
│
└─ Does this affect all modules globally?
   └─ YES → Global Module (use sparingly)
```

---

## Naming Conventions

### Module Code

- **kebab-case** (e.g., `bmm`, `cis`, `bmgd`, `healthcare-ai`)
- Short, memorable, descriptive
- 2-20 characters
- Lowercase letters, numbers, hyphens only

### Agent Files

- Format: `{role-name}.agent.yaml`
- Example: `pm.agent.yaml`, `architect.agent.yaml`

### Workflow Folders

- Format: `{workflow-name}/`
- Example: `prd/`, `create-architecture/`

---

## Module Dependencies

Modules can depend on:
- **Core BMAD** — Always available
- **Other modules** — Specify in module.yaml as `dependencies:`
- **External tools** — Document in README, handle in installer

---

## Quick Reference

| Question | Answer |
|----------|--------|
| What's a module? | Self-contained package of agents, workflows, config |
| What are the types? | Standalone, Extension, Global |
| What's required? | module.yaml, README.md |
| Where do modules live? | `src/modules/{code}/` |
| How do agents work? | Menu triggers → workflow/exec |
| How does installation work? | module.yaml prompts + optional installer.js |