mcp-context-engineering/src/context/methodology/prp-generator.ts

The intelligent context optimization system for AI coding assistants. Built with Cole's PRP methodology, Context Portal knowledge graphs, and production-ready MongoDB architecture.

import { z } from 'zod';
import { ResearchEngine, ResearchRequest, ResearchResult } from './research-engine.js';
import { UniversalContextPattern } from '../../mongodb/models/contextPattern.js';
import { ProjectContext } from '../../mongodb/models/projectContext.js';

// Cole's verified PRP template structure
export const PRPTemplateSchema = z.object({
  // Header: Clear goal definition
  header: z.object({
    goal: z.string(),
    business_value: z.string(),
    success_criteria: z.array(z.string()),
    estimated_complexity: z.enum(['low', 'medium', 'high'])
  }),
  
  // Research: Comprehensive analysis (Cole's methodology)
  research_section: z.object({
    codebase_analysis: z.array(z.string()),
    external_research: z.array(z.string()),
    existing_patterns: z.array(z.string()),
    potential_challenges: z.array(z.string()),
    best_practices: z.array(z.string()),
    confidence_score: z.number().min(1).max(10)
  }),
  
  // Implementation: Step-by-step blueprint
  implementation_section: z.object({
    technical_requirements: z.array(z.string()),
    pseudocode: z.string(),
    task_breakdown: z.array(z.object({
      task: z.string(),
      order: z.number(),
      dependencies: z.array(z.string()),
      validation: z.string(),
      estimated_effort: z.string()
    })),
    integration_points: z.array(z.string()),
    error_handling_strategy: z.string()
  }),
  
  // Validation: Quality assurance framework
  validation_section: z.object({
    syntax_checks: z.array(z.string()),
    unit_test_commands: z.array(z.string()),
    integration_tests: z.array(z.string()),
    quality_checklist: z.array(z.string()),
    acceptance_criteria: z.array(z.string())
  }),
  
  // Context Portal integration: Knowledge graph connections
  knowledge_connections: z.object({
    related_decisions: z.array(z.string()),
    dependent_patterns: z.array(z.string()),
    potential_conflicts: z.array(z.string()),
    architecture_impact: z.string()
  }),
  
  // Agent-specific optimizations
  agent_guidance: z.object({
    cursor_specific: z.string(),
    windsurf_specific: z.string(),
    claude_code_specific: z.string(),
    universal_notes: z.string()
  })
});

export const PRPGenerationRequestSchema = z.object({
  feature_description: z.string(),
  project_context: z.object({
    project_id: z.string(),
    current_patterns: z.array(z.string()).optional(),
    tech_stack: z.array(z.string()),
    complexity_preference: z.enum(['low', 'medium', 'high']).default('medium')
  }),
  agent_type: z.enum(['cursor', 'windsurf', 'claude_code', 'generic']).default('generic'),
  research_depth: z.enum(['basic', 'comprehensive', 'exhaustive']).default('comprehensive'),
  include_learning: z.boolean().default(true)
});

export type PRPTemplate = z.infer<typeof PRPTemplateSchema>;
export type PRPGenerationRequest = z.infer<typeof PRPGenerationRequestSchema>;

/**
 * PRP Generator - Core engine combining Cole's methodology with Context Portal knowledge graphs
 * 
 * Perfect harmony: MongoDB (memory) → MCP (interface) → AI Agent (execution)
 * 
 * This creates intelligent, memory-backed planning templates that:
 * 1. Remember what worked before (MongoDB effectiveness tracking)
 * 2. Adapt to different AI agents (Universal optimization)
 * 3. Integrate knowledge graphs (Context Portal patterns)
 * 4. Follow Cole's proven methodology (PRP structure)
 */
export class PRPGenerator {
  
  constructor(
    private researchEngine: ResearchEngine,
    private mongoOperations: any, // Will be MongoDB operations interface
    private embeddingService: any  // Will be Voyage AI embedding service
  ) {}

