create-byan-agent 2.0.1 → 2.1.1

package/src/byan-v2/orchestrator/analysis-state.js

@@ -0,0 +1,268 @@
+/**
+ * AnalysisState - Story 4.3
+ * Analyzes interview responses to extract structured requirements
+ * 
+ * Integrates:
+ * - TaskRouter: Route tasks based on complexity
+ * - LocalExecutor: Execute high-complexity analysis
+ * - Logger: Log analysis steps
+ * - SessionState: Store analysis results
+ */
+
+const TaskRouter = require('../dispatcher/task-router');
+const LocalExecutor = require('../dispatcher/local-executor');
+const Logger = require('../observability/logger');
+
+class AnalysisState {
+  constructor(sessionState) {
+    this.sessionState = sessionState;
+    this.taskRouter = new TaskRouter();
+    this.localExecutor = new LocalExecutor();
+    this.logger = new Logger();
+
+    this.analysisComplete = false;
+    this.requirements = null;
+    this.patterns = null;
+  }
+
+  /**
+   * AC2: Extract requirements from user responses
+   * Identifies: purpose, capabilities, knowledgeAreas, constraints
+   * 
+   * @returns {Promise<Object>} Extracted requirements
+   */
+  async extractRequirements() {
+    this.logger.info('Analysis started: extracting requirements', {
+      responseCount: this.sessionState.userResponses.length
+    });
+
+    // Prepare analysis task
+    const responsesText = this.sessionState.userResponses
+      .map((r, i) => `Response ${i + 1}: ${r.response}`)
+      .join('\n');
+
+    const analysisTask = {
+      type: 'analysis',
+      prompt: `Extract structured requirements from these user responses:
+
+${responsesText}
+
+Extract and return JSON with:
+- purpose: Main goal/purpose of the agent
+- capabilities: Array of specific capabilities needed
+- knowledgeAreas: Array of knowledge domains required
+- constraints: Array of constraints or limitations`,
+      metadata: {
+        requiresReasoning: true,
+        requiresMultipleSteps: true,
+        estimatedDuration: 'medium'
+      }
+    };
+
+    // AC6: Route through TaskRouter (complexity-based delegation)
+    const routing = this.taskRouter.routeTask(analysisTask);
+    
+    this.logger.info('Task routed', {
+      executor: routing.executor,
+      complexity: routing.complexity
+    });
+
+    // Execute analysis (typically routed to LocalExecutor due to high complexity)
+    let result;
+    if (routing.executor === 'local') {
+      result = await this.localExecutor.execute(analysisTask);
+    } else {
+      // Fallback to local if task-tool routing (shouldn't happen for analysis)
+      result = await this.localExecutor.execute(analysisTask);
+    }
+
+    // Parse requirements
+    try {
+      this.requirements = JSON.parse(result.output);
+    } catch (error) {
+      this.logger.error('Failed to parse analysis output', { error: error.message });
+      throw new Error('Invalid analysis output format');
+    }
+
+    // Store in SessionState
+    this.sessionState.setAnalysisResults({
+      requirements: this.requirements,
+      timestamp: Date.now(),
+      tokens: result.tokens,
+      duration: result.duration
+    });
+
+    this.logger.info('Requirements extraction complete', {
+      purpose: this.requirements.purpose,
+      capabilitiesCount: this.requirements.capabilities?.length || 0,
+      knowledgeAreasCount: this.requirements.knowledgeAreas?.length || 0
+    });
+
+    return this.requirements;
+  }
+
+  /**
+   * AC3: Identify patterns and common themes across responses
+   * @returns {Promise<Array>} Patterns found
+   */
+  async identifyPatterns() {
+    this.logger.info('Identifying patterns across responses');
+
+    if (!this.sessionState.userResponses || this.sessionState.userResponses.length === 0) {
+      this.logger.warn('No responses to analyze for patterns');
+      this.patterns = [];
+      return this.patterns;
+    }
+
+    // Simple pattern detection based on keyword frequency
+    const keywordCounts = {};
+    const responses = this.sessionState.userResponses
+      .map(r => (r.response || '').toLowerCase())
+      .join(' ');
+
+    // Extract words (simple tokenization)
+    const words = responses.split(/\s+/).filter(w => w.length > 3);
+
+    // Count occurrences
+    words.forEach(word => {
+      keywordCounts[word] = (keywordCounts[word] || 0) + 1;
+    });
+
+    // Find patterns (words appearing >= 2 times)
+    this.patterns = Object.entries(keywordCounts)
+      .filter(([word, count]) => count >= 2)
+      .map(([word, count]) => ({
+        theme: word,
+        occurrences: count,
+        relevance: count / words.length
+      }))
+      .sort((a, b) => b.occurrences - a.occurrences)
+      .slice(0, 10); // Top 10 patterns
+
+    // Update SessionState
+    if (this.sessionState.analysisResults) {
+      this.sessionState.analysisResults.patterns = this.patterns;
+    } else {
+      this.sessionState.setAnalysisResults({ patterns: this.patterns });
+    }
+
+    this.logger.info('Pattern identification complete', {
+      patternsFound: this.patterns.length
+    });
+
+    return this.patterns;
+  }
+
+  /**
+   * AC4: Validate that all required fields are present and complete
+   * @param {Object} requirements - Requirements object to validate
+   * @returns {boolean} True if complete
+   */
+  validateCompleteness(requirements) {
+    if (!requirements || typeof requirements !== 'object') {
+      this.logger.warn('Requirements validation failed: invalid input');
+      return false;
+    }
+
+    // Check required fields exist
+    const requiredFields = ['purpose', 'capabilities', 'knowledgeAreas', 'constraints'];
+    
+    for (const field of requiredFields) {
+      if (!requirements[field]) {
+        this.logger.warn(`Requirements validation failed: missing ${field}`);
+        return false;
+      }
+    }
+
+    // Validate purpose is not empty
+    if (typeof requirements.purpose !== 'string' || requirements.purpose.trim().length === 0) {
+      this.logger.warn('Requirements validation failed: empty purpose');
+      return false;
+    }
+
+    // Validate arrays are not empty
+    const arrayFields = ['capabilities', 'knowledgeAreas'];
+    
+    for (const field of arrayFields) {
+      if (!Array.isArray(requirements[field]) || requirements[field].length === 0) {
+        this.logger.warn(`Requirements validation failed: empty ${field}`);
+        return false;
+      }
+    }
+
+    // Constraints can be empty array (optional)
+    if (!Array.isArray(requirements.constraints)) {
+      this.logger.warn('Requirements validation failed: constraints must be array');
+      return false;
+    }
+
+    this.logger.info('Requirements validation passed', {
+      purpose: requirements.purpose.substring(0, 50),
+      capabilitiesCount: requirements.capabilities.length,
+      knowledgeAreasCount: requirements.knowledgeAreas.length
+    });
+
+    return true;
+  }
+
+  /**
+   * AC5: Check if analysis is complete and can transition to GENERATION
+   * @returns {boolean} True if ready to transition
+   */
+  canTransitionToGeneration() {
+    // Check if requirements have been extracted
+    if (!this.requirements) {
+      this.logger.warn('Cannot transition: requirements not extracted');
+      return false;
+    }
+
+    // Validate completeness
+    if (!this.validateCompleteness(this.requirements)) {
+      this.logger.warn('Cannot transition: requirements incomplete');
+      return false;
+    }
+
+    // Check SessionState has analysis results
+    if (!this.sessionState.analysisResults || 
+        !this.sessionState.analysisResults.requirements) {
+      this.logger.warn('Cannot transition: SessionState missing analysis results');
+      return false;
+    }
+
+    this.logger.info('Analysis complete - ready to transition to GENERATION');
+    this.analysisComplete = true;
+    return true;
+  }
+
+  /**
+   * Get current analysis results
+   * @returns {Object} Analysis results
+   */
+  getAnalysisResults() {
+    return {
+      requirements: this.requirements,
+      patterns: this.patterns,
+      complete: this.analysisComplete
+    };
+  }
+
+  /**
+   * Get requirements summary
+   * @returns {Object} Requirements summary
+   */
+  getRequirementsSummary() {
+    if (!this.requirements) {
+      return { summary: 'No requirements extracted yet' };
+    }
+
+    return {
+      purpose: this.requirements.purpose,
+      capabilitiesCount: this.requirements.capabilities?.length || 0,
+      knowledgeAreasCount: this.requirements.knowledgeAreas?.length || 0,
+      constraintsCount: this.requirements.constraints?.length || 0,
+      isComplete: this.validateCompleteness(this.requirements)
+    };
+  }
+}
+
+module.exports = AnalysisState;

