@hyperdrive.bot/bmad-workflow 1.0.18 → 1.0.19

package/dist/commands/workflow.js

@@ -1,6 +1,9 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { basename } from 'node:path';
+import { parseDuration } from '../utils/duration.js';
 import { createAgentRunner, isProviderSupported } from '../services/agents/agent-runner-factory.js';
+import { getRegisteredScannerNames } from '../services/review/scanner-factory.js';
+import { Severity } from '../services/review/types.js';
 import { FileManager } from '../services/file-system/file-manager.js';
 import { PathResolver } from '../services/file-system/path-resolver.js';
 import { BatchProcessor } from '../services/orchestration/batch-processor.js';
@@ -90,6 +93,37 @@ export default class Workflow extends Command {
             description: 'AI provider to use (claude, gemini, or opencode)',
             options: ['claude', 'gemini', 'opencode'],
         }),
+        mcp: Flags.boolean({
+            default: false,
+            description: 'Enable MCP tool injection for pipeline phases via Docker gateway',
+            helpGroup: 'MCP',
+        }),
+        'mcp-phases': Flags.string({
+            description: 'Comma-separated list of phases to inject MCP tools into (valid: epic,story,dev,review,qa)',
+            helpGroup: 'MCP',
+        }),
+        'mcp-preset': Flags.string({
+            description: 'MCP preset name to use for tool configuration (overrides config file)',
+            helpGroup: 'MCP',
+        }),
+        review: Flags.boolean({
+            default: false,
+            description: 'Enable automated code review phase between dev and QA',
+            helpGroup: 'Review Workflow',
+        }),
+        'review-block-on': Flags.string({
+            description: 'Minimum severity to block story from QA (critical|high|medium|low)',
+            helpGroup: 'Review Workflow',
+        }),
+        'review-max-fix': Flags.integer({
+            description: 'Maximum self-heal fix iterations (default: from config or 3)',
+            helpGroup: 'Review Workflow',
+        }),
+        'review-scanners': Flags.string({
+            description: 'Scanner names to run (e.g., lint, ai, coderabbit). Repeatable.',
+            helpGroup: 'Review Workflow',
+            multiple: true,
+        }),
         qa: Flags.boolean({
             default: false,
             description: 'Run QA workflow after development completes',
@@ -124,9 +158,17 @@ export default class Workflow extends Command {
             default: 60,
             description: 'Seconds between story development',
         }),
-        timeout: Flags.integer({
+        timeout: Flags.custom({
+            parse: async (input) => parseDuration(input),
+        })({
             default: 2_700_000,
-            description: 'Agent execution timeout in milliseconds (default: 2700000 = 45 minutes)',
+            description: 'Agent execution timeout — accepts durations like 30s, 5m, 1h, 90m, or raw milliseconds (default: 45m)',
+        }),
+        'review-timeout': Flags.custom({
+            parse: async (input) => parseDuration(input),
+        })({
+            description: 'AI review scanner timeout — overrides --timeout for review phase only (default: 5m)',
+            helpGroup: 'Review Workflow',
         }),
         'max-retries': Flags.integer({
             default: 0,
@@ -178,6 +220,35 @@ export default class Workflow extends Command {
             if (flags['dry-run']) {
                 this.displayDryRunBanner();
             }
+            // Validate review flags when --review is enabled
+            if (flags.review) {
+                // Validate --review-scanners against registered scanner names
+                if (flags['review-scanners'] && flags['review-scanners'].length > 0) {
+                    const validScanners = getRegisteredScannerNames();
+                    const invalidScanners = flags['review-scanners'].filter((s) => !validScanners.includes(s));
+                    if (invalidScanners.length > 0) {
+                        this.error(`Unknown --review-scanners value(s): ${invalidScanners.join(', ')}. Valid scanners are: ${validScanners.join(', ')}`, { exit: 1 });
+                    }
+                }
+                // Validate --review-max-fix is non-negative
+                if (flags['review-max-fix'] !== undefined && flags['review-max-fix'] < 0) {
+                    this.error(`--review-max-fix must be a non-negative integer, got: ${flags['review-max-fix']}`, { exit: 1 });
+                }
+                // Validate --review-block-on against severity enum
+                if (flags['review-block-on'] !== undefined) {
+                    const validSeverities = ['critical', 'high', 'medium', 'low'];
+                    if (!validSeverities.includes(flags['review-block-on'])) {
+                        this.error(`Invalid --review-block-on value: ${flags['review-block-on']}. Valid values are: ${validSeverities.join(', ')}`, { exit: 1 });
+                    }
+                }
+            }
+            // Map --review-block-on string to Severity enum
+            const severityMap = {
+                critical: Severity.CRITICAL,
+                high: Severity.HIGH,
+                low: Severity.LOW,
+                medium: Severity.MEDIUM,
+            };
             // Build workflow configuration
             const config = {
                 autoFix: flags['auto-fix'],
@@ -186,6 +257,9 @@ export default class Workflow extends Command {
                 epicInterval: flags['epic-interval'],
                 input: args.input,
                 maxRetries: flags['max-retries'],
+                mcp: flags.mcp || undefined,
+                mcpPhases: flags['mcp-phases'] ? flags['mcp-phases'].split(',').map((s) => s.trim()) : undefined,
+                mcpPreset: flags['mcp-preset'],
                 model: flags.model,
                 parallel: flags.parallel,
                 pipeline: flags.pipeline,
@@ -197,6 +271,11 @@ export default class Workflow extends Command {
                 qaRetries: flags['qa-retries'],
                 references: flags.reference || [],
                 retryBackoffMs: flags['retry-backoff'],
+                review: flags.review,
+                reviewBlockOn: flags['review-block-on'] ? severityMap[flags['review-block-on']] : undefined,
+                reviewMaxFix: flags['review-max-fix'],
+                reviewScanners: flags['review-scanners'],
+                reviewTimeout: flags['review-timeout'],
                 skipDev: flags['skip-dev'],
                 skipEpics: flags['skip-epics'],
                 skipStories: flags['skip-stories'],
@@ -204,6 +283,35 @@ export default class Workflow extends Command {
                 timeout: flags.timeout,
                 verbose: flags.verbose,
             };
+            // Validate --mcp-phases when --mcp is enabled
+            if (config.mcp && config.mcpPhases) {
+                const validPhases = ['epic', 'story', 'dev', 'review', 'qa'];
+                const invalidPhases = config.mcpPhases.filter((p) => !validPhases.includes(p));
+                if (invalidPhases.length > 0) {
+                    this.error(`Invalid --mcp-phases value(s): ${invalidPhases.join(', ')}. Valid phases are: ${validPhases.join(', ')}`, { exit: 1 });
+                }
+            }
+            // MCP gateway health pre-check (AC: #5, #6)
+            if (config.mcp) {
+                try {
+                    const gatewayUrl = 'http://localhost:8080';
+                    const healthUrl = `${gatewayUrl}/health`;
+                    const response = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+                    if (response.ok) {
+                        if (flags.verbose) {
+                            this.log(colors.info('MCP gateway is healthy'));
+                        }
+                    }
+                    else {
+                        this.log(colors.warning(`MCP gateway returned status ${response.status} — continuing without MCP`));
+                        config.mcp = false;
+                    }
+                }
+                catch {
+                    this.log(colors.warning('MCP gateway is not reachable — continuing without MCP'));
+                    config.mcp = false;
+                }
+            }
             // Log configuration if verbose
             if (flags.verbose) {
                 this.logger.info({ config }, 'Workflow configuration');

package/dist/mcp/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP Gateway Type Definitions
+ *
+ * Shared interfaces for MCP gateway services (health checker, config manager, credential manager).
+ * These types define the contracts that Story 2.4 and Epic 1 services will implement.
+ */
+/**
+ * Health status of a single component
+ */
+export type HealthStatus = 'disabled' | 'healthy' | 'offline' | 'unhealthy';
+/**
+ * Health status for an individual MCP server
+ */
+export interface ServerHealthStatus {
+    error: null | string;
+    latency: null | number;
+    name: string;
+    status: HealthStatus;
+    useCase?: string;
+}
+/**
+ * Gateway-level health status
+ */
+export interface GatewayHealthStatus {
+    latency: null | number;
+    status: HealthStatus;
+    url: string;
+}
+/**
+ * Complete health report for the MCP gateway and all servers
+ */
+export interface HealthReport {
+    gateway: GatewayHealthStatus;
+    servers: ServerHealthStatus[];
+}
+/**
+ * Credential entry with masked value
+ */
+export interface CredentialEntry {
+    configured: boolean;
+    key: string;
+    requiredByPreset: boolean;
+}
+/**
+ * MCP server configuration entry
+ */
+export interface McpServerConfig {
+    apiKeyRequired?: boolean;
+    enabled: boolean;
+    name: string;
+    useCase?: string;
+}
+/**
+ * Server template as defined in server-templates/*.yaml
+ */
+export interface ServerTemplate {
+    api_key_required: boolean;
+    args?: string[];
+    command?: string;
+    enabled: boolean;
+    env?: Record<string, string>;
+    health_check: {
+        command: string;
+        method: 'http' | 'tool_call';
+        timeout: number;
+    };
+    layer?: 'direct' | 'gateway';
+    name: string;
+    transport: 'sse' | 'stdio';
+    url?: string;
+    use_case: string;
+}
+/**
+ * Interface contract for McpHealthChecker (Story 2.4)
+ */
+export interface IHealthChecker {
+    checkAll(): Promise<HealthReport>;
+}
+/**
+ * Interface contract for McpConfigManager (Epic 1)
+ */
+export interface IConfigManager {
+    addServer(template: ServerTemplate): void;
+    applyPreset(presetName: string): void;
+    getEnabledServers(): McpServerConfig[];
+    getGatewayUrl(): string;
+    getPresetName(): string;
+    removeServer(name: string): boolean;
+}
+/**
+ * Interface contract for McpCredentialManager (Epic 1)
+ */
+export interface ICredentialManager {
+    get(key: string): string | null;
+    list(): CredentialEntry[];
+    remove(key: string): boolean;
+    resolve(key: string): string | null;
+    set(key: string, value: string): void;
+}

package/dist/mcp/types.js

@@ -0,0 +1,7 @@
+/**
+ * MCP Gateway Type Definitions
+ *
+ * Shared interfaces for MCP gateway services (health checker, config manager, credential manager).
+ * These types define the contracts that Story 2.4 and Epic 1 services will implement.
+ */
+export {};

package/dist/mcp/utils/docker-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Docker Availability Detection Utilities
+ *
+ * Provides functions to check Docker availability, resolve the gateway
+ * compose file path, and format Docker errors into user-friendly messages.
+ */
+/**
+ * Result of Docker availability check
+ */
+export interface DockerAvailabilityResult {
+    available: boolean;
+    error?: string;
+    reason?: 'daemon-not-running' | 'not-installed';
+}
+/**
+ * Check if Docker is available and the daemon is running
+ *
+ * Executes `docker info` to verify both installation and daemon status.
+ *
+ * @returns DockerAvailabilityResult with availability status and error details
+ */
+export declare function isDockerAvailable(): DockerAvailabilityResult;
+/**
+ * Resolve the path to the Docker Compose gateway file
+ *
+ * The compose file is expected at src/mcp/infrastructure/docker-compose.gateway.yml
+ * relative to the CLI package root.
+ *
+ * @returns Absolute path to docker-compose.gateway.yml
+ */
+export declare function getDockerComposeFilePath(): string;
+/**
+ * Check if the Docker Compose gateway file exists
+ *
+ * @returns true if the compose file exists at the expected path
+ */
+export declare function dockerComposeFileExists(): boolean;
+/**
+ * Format a Docker error into a user-friendly message with troubleshooting hints
+ *
+ * @param result - Docker availability check result
+ * @returns Formatted error message string
+ */
+export declare function formatDockerError(result: DockerAvailabilityResult): string;
+/**
+ * Default gateway health endpoint URL
+ */
+export declare const DEFAULT_GATEWAY_URL = "http://localhost:8080";
+/**
+ * Default health check poll interval in milliseconds
+ */
+export declare const HEALTH_CHECK_INTERVAL_MS = 2000;
+/**
+ * Default health check timeout in milliseconds
+ */
+export declare const HEALTH_CHECK_TIMEOUT_MS = 30000;

package/dist/mcp/utils/docker-utils.js

@@ -0,0 +1,108 @@
+/**
+ * Docker Availability Detection Utilities
+ *
+ * Provides functions to check Docker availability, resolve the gateway
+ * compose file path, and format Docker errors into user-friendly messages.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'mcp:utils:docker' });
+/**
+ * Check if Docker is available and the daemon is running
+ *
+ * Executes `docker info` to verify both installation and daemon status.
+ *
+ * @returns DockerAvailabilityResult with availability status and error details
+ */
+export function isDockerAvailable() {
+    try {
+        execSync('docker info', { stdio: 'pipe', timeout: 10_000 });
+        logger.debug('Docker is available');
+        return { available: true };
+    }
+    catch (error) {
+        const err = error;
+        const stderr = err.stderr ? err.stderr.toString() : err.message;
+        if (stderr.includes('command not found') || stderr.includes('not recognized') || stderr.includes('ENOENT')) {
+            logger.warn('Docker is not installed');
+            return {
+                available: false,
+                error: stderr,
+                reason: 'not-installed',
+            };
+        }
+        logger.warn('Docker daemon is not running');
+        return {
+            available: false,
+            error: stderr,
+            reason: 'daemon-not-running',
+        };
+    }
+}
+/**
+ * Resolve the path to the Docker Compose gateway file
+ *
+ * The compose file is expected at src/mcp/infrastructure/docker-compose.gateway.yml
+ * relative to the CLI package root.
+ *
+ * @returns Absolute path to docker-compose.gateway.yml
+ */
+export function getDockerComposeFilePath() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    // From src/mcp/utils/ → src/mcp/infrastructure/
+    const composePath = resolve(currentDir, '..', 'infrastructure', 'docker-compose.gateway.yml');
+    logger.debug('Resolved Docker Compose file path: %s', composePath);
+    return composePath;
+}
+/**
+ * Check if the Docker Compose gateway file exists
+ *
+ * @returns true if the compose file exists at the expected path
+ */
+export function dockerComposeFileExists() {
+    const composePath = getDockerComposeFilePath();
+    return existsSync(composePath);
+}
+/**
+ * Format a Docker error into a user-friendly message with troubleshooting hints
+ *
+ * @param result - Docker availability check result
+ * @returns Formatted error message string
+ */
+export function formatDockerError(result) {
+    if (result.reason === 'not-installed') {
+        return [
+            'Docker is not installed on this system.',
+            '',
+            'To install Docker:',
+            '  macOS:   brew install --cask docker',
+            '  Linux:   https://docs.docker.com/engine/install/',
+            '  Windows: https://docs.docker.com/desktop/install/windows-install/',
+        ].join('\n');
+    }
+    if (result.reason === 'daemon-not-running') {
+        return [
+            'Docker daemon is not running.',
+            '',
+            'To start Docker:',
+            '  macOS/Windows: Open the Docker Desktop application',
+            '  Linux:         sudo systemctl start docker',
+        ].join('\n');
+    }
+    return `Docker error: ${result.error || 'Unknown error'}`;
+}
+/**
+ * Default gateway health endpoint URL
+ */
+export const DEFAULT_GATEWAY_URL = 'http://localhost:8080';
+/**
+ * Default health check poll interval in milliseconds
+ */
+export const HEALTH_CHECK_INTERVAL_MS = 2000;
+/**
+ * Default health check timeout in milliseconds
+ */
+export const HEALTH_CHECK_TIMEOUT_MS = 30_000;

package/dist/mcp/utils/template-loader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Server Template Loader
+ *
+ * Loads and validates MCP server template YAML files from the
+ * src/mcp/server-templates/ directory.
+ */
+import type { ServerTemplate } from '../types.js';
+/**
+ * List all available server template names by scanning the server-templates directory
+ *
+ * @returns Array of template names (without .yaml extension)
+ */
+export declare function listAvailableTemplates(): string[];
+/**
+ * Load and parse a server template by name
+ *
+ * @param name - Server template name (e.g., 'context7', 'exa')
+ * @returns Parsed ServerTemplate object
+ * @throws Error if template not found, with available templates listed
+ */
+export declare function loadServerTemplate(name: string): ServerTemplate;

package/dist/mcp/utils/template-loader.js

@@ -0,0 +1,60 @@
+/**
+ * Server Template Loader
+ *
+ * Loads and validates MCP server template YAML files from the
+ * src/mcp/server-templates/ directory.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'mcp:utils:template-loader' });
+/**
+ * Resolve the absolute path to the server-templates directory
+ */
+function getTemplatesDir() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    return resolve(currentDir, '..', 'server-templates');
+}
+/**
+ * List all available server template names by scanning the server-templates directory
+ *
+ * @returns Array of template names (without .yaml extension)
+ */
+export function listAvailableTemplates() {
+    const templatesDir = getTemplatesDir();
+    logger.debug('Scanning templates directory: %s', templatesDir);
+    if (!existsSync(templatesDir)) {
+        logger.warn('Templates directory not found: %s', templatesDir);
+        return [];
+    }
+    const files = readdirSync(templatesDir);
+    return files
+        .filter((f) => f.endsWith('.yaml') && !f.startsWith('__'))
+        .map((f) => f.replace('.yaml', ''))
+        .sort();
+}
+/**
+ * Load and parse a server template by name
+ *
+ * @param name - Server template name (e.g., 'context7', 'exa')
+ * @returns Parsed ServerTemplate object
+ * @throws Error if template not found, with available templates listed
+ */
+export function loadServerTemplate(name) {
+    const templatesDir = getTemplatesDir();
+    const templatePath = resolve(templatesDir, `${name}.yaml`);
+    logger.debug('Loading template: %s from %s', name, templatePath);
+    if (!existsSync(templatePath)) {
+        const available = listAvailableTemplates();
+        throw new Error(`Server template '${name}' not found. Available templates: ${available.join(', ')}`);
+    }
+    const content = readFileSync(templatePath, 'utf8');
+    const parsed = yaml.load(content);
+    if (!parsed || typeof parsed !== 'object' || !parsed.name) {
+        throw new Error(`Invalid server template format in '${name}.yaml': missing required 'name' field`);
+    }
+    logger.info('Loaded template: %s (transport=%s, api_key_required=%s)', parsed.name, parsed.transport, parsed.api_key_required);
+    return parsed;
+}

package/dist/models/agent-options.d.ts

@@ -2,7 +2,7 @@ import type { AgentResult } from './agent-result.js';
 /**
  * Available BMAD agent types
  */
-export type AgentType = 'analyst' | 'architect' | 'dev' | 'pm' | 'prd-fixer' | 'quick-flow-solo-dev' | 'sm' | 'tea' | 'tech-writer' | 'ux-designer';
+export type AgentType = 'analyst' | 'architect' | 'dev' | 'pm' | 'prd-fixer' | 'qa' | 'quick-flow-solo-dev' | 'sm' | 'tea' | 'tech-writer' | 'ux-designer';
 /**
  * Agent options without prompt and callbacks (used internally)
  */
@@ -23,6 +23,10 @@ export interface AgentOptions {
      * The type of agent to execute
      */
     agentType: AgentType;
+    /**
+     * Working directory for the agent process
+     */
+    cwd?: string;
     /**
      * Additional CLI flags to pass to the Claude executable
      */
@@ -50,6 +54,11 @@ export interface AgentOptions {
      * File references to include in the agent execution
      */
     references?: string[];
+    /**
+     * System prompt to append via --append-system-prompt (Claude only).
+     * Used to enforce output format constraints (e.g., YAML-only output).
+     */
+    systemPrompt?: string;
     /**
      * Timeout in milliseconds (default: 1800000ms = 30 minutes)
      */

package/dist/models/workflow-config.d.ts

@@ -1,3 +1,4 @@
+import type { Severity } from '../services/review/types.js';
 /**
  * Configuration for workflow execution across all phases
  *
@@ -77,6 +78,31 @@ export interface WorkflowConfig {
      * - OpenCode: anthropic/claude-3-5-sonnet, openai/gpt-4o
      */
     model?: string;
+    /**
+     * Enable MCP tool discovery in agent prompts
+     *
+     * When true, MCP context (available tools/instructions) is prepended to
+     * agent prompts before each spawn. Requires McpContextInjector to be
+     * configured in the orchestrator.
+     * @default false
+     */
+    mcp?: boolean;
+    /**
+     * Restrict MCP injection to specific workflow phases
+     *
+     * When set, only the listed phases receive MCP tool context.
+     * When omitted (and mcp=true), all phases receive MCP context.
+     * @example ['epic', 'dev'] — only epic and dev phases get MCP tools
+     */
+    mcpPhases?: string[];
+    /**
+     * MCP preset name for tool configuration
+     *
+     * Overrides the configured preset for the pipeline run.
+     * Presets define which MCP servers and tools are available.
+     * @example 'research'
+     */
+    mcpPreset?: string;
     /**
      * Filename prefix for generated files
      *
@@ -90,6 +116,37 @@ export interface WorkflowConfig {
      * @default 'claude'
      */
     provider?: 'claude' | 'gemini' | 'opencode';
+    /**
+     * Run automated code review between dev and QA phases
+     *
+     * When true, completed stories are reviewed before forwarding to QA.
+     * In pipeline mode, review runs concurrently via ReviewQueue.
+     * Only PASS stories proceed to QA; FAIL stories are excluded with a warning.
+     * @default false
+     */
+    review?: boolean;
+    /**
+     * Minimum severity that blocks the pipeline during review
+     *
+     * Issues at or above this severity after self-heal will cause a FAIL verdict.
+     * @default Severity.HIGH
+     */
+    reviewBlockOn?: Severity;
+    /**
+     * Maximum self-heal iterations during review
+     *
+     * Controls how many scan→fix cycles the review phase attempts before
+     * giving up on blocking issues.
+     * @default 3
+     */
+    reviewMaxFix?: number;
+    /**
+     * List of scanner IDs to enable during review
+     *
+     * When specified, only these scanners are used (e.g., ['lint', 'ai']).
+     * When omitted, all configured scanners run.
+     */
+    reviewScanners?: string[];
     /**
      * Run QA workflow after development completes
      *
@@ -119,6 +176,13 @@ export interface WorkflowConfig {
      * @example ['docs/architecture.md', 'docs/tech-stack.md']
      */
     references: string[];
+    /**
+     * Absolute path to the workflow session directory
+     *
+     * When set, session-level reports (review summary, tech debt backlog)
+     * are written to this directory. When undefined, session reports are skipped.
+     */
+    sessionDir?: string;
     /**
      * Skip development phase
      *
@@ -147,8 +211,21 @@ export interface WorkflowConfig {
      * @default 60
      */
     storyInterval: number;
+    /**
+     * AI review scanner timeout in milliseconds
+     *
+     * Overrides the global timeout for the AI review phase only.
+     * When not set, falls back to the global timeout or the default (5 minutes).
+     * Accepts human-readable durations via CLI (e.g., "10m", "1h").
+     * @default 300_000 (5 minutes)
+     */
+    reviewTimeout?: number;
     /**
      * Agent execution timeout in milliseconds
+     *
+     * Global timeout ceiling for all agent spawns, review scanners, and
+     * infrastructure operations. Accepts human-readable durations via CLI
+     * (e.g., "45m", "1h", "90m").
      * @default 2_700_000 (45 minutes)
      */
     timeout?: number;

package/dist/models/workflow-result.d.ts

@@ -141,6 +141,13 @@ export interface WorkflowResult {
      * Undefined if QA phase was skipped or not executed.
      */
     qaPhase?: PhaseResult;
+    /**
+     * Review phase result
+     *
+     * Undefined if review phase was skipped or not executed.
+     * Present when config.review === true.
+     */
+    reviewPhase?: PhaseResult;
     /**
      * Story creation phase result
      *