pig-farm-controller/bmad/bmb/workflows/create-module/module-structure.md

BMAD Module Structure Guide

What is a Module?

A BMAD module is a self-contained package of agents, workflows, tasks, and resources that work together to provide specialized functionality. Think of it as an expansion pack for the BMAD Method.

Module Architecture

Core Structure

# SOURCE MODULE (in BMAD-METHOD project)
src/modules/{module-code}/
├── agents/                        # Agent definitions (.agent.yaml)
├── workflows/                     # Workflow folders
├── tasks/                         # Task files
├── tools/                         # Tool files
├── templates/                     # Shared templates
├── data/                          # Static data
├── _module-installer/             # Installation configuration
│   ├── install-config.yaml  # Installation questions & config
│   ├── installer.js              # Optional custom install logic
│   └── assets/                   # Files to copy during install
└── README.md                      # Module documentation

# INSTALLED MODULE (in target project)
{project-root}/bmad/{module-code}/
├── agents/                        # Compiled agent files (.md)
├── workflows/                     # Workflow instances
├── tasks/                         # Task files
├── tools/                         # Tool files
├── templates/                     # Templates
├── data/                          # Module data
├── config.yaml                    # Generated from install-config.yaml
└── README.md                      # Module documentation

Module Types by Complexity

Simple Module (1-2 agents, 2-3 workflows)

Perfect for focused, single-purpose tools.

Example: Code Review Module

• 1 Reviewer Agent
• 2 Workflows: quick-review, deep-review
• Clear, narrow scope

Standard Module (3-5 agents, 5-10 workflows)

Comprehensive solution for a domain.

Example: Project Management Module

• PM Agent, Scrum Master Agent, Analyst Agent
• Workflows: sprint-planning, retrospective, roadmap, user-stories
• Integrated component ecosystem

Complex Module (5+ agents, 10+ workflows)

Full platform or framework.

Example: RPG Toolkit Module

• DM Agent, NPC Agent, Monster Agent, Loot Agent, Map Agent
• 15+ workflows for every aspect of game management
• Multiple interconnected systems

Module Naming Conventions

Module Code (kebab-case)

• data-viz - Data Visualization
• team-collab - Team Collaboration
• rpg-toolkit - RPG Toolkit
• legal-assist - Legal Assistant

Module Name (Title Case)

• "Data Visualization Suite"
• "Team Collaboration Platform"
• "RPG Game Master Toolkit"
• "Legal Document Assistant"

Component Guidelines

Agents per Module

Recommended Distribution:

• Primary Agent (1): The main interface/orchestrator
• Specialist Agents (2-4): Domain-specific experts
• Utility Agents (0-2): Helper/support functions

Anti-patterns to Avoid:

• Too many overlapping agents
• Agents that could be combined
• Agents without clear purpose

Workflows per Module

Categories:

• Core Workflows (2-3): Essential functionality
• Feature Workflows (3-5): Specific capabilities
• Utility Workflows (2-3): Supporting operations
• Admin Workflows (0-2): Maintenance/config

Workflow Complexity Guide:

• Simple: 3-5 steps, single output
• Standard: 5-10 steps, multiple outputs
• Complex: 10+ steps, conditional logic, sub-workflows

Tasks per Module

Tasks should be used for:

• Single-operation utilities
• Shared subroutines
• Quick actions that don't warrant workflows

Module Dependencies

Internal Dependencies

• Agents can reference module workflows
• Workflows can invoke module tasks
• Tasks can use module templates

External Dependencies

• Reference other modules via full paths
• Declare dependencies in config.yaml
• Version compatibility notes

Installation Infrastructure

Required: _module-installer/install-config.yaml

This file defines both installation questions AND static configuration values:

# Module metadata
code: module-code
name: 'Module Name'
default_selected: false

# Welcome message during installation
prompt:
  - 'Welcome to Module Name!'
  - 'Brief description here'

# Core values automatically inherited from installer:
## user_name
## communication_language
## document_output_language
## output_folder

# INTERACTIVE fields (ask user during install)
output_location:
  prompt: 'Where should module outputs be saved?'
  default: 'output/module-code'
  result: '{project-root}/{value}'

feature_level:
  prompt: 'Which feature set?'
  default: 'standard'
  result: '{value}'
  single-select:
    - value: 'basic'
      label: 'Basic - Core features only'
    - value: 'standard'
      label: 'Standard - Recommended features'
    - value: 'advanced'
      label: 'Advanced - All features'

