@hyperdrive.bot/bmad-workflow 1.0.21 → 1.0.23

package/dist/commands/workflow.js

@@ -1,6 +1,9 @@
 import { Args, Command, Flags } from '@oclif/core';
+import { execSync } from 'node:child_process';
 import { basename } from 'node:path';
 import { parseDuration } from '../utils/duration.js';
+import { AssetResolver } from '../services/file-system/asset-resolver.js';
+import { mergeExecutionConfig } from '../utils/config-merge.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';
@@ -55,7 +58,21 @@ export default class Workflow extends Command {
             description: 'Auto-fix PRD format using AI when parsing fails',
         }),
         cwd: Flags.string({
-            description: 'Working directory path to pass to AI agents. Agents will operate in this directory.',
+            description: 'Working directory path to pass to AI agents. Agents will operate in this directory. When using --worktree, this is set automatically.',
+        }),
+        worktree: Flags.boolean({
+            default: false,
+            description: 'Create an isolated gut worktree before running the workflow. Requires --gut-entities.',
+            helpGroup: 'Worktree Isolation',
+        }),
+        'gut-entities': Flags.string({
+            description: 'Comma-separated gut entity names to focus before worktree creation (e.g., "serverless-api,sign"). Required with --worktree.',
+            helpGroup: 'Worktree Isolation',
+        }),
+        'worktree-install': Flags.boolean({
+            default: false,
+            description: 'Run pnpm install in the worktree after creation',
+            helpGroup: 'Worktree Isolation',
         }),
         'dev-agent': Flags.string({
             description: 'Absolute path to a custom dev agent file (default: .bmad-core/agents/dev.md)',
@@ -72,13 +89,11 @@ export default class Workflow extends Command {
             description: 'Seconds between story creation batches',
         }),
         parallel: Flags.integer({
-            default: 3,
-            description: 'Max concurrent epic/story creations',
+            description: 'Max concurrent epic/story creations (default: 3, overridden by .bmad-workflow.yaml)',
         }),
         pipeline: Flags.boolean({
             allowNo: true,
-            default: true,
-            description: 'Enable pipelined workflow (start dev on stories sequentially as they are created)',
+            description: 'Enable pipelined workflow (default: true, overridden by .bmad-workflow.yaml)',
         }),
         'prd-interval': Flags.integer({
             default: 60,
@@ -95,8 +110,7 @@ export default class Workflow extends Command {
             description: 'Session directory prefix (default: derived from input filename, e.g., PRD-feature.md → feature)',
         }),
         provider: Flags.string({
-            default: 'claude',
-            description: 'AI provider to use (claude, gemini, or opencode)',
+            description: 'AI provider to use (default: claude, overridden by .bmad-workflow.yaml)',
             options: ['claude', 'gemini', 'opencode'],
         }),
         mcp: Flags.boolean({
@@ -131,8 +145,8 @@ export default class Workflow extends Command {
             multiple: true,
         }),
         qa: Flags.boolean({
-            default: false,
-            description: 'Run QA workflow after development completes',
+            allowNo: true,
+            description: 'Run QA workflow after development completes (default: false, overridden by qa_enabled in .bmad-workflow.yaml)',
             helpGroup: 'QA Workflow',
         }),
         'qa-prompt': Flags.string({
@@ -167,8 +181,7 @@ export default class Workflow extends Command {
         timeout: Flags.custom({
             parse: async (input) => parseDuration(input),
         })({
-            default: 2_700_000,
-            description: 'Agent execution timeout — accepts durations like 30s, 5m, 1h, 90m, or raw milliseconds (default: 45m)',
+            description: 'Agent execution timeout — accepts durations like 30s, 5m, 1h, 90m, or raw milliseconds (default: 45m, overridden by .bmad-workflow.yaml)',
         }),
         'review-timeout': Flags.custom({
             parse: async (input) => parseDuration(input),
@@ -212,12 +225,79 @@ export default class Workflow extends Command {
                     this.error(`File not found: ${inputPath}`, { exit: 1 });
                 }
             }
+            // Worktree isolation: validate flags and create worktree if requested
+            if (flags.worktree) {
+                if (!flags['gut-entities']) {
+                    this.error('--gut-entities is required when using --worktree. Specify comma-separated entity names (e.g., --gut-entities "serverless-api,sign").', { exit: 1 });
+                }
+                if (flags.cwd) {
+                    this.error('--cwd and --worktree are mutually exclusive. --worktree sets cwd automatically.', { exit: 1 });
+                }
+                const entities = flags['gut-entities'].split(',').map((e) => e.trim()).filter(Boolean);
+                const branchSlug = `workflow/${basename(inputPath, '.md').replace(/^PRD-/, '').toLowerCase()}-${Date.now()}`;
+                const installFlag = flags['worktree-install'] ? '--install' : '';
+                this.log(colors.info(`Creating isolated worktree: ${branchSlug}`));
+                this.log(colors.info(`Entities: ${entities.join(', ')}`));
+                try {
+                    // Focus entities
+                    for (const entity of entities) {
+                        execSync(`gut focus ${entity}`, { cwd: process.cwd(), stdio: 'pipe' });
+                    }
+                    // Create worktree
+                    const wtOutput = execSync(`gut worktree create ${branchSlug} ${installFlag}`.trim(), { cwd: process.cwd(), encoding: 'utf8', stdio: 'pipe' });
+                    // Extract worktree path from output (gut prints "Path:   /tmp/gut-worktrees/...")
+                    const pathMatch = wtOutput.match(/Path:\s+(.+)/);
+                    if (!pathMatch) {
+                        this.error('Failed to parse worktree path from gut output. Run gut worktree create manually.', { exit: 1 });
+                    }
+                    flags.cwd = pathMatch[1].trim();
+                    this.log(colors.info(`Worktree created at: ${flags.cwd}`));
+                    // Copy PRD and reference files to worktree (they may not exist in the worktree branch)
+                    const { copyFileSync, mkdirSync } = await import('node:fs');
+                    const { dirname, join } = await import('node:path');
+                    const filesToCopy = [inputPath, ...(flags.reference || [])];
+                    for (const file of filesToCopy) {
+                        const destPath = join(flags.cwd, file);
+                        try {
+                            mkdirSync(dirname(destPath), { recursive: true });
+                            copyFileSync(file, destPath);
+                        }
+                        catch {
+                            // File may already exist in worktree — ignore
+                        }
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.error(`Worktree creation failed: ${message}`, { exit: 1 });
+                }
+            }
+            // Three-layer config merge: CLI flags → .bmad-workflow.yaml → hardcoded defaults
+            const assetResolver = new AssetResolver({
+                devAgent: flags['dev-agent'],
+                smAgent: flags['sm-agent'],
+            });
+            const configDefaults = assetResolver.getExecutionDefaults();
+            const cliFlags = {
+                epicInterval: flags['epic-interval'],
+                maxRetries: flags['max-retries'],
+                model: flags.model,
+                parallel: flags.parallel,
+                pipeline: flags.pipeline,
+                prdInterval: flags['prd-interval'],
+                provider: flags.provider,
+                qa: flags.qa,
+                retryBackoffMs: flags['retry-backoff'],
+                storyInterval: flags['story-interval'],
+                timeout: flags.timeout,
+            };
+            const merged = mergeExecutionConfig(cliFlags, configDefaults);
             // Validate provider
-            if (!isProviderSupported(flags.provider)) {
-                this.error(`Unsupported provider: ${flags.provider}. Use 'claude', 'gemini', or 'opencode'.`, { exit: 1 });
+            if (!isProviderSupported(merged.provider)) {
+                this.error(`Unsupported provider: ${merged.provider}. Use 'claude', 'gemini', or 'opencode'.`, { exit: 1 });
             }
             // Initialize services with parallel concurrency and provider
-            await this.initializeServices(flags.parallel, flags.provider, flags.verbose);
+            await this.initializeServices(merged.parallel, merged.provider, flags.verbose);
             // Register signal handlers
             this.registerSignalHandlers();
             // Initialize session scaffolder and create session structure
@@ -255,29 +335,29 @@ export default class Workflow extends Command {
                 low: Severity.LOW,
                 medium: Severity.MEDIUM,
             };
-            // Build workflow configuration
+            // Build workflow configuration using merged execution defaults
             const config = {
                 autoFix: flags['auto-fix'],
                 cwd: flags.cwd,
                 devAgent: flags['dev-agent'],
                 dryRun: flags['dry-run'],
-                epicInterval: flags['epic-interval'],
+                epicInterval: merged.epicInterval,
                 input: args.input,
-                maxRetries: flags['max-retries'],
+                maxRetries: merged.maxRetries,
                 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,
-                prdInterval: flags['prd-interval'],
+                model: merged.model,
+                parallel: merged.parallel,
+                pipeline: merged.pipeline,
+                prdInterval: merged.prdInterval,
                 prefix: flags.prefix,
-                provider: flags.provider,
-                qa: flags.qa,
+                provider: merged.provider,
+                qa: merged.qa,
                 qaPrompt: flags['qa-prompt'],
                 qaRetries: flags['qa-retries'],
                 references: flags.reference || [],
-                retryBackoffMs: flags['retry-backoff'],
+                retryBackoffMs: merged.retryBackoffMs,
                 review: flags.review,
                 reviewBlockOn: flags['review-block-on'] ? severityMap[flags['review-block-on']] : undefined,
                 reviewMaxFix: flags['review-max-fix'],
@@ -287,8 +367,8 @@ export default class Workflow extends Command {
                 smAgent: flags['sm-agent'],
                 skipEpics: flags['skip-epics'],
                 skipStories: flags['skip-stories'],
-                storyInterval: flags['story-interval'],
-                timeout: flags.timeout,
+                storyInterval: merged.storyInterval,
+                timeout: merged.timeout,
                 verbose: flags.verbose,
             };
             // Validate --mcp-phases when --mcp is enabled

package/dist/models/bmad-config-schema.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Zod schema for .bmad-workflow.yaml configuration file.
+ *
+ * Defines validation, defaults, and type inference for the CLI config.
+ */
+import { z } from 'zod';
+/**
+ * Built-in agent names grouped by role
+ */
+export declare const BUILT_IN_AGENTS: {
+    readonly dev: readonly ["pirlo", "barry"];
+    readonly qa: readonly ["quinn"];
+    readonly sm: readonly ["lena", "bob"];
+};
+/**
+ * All valid built-in agent names (flat list)
+ */
+export declare const ALL_BUILT_IN_AGENTS: readonly ["pirlo", "barry", "lena", "bob", "quinn"];
+/**
+ * Agent descriptions for interactive menus
+ */
+export declare const AGENT_DESCRIPTIONS: Record<string, string>;
+/**
+ * Zod schema for .bmad-workflow.yaml
+ */
+export declare const BmadConfigSchema: z.ZodObject<{
+    bmad_path: z.ZodOptional<z.ZodString>;
+    communication_language: z.ZodDefault<z.ZodString>;
+    dev_agent: z.ZodDefault<z.ZodString>;
+    document_output_language: z.ZodDefault<z.ZodString>;
+    epic_location: z.ZodDefault<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    output_folder: z.ZodDefault<z.ZodString>;
+    parallel: z.ZodDefault<z.ZodNumber>;
+    provider: z.ZodDefault<z.ZodEnum<{
+        claude: "claude";
+        gemini: "gemini";
+        opencode: "opencode";
+    }>>;
+    qa_agent: z.ZodDefault<z.ZodString>;
+    qa_enabled: z.ZodDefault<z.ZodBoolean>;
+    qa_location: z.ZodDefault<z.ZodString>;
+    sm_agent: z.ZodDefault<z.ZodString>;
+    story_location: z.ZodDefault<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodString>;
+    user_name: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Inferred TypeScript type from the schema
+ */
+export type BmadConfig = z.infer<typeof BmadConfigSchema>;

package/dist/models/bmad-config-schema.js

@@ -0,0 +1,53 @@
+/**
+ * Zod schema for .bmad-workflow.yaml configuration file.
+ *
+ * Defines validation, defaults, and type inference for the CLI config.
+ */
+import { z } from 'zod';
+/**
+ * Built-in agent names grouped by role
+ */
+export const BUILT_IN_AGENTS = {
+    dev: ['pirlo', 'barry'],
+    qa: ['quinn'],
+    sm: ['lena', 'bob'],
+};
+/**
+ * All valid built-in agent names (flat list)
+ */
+export const ALL_BUILT_IN_AGENTS = [
+    ...BUILT_IN_AGENTS.dev,
+    ...BUILT_IN_AGENTS.sm,
+    ...BUILT_IN_AGENTS.qa,
+];
+/**
+ * Agent descriptions for interactive menus
+ */
+export const AGENT_DESCRIPTIONS = {
+    barry: 'Quick Flow Solo Dev — lean, fast, minimal ceremony',
+    bob: 'Classic SM — standard agile stories',
+    lena: 'Pirlo-Aware SM — deploy subtasks, real-infra ACs',
+    pirlo: 'Full-Stack Orchestrator — backend, deploy, E2E',
+    quinn: 'QA Engineer — rapid test coverage',
+};
+/**
+ * Zod schema for .bmad-workflow.yaml
+ */
+export const BmadConfigSchema = z.object({
+    bmad_path: z.string().optional(),
+    communication_language: z.string().default('English'),
+    dev_agent: z.string().default('pirlo'),
+    document_output_language: z.string().default('English'),
+    epic_location: z.string().default('docs/epics'),
+    model: z.string().optional(),
+    output_folder: z.string().default('./docs'),
+    parallel: z.number().default(3),
+    provider: z.enum(['claude', 'gemini', 'opencode']).default('claude'),
+    qa_agent: z.string().default('quinn'),
+    qa_enabled: z.boolean().default(true),
+    qa_location: z.string().default('docs/qa/stories'),
+    sm_agent: z.string().default('lena'),
+    story_location: z.string().default('docs/stories'),
+    timeout: z.string().default('45m'),
+    user_name: z.string().default(''),
+});

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

@@ -161,12 +161,17 @@ export class GeminiAgentRunner {
         let stderrData = '';
         try {
             // Use exec instead of spawn for better shell compatibility
-            const { stderr, stdout } = await execAsync(command, {
+            const execOptions = {
                 env: process.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 Gemini agent');
+            }
+            const { stderr, stdout } = await execAsync(command, execOptions);
             stdoutData = stdout;
             stderrData = stderr;
             const duration = Date.now() - startTime;

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

@@ -167,12 +167,17 @@ export class OpenCodeAgentRunner {
                 tempFile,
             }, 'Executing command with temp file');
             // Use exec for better shell compatibility
-            const { stderr, stdout } = await execAsync(command, {
+            const execOptions = {
                 env: process.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 OpenCode agent');
+            }
+            const { stderr, stdout } = await execAsync(command, execOptions);
             stdoutData = stdout;
             stderrData = stderr;
             const duration = Date.now() - startTime;

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

@@ -0,0 +1,117 @@
+/**
+ * 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/.
+ */
+/**
+ * Resolved asset with its source
+ */
+export interface ResolvedAsset {
+    path: string;
+    source: 'bundled' | 'config' | 'flag';
+}
+/**
+ * CLI flags for agent overrides
+ */
+export interface AssetResolverFlags {
+    devAgent?: string;
+    qaAgent?: string;
+    smAgent?: string;
+}
+/**
+ * Execution defaults parsed from .bmad-workflow.yaml
+ */
+export interface ConfigExecutionDefaults {
+    model?: string;
+    parallel?: number;
+    pipeline?: boolean;
+    provider?: 'claude' | 'gemini' | 'opencode';
+    qa_enabled?: boolean;
+    timeout?: number;
+}
+/**
+ * AssetResolver resolves asset paths using a three-level resolution chain.
+ */
+export declare class AssetResolver {
+    private readonly bundledPath;
+    private readonly config;
+    private readonly flags;
+    /**
+     * Create a new AssetResolver
+     *
+     * @param flags - CLI flag overrides for agent selection
+     */
+    constructor(flags?: Partial<AssetResolverFlags>);
+    /**
+     * 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: 'dev' | 'qa' | 'sm', flagValue?: string): ResolvedAsset;
+    /**
+     * 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: string): ResolvedAsset;
+    /**
+     * 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(): string;
+    /**
+     * 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(): ConfigExecutionDefaults;
+    /**
+     * 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
+     */
+    private computeBundledPath;
+    /**
+     * Get CLI flag value for a given role.
+     */
+    private getFlagForRole;
+    /**
+     * Load .bmad-workflow.yaml from project root (if exists).
+     *
+     * @returns Parsed config or null if file absent
+     */
+    private loadConfigFile;
+    /**
+     * 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
+     */
+    private resolveAgentValue;
+}