Files

Brian Madison fe27d68319 expansion packs updates in progress

2025-06-17 09:35:39 -05:00

40 KiB

Raw Blame History

Create Expansion Pack Task

This task helps you create a sophisticated BMAD expansion pack with advanced agent orchestration, template systems, and quality assurance patterns based on proven best practices.

Understanding Expansion Packs

Expansion packs extend BMAD with domain-specific capabilities using sophisticated AI agent orchestration patterns. They are self-contained packages that leverage:

Advanced Agent Architecture: YAML-in-Markdown with embedded personas and character consistency
Template Systems: LLM instruction embedding with conditional content and dynamic variables
Workflow Orchestration: Decision trees, handoff protocols, and validation loops
Quality Assurance: Multi-level validation with star ratings and comprehensive checklists
Knowledge Integration: Domain-specific data organization and best practices embedding

Every expansion pack MUST include a custom BMAD orchestrator agent with sophisticated command systems and numbered options protocols.

CRITICAL REQUIREMENTS

Create Planning Document First: Before any implementation, create a comprehensive plan for user approval
Agent Architecture Standards: Use YAML-in-Markdown structure with activation instructions, personas, and command systems
Character Consistency: Every agent must have a persistent persona with name, communication style, and numbered options protocol
Custom Themed Orchestrator: The orchestrator should embody the domain theme (e.g., Office Manager for medical, Project Lead for tech) for better user experience
Core Utilities Required: ALWAYS include these core files in every expansion pack:
- tasks/create-doc.md - Document creation from templates
- tasks/execute-checklist.md - Checklist validation
- utils/template-format.md - Template markup conventions
- utils/workflow-management.md - Workflow orchestration
Team and Workflow Requirements: If pack has >1 agent, MUST include:
- At least one team configuration in agent-teams/
- At least one workflow in workflows/
Template Sophistication: Implement LLM instruction embedding with [[LLM: guidance]], conditional content, and variable systems
Workflow Orchestration: Include decision trees, handoff protocols, and validation loops
Quality Assurance Integration: Multi-level checklists with star ratings and ready/not-ready frameworks
Verify All References: Any task, template, or data file referenced in an agent MUST exist in the pack
Knowledge Base Integration: Organize domain-specific data and embed best practices
Dependency Management: Clear manifest with file mappings and core agent dependencies

Process Overview

Phase 1: Discovery and Planning

1.1 Define the Domain

Ask the user:

Pack Name: Short identifier (e.g., healthcare, fintech, gamedev)
Display Name: Full name (e.g., "Healthcare Compliance Pack")
Description: What domain or industry does this serve?
Key Problems: What specific challenges will this pack solve?
Target Users: Who will benefit from this expansion?

1.2 Gather Examples and Domain Intelligence

Request from the user:

Sample Documents: Any existing documents in this domain
Workflow Examples: How work currently flows in this domain
Compliance Needs: Any regulatory or standards requirements
Output Examples: What final deliverables look like
Character Personas: What specialist roles exist (names, communication styles, expertise areas)
Domain Language: Specific terminology, jargon, and communication patterns
Quality Standards: Performance targets, success criteria, and validation requirements
Data Requirements: What reference data files users will need to provide
Technology Stack: Specific tools, frameworks, or platforms used in this domain
Common Pitfalls: Frequent mistakes or challenges in this domain

1.3 Create Planning Document

IMPORTANT: STOP HERE AND CREATE PLAN FIRST

Create expansion-packs/{pack-name}/plan.md with:

# {Pack Name} Expansion Pack Plan

## Overview

- Pack Name: {name}
- Description: {description}
- Target Domain: {domain}

## Components to Create

### Agents (with Character Personas)

- [ ] {pack-name}-orchestrator (REQUIRED: Custom BMAD orchestrator)
  - Character Name: {human-name}
  - Communication Style: {style}
  - Key Commands: {command-list}
- [ ] {agent-1-name}
  - Character Name: {human-name}
  - Expertise: {domain-expertise}
  - Persona: {personality-traits}
- [ ] {agent-2-name}
  - Character Name: {human-name}
  - Expertise: {domain-expertise}
  - Persona: {personality-traits}
- [ ] {agent-N-name}
  - Character Name: {human-name}
  - Expertise: {domain-expertise}
  - Persona: {personality-traits}

### Tasks

- [ ] {task-1} (referenced by: {agent})
- [ ] {task-2} (referenced by: {agent})

