MAINFRAME TERMINAL #113

TYPES DOCUMENTATION

File: workflow-options.md

TECHNICAL BULLETIN NO. 006

WORKFLOW OPTIONS - WORKFLOW AUTOMATION CONFIGURATION SYSTEM

DOCUMENT ID: task-o-matic-workflow-options-v1
CLEARANCE: All Personnel

MANDATORY COMPLIANCE: Yes

⚠️ CRITICAL SURVIVAL NOTICE

Citizen, ignore these workflow option types and your automation becomes a runaway train in the wasteland. Steps execute without control, AI configurations clash, and your workflow becomes a cascade of failed operations. This is your automation control tower.

TYPE SYSTEM ARCHITECTURE

The workflow options system provides comprehensive automation configuration for the entire task-o-matic workflow process. It uses interface composition and granular control to enable both fully automated and semi-automated workflow execution. The architecture supports:

  • Step-by-Step Control: Fine-grained control over each workflow phase
  • AI Configuration: Per-step AI provider and model selection
  • Automation Levels: From fully manual to completely automated
  • Configuration Loading: Support for both inline and file-based configuration
  • Error Recovery: Robust error handling and retry mechanisms

This design enables predictable workflow automation while maintaining human oversight when needed.

COMPLETE TYPE DOCUMENTATION

#### WorkflowAutomationOptions Interface

export interface WorkflowAutomationOptions extends StreamingAIOptions {
  // Global workflow control
  skipAll?: boolean; // Skip all optional steps
  autoAccept?: boolean; // Auto-accept all AI suggestions
  configFile?: string; // Load options from JSON file

  // Step 1: Initialize
  skipInit?: boolean; // Skip initialization entirely
  projectName?: string; // Pre-set project name
  initMethod?: "quick" | "custom" | "ai"; // Initialization method
  projectDescription?: string; // For AI-assisted init
  useExistingConfig?: boolean; // Use existing config if found

  // AI Configuration (inherited from StreamingAIOptions)
  // aiProvider, aiModel, aiKey, aiProviderUrl, stream

  // Stack Configuration
  frontend?: string; // Frontend framework
  backend?: string; // Backend framework
  database?: string; // Database choice
  auth?: boolean; // Include authentication
  bootstrap?: boolean; // Bootstrap with Better-T-Stack
  includeDocs?: boolean; // Include documentation in new project

  // Step 2: Define PRD
  skipPrd?: boolean; // Skip PRD definition
  prdMethod?: "upload" | "manual" | "ai" | "skip"; // PRD creation method
  prdFile?: string; // Path to existing PRD file
  prdDescription?: string; // For AI-assisted PRD creation
  prdContent?: string; // Direct PRD content (for automation)
  prdMultiGeneration?: boolean; // Use multi-generation for PRD creation
  skipPrdMultiGeneration?: boolean; // Skip PRD multi-generation
  prdMultiGenerationModels?: string; // Comma-separated list of provider:model
  prdCombine?: boolean; // Combine multiple PRDs into master
  skipPrdCombine?: boolean; // Skip PRD combination
  prdCombineModel?: string; // Model to use for combining (provider:model)

  // Step 3: Refine PRD
  skipRefine?: boolean; // Skip PRD refinement
  refineMethod?: "manual" | "ai" | "skip"; // Refinement method
  refineFeedback?: string; // Feedback for AI refinement

  // Step 2.5: PRD Question/Refine (NEW)
  skipPrdQuestionRefine?: boolean; // Skip PRD question/refine step
  prdQuestionRefine?: boolean; // Use question-based PRD refinement
  prdAnswerMode?: "user" | "ai"; // Who answers questions: user or AI
  prdAnswerAiProvider?: string; // AI provider for answering (optional override)
  prdAnswerAiModel?: string; // AI model for answering (optional override)
  prdAnswerAiKey?: string; // AI API key for answering (optional override)
  prdAnswerAiProviderUrl?: string; // AI provider URL for answering (optional override)
  prdAnswerAiReasoning?: boolean; // Enable reasoning for AI answering model

  // Step 4: Generate Tasks
  skipGenerate?: boolean; // Skip task generation
  generateMethod?: "standard" | "ai"; // Generation method
  generateInstructions?: string; // Custom instructions for task generation

  // Step 5: Split Tasks
  skipSplit?: boolean; // Skip task splitting
  splitTasks?: string; // Comma-separated task IDs to split
  splitAll?: boolean; // Split all tasks
  splitMethod?: "interactive" | "standard" | "custom"; // Split method
  splitInstructions?: string; // Custom instructions for splitting
}

Purpose: Comprehensive options for workflow command automation