# STATIC fields (no prompt, just hardcoded values)
module_version:
  result: '1.0.0'

data_path:
  result: '{project-root}/bmad/module-code/data'

Key Points:

• File is named install-config.yaml (NOT install-config.yaml)
• Supports both interactive prompts and static values
• result field uses placeholders: {value}, {project-root}, {directory_name}
• Installer generates final config.yaml from this template

Optional: _module-installer/installer.js

For complex installations requiring custom logic:

/**
 * @param {Object} options - Installation options
 * @param {string} options.projectRoot - Target project directory
 * @param {Object} options.config - Config from install-config.yaml
 * @param {Array} options.installedIDEs - IDEs being configured
 * @param {Object} options.logger - Logger (log, warn, error)
 * @returns {boolean} - true if successful
 */
async function install(options) {
  // Custom installation logic here
  // - Database setup
  // - API configuration
  // - External downloads
  // - Integration setup

  return true;
}

module.exports = { install };

Optional: _module-installer/assets/

Files to copy during installation:

• External configurations
• Documentation
• Example files
• Integration scripts

Module Lifecycle

Development Phases

1. Planning Phase

   • Define scope and purpose
   • Identify components
   • Design architecture

2. Scaffolding Phase

   • Create directory structure
   • Generate configurations
   • Setup installer

3. Building Phase

   • Create agents incrementally
   • Build workflows progressively
   • Add tasks as needed

4. Testing Phase

   • Test individual components
   • Verify integration
   • Validate installation

5. Deployment Phase

   • Package module
   • Document usage
   • Distribute/share

Best Practices

Module Cohesion

• All components should relate to module theme
• Clear boundaries between modules
• No feature creep

Progressive Enhancement

• Start with MVP (1 agent, 2 workflows)
• Add components based on usage
• Refactor as patterns emerge

Documentation Standards

• Every module needs README.md
• Each agent needs purpose statement
• Workflows need clear descriptions
• Include examples and quickstart

Naming Consistency

• Use module code prefix for uniqueness
• Consistent naming patterns within module
• Clear, descriptive names

Example Modules

Example 1: Personal Productivity

productivity/
├── agents/
│   ├── task-manager.md      # GTD methodology
│   └── focus-coach.md        # Pomodoro timer
├── workflows/
│   ├── daily-planning/       # Morning routine
│   ├── weekly-review/        # Week retrospective
│   └── project-setup/        # New project init
└── config.yaml

Example 2: Content Creation

content/
├── agents/
│   ├── writer.md            # Blog/article writer
│   ├── editor.md            # Copy editor
│   └── seo-optimizer.md     # SEO specialist
├── workflows/
│   ├── blog-post/           # Full blog creation
│   ├── social-media/        # Social content
│   ├── email-campaign/      # Email sequence
│   └── content-calendar/    # Planning
└── templates/
    ├── blog-template.md
    └── email-template.md

Example 3: DevOps Automation

devops/
├── agents/
│   ├── deploy-master.md     # Deployment orchestrator
│   ├── monitor.md           # System monitoring
│   ├── incident-responder.md # Incident management
│   └── infra-architect.md   # Infrastructure design
├── workflows/
│   ├── ci-cd-setup/         # Pipeline creation
│   ├── deploy-app/          # Application deployment
│   ├── rollback/            # Emergency rollback
│   ├── health-check/        # System verification
│   └── incident-response/   # Incident handling
├── tasks/
│   ├── check-status.md      # Quick status check
│   └── notify-team.md       # Team notifications
└── data/
    └── runbooks/            # Operational guides

Module Evolution Pattern

Simple Module → Standard Module → Complex Module → Module Suite
     (MVP)          (Enhanced)        (Complete)      (Ecosystem)

Common Pitfalls

1. Over-engineering: Starting too complex
2. Under-planning: No clear architecture
3. Poor boundaries: Module does too much
4. Weak integration: Components don't work together
5. Missing docs: No clear usage guide

Success Metrics

A well-designed module has:

• ✅ Clear, focused purpose
• ✅ Cohesive components
• ✅ Smooth installation
• ✅ Comprehensive docs
• ✅ Room for growth
• ✅ Happy users!