@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/orchestration/story-queue.js

@@ -0,0 +1,170 @@
+/**
+ * Story Queue
+ *
+ * Thread-safe queue mechanism for capturing completed stories during the story creation phase
+ * and making them available to the development phase. Supports concurrent consumers with
+ * async waiting when queue is empty.
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino'
+ * import { StoryQueue } from './story-queue.js'
+ *
+ * const logger = pino()
+ * const queue = new StoryQueue(logger)
+ *
+ * // Producer: enqueue completed stories
+ * queue.enqueue(story1)
+ * queue.enqueue(story2)
+ *
+ * // Consumer: dequeue stories for processing
+ * const story = await queue.dequeue() // Waits if queue is empty
+ * if (story === null) {
+ *   // Queue is closed and empty
+ *   return
+ * }
+ *
+ * // When all stories are created, close the queue
+ * queue.close()
+ * ```
+ */
+/**
+ * Thread-safe queue for story pipeline coordination.
+ *
+ * Provides FIFO queueing with async waiting for consumers. Safe for concurrent
+ * access in Node.js event loop (no mutex needed due to single-threaded execution).
+ */
+export class StoryQueue {
+    /**
+     * Flag indicating no more stories will be added
+     */
+    closed = false;
+    /**
+     * Structured logger instance
+     */
+    logger;
+    /**
+     * Internal FIFO queue of stories
+     */
+    queue = [];
+    /**
+     * Array of waiting dequeue promises
+     */
+    waiters = [];
+    /**
+     * Creates a new StoryQueue instance
+     *
+     * @param logger - Pino logger for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+        this.logger.debug('StoryQueue initialized');
+    }
+    /**
+     * Signals that no more stories will be added to the queue.
+     * All waiting dequeue calls will be resolved with null.
+     */
+    close() {
+        if (this.closed) {
+            this.logger.warn('Close called on already closed queue');
+            return;
+        }
+        this.closed = true;
+        this.logger.info({
+            remainingQueueSize: this.queue.length,
+            waitersToNotify: this.waiters.length,
+        }, 'Queue closed');
+        // Wake up all waiting dequeue calls with null
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            if (waiter) {
+                waiter(null);
+            }
+        }
+    }
+    /**
+     * Removes and returns the next story from the queue.
+     * If queue is empty and not closed, waits asynchronously for a story to be enqueued.
+     * If queue is closed and empty, returns null.
+     *
+     * @returns Promise that resolves to the next story, or null if queue is closed and empty
+     */
+    async dequeue() {
+        // If queue has items, return immediately
+        if (this.queue.length > 0) {
+            const story = this.queue.shift() ?? null;
+            this.logger.info({
+                remainingQueueSize: this.queue.length,
+                storyNumber: story?.fullNumber,
+                storyTitle: story?.title,
+            }, 'Story dequeued');
+            return story;
+        }
+        // If closed and empty, return null
+        if (this.closed) {
+            this.logger.debug({
+                closed: this.closed,
+                isEmpty: true,
+            }, 'Dequeue returning null: queue closed and empty');
+            return null;
+        }
+        // Wait for item or close
+        this.logger.debug({
+            closed: this.closed,
+            isEmpty: this.isEmpty(),
+            waiters: this.waiters.length,
+        }, 'Dequeue waiting for story');
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    /**
+     * Adds a story to the queue
+     *
+     * @param story - The story to enqueue
+     * @throws Error if queue is already closed
+     */
+    enqueue(story) {
+        if (this.closed) {
+            const error = new Error('Cannot enqueue to closed queue');
+            this.logger.error({
+                closed: this.closed,
+                storyNumber: story.fullNumber,
+            }, 'Enqueue failed: queue closed');
+            throw error;
+        }
+        this.queue.push(story);
+        this.logger.info({
+            queueSize: this.queue.length,
+            storyNumber: story.fullNumber,
+            storyTitle: story.title,
+            waiters: this.waiters.length,
+        }, 'Story enqueued');
+        // Wake up a waiting dequeue call if any
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            const dequeuedStory = this.queue.shift() ?? null;
+            this.logger.debug({
+                remainingQueueSize: this.queue.length,
+                storyNumber: dequeuedStory?.fullNumber,
+            }, 'Woke up waiting dequeue consumer');
+            waiter(dequeuedStory);
+        }
+    }
+    /**
+     * Gets the number of pending stories in the queue
+     *
+     * @returns Number of stories waiting to be dequeued
+     */
+    getPendingCount() {
+        return this.queue.length;
+    }
+    /**
+     * Checks if the queue is empty
+     *
+     * @returns true if queue has no items, false otherwise
+     */
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+}