Inherited Properties: From StreamingAIOptions

  • aiProvider (Optional, string): AI provider name
  • aiModel (Optional, string): AI model name
  • aiKey (Optional, string): API authentication key
  • aiProviderUrl (Optional, string): Custom endpoint URL
  • stream (Optional, boolean): Enable streaming AI responses

Global Workflow Control Properties:

  • skipAll (Optional, boolean): Skip all optional steps and run with defaults
  • autoAccept (Optional, boolean): Automatically accept all AI suggestions without prompting
  • configFile (Optional, string): Path to JSON configuration file with workflow options

Step 1: Initialize Properties:

  • skipInit (Optional, boolean): Skip project initialization entirely
  • projectName (Optional, string): Pre-defined project name
  • initMethod (Optional, union): Initialization approach

- "quick": Use sensible defaults for rapid setup

- "custom": Interactive custom configuration

- "ai": AI-assisted project setup

  • projectDescription (Optional, string): Project description for AI-assisted initialization
  • useExistingConfig (Optional, boolean): Use existing configuration if found

Step 2: Define PRD Properties:

  • skipPrd (Optional, boolean): Skip PRD definition step
  • prdMethod (Optional, union): PRD creation approach

- "upload": Use existing PRD file

- "manual": Interactive PRD creation

- "ai": AI-generated PRD from description

- "skip": Skip PRD entirely

  • prdFile (Optional, string): Path to existing PRD file for upload method
  • prdDescription (Optional, string): Description for AI-generated PRD
  • prdContent (Optional, string): Direct PRD content for automation
  • prdMultiGeneration (Optional, boolean): Use multiple AI models for PRD generation
  • skipPrdMultiGeneration (Optional, boolean): Skip multi-generation step
  • prdMultiGenerationModels (Optional, string): Comma-separated provider:model combinations
  • prdCombine (Optional, boolean): Combine multiple PRDs into master document
  • skipPrdCombine (Optional, boolean): Skip PRD combination step
  • prdCombineModel (Optional, string): AI model for PRD combination (provider:model format)

Step 3: Refine PRD Properties:

  • skipRefine (Optional, boolean): Skip PRD refinement step
  • refineMethod (Optional, union): PRD refinement approach

- "manual": Manual PRD editing and improvement

- "ai": AI-assisted PRD refinement

- "skip": Skip refinement entirely

  • refineFeedback (Optional, string): Feedback for AI-driven refinement

Step 2.5: PRD Question/Refine Properties:

  • skipPrdQuestionRefine (Optional, boolean): Skip question-based PRD refinement
  • prdQuestionRefine (Optional, boolean): Enable question-based PRD refinement
  • prdAnswerMode (Optional, union): Who answers PRD questions

- "user": Human user answers questions

- "ai": AI model answers questions

  • prdAnswerAiProvider (Optional, string): AI provider for answering questions
  • prdAnswerAiModel (Optional, string): AI model for answering questions
  • prdAnswerAiKey (Optional, string): API key for answering AI
  • prdAnswerAiProviderUrl (Optional, string): Custom endpoint for answering AI
  • prdAnswerAiReasoning (Optional, boolean): Enable reasoning for answering AI model

Step 4: Generate Tasks Properties:

  • skipGenerate (Optional, boolean): Skip task generation step
  • generateMethod (Optional, union): Task generation approach

- "standard": Standard task extraction from PRD

- "ai": AI-enhanced task generation

  • generateInstructions (Optional, string): Custom instructions for task generation

Step 5: Split Tasks Properties:

  • skipSplit (Optional, boolean): Skip task splitting step
  • splitTasks (Optional, string): Comma-separated task IDs to split
  • splitAll (Optional, boolean): Split all generated tasks
  • splitMethod (Optional, union): Task splitting approach

- "interactive": Interactive task splitting with user confirmation

- "standard": Standard AI-powered task splitting

- "custom": Custom splitting with specific instructions

  • splitInstructions (Optional, string): Custom instructions for task splitting

Stack Configuration Properties:

  • frontend (Optional, string): Frontend framework selection
  • backend (Optional, string): Backend framework selection
  • database (Optional, string): Database selection
  • auth (Optional, boolean): Include authentication system
  • bootstrap (Optional, boolean): Use Better-T-Stack bootstrap process
  • includeDocs (Optional, boolean): Include documentation in new project

Usage Examples:

// Fully automated workflow
const fullyAutomated: WorkflowAutomationOptions = {
  skipAll: true,
  autoAccept: true,
  projectName: "E-commerce Platform",
  initMethod: "ai",
  prdMethod: "ai",
  prdDescription: "Complete e-commerce platform with user authentication and product catalog",
  generateMethod: "ai",
  splitMethod: "standard",
  splitAll: true,
  frontend: "next",
  backend: "hono",
  database: "postgres",
  auth: true,
  bootstrap: true,
  stream: true,
  aiProvider: "anthropic",
  aiModel: "claude-3.5-sonnet"
};

