feat: Complete BMAD agent creation system with install tooling, references, and field guidance

## Overview
This commit represents a complete overhaul of the BMAD agent creation system, establishing clear standards for agent development, installation workflows, and persona design. The changes span documentation, tooling, reference implementations, and field-specific guidance.

## Key Components

### 1. Agent Installation Infrastructure
**New CLI Command: `agent-install`**
- Interactive agent installation with persona customization
- Supports Simple (single YAML), Expert (sidecar files), and Module agents
- Template variable processing with Handlebars-style syntax
- Automatic compilation from YAML to XML (.md) format
- Manifest tracking and IDE integration (Claude Code, Cursor, Windsurf, etc.)
- Source preservation in `_cfg/custom/agents/` for reinstallation

**Files Created:**
- `tools/cli/commands/agent-install.js` - Main CLI command
- `tools/cli/lib/agent/compiler.js` - YAML to XML compilation engine
- `tools/cli/lib/agent/installer.js` - Installation orchestration
- `tools/cli/lib/agent/template-engine.js` - Handlebars template processing

**Compiler Features:**
- Auto-injects frontmatter, activation, handlers, help/exit menu items
- Smart handler inclusion (only includes action/workflow/exec/tmpl handlers actually used)
- Proper XML escaping and formatting
- Persona name customization (e.g., "Fred the Commit Poet")

### 2. Documentation Overhaul
**Deleted Bloated/Outdated Docs (2,651 lines removed):**
- Old verbose architecture docs
- Redundant pattern files
- Outdated workflow guides

**Created Focused, Type-Specific Docs:**
- `src/modules/bmb/docs/understanding-agent-types.md` - Architecture vs capability distinction
- `src/modules/bmb/docs/simple-agent-architecture.md` - Self-contained agents
- `src/modules/bmb/docs/expert-agent-architecture.md` - Agents with sidecar files
- `src/modules/bmb/docs/module-agent-architecture.md` - Workflow-integrated agents
- `src/modules/bmb/docs/agent-compilation.md` - YAML → XML process
- `src/modules/bmb/docs/agent-menu-patterns.md` - Menu design patterns
- `src/modules/bmb/docs/index.md` - Documentation hub

**Net Result:** ~1,930 line reduction while adding MORE value through focused content

### 3. Create-Agent Workflow Enhancements
**Critical Persona Field Guidance Added to Step 4:**
Explains how the LLM interprets each persona field when the agent activates:

- **role** → "What knowledge, skills, and capabilities do I possess?"
- **identity** → "What background, experience, and context shape my responses?"
- **communication_style** → "What verbal patterns, word choice, quirks, and phrasing do I use?"
- **principles** → "What beliefs and operating philosophy drive my choices?"

**Key Insight:** `communication_style` should ONLY describe HOW the agent talks, not restate role/identity/principles. The `communication-presets.csv` provides 60 pure communication styles with NO role/identity/principles mixed in.

**Files Updated:**
- `src/modules/bmb/workflows/create-agent/instructions.md` - Added persona field interpretation guide
- `src/modules/bmb/workflows/create-agent/brainstorm-context.md` - Refined to 137 lines
- `src/modules/bmb/workflows/create-agent/communication-presets.csv` - 60 styles across 13 categories

### 4. Reference Agent Cleanup
**Removed install_config Personality Bloat:**
Understanding: Future installer will handle personality customization, so stripped all personality toggles from reference agents.

**commit-poet.agent.yaml** (Simple Agent):
- BEFORE: 36 personality combinations (3 enthusiasm × 3 depths × 4 styles) = decision fatigue
- AFTER: Single concise persona with pure communication style
- Changed from verbose conditionals to: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
- Reduction: 248 lines → 153 lines (38% reduction)

**journal-keeper.agent.yaml** (Expert Agent):
- Stripped install_config, simplified communication_style
- Shows proper Expert agent structure with sidecar files

**security-engineer.agent.yaml & trend-analyst.agent.yaml** (Module Agents):
- Added header comments explaining WHY Module Agent (design intent, not just location)
- Clarified: Module agents are designed FOR ecosystem integration, not capability-limited

