@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/services/agents/claude-agent-runner.js

@@ -155,22 +155,43 @@ export class ClaudeAgentRunner {
             tempDir = await mkdtemp(join(tmpdir(), 'claude-prompt-'));
             tempFile = join(tempDir, 'prompt.txt');
             await writeFile(tempFile, prompt, 'utf8');
+            // Write system prompt to temp file if provided (Claude-only feature)
+            // Uses --system-prompt (full replacement) instead of --append-system-prompt
+            // to prevent the default Claude Code system prompt from competing with
+            // our output format instructions (e.g., YAML-only output).
+            let systemPromptArg = '';
+            if (options.systemPrompt) {
+                const systemPromptFile = join(tempDir, 'system-prompt.txt');
+                await writeFile(systemPromptFile, options.systemPrompt, 'utf8');
+                systemPromptArg = `--system-prompt "$(cat '${systemPromptFile}')"`;
+            }
             // Build command with temp file
             const flags = this.config.flags.join(' ');
             const modelArg = options.model ? `${this.config.modelFlag} ${options.model}` : '';
-            const command = `${this.config.command} ${flags} ${modelArg} < "${tempFile}"`.replace(/\s+/g, ' ').trim();
+            const extraFlags = options.flags ? options.flags.join(' ') : '';
+            const command = `${this.config.command} ${flags} ${modelArg} ${extraFlags} ${systemPromptArg} < "${tempFile}"`.replace(/\s+/g, ' ').trim();
             // Log the command being executed
             this.logger.info({
                 promptLength: prompt.length,
                 tempFile,
             }, 'Executing command with temp file');
             // Use exec instead of spawn for better shell compatibility
-            const { stderr, stdout } = await execAsync(command, {
-                env: process.env,
+            // Note: setting CLAUDECODE to undefined in a spread does NOT remove it —
+            // Node coerces undefined to the string "undefined", which is still truthy.
+            // We must delete the key from the env object to fully unset it.
+            const env = { ...process.env };
+            delete env.CLAUDECODE;
+            const execOptions = {
+                env,
                 maxBuffer: 10 * 1024 * 1024, // 10MB buffer
                 shell: process.env.SHELL || '/bin/bash',
                 timeout,
-            });
+            };
+            if (options.cwd) {
+                execOptions.cwd = options.cwd;
+                this.logger.info({ cwd: options.cwd }, 'Setting working directory for agent');
+            }
+            const { stderr, stdout } = await execAsync(command, execOptions);
             stdoutData = stdout;
             stderrData = stderr;
             const duration = Date.now() - startTime;

package/dist/services/file-system/path-resolver.d.ts

@@ -5,6 +5,7 @@
  * All commands use this service to get correct directories for epics, stories, and PRD files.
  */
 import type pino from 'pino';
+import type { ReviewConfig } from '../validation/config-validator.js';
 import { FileManager } from './file-manager.js';
 /**
  * PathResolver service for resolving and validating file paths
@@ -118,6 +119,15 @@ export declare class PathResolver {
      * // Returns: '/path/to/project/docs/qa/stories'
      */
     getQaStoryDir(): string;
+    /**
+     * Get the review configuration section from core-config.yaml
+     *
+     * Returns the parsed review configuration if present, or undefined if not.
+     * The review section contains scanner, severity, self-heal, and path-rule settings.
+     *
+     * @returns Review configuration object or undefined
+     */
+    getReviewConfig(): ReviewConfig | undefined;
     /**
      * Get the story directory path
      *

package/dist/services/file-system/path-resolver.js

@@ -154,6 +154,18 @@ export class PathResolver {
         this.logger.debug('Getting QA story directory: %s', paths.qaStoryDir);
         return paths.qaStoryDir;
     }
+    /**
+     * Get the review configuration section from core-config.yaml
+     *
+     * Returns the parsed review configuration if present, or undefined if not.
+     * The review section contains scanner, severity, self-heal, and path-rule settings.
+     *
+     * @returns Review configuration object or undefined
+     */
+    getReviewConfig() {
+        const config = this.loadConfig();
+        return config.review;
+    }
     /**
      * Get the story directory path
      *

package/dist/services/mcp/mcp-config-manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP Configuration Manager
+ *
+ * Manages the active MCP gateway configuration at ~/.bmad/mcp/config.yaml.
+ * Provides methods to add/remove servers, apply presets, and query config state.
+ */
+import type { IConfigManager, McpServerConfig, ServerTemplate } from '../../mcp/types.js';
+export declare class McpConfigManager implements IConfigManager {
+    private config;
+    private readonly configPath;
+    constructor(configPath?: string);
+    /**
+     * Add a server template to the active configuration
+     */
+    addServer(template: ServerTemplate): void;
+    /**
+     * Apply a named preset to the active configuration
+     */
+    applyPreset(presetName: string): void;
+    /**
+     * Get all configured servers with their enabled/disabled status
+     */
+    getEnabledServers(): McpServerConfig[];
+    /**
+     * Get the configured gateway URL
+     */
+    getGatewayUrl(): string;
+    /**
+     * Get the name of the currently active preset
+     */
+    getPresetName(): string;
+    /**
+     * Remove a server from the active configuration
+     *
+     * @returns true if server was found and removed, false if not found
+     */
+    removeServer(name: string): boolean;
+    /**
+     * Load the active config from disk
+     */
+    private loadConfig;
+    /**
+     * Load a preset YAML file
+     */
+    private loadPreset;
+    /**
+     * Resolve preset inheritance chain (e.g., full extends research extends minimal)
+     */
+    private resolvePresetInheritance;
+    /**
+     * Save the active config to disk
+     */
+    private saveConfig;
+}

package/dist/services/mcp/mcp-config-manager.js

@@ -0,0 +1,146 @@
+/**
+ * MCP Configuration Manager
+ *
+ * Manages the active MCP gateway configuration at ~/.bmad/mcp/config.yaml.
+ * Provides methods to add/remove servers, apply presets, and query config state.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'services:mcp:config-manager' });
+const CONFIG_DIR = join(homedir(), '.bmad', 'mcp');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.yaml');
+export class McpConfigManager {
+    config;
+    configPath;
+    constructor(configPath) {
+        this.configPath = configPath || CONFIG_FILE;
+        this.config = this.loadConfig();
+    }
+    /**
+     * Add a server template to the active configuration
+     */
+    addServer(template) {
+        logger.info('Adding server: %s', template.name);
+        this.config.servers[template.name] = template;
+        this.saveConfig();
+    }
+    /**
+     * Apply a named preset to the active configuration
+     */
+    applyPreset(presetName) {
+        logger.info('Applying preset: %s', presetName);
+        const validPresets = ['minimal', 'research', 'full'];
+        if (!validPresets.includes(presetName)) {
+            throw new Error(`Invalid preset '${presetName}'. Available presets: ${validPresets.join(', ')}`);
+        }
+        const presetConfig = this.loadPreset(presetName);
+        this.config = {
+            preset: presetName,
+            servers: {},
+        };
+        // Resolve preset inheritance
+        const resolvedServers = this.resolvePresetInheritance(presetConfig);
+        for (const [name, serverConfig] of Object.entries(resolvedServers)) {
+            this.config.servers[name] = { ...serverConfig, name };
+        }
+        this.saveConfig();
+    }
+    /**
+     * Get all configured servers with their enabled/disabled status
+     */
+    getEnabledServers() {
+        return Object.values(this.config.servers).map((server) => ({
+            apiKeyRequired: server.api_key_required,
+            enabled: server.enabled,
+            name: server.name,
+            useCase: server.use_case,
+        }));
+    }
+    /**
+     * Get the configured gateway URL
+     */
+    getGatewayUrl() {
+        return 'http://localhost:8080';
+    }
+    /**
+     * Get the name of the currently active preset
+     */
+    getPresetName() {
+        return this.config.preset || 'custom';
+    }
+    /**
+     * Remove a server from the active configuration
+     *
+     * @returns true if server was found and removed, false if not found
+     */
+    removeServer(name) {
+        logger.info('Removing server: %s', name);
+        if (this.config.servers[name]) {
+            delete this.config.servers[name];
+            this.saveConfig();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Load the active config from disk
+     */
+    loadConfig() {
+        try {
+            if (existsSync(this.configPath)) {
+                const content = readFileSync(this.configPath, 'utf8');
+                const parsed = yaml.load(content);
+                if (parsed && typeof parsed === 'object') {
+                    return {
+                        preset: parsed.preset,
+                        servers: parsed.servers || {},
+                    };
+                }
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to load config from %s: %s', this.configPath, error.message);
+        }
+        return { servers: {} };
+    }
+    /**
+     * Load a preset YAML file
+     */
+    loadPreset(presetName) {
+        const currentDir = dirname(fileURLToPath(import.meta.url));
+        const presetPath = resolve(currentDir, '..', '..', 'mcp', 'presets', `${presetName}.yaml`);
+        if (!existsSync(presetPath)) {
+            throw new Error(`Preset file not found: ${presetPath}`);
+        }
+        const content = readFileSync(presetPath, 'utf8');
+        return yaml.load(content);
+    }
+    /**
+     * Resolve preset inheritance chain (e.g., full extends research extends minimal)
+     */
+    resolvePresetInheritance(presetConfig) {
+        let servers = {};
+        if (presetConfig.extends) {
+            const parentConfig = this.loadPreset(presetConfig.extends);
+            servers = this.resolvePresetInheritance(parentConfig);
+        }
+        // Merge current preset servers (overrides parent)
+        return { ...servers, ...presetConfig.servers };
+    }
+    /**
+     * Save the active config to disk
+     */
+    saveConfig() {
+        const dir = dirname(this.configPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const content = yaml.dump(this.config, { sortKeys: true });
+        writeFileSync(this.configPath, content, 'utf8');
+        logger.info('Config saved to %s', this.configPath);
+    }
+}

package/dist/services/mcp/mcp-context-injector.d.ts

@@ -0,0 +1,92 @@
+/**
+ * MCP Context Injector
+ *
+ * Provides MCP tool discovery context to headless pipeline agents.
+ * Returns formatted instructions that are prepended to agent prompts,
+ * enabling agents to discover and use external MCP tools.
+ *
+ * Interface consumed by WorkflowOrchestrator (Story 3.3).
+ * Concrete implementation provided by Story 3.1.
+ */
+import type { IConfigManager, IHealthChecker } from '../../mcp/types.js';
+/**
+ * A single MCP tool entry describing a server and its available tools
+ */
+export interface McpToolEntry {
+    description: string;
+    name: string;
+    tools: string[];
+}
+/**
+ * MCP context returned by the injector for a specific agent/phase combination
+ */
+export interface McpContext {
+    /** Formatted tool descriptions from healthy MCP servers */
+    availableTools: McpToolEntry[];
+    /** The text to prepend to the agent prompt — empty string means no injection */
+    instructions: string;
+}
+/** Valid workflow phase identifiers for MCP context injection */
+export type McpPhase = 'dev' | 'epic' | 'qa' | 'review' | 'story';
+/**
+ * Interface for injecting MCP tool context into agent prompts
+ *
+ * Implementations handle: phase-server mapping, health checks,
+ * 500-token budget enforcement, and graceful degradation.
+ */
+export interface McpContextInjector {
+    /**
+     * Get MCP context for a specific agent type and workflow phase
+     *
+     * @param agentType - The type of agent being spawned (e.g., 'architect', 'sm', 'dev', 'qa')
+     * @param phase - The workflow phase (epic, story, dev, review, qa)
+     * @returns MCP context with instructions to prepend (empty instructions = no injection)
+     */
+    getContextForAgent(agentType: string, phase: McpPhase): Promise<McpContext>;
+}
+/** Maximum token budget for MCP instructions (NFR3) */
+export declare const MAX_TOKEN_BUDGET = 500;
+/**
+ * McpContextInjectorImpl generates phase-aware MCP instructions for agent prompts.
+ *
+ * - Queries health status of configured servers
+ * - Filters to servers relevant for the workflow phase
+ * - Generates compact instructions under 500-token budget
+ * - Gracefully degrades: never throws, returns empty context on any error
+ */
+export declare class McpContextInjectorImpl implements McpContextInjector {
+    private readonly configManager;
+    private readonly healthChecker;
+    constructor(configManager: IConfigManager, healthChecker: IHealthChecker);
+    /**
+     * Get MCP context for a specific agent type and workflow phase
+     *
+     * @param agentType - The type of agent being spawned
+     * @param phase - The workflow phase
+     * @returns MCP context with instructions (empty on any error)
+     */
+    getContextForAgent(agentType: string, phase: McpPhase): Promise<McpContext>;
+    /**
+     * Build compact MCP instructions for agent prompt injection
+     *
+     * @param tools - Available tool entries
+     * @param gatewayUrl - MCP gateway URL
+     * @returns Formatted instructions string (empty if no tools)
+     */
+    private buildMcpInstructions;
+    /**
+     * Filter servers to those allowed for the given workflow phase
+     *
+     * @param servers - Available healthy servers
+     * @param phase - Workflow phase
+     * @returns Servers relevant to the phase
+     */
+    private selectServersForPhase;
+}
+/**
+ * Approximate token count using chars/4 heuristic
+ *
+ * @param text - Text to count tokens for
+ * @returns Approximate token count
+ */
+export declare function countTokens(text: string): number;

package/dist/services/mcp/mcp-context-injector.js

@@ -0,0 +1,168 @@
+/**
+ * MCP Context Injector
+ *
+ * Provides MCP tool discovery context to headless pipeline agents.
+ * Returns formatted instructions that are prepended to agent prompts,
+ * enabling agents to discover and use external MCP tools.
+ *
+ * Interface consumed by WorkflowOrchestrator (Story 3.3).
+ * Concrete implementation provided by Story 3.1.
+ */
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'services:mcp:context-injector' });
+// --- Constants ---
+/** Maximum token budget for MCP instructions (NFR3) */
+export const MAX_TOKEN_BUDGET = 500;
+/** Empty context returned on any error or when no servers are available */
+const EMPTY_CONTEXT = { availableTools: [], instructions: '' };
+/**
+ * Phase-to-server mapping. Defines which MCP servers are relevant per workflow phase.
+ * Not user-configurable — fixed per architecture decision.
+ */
+const PHASE_SERVER_MAP = {
+    dev: ['context7', 'playwright'],
+    epic: ['context7', 'exa'],
+    qa: ['context7', 'playwright'],
+    review: ['context7'],
+    story: ['context7'],
+};
+/** Default servers for unrecognized phases */
+const DEFAULT_SERVERS = ['context7'];
+/**
+ * Known tool lists per server (used for instructions generation).
+ * Maps server name → representative tool names.
+ */
+const SERVER_TOOLS = {
+    context7: ['resolve-library-id', 'get-library-docs'],
+    exa: ['web_search_exa', 'research_paper_search', 'company_research', 'competitor_finder'],
+    playwright: ['puppeteer_navigate', 'puppeteer_screenshot', 'puppeteer_click', 'puppeteer_fill'],
+};
+/** Use-case descriptions per server */
+const SERVER_USE_CASES = {
+    context7: 'Library documentation lookup (current API references)',
+    exa: 'Web search, competitive analysis, academic research',
+    playwright: 'Browser automation, screenshots, E2E testing',
+};
+/** Tool selection priority text — must be included in all non-empty instructions */
+const TOOL_PRIORITY_TEXT = `ALWAYS use native tools for local operations:
+  Read files → Read tool, Write files → Write/Edit, Search → Grep/Glob, Run commands → Bash
+ONLY use MCP tools for external operations.`;
+// --- Implementation ---
+/**
+ * McpContextInjectorImpl generates phase-aware MCP instructions for agent prompts.
+ *
+ * - Queries health status of configured servers
+ * - Filters to servers relevant for the workflow phase
+ * - Generates compact instructions under 500-token budget
+ * - Gracefully degrades: never throws, returns empty context on any error
+ */
+export class McpContextInjectorImpl {
+    configManager;
+    healthChecker;
+    constructor(configManager, healthChecker) {
+        this.configManager = configManager;
+        this.healthChecker = healthChecker;
+        logger.debug('McpContextInjectorImpl initialized');
+    }
+    /**
+     * Get MCP context for a specific agent type and workflow phase
+     *
+     * @param agentType - The type of agent being spawned
+     * @param phase - The workflow phase
+     * @returns MCP context with instructions (empty on any error)
+     */
+    async getContextForAgent(agentType, phase) {
+        try {
+            logger.debug('Getting context for agent=%s phase=%s', agentType, phase);
+            // 1. Get configured servers
+            const configuredServers = this.configManager.getEnabledServers();
+            // 2. Check health of all servers
+            const healthReport = await this.healthChecker.checkAll();
+            // 3. Filter to only healthy servers
+            const healthyServerNames = new Set(healthReport.servers
+                .filter((s) => s.status === 'healthy')
+                .map((s) => s.name));
+            const healthyServers = configuredServers.filter((s) => s.enabled && healthyServerNames.has(s.name));
+            // 4. Apply phase-server mapping
+            const phaseServers = this.selectServersForPhase(healthyServers, phase);
+            if (phaseServers.length === 0) {
+                logger.debug('No healthy servers available for phase=%s', phase);
+                return EMPTY_CONTEXT;
+            }
+            // 5. Build tool entries
+            const availableTools = phaseServers.map((server) => ({
+                description: SERVER_USE_CASES[server.name] || server.useCase || server.name,
+                name: server.name,
+                tools: SERVER_TOOLS[server.name] || [],
+            }));
+            // 6. Build instructions with token budget enforcement
+            const gatewayUrl = this.configManager.getGatewayUrl();
+            const instructions = this.buildMcpInstructions(availableTools, gatewayUrl);
+            logger.debug('Context generated: %d servers, %d tokens', availableTools.length, countTokens(instructions));
+            return { availableTools, instructions };
+        }
+        catch (error) {
+            logger.warn('Failed to get MCP context (returning empty): %s', error.message);
+            return EMPTY_CONTEXT;
+        }
+    }
+    /**
+     * Build compact MCP instructions for agent prompt injection
+     *
+     * @param tools - Available tool entries
+     * @param gatewayUrl - MCP gateway URL
+     * @returns Formatted instructions string (empty if no tools)
+     */
+    buildMcpInstructions(tools, gatewayUrl) {
+        if (tools.length === 0) {
+            return '';
+        }
+        let serverLines = tools.map((t) => `- **${t.name}**: ${t.description} [${t.tools.join(', ')}]`);
+        let instructions = assembleInstructions(serverLines, gatewayUrl);
+        // Enforce token budget — drop lowest-priority servers if over budget
+        while (countTokens(instructions) > MAX_TOKEN_BUDGET && serverLines.length > 1) {
+            serverLines = serverLines.slice(0, -1);
+            instructions = assembleInstructions(serverLines, gatewayUrl);
+        }
+        // If still over budget with one server, truncate
+        if (countTokens(instructions) > MAX_TOKEN_BUDGET && serverLines.length === 1) {
+            const maxChars = MAX_TOKEN_BUDGET * 4 - 100;
+            instructions = instructions.slice(0, maxChars);
+        }
+        return instructions;
+    }
+    /**
+     * Filter servers to those allowed for the given workflow phase
+     *
+     * @param servers - Available healthy servers
+     * @param phase - Workflow phase
+     * @returns Servers relevant to the phase
+     */
+    selectServersForPhase(servers, phase) {
+        const allowedNames = PHASE_SERVER_MAP[phase] || DEFAULT_SERVERS;
+        const allowedSet = new Set(allowedNames);
+        return servers.filter((s) => allowedSet.has(s.name));
+    }
+}
+// --- Utility functions (exported for testing) ---
+/**
+ * Approximate token count using chars/4 heuristic
+ *
+ * @param text - Text to count tokens for
+ * @returns Approximate token count
+ */
+export function countTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Assemble the full instructions string from server lines
+ */
+function assembleInstructions(serverLines, gatewayUrl) {
+    return `## Available MCP Tools
+
+${serverLines.join('\n')}
+
+Gateway: ${gatewayUrl}
+
+${TOOL_PRIORITY_TEXT}`;
+}

package/dist/services/mcp/mcp-credential-manager.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP Credential Manager
+ *
+ * Manages API key credentials for MCP servers.
+ * Resolution chain: environment variable > stored credential file.
+ * Stores credentials at ~/.bmad/credentials/.
+ */
+import type { CredentialEntry, ICredentialManager } from '../../mcp/types.js';
+export declare class McpCredentialManager implements ICredentialManager {
+    private readonly credentialsPath;
+    private store;
+    constructor(credentialsPath?: string);
+    /**
+     * Get a credential value from the stored file (not env vars).
+     *
+     * @returns The stored credential value, or null if not found
+     */
+    get(key: string): string | null;
+    /**
+     * List all known credential entries with their configuration status
+     */
+    list(): CredentialEntry[];
+    /**
+     * Resolve a credential key value.
+     * Resolution chain: environment variable > stored credential file.
+     *
+     * @returns The credential value, or null if not found anywhere
+     */
+    resolve(key: string): string | null;
+    /**
+     * Remove a credential from the store.
+     *
+     * @returns true if the key was found and removed, false if not found
+     */
+    remove(key: string): boolean;
+    /**
+     * Store a credential key-value pair
+     */
+    set(key: string, value: string): void;
+    /**
+     * Load the credential store from disk
+     */
+    private loadStore;
+    /**
+     * Save the credential store to disk
+     */
+    private saveStore;
+}