// Semi-automated with human oversight
const semiAutomated: WorkflowAutomationOptions = {
  autoAccept: false,
  projectName: "Mobile App",
  initMethod: "custom",
  prdMethod: "upload",
  prdFile: "./docs/PRD.md",
  prdQuestionRefine: true,
  prdAnswerMode: "user",
  generateMethod: "standard",
  splitTasks: "task-large-1,task-large-2",
  splitMethod: "interactive",
  aiProvider: "openrouter",
  stream: true
};

// Custom AI configuration per step
const customAIConfig: WorkflowAutomationOptions = {
  projectName: "AI Assistant",
  initMethod: "ai",
  prdMultiGeneration: true,
  prdMultiGenerationModels: "anthropic:claude-3.5-sonnet,openai:gpt-4o",
  prdCombine: true,
  prdCombineModel: "anthropic:claude-3.5-sonnet",
  generateMethod: "ai",
  generateInstructions: "Focus on technical implementation details and API design",
  splitMethod: "custom",
  splitInstructions: "Split tasks by technical components (frontend, backend, database)",
  prdAnswerAiProvider: "openrouter",
  prdAnswerAiModel: "anthropic/claude-3.5-sonnet",
  prdAnswerAiReasoning: true,
  aiProvider: "openrouter",
  aiModel: "anthropic/claude-3.5-sonnet"
};

// Configuration from file
const fileBasedConfig: WorkflowAutomationOptions = {
  configFile: "./workflow-config.json",
  // Other options will be loaded from file
};

// Minimal automation
const minimalAutomation: WorkflowAutomationOptions = {
  skipInit: true,
  skipPrd: true,
  skipRefine: true,
  skipGenerate: false,
  skipSplit: true,
  generateMethod: "standard",
  aiProvider: "openai",
  aiModel: "gpt-4"
};

FUNCTION DOCUMENTATION

No standalone functions in this module - this is a type definition file.

INTEGRATION PROTOCOLS

#### Workflow Command Integration

// commands/workflow.ts
import { WorkflowAutomationOptions } from '../types/workflow-options';
import { WorkflowService } from '../services/workflow';

export function createWorkflowCommand(): Command {
  return new Command('workflow')
    .description('Execute complete task-o-matic workflow')
    .option('--config-file <file>', 'Load configuration from JSON file')
    .option('--skip-all', 'Skip all optional steps')
    .option('--auto-accept', 'Auto-accept all AI suggestions')
    .option('--project-name <name>', 'Project name')
    .option('--init-method <method>', 'Initialization method (quick|custom|ai)')
    .option('--skip-init', 'Skip initialization')
    .option('--prd-method <method>', 'PRD method (upload|manual|ai|skip)')
    .option('--prd-file <file>', 'Path to PRD file')
    .option('--prd-description <desc>', 'PRD description for AI generation')
    .option('--prd-multi-generation', 'Use multi-generation for PRD')
    .option('--prd-multi-models <models>', 'Models for PRD multi-generation')
    .option('--prd-combine', 'Combine multiple PRDs')
    .option('--prd-combine-model <model>', 'Model for PRD combination')
    .option('--skip-refine', 'Skip PRD refinement')
    .option('--refine-method <method>', 'Refinement method (manual|ai|skip)')
    .option('--refine-feedback <feedback>', 'Feedback for PRD refinement')
    .option('--prd-question-refine', 'Use question-based PRD refinement')
    .option('--prd-answer-mode <mode>', 'Who answers PRD questions (user|ai)')
    .option('--prd-answer-ai-provider <provider>', 'AI provider for answering questions')
    .option('--prd-answer-ai-model <model>', 'AI model for answering questions')
    .option('--prd-answer-ai-key <key>', 'API key for answering AI')
    .option('--prd-answer-ai-url <url>', 'Custom endpoint for answering AI')
    .option('--prd-answer-ai-reasoning', 'Enable reasoning for answering AI')
    .option('--skip-generate', 'Skip task generation')
    .option('--generate-method <method>', 'Task generation method (standard|ai)')
    .option('--generate-instructions <instructions>', 'Custom instructions for task generation')
    .option('--skip-split', 'Skip task splitting')
    .option('--split-tasks <tasks>', 'Comma-separated task IDs to split')
    .option('--split-all', 'Split all tasks')
    .option('--split-method <method>', 'Split method (interactive|standard|custom)')
    .option('--split-instructions <instructions>', 'Custom instructions for splitting')
    .option('--frontend <framework>', 'Frontend framework')
    .option('--backend <framework>', 'Backend framework')
    .option('--database <db>', 'Database choice')
    .option('--auth', 'Include authentication')
    .option('--bootstrap', 'Bootstrap with Better-T-Stack')
    .option('--include-docs', 'Include documentation')
    .option('--stream', 'Stream AI output')
    .option('--ai-provider <provider>', 'AI provider')
    .option('--ai-model <model>', 'AI model')
    .option('--ai-key <key>', 'AI API key')
    .option('--ai-provider-url <url>', 'Custom AI provider URL')
    .action(async (options: WorkflowAutomationOptions) => {
      await handleWorkflowCommand(options);
    });
}

