SuperClaude/Framework-Hooks/docs/Modules/Shared-Modules-Overview.md

SuperClaude Framework Hooks - Shared Modules Overview

Architecture Summary

The SuperClaude Framework Hooks shared modules provide the intelligent foundation for all 7 Claude Code hooks. These 10 shared modules implement the core SuperClaude framework patterns from RULES.md, PRINCIPLES.md, and ORCHESTRATOR.md, delivering executable intelligence that transforms static configuration into dynamic, adaptive behavior.

Module Architecture

hooks/shared/
├── __init__.py                    # Module exports and initialization
├── framework_logic.py             # Core SuperClaude decision algorithms
├── pattern_detection.py           # Pattern matching and mode activation
├── mcp_intelligence.py            # MCP server routing and coordination
├── compression_engine.py          # Token efficiency and optimization
├── learning_engine.py             # Adaptive learning and feedback
├── intelligence_engine.py         # Generic YAML pattern interpreter
├── validate_system.py             # YAML-driven system validation
├── yaml_loader.py                 # Configuration loading and management
├── logger.py                      # Structured logging utilities
└── tests/                         # Test suite for shared modules

Core Design Principles

1. Evidence-Based Intelligence

All modules implement measurable decision-making with metrics, performance targets, and validation cycles. No assumptions without evidence.

2. Adaptive Learning System

Cross-hook learning engine that continuously improves effectiveness through pattern recognition, user preference adaptation, and performance optimization.

3. Configuration-Driven Behavior

YAML-based configuration system supporting hot-reload, environment interpolation, and modular includes for flexible deployment.

4. Performance-First Design

Sub-200ms operation targets with intelligent caching, optimized algorithms, and resource-aware processing.

5. Quality-Gated Operations

Every operation includes validation, error handling, fallback strategies, and comprehensive logging for reliability.

Module Responsibilities

Intelligence Layer

• framework_logic.py: Core SuperClaude decision algorithms and validation
• pattern_detection.py: Intelligent pattern matching for automatic activation
• mcp_intelligence.py: Smart MCP server selection and coordination
• intelligence_engine.py: Generic YAML pattern interpreter for hot-reloadable intelligence

Optimization Layer

• compression_engine.py: Token efficiency with quality preservation
• learning_engine.py: Continuous adaptation and improvement

Infrastructure Layer

• yaml_loader.py: High-performance configuration management
• logger.py: Structured event logging and analysis
• validate_system.py: YAML-driven system health validation and diagnostics

Key Features

Intelligent Decision Making

• Complexity Scoring: 0.0-1.0 complexity assessment for operation routing
• Risk Assessment: Low/Medium/High/Critical risk evaluation
• Performance Estimation: Time and resource impact prediction
• Quality Validation: Multi-step validation with quality scores

Pattern Recognition

• Mode Triggers: Automatic detection of brainstorming, task management, efficiency needs
• MCP Server Selection: Context-aware server activation based on operation patterns
• Persona Detection: Domain expertise hints for specialized routing
• Complexity Indicators: Multi-file, architectural, and system-wide operation detection

Adaptive Learning

• User Preference Learning: Personalization based on effectiveness feedback
• Operation Pattern Recognition: Optimization of common workflows
• Performance Feedback Integration: Continuous improvement through metrics
• Cross-Hook Knowledge Sharing: Shared learning across all hook implementations

Configuration Management

• Dual-Format Support: JSON (Claude Code settings) + YAML (SuperClaude configs)
• Hot-Reload Capability: File modification detection with <1s response time
• Environment Interpolation: ${VAR} and ${VAR:default} syntax support
• Modular Configuration: Include/merge support for complex deployments

Performance Optimization

• Token Compression: 30-50% reduction with ≥95% quality preservation
• Intelligent Caching: Sub-10ms configuration access with change detection
• Resource Management: Adaptive behavior based on usage thresholds
• Parallel Processing: Coordination strategies for multi-server operations

Integration Points

Hook Integration

Each hook imports and uses shared modules for:

