@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/models/provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AI Provider types and configuration
+ */
+/**
+ * Supported AI providers
+ */
+export type AIProvider = 'claude' | 'gemini';
+/**
+ * Provider-specific configuration
+ */
+export interface ProviderConfig {
+    /**
+     * The CLI command to execute
+     */
+    command: string;
+    /**
+     * Default flags to pass to the CLI
+     */
+    flags: string[];
+    /**
+     * Whether this provider supports @file references natively
+     */
+    supportsFileReferences: boolean;
+}
+/**
+ * Default provider configurations
+ */
+export declare const PROVIDER_CONFIGS: Record<AIProvider, ProviderConfig>;

package/dist/models/provider.js

@@ -0,0 +1,18 @@
+/**
+ * AI Provider types and configuration
+ */
+/**
+ * Default provider configurations
+ */
+export const PROVIDER_CONFIGS = {
+    claude: {
+        command: 'claude',
+        flags: ['--dangerously-skip-permissions', '--print'],
+        supportsFileReferences: true,
+    },
+    gemini: {
+        command: 'gemini',
+        flags: ['-p', '--yolo'],
+        supportsFileReferences: false,
+    },
+};

package/dist/models/story.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Story Model
+ *
+ * Represents a user story within an epic that can be implemented by the dev agent.
+ * Stories are extracted from epic markdown files and tracked through their lifecycle.
+ */
+/**
+ * Story status values
+ */
+export type StoryStatus = 'Done' | 'Draft' | 'Failed' | 'InProgress' | 'Ready';
+/**
+ * Represents a user story extracted from an epic
+ */
+export interface Story {
+    /**
+     * Parent epic number
+     */
+    epicNumber: number;
+    /**
+     * Path to story markdown file (optional, set by commands)
+     */
+    filePath?: string;
+    /**
+     * Complete story ID (e.g., "1.2", "2.1")
+     */
+    fullNumber: string;
+    /**
+     * Story number within epic (e.g., 1, 2, 3)
+     */
+    number: number;
+    /**
+     * Current story status (optional, extracted from story file)
+     */
+    status?: StoryStatus;
+    /**
+     * Story title from header
+     */
+    title: string;
+}
+/**
+ * Story type discriminator
+ */
+export type StoryType = 'epic-based' | 'standalone';
+/**
+ * Base metadata shared by all story types
+ */
+export interface BaseStoryMetadata {
+    /**
+     * Full path to story file
+     */
+    filePath: string;
+    /**
+     * Unique identifier for the story
+     */
+    id: string;
+    /**
+     * Current story status
+     */
+    status: StoryStatus;
+    /**
+     * Story title extracted from H1 header
+     */
+    title: string;
+    /**
+     * Story type discriminator
+     */
+    type: StoryType;
+}
+/**
+ * Metadata for epic-based stories (e.g., PREFIX-2.3-story.md)
+ *
+ * Stories that follow the epic.story numbering pattern and are part
+ * of a larger epic workflow.
+ */
+export interface EpicStoryMetadata extends BaseStoryMetadata {
+    /**
+     * Parent epic number (e.g., 2)
+     */
+    epicNumber: number;
+    /**
+     * Complete story number as string (e.g., "2.3")
+     */
+    number: string;
+    /**
+     * Story number within epic (e.g., 3)
+     */
+    storyNumber: number;
+    /**
+     * Type discriminator
+     */
+    type: 'epic-based';
+}
+/**
+ * Metadata for standalone stories (e.g., JIRA-SIGN-10.md, fix-bug.md)
+ *
+ * Stories that don't follow epic numbering and are tracked independently.
+ */
+export interface StandaloneStoryMetadata extends BaseStoryMetadata {
+    /**
+     * Optional category/prefix (e.g., "JIRA-SIGN", "bugfix")
+     */
+    category?: string;
+    /**
+     * Type discriminator
+     */
+    type: 'standalone';
+}
+/**
+ * Union type for all story metadata
+ *
+ * Use type guards to discriminate between epic-based and standalone stories.
+ */
+export type StoryMetadata = EpicStoryMetadata | StandaloneStoryMetadata;
+/**
+ * Metadata extracted from a story file (legacy - kept for backward compatibility)
+ *
+ * @deprecated Use EpicStoryMetadata instead
+ * Used by StoryParser to return detailed information about a story,
+ * including both structural data (epic/story numbers) and content (title, status).
+ */
+export interface LegacyStoryMetadata {
+    /**
+     * Parent epic number (e.g., 2)
+     */
+    epicNumber: number;
+    /**
+     * Full path to story file
+     */
+    filePath: string;
+    /**
+     * Complete story number as string (e.g., "2.3")
+     */
+    number: string;
+    /**
+     * Current story status
+     */
+    status: StoryStatus;
+    /**
+     * Story number within epic (e.g., 3)
+     */
+    storyNumber: number;
+    /**
+     * Story title extracted from H1 header
+     */
+    title: string;
+}
+/**
+ * Type guard to check if metadata is epic-based
+ */
+export declare function isEpicStory(metadata: StoryMetadata): metadata is EpicStoryMetadata;
+/**
+ * Type guard to check if metadata is standalone
+ */
+export declare function isStandaloneStory(metadata: StoryMetadata): metadata is StandaloneStoryMetadata;