async function handleWorkflowCommand(options: WorkflowAutomationOptions): Promise<void> {
  try {
    const workflowService = new WorkflowService();
    
    // Load configuration from file if specified
    if (options.configFile) {
      const fileConfig = await loadWorkflowConfig(options.configFile);
      options = { ...options, ...fileConfig };
    }
    
    // Execute workflow with automation options
    const result = await workflowService.executeWorkflow(options);
    
    if (result.success) {
      console.log('✅ Workflow completed successfully!');
      console.log(`Project: ${result.projectName}`);
      console.log(`Tasks created: ${result.tasksCreated}`);
      console.log(`Duration: ${result.duration}ms`);
    } else {
      console.error('❌ Workflow failed:', result.error);
      process.exit(1);
    }
  } catch (error) {
    console.error('💥 Workflow execution failed:', error);
    process.exit(1);
  }
}

async function loadWorkflowConfig(configPath: string): Promise<Partial<WorkflowAutomationOptions>> {
  try {
    const configContent = await fs.readFile(configPath, 'utf-8');
    return JSON.parse(configContent);
  } catch (error) {
    console.error(`Failed to load workflow config from ${configPath}:`, error);
    return {};
  }
}

#### Service Layer Integration

// services/workflow.ts
import { WorkflowAutomationOptions } from '../types/workflow-options';
import { ProjectInitializer } from '../lib/project-initializer';
import { PRDService } from '../services/prd';
import { TaskService } from '../services/tasks';

export class WorkflowService {
  constructor(
    private projectInitializer: ProjectInitializer,
    private prdService: PRDService,
    private taskService: TaskService
  ) {}

  async executeWorkflow(options: WorkflowAutomationOptions): Promise<WorkflowResult> {
    const startTime = Date.now();
    
    try {
      // Step 1: Initialize
      if (!options.skipInit) {
        await this.executeInitialization(options);
      }
      
      // Step 2: Define PRD
      if (!options.skipPrd) {
        await this.executePRDDefinition(options);
      }
      
      // Step 2.5: PRD Question/Refine
      if (!options.skipPrdQuestionRefine && options.prdQuestionRefine) {
        await this.executePRDQuestionRefine(options);
      }
      
      // Step 3: Refine PRD
      if (!options.skipRefine) {
        await this.executePRDRefinement(options);
      }
      
      // Step 4: Generate Tasks
      if (!options.skipGenerate) {
        await this.executeTaskGeneration(options);
      }
      
      // Step 5: Split Tasks
      if (!options.skipSplit) {
        await this.executeTaskSplitting(options);
      }
      
      const duration = Date.now() - startTime;
      
      return {
        success: true,
        projectName: options.projectName || 'Untitled Project',
        tasksCreated: this.getTasksCreatedCount(),
        duration
      };
      
    } catch (error) {
      const duration = Date.now() - startTime;
      
      return {
        success: false,
        error: error.message,
        duration
      };
    }
  }

  private async executeInitialization(options: WorkflowAutomationOptions): Promise<void> {
    console.log('🚀 Step 1: Initializing project...');
    
    const initOptions = {
      projectName: options.projectName,
      method: options.initMethod || 'quick',
      projectDescription: options.projectDescription,
      useExistingConfig: options.useExistingConfig,
      frontend: options.frontend,
      backend: options.backend,
      database: options.database,
      auth: options.auth,
      bootstrap: options.bootstrap,
      includeDocs: options.includeDocs,
      aiProvider: options.aiProvider,
      aiModel: options.aiModel,
      aiKey: options.aiKey,
      aiProviderUrl: options.aiProviderUrl,
      stream: options.stream
    };
    
    await this.projectInitializer.initialize(initOptions);
  }

  private async executePRDDefinition(options: WorkflowAutomationOptions): Promise<void> {
    console.log('📝 Step 2: Defining PRD...');
    
    switch (options.prdMethod) {
      case 'upload':
        if (!options.prdFile) {
          throw new Error('PRD file path required for upload method');
        }
        await this.prdService.uploadPRD(options.prdFile);
        break;
        
      case 'manual':
        await this.prdService.createManualPRD();
        break;
        
      case 'ai':
        if (!options.prdDescription) {
          throw new Error('PRD description required for AI generation method');
        }
        await this.prdService.generatePRD(options.prdDescription, {
          aiProvider: options.aiProvider,
          aiModel: options.aiModel,
          stream: options.stream
        });
        break;
        
      case 'skip':
        console.log('⏭️ Skipping PRD definition');
        break;
        
      default:
        throw new Error(`Invalid PRD method: ${options.prdMethod}`);
    }
  }