  /**
   * Generate complete PRP following Cole's template with Context Portal integration
   * 
   * This is the core method that creates perfect planning templates by:
   * 1. Using Cole's research methodology
   * 2. Leveraging stored knowledge patterns
   * 3. Optimizing for specific AI agents
   * 4. Learning from past effectiveness
   */
  async generatePRP(request: PRPGenerationRequest): Promise<{
    prp_template: PRPTemplate;
    context_pattern: UniversalContextPattern;
    confidence_score: number;
    learning_applied: string[];
  }> {
    const validatedRequest = PRPGenerationRequestSchema.parse(request);
    
    // Step 1: Conduct Cole's systematic research
    console.log('🔍 Conducting systematic research using Cole\'s methodology...');
    const researchRequest: ResearchRequest = {
      feature_description: validatedRequest.feature_description,
      project_context: {
        type: 'software project',
        tech_stack: validatedRequest.project_context.tech_stack,
        existing_patterns: validatedRequest.project_context.current_patterns
      },
      research_depth: validatedRequest.research_depth
    };

    const research = await this.researchEngine.conductResearch(researchRequest);
    
    // Step 2: Query MongoDB for similar successful patterns
    console.log('🧠 Retrieving similar successful patterns from memory...');
    const similarPatterns = await this.findSimilarPatterns(validatedRequest);
    
    // Step 3: Apply learned optimizations for target agent
    console.log('🎯 Applying agent-specific optimizations...');
    const agentOptimizations = await this.getAgentOptimizations(
      validatedRequest.agent_type, 
      similarPatterns
    );
    
    // Step 4: Generate Context Portal knowledge graph connections
    console.log('🕸️ Building knowledge graph connections...');
    const knowledgeConnections = await this.buildKnowledgeConnections(
      validatedRequest,
      similarPatterns
    );
    
    // Step 5: Create the complete PRP template
    console.log('📋 Assembling complete PRP template...');
    const prpTemplate = await this.assemblePRPTemplate(
      validatedRequest,
      research,
      agentOptimizations,
      knowledgeConnections
    );
    
    // Step 6: Create universal context pattern for storage
    const contextPattern = await this.createContextPattern(
      prpTemplate,
      validatedRequest,
      research,
      knowledgeConnections
    );
    
    // Step 7: Calculate confidence and learning applied
    const confidenceScore = this.calculateOverallConfidence(research, similarPatterns.length);
    const learningApplied = this.extractLearningApplied(similarPatterns, agentOptimizations);
    
    console.log('✅ PRP generation complete with confidence:', confidenceScore);
    
    return {
      prp_template: prpTemplate,
      context_pattern: contextPattern,
      confidence_score: confidenceScore,
      learning_applied: learningApplied
    };
  }

  /**
   * Find similar successful patterns from MongoDB
   * Uses hybrid search: embeddings + metadata filtering
   */
  private async findSimilarPatterns(request: PRPGenerationRequest): Promise<UniversalContextPattern[]> {
    // This will use MongoDB Atlas Vector Search with effectiveness filtering
    // For now, return empty array - will be implemented with MongoDB operations
    return [];
  }

  /**
   * Get agent-specific optimizations based on historical effectiveness
   */
  private async getAgentOptimizations(
    agentType: string, 
    similarPatterns: UniversalContextPattern[]
  ): Promise<{
    format_preferences: string[];
    focus_areas: string[];
    avoid_patterns: string[];
    effectiveness_score: number;
  }> {
    // Extract learnings from similar patterns for this agent type
    const agentLearnings = similarPatterns
      .map(pattern => pattern.agent_optimizations[agentType as keyof typeof pattern.agent_optimizations])
      .filter(opt => opt?.effectiveness_score > 7);

    return {
      format_preferences: agentLearnings.flatMap(opt => opt?.preferred_sections || []),
      focus_areas: agentLearnings.flatMap(opt => opt?.focus || []),
      avoid_patterns: agentLearnings.flatMap(opt => opt?.avoid_patterns || []),
      effectiveness_score: agentLearnings.length > 0 
        ? agentLearnings.reduce((sum, opt) => sum + (opt?.effectiveness_score || 0), 0) / agentLearnings.length
        : 5
    };
  }

