aios-core 2.1.6 → 2.2.0

package/.aios-core/development/tasks/analyze-framework.md

@@ -1,697 +1,697 @@
-# Task: Analyze Framework
-
-## Description
-Performs comprehensive analysis of the AIOS-FULLSTACK framework to identify improvement opportunities, performance bottlenecks, component redundancies, and usage patterns.
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: analyzeFramework()
-responsável: Aria (Visionary)
-responsavel_type: Agente
-atomic_layer: Strategy
-
-**Entrada:**
-- campo: target
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Valid path or identifier
-
-- campo: options
-  tipo: object
-  origem: config
-  obrigatório: false
-  validação: Analysis configuration
-
-- campo: depth
-  tipo: number
-  origem: User Input
-  obrigatório: false
-  validação: Default: 1 (0-3)
-
-**Saída:**
-- campo: analysis_report
-  tipo: object
-  destino: File (.ai/*.json)
-  persistido: true
-
-- campo: findings
-  tipo: array
-  destino: Memory
-  persistido: false
-
-- campo: metrics
-  tipo: object
-  destino: Memory
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Target exists and is accessible; analysis tools available
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check target exists and is accessible; analysis tools available
-    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Analysis complete; report generated; no critical issues
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify analysis complete; report generated; no critical issues
-    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Analysis accurate; all targets covered; report complete
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert analysis accurate; all targets covered; report complete
-    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** code-analyzer
-  - **Purpose:** Static code analysis and metrics
-  - **Source:** .aios-core/utils/code-analyzer.js
-
-- **Tool:** file-system
-  - **Purpose:** Recursive directory traversal
-  - **Source:** Node.js fs module
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** analyze-codebase.js
-  - **Purpose:** Codebase analysis and reporting
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/analyze-codebase.js
-
----
-
-## Error Handling
-
-**Strategy:** fallback
-
-**Common Errors:**
-
-1. **Error:** Target Not Accessible
-   - **Cause:** Path does not exist or permissions denied
-   - **Resolution:** Verify path and check permissions
-   - **Recovery:** Skip inaccessible paths, continue with accessible ones
-
-2. **Error:** Analysis Timeout
-   - **Cause:** Analysis exceeds time limit for large codebases
-   - **Resolution:** Reduce analysis depth or scope
-   - **Recovery:** Return partial results with timeout warning
-
-3. **Error:** Memory Limit Exceeded
-   - **Cause:** Large codebase exceeds memory allocation
-   - **Resolution:** Process in batches or increase memory limit
-   - **Recovery:** Graceful degradation to summary analysis
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-20 min (estimated)
-cost_estimated: $0.003-0.015
-token_usage: ~2,000-8,000 tokens
-```
-
-**Optimization Notes:**
-- Iterative analysis with depth limits; cache intermediate results; batch similar operations
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - analysis
-  - metrics
-updated_at: 2025-11-17
-```
-
----
-
-
-## Type
-Analysis Task
-
-## Complexity
-High
-
-## Categories
-- framework-analysis
-- performance-optimization
-- code-quality
-
-## Dependencies
-- component-search.js (for component discovery)
-- usage-analytics.js (for usage pattern analysis)
-- performance-analyzer.js (for bottleneck detection)
-- redundancy-analyzer.js (for overlap detection)
-- improvement-engine.js (for suggestion generation)
-
-## Parameters
-- `scope` (string, optional): Analysis scope - 'full', 'agents', 'tasks', 'workflows', 'utils' (default: 'full')
-- `output_format` (string, optional): Output format - 'detailed', 'summary', 'json' (default: 'detailed')
-- `include_metrics` (boolean, optional): Include performance metrics (default: true)
-- `include_suggestions` (boolean, optional): Include improvement suggestions (default: true)
-- `save_report` (boolean, optional): Save report to file (default: true)
-
-## Implementation
-
-```javascript
-const FrameworkAnalyzer = require('../scripts/framework-analyzer');
-const UsageAnalytics = require('../scripts/usage-analytics');
-const PerformanceAnalyzer = require('../scripts/performance-analyzer');
-// const RedundancyAnalyzer = require('../scripts/redundancy-analyzer'); // Archived - Story 3.1.4
-const ImprovementEngine = require('../scripts/improvement-engine');
-const fs = require('fs').promises;
-const path = require('path');
-const chalk = require('chalk');
-
-module.exports = {
-  name: 'analyze-framework',
-  description: 'Performs comprehensive framework analysis with improvement recommendations',
-  
-  async execute(params) {
-    const {
-      scope = 'full',
-      output_format = 'detailed',
-      include_metrics = true,
-      include_suggestions = true,
-      save_report = true
-    } = params;
-
-    console.log(chalk.blue('🔍 Starting framework analysis...'));
-    console.log(chalk.gray(`   Scope: ${scope}`));
-    console.log(chalk.gray(`   Format: ${output_format}`));
-
-    const analysis = {
-      timestamp: new Date().toISOString(),
-      scope,
-      framework_info: {},
-      component_analysis: {},
-      usage_analytics: {},
-      performance_analysis: {},
-      redundancy_analysis: {},
-      improvement_suggestions: [],
-      summary: {}
-    };
-
-    try {
-      // Initialize analyzers
-      const frameworkAnalyzer = new FrameworkAnalyzer({ rootPath: process.cwd() });
-      const usageAnalytics = new UsageAnalytics({ rootPath: process.cwd() });
-      const performanceAnalyzer = new PerformanceAnalyzer({ rootPath: process.cwd() });
-      // const redundancyAnalyzer = new RedundancyAnalyzer({ rootPath: process.cwd() }); // Archived - Story 3.1.4
-      const improvementEngine = new ImprovementEngine({ rootPath: process.cwd() });
-
-      // Step 1: Discover and catalog framework components
-      console.log(chalk.blue('📊 Discovering framework components...'));
-      analysis.framework_info = await frameworkAnalyzer.analyzeFrameworkStructure(scope);
-      
-      console.log(chalk.gray(`   Found: ${analysis.framework_info.total_components} components`));
-      console.log(chalk.gray(`   Agents: ${analysis.framework_info.agents?.length || 0}`));
-      console.log(chalk.gray(`   Tasks: ${analysis.framework_info.tasks?.length || 0}`));
-      console.log(chalk.gray(`   Workflows: ${analysis.framework_info.workflows?.length || 0}`));
-      console.log(chalk.gray(`   Utils: ${analysis.framework_info.utils?.length || 0}`));
-
-      // Step 2: Analyze component usage patterns
-      console.log(chalk.blue('📈 Analyzing usage patterns...'));
-      analysis.usage_analytics = await usageAnalytics.analyzeUsagePatterns(
-        analysis.framework_info.components
-      );
-
-      // Step 3: Performance bottleneck detection
-      if (include_metrics) {
-        console.log(chalk.blue('⚡ Detecting performance bottlenecks...'));
-        analysis.performance_analysis = await performanceAnalyzer.analyzePerformance(
-          analysis.framework_info.components
-        );
-      }
-
-      // Step 4: Redundancy and overlap analysis
-      // console.log(chalk.blue('🔄 Analyzing redundancies and overlaps...'));
-      // analysis.redundancy_analysis = await redundancyAnalyzer.analyzeRedundancy(
-      //   analysis.framework_info.components
-      // ); // Archived - Story 3.1.4
-
-      // Step 5: Generate improvement suggestions
-      if (include_suggestions) {
-        console.log(chalk.blue('💡 Generating improvement suggestions...'));
-        analysis.improvement_suggestions = await improvementEngine.generateSuggestions({
-          components: analysis.framework_info.components,
-          usage: analysis.usage_analytics,
-          performance: analysis.performance_analysis
-          // redundancy: analysis.redundancy_analysis // Archived - Story 3.1.4
-        });
-      }
-
-      // Step 6: Generate summary
-      analysis.summary = this.generateSummary(analysis);
-
-      // Step 7: Format and display results
-      await this.displayResults(analysis, output_format);
-
-      // Step 8: Save report
-      if (save_report) {
-        const reportPath = await this.saveReport(analysis);
-        console.log(chalk.green(`📋 Report saved: ${reportPath}`));
-      }
-
-      console.log(chalk.green('✅ Framework analysis completed'));
-      
-      return {
-        success: true,
-        analysis,
-        suggestions_count: analysis.improvement_suggestions.length,
-        critical_issues: analysis.summary.critical_issues || 0,
-        performance_score: analysis.summary.performance_score || 'N/A'
-      };
-
-    } catch (error) {
-      console.error(chalk.red(`Framework analysis failed: ${error.message}`));
-      
-      return {
-        success: false,
-        error: error.message,
-        partial_analysis: analysis
-      };
-    }
-  },
-
-  /**
-   * Generate analysis summary
-   */
-  generateSummary(analysis) {
-    const summary = {
-      total_components: analysis.framework_info.total_components || 0,
-      health_score: 0,
-      critical_issues: 0,
-      warnings: 0,
-      recommendations: 0,
-      performance_score: 'N/A',
-      redundancy_level: 'low',
-      usage_efficiency: 0,
-      top_concerns: [],
-      strengths: []
-    };
-
-    // Calculate health score
-    let healthPoints = 100;
-    
-    if (analysis.redundancy_analysis.redundant_components) {
-      const redundancyPenalty = analysis.redundancy_analysis.redundant_components.length * 5;
-      healthPoints -= redundancyPenalty;
-      summary.critical_issues += analysis.redundancy_analysis.redundant_components.length;
-    }
-
-    if (analysis.performance_analysis.bottlenecks) {
-      const performancePenalty = analysis.performance_analysis.bottlenecks.length * 10;
-      healthPoints -= performancePenalty;
-      summary.critical_issues += analysis.performance_analysis.bottlenecks.length;
-    }
-
-    if (analysis.usage_analytics.unused_components) {
-      const unusedPenalty = analysis.usage_analytics.unused_components.length * 3;
-      healthPoints -= unusedPenalty;
-      summary.warnings += analysis.usage_analytics.unused_components.length;
-    }
-
-    summary.health_score = Math.max(0, Math.min(100, healthPoints));
-    summary.recommendations = analysis.improvement_suggestions.length;
-
-    // Performance score
-    if (analysis.performance_analysis.overall_score) {
-      summary.performance_score = analysis.performance_analysis.overall_score;
-    }
-
-    // Usage efficiency
-    if (analysis.usage_analytics.efficiency_score) {
-      summary.usage_efficiency = analysis.usage_analytics.efficiency_score;
-    }
-
-    // Redundancy level
-    if (analysis.redundancy_analysis.redundancy_level) {
-      summary.redundancy_level = analysis.redundancy_analysis.redundancy_level;
-    }
-
-    // Top concerns
-    if (analysis.performance_analysis.bottlenecks?.length > 0) {
-      summary.top_concerns.push('Performance bottlenecks detected');
-    }
-    
-    if (analysis.redundancy_analysis.redundant_components?.length > 0) {
-      summary.top_concerns.push('Code redundancy found');
-    }
-    
-    if (analysis.usage_analytics.unused_components?.length > 0) {
-      summary.top_concerns.push('Unused components detected');
-    }
-
-    // Strengths
-    if (summary.health_score >= 90) {
-      summary.strengths.push('Overall framework health excellent');
-    }
-    
-    if (summary.performance_score >= 8) {
-      summary.strengths.push('Good performance characteristics');
-    }
-    
-    if (summary.usage_efficiency >= 85) {
-      summary.strengths.push('High component utilization');
-    }
-
-    return summary;
-  },
-
-  /**
-   * Display analysis results
-   */
-  async displayResults(analysis, format) {
-    switch (format) {
-      case 'summary':
-        this.displaySummary(analysis);
-        break;
-      case 'json':
-        console.log(JSON.stringify(analysis, null, 2));
-        break;
-      case 'detailed':
-      default:
-        this.displayDetailed(analysis);
-        break;
-    }
-  },
-
-  /**
-   * Display summary format
-   */
-  displaySummary(analysis) {
-    const { summary } = analysis;
-    
-    console.log(chalk.bold('\n📊 Framework Analysis Summary'));
-    console.log(chalk.gray('─'.repeat(50)));
-    
-    // Health score with color coding
-    const healthColor = summary.health_score >= 80 ? 'green' : 
-                       summary.health_score >= 60 ? 'yellow' : 'red';
-    console.log(`Health Score: ${chalk[healthColor](summary.health_score + '/100')}`);
-    
-    console.log(`Components: ${summary.total_components}`);
-    console.log(`Critical Issues: ${chalk.red(summary.critical_issues)}`);
-    console.log(`Warnings: ${chalk.yellow(summary.warnings)}`);
-    console.log(`Recommendations: ${chalk.blue(summary.recommendations)}`);
-    
-    if (summary.performance_score !== 'N/A') {
-      console.log(`Performance: ${chalk.cyan(summary.performance_score + '/10')}`);
-    }
-    
-    console.log(`Usage Efficiency: ${chalk.cyan(summary.usage_efficiency + '%')}`);
-    console.log(`Redundancy Level: ${chalk.magenta(summary.redundancy_level)}`);
-
-    // Top concerns
-    if (summary.top_concerns.length > 0) {
-      console.log('\n🚨 Top Concerns:');
-      summary.top_concerns.forEach(concern => {
-        console.log(`  • ${chalk.red(concern)}`);
-      });
-    }
-
-    // Strengths
-    if (summary.strengths.length > 0) {
-      console.log('\n✅ Strengths:');
-      summary.strengths.forEach(strength => {
-        console.log(`  • ${chalk.green(strength)}`);
-      });
-    }
-  },
-
-  /**
-   * Display detailed format
-   */
-  displayDetailed(analysis) {
-    this.displaySummary(analysis);
-    
-    // Component breakdown
-    console.log(chalk.bold('\n📋 Component Analysis'));
-    console.log(chalk.gray('─'.repeat(50)));
-    
-    if (analysis.framework_info.agents) {
-      console.log(`Agents (${analysis.framework_info.agents.length}):`);
-      analysis.framework_info.agents.slice(0, 5).forEach(agent => {
-        console.log(`  • ${chalk.cyan(agent.name)} - ${agent.description || 'No description'}`);
-      });
-      if (analysis.framework_info.agents.length > 5) {
-        console.log(`  ... and ${analysis.framework_info.agents.length - 5} more`);
-      }
-    }
-
-    // Performance issues
-    if (analysis.performance_analysis.bottlenecks?.length > 0) {
-      console.log(chalk.bold('\n⚡ Performance Bottlenecks'));
-      console.log(chalk.gray('─'.repeat(50)));
-      
-      analysis.performance_analysis.bottlenecks.slice(0, 3).forEach(bottleneck => {
-        console.log(`  • ${chalk.red(bottleneck.component)}: ${bottleneck.issue}`);
-        console.log(`    Impact: ${chalk.yellow(bottleneck.impact)} | Effort: ${bottleneck.effort}`);
-      });
-    }
-
-    // Redundancy issues
-    if (analysis.redundancy_analysis.redundant_components?.length > 0) {
-      console.log(chalk.bold('\n🔄 Redundant Components'));
-      console.log(chalk.gray('─'.repeat(50)));
-      
-      analysis.redundancy_analysis.redundant_components.slice(0, 3).forEach(redundancy => {
-        console.log(`  • ${chalk.red(redundancy.component1)} ↔️ ${redundancy.component2}`);
-        console.log(`    Similarity: ${chalk.yellow(redundancy.similarity + '%')} | Type: ${redundancy.type}`);
-      });
-    }
-
-    // Top suggestions
-    if (analysis.improvement_suggestions.length > 0) {
-      console.log(chalk.bold('\n💡 Top Improvement Suggestions'));
-      console.log(chalk.gray('─'.repeat(50)));
-      
-      analysis.improvement_suggestions
-        .sort((a, b) => (b.priority_score || 0) - (a.priority_score || 0))
-        .slice(0, 5)
-        .forEach((suggestion, index) => {
-          const priorityColor = suggestion.priority === 'high' ? 'red' : 
-                               suggestion.priority === 'medium' ? 'yellow' : 'gray';
-          console.log(`  ${index + 1}. ${chalk[priorityColor](suggestion.title)}`);
-          console.log(`     ${suggestion.description}`);
-          console.log(`     Impact: ${chalk.cyan(suggestion.impact)} | Effort: ${suggestion.effort}`);
-        });
-    }
-  },
-
-  /**
-   * Save analysis report
-   */
-  async saveReport(analysis) {
-    const reportsDir = path.join(process.cwd(), '.aios', 'reports');
-    await fs.mkdir(reportsDir, { recursive: true });
-    
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const reportPath = path.join(reportsDir, `framework-analysis-${timestamp}.json`);
-    
-    await fs.writeFile(reportPath, JSON.stringify(analysis, null, 2));
-    
-    // Also save a human-readable summary
-    const summaryPath = path.join(reportsDir, `framework-analysis-summary-${timestamp}.md`);
-    const summaryContent = this.generateMarkdownSummary(analysis);
-    await fs.writeFile(summaryPath, summaryContent);
-    
-    return reportPath;
-  },
-
-  /**
-   * Generate markdown summary
-   */
-  generateMarkdownSummary(analysis) {
-    const { summary } = analysis;
-    
-    return `# Framework Analysis Report
-
-**Generated:** ${new Date(analysis.timestamp).toLocaleString()}
-**Scope:** ${analysis.scope}
-
-## Summary
-
-- **Health Score:** ${summary.health_score}/100
-- **Components:** ${summary.total_components}
-- **Critical Issues:** ${summary.critical_issues}
-- **Warnings:** ${summary.warnings}
-- **Recommendations:** ${summary.recommendations}
-- **Performance Score:** ${summary.performance_score}
-- **Usage Efficiency:** ${summary.usage_efficiency}%
-- **Redundancy Level:** ${summary.redundancy_level}
-
-## Top Concerns
-
-${summary.top_concerns.map(concern => `- ${concern}`).join('\n') || 'None identified'}
-
-## Strengths
-
-${summary.strengths.map(strength => `- ${strength}`).join('\n') || 'None identified'}
-
-## Key Metrics
-
-### Component Distribution
-- Agents: ${analysis.framework_info.agents?.length || 0}
-- Tasks: ${analysis.framework_info.tasks?.length || 0}
-- Workflows: ${analysis.framework_info.workflows?.length || 0}
-- Utils: ${analysis.framework_info.utils?.length || 0}
-
-### Performance Analysis
-${analysis.performance_analysis.bottlenecks?.length > 0 ? 
-  `**Bottlenecks Found:** ${analysis.performance_analysis.bottlenecks.length}\n\n` +
-  analysis.performance_analysis.bottlenecks.slice(0, 3).map(b => 
-    `- **${b.component}:** ${b.issue} (Impact: ${b.impact})`
-  ).join('\n') : 'No significant bottlenecks detected'}
-
-### Redundancy Analysis
-${analysis.redundancy_analysis.redundant_components?.length > 0 ?
-  `**Redundant Components:** ${analysis.redundancy_analysis.redundant_components.length}\n\n` +
-  analysis.redundancy_analysis.redundant_components.slice(0, 3).map(r =>
-    `- **${r.component1}** ↔️ **${r.component2}** (${r.similarity}% similar)`
-  ).join('\n') : 'No significant redundancy detected'}
-
-## Top Improvement Suggestions
-
-${analysis.improvement_suggestions.slice(0, 5).map((suggestion, index) => 
-  `${index + 1}. **${suggestion.title}** (${suggestion.priority})
-   - ${suggestion.description}
-   - Impact: ${suggestion.impact} | Effort: ${suggestion.effort}`
-).join('\n\n') || 'No suggestions generated'}
-
----
-*Report generated by AIOS Framework Analyzer*
-`;
-  }
-};
-```
-
-## Usage Examples
-
-### Basic Analysis
-```bash
-*analyze-framework
-```
-
-### Scope-specific Analysis
-```bash
-*analyze-framework scope=agents
-*analyze-framework scope=utils include_suggestions=false
-```
-
-### Summary Output
-```bash
-*analyze-framework output_format=summary
-```
-
-### Performance-focused Analysis
-```bash
-*analyze-framework include_metrics=true output_format=detailed
-```
-
-## Expected Output
-
-The analysis provides:
-
-1. **Framework Structure Overview**: Complete inventory of components
-2. **Usage Analytics**: Pattern analysis and utilization metrics
-3. **Performance Analysis**: Bottleneck identification and recommendations
-4. **Redundancy Detection**: Overlapping functionality identification
-5. **Improvement Suggestions**: Prioritized recommendations for enhancement
-6. **Health Score**: Overall framework quality assessment
-7. **Detailed Reports**: JSON and Markdown formats for future reference
-
-## Security Considerations
-
-- Read-only analysis - no modifications made to framework
-- Safe file system scanning with permission checks
-- Memory usage monitoring for large codebases
-- Configurable analysis depth to prevent performance issues
-
-## Integration
-
-Works seamlessly with:
-- `*improve-self` command for implementing suggestions
-- Memory layer for storing analysis history
-- Version control for tracking improvements
+# Task: Analyze Framework
+
+## Description
+Performs comprehensive analysis of the Synkra AIOS framework to identify improvement opportunities, performance bottlenecks, component redundancies, and usage patterns.
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: analyzeFramework()
+responsável: Aria (Visionary)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or identifier
+
+- campo: options
+  tipo: object
+  origem: config
+  obrigatório: false
+  validação: Analysis configuration
+
+- campo: depth
+  tipo: number
+  origem: User Input
+  obrigatório: false
+  validação: Default: 1 (0-3)
+
+**Saída:**
+- campo: analysis_report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+
+- campo: findings
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: metrics
+  tipo: object
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target exists and is accessible; analysis tools available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target exists and is accessible; analysis tools available
+    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis complete; report generated; no critical issues
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify analysis complete; report generated; no critical issues
+    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Analysis accurate; all targets covered; report complete
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert analysis accurate; all targets covered; report complete
+    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** code-analyzer
+  - **Purpose:** Static code analysis and metrics
+  - **Source:** .aios-core/utils/code-analyzer.js
+
+- **Tool:** file-system
+  - **Purpose:** Recursive directory traversal
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** analyze-codebase.js
+  - **Purpose:** Codebase analysis and reporting
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/analyze-codebase.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Target Not Accessible
+   - **Cause:** Path does not exist or permissions denied
+   - **Resolution:** Verify path and check permissions
+   - **Recovery:** Skip inaccessible paths, continue with accessible ones
+
+2. **Error:** Analysis Timeout
+   - **Cause:** Analysis exceeds time limit for large codebases
+   - **Resolution:** Reduce analysis depth or scope
+   - **Recovery:** Return partial results with timeout warning
+
+3. **Error:** Memory Limit Exceeded
+   - **Cause:** Large codebase exceeds memory allocation
+   - **Resolution:** Process in batches or increase memory limit
+   - **Recovery:** Graceful degradation to summary analysis
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - analysis
+  - metrics
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Type
+Analysis Task
+
+## Complexity
+High
+
+## Categories
+- framework-analysis
+- performance-optimization
+- code-quality
+
+## Dependencies
+- component-search.js (for component discovery)
+- usage-analytics.js (for usage pattern analysis)
+- performance-analyzer.js (for bottleneck detection)
+- redundancy-analyzer.js (for overlap detection)
+- improvement-engine.js (for suggestion generation)
+
+## Parameters
+- `scope` (string, optional): Analysis scope - 'full', 'agents', 'tasks', 'workflows', 'utils' (default: 'full')
+- `output_format` (string, optional): Output format - 'detailed', 'summary', 'json' (default: 'detailed')
+- `include_metrics` (boolean, optional): Include performance metrics (default: true)
+- `include_suggestions` (boolean, optional): Include improvement suggestions (default: true)
+- `save_report` (boolean, optional): Save report to file (default: true)
+
+## Implementation
+
+```javascript
+const FrameworkAnalyzer = require('../scripts/framework-analyzer');
+const UsageAnalytics = require('../scripts/usage-analytics');
+const PerformanceAnalyzer = require('../scripts/performance-analyzer');
+// const RedundancyAnalyzer = require('../scripts/redundancy-analyzer'); // Archived - Story 3.1.4
+const ImprovementEngine = require('../scripts/improvement-engine');
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+
+module.exports = {
+  name: 'analyze-framework',
+  description: 'Performs comprehensive framework analysis with improvement recommendations',
+  
+  async execute(params) {
+    const {
+      scope = 'full',
+      output_format = 'detailed',
+      include_metrics = true,
+      include_suggestions = true,
+      save_report = true
+    } = params;
+
+    console.log(chalk.blue('🔍 Starting framework analysis...'));
+    console.log(chalk.gray(`   Scope: ${scope}`));
+    console.log(chalk.gray(`   Format: ${output_format}`));
+
+    const analysis = {
+      timestamp: new Date().toISOString(),
+      scope,
+      framework_info: {},
+      component_analysis: {},
+      usage_analytics: {},
+      performance_analysis: {},
+      redundancy_analysis: {},
+      improvement_suggestions: [],
+      summary: {}
+    };
+
+    try {
+      // Initialize analyzers
+      const frameworkAnalyzer = new FrameworkAnalyzer({ rootPath: process.cwd() });
+      const usageAnalytics = new UsageAnalytics({ rootPath: process.cwd() });
+      const performanceAnalyzer = new PerformanceAnalyzer({ rootPath: process.cwd() });
+      // const redundancyAnalyzer = new RedundancyAnalyzer({ rootPath: process.cwd() }); // Archived - Story 3.1.4
+      const improvementEngine = new ImprovementEngine({ rootPath: process.cwd() });
+
+      // Step 1: Discover and catalog framework components
+      console.log(chalk.blue('📊 Discovering framework components...'));
+      analysis.framework_info = await frameworkAnalyzer.analyzeFrameworkStructure(scope);
+      
+      console.log(chalk.gray(`   Found: ${analysis.framework_info.total_components} components`));
+      console.log(chalk.gray(`   Agents: ${analysis.framework_info.agents?.length || 0}`));
+      console.log(chalk.gray(`   Tasks: ${analysis.framework_info.tasks?.length || 0}`));
+      console.log(chalk.gray(`   Workflows: ${analysis.framework_info.workflows?.length || 0}`));
+      console.log(chalk.gray(`   Utils: ${analysis.framework_info.utils?.length || 0}`));
+
+      // Step 2: Analyze component usage patterns
+      console.log(chalk.blue('📈 Analyzing usage patterns...'));
+      analysis.usage_analytics = await usageAnalytics.analyzeUsagePatterns(
+        analysis.framework_info.components
+      );
+
+      // Step 3: Performance bottleneck detection
+      if (include_metrics) {
+        console.log(chalk.blue('⚡ Detecting performance bottlenecks...'));
+        analysis.performance_analysis = await performanceAnalyzer.analyzePerformance(
+          analysis.framework_info.components
+        );
+      }
+
+      // Step 4: Redundancy and overlap analysis
+      // console.log(chalk.blue('🔄 Analyzing redundancies and overlaps...'));
+      // analysis.redundancy_analysis = await redundancyAnalyzer.analyzeRedundancy(
+      //   analysis.framework_info.components
+      // ); // Archived - Story 3.1.4
+
+      // Step 5: Generate improvement suggestions
+      if (include_suggestions) {
+        console.log(chalk.blue('💡 Generating improvement suggestions...'));
+        analysis.improvement_suggestions = await improvementEngine.generateSuggestions({
+          components: analysis.framework_info.components,
+          usage: analysis.usage_analytics,
+          performance: analysis.performance_analysis
+          // redundancy: analysis.redundancy_analysis // Archived - Story 3.1.4
+        });
+      }
+
+      // Step 6: Generate summary
+      analysis.summary = this.generateSummary(analysis);
+
+      // Step 7: Format and display results
+      await this.displayResults(analysis, output_format);
+
+      // Step 8: Save report
+      if (save_report) {
+        const reportPath = await this.saveReport(analysis);
+        console.log(chalk.green(`📋 Report saved: ${reportPath}`));
+      }
+
+      console.log(chalk.green('✅ Framework analysis completed'));
+      
+      return {
+        success: true,
+        analysis,
+        suggestions_count: analysis.improvement_suggestions.length,
+        critical_issues: analysis.summary.critical_issues || 0,
+        performance_score: analysis.summary.performance_score || 'N/A'
+      };
+
+    } catch (error) {
+      console.error(chalk.red(`Framework analysis failed: ${error.message}`));
+      
+      return {
+        success: false,
+        error: error.message,
+        partial_analysis: analysis
+      };
+    }
+  },
+
+  /**
+   * Generate analysis summary
+   */
+  generateSummary(analysis) {
+    const summary = {
+      total_components: analysis.framework_info.total_components || 0,
+      health_score: 0,
+      critical_issues: 0,
+      warnings: 0,
+      recommendations: 0,
+      performance_score: 'N/A',
+      redundancy_level: 'low',
+      usage_efficiency: 0,
+      top_concerns: [],
+      strengths: []
+    };
+
+    // Calculate health score
+    let healthPoints = 100;
+    
+    if (analysis.redundancy_analysis.redundant_components) {
+      const redundancyPenalty = analysis.redundancy_analysis.redundant_components.length * 5;
+      healthPoints -= redundancyPenalty;
+      summary.critical_issues += analysis.redundancy_analysis.redundant_components.length;
+    }
+
+    if (analysis.performance_analysis.bottlenecks) {
+      const performancePenalty = analysis.performance_analysis.bottlenecks.length * 10;
+      healthPoints -= performancePenalty;
+      summary.critical_issues += analysis.performance_analysis.bottlenecks.length;
+    }
+
+    if (analysis.usage_analytics.unused_components) {
+      const unusedPenalty = analysis.usage_analytics.unused_components.length * 3;
+      healthPoints -= unusedPenalty;
+      summary.warnings += analysis.usage_analytics.unused_components.length;
+    }
+
+    summary.health_score = Math.max(0, Math.min(100, healthPoints));
+    summary.recommendations = analysis.improvement_suggestions.length;
+
+    // Performance score
+    if (analysis.performance_analysis.overall_score) {
+      summary.performance_score = analysis.performance_analysis.overall_score;
+    }
+
+    // Usage efficiency
+    if (analysis.usage_analytics.efficiency_score) {
+      summary.usage_efficiency = analysis.usage_analytics.efficiency_score;
+    }
+
+    // Redundancy level
+    if (analysis.redundancy_analysis.redundancy_level) {
+      summary.redundancy_level = analysis.redundancy_analysis.redundancy_level;
+    }
+
+    // Top concerns
+    if (analysis.performance_analysis.bottlenecks?.length > 0) {
+      summary.top_concerns.push('Performance bottlenecks detected');
+    }
+    
+    if (analysis.redundancy_analysis.redundant_components?.length > 0) {
+      summary.top_concerns.push('Code redundancy found');
+    }
+    
+    if (analysis.usage_analytics.unused_components?.length > 0) {
+      summary.top_concerns.push('Unused components detected');
+    }
+
+    // Strengths
+    if (summary.health_score >= 90) {
+      summary.strengths.push('Overall framework health excellent');
+    }
+    
+    if (summary.performance_score >= 8) {
+      summary.strengths.push('Good performance characteristics');
+    }
+    
+    if (summary.usage_efficiency >= 85) {
+      summary.strengths.push('High component utilization');
+    }
+
+    return summary;
+  },
+
+  /**
+   * Display analysis results
+   */
+  async displayResults(analysis, format) {
+    switch (format) {
+      case 'summary':
+        this.displaySummary(analysis);
+        break;
+      case 'json':
+        console.log(JSON.stringify(analysis, null, 2));
+        break;
+      case 'detailed':
+      default:
+        this.displayDetailed(analysis);
+        break;
+    }
+  },
+
+  /**
+   * Display summary format
+   */
+  displaySummary(analysis) {
+    const { summary } = analysis;
+    
+    console.log(chalk.bold('\n📊 Framework Analysis Summary'));
+    console.log(chalk.gray('─'.repeat(50)));
+    
+    // Health score with color coding
+    const healthColor = summary.health_score >= 80 ? 'green' : 
+                       summary.health_score >= 60 ? 'yellow' : 'red';
+    console.log(`Health Score: ${chalk[healthColor](summary.health_score + '/100')}`);
+    
+    console.log(`Components: ${summary.total_components}`);
+    console.log(`Critical Issues: ${chalk.red(summary.critical_issues)}`);
+    console.log(`Warnings: ${chalk.yellow(summary.warnings)}`);
+    console.log(`Recommendations: ${chalk.blue(summary.recommendations)}`);
+    
+    if (summary.performance_score !== 'N/A') {
+      console.log(`Performance: ${chalk.cyan(summary.performance_score + '/10')}`);
+    }
+    
+    console.log(`Usage Efficiency: ${chalk.cyan(summary.usage_efficiency + '%')}`);
+    console.log(`Redundancy Level: ${chalk.magenta(summary.redundancy_level)}`);
+
+    // Top concerns
+    if (summary.top_concerns.length > 0) {
+      console.log('\n🚨 Top Concerns:');
+      summary.top_concerns.forEach(concern => {
+        console.log(`  • ${chalk.red(concern)}`);
+      });
+    }
+
+    // Strengths
+    if (summary.strengths.length > 0) {
+      console.log('\n✅ Strengths:');
+      summary.strengths.forEach(strength => {
+        console.log(`  • ${chalk.green(strength)}`);
+      });
+    }
+  },
+
+  /**
+   * Display detailed format
+   */
+  displayDetailed(analysis) {
+    this.displaySummary(analysis);
+    
+    // Component breakdown
+    console.log(chalk.bold('\n📋 Component Analysis'));
+    console.log(chalk.gray('─'.repeat(50)));
+    
+    if (analysis.framework_info.agents) {
+      console.log(`Agents (${analysis.framework_info.agents.length}):`);
+      analysis.framework_info.agents.slice(0, 5).forEach(agent => {
+        console.log(`  • ${chalk.cyan(agent.name)} - ${agent.description || 'No description'}`);
+      });
+      if (analysis.framework_info.agents.length > 5) {
+        console.log(`  ... and ${analysis.framework_info.agents.length - 5} more`);
+      }
+    }
+
+    // Performance issues
+    if (analysis.performance_analysis.bottlenecks?.length > 0) {
+      console.log(chalk.bold('\n⚡ Performance Bottlenecks'));
+      console.log(chalk.gray('─'.repeat(50)));
+      
+      analysis.performance_analysis.bottlenecks.slice(0, 3).forEach(bottleneck => {
+        console.log(`  • ${chalk.red(bottleneck.component)}: ${bottleneck.issue}`);
+        console.log(`    Impact: ${chalk.yellow(bottleneck.impact)} | Effort: ${bottleneck.effort}`);
+      });
+    }
+
+    // Redundancy issues
+    if (analysis.redundancy_analysis.redundant_components?.length > 0) {
+      console.log(chalk.bold('\n🔄 Redundant Components'));
+      console.log(chalk.gray('─'.repeat(50)));
+      
+      analysis.redundancy_analysis.redundant_components.slice(0, 3).forEach(redundancy => {
+        console.log(`  • ${chalk.red(redundancy.component1)} ↔️ ${redundancy.component2}`);
+        console.log(`    Similarity: ${chalk.yellow(redundancy.similarity + '%')} | Type: ${redundancy.type}`);
+      });
+    }
+
+    // Top suggestions
+    if (analysis.improvement_suggestions.length > 0) {
+      console.log(chalk.bold('\n💡 Top Improvement Suggestions'));
+      console.log(chalk.gray('─'.repeat(50)));
+      
+      analysis.improvement_suggestions
+        .sort((a, b) => (b.priority_score || 0) - (a.priority_score || 0))
+        .slice(0, 5)
+        .forEach((suggestion, index) => {
+          const priorityColor = suggestion.priority === 'high' ? 'red' : 
+                               suggestion.priority === 'medium' ? 'yellow' : 'gray';
+          console.log(`  ${index + 1}. ${chalk[priorityColor](suggestion.title)}`);
+          console.log(`     ${suggestion.description}`);
+          console.log(`     Impact: ${chalk.cyan(suggestion.impact)} | Effort: ${suggestion.effort}`);
+        });
+    }
+  },
+
+  /**
+   * Save analysis report
+   */
+  async saveReport(analysis) {
+    const reportsDir = path.join(process.cwd(), '.aios', 'reports');
+    await fs.mkdir(reportsDir, { recursive: true });
+    
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const reportPath = path.join(reportsDir, `framework-analysis-${timestamp}.json`);
+    
+    await fs.writeFile(reportPath, JSON.stringify(analysis, null, 2));
+    
+    // Also save a human-readable summary
+    const summaryPath = path.join(reportsDir, `framework-analysis-summary-${timestamp}.md`);
+    const summaryContent = this.generateMarkdownSummary(analysis);
+    await fs.writeFile(summaryPath, summaryContent);
+    
+    return reportPath;
+  },
+
+  /**
+   * Generate markdown summary
+   */
+  generateMarkdownSummary(analysis) {
+    const { summary } = analysis;
+    
+    return `# Framework Analysis Report
+
+**Generated:** ${new Date(analysis.timestamp).toLocaleString()}
+**Scope:** ${analysis.scope}
+
+## Summary
+
+- **Health Score:** ${summary.health_score}/100
+- **Components:** ${summary.total_components}
+- **Critical Issues:** ${summary.critical_issues}
+- **Warnings:** ${summary.warnings}
+- **Recommendations:** ${summary.recommendations}
+- **Performance Score:** ${summary.performance_score}
+- **Usage Efficiency:** ${summary.usage_efficiency}%
+- **Redundancy Level:** ${summary.redundancy_level}
+
+## Top Concerns
+
+${summary.top_concerns.map(concern => `- ${concern}`).join('\n') || 'None identified'}
+
+## Strengths
+
+${summary.strengths.map(strength => `- ${strength}`).join('\n') || 'None identified'}
+
+## Key Metrics
+
+### Component Distribution
+- Agents: ${analysis.framework_info.agents?.length || 0}
+- Tasks: ${analysis.framework_info.tasks?.length || 0}
+- Workflows: ${analysis.framework_info.workflows?.length || 0}
+- Utils: ${analysis.framework_info.utils?.length || 0}
+
+### Performance Analysis
+${analysis.performance_analysis.bottlenecks?.length > 0 ? 
+  `**Bottlenecks Found:** ${analysis.performance_analysis.bottlenecks.length}\n\n` +
+  analysis.performance_analysis.bottlenecks.slice(0, 3).map(b => 
+    `- **${b.component}:** ${b.issue} (Impact: ${b.impact})`
+  ).join('\n') : 'No significant bottlenecks detected'}
+
+### Redundancy Analysis
+${analysis.redundancy_analysis.redundant_components?.length > 0 ?
+  `**Redundant Components:** ${analysis.redundancy_analysis.redundant_components.length}\n\n` +
+  analysis.redundancy_analysis.redundant_components.slice(0, 3).map(r =>
+    `- **${r.component1}** ↔️ **${r.component2}** (${r.similarity}% similar)`
+  ).join('\n') : 'No significant redundancy detected'}
+
+## Top Improvement Suggestions
+
+${analysis.improvement_suggestions.slice(0, 5).map((suggestion, index) => 
+  `${index + 1}. **${suggestion.title}** (${suggestion.priority})
+   - ${suggestion.description}
+   - Impact: ${suggestion.impact} | Effort: ${suggestion.effort}`
+).join('\n\n') || 'No suggestions generated'}
+
+---
+*Report generated by AIOS Framework Analyzer*
+`;
+  }
+};
+```
+
+## Usage Examples
+
+### Basic Analysis
+```bash
+*analyze-framework
+```
+
+### Scope-specific Analysis
+```bash
+*analyze-framework scope=agents
+*analyze-framework scope=utils include_suggestions=false
+```
+
+### Summary Output
+```bash
+*analyze-framework output_format=summary
+```
+
+### Performance-focused Analysis
+```bash
+*analyze-framework include_metrics=true output_format=detailed
+```
+
+## Expected Output
+
+The analysis provides:
+
+1. **Framework Structure Overview**: Complete inventory of components
+2. **Usage Analytics**: Pattern analysis and utilization metrics
+3. **Performance Analysis**: Bottleneck identification and recommendations
+4. **Redundancy Detection**: Overlapping functionality identification
+5. **Improvement Suggestions**: Prioritized recommendations for enhancement
+6. **Health Score**: Overall framework quality assessment
+7. **Detailed Reports**: JSON and Markdown formats for future reference
+
+## Security Considerations
+
+- Read-only analysis - no modifications made to framework
+- Safe file system scanning with permission checks
+- Memory usage monitoring for large codebases
+- Configurable analysis depth to prevent performance issues
+
+## Integration
+
+Works seamlessly with:
+- `*improve-self` command for implementing suggestions
+- Memory layer for storing analysis history
+- Version control for tracking improvements
 - Component modification tools for applying changes