@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/scaffolding/file-scaffolder.d.ts

@@ -0,0 +1,94 @@
+/**
+ * File Scaffolder Service
+ *
+ * Creates scaffolded markdown files for epics and stories with pre-populated
+ * metadata headers and empty content sections following template structure.
+ *
+ * @example
+ * ```typescript
+ * const scaffolder = new FileScaffolder(logger)
+ * const epicContent = scaffolder.scaffoldEpic({
+ *   epicNumber: 1,
+ *   epicTitle: 'Foundation Setup',
+ *   prefix: 'SIGN-TEMPLATES'
+ * })
+ * ```
+ */
+import type pino from 'pino';
+/**
+ * Epic scaffolding data
+ */
+export interface EpicScaffoldData {
+    /**
+     * Epic number (1, 2, 3, etc.)
+     */
+    epicNumber: number;
+    /**
+     * Epic title
+     */
+    epicTitle: string;
+    /**
+     * Project prefix (e.g., 'SIGN-TEMPLATES', 'USER-GROUPS')
+     */
+    prefix: string;
+}
+/**
+ * Story scaffolding data
+ */
+export interface StoryScaffoldData {
+    /**
+     * Epic number
+     */
+    epicNumber: number;
+    /**
+     * Story number within epic
+     */
+    storyNumber: number;
+    /**
+     * Story title
+     */
+    storyTitle: string;
+}
+/**
+ * File Scaffolder Service
+ *
+ * Generates structured markdown files with populated metadata sections
+ * and empty content sections ready for AI agent population.
+ */
+export declare class FileScaffolder {
+    private readonly logger;
+    /**
+     * Create a new FileScaffolder instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Scaffold an epic markdown file
+     *
+     * Creates a structured epic file with:
+     * - Populated metadata: Epic ID, Status (Draft), Creation Date
+     * - Empty content sections: Epic Goal, Description, Stories, etc.
+     *
+     * @param data - Epic scaffolding data
+     * @returns Scaffolded epic markdown content
+     */
+    scaffoldEpic(data: EpicScaffoldData): string;
+    /**
+     * Scaffold a story markdown file
+     *
+     * Creates a structured story file with:
+     * - Populated metadata: Status (Draft)
+     * - Empty content sections: Story, Acceptance Criteria, Tasks, etc.
+     *
+     * @param data - Story scaffolding data
+     * @returns Scaffolded story markdown content
+     */
+    scaffoldStory(data: StoryScaffoldData): string;
+    /**
+     * Get current date in YYYY-MM-DD format
+     *
+     * @returns Current date string
+     */
+    private getCurrentDate;
+}

package/dist/services/scaffolding/file-scaffolder.js