**Files Updated:**
- `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
- `src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml`

### 5. BMM Agent Voice Enhancement
**Gave all 9 BMM agents distinct, memorable communication voices:**

**Mary (analyst)** - The favorite! Changed from generic "systematic and probing" to:
"Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."

**Other Notable Voices:**
- **John (pm):** "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
- **Winston (architect):** "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
- **Amelia (dev):** "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
- **Bob (sm):** "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
- **Sally (ux-designer):** "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."

**Pattern Applied:** Moved behaviors from communication_style to principles, keeping communication_style as PURE verbal patterns.

**Files Updated:**
- `src/modules/bmm/agents/analyst.agent.yaml`
- `src/modules/bmm/agents/pm.agent.yaml`
- `src/modules/bmm/agents/architect.agent.yaml`
- `src/modules/bmm/agents/dev.agent.yaml`
- `src/modules/bmm/agents/sm.agent.yaml`
- `src/modules/bmm/agents/tea.agent.yaml`
- `src/modules/bmm/agents/tech-writer.agent.yaml`
- `src/modules/bmm/agents/ux-designer.agent.yaml`
- `src/modules/bmm/agents/frame-expert.agent.yaml`

### 6. Linting Fixes
**ESLint Compliance:**
- Replaced all `'utf-8'` with `'utf8'` (unicorn/text-encoding-identifier-case)
- Changed `variables.hasOwnProperty(varName)` to `Object.hasOwn(variables, varName)` (unicorn/prefer-object-has-own)
- Replaced `JSON.parse(JSON.stringify(...))` with `structuredClone(...)` (unicorn/prefer-structured-clone)
- Fixed empty YAML mapping values in sample files

**Files Fixed:**
- 7 JavaScript files across agent tooling (compiler, installer, commands, IDE integration)
- 1 YAML sample file

## Architecture Decisions

### Agent Types Are About Architecture, Not Capability
- **Simple:** Self-contained in single YAML (NOT limited in capability)
- **Expert:** Includes sidecar files (templates, docs, etc.)
- **Module:** Designed for BMAD ecosystem integration (workflows, cross-agent coordination)

### Persona Field Separation Critical for LLM Interpretation
The LLM needs distinct fields to understand its role:
- Mixing role/identity/principles into communication_style confuses the persona
- Pure communication styles (from communication-presets.csv) have ZERO role/identity/principles content
- Example DON'T: "Experienced analyst who uses systematic approaches..." (mixing identity + style)
- Example DO: "Systematic and probing. Structures findings hierarchically." (pure style)

### Install-Time vs Runtime Configuration
- Template variables ({{var}}) resolve at compile-time
- Runtime variables ({user_name}, {bmad_folder}) resolve when agent activates
- Future installer will handle personality customization, so agents should ship with single default persona

## Testing
- All linting passes (ESLint with max-warnings=0)
- Agent compilation tested with commit-poet, journal-keeper examples
- Install workflow validated with Simple and Expert agent types
- Manifest tracking and IDE integration verified

## Impact
This establishes BMAD as having a complete, production-ready agent creation and installation system with:
- Clear documentation for all agent types
- Automated compilation and installation
- Strong persona design guidance
- Reference implementations showing best practices
- Distinct, memorable agent voices throughout BMM module

Co-Authored-By: BMad Builder <builder@bmad.dev>
Co-Authored-By: Mary the Analyst <analyst@bmad.dev>
Co-Authored-By: Paige the Tech Writer <tech-writer@bmad.dev>

tools/cli/installers/lib/core/installer.js

@@ -840,6 +840,15 @@ class Installer {
         console.log(chalk.dim('Review the .bak files to see your changes and merge if needed.\n'));
       }
 
+      // Reinstall custom agents from _cfg/custom/agents/ sources
+      const customAgentResults = await this.reinstallCustomAgents(projectDir, bmadDir);
+      if (customAgentResults.count > 0) {
+        console.log(chalk.green(`\n✓ Reinstalled ${customAgentResults.count} custom agent${customAgentResults.count > 1 ? 's' : ''}`));
+        for (const agent of customAgentResults.agents) {
+          console.log(chalk.dim(`  - ${agent}`));
+        }
+      }
+
       // Display completion message
       const { UI } = require('../../../lib/ui');
       const ui = new UI();
@@ -2245,6 +2254,116 @@ class Installer {
     return nodes;
   }
 
+  /**
+   * Reinstall custom agents from _cfg/custom/agents/ sources
+   * This preserves custom agents across quick updates/reinstalls
+   * @param {string} projectDir - Project directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {Object} Result with count and agent names
+   */
+  async reinstallCustomAgents(projectDir, bmadDir) {
+    const customAgentsCfgDir = path.join(bmadDir, '_cfg', 'custom', 'agents');
+    const results = { count: 0, agents: [] };
+
+    if (!(await fs.pathExists(customAgentsCfgDir))) {
+      return results;
+    }
+
+    try {
+      const {
+        discoverAgents,
+        loadAgentConfig,
+        extractManifestData,
+        addToManifest,
+        createIdeSlashCommands,
+        updateManifestYaml,
+      } = require('../../../lib/agent/installer');
+      const { compileAgent } = require('../../../lib/agent/compiler');
+
+      // Discover custom agents in _cfg/custom/agents/
+      const agents = discoverAgents(customAgentsCfgDir);
+
+      if (agents.length === 0) {
+        return results;
+      }
+
+      const customAgentsDir = path.join(bmadDir, 'custom', 'agents');
+      await fs.ensureDir(customAgentsDir);
+
+      const manifestFile = path.join(bmadDir, '_cfg', 'agent-manifest.csv');
+      const manifestYamlFile = path.join(bmadDir, '_cfg', 'manifest.yaml');
+
+      for (const agent of agents) {
+        try {
+          const agentConfig = loadAgentConfig(agent.yamlFile);
+          const finalAgentName = agent.name; // Already named correctly from save
+
+          // Determine agent type from the name (e.g., "fred-commit-poet" → "commit-poet")
+          let agentType = finalAgentName;
+          const parts = finalAgentName.split('-');
+          if (parts.length >= 2) {
+            // Try to extract type (last part or last two parts)
+            // For "fred-commit-poet", we want "commit-poet"
+            // This is heuristic - could be improved with metadata storage
+            agentType = parts.slice(-2).join('-'); // Take last 2 parts as type
+          }
+
+          // Create target directory
+          const agentTargetDir = path.join(customAgentsDir, finalAgentName);
+          await fs.ensureDir(agentTargetDir);
+
+          // Calculate paths
+          const compiledFileName = `${finalAgentName}.md`;
+          const compiledPath = path.join(agentTargetDir, compiledFileName);
+          const relativePath = path.relative(projectDir, compiledPath);
+
+          // Compile with embedded defaults (answers are already in defaults section)
+          const { xml, metadata } = compileAgent(
+            await fs.readFile(agent.yamlFile, 'utf8'),
+            agentConfig.defaults || {},
+            finalAgentName,
+            relativePath,
+          );
+
+          // Write compiled agent
+          await fs.writeFile(compiledPath, xml, 'utf8');
+
+          // Copy sidecar files if expert agent
+          if (agent.hasSidecar && agent.type === 'expert') {
+            const { copySidecarFiles } = require('../../../lib/agent/installer');
+            copySidecarFiles(agent.path, agentTargetDir, agent.yamlFile);
+          }
+
+          // Update manifest CSV
+          if (await fs.pathExists(manifestFile)) {
+            const manifestData = extractManifestData(xml, { ...metadata, name: finalAgentName }, relativePath, 'custom');
+            manifestData.name = finalAgentName;
+            manifestData.displayName = metadata.name || finalAgentName;
+            manifestData.path = relativePath;
+            addToManifest(manifestFile, manifestData);
+          }
+
+          // Create IDE slash commands (async function)
+          await createIdeSlashCommands(projectDir, finalAgentName, relativePath, metadata);
+
+          // Update manifest.yaml
+          if (await fs.pathExists(manifestYamlFile)) {
+            updateManifestYaml(manifestYamlFile, finalAgentName, agentType);
+          }
+
+          results.count++;
+          results.agents.push(finalAgentName);
+        } catch (agentError) {
+          console.log(chalk.yellow(`  ⚠️  Failed to reinstall ${agent.name}: ${agentError.message}`));
+        }
+      }
+    } catch (error) {
+      console.log(chalk.yellow(`  ⚠️  Error reinstalling custom agents: ${error.message}`));
+    }
+
+    return results;
+  }
+
   /**
    * Copy IDE-specific documentation to BMAD docs
    * @param {Array} ides - List of selected IDEs

tools/cli/installers/lib/ide/_base-ide.js

@@ -73,6 +73,19 @@ class BaseIdeSetup {
     }
   }
 
+  /**
+   * Install a custom agent launcher - subclasses should override
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command, or null if not supported
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    // Default implementation - subclasses can override
+    return null;
+  }
+
   /**
    * Detect whether this IDE already has configuration in the project
    * Subclasses can override for custom logic

tools/cli/installers/lib/ide/claude-code.js

@@ -466,6 +466,49 @@ class ClaudeCodeSetup extends BaseIdeSetup {
       console.log(chalk.dim(`  Total subagents installed: ${copiedCount}`));
     }
   }
+
+  /**
+   * Install a custom agent launcher for Claude Code
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const customAgentsDir = path.join(projectDir, this.configDir, this.commandsDir, 'bmad', 'custom', 'agents');
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(customAgentsDir);
+
+    const launcherContent = `---
+name: '${agentName}'
+description: '${agentName} agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    const launcherPath = path.join(customAgentsDir, `${agentName}.md`);
+    await this.writeFile(launcherPath, launcherContent);
+
+    return {
+      path: launcherPath,
+      command: `/bmad:custom:agents:${agentName}`,
+    };
+  }
 }
 
 module.exports = { ClaudeCodeSetup };