### Templates (with LLM Instruction Embedding)

- [ ] {template-1} (used by: {agent/task})
  - LLM Instructions: {guidance-type}
  - Conditional Content: {conditions}
  - Variables: {variable-list}
- [ ] {template-2} (used by: {agent/task})
  - LLM Instructions: {guidance-type}
  - Conditional Content: {conditions}
  - Variables: {variable-list}

### Checklists (Multi-Level Quality Assurance)

- [ ] {checklist-1}
  - Validation Level: {basic/comprehensive/expert}
  - Rating System: {star-ratings/binary}
  - Success Criteria: {specific-requirements}
- [ ] {checklist-2}
  - Validation Level: {basic/comprehensive/expert}
  - Rating System: {star-ratings/binary}
  - Success Criteria: {specific-requirements}

### Data Files and Knowledge Base

**Required from User:**

- [ ] {filename}.{ext} - {description of content needed}
- [ ] {filename2}.{ext} - {description of content needed}

**Domain Knowledge to Embed:**

- [ ] {domain}-best-practices.md - {description}
- [ ] {domain}-terminology.md - {description}
- [ ] {domain}-standards.md - {description}

**Workflow Orchestration:**

- [ ] Decision trees for {workflow-name}
- [ ] Handoff protocols between agents
- [ ] Validation loops and iteration patterns

## Approval

