bmad-method 5.1.3 → 6.0.0-alpha.0

package/tools/cli/installers/lib/ide/cline.js

@@ -0,0 +1,301 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+/**
+ * Cline IDE setup handler
+ * Creates rules in .clinerules directory with ordering support
+ */
+class ClineSetup extends BaseIdeSetup {
+  constructor() {
+    super('cline', 'Cline');
+    this.configDir = '.clinerules';
+    this.defaultOrder = {
+      core: 10,
+      bmm: 20,
+      cis: 30,
+      other: 99,
+    };
+  }
+
+  /**
+   * Collect configuration choices before installation
+   * @param {Object} options - Configuration options
+   * @returns {Object} Collected configuration
+   */
+  async collectConfiguration(options = {}) {
+    const response = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'ordering',
+        message: 'How should BMAD rules be ordered in Cline?',
+        choices: [
+          { name: 'By module (core first, then modules)', value: 'module' },
+          { name: 'By importance (dev agents first)', value: 'importance' },
+          { name: 'Alphabetical (simple A-Z ordering)', value: 'alphabetical' },
+          { name: "Custom (I'll reorder manually)", value: 'custom' },
+        ],
+        default: 'module',
+      },
+    ]);
+
+    return { ordering: response.ordering };
+  }
+
+  /**
+   * Setup Cline IDE configuration
+   * @param {string} projectDir - Project directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, bmadDir, options = {}) {
+    console.log(chalk.cyan(`Setting up ${this.name}...`));
+
+    // Create .clinerules directory
+    const clineRulesDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(clineRulesDir);
+
+    // Get agents and tasks
+    const agents = await this.getAgents(bmadDir);
+    const tasks = await this.getTasks(bmadDir);
+
+    // Use pre-collected configuration if available
+    const config = options.preCollectedConfig || {};
+    const orderingStrategy = config.ordering || options.ordering || 'module';
+
+    // Process agents as rules with ordering
+    let ruleCount = 0;
+    for (const agent of agents) {
+      const content = await this.readFile(agent.path);
+      const order = this.getOrder(agent, orderingStrategy);
+      const processedContent = this.createAgentRule(agent, content, projectDir);
+
+      // Use numeric prefix for ordering
+      const prefix = order.toString().padStart(2, '0');
+      const targetPath = path.join(clineRulesDir, `${prefix}-${agent.module}-${agent.name}.md`);
+
+      await this.writeFile(targetPath, processedContent);
+      ruleCount++;
+    }
+
+    // Process tasks with ordering
+    for (const task of tasks) {
+      const content = await this.readFile(task.path);
+      const order = this.getTaskOrder(task, orderingStrategy);
+      const processedContent = this.createTaskRule(task, content);
+
+      // Tasks get higher order numbers to appear after agents
+      const prefix = (order + 50).toString().padStart(2, '0');
+      const targetPath = path.join(clineRulesDir, `${prefix}-task-${task.module}-${task.name}.md`);
+
+      await this.writeFile(targetPath, processedContent);
+      ruleCount++;
+    }
+
+    console.log(chalk.green(`✓ ${this.name} configured:`));
+    console.log(chalk.dim(`  - ${ruleCount} rules created in ${path.relative(projectDir, clineRulesDir)}`));
+    console.log(chalk.dim(`  - Ordering: ${orderingStrategy}`));
+
+    // Important message about toggle system
+    console.log(chalk.yellow('\n  ⚠️  IMPORTANT: Cline Toggle System'));
+    console.log(chalk.cyan('  Rules are OFF by default to avoid context pollution'));
+    console.log(chalk.dim('  To use BMAD agents:'));
+    console.log(chalk.dim('    1. Click rules icon below chat input'));
+    console.log(chalk.dim('    2. Toggle ON the specific agent you need'));
+    console.log(chalk.dim('    3. Type @{agent-name} to activate'));
+    console.log(chalk.dim('    4. Toggle OFF when done to free context'));
+    console.log(chalk.dim('\n  💡 Best practice: Only enable 1-2 agents at a time'));
+
+    return {
+      success: true,
+      rules: ruleCount,
+      ordering: orderingStrategy,
+    };
+  }
+
+  /**
+   * Ask user about rule ordering strategy
+   */
+  async askOrderingStrategy() {
+    const response = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'ordering',
+        message: 'How should BMAD rules be ordered in Cline?',
+        choices: [
+          { name: 'By module (core first, then modules)', value: 'module' },
+          { name: 'By importance (dev agents first)', value: 'importance' },
+          { name: 'Alphabetical (simple A-Z ordering)', value: 'alphabetical' },
+          { name: "Custom (I'll reorder manually)", value: 'custom' },
+        ],
+        default: 'module',
+      },
+    ]);
+
+    return response.ordering;
+  }
+
+  /**
+   * Get order number for an agent based on strategy
+   */
+  getOrder(agent, strategy) {
+    switch (strategy) {
+      case 'module': {
+        return this.defaultOrder[agent.module] || this.defaultOrder.other;
+      }
+
+      case 'importance': {
+        // Prioritize certain agent types
+        if (agent.name.includes('dev') || agent.name.includes('code')) return 10;
+        if (agent.name.includes('architect') || agent.name.includes('design')) return 15;
+        if (agent.name.includes('test') || agent.name.includes('qa')) return 20;
+        if (agent.name.includes('doc') || agent.name.includes('write')) return 25;
+        if (agent.name.includes('review')) return 30;
+        return 40;
+      }
+
+      case 'alphabetical': {
+        // Use a fixed number, files will sort alphabetically by name
+        return 50;
+      }
+
+      default: {
+        // 'custom' or any other value - user will reorder manually
+        return 99;
+      }
+    }
+  }
+
+  /**
+   * Get order number for a task
+   */
+  getTaskOrder(task, strategy) {
+    // Tasks always come after agents
+    return this.getOrder(task, strategy) + 50;
+  }
+
+  /**
+   * Create rule content for an agent
+   */
+  createAgentRule(agent, content, projectDir) {
+    // Extract metadata
+    const titleMatch = content.match(/title="([^"]+)"/);
+    const title = titleMatch ? titleMatch[1] : this.formatTitle(agent.name);
+
+    // Extract YAML content
+    const yamlMatch = content.match(/```ya?ml\r?\n([\s\S]*?)```/);
+    const yamlContent = yamlMatch ? yamlMatch[1] : content;
+
+    // Get relative path
+    const relativePath = path.relative(projectDir, agent.path).replaceAll('\\', '/');
+
+    let ruleContent = `# ${title} Agent
+
+This rule defines the ${title} persona and project standards.
+
+## Role Definition
+
+When the user types \`@${agent.name}\`, adopt this persona and follow these guidelines:
+
+\`\`\`yaml
+${yamlContent}
+\`\`\`
+
+## Project Standards
+
+- Always maintain consistency with project documentation in BMAD directories
+- Follow the agent's specific guidelines and constraints
+- Update relevant project files when making changes
+- Reference the complete agent definition in [${relativePath}](${relativePath})
+
+## Usage
+
+Type \`@${agent.name}\` to activate this ${title} persona.
+
+## Module
+
+Part of the BMAD ${agent.module.toUpperCase()} module.
+`;
+
+    return ruleContent;
+  }
+
+  /**
+   * Create rule content for a task
+   */
+  createTaskRule(task, content) {
+    // Extract task name
+    const nameMatch = content.match(/<name>([^<]+)<\/name>/);
+    const taskName = nameMatch ? nameMatch[1] : this.formatTitle(task.name);
+
+    let ruleContent = `# ${taskName} Task
+
+This rule defines the ${taskName} task workflow.
+
+## Task Workflow
+
+When this task is referenced, execute the following steps:
+
+${content}
+
+## Project Integration
+
+- This task follows BMAD Method standards
+- Ensure all outputs align with project conventions
+- Update relevant documentation after task completion
+
+## Usage
+
+Reference with \`@task-${task.name}\` to access this workflow.
+
+## Module
+
+Part of the BMAD ${task.module.toUpperCase()} module.
+`;
+
+    return ruleContent;
+  }
+
+  /**
+   * Format name as title
+   */
+  formatTitle(name) {
+    return name
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  /**
+   * Cleanup Cline configuration
+   */
+  async cleanup(projectDir) {
+    const fs = require('fs-extra');
+    const clineRulesDir = path.join(projectDir, this.configDir);
+
+    if (await fs.pathExists(clineRulesDir)) {
+      // Remove all numbered BMAD rules
+      const files = await fs.readdir(clineRulesDir);
+      let removed = 0;
+
+      for (const file of files) {
+        // Check if it matches our naming pattern (XX-module-name.md)
+        if (/^\d{2}-.*\.md$/.test(file)) {
+          const filePath = path.join(clineRulesDir, file);
+          const content = await fs.readFile(filePath, 'utf8');
+
+          // Verify it's a BMAD rule
+          if (content.includes('BMAD') && content.includes('Module')) {
+            await fs.remove(filePath);
+            removed++;
+          }
+        }
+      }
+
+      console.log(chalk.dim(`Removed ${removed} BMAD rules from Cline`));
+    }
+  }
+}
+
+module.exports = { ClineSetup };

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