package/dist/services/orchestration/story-type-detector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * StoryTypeDetector Service
+ *
+ * Analyzes story content to determine if it's frontend, backend, or full-stack work.
+ * Used to automatically include relevant documentation references for dev agents.
+ */
+import type pino from 'pino';
+/**
+ * Story type classification
+ */
+export type StoryType = 'backend' | 'frontend' | 'fullstack' | 'unknown';
+/**
+ * Detection result with confidence score
+ */
+export interface StoryTypeDetection {
+    /**
+     * Confidence score (0-1)
+     */
+    confidence: number;
+    /**
+     * Matched keywords that led to detection
+     */
+    matchedKeywords: string[];
+    /**
+     * Detected story type
+     */
+    type: StoryType;
+}
+/**
+ * Configuration for documentation references by story type
+ */
+export interface DocumentationReferences {
+    backend: string[];
+    frontend: string[];
+}
+/**
+ * StoryTypeDetector service for analyzing story content
+ *
+ * Detects whether a story is frontend, backend, or full-stack work
+ * by analyzing keywords, file paths, and acceptance criteria.
+ */
+export declare class StoryTypeDetector {
+    private readonly logger;
+    /**
+     * Create a new StoryTypeDetector instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Detect story type from content
+     *
+     * Analyzes the story content (title, description, tasks, acceptance criteria)
+     * to determine if it's frontend, backend, or full-stack work.
+     *
+     * @param storyContent - Full story markdown content
+     * @returns Detection result with type, confidence, and matched keywords
+     */
+    detectStoryType(storyContent: string): StoryTypeDetection;
+    /**
+     * Get documentation references for a story type
+     *
+     * Returns the appropriate documentation file paths based on the detected story type.
+     * Saves tokens by only including relevant documentation.
+     *
+     * @param storyType - Detected story type
+     * @returns Array of documentation file paths to include
+     */
+    getDocumentationReferences(storyType: StoryType): string[];
+    /**
+     * Count keyword matches in content
+     * @private
+     */
+    private countKeywordMatches;
+    /**
+     * Count file path pattern matches
+     * @private
+     */
+    private countPathPatternMatches;
+}

package/dist/services/orchestration/story-type-detector.js