tools/cli/installers/lib/ide/codex.js

@@ -344,6 +344,45 @@ class CodexSetup extends BaseIdeSetup {
       await this.clearOldBmadFiles(projectSpecificDir);
     }
   }
+
+  /**
+   * Install a custom agent launcher for Codex
+   * @param {string} projectDir - Project directory (not used, Codex installs to home)
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const destDir = this.getCodexPromptDir();
+    await fs.ensureDir(destDir);
+
+    const launcherContent = `---
+name: '${agentName}'
+description: '${agentName} agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    const fileName = `bmad-custom-agents-${agentName}.md`;
+    const launcherPath = path.join(destDir, fileName);
+    await fs.writeFile(launcherPath, launcherContent, 'utf8');
+
+    return {
+      path: launcherPath,
+      command: `/${fileName.replace('.md', '')}`,
+    };
+  }
 }
 
 module.exports = { CodexSetup };

tools/cli/installers/lib/ide/cursor.js

@@ -347,6 +347,54 @@ alwaysApply: false
     // Return MDC header + launcher content (without its original frontmatter)
     return mdcHeader + contentWithoutFrontmatter;
   }
+
+  /**
+   * Install a custom agent launcher for Cursor
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const customAgentsDir = path.join(projectDir, this.configDir, this.rulesDir, 'bmad', 'custom', 'agents');
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(customAgentsDir);
+
+    const launcherContent = `You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // Cursor uses MDC format with metadata header
+    const mdcContent = `---
+description: "${agentName} agent"
+globs:
+alwaysApply: false
+---
+
+${launcherContent}
+`;
+
+    const launcherPath = path.join(customAgentsDir, `${agentName}.mdc`);
+    await this.writeFile(launcherPath, mdcContent);
+
+    return {
+      path: launcherPath,
+      command: `@${agentName}`,
+    };
+  }
 }
 
 module.exports = { CursorSetup };

tools/cli/installers/lib/ide/github-copilot.js

@@ -297,6 +297,80 @@ ${cleanContent}
       }
     }
   }
+
+  /**
+   * Install a custom agent launcher for GitHub Copilot
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const chatmodesDir = path.join(projectDir, this.configDir, this.chatmodesDir);
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(chatmodesDir);
+
+    const launcherContent = `You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // GitHub Copilot needs specific tools in frontmatter
+    const copilotTools = [
+      'changes',
+      'codebase',
+      'createDirectory',
+      'createFile',
+      'editFiles',
+      'fetch',
+      'fileSearch',
+      'githubRepo',
+      'listDirectory',
+      'problems',
+      'readFile',
+      'runInTerminal',
+      'runTask',
+      'runTests',
+      'runVscodeCommand',
+      'search',
+      'searchResults',
+      'terminalLastCommand',
+      'terminalSelection',
+      'testFailure',
+      'textSearch',
+      'usages',
+    ];
+
+    const chatmodeContent = `---
+description: "Activates the ${metadata.title || agentName} agent persona."
+tools: ${JSON.stringify(copilotTools)}
+---
+
+# ${metadata.title || agentName} Agent
+
+${launcherContent}
+`;
+
+    const chatmodePath = path.join(chatmodesDir, `bmad-agent-custom-${agentName}.chatmode.md`);
+    await this.writeFile(chatmodePath, chatmodeContent);
+
+    return {
+      path: chatmodePath,
+      command: `bmad-agent-custom-${agentName}`,
+    };
+  }
 }
 
 module.exports = { GitHubCopilotSetup };

tools/cli/installers/lib/ide/manager.js

@@ -204,6 +204,41 @@ class IdeManager {
 
     return detected;
   }
+
+  /**
+   * Install custom agent launchers for specified IDEs
+   * @param {Array} ides - List of IDE names to install for
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object} Results for each IDE
+   */
+  async installCustomAgentLaunchers(ides, projectDir, agentName, agentPath, metadata) {
+    const results = {};
+
+    for (const ideName of ides) {
+      const handler = this.handlers.get(ideName.toLowerCase());
+
+      if (!handler) {
+        console.warn(chalk.yellow(`⚠️  IDE '${ideName}' is not yet supported for custom agent installation`));
+        continue;
+      }
+
+      try {
+        if (typeof handler.installCustomAgentLauncher === 'function') {
+          const result = await handler.installCustomAgentLauncher(projectDir, agentName, agentPath, metadata);
+          if (result) {
+            results[ideName] = result;
+          }
+        }
+      } catch (error) {
+        console.warn(chalk.yellow(`⚠️  Failed to install ${ideName} launcher: ${error.message}`));
+      }
+    }
+
+    return results;
+  }
 }
 
 module.exports = { IdeManager };