@@ -0,0 +1,267 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+/**
+ * Codex setup handler (supports both CLI and Web)
+ * Creates comprehensive AGENTS.md file in project root
+ */
+class CodexSetup extends BaseIdeSetup {
+  constructor() {
+    super('codex', 'Codex', true); // preferred IDE
+    this.agentsFile = 'AGENTS.md';
+  }
+
+  /**
+   * Collect configuration choices before installation
+   * @param {Object} options - Configuration options
+   * @returns {Object} Collected configuration
+   */
+  async collectConfiguration(options = {}) {
+    const response = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'mode',
+        message: 'Select Codex deployment mode:',
+        choices: [
+          { name: 'CLI (Command-line interface)', value: 'cli' },
+          { name: 'Web (Browser-based interface)', value: 'web' },
+        ],
+        default: 'cli',
+      },
+    ]);
+
+    return { codexMode: response.mode };
+  }
+
+  /**
+   * Setup Codex configuration
+   * @param {string} projectDir - Project directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, bmadDir, options = {}) {
+    console.log(chalk.cyan(`Setting up ${this.name}...`));
+
+    // Use pre-collected configuration if available
+    const config = options.preCollectedConfig || {};
+    const mode = config.codexMode || options.codexMode || 'cli';
+
+    // Get agents and tasks
+    const agents = await this.getAgents(bmadDir);
+    const tasks = await this.getTasks(bmadDir);
+
+    // Create AGENTS.md content
+    const content = this.createAgentsDocument(agents, tasks, mode);
+
+    // Write AGENTS.md file
+    const agentsPath = path.join(projectDir, this.agentsFile);
+    await this.writeFile(agentsPath, content);
+
+    // Handle mode-specific setup
+    if (mode === 'web') {
+      await this.setupWebMode(projectDir);
+    } else {
+      await this.setupCliMode(projectDir);
+    }
+
+    console.log(chalk.green(`✓ ${this.name} configured:`));
+    console.log(chalk.dim(`  - Mode: ${mode === 'web' ? 'Web' : 'CLI'}`));
+    console.log(chalk.dim(`  - ${agents.length} agents documented`));
+    console.log(chalk.dim(`  - ${tasks.length} tasks documented`));
+    console.log(chalk.dim(`  - Agents file: ${this.agentsFile}`));
+
+    return {
+      success: true,
+      mode,
+      agents: agents.length,
+      tasks: tasks.length,
+    };
+  }
+
+  /**
+   * Select Codex mode (CLI or Web)
+   */
+  async selectMode() {
+    const response = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'mode',
+        message: 'Select Codex deployment mode:',
+        choices: [
+          { name: 'CLI (Command-line interface)', value: 'cli' },
+          { name: 'Web (Browser-based interface)', value: 'web' },
+        ],
+        default: 'cli',
+      },
+    ]);
+
+    return response.mode;
+  }
+
+  /**
+   * Create comprehensive agents document
+   */
+  createAgentsDocument(agents, tasks, mode) {
+    let content = `# BMAD Method - Agent Directory
+
+This document contains all available BMAD agents and tasks for use with Codex ${mode === 'web' ? 'Web' : 'CLI'}.
+
+## Quick Start
+
+${
+  mode === 'web'
+    ? `Access agents through the web interface:
+1. Navigate to the Agents section
+2. Select an agent to activate
+3. The agent persona will be active for your session`
+    : `Activate agents in CLI:
+1. Reference agents using \`@{agent-name}\`
+2. Execute tasks using \`@task-{task-name}\`
+3. Agents remain active for the conversation`
+}
+
+---
+
+## Available Agents
+
+`;
+
+    // Group agents by module
+    const agentsByModule = {};
+    for (const agent of agents) {
+      if (!agentsByModule[agent.module]) {
+        agentsByModule[agent.module] = [];
+      }
+      agentsByModule[agent.module].push(agent);
+    }
+
+    // Document each module's agents
+    for (const [module, moduleAgents] of Object.entries(agentsByModule)) {
+      content += `### ${module.toUpperCase()} Module\n\n`;
+
+      for (const agent of moduleAgents) {
+        const agentContent = this.readFileSync(agent.path);
+        const titleMatch = agentContent.match(/title="([^"]+)"/);
+        const title = titleMatch ? titleMatch[1] : this.formatTitle(agent.name);
+
+        const iconMatch = agentContent.match(/icon="([^"]+)"/);
+        const icon = iconMatch ? iconMatch[1] : '🤖';
+
+        const whenToUseMatch = agentContent.match(/whenToUse="([^"]+)"/);
+        const whenToUse = whenToUseMatch ? whenToUseMatch[1] : `Use for ${title} tasks`;
+
+        content += `#### ${icon} ${title} (\`@${agent.name}\`)\n\n`;
+        content += `**When to use:** ${whenToUse}\n\n`;
+        content += `**Activation:** Type \`@${agent.name}\` to activate this agent.\n\n`;
+      }
+    }
+
+    content += `---
+
+## Available Tasks
+
+`;
+
+    // Group tasks by module
+    const tasksByModule = {};
+    for (const task of tasks) {
+      if (!tasksByModule[task.module]) {
+        tasksByModule[task.module] = [];
+      }
+      tasksByModule[task.module].push(task);
+    }
+
+    // Document each module's tasks
+    for (const [module, moduleTasks] of Object.entries(tasksByModule)) {
+      content += `### ${module.toUpperCase()} Module Tasks\n\n`;
+
+      for (const task of moduleTasks) {
+        const taskContent = this.readFileSync(task.path);
+        const nameMatch = taskContent.match(/<name>([^<]+)<\/name>/);
+        const taskName = nameMatch ? nameMatch[1] : this.formatTitle(task.name);
+
+        content += `- **${taskName}** (\`@task-${task.name}\`)\n`;
+      }
+      content += '\n';
+    }
+
+    content += `---
+
+## Usage Guidelines
+
+1. **One agent at a time**: Activate a single agent for focused assistance
+2. **Task execution**: Tasks are one-time workflows, not persistent personas
+3. **Module organization**: Agents and tasks are grouped by their source module
+4. **Context preservation**: ${mode === 'web' ? 'Sessions maintain agent context' : 'Conversations maintain agent context'}
+
+---
+
+*Generated by BMAD Method installer for Codex ${mode === 'web' ? 'Web' : 'CLI'}*
+`;
+
+    return content;
+  }
+
+  /**
+   * Read file synchronously (for document generation)
+   */
+  readFileSync(filePath) {
+    const fs = require('node:fs');
+    try {
+      return fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Setup for CLI mode
+   */
+  async setupCliMode(projectDir) {
+    // CLI mode - ensure .gitignore includes AGENTS.md if needed
+    const fs = require('fs-extra');
+    const gitignorePath = path.join(projectDir, '.gitignore');
+
+    if (await fs.pathExists(gitignorePath)) {
+      const gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
+      if (!gitignoreContent.includes('AGENTS.md')) {
+        // User can decide whether to track this file
+        console.log(chalk.dim('  Note: Consider adding AGENTS.md to .gitignore if desired'));
+      }
+    }
+  }
+
+  /**
+   * Setup for Web mode
+   */
+  async setupWebMode(projectDir) {
+    // Web mode - add to .gitignore to avoid committing
+    const fs = require('fs-extra');
+    const gitignorePath = path.join(projectDir, '.gitignore');
+
+    if (await fs.pathExists(gitignorePath)) {
+      const gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
+      if (!gitignoreContent.includes('AGENTS.md')) {
+        await fs.appendFile(gitignorePath, '\n# Codex Web agents file\nAGENTS.md\n');
+        console.log(chalk.dim('  Added AGENTS.md to .gitignore for web deployment'));
+      }
+    }
+  }
+
+  /**
+   * Cleanup Codex configuration
+   */
+  async cleanup(projectDir) {
+    const fs = require('fs-extra');
+    const agentsPath = path.join(projectDir, this.agentsFile);
+
+    if (await fs.pathExists(agentsPath)) {
+      await fs.remove(agentsPath);
+      console.log(chalk.dim('Removed AGENTS.md file'));
+    }
+  }
+}
+
+module.exports = { CodexSetup };