@@ -0,0 +1,258 @@
+/**
+ * StoryTypeDetector Service
+ *
+ * Analyzes story content to determine if it's frontend, backend, or full-stack work.
+ * Used to automatically include relevant documentation references for dev agents.
+ */
+/**
+ * Keywords that indicate frontend work
+ */
+const FRONTEND_KEYWORDS = [
+    'frontend',
+    'ui',
+    'component',
+    'react',
+    'amplify',
+    'interface',
+    'page',
+    'view',
+    'form',
+    'button',
+    'modal',
+    'navigation',
+    'routing',
+    'css',
+    'style',
+    'theme',
+    'layout',
+    'responsive',
+    'client-side',
+    'browser',
+    'web app',
+    'user interface',
+    'vite',
+    'typescript react',
+    'tsx',
+    'jsx',
+    'cognito',
+    'authentication ui',
+    'sign-in',
+    'sign-up',
+];
+/**
+ * Keywords that indicate backend work
+ */
+const BACKEND_KEYWORDS = [
+    'backend',
+    'api',
+    'endpoint',
+    'handler',
+    'service',
+    'dynamodb',
+    'database',
+    'lambda',
+    'serverless',
+    'middleware',
+    'authentication',
+    'authorization',
+    'rest api',
+    'graphql',
+    's3',
+    'eventbridge',
+    'sqs',
+    'sns',
+    'cognito user pool',
+    'aws sdk',
+    'marshall',
+    'unmarshall',
+    'query command',
+    'put item',
+    'get item',
+    'update item',
+    'delete item',
+    'gsi',
+    'partition key',
+    'sort key',
+    'http status',
+    'error handling',
+    'validation',
+    'business logic',
+];
+/**
+ * File path patterns that indicate frontend work
+ */
+const FRONTEND_PATH_PATTERNS = [
+    /packages\/web-apps\//i,
+    /packages\/entities\/clients\/.*\/repos\//i,
+    /src\/components\//i,
+    /src\/pages\//i,
+    /src\/lib\//i,
+    /\.tsx$/i,
+    /\.jsx$/i,
+    /frontend/i,
+];
+/**
+ * File path patterns that indicate backend work
+ */
+const BACKEND_PATH_PATTERNS = [
+    /packages\/serverless\/api/i,
+    /src\/handlers\//i,
+    /src\/services\//i,
+    /src\/middleware/i,
+    /serverless\.yml$/i,
+    /\.handler\.ts$/i,
+    /\.service\.ts$/i,
+    /backend/i,
+    /api/i,
+];
+/**
+ * StoryTypeDetector service for analyzing story content
+ *
+ * Detects whether a story is frontend, backend, or full-stack work
+ * by analyzing keywords, file paths, and acceptance criteria.
+ */
+export class StoryTypeDetector {
+    logger;
+    /**
+     * Create a new StoryTypeDetector instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Detect story type from content
+     *
+     * Analyzes the story content (title, description, tasks, acceptance criteria)
+     * to determine if it's frontend, backend, or full-stack work.
+     *
+     * @param storyContent - Full story markdown content
+     * @returns Detection result with type, confidence, and matched keywords
+     */
+    detectStoryType(storyContent) {
+        this.logger.debug('Detecting story type from content');
+        // Convert to lowercase for case-insensitive matching
+        const contentLower = storyContent.toLowerCase();
+        // Count keyword matches
+        const frontendMatches = this.countKeywordMatches(contentLower, FRONTEND_KEYWORDS);
+        const backendMatches = this.countKeywordMatches(contentLower, BACKEND_KEYWORDS);
+        // Check file path patterns
+        const frontendPathMatches = this.countPathPatternMatches(storyContent, FRONTEND_PATH_PATTERNS);
+        const backendPathMatches = this.countPathPatternMatches(storyContent, BACKEND_PATH_PATTERNS);
+        // Calculate weighted scores (keywords count more than paths)
+        const frontendScore = frontendMatches.count * 2 + frontendPathMatches.count;
+        const backendScore = backendMatches.count * 2 + backendPathMatches.count;
+        this.logger.debug({
+            backendScore,
+            frontendScore,
+        }, 'Story type detection scores');
+        // Determine type based on scores
+        let type;
+        let confidence;
+        let matchedKeywords;
+        if (frontendScore === 0 && backendScore === 0) {
+            // No clear indicators
+            type = 'unknown';
+            confidence = 0;
+            matchedKeywords = [];
+        }
+        else if (frontendScore > backendScore * 2) {
+            // Clearly frontend
+            type = 'frontend';
+            confidence = Math.min(frontendScore / 10, 1);
+            matchedKeywords = [...frontendMatches.keywords, ...frontendPathMatches.patterns];
+        }
+        else if (backendScore > frontendScore * 2) {
+            // Clearly backend
+            type = 'backend';
+            confidence = Math.min(backendScore / 10, 1);
+            matchedKeywords = [...backendMatches.keywords, ...backendPathMatches.patterns];
+        }
+        else {
+            // Mixed signals - likely full-stack
+            type = 'fullstack';
+            confidence = Math.min((frontendScore + backendScore) / 15, 1);
+            matchedKeywords = [
+                ...frontendMatches.keywords,
+                ...backendMatches.keywords,
+                ...frontendPathMatches.patterns,
+                ...backendPathMatches.patterns,
+            ];
+        }
+        this.logger.info({
+            confidence,
+            matchedCount: matchedKeywords.length,
+            type,
+        }, 'Story type detected');
+        return {
+            confidence,
+            matchedKeywords,
+            type,
+        };
+    }
+    /**
+     * Get documentation references for a story type
+     *
+     * Returns the appropriate documentation file paths based on the detected story type.
+     * Saves tokens by only including relevant documentation.
+     *
+     * @param storyType - Detected story type
+     * @returns Array of documentation file paths to include
+     */
+    getDocumentationReferences(storyType) {
+        const docs = {
+            backend: [
+                'docs/api/src/services/service-style-typescript.md',
+                'docs/api/src/handlers/handlers-guide-typescript.md',
+                'docs/api/dynamodb-tables.md',
+                'docs/api/multitenancy-guide.md',
+            ],
+            frontend: ['docs/frontend-tenant-and-amplify-guide.md', 'docs/api/multitenancy-guide.md'],
+        };
+        switch (storyType) {
+            case 'backend': {
+                this.logger.debug('Returning backend documentation references');
+                return docs.backend;
+            }
+            case 'frontend': {
+                this.logger.debug('Returning frontend documentation references');
+                return docs.frontend;
+            }
+            case 'fullstack': {
+                this.logger.debug('Returning full-stack documentation references (frontend + backend)');
+                return [...docs.frontend, ...docs.backend];
+            }
+            default: {
+                this.logger.debug('No documentation references for unknown story type');
+                return [];
+            }
+        }
+    }
+    /**
+     * Count keyword matches in content
+     * @private
+     */
+    countKeywordMatches(content, keywords) {
+        const matched = [];
+        for (const keyword of keywords) {
+            if (content.includes(keyword)) {
+                matched.push(keyword);
+            }
+        }
+        return { count: matched.length, keywords: matched };
+    }
+    /**
+     * Count file path pattern matches
+     * @private
+     */
+    countPathPatternMatches(content, patterns) {
+        const matched = [];
+        for (const pattern of patterns) {
+            if (pattern.test(content)) {
+                matched.push(pattern.source);
+            }
+        }
+        return { count: matched.length, patterns: matched };
+    }
+}