from shared import (
    FrameworkLogic,           # Decision making
    PatternDetector,          # Pattern recognition  
    MCPIntelligence,          # Server coordination
    CompressionEngine,        # Token optimization
    LearningEngine,           # Adaptive learning
    UnifiedConfigLoader,      # Configuration
)

# Additional modules available for direct import:
from shared.intelligence_engine import IntelligenceEngine  # YAML pattern interpreter
from shared.validate_system import YAMLValidationEngine    # System health validation
from shared.logger import get_logger                       # Logging utilities

SuperClaude Framework Compliance

• RULES.md: Operational security, validation requirements, systematic approaches
• PRINCIPLES.md: Evidence-based decisions, quality standards, error handling
• ORCHESTRATOR.md: Intelligent routing, resource management, quality gates

MCP Server Coordination

• Context7: Library documentation and framework patterns
• Sequential: Complex analysis and multi-step reasoning
• Magic: UI component generation and design systems
• Playwright: Testing automation and validation
• Morphllm: Intelligent editing with pattern application
• Serena: Semantic analysis and project-wide context

Performance Characteristics

Operation Timings

• Configuration Loading: <10ms (cached), <50ms (reload)
• Pattern Detection: <25ms for complex analysis
• Decision Making: <15ms for framework logic operations
• Compression Processing: <100ms with quality validation
• Learning Adaptation: <30ms for preference application

Memory Efficiency

• Configuration Cache: ~2-5KB per config file
• Pattern Cache: ~1-3KB per compiled pattern set
• Learning Records: ~500B per learning event
• Compression Cache: Dynamic based on content size

Quality Metrics

• Decision Accuracy: >90% correct routing decisions
• Pattern Recognition: >85% confidence for auto-activation
• Compression Quality: ≥95% information preservation
• Configuration Reliability: <0.1% cache invalidation errors

Error Handling Strategy

Graceful Degradation

• Module Failures: Fallback to simpler algorithms
• Configuration Errors: Default values with warnings
• Pattern Recognition Failures: Manual routing options
• Learning System Errors: Continue without adaptation

Recovery Mechanisms

• Configuration Reload: Automatic retry on file corruption
• Cache Regeneration: Intelligent cache rebuilding
• Performance Fallbacks: Resource constraint adaptation
• Error Logging: Comprehensive error context capture

Usage Patterns

Basic Hook Integration

# Initialize shared modules
framework_logic = FrameworkLogic()
pattern_detector = PatternDetector()
mcp_intelligence = MCPIntelligence()

# Use in hook implementation
context = {...}
complexity_score = framework_logic.calculate_complexity_score(context)
detection_result = pattern_detector.detect_patterns(user_input, context, operation_data)
activation_plan = mcp_intelligence.create_activation_plan(user_input, context, operation_data)

Advanced Learning Integration

# Record learning events
learning_engine.record_learning_event(
    LearningType.USER_PREFERENCE,
    AdaptationScope.USER,
    context,
    pattern,
    effectiveness_score=0.85
)

# Apply learned adaptations
enhanced_recommendations = learning_engine.apply_adaptations(
    context, base_recommendations
)

Future Enhancements

Planned Features

• Multi-Language Support: Expanded pattern recognition for polyglot projects
• Cloud Configuration: Remote configuration management with caching
• Advanced Analytics: Deeper learning insights and recommendation engines
• Real-Time Monitoring: Live performance dashboards and alerting

Architecture Evolution

• Plugin System: Extensible module architecture for custom intelligence
• Distributed Learning: Cross-instance learning coordination
• Enhanced Caching: Redis/memcached integration for enterprise deployments
• API Integration: REST/GraphQL endpoints for external system integration

Related Documentation

• Individual Module Documentation: See module-specific .md files in this directory
• Hook Implementation Guides: /docs/Hooks/ directory
• Configuration Reference: /docs/Configuration/ directory
• Performance Tuning: /docs/Performance/ directory

---

This overview provides the architectural foundation for understanding how SuperClaude's intelligent hooks system transforms static configuration into adaptive, evidence-based automation.