bmad-method 6.0.0-alpha.9 → 6.0.2

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

@@ -1,87 +1,27 @@
 const path = require('node:path');
 const { BaseIdeSetup } = require('./_base-ide');
-const chalk = require('chalk');
-const inquirer = require('inquirer');
+const prompts = require('../../../lib/prompts');
 const { AgentCommandGenerator } = require('./shared/agent-command-generator');
+const { BMAD_FOLDER_NAME, toDashPath } = require('./shared/path-utils');
+const fs = require('fs-extra');
+const csv = require('csv-parse/sync');
+const yaml = require('yaml');
 
 /**
  * GitHub Copilot setup handler
- * Creates chat modes in .github/chatmodes/ and configures VS Code settings
+ * Creates agents in .github/agents/, prompts in .github/prompts/,
+ * copilot-instructions.md, and configures VS Code settings
  */
 class GitHubCopilotSetup extends BaseIdeSetup {
   constructor() {
-    super('github-copilot', 'GitHub Copilot', true); // preferred IDE
-    this.configDir = '.github';
-    this.chatmodesDir = 'chatmodes';
-    this.vscodeDir = '.vscode';
-  }
-
-  /**
-   * Collect configuration choices before installation
-   * @param {Object} options - Configuration options
-   * @returns {Object} Collected configuration
-   */
-  async collectConfiguration(options = {}) {
-    const config = {};
-
-    console.log('\n' + chalk.blue('  🔧 VS Code Settings Configuration'));
-    console.log(chalk.dim('  GitHub Copilot works best with specific settings\n'));
-
-    const response = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'configChoice',
-        message: 'How would you like to configure VS Code settings?',
-        choices: [
-          { name: 'Use recommended defaults (fastest)', value: 'defaults' },
-          { name: 'Configure each setting manually', value: 'manual' },
-          { name: 'Skip settings configuration', value: 'skip' },
-        ],
-        default: 'defaults',
-      },
-    ]);
-    config.vsCodeConfig = response.configChoice;
-
-    if (response.configChoice === 'manual') {
-      config.manualSettings = await inquirer.prompt([
-        {
-          type: 'input',
-          name: 'maxRequests',
-          message: 'Maximum requests per session (1-50)?',
-          default: '15',
-          validate: (input) => {
-            const num = parseInt(input);
-            return (num >= 1 && num <= 50) || 'Enter 1-50';
-          },
-        },
-        {
-          type: 'confirm',
-          name: 'runTasks',
-          message: 'Allow running workspace tasks?',
-          default: true,
-        },
-        {
-          type: 'confirm',
-          name: 'mcpDiscovery',
-          message: 'Enable MCP server discovery?',
-          default: true,
-        },
-        {
-          type: 'confirm',
-          name: 'autoFix',
-          message: 'Enable automatic error fixing?',
-          default: true,
-        },
-        {
-          type: 'confirm',
-          name: 'autoApprove',
-          message: 'Auto-approve tools (less secure)?',
-          default: false,
-        },
-      ]);
-    }
-
-    return config;
+    super('github-copilot', 'GitHub Copilot', false);
+    // Don't set configDir to '.github' — nearly every GitHub repo has that directory,
+    // which would cause the base detect() to false-positive. Use detectionPaths instead.
+    this.configDir = null;
+    this.githubDir = '.github';
+    this.agentsDir = 'agents';
+    this.promptsDir = 'prompts';
+    this.detectionPaths = ['.github/copilot-instructions.md', '.github/agents'];
   }
 
   /**
@@ -91,176 +31,557 @@ class GitHubCopilotSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, bmadDir, options = {}) {
-    console.log(chalk.cyan(`Setting up ${this.name}...`));
+    if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`);
 
-    // Configure VS Code settings using pre-collected config if available
-    const config = options.preCollectedConfig || {};
-    await this.configureVsCodeSettings(projectDir, { ...options, ...config });
+    // Create .github/agents and .github/prompts directories
+    const githubDir = path.join(projectDir, this.githubDir);
+    const agentsDir = path.join(githubDir, this.agentsDir);
+    const promptsDir = path.join(githubDir, this.promptsDir);
+    await this.ensureDir(agentsDir);
+    await this.ensureDir(promptsDir);
 
-    // Create .github/chatmodes directory
-    const githubDir = path.join(projectDir, this.configDir);
-    const chatmodesDir = path.join(githubDir, this.chatmodesDir);
-    await this.ensureDir(chatmodesDir);
+    // Preserve any customised tool permissions from existing files before cleanup
+    this.existingToolPermissions = await this.collectExistingToolPermissions(projectDir);
 
     // Clean up any existing BMAD files before reinstalling
     await this.cleanup(projectDir);
 
+    // Load agent manifest for enriched descriptions
+    const agentManifest = await this.loadAgentManifest(bmadDir);
+
     // Generate agent launchers
     const agentGen = new AgentCommandGenerator(this.bmadFolderName);
     const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []);
 
-    // Create chat mode files with bmad- prefix
-    let modeCount = 0;
+    // Create agent .agent.md files
+    let agentCount = 0;
     for (const artifact of agentArtifacts) {
-      const content = artifact.content;
-      const chatmodeContent = await this.createChatmodeContent({ module: artifact.module, name: artifact.name }, content);
+      const agentMeta = agentManifest.get(artifact.name);
+
+      // Compute fileName first so we can look up any existing tool permissions
+      const dashName = toDashPath(artifact.relativePath);
+      const fileName = dashName.replace(/\.md$/, '.agent.md');
+      const toolsStr = this.getToolsForFile(fileName);
+      const agentContent = this.createAgentContent(artifact, agentMeta, toolsStr);
+      const targetPath = path.join(agentsDir, fileName);
+      await this.writeFile(targetPath, agentContent);
+      agentCount++;
+    }
 
-      // Use bmad- prefix: bmad-agent-{module}-{name}.chatmode.md
-      const targetPath = path.join(chatmodesDir, `bmad-agent-${artifact.module}-${artifact.name}.chatmode.md`);
-      await this.writeFile(targetPath, chatmodeContent);
-      modeCount++;
+    // Generate prompt files from bmad-help.csv
+    const promptCount = await this.generatePromptFiles(projectDir, bmadDir, agentArtifacts, agentManifest);
 
-      console.log(chalk.green(`  ✓ Created chat mode: bmad-agent-${artifact.module}-${artifact.name}`));
-    }
+    // Generate copilot-instructions.md
+    await this.generateCopilotInstructions(projectDir, bmadDir, agentManifest, options);
 
-    console.log(chalk.green(`✓ ${this.name} configured:`));
-    console.log(chalk.dim(`  - ${modeCount} chat modes created`));
-    console.log(chalk.dim(`  - Chat modes directory: ${path.relative(projectDir, chatmodesDir)}`));
-    console.log(chalk.dim(`  - VS Code settings configured`));
-    console.log(chalk.dim('\n  Chat modes available in VS Code Chat view'));
+    if (!options.silent) await prompts.log.success(`${this.name} configured: ${agentCount} agents, ${promptCount} prompts → .github/`);
 
     return {
       success: true,
-      chatmodes: modeCount,
-      settings: true,
+      results: {
+        agents: agentCount,
+        workflows: promptCount,
+        tasks: 0,
+        tools: 0,
+      },
     };
   }
 
   /**
-   * Configure VS Code settings for GitHub Copilot
+   * Load agent manifest CSV into a Map keyed by agent name
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {Map} Agent metadata keyed by name
    */
