aiwf 0.3.22 → 0.4.0

package/docs/designs/AI_PERSONA_SYSTEM_DESIGN.md

@@ -1,516 +0,0 @@
-# AI Persona System Design Document
-
-## Overview
-
-The AI Persona System is designed to optimize Claude Code's behavior for different development tasks through specialized personas. This document outlines the architecture, implementation strategy, and integration approach.
-
-## Design Principles
-
-1. **Hybrid Activation**: Automatic detection with manual override capability
-2. **Context Preservation**: Maintain existing context while adding persona-specific rules
-3. **Predefined Personas**: Start with 5 core personas, extensible in future versions
-4. **Prompt Injection**: Integrate with Claude via system prompt modification
-5. **Tool Recommendations**: Suggest optimal tools without hard restrictions
-6. **Dynamic Token Management**: Adjust token allocation based on task complexity
-7. **Metrics-Driven**: Collect completion time and quality metrics for continuous improvement
-
-## Architecture
-
-### System Components
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Claude Code                           │
-├─────────────────────────────────────────────────────────────┤
-│                    AI Persona System                         │
-├─────────────────┬───────────────────┬───────────────────────┤
-│  Persona Manager │  Context Engine   │  Metrics Collector   │
-├─────────────────┼───────────────────┼───────────────────────┤
-│ Auto Detector   │  Rule Processor   │  Quality Analyzer    │
-│ Manual Switch   │  Token Optimizer  │  Time Tracker        │
-│ State Manager   │  Prompt Builder   │  Report Generator    │
-└─────────────────┴───────────────────┴───────────────────────┘
-```
-
-### Core Personas
-
-| Persona | Primary Focus | Key Behaviors | Recommended Tools |
-|---------|---------------|---------------|-------------------|
-| **Architect** | System design | Big picture thinking, scalability focus | Glob, LS, MarkdownProcessor |
-| **Debugger** | Problem solving | Detailed analysis, systematic approach | Grep, Read, MemoryProfiler |
-| **Reviewer** | Code quality | Standards compliance, security awareness | Git commands, FileUtils |
-| **Documenter** | Documentation | Clear explanations, examples | MarkdownProcessor, TemplateEngine |
-| **Optimizer** | Performance | Efficiency focus, benchmarking | PerformanceBenchmark, TokenTracker |
-
-## Implementation Strategy
-
-### Phase 1: Core Infrastructure
-
-#### 1.1 Persona Manager Class
-
-```javascript
-class PersonaManager {
-  constructor(options = {}) {
-    this.currentPersona = null;
-    this.personaHistory = [];
-    this.autoDetectionEnabled = true;
-    this.metricsCollector = new MetricsCollector();
-    this.contextEngine = new ContextEngine();
-  }
-
-  async switchPersona(personaName, options = {}) {
-    // Validate persona
-    if (!this.isValidPersona(personaName)) {
-      throw new Error(`Invalid persona: ${personaName}`);
-    }
-
-    // Save current state
-    if (this.currentPersona) {
-      this.personaHistory.push({
-        persona: this.currentPersona,
-        timestamp: new Date(),
-        metrics: await this.collectMetrics()
-      });
-    }
-
-    // Load new persona
-    const persona = await this.loadPersona(personaName);
-    
-    // Apply context rules
-    await this.contextEngine.applyPersonaRules(persona);
-    
-    // Update state
-    this.currentPersona = persona;
-    
-    // Track switch event
-    this.metricsCollector.trackEvent('persona_switch', {
-      from: this.personaHistory[this.personaHistory.length - 1]?.persona?.name,
-      to: personaName,
-      trigger: options.manual ? 'manual' : 'auto'
-    });
-
-    return persona;
-  }
-
-  async detectOptimalPersona(taskContext) {
-    // Analyze task characteristics
-    const analysis = await this.analyzeTask(taskContext);
-    
-    // Score each persona
-    const scores = {};
-    for (const personaName of this.getAvailablePersonas()) {
-      scores[personaName] = await this.scorePersonaFit(personaName, analysis);
-    }
-    
-    // Return best match
-    return Object.entries(scores)
-      .sort(([,a], [,b]) => b - a)[0][0];
-  }
-}
-```
-
-#### 1.2 Context Engine
-
-```javascript
-class ContextEngine {
-  constructor() {
-    this.baseContext = null;
-    this.personaOverlay = null;
-    this.tokenOptimizer = new TokenOptimizer();
-  }
-
-  async applyPersonaRules(persona) {
-    // Preserve base context
-    if (!this.baseContext) {
-      this.baseContext = await this.captureCurrentContext();
-    }
-
-    // Build persona-specific overlay
-    this.personaOverlay = {
-      systemPrompt: this.buildSystemPrompt(persona),
-      priorityPatterns: persona.contextRules.priority,
-      exclusionPatterns: persona.contextRules.exclude,
-      focusAreas: persona.contextRules.focus,
-      keywords: persona.contextRules.keywords
-    };
-
-    // Optimize token usage
-    const optimizedContext = await this.tokenOptimizer.optimize(
-      this.baseContext,
-      this.personaOverlay,
-      persona.tokenAllocation
-    );
-
-    // Inject into Claude
-    await this.injectContext(optimizedContext);
-  }
-
-  buildSystemPrompt(persona) {
-    return `You are currently operating in ${persona.name} mode.
-
-Key behaviors:
-${persona.behaviors.map(b => `- ${b}`).join('\n')}
-
-Focus areas:
-${persona.focusAreas.map(f => `- ${f}`).join('\n')}
-
-Communication style: ${persona.communicationStyle}
-
-Recommended tools: ${persona.recommendedTools.join(', ')}`;
-  }
-}
-```
-
-### Phase 2: Auto-Detection System
-
-#### 2.1 Task Analyzer
-
-```javascript
-class TaskAnalyzer {
-  constructor() {
-    this.patterns = {
-      architecture: [
-        /design|architect|structure|system|scalab/i,
-        /interface|api|contract|schema/i
-      ],
-      debugging: [
-        /bug|error|fix|issue|problem|debug/i,
-        /trace|stack|exception|fail/i
-      ],
-      review: [
-        /review|audit|check|quality|standard/i,
-        /security|vulnerability|code.*smell/i
-      ],
-      documentation: [
-        /document|docs|readme|guide|tutorial/i,
-        /explain|describe|comment/i
-      ],
-      optimization: [
-        /optimiz|performance|speed|efficient/i,
-        /benchmark|profile|memory|token/i
-      ]
-    };
-  }
-
-  async analyzeTask(context) {
-    const analysis = {
-      command: context.command,
-      recentFiles: await this.getRecentFiles(),
-      keywords: this.extractKeywords(context),
-      gitContext: await this.getGitContext(),
-      errorState: await this.checkErrorState()
-    };
-
-    // Score each persona category
-    analysis.scores = {};
-    for (const [persona, patterns] of Object.entries(this.patterns)) {
-      analysis.scores[persona] = this.calculatePatternScore(
-        analysis,
-        patterns
-      );
-    }
-
-    return analysis;
-  }
-
-  calculatePatternScore(analysis, patterns) {
-    let score = 0;
-    
-    // Check command
-    patterns.forEach(pattern => {
-      if (pattern.test(analysis.command)) score += 10;
-    });
-
-    // Check keywords
-    analysis.keywords.forEach(keyword => {
-      patterns.forEach(pattern => {
-        if (pattern.test(keyword)) score += 5;
-      });
-    });
-
-    // Context bonuses
-    if (analysis.errorState.hasErrors && patterns.some(p => p.test('debug'))) {
-      score += 20;
-    }
-
-    return score;
-  }
-}
-```
-
-### Phase 3: Metrics Collection
-
-#### 3.1 Metrics Collector
-
-```javascript
-class MetricsCollector {
-  constructor() {
-    this.metrics = {
-      sessions: [],
-      personaPerformance: {},
-      taskOutcomes: []
-    };
-    this.currentSession = null;
-  }
-
-  startSession(persona, task) {
-    this.currentSession = {
-      id: generateId(),
-      persona: persona.name,
-      task: task,
-      startTime: Date.now(),
-      events: [],
-      tokenUsage: {
-        start: this.getCurrentTokenCount(),
-        contextSwitches: 0
-      }
-    };
-  }
-
-  trackEvent(eventType, data) {
-    if (!this.currentSession) return;
-    
-    this.currentSession.events.push({
-      type: eventType,
-      timestamp: Date.now(),
-      data
-    });
-
-    // Special handling for quality events
-    if (eventType === 'task_completed') {
-      this.calculateQualityMetrics(data);
-    }
-  }
-
-  async calculateQualityMetrics(completionData) {
-    const metrics = {
-      completionTime: Date.now() - this.currentSession.startTime,
-      tokenEfficiency: this.calculateTokenEfficiency(),
-      errorRate: await this.calculateErrorRate(),
-      codeQuality: await this.assessCodeQuality(completionData),
-      userSatisfaction: null // To be collected via feedback
-    };
-
-    this.currentSession.qualityMetrics = metrics;
-    this.updatePersonaPerformance(this.currentSession.persona, metrics);
-  }
-
-  calculateTokenEfficiency() {
-    const totalTokens = this.getCurrentTokenCount() - 
-                       this.currentSession.tokenUsage.start;
-    const taskComplexity = this.estimateTaskComplexity();
-    
-    return {
-      totalUsed: totalTokens,
-      efficiency: taskComplexity / totalTokens,
-      contextSwitches: this.currentSession.tokenUsage.contextSwitches
-    };
-  }
-
-  async generateReport(timeRange = 'week') {
-    const report = {
-      summary: {
-        totalSessions: this.metrics.sessions.length,
-        averageCompletionTime: this.calculateAverageTime(),
-        personaUsage: this.getPersonaUsageStats(),
-        qualityTrend: this.calculateQualityTrend()
-      },
-      personaAnalysis: this.analyzePersonaEffectiveness(),
-      recommendations: this.generateRecommendations()
-    };
-
-    return report;
-  }
-
-  analyzePersonaEffectiveness() {
-    const analysis = {};
-    
-    for (const [persona, data] of Object.entries(this.metrics.personaPerformance)) {
-      analysis[persona] = {
-        averageCompletionTime: average(data.completionTimes),
-        averageQualityScore: average(data.qualityScores),
-        tokenEfficiency: average(data.tokenEfficiencies),
-        bestUseCases: this.identifyBestUseCases(persona),
-        improvementAreas: this.identifyImprovementAreas(persona)
-      };
-    }
-
-    return analysis;
-  }
-}
-```
-
-### Phase 4: Integration Points
-
-#### 4.1 Claude Command Integration
-
-```javascript
-// In .claude/commands/aiwf/persona-commands.js
-
-export const personaCommands = {
-  '/project:aiwf:ai_persona:switch': async (personaName) => {
-    const manager = getPersonaManager();
-    await manager.switchPersona(personaName, { manual: true });
-    return `Switched to ${personaName} persona`;
-  },
-
-  '/project:aiwf:ai_persona:auto': async (enabled) => {
-    const manager = getPersonaManager();
-    manager.autoDetectionEnabled = enabled;
-    return `Auto-detection ${enabled ? 'enabled' : 'disabled'}`;
-  },
-
-  '/project:aiwf:ai_persona:status': async () => {
-    const manager = getPersonaManager();
-    const current = manager.currentPersona;
-    const metrics = await manager.metricsCollector.getCurrentSessionMetrics();
-    
-    return formatPersonaStatus(current, metrics);
-  },
-
-  '/project:aiwf:ai_persona:report': async (timeRange) => {
-    const manager = getPersonaManager();
-    const report = await manager.metricsCollector.generateReport(timeRange);
-    
-    return formatPersonaReport(report);
-  }
-};
-```
-
-#### 4.2 Git Hook Integration
-
-```bash
-#!/bin/bash
-# .git/hooks/post-commit
-
-# Detect if this was a bug fix
-if git log -1 --pretty=%B | grep -qiE "fix|bug|error"; then
-  # Suggest debugger persona for follow-up
-  echo "💡 Tip: Switch to debugger persona for thorough testing"
-  echo "   /project:aiwf:ai_persona:debugger"
-fi
-
-# Track commit patterns for persona optimization
-aiwf-persona track-commit
-```
-
-## Performance Optimization
-
-### Token Management Strategy
-
-1. **Base Allocation**: Each persona has a suggested token budget
-   - Architect: 30% context, 70% response
-   - Debugger: 50% context, 50% response  
-   - Reviewer: 40% context, 60% response
-   - Documenter: 20% context, 80% response
-   - Optimizer: 60% context, 40% response
-
-2. **Dynamic Adjustment**: Based on task complexity
-   - Simple tasks: -20% tokens
-   - Complex tasks: +30% tokens
-   - Multi-file tasks: +50% tokens
-
-3. **Context Pruning**: Remove irrelevant information
-   - Architect: Prune implementation details
-   - Debugger: Prune documentation
-   - Reviewer: Prune test files
-   - Documenter: Prune internal logic
-   - Optimizer: Prune comments
-
-## Testing Strategy
-
-### Unit Tests
-
-```javascript
-describe('PersonaManager', () => {
-  test('switches personas correctly', async () => {
-    const manager = new PersonaManager();
-    await manager.switchPersona('architect');
-    
-    expect(manager.currentPersona.name).toBe('architect');
-    expect(manager.personaHistory).toHaveLength(0);
-  });
-
-  test('detects optimal persona', async () => {
-    const manager = new PersonaManager();
-    const taskContext = {
-      command: 'debug the login error',
-      recentFiles: ['auth.js', 'login.test.js']
-    };
-    
-    const optimal = await manager.detectOptimalPersona(taskContext);
-    expect(optimal).toBe('debugger');
-  });
-});
-```
-
-### Integration Tests
-
-```javascript
-describe('Persona System Integration', () => {
-  test('full workflow with auto-detection', async () => {
-    // Initialize system
-    const system = await initializePersonaSystem();
-    
-    // Simulate task
-    const task = {
-      type: 'bug_fix',
-      description: 'Fix authentication timeout'
-    };
-    
-    // Start task
-    await system.startTask(task);
-    
-    // Verify persona selection
-    expect(system.currentPersona.name).toBe('debugger');
-    
-    // Complete task
-    const result = await system.completeTask({
-      success: true,
-      filesModified: ['auth.js']
-    });
-    
-    // Verify metrics collected
-    expect(result.metrics).toHaveProperty('completionTime');
-    expect(result.metrics).toHaveProperty('tokenEfficiency');
-  });
-});
-```
-
-## Rollout Plan
-
-### Phase 1: Beta (Week 1-2)
-- Core PersonaManager implementation
-- Manual switching only
-- Basic metrics collection
-
-### Phase 2: Auto-Detection (Week 3-4)
-- Task analyzer implementation
-- Auto-detection with manual override
-- Enhanced context engine
-
-### Phase 3: Metrics & Optimization (Week 5-6)
-- Full metrics collection
-- Performance reports
-- Token optimization
-
-### Phase 4: Production (Week 7+)
-- Public release
-- User feedback collection
-- Continuous improvement
-
-## Success Metrics
-
-1. **Adoption Rate**: >70% of users actively using personas
-2. **Task Completion Time**: 20% reduction on average
-3. **Token Efficiency**: 30% improvement
-4. **User Satisfaction**: >4.5/5 rating
-5. **Auto-Detection Accuracy**: >85% correct persona selection
-
-## Future Enhancements
-
-1. **Custom Personas**: User-defined personas
-2. **Team Personas**: Shared team configurations
-3. **Learning System**: ML-based persona optimization
-4. **IDE Integration**: Direct VS Code/Cursor integration
-5. **Persona Marketplace**: Community-shared personas