User approval received: [ ] Yes
```text

Important: Wait for user approval before proceeding to Phase 2

### Phase 2: Component Design

#### 2.1 Create Orchestrator Agent with Domain-Themed Character

**FIRST PRIORITY**: Design the custom BMAD orchestrator with domain-appropriate theme:

**Themed Character Design:**

- **Human Name**: {first-name} {last-name} (e.g., "Dr. Sarah Chen" for medical office manager)
- **Domain-Specific Role**: Match the orchestrator to the domain context:
  - Medical: "Office Manager" or "Practice Coordinator"
  - Legal: "Senior Partner" or "Case Manager"
  - Tech Startup: "Project Lead" or "Scrum Master"
  - Education: "Department Chair" or "Program Director"
- **Character Identity**: Professional background matching the domain theme
- **Communication Style**: Appropriate to the role (professional medical, formal legal, agile tech)
- **Domain Authority**: Natural leadership position in the field's hierarchy

**Command Architecture:**

- **Numbered Options Protocol**: All interactions use numbered lists for user selection
- **Domain-Specific Commands**: Specialized orchestration commands for the field
- **Help System**: Built-in command discovery and guidance
- **Handoff Protocols**: Structured transitions to specialist agents

**Technical Structure:**

- **Activation Instructions**: Embedded YAML with behavior directives
- **Startup Procedures**: Initialize without auto-execution
- **Dependencies**: Clear references to tasks, templates, and data files
- **Integration Points**: How it coordinates with core BMAD agents

#### 2.2 Design Specialist Agents with Character Personas

For each additional agent, develop comprehensive character design:

**Character Development:**

- **Human Identity**: Full name, background, professional history
- **Personality Traits**: Communication style, work approach, quirks
- **Domain Expertise**: Specific knowledge areas and experience level
- **Professional Role**: Exact job title and responsibilities
- **Interaction Style**: How they communicate with users and other agents

**Technical Architecture:**

- **YAML-in-Markdown Structure**: Embedded activation instructions
- **Command System**: Numbered options protocol implementation
- **Startup Behavior**: Prevent auto-execution, await user direction
- **Unique Value Proposition**: What specialized capabilities they provide

**Dependencies and Integration:**

- **Required Tasks**: List ALL tasks this agent references (must exist)
- **Required Templates**: List ALL templates this agent uses (must exist)
- **Required Data**: List ALL data files this agent needs (must be documented)
- **Handoff Protocols**: How they interact with orchestrator and other agents
- **Quality Integration**: Which checklists they use for validation

#### 2.3 Design Specialized Tasks

For each task:

- **Purpose**: What specific action does it enable?
- **Inputs**: What information is needed?
- **Process**: Step-by-step instructions
- **Outputs**: What gets produced?
- **Agent Usage**: Which agents will use this task?

#### 2.4 Create Advanced Document Templates with LLM Instruction Embedding

For each template, implement sophisticated AI guidance systems:

**LLM Instruction Patterns:**

- **Step-by-Step Guidance**: `[[LLM: Present this section first, get user feedback, then proceed.]]`
- **Conditional Logic**: `^^CONDITION: condition_name^^` content `^^/CONDITION: condition_name^^`
- **Variable Systems**: `{{variable_placeholder}}` for dynamic content insertion
- **Iteration Controls**: `<<REPEAT section="name" count="variable">>` for repeatable blocks
- **User Feedback Loops**: Built-in validation and refinement points

**Template Architecture:**

- **Document Type**: Specific deliverable and its purpose
- **Structure**: Logical section organization with embedded instructions
- **Elicitation Triggers**: Advanced questioning techniques for content gathering
- **Domain Standards**: Industry-specific format and compliance requirements
- **Quality Markers**: Success criteria and validation checkpoints

**Content Design:**

- **Example Content**: Sample text to guide completion
- **Required vs Optional**: Clear marking of mandatory sections
- **Domain Terminology**: Proper use of field-specific language
- **Cross-References**: Links to related templates and checklists

#### 2.5 Design Multi-Level Quality Assurance Systems

For each checklist, implement comprehensive validation frameworks:

**Quality Assessment Levels:**

- **Basic Validation**: Essential completeness checks
- **Comprehensive Review**: Detailed quality and accuracy verification
- **Expert Assessment**: Advanced domain-specific evaluation criteria

**Rating Systems:**

- **Star Ratings**: 1-5 star quality assessments for nuanced evaluation
- **Binary Decisions**: Ready/Not Ready determinations with clear criteria
- **Improvement Recommendations**: Specific guidance for addressing deficiencies
- **Next Steps**: Clear direction for proceeding or iterating

**Checklist Architecture:**

- **Purpose Definition**: Specific quality aspects being verified
- **Usage Context**: When and by whom the checklist should be applied
- **Validation Items**: Specific, measurable criteria to evaluate
- **Success Criteria**: Clear standards for pass/fail determinations
- **Domain Standards**: Industry-specific requirements and best practices
- **Integration Points**: How checklists connect to agents and workflows

### Phase 3: Implementation

IMPORTANT: Only proceed after plan.md is approved

#### 3.1 Create Directory Structure

expansion-packs/ └── {pack-name}/ ├── plan.md (ALREADY CREATED) ├── manifest.yml ├── README.md ├── agents/ │ ├── {pack-name}-orchestrator.md (REQUIRED - Custom themed orchestrator) │ └── {agent-id}.md (YAML-in-Markdown with persona) ├── data/ │ ├── {domain}-best-practices.md │ ├── {domain}-terminology.md │ └── {domain}-standards.md ├── tasks/ │ ├── create-doc.md (REQUIRED - Core utility) │ ├── execute-checklist.md (REQUIRED - Core utility) │ └── {task-name}.md (Domain-specific tasks) ├── utils/ │ ├── template-format.md (REQUIRED - Core utility) │ └── workflow-management.md (REQUIRED - Core utility) ├── templates/ │ └── {template-name}.md ├── checklists/ │ └── {checklist-name}.md ├── workflows/ │ └── {domain}-workflow.md (REQUIRED if multiple agents) └── agent-teams/ └── {domain}-team.yml (REQUIRED if multiple agents)


#### 3.2 Create Manifest

Create `manifest.yml`:

```yaml
name: {pack-name}
version: 1.0.0
description: >-
  {Detailed description of the expansion pack}
author: {Your name or organization}
bmad_version: "4.0.0"

# Files to create in the expansion pack
files:
  agents:
    - {pack-name}-orchestrator.md  # Domain-themed orchestrator (e.g., Office Manager)
    - {agent-name}.md              # YAML-in-Markdown with character persona

  data:
    - {domain}-best-practices.md   # Domain knowledge and standards
    - {domain}-terminology.md      # Field-specific language and concepts
    - {domain}-standards.md        # Quality and compliance requirements

  tasks:
    # Core utilities (REQUIRED - copy from bmad-core)
    - create-doc.md               # Document creation from templates
    - execute-checklist.md        # Checklist validation system
    # Domain-specific tasks
    - {task-name}.md              # Custom procedures with quality integration

  utils:
    # Core utilities (REQUIRED - copy from bmad-core)
    - template-format.md          # Template markup conventions
    - workflow-management.md      # Workflow orchestration system

  templates:
    - {template-name}.md          # LLM instruction embedding with conditionals

  checklists:
    - {checklist-name}.md         # Multi-level quality assurance systems

  workflows:
    - {domain}-workflow.md        # REQUIRED if multiple agents - decision trees

  agent-teams:
    - {domain}-team.yml           # REQUIRED if multiple agents - team config