  /**
   * Build Context Portal style knowledge graph connections
   */
  private async buildKnowledgeConnections(
    request: PRPGenerationRequest,
    similarPatterns: UniversalContextPattern[]
  ): Promise<{
    related_decisions: string[];
    dependent_patterns: string[];
    potential_conflicts: string[];
    architecture_impact: string;
  }> {
    const connections = {
      related_decisions: [] as string[],
      dependent_patterns: [] as string[],
      potential_conflicts: [] as string[],
      architecture_impact: ''
    };

    // Extract knowledge graph connections from similar patterns
    for (const pattern of similarPatterns) {
      const kg = pattern.knowledge_graph;
      
      // Find related architectural decisions
      connections.related_decisions.push(
        ...kg.decisions
          .filter(d => d.status === 'accepted')
          .map(d => `${d.title}: ${d.description}`)
      );
      
      // Find dependent patterns
      connections.dependent_patterns.push(
        ...kg.relationships.depends_on,
        ...kg.relationships.related_patterns
      );
      
      // Find potential conflicts
      connections.potential_conflicts.push(
        ...kg.relationships.conflicts_with
      );
    }

    // Analyze architecture impact
    connections.architecture_impact = this.analyzeArchitectureImpact(
      request.feature_description,
      request.project_context.tech_stack
    );

    return connections;
  }

  /**
   * Assemble the complete PRP template following Cole's verified structure
   */
  private async assemblePRPTemplate(
    request: PRPGenerationRequest,
    research: ResearchResult,
    agentOptimizations: any,
    knowledgeConnections: any
  ): Promise<PRPTemplate> {
    
    return {
      // Header: Clear goal definition (Cole's emphasis on clarity)
      header: {
        goal: `Implement ${request.feature_description}`,
        business_value: this.extractBusinessValue(request.feature_description),
        success_criteria: this.generateSuccessCriteria(request.feature_description, research),
        estimated_complexity: request.project_context.complexity_preference
      },
      
      // Research: Cole's comprehensive analysis
      research_section: {
        codebase_analysis: research.codebase_analysis,
        external_research: research.external_research,
        existing_patterns: research.existing_patterns,
        potential_challenges: research.potential_challenges,
        best_practices: research.best_practices,
        confidence_score: research.confidence_score
      },
      
      // Implementation: Step-by-step blueprint (Cole's structured approach)
      implementation_section: {
        technical_requirements: this.generateTechnicalRequirements(request, research),
        pseudocode: this.generatePseudocode(request, research),
        task_breakdown: this.generateTaskBreakdown(request, research),
        integration_points: this.identifyIntegrationPoints(request, research),
        error_handling_strategy: this.generateErrorHandlingStrategy(request, research)
      },
      
      // Validation: Quality assurance (Cole's quality focus)
      validation_section: {
        syntax_checks: this.generateSyntaxChecks(request.project_context.tech_stack),
        unit_test_commands: this.generateTestCommands(request.project_context.tech_stack),
        integration_tests: this.generateIntegrationTests(request),
        quality_checklist: this.generateQualityChecklist(request),
        acceptance_criteria: this.generateAcceptanceCriteria(request.feature_description)
      },
      
      // Context Portal: Knowledge graph integration
      knowledge_connections: knowledgeConnections,
      
      // Agent-specific guidance (Universal optimization)
      agent_guidance: {
        cursor_specific: this.generateCursorGuidance(agentOptimizations, request),
        windsurf_specific: this.generateWindsurfGuidance(agentOptimizations, request),
        claude_code_specific: this.generateClaudeCodeGuidance(agentOptimizations, request),
        universal_notes: this.generateUniversalNotes(agentOptimizations, request)
      }
    };
  }

