@hyperdrive.bot/bmad-workflow 1.0.22 → 1.0.24

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

@@ -0,0 +1,234 @@
+/**
+ * AssetResolver Service
+ *
+ * Resolves agents, templates, and config through a three-level chain:
+ * 1. CLI flags (highest priority)
+ * 2. .bmad-workflow.yaml config file
+ * 3. Bundled defaults (shipped inside npm package)
+ *
+ * This enables the CLI to work both standalone (zero-config) and
+ * in existing BMAD setups with .bmad-core/.
+ */
+import fs from 'fs-extra';
+import { load as yamlLoad } from 'js-yaml';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDuration } from '../../utils/duration.js';
+/**
+ * Valid AI provider names
+ */
+const VALID_PROVIDERS = ['claude', 'gemini', 'opencode'];
+/**
+ * AssetResolver resolves asset paths using a three-level resolution chain.
+ */
+export class AssetResolver {
+    bundledPath;
+    config;
+    flags;
+    /**
+     * Create a new AssetResolver
+     *
+     * @param flags - CLI flag overrides for agent selection
+     */
+    constructor(flags = {}) {
+        this.flags = flags;
+        this.bundledPath = this.computeBundledPath();
+        this.config = this.loadConfigFile();
+    }
+    /**
+     * Resolve an agent file path.
+     *
+     * Resolution order: CLI flag → config file → bundled default
+     *
+     * @param role - Agent role (dev, sm, qa)
+     * @param flagValue - Optional CLI flag override
+     * @returns Resolved asset with path and source
+     */
+    resolveAgent(role, flagValue) {
+        // Level 1: CLI flag
+        const flag = flagValue || this.getFlagForRole(role);
+        if (flag) {
+            return { path: this.resolveAgentValue(flag), source: 'flag' };
+        }
+        // Level 2: Config file
+        const configKey = `${role}_agent`;
+        const configValue = this.config?.[configKey];
+        if (configValue) {
+            return { path: this.resolveAgentValue(configValue), source: 'config' };
+        }
+        // Level 3: Bundled default
+        return {
+            path: join(this.bundledPath, 'agents', `${role}.md`),
+            source: 'bundled',
+        };
+    }
+    /**
+     * Resolve a template file path.
+     *
+     * Checks bmad_path config directory first, falls back to bundled.
+     *
+     * @param name - Template filename (e.g., 'epic-tmpl.yaml')
+     * @returns Resolved asset with path and source
+     */
+    resolveTemplate(name) {
+        // Config bmad_path override (resolved relative to project root)
+        if (this.config?.bmad_path) {
+            const local = join(process.cwd(), this.config.bmad_path, 'templates', name);
+            if (fs.existsSync(local)) {
+                return { path: local, source: 'config' };
+            }
+        }
+        // Bundled default
+        return {
+            path: join(this.bundledPath, 'templates', name),
+            source: 'bundled',
+        };
+    }
+    /**
+     * Resolve the config file path.
+     *
+     * Returns the absolute path to the bundled default-config.yaml.
+     * Callers (PathResolver) decide whether to prefer local .bmad-core/ over this.
+     *
+     * @returns Absolute path to bundled config file
+     */
+    resolveConfig() {
+        return join(this.bundledPath, 'config', 'default-config.yaml');
+    }
+    /**
+     * Extract execution defaults from the loaded config file.
+     *
+     * Parses and validates: parallel, timeout, provider, model, qa_enabled, pipeline.
+     * Invalid values are silently ignored (field omitted from result).
+     *
+     * @returns Parsed execution defaults, or empty object if no config file
+     */
+    getExecutionDefaults() {
+        if (!this.config)
+            return {};
+        const defaults = {};
+        // parallel — must be positive integer
+        if (this.config.parallel !== undefined) {
+            const val = Number(this.config.parallel);
+            if (Number.isInteger(val) && val > 0) {
+                defaults.parallel = val;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value parallel: ${this.config.parallel} (expected positive integer)`);
+            }
+        }
+        // timeout — human-readable string or number, converted to ms
+        if (this.config.timeout !== undefined) {
+            try {
+                defaults.timeout = parseDuration(this.config.timeout);
+            }
+            catch {
+                console.warn(`[bmad-workflow] Ignoring invalid config value timeout: ${this.config.timeout}`);
+            }
+        }
+        // provider — must be one of valid providers
+        if (this.config.provider !== undefined) {
+            const val = String(this.config.provider);
+            if (VALID_PROVIDERS.includes(val)) {
+                defaults.provider = val;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value provider: ${val} (expected: ${VALID_PROVIDERS.join(', ')})`);
+            }
+        }
+        // model — any non-empty string
+        if (this.config.model !== undefined && typeof this.config.model === 'string' && this.config.model.trim()) {
+            defaults.model = this.config.model.trim();
+        }
+        // qa_enabled — must be boolean
+        if (this.config.qa_enabled !== undefined) {
+            if (typeof this.config.qa_enabled === 'boolean') {
+                defaults.qa_enabled = this.config.qa_enabled;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value qa_enabled: ${this.config.qa_enabled} (expected boolean)`);
+            }
+        }
+        // pipeline — must be boolean
+        if (this.config.pipeline !== undefined) {
+            if (typeof this.config.pipeline === 'boolean') {
+                defaults.pipeline = this.config.pipeline;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value pipeline: ${this.config.pipeline} (expected boolean)`);
+            }
+        }
+        return defaults;
+    }
+    /**
+     * Compute the bundled assets root path.
+     *
+     * From compiled dist/services/file-system/asset-resolver.js,
+     * the assets directory is three levels up: ../../.. → <pkg>/assets/
+     *
+     * @returns Absolute path to bundled assets directory
+     */
+    computeBundledPath() {
+        // Support both ESM (__dirname equivalent) and compiled contexts
+        try {
+            const currentFile = fileURLToPath(import.meta.url);
+            const currentDir = dirname(currentFile);
+            return join(currentDir, '..', '..', '..', 'assets');
+        }
+        catch {
+            // Fallback for environments where import.meta.url is not available
+            return join(__dirname, '..', '..', 'assets');
+        }
+    }
+    /**
+     * Get CLI flag value for a given role.
+     */
+    getFlagForRole(role) {
+        const map = {
+            dev: this.flags.devAgent,
+            qa: this.flags.qaAgent,
+            sm: this.flags.smAgent,
+        };
+        return map[role];
+    }
+    /**
+     * Load .bmad-workflow.yaml from project root (if exists).
+     *
+     * @returns Parsed config or null if file absent
+     */
+    loadConfigFile() {
+        const configPath = join(process.cwd(), '.bmad-workflow.yaml');
+        if (!fs.existsSync(configPath))
+            return null;
+        try {
+            const content = fs.readFileSync(configPath, 'utf8');
+            return yamlLoad(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolve an agent value — could be a built-in name or a file path.
+     *
+     * Built-in names (no path separators, no .md extension) map to bundled agents.
+     * File paths are resolved relative to project root.
+     *
+     * @param value - Agent name or file path
+     * @returns Absolute path to agent file
+     */
+    resolveAgentValue(value) {
+        // Built-in name (no path separators, no extension)
+        if (!value.includes('/') && !value.endsWith('.md')) {
+            // Check bmad_path first (resolved relative to project root)
+            if (this.config?.bmad_path) {
+                const local = join(process.cwd(), this.config.bmad_path, 'agents', `${value}.md`);
+                if (fs.existsSync(local))
+                    return local;
+            }
+            return join(this.bundledPath, 'agents', `${value}.md`);
+        }
+        // File path — resolve relative to project root
+        return resolve(value);
+    }
+}

package/dist/services/file-system/file-manager.d.ts

@@ -37,6 +37,19 @@ export declare class FileManager {
      * await fileManager.createDirectory('docs/epics')
      */
     createDirectory(path: string): Promise<void>;
+    /**
+     * Copy a file from source to destination
+     *
+     * Creates parent directories if they don't exist.
+     * Overwrites destination file if it exists.
+     *
+     * @param source - Source file path
+     * @param dest - Destination file path
+     * @throws {FileSystemError} If file cannot be copied (source not found, permission denied, etc.)
+     * @example
+     * await fileManager.copyFile('assets/agents/dev.md', '.bmad-core/agents/dev.md')
+     */
+    copyFile(source: string, dest: string): Promise<void>;
     /**
      * Check if a file or directory exists
      *

package/dist/services/file-system/file-manager.js

@@ -56,6 +56,38 @@ export class FileManager {
             });
         }
     }
+    /**
+     * Copy a file from source to destination
+     *
+     * Creates parent directories if they don't exist.
+     * Overwrites destination file if it exists.
+     *
+     * @param source - Source file path
+     * @param dest - Destination file path
+     * @throws {FileSystemError} If file cannot be copied (source not found, permission denied, etc.)
+     * @example
+     * await fileManager.copyFile('assets/agents/dev.md', '.bmad-core/agents/dev.md')
+     */
+    async copyFile(source, dest) {
+        this.logger.info('Copying file from %s to %s', source, dest);
+        try {
+            // Ensure destination directory exists
+            await fs.ensureDir(dirname(dest));
+            // Copy file
+            await fs.copy(source, dest, { overwrite: true });
+            this.logger.info('File copied successfully from %s to %s', source, dest);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error copying file from %s to %s: %O', source, dest, err);
+            throw new FileSystemError(`Failed to copy file from ${source} to ${dest}: ${err.message}`, {
+                dest,
+                operation: 'copyFile',
+                originalError: err.message,
+                source,
+            });
+        }
+    }
     /**
      * Check if a file or directory exists
      *

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

@@ -6,6 +6,7 @@
  */
 import type pino from 'pino';
 import type { ReviewConfig } from '../validation/config-validator.js';
+import { AssetResolver } from './asset-resolver.js';
 import { FileManager } from './file-manager.js';
 /**
  * PathResolver service for resolving and validating file paths
@@ -15,10 +16,18 @@ import { FileManager } from './file-manager.js';
  * are resolved relative to the project root and validated for existence.
  */
 export declare class PathResolver {
+    /**
+     * AssetResolver for bundled asset fallback
+     */
+    private readonly assetResolver;
     /**
      * Cached configuration to avoid repeated file reads
      */
     private cachedConfig;
+    /**
+     * Cached path to the configuration file (local or bundled)
+     */
+    private cachedConfigPath;
     /**
      * Cached resolved paths
      */
@@ -40,12 +49,13 @@ export declare class PathResolver {
      *
      * @param fileManager - FileManager instance for file operations
      * @param logger - Pino logger instance for logging path operations
+     * @param assetResolver - Optional AssetResolver instance (DI for testability)
      * @example
      * const logger = createLogger({ namespace: 'services:path-resolver' })
      * const fileManager = new FileManager(logger)
      * const pathResolver = new PathResolver(fileManager, logger)
      */
-    constructor(fileManager: FileManager, logger: pino.Logger);
+    constructor(fileManager: FileManager, logger: pino.Logger, assetResolver?: AssetResolver);
     /**
      * Get all story directories for existence checks
      *
@@ -170,6 +180,17 @@ export declare class PathResolver {
      * @throws {ConfigurationError} If configuration structure is invalid
      */
     private loadConfig;
+    /**
+     * Read, parse, and validate a config file at the given path.
+     *
+     * Sets cachedConfig and cachedConfigPath on success.
+     * Applies hardcoded defaults for missing fields.
+     *
+     * @param configPath - Absolute path to YAML config file
+     * @returns Parsed and validated configuration
+     * @throws {ConfigurationError} If configuration structure is invalid
+     */
+    private readAndParseConfig;
     /**
      * Validate configuration structure
      *

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

@@ -8,6 +8,7 @@ import fs from 'fs-extra';
 import { load as yamlLoad } from 'js-yaml';
 import { dirname, resolve } from 'node:path';
 import { ConfigurationError, FileSystemError } from '../../utils/errors.js';
+import { AssetResolver } from './asset-resolver.js';
 /**
  * Configuration file path relative to project root
  */
@@ -20,10 +21,18 @@ const CONFIG_FILE_PATH = '.bmad-core/core-config.yaml';
  * are resolved relative to the project root and validated for existence.
  */
 export class PathResolver {
+    /**
+     * AssetResolver for bundled asset fallback
+     */
+    assetResolver;
     /**
      * Cached configuration to avoid repeated file reads
      */
     cachedConfig = null;
+    /**
+     * Cached path to the configuration file (local or bundled)
+     */
+    cachedConfigPath = null;
     /**
      * Cached resolved paths
      */
@@ -45,14 +54,16 @@ export class PathResolver {
      *
      * @param fileManager - FileManager instance for file operations
      * @param logger - Pino logger instance for logging path operations
+     * @param assetResolver - Optional AssetResolver instance (DI for testability)
      * @example
      * const logger = createLogger({ namespace: 'services:path-resolver' })
      * const fileManager = new FileManager(logger)
      * const pathResolver = new PathResolver(fileManager, logger)
      */
-    constructor(fileManager, logger) {
+    constructor(fileManager, logger, assetResolver) {
         this.fileManager = fileManager;
         this.logger = logger;
+        this.assetResolver = assetResolver || new AssetResolver({});
         this.projectRoot = process.cwd();
         this.logger.debug('PathResolver initialized with project root: %s', this.projectRoot);
     }
@@ -87,7 +98,11 @@ export class PathResolver {
      * // Returns: '/path/to/project/.bmad-core/core-config.yaml'
      */
     getConfigPath() {
-        const configPath = resolve(this.projectRoot, CONFIG_FILE_PATH);
+        // Trigger config load if not yet loaded (populates cachedConfigPath)
+        if (!this.cachedConfigPath) {
+            this.loadConfig();
+        }
+        const configPath = this.cachedConfigPath;
         this.logger.debug('Getting config path: %s', configPath);
         return configPath;
     }
@@ -274,23 +289,35 @@ export class PathResolver {
         }
         const configPath = this.findConfigFile();
         if (!configPath) {
-            const searchStart = resolve(this.projectRoot, CONFIG_FILE_PATH);
-            this.logger.error('Configuration file not found after searching up to 5 parent directories');
-            throw new FileSystemError(`Configuration file not found: ${searchStart} (searched up to 5 parent directories)`, {
-                configPath: searchStart,
-                operation: 'loadConfig',
-            });
+            // Fallback to bundled default config via AssetResolver
+            const bundledPath = this.assetResolver.resolveConfig();
+            this.logger.info('No local config found, falling back to bundled default: %s', bundledPath);
+            return this.readAndParseConfig(bundledPath);
         }
         this.logger.info('Loading configuration from: %s', configPath);
+        return this.readAndParseConfig(configPath);
+    }
+    /**
+     * Read, parse, and validate a config file at the given path.
+     *
+     * Sets cachedConfig and cachedConfigPath on success.
+     * Applies hardcoded defaults for missing fields.
+     *
+     * @param configPath - Absolute path to YAML config file
+     * @returns Parsed and validated configuration
+     * @throws {ConfigurationError} If configuration structure is invalid
+     */
+    readAndParseConfig(configPath) {
         try {
             // Read configuration file
             const content = fs.readFileSync(configPath, 'utf8');
-            this.logger.debug('Configuration file read successfully');
+            this.logger.debug('Configuration file read successfully from: %s', configPath);
             // Parse YAML
             const config = yamlLoad(content);
             // Validate required fields
             this.validateConfig(config);
             this.cachedConfig = config;
+            this.cachedConfigPath = configPath;
             this.logger.info('Configuration loaded and validated successfully');
             return config;
         }

package/dist/services/orchestration/dependency-graph-executor.js

@@ -308,6 +308,7 @@ Use the file at the path above to document:
             // Execute agent
             const result = await this.agentRunner.runAgent(fullPrompt, {
                 agentType,
+                cwd: this.cwd,
                 model: this.model,
                 references: task.targetFiles, // Pass target files as references
                 timeout: task.estimatedMinutes * 60 * 1000 * 1.5, // 1.5x estimated time as buffer

package/dist/services/orchestration/workflow-orchestrator.d.ts

@@ -47,6 +47,7 @@ import type pino from 'pino';
 import type { InputDetectionResult, WorkflowCallbacks, WorkflowConfig, WorkflowResult } from '../../models/index.js';
 import type { AIProviderRunner } from '../agents/agent-runner.js';
 import type { WorkflowLogger } from '../logging/workflow-logger.js';
+import { AssetResolver } from '../file-system/asset-resolver.js';
 import { FileManager } from '../file-system/file-manager.js';
 import { PathResolver } from '../file-system/path-resolver.js';
 import { EpicParser } from '../parsers/epic-parser.js';
@@ -79,6 +80,8 @@ export interface InputDetector {
 export interface WorkflowOrchestratorConfig {
     /** Service to execute AI agents (Claude or Gemini) */
     agentRunner: AIProviderRunner;
+    /** Optional AssetResolver for three-level path resolution (CLI flag → config → bundled) */
+    assetResolver?: AssetResolver;
     /** Service to handle parallel batch processing */
     batchProcessor: BatchProcessor;
     /** Service to parse epic files and extract stories */
@@ -147,6 +150,7 @@ export interface StoryPromptOptions {
  */
 export declare class WorkflowOrchestrator {
     private readonly agentRunner;
+    private readonly assetResolver;
     private readonly batchProcessor;
     private readonly callbacks?;
     private readonly epicParser;

package/dist/services/orchestration/workflow-orchestrator.js

@@ -46,6 +46,7 @@
 import { isEpicStory } from '../../models/story.js';
 import { ParserError, ValidationError } from '../../utils/errors.js';
 import { runAgentWithRetry } from '../../utils/retry.js';
+import { AssetResolver } from '../file-system/asset-resolver.js';
 import { PrdFixer } from '../parsers/prd-fixer.js';
 import { FileScaffolder } from '../scaffolding/file-scaffolder.js';
 import { BatchProcessor } from './batch-processor.js';
@@ -60,6 +61,7 @@ import { ReviewQueue } from '../review/review-queue.js';
  */
 export class WorkflowOrchestrator {
     agentRunner;
+    assetResolver;
     batchProcessor;
     callbacks;
     epicParser;
@@ -80,6 +82,7 @@ export class WorkflowOrchestrator {
      * @param config - Configuration object containing all service dependencies
      */
     constructor(config) {
+        this.assetResolver = config.assetResolver ?? new AssetResolver({});
         this.inputDetector = config.inputDetector;
         this.prdParser = config.prdParser;
         this.epicParser = config.epicParser;
@@ -173,7 +176,9 @@ export class WorkflowOrchestrator {
         const { cwd, outputPath, prdPath, references, smAgent } = options;
         const referencesText = references.length > 0 ? `\nReferences: ${references.join(', ')}` : '';
         const cwdText = cwd ? `\n\nWorking directory: ${cwd}` : '';
-        const agentRef = smAgent ? `@${smAgent}` : `@.bmad-core/agents/sm.md`;
+        const resolved = this.assetResolver.resolveAgent('sm', smAgent);
+        const agentRef = `@${resolved.path}`;
+        const templateResolved = this.assetResolver.resolveTemplate('epic-tmpl.yaml');
         return `${agentRef}${cwdText}
 
 Create epic '${epic.number}: ${epic.title}' for PRD '${prdPath}'.${referencesText}.
@@ -182,7 +187,7 @@ IMPORTANT: The file at '${outputPath}' has been pre-scaffolded with structure an
 - DO NOT modify the Epic Header section (Epic ID, Status: Draft, Created date are already set)
 - DO NOT change the document structure or section headers
 - ONLY populate the empty content sections marked with [AI Agent will populate]
-- Follow the template structure at @.bmad-core/templates/epic-tmpl.yaml for content guidance
+- Follow the template structure at @${templateResolved.path} for content guidance
 
 Write output to: '${outputPath}'`;
     }
@@ -220,7 +225,9 @@ Write output to: '${outputPath}'`;
         const { cwd, epicPath, outputPath, references, smAgent } = options;
         const referencesText = references.length > 0 ? `\nReferences: ${references.join(', ')}` : '';
         const cwdText = cwd ? `\n\nWorking directory: ${cwd}` : '';
-        const agentRef = smAgent ? `@${smAgent}` : `@.bmad-core/agents/sm.md`;
+        const resolved = this.assetResolver.resolveAgent('sm', smAgent);
+        const agentRef = `@${resolved.path}`;
+        const templateResolved = this.assetResolver.resolveTemplate('story-tmpl.yaml');
         return `${agentRef}${cwdText}
 
 Create story '${story.fullNumber}: ${story.title}' for epic '${epicPath}'. ${referencesText}
@@ -230,7 +237,7 @@ IMPORTANT: The file at '${outputPath}' has been pre-scaffolded with structure an
 - DO NOT modify the Created date in Change Log
 - DO NOT change the document structure or section headers
 - ONLY populate the empty content sections marked with [AI Agent will populate]
-- Follow the template structure at @.bmad-core/templates/story-tmpl.yaml for content guidance
+- Follow the template structure at @${templateResolved.path} for content guidance
 
 Write output to: ${outputPath}`;
     }
@@ -626,7 +633,8 @@ Write output to: ${outputPath}`;
                     // Build prompt with auto-detected references
                     const mcpPrefix = await this.getMcpPromptPrefix('dev', 'dev', config);
                     let prompt = mcpPrefix ? `${mcpPrefix}\n\n` : '';
-                    prompt += config.devAgent ? `@${config.devAgent}\n\n` : `@.bmad-core/agents/dev.md\n\n`;
+                    const devResolved = this.assetResolver.resolveAgent('dev', config.devAgent);
+                    prompt += `@${devResolved.path}\n\n`;
                     // Add working directory instruction if specified
                     if (config.cwd) {
                         prompt += `Working directory: ${config.cwd}\n\n`;
@@ -665,6 +673,7 @@ Write output to: ${outputPath}`;
                     // Execute dev agent with retry on timeout/killed
                     const result = await runAgentWithRetry(this.agentRunner, prompt, {
                         agentType: 'dev',
+                        cwd: config.cwd,
                         references: config.references,
                         timeout: config.timeout ?? 2_700_000,
                     }, {
@@ -907,7 +916,8 @@ Write output to: ${outputPath}`;
                 // Build prompt with auto-detected references
                 const mcpPrefix = await this.getMcpPromptPrefix('dev', 'dev', config);
                 let prompt = mcpPrefix ? `${mcpPrefix}\n\n` : '';
-                prompt += config.devAgent ? `@${config.devAgent}\n\n` : `@.bmad-core/agents/dev.md\n\n`;
+                const devResolved = this.assetResolver.resolveAgent('dev', config.devAgent);
+                prompt += `@${devResolved.path}\n\n`;
                 // Add working directory instruction if specified
                 if (config.cwd) {
                     prompt += `Working directory: ${config.cwd}\n\n`;
@@ -945,6 +955,7 @@ Write output to: ${outputPath}`;
                 });
                 const result = await runAgentWithRetry(this.agentRunner, prompt, {
                     agentType: 'dev',
+                    cwd: config.cwd,
                     references: config.references,
                     timeout: config.timeout ?? 2_700_000,
                 }, {
@@ -1270,6 +1281,7 @@ Write output to: ${outputPath}`;
                     // Step 3: Run Claude agent to populate content sections
                     const result = await runAgentWithRetry(this.agentRunner, prompt, {
                         agentType: 'architect',
+                        cwd: config.cwd,
                         references: config.references,
                         timeout: config.timeout ?? 2_700_000,
                     }, {
@@ -2262,6 +2274,7 @@ Write output to: ${outputPath}`;
                     // Step 4: Run Claude agent to populate content sections
                     const result = await runAgentWithRetry(this.agentRunner, prompt, {
                         agentType: 'sm',
+                        cwd: config.cwd,
                         references: config.references,
                         timeout: config.timeout ?? 2_700_000,
                     }, {
@@ -2588,6 +2601,7 @@ Write output to: ${outputPath}`;
                     // Step 4: Run Claude agent to populate content sections
                     const result = await runAgentWithRetry(this.agentRunner, prompt, {
                         agentType: 'sm',
+                        cwd: config.cwd,
                         references: config.references,
                         timeout: config.timeout ?? 2_700_000,
                     }, {

package/dist/utils/config-merge.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Config Merge Utility
+ *
+ * Implements three-layer merge for execution config:
+ * CLI flags (highest) → .bmad-workflow.yaml → hardcoded defaults (lowest)
+ *
+ * Pure function — no side effects, easy to test.
+ */
+import type { ConfigExecutionDefaults } from '../services/file-system/asset-resolver.js';
+/**
+ * Merged execution config with all fields resolved
+ */
+export interface MergedExecutionConfig {
+    epicInterval: number;
+    maxRetries: number;
+    model: string | undefined;
+    parallel: number;
+    pipeline: boolean;
+    prdInterval: number;
+    provider: 'claude' | 'gemini' | 'opencode';
+    qa: boolean;
+    retryBackoffMs: number;
+    storyInterval: number;
+    timeout: number;
+}
+/**
+ * CLI flags that may be undefined when user didn't pass them.
+ * Only fields explicitly passed by the user should be present.
+ */
+export interface CliExecutionFlags {
+    epicInterval?: number;
+    maxRetries?: number;
+    model?: string;
+    parallel?: number;
+    pipeline?: boolean;
+    prdInterval?: number;
+    provider?: string;
+    qa?: boolean;
+    retryBackoffMs?: number;
+    storyInterval?: number;
+    timeout?: number;
+}
+/**
+ * Hardcoded defaults — final fallback when neither CLI nor config provides a value
+ */
+export declare const EXECUTION_DEFAULTS: MergedExecutionConfig;
+/**
+ * Merge execution config from three layers: CLI flags → config file → hardcoded defaults.
+ *
+ * For each field, the first defined value wins (left to right):
+ * 1. CLI flag (explicit user input)
+ * 2. Config file value (from .bmad-workflow.yaml)
+ * 3. Hardcoded default
+ *
+ * @param cliFlags - Flags explicitly passed via CLI (undefined = not passed)
+ * @param configFile - Execution defaults from .bmad-workflow.yaml
+ * @param defaults - Hardcoded fallback values
+ * @returns Fully resolved execution config
+ */
+export declare function mergeExecutionConfig(cliFlags: CliExecutionFlags, configFile: ConfigExecutionDefaults, defaults?: MergedExecutionConfig): MergedExecutionConfig;