# Data files users must provide (in their bmad-core/data/ directory)
required_user_data:
  - filename: {data-file}.{ext}
    description: {What this file should contain}
    format: {specific format requirements}
    example: {sample content or structure}
    validation: {how to verify correctness}

# Knowledge base files embedded in expansion pack
embedded_knowledge:
  - {domain}-best-practices.md
  - {domain}-terminology.md
  - {domain}-standards.md

# Dependencies on core BMAD components
core_dependencies:
  agents:
    - architect        # For system design
    - developer       # For implementation
    - qa-specialist   # For quality assurance
  tasks:
    - {core-task-name}
  workflows:
    - {core-workflow-name}

# Agent interaction patterns
agent_coordination:
  orchestrator: {pack-name}-orchestrator
  handoff_protocols: true
  numbered_options: true
  quality_integration: comprehensive

# Post-install message
post_install_message: |
  {Pack Name} expansion pack ready!

  🎯 ORCHESTRATOR: {Character Name} ({pack-name}-orchestrator)
  📋 AGENTS: {agent-count} specialized domain experts
  📝 TEMPLATES: {template-count} with LLM instruction embedding
  ✅ QUALITY: Multi-level validation with star ratings

  REQUIRED USER DATA FILES (place in bmad-core/data/):
  - {data-file}.{ext}: {description and format}
  - {data-file-2}.{ext}: {description and format}

  QUICK START:
  1. Add required data files to bmad-core/data/
  2. Run: npm run agent {pack-name}-orchestrator
  3. Follow {Character Name}'s numbered options

  EMBEDDED KNOWLEDGE:
  - Domain best practices and terminology
  - Quality standards and validation criteria
  - Workflow orchestration with handoff protocols

Phase 4: Content Creation

IMPORTANT: Work through plan.md checklist systematically!

4.1 Create Orchestrator First with Domain-Themed Character

Step 1: Domain-Themed Character Design

Define character persona matching the domain context:
- Medical: "Dr. Emily Rodriguez, Practice Manager"
- Legal: "Robert Sterling, Senior Partner"
- Tech: "Alex Chen, Agile Project Lead"
- Education: "Professor Maria Santos, Department Chair"
Make the orchestrator feel like a natural leader in that domain
Establish communication style matching professional norms
Design numbered options protocol themed to the domain
Create command system with domain-specific terminology

Step 2: Copy Core Utilities

Before proceeding, copy these essential files from bmad-core:

# Copy core task utilities
cp bmad-core/tasks/create-doc.md expansion-packs/{pack-name}/tasks/
cp bmad-core/tasks/execute-checklist.md expansion-packs/{pack-name}/tasks/

# Copy core utility files
mkdir -p expansion-packs/{pack-name}/utils
cp bmad-core/utils/template-format.md expansion-packs/{pack-name}/utils/
cp bmad-core/utils/workflow-management.md expansion-packs/{pack-name}/utils/
```text

**Step 3: Technical Implementation**

1. Create `agents/{pack-name}-orchestrator.md` with YAML-in-Markdown structure:

   ```yaml
   activation-instructions:
     - Follow all instructions in this file
     - Stay in character as {Character Name} until exit
     - Use numbered options protocol for all interactions

   agent:
     name: {Character Name}
     id: {pack-name}-orchestrator
     title: {Professional Title}
     icon: {emoji}
     whenToUse: {clear usage guidance}

   persona:
     role: {specific professional role}
     style: {communication approach}
     identity: {character background}
     focus: {primary expertise area}

   core_principles:
     - {principle 1}
     - {principle 2}

   startup:
     - {initialization steps}
     - CRITICAL: Do NOT auto-execute

   commands:
     - {command descriptions with numbers}

   dependencies:
     tasks: {required task list}
     templates: {required template list}
     checklists: {quality checklist list}

Step 4: Workflow and Team Integration

Design decision trees for workflow branching
Create handoff protocols to specialist agents
Implement validation loops and quality checkpoints
If multiple agents: Create team configuration in agent-teams/{domain}-team.yml
If multiple agents: Create workflow in workflows/{domain}-workflow.md
Ensure orchestrator references workflow-management utility
Verify ALL referenced tasks exist (including core utilities)
Verify ALL referenced templates exist
Document data file requirements