package/src/byan-v2/orchestrator/generation-state.js

@@ -0,0 +1,340 @@
+/**
+ * GenerationState - Story 4.4
+ * Generates agent profile in BMAD/Copilot format
+ * 
+ * Format:
+ * - YAML frontmatter (name, description)
+ * - XML structure (<agent>, <persona>, <menu>, <capabilities>)
+ * - Compliant with .github/copilot/agents/ standard
+ */
+
+const Logger = require('../observability/logger');
+const fs = require('fs');
+const path = require('path');
+
+class GenerationState {
+  constructor(sessionState) {
+    if (!sessionState) {
+      throw new Error('SessionState is required');
+    }
+
+    this.sessionState = sessionState;
+    this.logger = new Logger();
+    this.profileGenerated = false;
+    this.generatedProfile = null;
+  }
+
+  /**
+   * AC2: Generate agent profile from analysis results
+   * Creates: name, description, persona, menu, capabilities
+   * 
+   * @returns {Promise<string>} Agent profile content
+   */
+  async generateProfile() {
+    this.logger.info('Starting agent profile generation');
+
+    // AC6: Try to retrieve analysis results, fallback to user responses
+    let requirements;
+    
+    if (this.sessionState.analysisResults && this.sessionState.analysisResults.requirements) {
+      requirements = this.sessionState.analysisResults.requirements;
+    } else {
+      // Fallback: Generate minimal requirements from user responses
+      this.logger.warn('No analysis results, generating from user responses');
+      requirements = this._extractRequirementsFromResponses();
+    }
+
+    // AC2: Extract components from requirements
+    const agentName = this._deriveAgentName(requirements.purpose || 'custom-agent');
+    const description = this._deriveDescription(requirements.purpose || 'Custom agent');
+    const persona = this._generatePersona(requirements);
+    const menu = this._generateMenu(requirements.capabilities || []);
+    const capabilities = this._generateCapabilities(requirements);
+
+    // AC1 & AC3: Build profile with YAML frontmatter + XML
+    this.generatedProfile = this._buildProfile({
+      name: agentName,
+      description,
+      persona,
+      menu,
+      capabilities,
+      requirements
+    });
+
+    // AC6: Store in SessionState
+    this.sessionState.agentProfileDraft = {
+      content: this.generatedProfile,
+      name: agentName,
+      timestamp: Date.now()
+    };
+
+    this.profileGenerated = true;
+
+    this.logger.info('Agent profile generated', {
+      name: agentName,
+      length: this.generatedProfile.length
+    });
+
+    return this.generatedProfile;
+  }
+
+  /**
+   * AC4: Validate profile format and compliance
+   * Checks: YAML frontmatter, XML well-formed, required fields, no emojis in code
+   * 
+   * @param {string} profile - Profile content to validate
+   * @returns {boolean} True if valid
+   */
+  validateProfile(profile) {
+    if (!profile || typeof profile !== 'string') {
+      this.logger.warn('Validation failed: invalid profile');
+      return false;
+    }
+
+    try {
+      // AC4: Validate YAML frontmatter
+      const frontmatterMatch = profile.match(/^---([\s\S]*?)---/);
+      if (!frontmatterMatch) {
+        this.logger.warn('Validation failed: missing YAML frontmatter');
+        return false;
+      }
+
+      const frontmatter = frontmatterMatch[1];
+      
+      // Check required YAML fields
+      if (!frontmatter.includes('name:')) {
+        this.logger.warn('Validation failed: missing name in frontmatter');
+        return false;
+      }
+      if (!frontmatter.includes('description:')) {
+        this.logger.warn('Validation failed: missing description in frontmatter');
+        return false;
+      }
+
+      // AC4: Validate XML block
+      const xmlMatch = profile.match(/```xml\s*([\s\S]*?)\s*```/);
+      if (!xmlMatch) {
+        this.logger.warn('Validation failed: missing XML block');
+        return false;
+      }
+
+      const xml = xmlMatch[1];
+
+      // AC4: Check XML well-formedness (basic)
+      if (!xml.includes('<agent') || !xml.includes('</agent>')) {
+        this.logger.warn('Validation failed: malformed XML');
+        return false;
+      }
+
+      // AC4: Validate no emojis in XML code sections
+      const emojiRegex = /[\u{1F300}-\u{1F9FF}]/u;
+      if (emojiRegex.test(xml)) {
+        this.logger.warn('Validation failed: emojis found in XML');
+        return false;
+      }
+
+      this.logger.info('Profile validation passed');
+      return true;
+
+    } catch (error) {
+      this.logger.error('Validation error', { error: error.message });
+      return false;
+    }
+  }
+
+  /**
+   * AC5: Save profile to disk
+   * @param {string} filePath - Path to save profile
+   */
+  saveProfile(filePath) {
+    if (!this.generatedProfile) {
+      throw new Error('No profile to save - generate profile first');
+    }
+
+    try {
+      // Ensure directory exists
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      // Write profile
+      fs.writeFileSync(filePath, this.generatedProfile, 'utf-8');
+
+      this.logger.info('Profile saved', {
+        path: filePath,
+        size: this.generatedProfile.length
+      });
+
+    } catch (error) {
+      this.logger.error('Save failed', { error: error.message, path: filePath });
+      throw error;
+    }
+  }
+
+  /**
+   * Get default save path
+   * @returns {string} Default path
+   */
+  getDefaultSavePath() {
+    const name = this.sessionState.agentProfileDraft?.name || 'agent';
+    return `.github/copilot/agents/${name}.md`;
+  }
+
+  /**
+   * Extract requirements from user responses (fallback)
+   * @private
+   */
+  _extractRequirementsFromResponses() {
+    const responseData = this.sessionState.userResponses || [];
+    
+    // Extract response text from response objects
+    const responses = responseData.map(r => typeof r === 'string' ? r : (r.response || ''));
+    
+    return {
+      purpose: responses[0] || 'Custom agent',
+      domain: responses[3] || 'General',
+      capabilities: responses[7] ? responses[7].split(',').map(c => c.trim()) : ['General capability'],
+      knowledgeAreas: responses[2] ? responses[2].split(',').map(k => k.trim()) : ['General'],
+      users: responses[4] ? responses[4].split(',').map(u => u.trim()) : ['Users'],
+      constraints: responses.length > 10 ? [responses[10]] : []
+    };
+  }
+
+  /**
+   * Derive agent name from purpose
+   * @private
+   */
+  _deriveAgentName(purpose) {
+    // Extract key words, sanitize, hyphenate
+    const name = purpose
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .trim()
+      .split(/\s+/)
+      .slice(0, 3) // Max 3 words
+      .join('-');
+
+    return name || 'custom-agent';
+  }
+
+  /**
+   * Derive description from purpose
+   * @private
+   */
+  _deriveDescription(purpose) {
+    // Use first sentence or truncate
+    const firstSentence = purpose.split(/[.!?]/)[0].trim();
+    return firstSentence.length > 100 
+      ? firstSentence.substring(0, 97) + '...'
+      : firstSentence;
+  }
+
+  /**
+   * Generate persona from requirements
+   * @private
+   */
+  _generatePersona(requirements) {
+    const { purpose, capabilities, knowledgeAreas } = requirements;
+
+    return `<persona>
+    <role>Specialized Agent</role>
+    <identity>${purpose}</identity>
+    <expertise>Expert in ${knowledgeAreas.slice(0, 3).join(', ')}</expertise>
+    <communication_style>Professional, clear, and focused on delivering results</communication_style>
+    <capabilities>
+${capabilities.slice(0, 5).map(cap => `      <capability>${this._escapeXml(cap)}</capability>`).join('\n')}
+    </capabilities>
+  </persona>`;
+  }
+
+  /**
+   * Generate menu from capabilities
+   * @private
+   */
+  _generateMenu(capabilities) {
+    const menuItems = capabilities.slice(0, 5).map((cap, index) => {
+      const cmdKey = `C${index + 1}`;
+      return `    <item cmd="${cmdKey}">[${cmdKey}] ${this._escapeXml(cap)}</item>`;
+    });
+
+    return `<menu>
+${menuItems.join('\n')}
+    <item cmd="MH">[MH] Menu Help</item>
+  </menu>`;
+  }
+
+  /**
+   * Generate capabilities section
+   * @private
+   */
+  _generateCapabilities(requirements) {
+    const { capabilities, knowledgeAreas, constraints } = requirements;
+
+    return `<capabilities>
+    <primary>
+${capabilities.map(cap => `      <capability>${this._escapeXml(cap)}</capability>`).join('\n')}
+    </primary>
+    <knowledge>
+${knowledgeAreas.map(area => `      <domain>${this._escapeXml(area)}</domain>`).join('\n')}
+    </knowledge>
+    <constraints>
+${(constraints || []).map(c => `      <constraint>${this._escapeXml(c)}</constraint>`).join('\n')}
+    </constraints>
+  </capabilities>`;
+  }
+
+  /**
+   * Build complete profile
+   * @private
+   */
+  _buildProfile({ name, description, persona, menu, capabilities, requirements }) {
+    const agentId = `${name}.agent.yaml`;
+
+    return `---
+name: "${name}"
+description: "${description}"
+---
+
+\`\`\`xml
+<agent id="${agentId}" name="${name}" title="${description}">
+  <activation>
+    <step n="1">Load agent context and requirements</step>
+    <step n="2">Initialize with user's project context</step>
+    <step n="3">Display greeting and menu</step>
+    <step n="4">Await user input</step>
+  </activation>
+
+  ${persona}
+
+  ${menu}
+
+  ${capabilities}
+
+  <guidelines>
+    <guideline>Follow user requirements precisely</guideline>
+    <guideline>Maintain professional communication</guideline>
+    <guideline>Provide actionable, clear responses</guideline>
+    <guideline>Leverage knowledge domains effectively</guideline>
+  </guidelines>
+</agent>
+\`\`\`
+`;
+  }
+
+  /**
+   * Escape XML special characters
+   * @private
+   */
+  _escapeXml(str) {
+    if (!str) return '';
+    return String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+}
+
+module.exports = GenerationState;