  /**
   * Create universal context pattern for MongoDB storage
   */
  private async createContextPattern(
    prpTemplate: PRPTemplate,
    request: PRPGenerationRequest,
    research: ResearchResult,
    knowledgeConnections: any
  ): Promise<UniversalContextPattern> {
    
    // Generate embeddings for the English methodology descriptions
    const methodologyText = `${prpTemplate.header.goal}. ${prpTemplate.research_section.best_practices.join(' ')}`;
    const contextText = `${prpTemplate.knowledge_connections.architecture_impact}. ${prpTemplate.knowledge_connections.related_decisions.join(' ')}`;
    const queryText = request.feature_description;

    // These would use Voyage AI embedding service
    const embeddings = {
      methodology_vector: await this.generateEmbedding(methodologyText),
      context_vector: await this.generateEmbedding(contextText),
      query_vector: await this.generateEmbedding(queryText)
    };

    return {
      prp_methodology: {
        research: {
          codebase_analysis: research.codebase_analysis,
          external_research: research.external_research,
          documentation_urls: research.documentation_urls,
          existing_patterns: research.existing_patterns,
          potential_challenges: research.potential_challenges
        },
        implementation: {
          goal: prpTemplate.header.goal,
          business_value: prpTemplate.header.business_value,
          technical_requirements: prpTemplate.implementation_section.technical_requirements,
          pseudocode: prpTemplate.implementation_section.pseudocode,
          task_breakdown: prpTemplate.implementation_section.task_breakdown,
          error_handling_strategy: prpTemplate.implementation_section.error_handling_strategy,
          integration_points: prpTemplate.implementation_section.integration_points
        },
        validation: {
          syntax_checks: prpTemplate.validation_section.syntax_checks,
          unit_test_commands: prpTemplate.validation_section.unit_test_commands,
          integration_tests: prpTemplate.validation_section.integration_tests,
          confidence_score: research.confidence_score,
          quality_checklist: prpTemplate.validation_section.quality_checklist
        }
      },
      knowledge_graph: {
        decisions: [],
        progress_entries: [],
        system_patterns: [],
        context_links: [],
        custom_data: {},
        workspace_context: {
          workspace_id: 'default',
          project_id: request.project_context.project_id
        },
        relationships: {
          depends_on: knowledgeConnections.dependent_patterns,
          enables: [],
          conflicts_with: knowledgeConnections.potential_conflicts,
          related_patterns: []
        }
      },
      embeddings,
      agent_optimizations: {
        cursor: {
          format: 'concise',
          focus: ['implementation', 'validation'],
          effectiveness_score: 7,
          preferred_sections: ['header', 'implementation_section'],
          avoid_patterns: ['lengthy_explanations']
        },
        windsurf: {
          format: 'step_by_step',
          focus: ['task_breakdown', 'error_handling'],
          effectiveness_score: 7,
          preferred_sections: ['implementation_section', 'validation_section'],
          avoid_patterns: ['abstract_concepts']
        },
        claude_code: {
          format: 'full_prp',
          focus: ['research', 'comprehensive_analysis'],
          effectiveness_score: 8,
          preferred_sections: ['research_section', 'knowledge_connections'],
          avoid_patterns: ['minimal_context']
        },
        generic: {
          format: 'balanced',
          focus: ['all_sections'],
          effectiveness_score: 6,
          preferred_sections: ['header', 'implementation_section'],
          avoid_patterns: []
        }
      },
      effectiveness_metrics: {
        overall_success_rate: 0.0,
        implementation_success_count: 0,
        usage_count: 0,
        last_used: new Date(),
        improvement_suggestions: [],
        feedback_history: []
      },
      metadata: {
        pattern_type: this.classifyPatternType(request.feature_description),
        complexity: request.project_context.complexity_preference,
        project_types: ['universal'],
        tech_stacks: request.project_context.tech_stack,
        tags: this.generateTags(request.feature_description, request.project_context.tech_stack),
        created_at: new Date(),
        updated_at: new Date(),
        version: 1
      }
    };
  }

  // Helper methods for PRP generation
  private extractBusinessValue(featureDescription: string): string {
    return `Enhance system capabilities by implementing ${featureDescription}, improving user experience and system functionality.`;
  }

  private generateSuccessCriteria(featureDescription: string, research: ResearchResult): string[] {
    return [
      `${featureDescription} is fully implemented and functional`,
      'All tests pass successfully',
      'Code follows project standards and best practices',
      'Integration with existing system is seamless',
      'Performance meets or exceeds requirements'
    ];
  }