-  async configureVsCodeSettings(projectDir, options) {
-    const fs = require('fs-extra');
-    const vscodeDir = path.join(projectDir, this.vscodeDir);
-    const settingsPath = path.join(vscodeDir, 'settings.json');
-
-    await this.ensureDir(vscodeDir);
-
-    // Read existing settings
-    let existingSettings = {};
-    if (await fs.pathExists(settingsPath)) {
-      try {
-        const content = await fs.readFile(settingsPath, 'utf8');
-        existingSettings = JSON.parse(content);
-        console.log(chalk.yellow('  Found existing .vscode/settings.json'));
-      } catch {
-        console.warn(chalk.yellow('  Could not parse settings.json, creating new'));
+  async loadAgentManifest(bmadDir) {
+    const manifestPath = path.join(bmadDir, '_config', 'agent-manifest.csv');
+    const agents = new Map();
+
+    if (!(await fs.pathExists(manifestPath))) {
+      return agents;
+    }
+
+    try {
+      const csvContent = await fs.readFile(manifestPath, 'utf8');
+      const records = csv.parse(csvContent, {
+        columns: true,
+        skip_empty_lines: true,
+      });
+
+      for (const record of records) {
+        agents.set(record.name, record);
       }
+    } catch {
+      // Gracefully degrade if manifest is unreadable/malformed
     }
 
-    // Use pre-collected configuration or skip if not available
-    let configChoice = options.vsCodeConfig;
-    if (!configChoice) {
-      // If no pre-collected config, skip configuration
-      console.log(chalk.yellow('  ⚠ No configuration collected, skipping VS Code settings'));
-      return;
+    return agents;
+  }
+
+  /**
+   * Load bmad-help.csv to drive prompt generation
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {Array|null} Parsed CSV rows
+   */
+  async loadBmadHelp(bmadDir) {
+    const helpPath = path.join(bmadDir, '_config', 'bmad-help.csv');
+
+    if (!(await fs.pathExists(helpPath))) {
+      return null;
     }
 
-    if (configChoice === 'skip') {
-      console.log(chalk.yellow('  ⚠ Skipping VS Code settings'));
-      return;
+    try {
+      const csvContent = await fs.readFile(helpPath, 'utf8');
+      return csv.parse(csvContent, {
+        columns: true,
+        skip_empty_lines: true,
+      });
+    } catch {
+      // Gracefully degrade if help CSV is unreadable/malformed
+      return null;
     }
+  }
 
-    let bmadSettings = {};
-
-    if (configChoice === 'defaults') {
-      bmadSettings = {
-        'chat.agent.enabled': true,
-        'chat.agent.maxRequests': 15,
-        'github.copilot.chat.agent.runTasks': true,
-        'chat.mcp.discovery.enabled': true,
-        'github.copilot.chat.agent.autoFix': true,
-        'chat.tools.autoApprove': false,
-      };
-      console.log(chalk.green('  ✓ Using recommended defaults'));
+  /**
+   * Create agent .agent.md content with enriched description
+   * @param {Object} artifact - Agent artifact from AgentCommandGenerator
+   * @param {Object|undefined} manifestEntry - Agent manifest entry with metadata
+   * @returns {string} Agent file content
+   */
+  createAgentContent(artifact, manifestEntry, toolsStr) {
+    // Build enriched description from manifest metadata
+    let description;
+    if (manifestEntry) {
+      const persona = manifestEntry.displayName || artifact.name;
+      const title = manifestEntry.title || this.formatTitle(artifact.name);
+      const capabilities = manifestEntry.capabilities || 'agent capabilities';
+      description = `${persona} — ${title}: ${capabilities}`;
     } else {
-      // Manual configuration - use pre-collected settings
-      const manual = options.manualSettings || {};
-
-      bmadSettings = {
-        'chat.agent.enabled': true,
-        'chat.agent.maxRequests': parseInt(manual.maxRequests || 15),
-        'github.copilot.chat.agent.runTasks': manual.runTasks === undefined ? true : manual.runTasks,
-        'chat.mcp.discovery.enabled': manual.mcpDiscovery === undefined ? true : manual.mcpDiscovery,
-        'github.copilot.chat.agent.autoFix': manual.autoFix === undefined ? true : manual.autoFix,
-        'chat.tools.autoApprove': manual.autoApprove || false,
-      };
+      description = `Activates the ${this.formatTitle(artifact.name)} agent persona.`;
+    }
+
+    // Build the agent file path for the activation block
+    const agentPath = artifact.agentPath || artifact.relativePath;
+    const agentFilePath = `{project-root}/${this.bmadFolderName}/${agentPath}`;
+
+    return `---
+description: '${description.replaceAll("'", "''")}'
+tools: ${toolsStr}
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from ${agentFilePath}
+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>
+`;
+  }
+
+  /**
+   * Generate .prompt.md files for workflows, tasks, tech-writer commands, and agent activators
+   * @param {string} projectDir - Project directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Array} agentArtifacts - Agent artifacts for activator generation
+   * @param {Map} agentManifest - Agent manifest data
+   * @returns {number} Count of prompts generated
+   */
+  async generatePromptFiles(projectDir, bmadDir, agentArtifacts, agentManifest) {
+    const promptsDir = path.join(projectDir, this.githubDir, this.promptsDir);
+    let promptCount = 0;
+
+    // Load bmad-help.csv to drive workflow/task prompt generation
+    const helpEntries = await this.loadBmadHelp(bmadDir);
+
+    if (helpEntries) {
+      for (const entry of helpEntries) {
+        const command = entry.command;
+        if (!command) continue; // Skip entries without a command (tech-writer commands have no command column)
+
+        const workflowFile = entry['workflow-file'];
+        if (!workflowFile) continue; // Skip entries with no workflow file path
+        const promptFileName = `${command}.prompt.md`;
+        const toolsStr = this.getToolsForFile(promptFileName);
+        const promptContent = this.createWorkflowPromptContent(entry, workflowFile, toolsStr);
+        const promptPath = path.join(promptsDir, promptFileName);
+        await this.writeFile(promptPath, promptContent);
+        promptCount++;
+      }
+
+      // Generate tech-writer command prompts (entries with no command column)
+      for (const entry of helpEntries) {
+        if (entry.command) continue; // Already handled above
+        const techWriterPrompt = this.createTechWriterPromptContent(entry);
+        if (techWriterPrompt) {
+          const promptFileName = `${techWriterPrompt.fileName}.prompt.md`;
+          const promptPath = path.join(promptsDir, promptFileName);
+          await this.writeFile(promptPath, techWriterPrompt.content);
+          promptCount++;
+        }
+      }
     }
 
-    // Merge settings (existing take precedence)
-    const mergedSettings = { ...bmadSettings, ...existingSettings };
+    // Generate agent activator prompts (Pattern D)
+    for (const artifact of agentArtifacts) {
+      const agentMeta = agentManifest.get(artifact.name);
+      const fileName = `bmad-${artifact.name}.prompt.md`;
+      const toolsStr = this.getToolsForFile(fileName);
+      const promptContent = this.createAgentActivatorPromptContent(artifact, agentMeta, toolsStr);
+      const promptPath = path.join(promptsDir, fileName);
+      await this.writeFile(promptPath, promptContent);
+      promptCount++;
+    }
 
-    // Write settings
-    await fs.writeFile(settingsPath, JSON.stringify(mergedSettings, null, 2));
-    console.log(chalk.green('  ✓ VS Code settings configured'));
+    return promptCount;
   }
 
   /**
-   * Create chat mode content
+   * Create prompt content for a workflow/task entry from bmad-help.csv
+   * Determines the pattern (A, B, or A for .xml tasks) based on file extension
+   * @param {Object} entry - bmad-help.csv row
+   * @param {string} workflowFile - Workflow file path
+   * @returns {string} Prompt file content
    */
-  async createChatmodeContent(agent, content) {
-    // Extract metadata from launcher frontmatter if present
-    const descMatch = content.match(/description:\s*"([^"]+)"/);
-    const title = descMatch ? descMatch[1] : this.formatTitle(agent.name);
-
-    const description = `Activates the ${title} agent persona.`;
-
-    // Strip any existing frontmatter from the content
-    const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
-    let cleanContent = content;
-    if (frontmatterRegex.test(content)) {
-      cleanContent = content.replace(frontmatterRegex, '').trim();
+  createWorkflowPromptContent(entry, workflowFile, toolsStr) {
+    const description = this.escapeYamlSingleQuote(this.createPromptDescription(entry.name));
+    // bmm/config.yaml is safe to hardcode here: these prompts are only generated when
+    // bmad-help.csv exists (bmm module data), so bmm is guaranteed to be installed.
+    const configLine = `1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables`;
+
+    let body;
+    if (workflowFile.endsWith('.yaml')) {
+      // Pattern B: YAML-based workflows — use workflow engine
+      body = `${configLine}
+2. Load the workflow engine at {project-root}/${this.bmadFolderName}/core/tasks/workflow.xml
+3. Load and execute the workflow configuration at {project-root}/${workflowFile} using the engine from step 2`;
+    } else if (workflowFile.endsWith('.xml')) {
+      // Pattern A variant: XML tasks — load and execute directly
+      body = `${configLine}
+2. Load and execute the task at {project-root}/${workflowFile}`;
+    } else {
+      // Pattern A: MD workflows — load and follow directly
+      body = `${configLine}
+2. Load and follow the workflow at {project-root}/${workflowFile}`;
     }
 
-    // Available GitHub Copilot tools (November 2025 - Official VS Code Documentation)
-    // Reference: https://code.visualstudio.com/docs/copilot/reference/copilot-vscode-features#_chat-tools
-    const tools = [
-      'changes', // List of source control changes
-      'codebase', // Perform code search in workspace
-      'createDirectory', // Create new directory in workspace
-      'createFile', // Create new file in workspace
-      'editFiles', // Apply edits to files in workspace
-      'fetch', // Fetch content from web page
-      'fileSearch', // Search files using glob patterns
-      'githubRepo', // Perform code search in GitHub repo
-      'listDirectory', // List files in a directory
-      'problems', // Add workspace issues from Problems panel
-      'readFile', // Read content of a file in workspace
-      'runInTerminal', // Run shell command in integrated terminal
-      'runTask', // Run existing task in workspace
-      'runTests', // Run unit tests in workspace
-      'runVscodeCommand', // Run VS Code command
-      'search', // Enable file searching in workspace
-      'searchResults', // Get search results from Search view
-      'terminalLastCommand', // Get last terminal command and output
-      'terminalSelection', // Get current terminal selection
-      'testFailure', // Get unit test failure information
-      'textSearch', // Find text in files
-      'usages', // Find references and navigate definitions
-    ];
+    return `---
+description: '${description}'
+agent: 'agent'
+tools: ${toolsStr}
+---
+
+${body}
+`;
+  }
+
+  /**
+   * Create a short 2-5 word description for a prompt from the entry name
+   * @param {string} name - Entry name from bmad-help.csv
+   * @returns {string} Short description
+   */
+  createPromptDescription(name) {
+    const descriptionMap = {
+      'Brainstorm Project': 'Brainstorm ideas',
+      'Market Research': 'Market research',
+      'Domain Research': 'Domain research',
+      'Technical Research': 'Technical research',
+      'Create Brief': 'Create product brief',
+      'Create PRD': 'Create PRD',
+      'Validate PRD': 'Validate PRD',
+      'Edit PRD': 'Edit PRD',
+      'Create UX': 'Create UX design',
+      'Create Architecture': 'Create architecture',
+      'Create Epics and Stories': 'Create epics and stories',
+      'Check Implementation Readiness': 'Check implementation readiness',
+      'Sprint Planning': 'Sprint planning',
+      'Sprint Status': 'Sprint status',
+      'Create Story': 'Create story',
+      'Validate Story': 'Validate story',
+      'Dev Story': 'Dev story',
+      'QA Automation Test': 'QA automation',
+      'Code Review': 'Code review',
+      Retrospective: 'Retrospective',
+      'Document Project': 'Document project',
+      'Generate Project Context': 'Generate project context',
+      'Quick Spec': 'Quick spec',
+      'Quick Dev': 'Quick dev',
+      'Correct Course': 'Correct course',
+      Brainstorming: 'Brainstorm ideas',
+      'Party Mode': 'Party mode',
+      'bmad-help': 'BMAD help',
+      'Index Docs': 'Index documents',
+      'Shard Document': 'Shard document',
+      'Editorial Review - Prose': 'Editorial review prose',
+      'Editorial Review - Structure': 'Editorial review structure',
+      'Adversarial Review (General)': 'Adversarial review',
+    };
 
-    let chatmodeContent = `---
-description: "${description.replaceAll('"', String.raw`\"`)}"
-tools: ${JSON.stringify(tools)}
+    return descriptionMap[name] || name;
+  }
+
+  /**
+   * Create prompt content for tech-writer agent-only commands (Pattern C)
+   * @param {Object} entry - bmad-help.csv row
+   * @returns {Object|null} { fileName, content } or null if not a tech-writer command
+   */
+  createTechWriterPromptContent(entry) {
+    if (entry['agent-name'] !== 'tech-writer') return null;
+
+    const techWriterCommands = {
+      'Write Document': { code: 'WD', file: 'bmad-bmm-write-document', description: 'Write document' },
+      'Update Standards': { code: 'US', file: 'bmad-bmm-update-standards', description: 'Update standards' },
+      'Mermaid Generate': { code: 'MG', file: 'bmad-bmm-mermaid-generate', description: 'Mermaid generate' },
+      'Validate Document': { code: 'VD', file: 'bmad-bmm-validate-document', description: 'Validate document' },
+      'Explain Concept': { code: 'EC', file: 'bmad-bmm-explain-concept', description: 'Explain concept' },
+    };
+
+    const cmd = techWriterCommands[entry.name];
+    if (!cmd) return null;
+
+    const safeDescription = this.escapeYamlSingleQuote(cmd.description);
+    const toolsStr = this.getToolsForFile(`${cmd.file}.prompt.md`);
+
+    const content = `---
+description: '${safeDescription}'
+agent: 'agent'
+tools: ${toolsStr}
 ---
 
-# ${title} Agent
+1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables
+2. Load the full agent file from {project-root}/${this.bmadFolderName}/bmm/agents/tech-writer/tech-writer.md and activate the Paige (Technical Writer) persona
+3. Execute the ${entry.name} menu command (${cmd.code})
+`;
+
+    return { fileName: cmd.file, content };
+  }
 
-${cleanContent}
+  /**
+   * Create agent activator prompt content (Pattern D)
+   * @param {Object} artifact - Agent artifact
+   * @param {Object|undefined} manifestEntry - Agent manifest entry
+   * @returns {string} Prompt file content
+   */
+  createAgentActivatorPromptContent(artifact, manifestEntry, toolsStr) {
+    let description;
+    if (manifestEntry) {
+      description = manifestEntry.title || this.formatTitle(artifact.name);
+    } else {
+      description = this.formatTitle(artifact.name);
+    }
+
+    const safeDescription = this.escapeYamlSingleQuote(description);
+    const agentPath = artifact.agentPath || artifact.relativePath;
+    const agentFilePath = `{project-root}/${this.bmadFolderName}/${agentPath}`;
+
+    // bmm/config.yaml is safe to hardcode: agent activators are only generated from
+    // bmm agent artifacts, so bmm is guaranteed to be installed.
+    return `---
+description: '${safeDescription}'
+agent: 'agent'
+tools: ${toolsStr}
+---
 
+1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables
+2. Load the full agent file from ${agentFilePath}
+3. Follow ALL activation instructions in the agent file
+4. Display the welcome/greeting as instructed
+5. Present the numbered menu
+6. Wait for user input before proceeding
 `;
+  }
+
+  /**
+   * Generate copilot-instructions.md from module config
+   * @param {string} projectDir - Project directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Map} agentManifest - Agent manifest data
+   */
+  async generateCopilotInstructions(projectDir, bmadDir, agentManifest, options = {}) {
+    const configVars = await this.loadModuleConfig(bmadDir);
+
+    // Build the agents table from the manifest
+    let agentsTable = '| Agent | Persona | Title | Capabilities |\n|---|---|---|---|\n';
+    const agentOrder = [
+      'bmad-master',
+      'analyst',
+      'architect',
+      'dev',
+      'pm',
+      'qa',
+      'quick-flow-solo-dev',
+      'sm',
+      'tech-writer',
+      'ux-designer',
+    ];
+
+    for (const agentName of agentOrder) {
+      const meta = agentManifest.get(agentName);
+      if (meta) {
+        const capabilities = meta.capabilities || 'agent capabilities';
+        const cleanTitle = (meta.title || '').replaceAll('""', '"');
+        agentsTable += `| ${agentName} | ${meta.displayName} | ${cleanTitle} | ${capabilities} |\n`;
+      }
+    }
+
+    const bmad = this.bmadFolderName;
+    const bmadSection = `# BMAD Method — Project Instructions
+
+## Project Configuration
+
+- **Project**: ${configVars.project_name || '{{project_name}}'}
+- **User**: ${configVars.user_name || '{{user_name}}'}
+- **Communication Language**: ${configVars.communication_language || '{{communication_language}}'}
+- **Document Output Language**: ${configVars.document_output_language || '{{document_output_language}}'}
+- **User Skill Level**: ${configVars.user_skill_level || '{{user_skill_level}}'}
+- **Output Folder**: ${configVars.output_folder || '{{output_folder}}'}
+- **Planning Artifacts**: ${configVars.planning_artifacts || '{{planning_artifacts}}'}
+- **Implementation Artifacts**: ${configVars.implementation_artifacts || '{{implementation_artifacts}}'}
+- **Project Knowledge**: ${configVars.project_knowledge || '{{project_knowledge}}'}
+
+## BMAD Runtime Structure
+
+- **Agent definitions**: \`${bmad}/bmm/agents/\` (BMM module) and \`${bmad}/core/agents/\` (core)
+- **Workflow definitions**: \`${bmad}/bmm/workflows/\` (organized by phase)
+- **Core tasks**: \`${bmad}/core/tasks/\` (help, editorial review, indexing, sharding, adversarial review)
+- **Core workflows**: \`${bmad}/core/workflows/\` (brainstorming, party-mode, advanced-elicitation)
+- **Workflow engine**: \`${bmad}/core/tasks/workflow.xml\` (executes YAML-based workflows)
+- **Module configuration**: \`${bmad}/bmm/config.yaml\`
+- **Core configuration**: \`${bmad}/core/config.yaml\`
+- **Agent manifest**: \`${bmad}/_config/agent-manifest.csv\`
+- **Workflow manifest**: \`${bmad}/_config/workflow-manifest.csv\`
+- **Help manifest**: \`${bmad}/_config/bmad-help.csv\`
+- **Agent memory**: \`${bmad}/_memory/\`
+
+## Key Conventions
+
+- Always load \`${bmad}/bmm/config.yaml\` before any agent activation or workflow execution
+- Store all config fields as session variables: \`{user_name}\`, \`{communication_language}\`, \`{output_folder}\`, \`{planning_artifacts}\`, \`{implementation_artifacts}\`, \`{project_knowledge}\`
+- MD-based workflows execute directly — load and follow the \`.md\` file
+- YAML-based workflows require the workflow engine — load \`workflow.xml\` first, then pass the \`.yaml\` config
+- Follow step-based workflow execution: load steps JIT, never multiple at once
+- Save outputs after EACH step when using the workflow engine
+- The \`{project-root}\` variable resolves to the workspace root at runtime
+
+## Available Agents
+
+${agentsTable}
+## Slash Commands
+
+Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent activators. Agents are also available in the agents dropdown.`;
+
+    const instructionsPath = path.join(projectDir, this.githubDir, 'copilot-instructions.md');
+    const markerStart = '<!-- BMAD:START -->';
+    const markerEnd = '<!-- BMAD:END -->';
+    const markedContent = `${markerStart}\n${bmadSection}\n${markerEnd}`;
+
+    if (await fs.pathExists(instructionsPath)) {
+      const existing = await fs.readFile(instructionsPath, 'utf8');
+      const startIdx = existing.indexOf(markerStart);
+      const endIdx = existing.indexOf(markerEnd);
+
+      if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace only the BMAD section between markers
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + markerEnd.length);
+        const merged = `${before}${markedContent}${after}`;
+        await this.writeFile(instructionsPath, merged);
+      } else {
+        // Existing file without markers — back it up before overwriting
+        const backupPath = `${instructionsPath}.bak`;
+        await fs.copy(instructionsPath, backupPath);
+        if (!options.silent) await prompts.log.warn(`  Backed up copilot-instructions.md → .bak`);
+        await this.writeFile(instructionsPath, `${markedContent}\n`);
+      }
+    } else {
+      // No existing file — create fresh with markers
+      await this.writeFile(instructionsPath, `${markedContent}\n`);
+    }
+  }
+
+  /**
+   * Load module config.yaml for template variables
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {Object} Config variables
+   */
+  async loadModuleConfig(bmadDir) {
+    const bmmConfigPath = path.join(bmadDir, 'bmm', 'config.yaml');
+    const coreConfigPath = path.join(bmadDir, 'core', 'config.yaml');
+
+    for (const configPath of [bmmConfigPath, coreConfigPath]) {
+      if (await fs.pathExists(configPath)) {
+        try {
+          const content = await fs.readFile(configPath, 'utf8');
+          return yaml.parse(content) || {};
+        } catch {
+          // Fall through to next config
+        }
+      }
+    }
+
+    return {};
+  }
+
+  /**
+   * Escape a string for use inside YAML single-quoted values.
+   * In YAML, the only escape inside single quotes is '' for a literal '.
+   * @param {string} value - Raw string
+   * @returns {string} Escaped string safe for YAML single-quoted context
+   */
+  escapeYamlSingleQuote(value) {
+    return (value || '').replaceAll("'", "''");
+  }
+
+  /**
+   * Scan existing agent and prompt files for customised tool permissions before cleanup.
+   * Returns a Map<filename, toolsArray> so permissions can be preserved across reinstalls.
+   * @param {string} projectDir - Project directory
+   * @returns {Map} Existing tool permissions keyed by filename
+   */
+  async collectExistingToolPermissions(projectDir) {
+    const permissions = new Map();
+    const dirs = [
+      [path.join(projectDir, this.githubDir, this.agentsDir), /^bmad.*\.agent\.md$/],
+      [path.join(projectDir, this.githubDir, this.promptsDir), /^bmad-.*\.prompt\.md$/],
+    ];
+
+    for (const [dir, pattern] of dirs) {
+      if (!(await fs.pathExists(dir))) continue;
+      const files = await fs.readdir(dir);
+
+      for (const file of files) {
+        if (!pattern.test(file)) continue;
+
+        try {
+          const content = await fs.readFile(path.join(dir, file), 'utf8');
+          const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+          if (!fmMatch) continue;
+
+          const frontmatter = yaml.parse(fmMatch[1]);
+          if (frontmatter && Array.isArray(frontmatter.tools)) {
+            permissions.set(file, frontmatter.tools);
+          }
+        } catch {
+          // Skip unreadable files
+        }
+      }
+    }
 
-    return chatmodeContent;
+    return permissions;
+  }
+
+  /**
+   * Get the tools array string for a file, preserving any existing customisation.
+   * Falls back to the default tools if no prior customisation exists.
+   * @param {string} fileName - Target filename (e.g. 'bmad-agent-bmm-pm.agent.md')
+   * @returns {string} YAML inline array string
+   */
+  getToolsForFile(fileName) {
+    const defaultTools = ['read', 'edit', 'search', 'execute'];
+    const tools = (this.existingToolPermissions && this.existingToolPermissions.get(fileName)) || defaultTools;
+    return '[' + tools.map((t) => `'${t}'`).join(', ') + ']';
   }
 
   /**
@@ -276,24 +597,100 @@ ${cleanContent}
   /**
    * Cleanup GitHub Copilot configuration - surgically remove only BMAD files
    */
-  async cleanup(projectDir) {
-    const fs = require('fs-extra');
-    const chatmodesDir = path.join(projectDir, this.configDir, this.chatmodesDir);
+  async cleanup(projectDir, options = {}) {
+    // Clean up agents directory
+    const agentsDir = path.join(projectDir, this.githubDir, this.agentsDir);
+    if (await fs.pathExists(agentsDir)) {
+      const files = await fs.readdir(agentsDir);
+      let removed = 0;
 
-    if (await fs.pathExists(chatmodesDir)) {
-      // Only remove files that start with bmad- prefix
-      const files = await fs.readdir(chatmodesDir);
+      for (const file of files) {
+        if (file.startsWith('bmad') && (file.endsWith('.agent.md') || file.endsWith('.md'))) {
+          await fs.remove(path.join(agentsDir, file));
+          removed++;
+        }
+      }
+
+      if (removed > 0 && !options.silent) {
+        await prompts.log.message(`  Cleaned up ${removed} existing BMAD agents`);
+      }
+    }
+
+    // Clean up prompts directory
+    const promptsDir = path.join(projectDir, this.githubDir, this.promptsDir);
+    if (await fs.pathExists(promptsDir)) {
+      const files = await fs.readdir(promptsDir);
       let removed = 0;
 
       for (const file of files) {
-        if (file.startsWith('bmad-') && file.endsWith('.chatmode.md')) {
-          await fs.remove(path.join(chatmodesDir, file));
+        if (file.startsWith('bmad-') && file.endsWith('.prompt.md')) {
+          await fs.remove(path.join(promptsDir, file));
           removed++;
         }
       }
 
-      if (removed > 0) {
-        console.log(chalk.dim(`  Cleaned up ${removed} existing BMAD chat modes`));
+      if (removed > 0 && !options.silent) {
+        await prompts.log.message(`  Cleaned up ${removed} existing BMAD prompts`);
+      }
+    }
+
+    // During uninstall, also strip BMAD markers from copilot-instructions.md.
+    // During reinstall (default), this is skipped because generateCopilotInstructions()
+    // handles marker-based replacement in a single read-modify-write pass,
+    // which correctly preserves user content outside the markers.
+    if (options.isUninstall) {
+      await this.cleanupCopilotInstructions(projectDir, options);
+    }
+  }
+
+  /**
+   * Strip BMAD marker section from copilot-instructions.md
+   * If file becomes empty after stripping, delete it.
+   * If a .bak backup exists and the main file was deleted, restore the backup.
+   * @param {string} projectDir - Project directory
+   * @param {Object} [options] - Options (e.g. { silent: true })
+   */
+  async cleanupCopilotInstructions(projectDir, options = {}) {
+    const instructionsPath = path.join(projectDir, this.githubDir, 'copilot-instructions.md');
+    const backupPath = `${instructionsPath}.bak`;
+
+    if (!(await fs.pathExists(instructionsPath))) {
+      return;
+    }
+
+    const content = await fs.readFile(instructionsPath, 'utf8');
+    const markerStart = '<!-- BMAD:START -->';
+    const markerEnd = '<!-- BMAD:END -->';
+    const startIdx = content.indexOf(markerStart);
+    const endIdx = content.indexOf(markerEnd);
+
+    if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+      return; // No valid markers found
+    }
+
+    // Strip the marker section (including markers)
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + markerEnd.length);
+    const cleaned = before + after;
+
+    if (cleaned.trim().length === 0) {
+      // File is empty after stripping — delete it
+      await fs.remove(instructionsPath);
+
+      // If backup exists, restore it
+      if (await fs.pathExists(backupPath)) {
+        await fs.rename(backupPath, instructionsPath);
+        if (!options.silent) {
+          await prompts.log.message('  Restored copilot-instructions.md from backup');
+        }
+      }
+    } else {
+      // Write cleaned content back (preserve original whitespace)
+      await fs.writeFile(instructionsPath, cleaned, 'utf8');
+
+      // If backup exists, it's stale now — remove it
+      if (await fs.pathExists(backupPath)) {
+        await fs.remove(backupPath);
       }
     }
   }