  private async executePRDQuestionRefine(options: WorkflowAutomationOptions): Promise<void> {
    console.log('❓ Step 2.5: PRD Question/Refine...');
    
    const prdContent = await this.prdService.getCurrentPRDContent();
    
    if (options.prdAnswerMode === 'ai') {
      // AI answers questions about PRD
      const answerAIConfig = {
        provider: options.prdAnswerAiProvider || options.aiProvider,
        model: options.prdAnswerAiModel || options.aiModel,
        apiKey: options.prdAnswerAiKey || options.aiKey,
        baseURL: options.prdAnswerAiProviderUrl || options.aiProviderUrl,
        reasoning: options.prdAnswerAiReasoning
      };
      
      await this.prdService.questionAndRefinePRD(prdContent, {
        answerMode: 'ai',
        answerAIConfig
      });
    } else {
      // User answers questions about PRD
      await this.prdService.questionAndRefinePRD(prdContent, {
        answerMode: 'user'
      });
    }
  }

  private async executePRDRefinement(options: WorkflowAutomationOptions): Promise<void> {
    console.log('✏️ Step 3: Refining PRD...');
    
    switch (options.refineMethod) {
      case 'manual':
        await this.prdService.manualRefinePRD();
        break;
        
      case 'ai':
        if (!options.refineFeedback) {
          throw new Error('Refinement feedback required for AI refinement method');
        }
        await this.prdService.aiRefinePRD(options.refineFeedback, {
          aiProvider: options.aiProvider,
          aiModel: options.aiModel,
          stream: options.stream
        });
        break;
        
      case 'skip':
        console.log('⏭️ Skipping PRD refinement');
        break;
        
      default:
        throw new Error(`Invalid refinement method: ${options.refineMethod}`);
    }
  }

  private async executeTaskGeneration(options: WorkflowAutomationOptions): Promise<void> {
    console.log('📋 Step 4: Generating tasks...');
    
    switch (options.generateMethod) {
      case 'standard':
        await this.taskService.generateTasksFromPRD({
          aiProvider: options.aiProvider,
          aiModel: options.aiModel,
          stream: options.stream
        });
        break;
        
      case 'ai':
        if (!options.generateInstructions) {
          throw new Error('Generation instructions required for AI generation method');
        }
        await this.taskService.generateTasksFromPRD({
          aiProvider: options.aiProvider,
          aiModel: options.aiModel,
          stream: options.stream,
          customInstructions: options.generateInstructions
        });
        break;
        
      default:
        throw new Error(`Invalid generation method: ${options.generateMethod}`);
    }
  }

  private async executeTaskSplitting(options: WorkflowAutomationOptions): Promise<void> {
    console.log('🔧 Step 5: Splitting tasks...');
    
    // Determine which tasks to split
    let tasksToSplit: string[] = [];
    
    if (options.splitAll) {
      const allTasks = await this.taskService.listTasks();
      tasksToSplit = allTasks.map(task => task.id);
    } else if (options.splitTasks) {
      tasksToSplit = options.splitTasks.split(',').map(id => id.trim());
    }
    
    if (tasksToSplit.length === 0) {
      console.log('⏭️ No tasks to split');
      return;
    }
    
    switch (options.splitMethod) {
      case 'interactive':
        for (const taskId of tasksToSplit) {
          await this.taskService.splitTaskInteractive(taskId, {
            aiProvider: options.aiProvider,
            aiModel: options.aiModel,
            stream: options.stream
          });
        }
        break;
        
      case 'standard':
        for (const taskId of tasksToSplit) {
          await this.taskService.splitTask(taskId, {
            aiProvider: options.aiProvider,
            aiModel: options.aiModel,
            stream: options.stream
          });
        }
        break;
        
      case 'custom':
        if (!options.splitInstructions) {
          throw new Error('Split instructions required for custom splitting method');
        }
        for (const taskId of tasksToSplit) {
          await this.taskService.splitTask(taskId, {
            aiProvider: options.aiProvider,
            aiModel: options.aiModel,
            stream: options.stream,
            customInstructions: options.splitInstructions
          });
        }
        break;
        
      default:
        throw new Error(`Invalid splitting method: ${options.splitMethod}`);
    }
  }

  private getTasksCreatedCount(): number {
    // Implementation would count tasks created during workflow
    return 0; // Placeholder
  }
}

#### Configuration File Support

// utils/workflow-config-loader.ts
import { WorkflowAutomationOptions } from '../types/workflow-options';
import { loadAIConfig } from './ai-config-builder';