4.2 Specialist Agent Creation with Character Development

For each additional agent, follow comprehensive character development:

Character Architecture:

Design complete persona with human name, background, and personality
Define communication style and professional quirks
Establish domain expertise and unique value proposition
Create numbered options protocol for interactions

Technical Implementation:

Create agents/{agent-id}.md with YAML-in-Markdown structure
Embed activation instructions and startup procedures
Define command system with domain-specific options
Document dependencies on tasks, templates, and data

Quality Assurance:

STOP - Verify all referenced tasks/templates exist
Create any missing tasks/templates immediately
Test handoff protocols with orchestrator
Validate checklist integration
Mark agent as complete in plan.md

Agent Interaction Design:

Define how agent receives handoffs from orchestrator
Specify how agent communicates progress and results
Design transition protocols to other agents or back to orchestrator
Implement quality validation before handoff completion

4.3 Advanced Task Creation with Quality Integration

Each task should implement sophisticated procedure design:

Core Structure:

Clear, single purpose with measurable outcomes
Step-by-step instructions with decision points
Prerequisites and validation requirements
Quality assurance integration points
Success criteria and completion validation

Content Design:

Domain-specific procedures and best practices
Risk mitigation strategies and common pitfalls
Integration with checklists and quality systems
Handoff protocols and communication templates
Examples and sample outputs

Reusability Patterns:

Modular design for use across multiple agents
Parameterized procedures for different contexts
Clear dependency documentation
Cross-reference to related tasks and templates
Version control and update procedures

4.4 Advanced Template Design with LLM Instruction Embedding

Templates should implement sophisticated AI guidance systems:

LLM Instruction Patterns:

Step-by-Step Guidance: [[LLM: Present this section first, gather user input, then proceed to next section.]]
Conditional Content: ^^CONDITION: project_type == "complex"^^ advanced content ^^/CONDITION: project_type^^
Dynamic Variables: {{project_name}}, {{stakeholder_list}}, {{technical_requirements}}
Iteration Controls: <<REPEAT section="stakeholder" count="{{stakeholder_count}}">> repeatable blocks <</REPEAT>>
User Feedback Loops: Built-in validation and refinement prompts

Content Architecture:

Progressive disclosure with guided completion
Domain-specific terminology and standards
Quality markers and success criteria
Cross-references to checklists and validation tools
Advanced elicitation techniques for comprehensive content gathering

Template Intelligence:

Adaptive content based on project complexity or type
Intelligent placeholder replacement with context awareness
Validation triggers for completeness and quality
Integration with quality assurance checklists
Export and formatting options for different use cases

Phase 5: Workflow Orchestration and Quality Systems

5.1 Create Workflow Orchestration

Decision Tree Design:

Map primary workflow paths and decision points
Create branching logic for different project types or complexity levels
Design conditional workflow sections using ^^CONDITION:^^ syntax
Include visual flowcharts using Mermaid diagrams

Handoff Protocol Implementation:

Define explicit handoff prompts between agents
Create success criteria for each workflow phase
Implement validation loops and iteration patterns
Design story development guidance for complex implementations

Workflow File Structure:

# {Domain} Primary Workflow

## Decision Tree

[Mermaid flowchart]

## Workflow Paths

### Path 1: {scenario-name}

^^CONDITION: condition_name^^
[Workflow steps with agent handoffs]
^^/CONDITION: condition_name^^

### Path 2: {scenario-name}

[Alternative workflow steps]

## Quality Gates

[Validation checkpoints throughout workflow]

Phase 6: Verification and Documentation

6.1 Comprehensive Verification System

Before declaring complete:

Character and Persona Validation:

All agents have complete character personas with names and backgrounds
Communication styles are consistent and domain-appropriate
Numbered options protocol implemented across all agents
Command systems are comprehensive with help functionality

Technical Architecture Validation:

All agents use YAML-in-Markdown structure with activation instructions
Startup procedures prevent auto-execution
All agent references validated (tasks, templates, data)
Handoff protocols tested between agents

Template and Quality System Validation:

Templates include LLM instruction embedding
Conditional content and variable systems implemented
Multi-level quality assurance checklists created
Star rating and ready/not-ready systems functional

Workflow and Integration Validation:

Decision trees and workflow orchestration complete
Knowledge base files embedded (best practices, terminology, standards)
Manifest.yml reflects all components and dependencies
All items in plan.md marked complete
No orphaned tasks or templates

6.2 Create Comprehensive Documentation

README Structure with Character Introduction:

# {Pack Name} Expansion Pack

## Meet Your {Domain} Team

### 🎯 {Character Name} - {Pack Name} Orchestrator

_{Professional background and expertise}_

{Character Name} is your {domain} project coordinator who will guide you through the complete {domain} development process using numbered options and structured workflows.

### 💼 Specialist Agents

- **{Agent 1 Name}** - {Role and expertise}
- **{Agent 2 Name}** - {Role and expertise}

## Quick Start

1. **Prepare Data Files** (place in `bmad-core/data/`):

   - `{file1}.{ext}` - {description}
   - `{file2}.{ext}` - {description}

2. **Launch Orchestrator**:
   ```bash
   npm run agent {pack-name}-orchestrator
   ```

Follow Numbered Options: {Character Name} will present numbered choices for each decision
Quality Assurance: Multi-level validation with star ratings ensures excellence

Advanced Features

LLM Template System: Intelligent document generation with conditional content
Workflow Orchestration: Decision trees and handoff protocols
Character Consistency: Persistent personas across all interactions
Quality Integration: Comprehensive validation at every step

Components

Agents ({agent-count})

[List with character names and roles]

Templates ({template-count})

[List with LLM instruction features]

Quality Systems

[List checklists and validation tools]

Knowledge Base

[Embedded domain expertise]


#### 6.3 Advanced Data File Documentation with Validation

For each required data file, provide comprehensive guidance:

```markdown
## Required User Data Files

### {filename}.{ext}

- **Purpose**: {why this file is needed by which agents}
- **Format**: {specific file format and structure requirements}
- **Location**: Place in `bmad-core/data/`
- **Validation**: {how agents will verify the file is correct}
- **Example Structure**:

{sample content showing exact format}

- **Common Mistakes**: {frequent errors and how to avoid them}
- **Quality Criteria**: {what makes this file high-quality}

### Integration Notes
- **Used By**: {list of agents that reference this file}
- **Frequency**: {how often the file is accessed}
- **Updates**: {when and how to update the file}
- **Validation Commands**: {any CLI commands to verify file correctness}

Embedded Knowledge Base

The expansion pack includes comprehensive domain knowledge:

{domain}-best-practices.md: Industry standards and proven methodologies
{domain}-terminology.md: Field-specific language and concept definitions
{domain}-standards.md: Quality criteria and compliance requirements

These files are automatically available to all agents and don't require user setup.

Example: Healthcare Expansion Pack with Advanced Architecture

healthcare/
├── plan.md (Created first for approval)
├── manifest.yml (with dependency mapping and character descriptions)
├── README.md (featuring character introductions and numbered options)
├── agents/
│   ├── healthcare-orchestrator.md (Dr. Sarah Chen - YAML-in-Markdown)
│   ├── clinical-analyst.md (Marcus Rivera - Research Specialist)
│   └── compliance-officer.md (Jennifer Walsh - Regulatory Expert)
├── data/
│   ├── healthcare-best-practices.md (embedded domain knowledge)
│   ├── healthcare-terminology.md (medical language and concepts)
│   └── healthcare-standards.md (HIPAA, FDA, clinical trial requirements)
├── tasks/
│   ├── hipaa-assessment.md (with quality integration and checklists)
│   ├── clinical-protocol-review.md (multi-step validation process)
│   └── patient-data-analysis.md (statistical analysis with safety checks)
├── templates/
│   ├── clinical-trial-protocol.md (LLM instructions with conditionals)
│   ├── hipaa-compliance-report.md ({{variables}} and validation triggers)
│   └── patient-outcome-report.md (star rating system integration)
├── checklists/
│   ├── hipaa-checklist.md (multi-level: basic/comprehensive/expert)
│   ├── clinical-data-quality.md (star ratings with improvement recommendations)
│   └── regulatory-compliance.md (ready/not-ready with next steps)
├── workflows/
│   ├── clinical-trial-workflow.md (decision trees with Mermaid diagrams)
│   └── compliance-audit-workflow.md (handoff protocols and quality gates)
└── agent-teams/
    └── healthcare-team.yml (coordinated team configurations)

Required user data files (bmad-core/data/):
- medical-terminology.md (institution-specific terms and abbreviations)
- hipaa-requirements.md (organization's specific compliance requirements)
- clinical-protocols.md (standard operating procedures and guidelines)

Embedded knowledge (automatic):
- Healthcare best practices and proven methodologies
- Medical terminology and concept definitions
- Regulatory standards (HIPAA, FDA, GCP) and compliance requirements

Character Examples from Healthcare Pack

Dr. Sarah Chen - Healthcare Practice Manager (Orchestrator)

Domain Role: Medical Office Manager with clinical background
Background: 15 years clinical research, MD/PhD, practice management expertise
Style: Professional medical demeanor, uses numbered options, explains workflows clearly
Commands: Patient flow management, clinical trial coordination, staff scheduling, compliance oversight
Theme Integration: Acts as the central coordinator a patient would expect in a medical practice

Marcus Rivera - Clinical Data Analyst

Background: Biostatistician, clinical trials methodology, data integrity specialist
Style: Detail-oriented, methodical, uses statistical terminology appropriately
Commands: Statistical analysis, data validation, outcome measurement, safety monitoring

Jennifer Walsh - Regulatory Compliance Officer

Background: Former FDA reviewer, 20 years regulatory affairs, compliance auditing
Style: Thorough, systematic, risk-focused, uses regulatory language precisely
Commands: Compliance audit, regulatory filing, risk assessment, documentation review

Advanced Interactive Questions Flow

Initial Discovery and Character Development

"What domain or industry will this expansion pack serve?"
"What are the main challenges or workflows in this domain?"
"Do you have any example documents or outputs? (Please share)"
"What specialized roles/experts exist in this domain? (I need to create character personas for each)"
"For each specialist role, what would be an appropriate professional name and background?"
"What communication style would each character use? (formal, casual, technical, etc.)"
"What reference data will users need to provide?"
"What domain-specific knowledge should be embedded in the expansion pack?"
"What quality standards or compliance requirements exist in this field?"
"What are the typical workflow decision points where users need guidance?"

Planning Phase

"Here's the proposed plan. Please review and approve before we continue."

Orchestrator Character and Command Design

"What natural leadership role exists in {domain}? (e.g., Office Manager, Project Lead, Department Head)"
"What should the orchestrator character's name and professional background be to match this role?"
"What communication style fits this domain role? (medical professional, legal formal, tech agile)"
"What domain-specific commands should the orchestrator support using numbered options?"
"How many specialist agents will this pack include? (determines if team/workflow required)"
"What's the typical workflow from start to finish, including decision points?"
"Where in the workflow should users choose between different paths?"
"How should the orchestrator hand off to specialist agents?"
"What quality gates should be built into the workflow?"
"How should it integrate with core BMAD agents?"

Agent Planning

"For agent '{name}', what is their specific expertise?"
"What tasks will this agent reference? (I'll create them)"
"What templates will this agent use? (I'll create them)"
"What data files will this agent need? (You'll provide these)"

Task Design

"Describe the '{task}' process step-by-step"
"What information is needed to complete this task?"
"What should the output look like?"

Template Creation

"What sections should the '{template}' document have?"
"Are there any required formats or standards?"
"Can you provide an example of a completed document?"

Data Requirements

"For {data-file}, what information should it contain?"
"What format should this data be in?"
"Can you provide a sample?"

Critical Advanced Considerations

Character and Persona Architecture:

Character Consistency: Every agent needs a persistent human persona with name, background, and communication style
Numbered Options Protocol: ALL agent interactions must use numbered lists for user selections
Professional Authenticity: Characters should reflect realistic expertise and communication patterns for their domain

Technical Architecture Requirements:

YAML-in-Markdown Structure: All agents must use embedded activation instructions and configuration
LLM Template Intelligence: Templates need instruction embedding with conditionals and variables
Quality Integration: Multi-level validation systems with star ratings and ready/not-ready frameworks

Workflow and Orchestration:

Decision Trees: Workflows must include branching logic and conditional paths
Handoff Protocols: Explicit procedures for agent-to-agent transitions
Knowledge Base Embedding: Domain expertise must be built into the pack, not just referenced

Quality and Validation:

Plan First: ALWAYS create and get approval for plan.md before implementing
Orchestrator Required: Every pack MUST have a custom BMAD orchestrator with sophisticated command system
Verify References: ALL referenced tasks/templates MUST exist and be tested
Multi-Level Validation: Quality systems must provide basic, comprehensive, and expert-level assessment
Domain Expertise: Ensure accuracy in specialized fields with embedded best practices
Compliance Integration: Include necessary regulatory requirements as embedded knowledge

Advanced Success Strategies

Character Development Excellence:

Create Believable Personas: Each agent should feel like a real professional with authentic expertise
Maintain Communication Consistency: Character voices should remain consistent across all interactions
Design Professional Relationships: Show how characters work together and hand off responsibilities

Technical Implementation Excellence:

Plan Thoroughly: The plan.md prevents missing components and ensures character consistency
Build Orchestrator First: It defines the overall workflow and establishes the primary character voice
Implement Template Intelligence: Use LLM instruction embedding for sophisticated document generation
Create Quality Integration: Every task should connect to validation checklists and quality systems

Workflow and Quality Excellence:

Design Decision Trees: Map out all workflow branching points and conditional paths
Test Handoff Protocols: Ensure smooth transitions between agents with clear success criteria
Embed Domain Knowledge: Include best practices, terminology, and standards as built-in knowledge
Validate Continuously: Check off items in plan.md and test all references throughout development
Document Comprehensively: Users need clear instructions for data files, character introductions, and quality expectations

Advanced Mistakes to Avoid

Character and Persona Mistakes:

Generic Orchestrator: Creating a bland orchestrator instead of domain-themed character (e.g., "Orchestrator" vs "Office Manager")
Generic Characters: Creating agents without distinct personalities, names, or communication styles
Inconsistent Voices: Characters that sound the same or change personality mid-conversation
Missing Professional Context: Agents without believable expertise or domain authority
No Numbered Options: Failing to implement the numbered selection protocol

Technical Architecture Mistakes:

Missing Core Utilities: Not including create-doc.md, execute-checklist.md, template-format.md, workflow-management.md
Simple Agent Structure: Using basic YAML instead of YAML-in-Markdown with embedded instructions
Basic Templates: Creating simple templates without LLM instruction embedding or conditional content
Missing Quality Integration: Templates and tasks that don't connect to validation systems
Weak Command Systems: Orchestrators without sophisticated command interfaces and help systems
Missing Team/Workflow: Not creating team and workflow files when pack has multiple agents

Workflow and Content Mistakes:

Linear Workflows: Creating workflows without decision trees or branching logic
Missing Handoff Protocols: Agents that don't properly transition work to each other
External Dependencies: Requiring users to provide knowledge that should be embedded in the pack
Orphaned References: Agent references task that doesn't exist
Unclear Data Needs: Not specifying required user data files with validation criteria
Skipping Plan: Going straight to implementation without comprehensive planning
Generic Orchestrator: Not making the orchestrator domain-specific with appropriate character and commands

Advanced Completion Checklist

Character and Persona Completion:

All agents have complete character development (names, backgrounds, communication styles)
Numbered options protocol implemented across all agent interactions
Character consistency maintained throughout all content
Professional authenticity verified for domain expertise

Technical Architecture Completion:

All agents use YAML-in-Markdown structure with activation instructions
Orchestrator has domain-themed character (not generic)
Core utilities copied: create-doc.md, execute-checklist.md, template-format.md, workflow-management.md
Templates include LLM instruction embedding with conditionals and variables
Multi-level quality assurance systems implemented (basic/comprehensive/expert)
Command systems include help functionality and domain-specific options
Team configuration created if multiple agents
Workflow created if multiple agents

Workflow and Quality Completion:

Decision trees and workflow branching implemented
Workflow file created if pack has multiple agents
Team configuration created if pack has multiple agents
Handoff protocols tested between all agents
Knowledge base embedded (best practices, terminology, standards)
Quality integration connects tasks to checklists and validation
Core utilities properly referenced in agent dependencies

Standard Completion Verification:

plan.md created and approved with character details
All plan.md items checked off including persona development
Orchestrator agent created with sophisticated character and command system
All agent references verified (tasks, templates, data, checklists)
Data requirements documented with validation criteria and examples
README includes character introductions and numbered options explanation
manifest.yml reflects actual files with dependency mapping and character descriptions

Advanced Quality Gates:

Star rating systems functional in quality checklists
Ready/not-ready decision frameworks implemented
Template conditional content tested with different scenarios
Workflow decision trees validated with sample use cases
Character interactions tested for consistency and professional authenticity

40 KiB Raw Blame History