@@ -0,0 +1,314 @@
+/**
+ * File Scaffolder Service
+ *
+ * Creates scaffolded markdown files for epics and stories with pre-populated
+ * metadata headers and empty content sections following template structure.
+ *
+ * @example
+ * ```typescript
+ * const scaffolder = new FileScaffolder(logger)
+ * const epicContent = scaffolder.scaffoldEpic({
+ *   epicNumber: 1,
+ *   epicTitle: 'Foundation Setup',
+ *   prefix: 'SIGN-TEMPLATES'
+ * })
+ * ```
+ */
+/**
+ * File Scaffolder Service
+ *
+ * Generates structured markdown files with populated metadata sections
+ * and empty content sections ready for AI agent population.
+ */
+export class FileScaffolder {
+    logger;
+    /**
+     * Create a new FileScaffolder instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Scaffold an epic markdown file
+     *
+     * Creates a structured epic file with:
+     * - Populated metadata: Epic ID, Status (Draft), Creation Date
+     * - Empty content sections: Epic Goal, Description, Stories, etc.
+     *
+     * @param data - Epic scaffolding data
+     * @returns Scaffolded epic markdown content
+     */
+    scaffoldEpic(data) {
+        const epicId = `${data.prefix}-EPIC-${data.epicNumber}`;
+        const currentDate = this.getCurrentDate();
+        this.logger.info({
+            epicId,
+            epicNumber: data.epicNumber,
+            epicTitle: data.epicTitle,
+        }, 'Scaffolding epic file');
+        // Hardcoded epic scaffold following epic-tmpl.yaml structure
+        const content = `# Epic ${data.epicNumber}: ${data.epicTitle}
+
+<!-- Powered by BMAD™ Core -->
+
+## Epic Header
+
+**Epic ID:** ${epicId}
+**Epic Type:** _[To be determined by sm agent]_
+**Status:** Draft
+**Priority:** _[To be determined by sm agent]_
+**Created:** ${currentDate}
+
+---
+
+## Epic Goal
+
+_[AI Agent will populate: 2-3 sentences describing what this epic will accomplish and the end state it will deliver]_
+
+---
+
+## Epic Description
+
+### Existing System Context
+
+_[AI Agent will populate if Brownfield Enhancement]_
+
+**Current relevant functionality:**
+
+**Technology stack:**
+
+**Integration points:**
+
+### Enhancement Details
+
+#### What's Being Added/Changed
+
+_[AI Agent will populate: Specific deliverables with file locations]_
+
+#### How It Integrates
+
+_[AI Agent will populate: Integration approach and patterns]_
+
+#### Success Criteria
+
+_[AI Agent will populate: Measurable outcomes defining "done"]_
+
+---
+
+## Stories
+
+_[AI Agent will populate: List of stories with descriptions and key tasks]_
+
+---
+
+## Compatibility Requirements
+
+_[AI Agent will populate: Backward compatibility checklist]_
+
+- [ ] Existing APIs remain unchanged (or document breaking changes)
+- [ ] Database schema changes are backward compatible
+- [ ] UI changes follow existing patterns
+- [ ] Performance impact is minimal
+- [ ] No regression in existing functionality
+
+---
+
+## Risk Mitigation
+
+### Primary Risk
+
+_[AI Agent will populate]_
+
+### Mitigation
+
+_[AI Agent will populate: Specific actions to prevent or reduce risk]_
+
+### Rollback Plan
+
+_[AI Agent will populate: Step-by-step rollback procedure]_
+
+---
+
+## Definition of Done
+
+- [ ] All stories completed with acceptance criteria met
+- [ ] Unit test coverage ≥ 80% for new code
+- [ ] Integration tests verify end-to-end flows
+- [ ] TypeScript compilation passes with strict mode
+- [ ] Code follows project style guides
+- [ ] Documentation updated appropriately
+- [ ] No regression in existing features verified
+- [ ] Performance targets met
+
+---
+
+## Validation Checklist
+
+### Scope Validation
+
+- [ ] Epic contains appropriate number of stories (1-10)
+- [ ] No major architectural changes (or documented if required)
+- [ ] Enhancement follows existing patterns where applicable
+- [ ] Integration complexity is manageable
+
+### Risk Assessment
+
+- [ ] Risk to existing system is acceptable
+- [ ] Rollback plan is feasible
+- [ ] Testing approach covers critical paths
+- [ ] Team has sufficient knowledge/expertise
+
+### Completeness Check
+
+- [ ] Epic goal is clear and achievable
+- [ ] Stories are properly scoped and sequenced
+- [ ] Success criteria are measurable
+- [ ] Dependencies are identified
+
+---
+
+## Technical Implementation Notes
+
+_[AI Agent will populate if needed: Key integration patterns, architecture decisions, file locations, testing strategy]_
+
+---
+
+## Story Manager Handoff
+
+_[AI Agent will populate: Handoff message to Story Manager with context and requirements]_
+
+---
+
+## Change Log
+
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| ${currentDate} | 1.0 | Epic created | AI Agent |
+`;
+        this.logger.debug({ epicId, length: content.length }, 'Epic scaffold generated');
+        return content;
+    }
+    /**
+     * Scaffold a story markdown file
+     *
+     * Creates a structured story file with:
+     * - Populated metadata: Status (Draft)
+     * - Empty content sections: Story, Acceptance Criteria, Tasks, etc.
+     *
+     * @param data - Story scaffolding data
+     * @returns Scaffolded story markdown content
+     */
+    scaffoldStory(data) {
+        const storyId = `${data.epicNumber}.${data.storyNumber}`;
+        const currentDate = this.getCurrentDate();
+        this.logger.info({
+            storyId,
+            storyTitle: data.storyTitle,
+        }, 'Scaffolding story file');
+        // Hardcoded story scaffold following story-tmpl.yaml structure
+        const content = `# Story ${storyId}: ${data.storyTitle}
+
+<!-- Powered by BMAD™ Core -->
+
+## Status
+
+Draft
+
+---
+
+## Story
+
+**As a** _[AI Agent will populate]_,
+**I want** _[AI Agent will populate]_,
+**so that** _[AI Agent will populate]_
+
+---
+
+## Acceptance Criteria
+
+_[AI Agent will populate: Numbered list copied from epic]_
+
+1. _[Criterion 1]_
+2. _[Criterion 2]_
+3. _[Criterion 3]_
+
+---
+
+## Tasks / Subtasks
+
+_[AI Agent will populate: Break down into specific tasks with subtasks]_
+
+- [ ] Task 1 (AC: #)
+  - [ ] Subtask 1.1
+  - [ ] Subtask 1.2
+- [ ] Task 2 (AC: #)
+  - [ ] Subtask 2.1
+- [ ] Task 3 (AC: #)
+  - [ ] Subtask 3.1
+
+---
+
+## Dev Notes
+
+_[AI Agent will populate: Relevant architecture info, source tree context, and previous story notes]_
+
+### Testing
+
+_[AI Agent will populate: Testing standards, file locations, frameworks, patterns]_
+
+- Test file location:
+- Test standards:
+- Testing frameworks:
+- Specific requirements:
+
+---
+
+## Change Log
+
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| ${currentDate} | 1.0 | Story created | AI Agent |
+
+---
+
+## Dev Agent Record
+
+_[This section will be populated by the development agent during implementation]_
+
+### Agent Model Used
+
+_[AI Agent will record model and version]_
+
+### Debug Log References
+
+_[AI Agent will record debug log references]_
+
+### Completion Notes List
+
+_[AI Agent will record completion notes and issues encountered]_
+
+### File List
+
+_[AI Agent will list all files created, modified, or affected]_
+
+---
+
+## QA Results
+
+_[This section will be populated by QA Agent after review]_
+`;
+        this.logger.debug({ length: content.length, storyId }, 'Story scaffold generated');
+        return content;
+    }
+    /**
+     * Get current date in YYYY-MM-DD format
+     *
+     * @returns Current date string
+     */
+    getCurrentDate() {
+        const now = new Date();
+        return now.toISOString().split('T')[0];
+    }
+}