export interface WorkflowConfigFile {
  version?: string;
  workflow?: Partial<WorkflowAutomationOptions>;
  profiles?: Record<string, Partial<WorkflowAutomationOptions>>;
}

export class WorkflowConfigLoader {
  static async loadFromFile(configPath: string): Promise<WorkflowConfigFile> {
    try {
      const configContent = await fs.readFile(configPath, 'utf-8');
      const config = JSON.parse(configContent) as WorkflowConfigFile;
      
      // Validate configuration
      WorkflowConfigLoader.validateConfig(config);
      
      return config;
    } catch (error) {
      throw new Error(`Failed to load workflow config from ${configPath}: ${error.message}`);
    }
  }

  static async loadFromProfile(configPath: string, profileName: string): Promise<WorkflowAutomationOptions> {
    const config = await this.loadFromFile(configPath);
    
    if (!config.profiles || !config.profiles[profileName]) {
      throw new Error(`Profile '${profileName}' not found in configuration`);
    }
    
    return {
      ...config.workflow,
      ...config.profiles[profileName]
    };
  }

  static validateConfig(config: WorkflowConfigFile): void {
    if (!config.workflow) {
      throw new Error('Workflow configuration is required');
    }
    
    // Validate AI configuration
    if (config.workflow.aiProvider && !config.workflow.aiModel) {
      throw new Error('AI model is required when AI provider is specified');
    }
    
    // Validate PRD method combinations
    if (config.workflow.prdMethod === 'upload' && !config.workflow.prdFile) {
      throw new Error('PRD file is required when using upload method');
    }
    
    if (config.workflow.prdMethod === 'ai' && !config.workflow.prdDescription) {
      throw new Error('PRD description is required when using AI generation method');
    }
    
    // Validate refinement method combinations
    if (config.workflow.refineMethod === 'ai' && !config.workflow.refineFeedback) {
      throw new Error('Refinement feedback is required when using AI refinement method');
    }
    
    // Validate splitting method combinations
    if (config.workflow.splitMethod === 'custom' && !config.workflow.splitInstructions) {
      throw new Error('Split instructions are required when using custom splitting method');
    }
    
    // Validate question/refine combinations
    if (config.workflow.prdQuestionRefine && config.workflow.prdAnswerMode === 'ai') {
      if (!config.workflow.prdAnswerAiProvider || !config.workflow.prdAnswerAiModel) {
        throw new Error('AI provider and model are required when AI answers questions');
      }
    }
  }

  static createSampleConfig(): WorkflowConfigFile {
    return {
      version: "1.0.0",
      workflow: {
        projectName: "Sample Project",
        initMethod: "ai",
        prdMethod: "ai",
        prdDescription: "Sample project for demonstration",
        generateMethod: "ai",
        splitMethod: "standard",
        frontend: "next",
        backend: "hono",
        database: "postgres",
        auth: true,
        bootstrap: true,
        stream: true,
        autoAccept: false,
        aiProvider: "anthropic",
        aiModel: "claude-3.5-sonnet"
      },
      profiles: {
        "quick-start": {
          projectName: "Quick Start Project",
          skipAll: true,
          autoAccept: true,
          initMethod: "quick",
          prdMethod: "skip",
          generateMethod: "standard",
          splitMethod: "standard"
        },
        "custom-ai": {
          projectName: "Custom AI Project",
          initMethod: "ai",
          prdMultiGeneration: true,
          prdMultiGenerationModels: "anthropic:claude-3.5-sonnet,openai:gpt-4o",
          prdCombine: true,
          prdCombineModel: "anthropic:claude-3.5-sonnet",
          generateInstructions: "Focus on API design and microservices architecture",
          splitInstructions: "Split by API endpoints and data models"
        }
      }
    };
  }

  static async saveToFile(config: WorkflowConfigFile, configPath: string): Promise<void> {
    try {
      const configContent = JSON.stringify(config, null, 2);
      await fs.writeFile(configPath, configContent, 'utf-8');
      console.log(`✅ Workflow configuration saved to ${configPath}`);
    } catch (error) {
      throw new Error(`Failed to save workflow config to ${configPath}: ${error.message}`);
    }
  }
}

SURVIVAL SCENARIOS

#### Scenario 1: Fully Automated E-commerce Platform Setup

