create-byan-agent 2.0.1 → 2.1.0

package/install/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;

package/install/src/byan-v2/orchestrator/interview-state.js

@@ -0,0 +1,271 @@
+/**
+ * InterviewState - Story 4.2
+ * Manages structured interview flow through 4 phases
+ * 
+ * Phases:
+ * 1. CONTEXT: Project context, domain, users
+ * 2. BUSINESS: Goals, problems, success criteria
+ * 3. AGENT_NEEDS: Agent capabilities, behavior, constraints
+ * 4. VALIDATION: Confirm understanding, clarifications
+ * 
+ * Integrates with SessionState to persist interview data
+ */
+
+const Logger = require('../observability/logger');
+const crypto = require('crypto');
+
+class InterviewState {
+  constructor(sessionState) {
+    this.sessionState = sessionState;
+    this.logger = new Logger();
+
+    // AC1: Define 4 phases
+    this.PHASES = {
+      CONTEXT: 'CONTEXT',
+      BUSINESS: 'BUSINESS',
+      AGENT_NEEDS: 'AGENT_NEEDS',
+      VALIDATION: 'VALIDATION'
+    };
+
+    // Current interview state
+    this.currentPhase = this.PHASES.CONTEXT;
+    this.currentQuestionIndex = 0;
+    this.awaitingResponse = false;
+    this.lastAskedQuestion = null;
+
+    // AC4: Track responses per phase
+    this.phaseResponses = {
+      CONTEXT: [],
+      BUSINESS: [],
+      AGENT_NEEDS: [],
+      VALIDATION: []
+    };
+
+    // AC1: Question banks for each phase (min 3 per phase)
+    this.questionBanks = {
+      CONTEXT: [
+        'What is the main purpose or domain of your project?',
+        'Who are the primary users or stakeholders?',
+        'What is the current workflow or process this agent will support?',
+        'What technologies or platforms are you using?',
+        'What is the scale or scope of your project?'
+      ],
+      BUSINESS: [
+        'What specific problem or challenge does this agent need to solve?',
+        'What are the key goals or objectives for this agent?',
+        'How will you measure the success of this agent?',
+        'What are the most time-consuming or error-prone tasks currently?',
+        'What business value or ROI do you expect?'
+      ],
+      AGENT_NEEDS: [
+        'What specific capabilities should this agent have?',
+        'What knowledge or expertise should the agent possess?',
+        'How should the agent interact with users (tone, style, format)?',
+        'What are the critical constraints or limitations for the agent?',
+        'What level of autonomy should the agent have in decision-making?'
+      ],
+      VALIDATION: [
+        'Let me confirm: The agent will help with [SUMMARY]. Is this correct?',
+        'Are there any critical requirements or edge cases we haven\'t covered?',
+        'What would make this agent a complete failure in your eyes?',
+        'Is there anything else important I should know about this agent?'
+      ]
+    };
+
+    this.phaseOrder = ['CONTEXT', 'BUSINESS', 'AGENT_NEEDS', 'VALIDATION'];
+    this.minResponsesPerPhase = 3;
+  }
+
+  /**
+   * AC2: Ask next question based on phase and responses
+   * @returns {Object|null} Question object or null if complete
+   */
+  askNextQuestion() {
+    // Check if waiting for response to last question
+    if (this.awaitingResponse && this.lastAskedQuestion) {
+      this.logger.warn('Awaiting response to previous question');
+      return this.lastAskedQuestion;
+    }
+
+    // Check if interview complete
+    if (this.isInterviewComplete()) {
+      this.logger.info('Interview complete - no more questions');
+      return null;
+    }
+
+    // Check if current phase needs transition
+    if (this.isPhaseComplete(this.currentPhase)) {
+      this._transitionToNextPhase();
+    }
+
+    // Get question from current phase
+    const phaseQuestions = this.questionBanks[this.currentPhase];
+    const phaseResponseCount = this.phaseResponses[this.currentPhase].length;
+    
+    // Use response count as index (allows revisiting questions)
+    const questionIndex = Math.min(phaseResponseCount, phaseQuestions.length - 1);
+    const questionText = phaseQuestions[questionIndex];
+
+    // Build question object
+    const question = {
+      questionId: crypto.randomUUID(),
+      text: questionText,
+      phase: this.currentPhase,
+      questionNumber: this.currentQuestionIndex + 1,
+      totalInPhase: phaseQuestions.length,
+      phaseProgress: `${phaseResponseCount + 1}/${this.minResponsesPerPhase} (min)`
+    };
+
+    // Store in SessionState
+    this.sessionState.addQuestion(questionText);
+
+    // Mark as awaiting response
+    this.awaitingResponse = true;
+    this.lastAskedQuestion = question;
+
+    this.logger.info('Question asked', {
+      phase: this.currentPhase,
+      questionNumber: question.questionNumber,
+      phaseProgress: question.phaseProgress
+    });
+
+    return question;
+  }
+
+  /**
+   * AC3: Process user response and store
+   * @param {string} response - User's response
+   */
+  processResponse(response) {
+    if (!this.awaitingResponse) {
+      this.logger.warn('No question pending - ignoring response');
+      return false;
+    }
+
+    // Store response in current phase
+    const responseData = {
+      questionId: this.lastAskedQuestion.questionId,
+      response: response || '',
+      timestamp: Date.now(),
+      phase: this.currentPhase
+    };
+
+    this.phaseResponses[this.currentPhase].push(responseData);
+
+    // Store in SessionState
+    this.sessionState.addResponse(this.lastAskedQuestion.questionId, response);
+
+    // Update state
+    this.currentQuestionIndex++;
+    this.awaitingResponse = false;
+    this.lastAskedQuestion = null;
+
+    this.logger.info('Response processed', {
+      phase: this.currentPhase,
+      responseCount: this.phaseResponses[this.currentPhase].length,
+      phaseComplete: this.isPhaseComplete(this.currentPhase)
+    });
+
+    // Transition to next phase if current phase is complete
+    if (this.isPhaseComplete(this.currentPhase)) {
+      const currentPhaseIndex = this.phaseOrder.indexOf(this.currentPhase);
+      if (currentPhaseIndex < this.phaseOrder.length - 1) {
+        this._transitionToNextPhase();
+      }
+    }
+
+    return this.isInterviewComplete();
+  }
+
+  /**
+   * AC4: Check if phase has minimum responses
+   * @param {string} phase - Phase name
+   * @returns {boolean} True if phase complete
+   */
+  isPhaseComplete(phase) {
+    return this.phaseResponses[phase].length >= this.minResponsesPerPhase;
+  }
+
+  /**
+   * AC5: Check if all phases complete and can transition to ANALYSIS
+   * @returns {boolean} True if interview complete
+   */
+  canTransitionToAnalysis() {
+    return this.phaseOrder.every(phase => this.isPhaseComplete(phase));
+  }
+
+  /**
+   * Check if interview is complete
+   * @returns {boolean} True if all phases done
+   */
+  isInterviewComplete() {
+    return this.canTransitionToAnalysis();
+  }
+
+  /**
+   * Get all collected responses
+   * @returns {Object} All phase responses
+   */
+  getAllResponses() {
+    return { ...this.phaseResponses };
+  }
+
+  /**
+   * Get responses for specific phase
+   * @param {string} phase - Phase name
+   * @returns {Array} Phase responses
+   */
+  getPhaseResponses(phase) {
+    return [...this.phaseResponses[phase]];
+  }
+
+  /**
+   * Get interview progress summary
+   * @returns {Object} Progress data
+   */
+  getProgress() {
+    const phaseProgress = {};
+    
+    this.phaseOrder.forEach(phase => {
+      const count = this.phaseResponses[phase].length;
+      phaseProgress[phase] = {
+        responses: count,
+        complete: this.isPhaseComplete(phase),
+        progress: `${count}/${this.minResponsesPerPhase}`
+      };
+    });
+
+    return {
+      currentPhase: this.currentPhase,
+      totalQuestions: this.currentQuestionIndex,
+      phases: phaseProgress,
+      canTransitionToAnalysis: this.canTransitionToAnalysis()
+    };
+  }
+
+  /**
+   * Transition to next phase
+   * @private
+   */
+  _transitionToNextPhase() {
+    const currentIndex = this.phaseOrder.indexOf(this.currentPhase);
+    
+    if (currentIndex === -1 || currentIndex >= this.phaseOrder.length - 1) {
+      // Already at last phase or invalid
+      return;
+    }
+
+    const nextPhase = this.phaseOrder[currentIndex + 1];
+    const previousPhase = this.currentPhase;
+    
+    this.currentPhase = nextPhase;
+
+    this.logger.info('Interview phase transition', {
+      from: previousPhase,
+      to: nextPhase,
+      previousPhaseResponses: this.phaseResponses[previousPhase].length
+    });
+  }
+}
+
+module.exports = InterviewState;