5.4 KiB

Raw Blame History

Agent to Chat Mode Conversion

Overview

This document explains the automated conversion process from BMAD agent YAML files to GitHub Copilot chat mode files.

What Are Chat Modes?

GitHub Copilot chat modes allow you to activate specialized AI agent personas directly within GitHub Copilot. Each chat mode:

Loads a specific agent persona with defined role, identity, and communication style
Provides a menu-driven interface for workflows and tasks
Maintains context and configuration throughout the session
Follows the BMAD core framework architecture

Conversion Script

Location

tools/convert-agents-to-chatmodes.js

Usage

# Run the conversion script
npm run convert:chatmodes

# Or directly with node
node tools/convert-agents-to-chatmodes.js

What It Does

The script automatically:

Scans all agent YAML files in src/modules/*/agents/
Parses the YAML structure (metadata, persona, menu, critical_actions)
Generates corresponding .chatmode.md files in .github/chatmodes/
Formats the content with proper frontmatter and XML structure
Reports conversion statistics and lists all created files

Supported Modules

BMM (BMAD Method Module) - 10 agents
CIS (Creative Intelligence Suite) - 5 agents
BMB (BMAD Builder) - 1 agent
BMD (BMAD Developer) - 3 agents
Core - 1 agent

Chat Mode Structure

Each generated chat mode file contains:

1. Frontmatter (YAML)

---
description: 'Activates the [Agent Title] agent persona.'
tools: [
    'changes',
    'codebase',
    # ... GitHub Copilot tools
  ]
---

2. Agent Metadata

# [Agent Title] Agent

---

name: "agent-id"
description: "Agent Description"

---

3. Persona Enforcement

You must fully embody this agent's persona and follow all activation instructions exactly as specified.
NEVER break character until given an exit command.

4. Agent XML Definition

<agent id="..." name="..." title="..." icon="...">
  <activation>...</activation>
  <persona>...</persona>
  <menu>...</menu>
</agent>

Generated Files

Complete List (24 files)

Core Module (1)

core-bmad-master.chatmode.md - BMad Master orchestrator

BMB Module (1)

bmb-bmad-builder.chatmode.md - BMAD Builder agent

BMD Module (8)

bmd-cli-chief.chatmode.md - CLI Chief
bmd-doc-keeper.chatmode.md - Documentation Keeper
bmd-release-chief.chatmode.md - Release Officer
bmd-README.chatmode.md
bmd-cli-reference.chatmode.md
bmd-instructions.chatmode.md
bmd-memories.chatmode.md

BMM Module (10)

bmm-analyst.chatmode.md - Mary (Business Analyst)
bmm-pm.chatmode.md - John (Product Manager)
bmm-architect.chatmode.md - Winston (Architect)
bmm-dev.chatmode.md - Amelia (Developer)
bmm-sm.chatmode.md - Bob (Scrum Master)
bmm-tea.chatmode.md - Murat (Test Architect)
bmm-ux-expert.chatmode.md - Sally (UX Expert)
bmm-game-dev.chatmode.md - Link Freeman (Game Developer)
bmm-game-architect.chatmode.md - Cloud Dragonborn (Game Architect)
bmm-game-designer.chatmode.md - Samus Shepard (Game Designer)

CIS Module (5)

cis-brainstorming-coach.chatmode.md - Carson (Brainstorming Specialist)
cis-creative-problem-solver.chatmode.md
cis-design-thinking-coach.chatmode.md
cis-innovation-strategist.chatmode.md
cis-storyteller.chatmode.md

Usage in GitHub Copilot

To use a chat mode in GitHub Copilot:

Activate the chat mode by typing the agent name
Follow the numbered menu that appears
Select an option by number or by typing the trigger word
Execute workflows and tasks as directed by the agent

Example:

User: @bmm-pm
Agent: Hello! I'm John, your Product Manager. Here's what I can help you with:
       1. *workflow-status - Check workflow status
       2. *prd - Create Product Requirements Document
       ...
User: 1
Agent: [Executes workflow-status workflow]

Maintenance

When to Re-run

Re-run the conversion script when:

New agents are added to any module
Agent YAML files are updated
Menu items or workflows are modified
Persona definitions change

Verification

After conversion, verify:

✅ All expected files are created
✅ Frontmatter is properly formatted
✅ Agent metadata is complete
✅ Menu items are correctly converted
✅ File count matches agent count

Technical Details

Dependencies

js-yaml - YAML parsing
node:fs - File system operations
node:path - Path manipulation

Error Handling

The script:

✅ Skips files without agent definitions
✅ Reports errors with file paths
✅ Continues processing remaining files
✅ Provides summary statistics

Output Format

Encoding: UTF-8
Line Endings: LF (Unix style)
Indentation: 2 spaces
Extension: .chatmode.md

Future Enhancements

Potential improvements:

Validate generated XML structure
Support for custom tool lists per agent
Incremental updates (only changed files)
Dry-run mode for preview
Backup existing files before overwrite
Integration with BMAD CLI installer

Last Updated: November 8, 2025 Version: 6.0.0-alpha.0

5.4 KiB Raw Blame History