// Complete automation for e-commerce platform
const ecommerceWorkflow: WorkflowAutomationOptions = {
  // Global automation
  skipAll: false,
  autoAccept: true,
  projectName: "ShopMaster E-commerce",
  
  // Step 1: AI-assisted initialization
  initMethod: "ai",
  projectDescription: "Complete e-commerce platform with user authentication, product catalog, shopping cart, order management, and admin dashboard",
  
  // Step 2: AI-generated PRD with multi-generation
  prdMethod: "ai",
  prdMultiGeneration: true,
  prdMultiGenerationModels: "anthropic:claude-3.5-sonnet,openai:gpt-4o",
  prdCombine: true,
  prdCombineModel: "anthropic:claude-3.5-sonnet",
  
  // Step 3: AI refinement with comprehensive feedback
  skipRefine: false,
  refineMethod: "ai",
  refineFeedback: "Add security requirements, performance metrics, scalability considerations, and detailed API specifications",
  
  // Step 4: AI-enhanced task generation
  skipGenerate: false,
  generateMethod: "ai",
  generateInstructions: "Focus on microservices architecture, API-first design, comprehensive testing strategy, and DevOps automation",
  
  // Step 5: Standard AI splitting for large tasks
  skipSplit: false,
  splitAll: true,
  splitMethod: "standard",
  
  // Stack configuration
  frontend: "next",
  backend: "hono",
  database: "postgres",
  auth: true,
  bootstrap: true,
  includeDocs: true,
  
  // AI configuration
  stream: true,
  aiProvider: "anthropic",
  aiModel: "claude-3.5-sonnet"
};

// Execute workflow
await executeWorkflow(ecommerceWorkflow);

// Expected output:
// 🚀 Step 1: Initializing project...
// ✅ Project initialized: ShopMaster E-commerce
// 📝 Step 2: Defining PRD...
// 🤖 Generating PRD with multiple models...
// 📋 Step 2.5: PRD Question/Refine...
// ❓ AI answering questions about PRD...
// ✏️ Step 3: Refining PRD...
// 📋 Step 4: Generating tasks...
// 🔧 Step 5: Splitting tasks...
// ✅ Workflow completed successfully!
// Project: ShopMaster E-commerce
// Tasks created: 47
// Duration: 4520000ms

#### Scenario 2: Semi-Automated Mobile App Development

// Semi-automated workflow with human oversight
const mobileAppWorkflow: WorkflowAutomationOptions = {
  // Human oversight required
  autoAccept: false,
  projectName: "Fitness Tracker Mobile App",
  
  // Step 1: Custom initialization with existing config
  initMethod: "custom",
  useExistingConfig: true,
  
  // Step 2: Manual PRD upload with question-based refinement
  prdMethod: "upload",
  prdFile: "./docs/mobile-app-PRD.md",
  skipPrdQuestionRefine: false,
  prdQuestionRefine: true,
  prdAnswerMode: "user",
  
  // Step 3: Manual refinement
  skipRefine: false,
  refineMethod: "manual",
  
  // Step 4: Standard task generation
  skipGenerate: false,
  generateMethod: "standard",
  
  // Step 5: Interactive splitting for complex tasks
  skipSplit: false,
  splitMethod: "interactive",
  splitTasks: "task-ui-design,task-api-integration",
  
  // Mobile-focused stack
  frontend: "react-router",
  backend: "express",
  database: "sqlite",
  auth: true,
  bootstrap: false,
  
  // AI configuration for mobile development
  stream: true,
  aiProvider: "openrouter",
  aiModel: "anthropic/claude-3.5-sonnet"
};

// Configuration file for team sharing
const teamConfig: WorkflowConfigFile = {
  version: "1.0.0",
  workflow: mobileAppWorkflow,
  profiles: {
    "developer": {
      ...mobileAppWorkflow,
      autoAccept: true,
      splitMethod: "standard"
    },
    "designer": {
      ...mobileAppWorkflow,
      prdAnswerMode: "ai",
      prdAnswerAiProvider: "openai",
      prdAnswerAiModel: "gpt-4"
    }
  }
};

await WorkflowConfigLoader.saveToFile(teamConfig, "./team-workflow-config.json");

#### Scenario 3: Custom AI Pipeline with Advanced Configuration