  private generateTechnicalRequirements(request: PRPGenerationRequest, research: ResearchResult): string[] {
    const requirements = [
      `Implement ${request.feature_description} using ${request.project_context.tech_stack.join(', ')}`,
      'Follow existing code patterns and conventions',
      'Ensure proper error handling and validation',
      'Include comprehensive testing',
      'Document API interfaces and usage'
    ];

    // Add research-based requirements
    requirements.push(...research.best_practices.slice(0, 3));
    
    return requirements;
  }

  private generatePseudocode(request: PRPGenerationRequest, research: ResearchResult): string {
    return `
// ${request.feature_description} Implementation Pseudocode
1. Initialize ${request.feature_description} module
2. Define core interfaces and types
3. Implement main functionality
4. Add error handling and validation
5. Create tests and documentation
6. Integrate with existing system
7. Validate and deploy

// Key considerations from research:
${research.potential_challenges.slice(0, 2).map(challenge => `// - ${challenge}`).join('\n')}
    `.trim();
  }

  private generateTaskBreakdown(request: PRPGenerationRequest, research: ResearchResult): Array<{
    task: string;
    order: number;
    dependencies: string[];
    validation: string;
    estimated_effort: string;
  }> {
    return [
      {
        task: `Set up ${request.feature_description} foundation`,
        order: 1,
        dependencies: [],
        validation: 'Basic structure created and compiles',
        estimated_effort: '1-2 hours'
      },
      {
        task: `Implement core ${request.feature_description} logic`,
        order: 2,
        dependencies: ['Set up foundation'],
        validation: 'Core functionality works as expected',
        estimated_effort: '2-4 hours'
      },
      {
        task: 'Add error handling and validation',
        order: 3,
        dependencies: ['Implement core logic'],
        validation: 'All edge cases handled properly',
        estimated_effort: '1-2 hours'
      },
      {
        task: 'Create comprehensive tests',
        order: 4,
        dependencies: ['Add error handling'],
        validation: 'All tests pass with good coverage',
        estimated_effort: '1-3 hours'
      },
      {
        task: 'Integration and documentation',
        order: 5,
        dependencies: ['Create tests'],
        validation: 'Feature fully integrated and documented',
        estimated_effort: '1-2 hours'
      }
    ];
  }

  private identifyIntegrationPoints(request: PRPGenerationRequest, research: ResearchResult): string[] {
    return [
      'Existing API endpoints and interfaces',
      'Database schema and data models',
      'Authentication and authorization systems',
      'Configuration and environment setup',
      'Logging and monitoring integration'
    ];
  }

  private generateErrorHandlingStrategy(request: PRPGenerationRequest, research: ResearchResult): string {
    return `Implement comprehensive error handling with:
1. Input validation at all entry points
2. Graceful degradation for non-critical failures
3. Detailed logging for debugging and monitoring
4. User-friendly error messages
5. Proper HTTP status codes and responses
6. Transaction rollback for data consistency`;
  }

  private generateSyntaxChecks(techStack: string[]): string[] {
    const checks = ['Basic syntax validation'];
    
    if (techStack.includes('typescript')) {
      checks.push('TypeScript type checking', 'ESLint validation');
    }
    if (techStack.includes('python')) {
      checks.push('Python syntax check', 'Flake8 linting');
    }
    if (techStack.includes('rust')) {
      checks.push('Cargo check', 'Clippy linting');
    }
    
    return checks;
  }

  private generateTestCommands(techStack: string[]): string[] {
    const commands = [];
    
    if (techStack.includes('javascript') || techStack.includes('typescript')) {
      commands.push('npm test', 'npm run test:coverage');
    }
    if (techStack.includes('python')) {
      commands.push('pytest', 'python -m pytest --cov');
    }
    if (techStack.includes('rust')) {
      commands.push('cargo test');
    }
    
    return commands.length > 0 ? commands : ['Run project-specific test command'];
  }

  private generateIntegrationTests(request: PRPGenerationRequest): string[] {
    return [
      `Test ${request.feature_description} with existing system components`,
      'Verify database integration and data flow',
      'Test API endpoints and responses',
      'Validate authentication and authorization',
      'Test error scenarios and edge cases'
    ];
  }

  private generateQualityChecklist(request: PRPGenerationRequest): string[] {
    return [
      'Code follows project style guidelines',
      'All functions have proper documentation',
      'Error handling is comprehensive',
      'Tests cover main functionality and edge cases',
      'Performance is acceptable',
      'Security considerations are addressed',
      'Integration points work correctly'
    ];
  }

  private generateAcceptanceCriteria(featureDescription: string): string[] {
    return [
      `${featureDescription} meets all specified requirements`,
      'User can successfully use the new feature',
      'System performance is not negatively impacted',
      'All existing functionality continues to work',
      'Feature is properly documented and testable'
    ];
  }

  private generateCursorGuidance(optimizations: any, request: PRPGenerationRequest): string {
    return `Cursor optimization: Focus on concise, actionable implementation steps. Prioritize code examples and clear validation points.`;
  }

  private generateWindsurfGuidance(optimizations: any, request: PRPGenerationRequest): string {
    return `Windsurf optimization: Provide step-by-step breakdown with clear dependencies. Emphasize error handling and validation at each step.`;
  }

  private generateClaudeCodeGuidance(optimizations: any, request: PRPGenerationRequest): string {
    return `Claude Code optimization: Include comprehensive research context and detailed analysis. Provide full PRP with all supporting information.`;
  }

  private generateUniversalNotes(optimizations: any, request: PRPGenerationRequest): string {
    return `Universal notes: This PRP can be adapted for any AI coding agent. Focus areas and validation criteria are designed to work across different AI systems.`;
  }

  private analyzeArchitectureImpact(featureDescription: string, techStack: string[]): string {
    return `Implementation of ${featureDescription} will integrate with existing ${techStack.join(', ')} architecture. Requires careful consideration of data flow, API design, and system boundaries.`;
  }

  private async generateEmbedding(text: string): Promise<number[]> {
    // Placeholder for Voyage AI embedding service
    // Will return actual embeddings in implementation
    return new Array(1024).fill(0).map(() => Math.random());
  }

  private classifyPatternType(featureDescription: string): string {
    const lowerDesc = featureDescription.toLowerCase();
    
    if (lowerDesc.includes('api') || lowerDesc.includes('endpoint')) return 'api_implementation';
    if (lowerDesc.includes('ui') || lowerDesc.includes('component')) return 'ui_component';
    if (lowerDesc.includes('database') || lowerDesc.includes('data')) return 'data_management';
    if (lowerDesc.includes('auth') || lowerDesc.includes('security')) return 'security_feature';
    if (lowerDesc.includes('test') || lowerDesc.includes('testing')) return 'testing_framework';
    
    return 'general_feature';
  }

  private generateTags(featureDescription: string, techStack: string[]): string[] {
    const tags = [...techStack];
    const lowerDesc = featureDescription.toLowerCase();
    
    if (lowerDesc.includes('crud')) tags.push('crud');
    if (lowerDesc.includes('api')) tags.push('api');
    if (lowerDesc.includes('ui')) tags.push('frontend');
    if (lowerDesc.includes('database')) tags.push('backend');
    if (lowerDesc.includes('auth')) tags.push('authentication');
    if (lowerDesc.includes('test')) tags.push('testing');
    
    return [...new Set(tags)]; // Remove duplicates
  }

  private calculateOverallConfidence(research: ResearchResult, similarPatternsCount: number): number {
    let confidence = research.confidence_score;
    
    // Boost confidence based on similar successful patterns
    if (similarPatternsCount > 0) {
      confidence += Math.min(similarPatternsCount * 0.5, 2);
    }
    
    return Math.min(confidence, 10);
  }

  private extractLearningApplied(patterns: UniversalContextPattern[], optimizations: any): string[] {
    const learning = ['Applied Cole\'s systematic research methodology'];
    
    if (patterns.length > 0) {
      learning.push(`Leveraged insights from ${patterns.length} similar successful patterns`);
    }
    
    if (optimizations.effectiveness_score > 7) {
      learning.push('Applied high-effectiveness agent optimizations');
    }
    
    return learning;
  }
}