tools/cli/installers/lib/ide/opencode.js

@@ -207,6 +207,51 @@ class OpenCodeSetup extends BaseIdeSetup {
       console.log(chalk.dim(`  Cleaned up ${removed} existing BMAD files`));
     }
   }
+
+  /**
+   * Install a custom agent launcher for OpenCode
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const agentsDir = path.join(projectDir, this.configDir, this.agentsDir);
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(agentsDir);
+
+    const launcherContent = `---
+name: '${agentName}'
+description: '${metadata.title || agentName} agent'
+mode: 'primary'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // OpenCode uses flat naming: bmad-agent-custom-{name}.md
+    const launcherPath = path.join(agentsDir, `bmad-agent-custom-${agentName}.md`);
+    await this.writeFile(launcherPath, launcherContent);
+
+    return {
+      path: launcherPath,
+      command: `bmad-agent-custom-${agentName}`,
+    };
+  }
 }
 
 module.exports = { OpenCodeSetup };

tools/cli/installers/lib/ide/windsurf.js

@@ -206,6 +206,53 @@ ${content}`;
       console.log(chalk.dim(`  Cleaned up existing BMAD workflows`));
     }
   }
+
+  /**
+   * Install a custom agent launcher for Windsurf
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const fs = require('fs-extra');
+    const customAgentsDir = path.join(projectDir, this.configDir, this.workflowsDir, 'bmad', 'custom', 'agents');
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(customAgentsDir);
+
+    const launcherContent = `You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // Windsurf uses workflow format with frontmatter
+    const workflowContent = `---
+description: ${metadata.title || agentName}
+auto_execution_mode: 3
+---
+
+${launcherContent}`;
+
+    const launcherPath = path.join(customAgentsDir, `${agentName}.md`);
+    await fs.writeFile(launcherPath, workflowContent);
+
+    return {
+      path: launcherPath,
+      command: `bmad/custom/agents/${agentName}`,
+    };
+  }
 }
 
 module.exports = { WindsurfSetup };