// Advanced AI pipeline with custom models per step
const advancedAIWorkflow: WorkflowAutomationOptions = {
  projectName: "AI Research Assistant",
  
  // Step 1: Quick initialization
  initMethod: "quick",
  
  // Step 2: Advanced PRD generation
  prdMethod: "ai",
  prdDescription: "AI-powered research assistant with advanced natural language processing",
  prdMultiGeneration: true,
  prdMultiGenerationModels: "anthropic:claude-3.5-sonnet,openai:gpt-4o,google:gemini-pro",
  prdCombine: true,
  prdCombineModel: "anthropic:claude-3.5-sonnet",
  
  // Step 2.5: AI-powered question/refine
  prdQuestionRefine: true,
  prdAnswerMode: "ai",
  prdAnswerAiProvider: "openrouter",
  prdAnswerAiModel: "anthropic/claude-3.5-sonnet",
  prdAnswerAiReasoning: true,
  
  // Step 3: AI refinement with domain-specific feedback
  skipRefine: false,
  refineMethod: "ai",
  refineFeedback: "Focus on machine learning integration, data privacy compliance, research methodology, and academic citation standards",
  
  // Step 4: Custom AI generation with specialized instructions
  skipGenerate: false,
  generateMethod: "ai",
  generateInstructions: "Generate tasks for ML pipeline development, data preprocessing, model training, and deployment automation. Include tasks for MLOps, experiment tracking, and model versioning.",
  
  // Step 5: Custom splitting with technical focus
  skipSplit: false,
  splitMethod: "custom",
  splitInstructions: "Split tasks by ML pipeline stages: data ingestion, preprocessing, feature engineering, model training, validation, deployment, and monitoring. Create separate subtasks for each stage with appropriate dependencies.",
  
  // AI-focused stack
  frontend: "none", // CLI tool
  backend: "none", // No backend needed
  database: "none", // External data sources
  auth: false,
  bootstrap: false,
  
  // Advanced AI configuration
  stream: true,
  aiProvider: "openrouter",
  aiModel: "anthropic/claude-3.5-sonnet"
};

// Execute with progress tracking
const progressCallback = {
  onProgress: (event) => {
    switch (event.type) {
      case "started":
        console.log(`🚀 ${event.message}`);
        break;
      case "progress":
        console.log(`📊 ${event.message}`);
        break;
      case "completed":
        console.log(`${event.message}`);
        break;
    }
  }
};

await executeWorkflow(advancedAIWorkflow);

TECHNICAL SPECIFICATIONS

#### Configuration Validation Rules

  • Mutual Exclusion: Certain options are mutually exclusive

- skipAll overrides individual step skips

- prdMethod determines required related options

- splitAll overrides splitTasks

  • Conditional Requirements: Some options require others

- prdFile required when prdMethod is "upload"

- prdDescription required when prdMethod is "ai"

- refineFeedback required when refineMethod is "ai"

- splitInstructions required when splitMethod is "custom"

  • AI Configuration Consistency: AI options cascade down to sub-steps

- Base AI config used unless overridden

- Answer AI config separate from main AI config

  • Stack Configuration Validation: Frontend/backend combinations validated

- Certain combinations may be incompatible

- Database choice affects backend options

#### Performance Characteristics

  • Configuration Loading: File-based config loaded asynchronously
  • Step Execution: Sequential execution with dependency management
  • Memory Management: Configuration objects are lightweight
  • Error Recovery: Each step can fail independently

#### Security Considerations

  • API Key Handling: Keys loaded from options or environment
  • File Access: Config files validated for path traversal
  • AI Provider Security: Custom endpoints validated for SSL/TLS
  • Code Execution: Bootstrap processes validated for security

#### Integration Points

  • CLI Layer: Command-line option parsing and validation
  • Service Layer: Workflow orchestration and step execution
  • AI Service: Multi-provider AI operations with streaming
  • Project Management: Better-T-Stack integration and initialization

FREQUENTLY ASKED QUESTIONS FROM THE FIELD

Q: How do I skip just the PRD steps but keep everything else?

A: Set skipPrd: true in your options. This skips both PRD definition and refinement while continuing with task generation. Remember that task generation needs a PRD to work with, so you'll need to provide one via prdFile or have an existing one.

Q: Can I use different AI models for different workflow steps?

A: Yes! Use the step-specific AI options like prdAnswerAiModel for question/refine steps, prdCombineModel for PRD combination, and the base aiModel for other steps. Each step can have its own AI configuration.

Q: What's the difference between `splitAll` and `splitTasks`?

A: splitAll: true splits every task generated in the workflow, while splitTasks lets you specify exact task IDs (comma-separated) to split. Use splitAll for comprehensive breakdown, or splitTasks for targeted splitting.

Q: How do I save my workflow configuration for team sharing?

A: Create a JSON configuration file using the WorkflowConfigLoader class. You can include multiple profiles in the profiles section for different team members or use cases. Use configFile option to load it: --config-file team-workflow.json.

Q: Can I run workflow steps interactively even with automation enabled?

A: Yes! Set autoAccept: false to maintain human oversight. The workflow will still use your AI configurations and predefined options, but will prompt for confirmation at each step. Set skipAll: false and use individual step skips for fine-grained control.

Q: What happens if I specify conflicting options?

A: The workflow validator will throw an error before execution. Common conflicts include: specifying both skipAll and individual step skips, setting prdMethod: "upload" without prdFile, or setting splitMethod: "custom" without splitInstructions.

Remember: Citizen, in the wasteland of manual project setup, workflow automation is your assembly line. Every option is a precision tool, every configuration is a quality control checkpoint, and every automated step is a worker that never sleeps. Configure them wisely, test them thoroughly, and they'll build your empire while you focus on the bigger picture.