package/dist/models/story.js

@@ -0,0 +1,18 @@
+/**
+ * Story Model
+ *
+ * Represents a user story within an epic that can be implemented by the dev agent.
+ * Stories are extracted from epic markdown files and tracked through their lifecycle.
+ */
+/**
+ * Type guard to check if metadata is epic-based
+ */
+export function isEpicStory(metadata) {
+    return metadata.type === 'epic-based';
+}
+/**
+ * Type guard to check if metadata is standalone
+ */
+export function isStandaloneStory(metadata) {
+    return metadata.type === 'standalone';
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Configuration for workflow execution across all phases
+ *
+ * Controls workflow behavior including which phases to execute,
+ * parallelization settings, and additional context for AI agents.
+ */
+export interface WorkflowConfig {
+    /**
+     * Auto-fix PRD format using AI when parsing fails
+     *
+     * When true, if the PRD parser fails to extract epics, the workflow
+     * will use Claude to automatically reformat the PRD to match expected
+     * patterns before retrying. Creates a backup (.bak) before modifying.
+     * @default false
+     */
+    autoFix?: boolean;
+    /**
+     * Working directory for agent execution
+     *
+     * When specified, this path is included in prompts to tell agents
+     * which directory to operate in. Does not affect CLI path resolution.
+     * @example '/path/to/project'
+     */
+    cwd?: string;
+    /**
+     * Preview actions without execution
+     *
+     * When true, workflow logs intended actions but doesn't execute them.
+     * @default false
+     */
+    dryRun: boolean;
+    /**
+     * Seconds between story creation batches
+     *
+     * Controls rate limiting when creating multiple stories.
+     * @default 60
+     */
+    epicInterval: number;
+    /**
+     * Input file path or pattern
+     *
+     * Can be:
+     * - PRD file path (e.g., 'docs/PRD-feature.md')
+     * - Epic file path (e.g., 'docs/epics/epic-1.md')
+     * - Story file pattern (e.g., 'docs/stories/STORY-1.*')
+     */
+    input: string;
+    /**
+     * Max concurrent epic/story creations
+     *
+     * Controls parallelization for epic and story creation phases.
+     * Development phase is always sequential.
+     * @default 3
+     */
+    parallel: number;
+    /**
+     * Enable pipelined workflow execution
+     *
+     * When true, story and dev phases run concurrently using StoryQueue.
+     * When false, executes phases sequentially (backward compatibility).
+     * @default true
+     */
+    pipeline: boolean;
+    /**
+     * Seconds between epic creation batches
+     *
+     * Controls rate limiting when creating multiple epics.
+     * @default 60
+     */
+    prdInterval: number;
+    /**
+     * Filename prefix for generated files
+     *
+     * Used for epic and story file naming.
+     * @example 'PROJ-123' -> 'PROJ-123-epic-1.md'
+     */
+    prefix: string;
+    /**
+     * AI provider to use for agent execution
+     *
+     * @default 'claude'
+     */
+    provider?: 'claude' | 'gemini';
+    /**
+     * Run QA workflow after development completes
+     *
+     * When true, stories are run through QA workflow after dev phase.
+     * @default false
+     */
+    qa?: boolean;
+    /**
+     * Custom prompt/instructions for QA review phase
+     *
+     * Optional additional instructions passed to the QA agent.
+     */
+    qaPrompt?: string;
+    /**
+     * Maximum QA → Dev fix cycles
+     *
+     * Controls how many times a story can go through fix cycles
+     * when QA finds issues. Only used with qa=true.
+     * @default 2
+     */
+    qaRetries?: number;
+    /**
+     * Additional context files for AI agents
+     *
+     * File paths to include as reference material when creating
+     * epics, stories, or during development.
+     * @example ['docs/architecture.md', 'docs/tech-stack.md']
+     */
+    references: string[];
+    /**
+     * Skip development phase
+     *
+     * When true, workflow stops after epic/story creation.
+     * @default false
+     */
+    skipDev: boolean;
+    /**
+     * Skip epic creation phase
+     *
+     * When true, workflow starts from story or dev phase.
+     * @default false
+     */
+    skipEpics: boolean;
+    /**
+     * Skip story creation phase
+     *
+     * When true, workflow skips story creation and goes directly to dev.
+     * @default false
+     */
+    skipStories: boolean;
+    /**
+     * Seconds between story development
+     *
+     * Controls rate limiting when developing multiple stories sequentially.
+     * @default 60
+     */
+    storyInterval: number;
+    /**
+     * Detailed output mode
+     *
+     * When true, additional debug information is logged.
+     * @default false
+     */
+    verbose: boolean;
+}

package/dist/models/workflow-config.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,164 @@
+/**
+ * Workflow Result
+ *
+ * Aggregates results from all workflow phases and provides
+ * overall execution metrics.
+ */
+import type { PhaseResult } from './phase-result.js';
+/**
+ * Input type classification
+ */
+export type InputType = 'epic' | 'prd' | 'story-pattern';
+/**
+ * Metadata about the detection process and results
+ */
+export interface DetectionMetadata {
+    /**
+     * Additional type-specific metadata
+     */
+    [key: string]: unknown;
+    /**
+     * Explanation of why detection was ambiguous (for low confidence)
+     */
+    ambiguityReason?: string;
+    /**
+     * Epic count (for PRD type)
+     */
+    epicCount?: number;
+    /**
+     * Epic number extracted from filename (for epic type)
+     */
+    epicNumber?: number;
+    /**
+     * Filename that was analyzed
+     */
+    filename?: string;
+    /**
+     * Markers found during detection (e.g., PRD section headers)
+     */
+    markers?: string[];
+    /**
+     * Matched files (for story pattern type)
+     */
+    matchedFiles?: string[];
+    /**
+     * Story count (for epic type)
+     */
+    storyCount?: number;
+}
+/**
+ * Internal detection check result
+ * Used for calculating confidence scores
+ */
+export interface DetectionCheck {
+    /**
+     * Evidence found during check
+     */
+    evidence?: string;
+    /**
+     * Name of the check performed
+     */
+    name: string;
+    /**
+     * Whether the check passed
+     */
+    passed: boolean;
+    /**
+     * Weight of this check (0.0 to 1.0)
+     */
+    weight: number;
+}
+/**
+ * Input detection result
+ *
+ * Determines which phase the workflow should start from
+ * based on the input file type.
+ */
+export interface InputDetectionResult {
+    /**
+     * Confidence score (0.0 to 1.0) indicating detection certainty
+     *
+     * - 1.0: High confidence (multiple indicators match)
+     * - 0.7: Medium confidence (single strong indicator)
+     * - 0.5: Low confidence (weak or conflicting indicators)
+     */
+    confidence: number;
+    /**
+     * Error message if detection failed
+     */
+    error?: string;
+    /**
+     * Resolved file path for the input
+     *
+     * Absolute path to the input file or pattern.
+     */
+    filePath: string;
+    /**
+     * Additional metadata about the detected input
+     *
+     * For PRD: { epicCount: number, markers: string[] }
+     * For epic: { epicNumber: number, storyCount: number }
+     * For story pattern: { matchedFiles: string[] }
+     */
+    metadata?: DetectionMetadata;
+    /**
+     * Type of input detected, or null if detection failed
+     *
+     * - 'prd': Product Requirements Document (start from epic phase)
+     * - 'epic': Epic markdown file (start from story phase)
+     * - 'story-pattern': Story file pattern (start from dev phase)
+     */
+    type: InputType | null;
+}
+/**
+ * Aggregated result of complete workflow execution
+ *
+ * Contains phase results, overall metrics, and success indicators.
+ */
+export interface WorkflowResult {
+    /**
+     * Development phase result
+     *
+     * Undefined if dev phase was skipped or not executed.
+     */
+    devPhase?: PhaseResult;
+    /**
+     * Epic creation phase result
+     *
+     * Undefined if epic phase was skipped or not executed.
+     */
+    epicPhase?: PhaseResult;
+    /**
+     * All executed phases succeeded
+     *
+     * True if all executed phases completed without any failures.
+     * Skipped phases do not affect this value.
+     */
+    overallSuccess: boolean;
+    /**
+     * QA phase result
+     *
+     * Undefined if QA phase was skipped or not executed.
+     */
+    qaPhase?: PhaseResult;
+    /**
+     * Story creation phase result
+     *
+     * Undefined if story phase was skipped or not executed.
+     */
+    storyPhase?: PhaseResult;
+    /**
+     * Total workflow duration in milliseconds
+     *
+     * Sum of all executed phase durations.
+     */
+    totalDuration: number;
+    /**
+     * Total number of failures across all phases
+     */
+    totalFailures: number;
+    /**
+     * Total number of files created/modified across all phases
+     */
+    totalFilesProcessed: number;
+}

package/dist/models/workflow-result.js

@@ -0,0 +1,7 @@
+/**
+ * Workflow Result
+ *
+ * Aggregates results from all workflow phases and provides
+ * overall execution metrics.
+ */
+export {};

package/dist/services/agents/agent-runner-factory.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent Runner Factory
+ *
+ * Creates the appropriate AIProviderRunner based on provider configuration.
+ */
+import type pino from 'pino';
+import type { AIProvider } from '../../models/provider.js';
+import type { AIProviderRunner } from './agent-runner.js';
+/**
+ * Create an AI provider runner for the specified provider
+ *
+ * @param provider - The AI provider to create a runner for
+ * @param logger - Logger instance for structured logging
+ * @returns An AIProviderRunner instance for the specified provider
+ * @throws Error if the provider is not supported
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'agent-runner' })
+ * const runner = createAgentRunner('claude', logger)
+ * const result = await runner.runAgent('Hello', { agentType: 'dev' })
+ * ```
+ */
+export declare function createAgentRunner(provider: AIProvider, logger: pino.Logger): AIProviderRunner;
+/**
+ * Check if a provider is supported
+ *
+ * @param provider - The provider to check
+ * @returns true if the provider is supported
+ */
+export declare function isProviderSupported(provider: string): provider is AIProvider;

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

@@ -0,0 +1,44 @@
+/**
+ * Agent Runner Factory
+ *
+ * Creates the appropriate AIProviderRunner based on provider configuration.
+ */
+import { ClaudeAgentRunner } from './claude-agent-runner.js';
+import { GeminiAgentRunner } from './gemini-agent-runner.js';
+/**
+ * Create an AI provider runner for the specified provider
+ *
+ * @param provider - The AI provider to create a runner for
+ * @param logger - Logger instance for structured logging
+ * @returns An AIProviderRunner instance for the specified provider
+ * @throws Error if the provider is not supported
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'agent-runner' })
+ * const runner = createAgentRunner('claude', logger)
+ * const result = await runner.runAgent('Hello', { agentType: 'dev' })
+ * ```
+ */
+export function createAgentRunner(provider, logger) {
+    switch (provider) {
+        case 'claude': {
+            return new ClaudeAgentRunner(logger);
+        }
+        case 'gemini': {
+            return new GeminiAgentRunner(logger);
+        }
+        default: {
+            throw new Error(`Unsupported AI provider: ${provider}`);
+        }
+    }
+}
+/**
+ * Check if a provider is supported
+ *
+ * @param provider - The provider to check
+ * @returns true if the provider is supported
+ */
+export function isProviderSupported(provider) {
+    return provider === 'claude' || provider === 'gemini';
+}

package/dist/services/agents/agent-runner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AIProviderRunner Interface
+ *
+ * Abstract interface for AI provider runners. Each provider (Claude, Gemini, etc.)
+ * implements this interface to provide consistent agent execution across providers.
+ */
+import type pino from 'pino';
+import type { AgentOptions, AgentResult } from '../../models/index.js';
+import type { AIProvider } from '../../models/provider.js';
+/**
+ * Interface for AI provider runners
+ */
+export interface AIProviderRunner {
+    /**
+     * Get the count of active processes
+     *
+     * @returns Number of currently active child processes
+     */
+    getActiveProcessCount(): number;
+    /**
+     * The provider type this runner handles
+     */
+    readonly provider: AIProvider;
+    /**
+     * Execute an AI agent with the specified prompt and options
+     *
+     * @param prompt - The prompt to execute with the agent
+     * @param options - Agent execution options (without prompt)
+     * @returns AgentResult with success status, output, errors, and metadata
+     */
+    runAgent(prompt: string, options: Omit<AgentOptions, 'prompt'>): Promise<AgentResult>;
+}
+/**
+ * Base class with shared functionality for AI provider runners
+ */
+export declare abstract class BaseAgentRunner implements AIProviderRunner {
+    protected readonly logger: pino.Logger;
+    abstract readonly provider: AIProvider;
+    constructor(logger: pino.Logger);
+    abstract getActiveProcessCount(): number;
+    /**
+     * Invoke onResponse callback and return result
+     */
+    protected returnWithCallback(result: AgentResult, onResponse?: (result: AgentResult) => Promise<void> | void): Promise<AgentResult>;
+    abstract runAgent(prompt: string, options: Omit<AgentOptions, 'prompt'>): Promise<AgentResult>;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * AIProviderRunner Interface
+ *
+ * Abstract interface for AI provider runners. Each provider (Claude, Gemini, etc.)
+ * implements this interface to provide consistent agent execution across providers.
+ */
+/**
+ * Base class with shared functionality for AI provider runners
+ */
+export class BaseAgentRunner {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Invoke onResponse callback and return result
+     */
+    async returnWithCallback(result, onResponse) {
+        if (onResponse) {
+            try {
+                await onResponse(result);
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message }, 'Error in onResponse callback');
+            }
+        }
+        return result;
+    }
+}