package/dist/services/validation/config-validator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ConfigValidator Service
+ *
+ * Validates configuration files against schemas using Zod.
+ * Ensures configuration has all required fields with correct types and that
+ * referenced directories exist.
+ */
+import type pino from 'pino';
+import { z } from 'zod';
+import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * Zod schema for core configuration
+ *
+ * Defines the expected structure of .bmad-core/core-config.yaml
+ * with all required fields for the BMAD Orchestrator CLI.
+ */
+declare const configSchema: z.ZodObject<{
+    devStoryLocation: z.ZodString;
+    prd: z.ZodOptional<z.ZodObject<{
+        prdFile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    qa: z.ZodOptional<z.ZodObject<{
+        qaLocation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Inferred TypeScript type from Zod schema
+ */
+export type CoreConfig = z.infer<typeof configSchema>;
+/**
+ * ConfigValidator service validates configuration files against schemas
+ *
+ * Uses Zod for schema validation and provides clear, actionable error messages
+ * when validation fails. Also validates that referenced directories exist.
+ */
+export declare class ConfigValidator {
+    /**
+     * FileManager instance for directory existence checks
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance for validation operations
+     */
+    private readonly logger;
+    /**
+     * Create a new ConfigValidator instance
+     *
+     * @param fileManager - FileManager instance for file system operations
+     * @param logger - Pino logger instance for logging validation operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:validation' })
+     * const fileManager = new FileManager(logger)
+     * const validator = new ConfigValidator(fileManager, logger)
+     */
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Validate configuration object against schema
+     *
+     * Validates that:
+     * 1. All required fields are present
+     * 2. All fields have correct types
+     * 3. Referenced directories exist
+     *
+     * @param config - Unknown configuration object to validate
+     * @returns Validated CoreConfig object
+     * @throws {ValidationError} If validation fails with detailed error messages
+     * @example
+     * const config = { epicDir: 'docs/epics', storyDir: 'docs/stories', ... }
+     * const validConfig = validator.validate(config)
+     */
+    validate(config: unknown): Promise<CoreConfig>;
+    /**
+     * Get custom error message and helpful suggestion based on Zod validation error
+     *
+     * @param error - Zod issue from validation failure
+     * @param config - The configuration object being validated
+     * @returns Object with error message and suggestion
+     */
+    private getErrorMessageAndSuggestion;
+    /**
+     * Validate that all directory paths in config exist
+     *
+     * @param config - Validated configuration object
+     * @throws {ValidationError} If any directory does not exist
+     */
+    private validateDirectories;
+}
+export {};

package/dist/services/validation/config-validator.js

@@ -0,0 +1,167 @@
+/**
+ * ConfigValidator Service
+ *
+ * Validates configuration files against schemas using Zod.
+ * Ensures configuration has all required fields with correct types and that
+ * referenced directories exist.
+ */
+import { z } from 'zod';
+import { ValidationError } from '../../utils/errors.js';
+/**
+ * Zod schema for core configuration
+ *
+ * Defines the expected structure of .bmad-core/core-config.yaml
+ * with all required fields for the BMAD Orchestrator CLI.
+ */
+const configSchema = z.object({
+    devStoryLocation: z.string().min(1, { message: 'Story directory path (devStoryLocation) is required' }),
+    prd: z
+        .object({
+        prdFile: z.string().optional(),
+    })
+        .optional(),
+    qa: z
+        .object({
+        qaLocation: z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * ConfigValidator service validates configuration files against schemas
+ *
+ * Uses Zod for schema validation and provides clear, actionable error messages
+ * when validation fails. Also validates that referenced directories exist.
+ */
+export class ConfigValidator {
+    /**
+     * FileManager instance for directory existence checks
+     */
+    fileManager;
+    /**
+     * Logger instance for validation operations
+     */
+    logger;
+    /**
+     * Create a new ConfigValidator instance
+     *
+     * @param fileManager - FileManager instance for file system operations
+     * @param logger - Pino logger instance for logging validation operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:validation' })
+     * const fileManager = new FileManager(logger)
+     * const validator = new ConfigValidator(fileManager, logger)
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Validate configuration object against schema
+     *
+     * Validates that:
+     * 1. All required fields are present
+     * 2. All fields have correct types
+     * 3. Referenced directories exist
+     *
+     * @param config - Unknown configuration object to validate
+     * @returns Validated CoreConfig object
+     * @throws {ValidationError} If validation fails with detailed error messages
+     * @example
+     * const config = { epicDir: 'docs/epics', storyDir: 'docs/stories', ... }
+     * const validConfig = validator.validate(config)
+     */
+    async validate(config) {
+        this.logger.info('Validating configuration');
+        // Step 1: Validate schema (required fields, types)
+        const result = configSchema.safeParse(config);
+        if (!result.success) {
+            const firstError = result.error.issues[0];
+            const fieldPath = firstError.path.join('.');
+            // Get custom error message and suggestion
+            const { message: errorMessage, suggestion } = this.getErrorMessageAndSuggestion(firstError, config);
+            const fullMessage = `Configuration validation failed: ${errorMessage}. ${suggestion}`;
+            this.logger.error({ field: fieldPath }, 'Configuration validation failed: %s', errorMessage);
+            throw new ValidationError(fullMessage, {
+                field: fieldPath,
+                received: config?.[firstError.path[0]],
+            });
+        }
+        const validConfig = result.data;
+        // Step 2: Validate directory existence
+        await this.validateDirectories(validConfig);
+        this.logger.info('Configuration validated successfully');
+        return validConfig;
+    }
+    /**
+     * Get custom error message and helpful suggestion based on Zod validation error
+     *
+     * @param error - Zod issue from validation failure
+     * @param config - The configuration object being validated
+     * @returns Object with error message and suggestion
+     */
+    getErrorMessageAndSuggestion(error, config) {
+        const fieldName = error.path[0];
+        const examples = {
+            devStoryLocation: 'docs/stories',
+            'prd.prdFile': 'docs/prd.md',
+            'qa.qaLocation': 'docs/qa',
+        };
+        const fieldDisplayNames = {
+            devStoryLocation: 'Story directory path (devStoryLocation)',
+            'prd.prdFile': 'PRD file path (prd.prdFile)',
+            'qa.qaLocation': 'QA location path (qa.qaLocation)',
+        };
+        const example = examples[fieldName] || 'path/to/directory';
+        const displayName = fieldDisplayNames[fieldName] || fieldName;
+        // Missing field or empty string
+        if (error.code === 'too_small') {
+            return {
+                message: `${displayName} is required`,
+                suggestion: `Add this field to .bmad-core/core-config.yaml with a valid path (e.g., "${example}").`,
+            };
+        }
+        // Wrong type or missing field
+        if (error.code === 'invalid_type') {
+            const invalidTypeError = error;
+            // Check if field exists in config (to differentiate missing vs wrong type)
+            const configObj = config;
+            const fieldValue = configObj?.[fieldName];
+            const fieldIsMissing = fieldValue === undefined || fieldValue === null;
+            // If field is missing, provide custom message
+            if (fieldIsMissing) {
+                return {
+                    message: `${displayName} is required`,
+                    suggestion: `Add this field to .bmad-core/core-config.yaml with a valid path (e.g., "${example}").`,
+                };
+            }
+            // Wrong type provided - use Zod's message which includes the types
+            return {
+                message: error.message, // e.g., "Invalid input: expected string, received number"
+                suggestion: `Update the value in .bmad-core/core-config.yaml to a valid ${invalidTypeError.expected}.`,
+            };
+        }
+        // Generic fallback
+        return {
+            message: error.message,
+            suggestion: `Check the value for '${fieldName}' in .bmad-core/core-config.yaml.`,
+        };
+    }
+    /**
+     * Validate that all directory paths in config exist
+     *
+     * @param config - Validated configuration object
+     * @throws {ValidationError} If any directory does not exist
+     */
+    async validateDirectories(config) {
+        // Validate story directory exists
+        const storyDir = config.devStoryLocation;
+        const exists = await this.fileManager.fileExists(storyDir);
+        if (!exists) {
+            const message = `Configuration validation failed: Story directory '${storyDir}' does not exist. ` +
+                `Create the directory with 'mkdir -p ${storyDir}' or update 'devStoryLocation' in .bmad-core/core-config.yaml.`;
+            this.logger.error({ field: 'devStoryLocation', path: storyDir }, 'Directory validation failed: %s', message);
+            throw new ValidationError(message, { field: 'devStoryLocation', path: storyDir });
+        }
+        this.logger.debug({ field: 'devStoryLocation' }, 'Directory exists: %s', storyDir);
+    }
+}