package/dist/services/orchestration/task-decomposition-service.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TaskDecompositionService
+ *
+ * Decomposes large goals into executable task graphs with dependency management.
+ * Leverages Claude AI to intelligently break down complex objectives into
+ * small, actionable tasks with proper sequencing and parallelization.
+ */
+import type pino from 'pino';
+import type { DecomposeOptions, TaskGraph } from '../../types/task-graph.js';
+import type { AIProviderRunner } from '../agents/agent-runner.js';
+import type { FileManager } from '../file-system/file-manager.js';
+import type { GlobMatcher } from '../file-system/glob-matcher.js';
+/**
+ * Service for decomposing goals into task graphs
+ */
+export declare class TaskDecompositionService {
+    private readonly agentRunner;
+    private readonly fileManager;
+    private readonly globMatcher;
+    private readonly logger;
+    constructor(agentRunner: AIProviderRunner, fileManager: FileManager, globMatcher: GlobMatcher, logger: pino.Logger);
+    /**
+     * Decompose a goal into an executable task graph
+     *
+     * @param options - Decomposition options including goal, context, and mode
+     * @param sessionDir - Directory where session outputs will be stored
+     * @returns Complete task graph with dependencies
+     */
+    decomposeGoal(options: DecomposeOptions, sessionDir: string): Promise<TaskGraph>;
+    /**
+     * Build the decomposition prompt for Claude
+     */
+    private buildDecompositionPrompt;
+    /**
+     * Build execution layers using topological sort (Kahn's algorithm)
+     * Each layer contains tasks that can run in parallel
+     */
+    private buildExecutionLayers;
+    /**
+     * Detect circular dependencies using DFS
+     */
+    private detectCircularDependencies;
+    /**
+     * Extract YAML content from output (handles markdown code fences)
+     */
+    private extractYaml;
+    /**
+     * Gather target files using glob pattern
+     */
+    private gatherTargetFiles;
+    /**
+     * Generate unique session ID
+     */
+    private generateSessionId;
+    /**
+     * Parse Claude's YAML output into a structured TaskGraph
+     */
+    private parseTaskGraph;
+    /**
+     * Validate YAML and ask Claude to fix it if invalid
+     */
+    private validateAndFixYaml;
+    /**
+     * Validate task graph for common errors
+     */
+    private validateTaskGraph;
+}