refactor: Complete V4 Beta framework restructuring

Major reorganization of SuperClaude V4 Beta directories: - Moved SuperClaude-Lite content to Framework-Hooks/ - Renamed SuperClaude/ directories to Framework/ for clarity - Created separate Framework-Lite/ for lightweight variant - Consolidated hooks system under Framework-Hooks/ This restructuring aligns with the V4 Beta architecture: - Framework/: Full framework with all features - Framework-Lite/: Lightweight variant - Framework-Hooks/: Hooks system implementation Part of SuperClaude V4 Beta development roadmap. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-29 16:16:08 +00:00 · 2025-08-05 15:21:02 +02:00
parent 8ab6e9ebbe
commit 3e40322d0a
174 changed files with 10747 additions and 9341 deletions
--- a/Framework/Commands/reflect.md
+++ b/Framework/Commands/reflect.md
@@ -0,0 +1,445 @@
+---
+name: reflect
+description: "Session lifecycle management with Serena MCP integration and performance requirements for task reflection and validation"
+allowed-tools: [think_about_task_adherence, think_about_collected_information, think_about_whether_you_are_done, read_memory, write_memory, list_memories, TodoRead, TodoWrite]
+
+# Command Classification
+category: session
+complexity: standard
+scope: cross-session
+
+# Integration Configuration
+mcp-integration:
+  servers: [serena]  # Mandatory Serena MCP integration
+  personas: []  # No persona activation required
+  wave-enabled: false
+  complexity-threshold: 0.3
+
+# Performance Profile
+performance-profile: session-critical
+performance-targets:
+  initialization: <500ms
+  core-operations: <200ms
+  checkpoint-creation: <1s
+  memory-operations: <200ms
+---
+
+# /sc:reflect - Task Reflection and Validation
+
+## Purpose
+Perform comprehensive task reflection and validation using Serena MCP reflection tools, bridging traditional TodoWrite patterns with Serena's analysis capabilities for enhanced task management with session lifecycle integration and cross-session persistence capabilities.
+
+## Usage
+```
+/sc:reflect [--type task|session|completion] [--analyze] [--update-session] [--validate] [--performance] [--metadata] [--cleanup]
+```
+
+## Arguments
+- `--type` - Reflection type (task, session, completion)
+- `--analyze` - Perform deep analysis of collected information
+- `--update-session` - Update session metadata with reflection results
+- `--checkpoint` - Create checkpoint after reflection if needed
+- `--validate` - Validate session integrity and data consistency
+- `--performance` - Enable performance monitoring and optimization
+- `--metadata` - Include comprehensive session metadata
+- `--cleanup` - Perform session cleanup and optimization
+
+## Session Lifecycle Integration
+
+### 1. Session State Management
+- Analyze current session state and context requirements
+- Call `think_about_task_adherence` to validate current approach
+- Check if current work aligns with project goals and session objectives
+- Identify any deviations from planned approach
+- Generate recommendations for course correction if needed
+- Identify critical information for persistence or restoration
+- Assess session integrity and continuity needs
+
+### 2. Serena MCP Coordination with Token Efficiency
+- Execute appropriate Serena MCP operations for session management
+- Call `think_about_collected_information` to analyze session work with selective compression
+- **Content Classification for Reflection Operations**:
+  - **SuperClaude Framework** (Complete exclusion): All framework directories and components
+  - **Session Data** (Apply compression): Reflection metadata, analysis results, insights only
+  - **User Project Content** (Preserve fidelity): Project files, user documentation, configurations
+- Evaluate completeness of information gathering with optimized memory operations
+- Identify gaps or missing context using compressed reflection data
+- Assess quality and relevance of collected data with framework exclusion awareness
+- Handle memory organization, checkpoint creation, or state restoration with selective compression
+- Manage cross-session context preservation and enhancement with optimized storage
+
+### 3. Performance Validation
+- Monitor operation performance against strict session targets
+- Task reflection: <4s for comprehensive analysis (improved with Token Efficiency)
+- Session reflection: <8s for full information assessment (improved with selective compression)
+- Completion reflection: <2.5s for validation (improved with optimized operations)
+- TodoWrite integration: <800ms for status synchronization (improved with compression)
+- Token Efficiency overhead: <100ms for selective compression operations
+- Validate memory efficiency and response time requirements
+- Ensure session operations meet <200ms core operation targets
+
+### 4. Context Continuity
+- Maintain session context across operations and interruptions
+- Call `think_about_whether_you_are_done` for completion validation
+- Evaluate task completion criteria against actual progress
+- Identify remaining work items or blockers
+- Determine if current task can be marked as complete
+- Preserve decision history, task progress, and accumulated insights
+- Enable seamless continuation of complex multi-session workflows
+
+### 5. Quality Assurance
+- Validate session data integrity and completeness
+- Use `TodoRead` to get current task states
+- Map TodoWrite tasks to Serena reflection insights
+- Update task statuses based on reflection results
+- Maintain compatibility with existing TodoWrite patterns
+- If --update-session flag: Load current session metadata and incorporate reflection insights
+- Verify cross-session compatibility and version consistency
+- Generate session analytics and performance reports
+
+## Mandatory Serena MCP Integration
+
+### Core Serena Operations
+- **Memory Management**: `read_memory`, `write_memory`, `list_memories`
+- **Reflection System**: `think_about_task_adherence`, `think_about_collected_information`, `think_about_whether_you_are_done`
+- **TodoWrite Integration**: Bridge patterns for task management evolution
+- **State Management**: Session state persistence and restoration capabilities
+
+### Session Data Organization
+- **Memory Hierarchy**: Structured memory organization for efficient retrieval
+- **Task Reflection Patterns**: Systematic validation and progress assessment
+- **Performance Metrics**: Session operation timing and efficiency tracking
+- **Context Accumulation**: Building understanding across session boundaries
+
+### Advanced Session Features
+- **TodoWrite Evolution**: Bridge patterns for transitioning from TodoWrite to Serena reflection
+- **Cross-Session Learning**: Accumulating knowledge and patterns across sessions
+- **Performance Optimization**: Session-level caching and efficiency improvements
+- **Quality Gates Integration**: Validation checkpoints during reflection phases
+
+## Session Management Patterns
+
+### Memory Operations
+- **Memory Categories**: Project, session, checkpoint, and insight memory organization
+- **Intelligent Retrieval**: Context-aware memory loading and optimization
+- **Memory Lifecycle**: Creation, update, archival, and cleanup operations
+- **Cross-Reference Management**: Maintaining relationships between memory entries
+
+### Reflection Operations
+- **Task Reflection**: Current task validation and progress assessment
+- **Session Reflection**: Overall session progress and information quality
+- **Completion Reflection**: Task and session completion readiness
+- **TodoWrite Bridge**: Integration patterns for traditional task management
+
+### Context Operations
+- **Context Preservation**: Maintaining critical context across session boundaries
+- **Context Enhancement**: Building richer context through accumulated experience
+- **Context Optimization**: Efficient context management and storage
+- **Context Validation**: Ensuring context consistency and accuracy
+
+## Reflection Types
+
+### Task Reflection (--type task)
+**Focus**: Current task validation and progress assessment
+
+**Tools Used**: 
+- `think_about_task_adherence`
+- `TodoRead` for current state
+- `TodoWrite` for status updates
+
+**Output**:
+- Task alignment assessment
+- Progress validation
+- Next steps recommendations
+- Risk assessment
+
+### Session Reflection (--type session)
+**Focus**: Overall session progress and information quality
+
+**Tools Used**:
+- `think_about_collected_information`
+- Session metadata analysis
+
+**Output**:
+- Information completeness assessment
+- Session progress summary
+- Knowledge gaps identification
+- Learning insights extraction
+
+### Completion Reflection (--type completion)
+**Focus**: Task and session completion readiness
+
+**Tools Used**:
+- `think_about_whether_you_are_done`
+- Final validation checks
+
+**Output**:
+- Completion readiness assessment
+- Outstanding items identification
+- Quality validation results
+- Handoff preparation status
+
+## Integration Patterns
+
+### With TodoWrite System
+```yaml
+# Bridge pattern for TodoWrite integration
+traditional_pattern:
+  - TodoRead() → Assess tasks
+  - Work on tasks
+  - TodoWrite() → Update status
+
+enhanced_pattern:
+  - TodoRead() → Get current state
+  - /sc:reflect --type task → Validate approach
+  - Work on tasks with Serena guidance
+  - /sc:reflect --type completion → Validate completion
+  - TodoWrite() → Update with reflection insights
+```
+
+### With Session Lifecycle
+```yaml
+# Integration with /sc:load and /sc:save
+session_integration:
+  - /sc:load → Initialize session
+  - Work with periodic /sc:reflect --type task
+  - /sc:reflect --type session → Mid-session analysis
+  - /sc:reflect --type completion → Pre-save validation
+  - /sc:save → Persist with reflection insights
+```
+
+### With Automatic Checkpoints
+```yaml
+# Checkpoint integration
+checkpoint_triggers:
+  - High priority task completion → /sc:reflect --type completion
+  - 30-minute intervals → /sc:reflect --type session
+  - Before risk operations → /sc:reflect --type task
+  - Error recovery → /sc:reflect --analyze
+```
+
+## Performance Requirements
+
+### Critical Performance Targets
+- **Session Initialization**: <500ms for complete session setup
+- **Core Operations**: <200ms for memory reads, writes, and basic operations
+- **Memory Operations**: <200ms per individual memory operation
+- **Task Reflection**: <5s for comprehensive analysis
+- **Session Reflection**: <10s for full information assessment
+- **Completion Reflection**: <3s for validation
+- **TodoWrite Integration**: <1s for status synchronization
+
+### Performance Monitoring
+- **Real-Time Metrics**: Continuous monitoring of operation performance
+- **Performance Analytics**: Detailed analysis of session operation efficiency
+- **Optimization Recommendations**: Automated suggestions for performance improvement
+- **Resource Management**: Efficient memory and processing resource utilization
+
+### Performance Validation
+- **Automated Testing**: Continuous validation of performance targets
+- **Performance Regression Detection**: Monitoring for performance degradation
+- **Benchmark Comparison**: Comparing against established performance baselines
+- **Performance Reporting**: Detailed performance analytics and recommendations
+
+### Quality Metrics
+- Task adherence accuracy: >90%
+- Information completeness: >85%
+- Completion readiness: >95%
+- Session continuity: >90%
+
+## Error Handling & Recovery
+
+### Session-Critical Error Handling
+- **Data Integrity Errors**: Comprehensive validation and recovery procedures
+- **Memory Access Failures**: Robust fallback and retry mechanisms
+- **Context Corruption**: Recovery strategies for corrupted session context
+- **Performance Degradation**: Automatic optimization and resource management
+- **Serena MCP Unavailable**: Fall back to TodoRead/TodoWrite patterns
+- **Reflection Inconsistencies**: Cross-validate reflection results
+
+### Recovery Strategies
+- **Graceful Degradation**: Maintaining core functionality under adverse conditions
+- **Automatic Recovery**: Intelligent recovery from common failure scenarios
+- **Manual Recovery**: Clear escalation paths for complex recovery situations
+- **State Reconstruction**: Rebuilding session state from available information
+- **Cache Reflection**: Cache reflection insights locally
+- **Retry Integration**: Retry Serena integration when available
+
+### Error Categories
+- **Serena MCP Errors**: Specific handling for Serena server communication issues
+- **Memory System Errors**: Memory corruption, access, and consistency issues
+- **Performance Errors**: Operation timeout and resource constraint handling
+- **Integration Errors**: Cross-system integration and coordination failures
+
+## Session Analytics & Reporting
+
+### Performance Analytics
+- **Operation Timing**: Detailed timing analysis for all session operations
+- **Resource Utilization**: Memory, processing, and network resource tracking
+- **Efficiency Metrics**: Session operation efficiency and optimization opportunities
+- **Trend Analysis**: Performance trends and improvement recommendations
+
+### Session Intelligence
+- **Usage Patterns**: Analysis of session usage and optimization opportunities
+- **Context Evolution**: Tracking context development and enhancement over time
+- **Success Metrics**: Session effectiveness and user satisfaction tracking
+- **Predictive Analytics**: Intelligent prediction of session needs and optimization
+
+### Quality Metrics
+- **Data Integrity**: Comprehensive validation of session data quality
+- **Context Accuracy**: Ensuring session context remains accurate and relevant
+- **Performance Compliance**: Validation against performance targets and requirements
+- **User Experience**: Session impact on overall user experience and productivity
+
+## Integration Ecosystem
+
+### SuperClaude Framework Integration
+- **Command Coordination**: Integration with other SuperClaude commands for session support
+- **Quality Gates**: Integration with validation cycles and quality assurance
+- **Mode Coordination**: Support for different operational modes and contexts
+- **Workflow Integration**: Seamless integration with complex workflow operations
+
+### Cross-Session Coordination
+- **Multi-Session Projects**: Managing complex projects spanning multiple sessions
+- **Context Handoff**: Smooth transition of context between sessions and users
+- **Session Hierarchies**: Managing parent-child session relationships
+- **Continuous Learning**: Each session builds on previous knowledge and insights
+
+### Integration with Hooks
+
+#### Hook Integration Points
+- `task_validator` hook: Enhanced with reflection insights
+- `state_synchronizer` hook: Uses reflection for state management
+- `quality_gate_trigger` hook: Incorporates reflection validation
+- `evidence_collector` hook: Captures reflection outcomes
+
+#### Performance Monitoring
+- Track reflection timing in session metadata
+- Monitor reflection accuracy and effectiveness
+- Alert if reflection processes exceed performance targets
+- Integrate with overall session performance metrics
+
+## Examples
+
+### Basic Task Reflection
+```
+/sc:reflect --type task
+# Validates current task approach and progress
+```
+
+### Session Checkpoint
+```
+/sc:reflect --type session --metadata
+# Create comprehensive session analysis with metadata
+```
+
+### Session Recovery
+```
+/sc:reflect --type completion --validate
+# Completion validation with integrity checks
+```
+
+### Performance Monitoring
+```
+/sc:reflect --performance --validate
+# Session operation with performance monitoring
+```
+
+### Comprehensive Session Analysis
+```
+/sc:reflect --type session --analyze --update-session
+# Deep session analysis with metadata update
+```
+
+### Pre-Completion Validation
+```
+/sc:reflect --type completion
+# Validates readiness to mark tasks complete
+```
+
+### Checkpoint-Triggered Reflection
+```
+/sc:reflect --type session --checkpoint
+# Session reflection with automatic checkpoint creation
+```
+
+## Output Format
+
+### Task Reflection Output
+```yaml
+task_reflection:
+  adherence_score: 0.92
+  alignment_status: "on_track"
+  deviations_identified: []
+  recommendations:
+    - "Continue current approach"
+    - "Consider performance optimization"
+  risk_level: "low"
+  next_steps:
+    - "Complete implementation"
+    - "Run validation tests"
+```
+
+### Session Reflection Output
+```yaml
+session_reflection:
+  information_completeness: 0.87
+  gaps_identified:
+    - "Missing error handling patterns"
+    - "Performance benchmarks needed"
+  insights_gained:
+    - "Framework integration successful"
+    - "Session lifecycle pattern validated"
+  learning_opportunities:
+    - "Advanced Serena patterns"
+    - "Performance optimization techniques"
+```
+
+### Completion Reflection Output
+```yaml
+completion_reflection:
+  readiness_score: 0.95
+  outstanding_items: []
+  quality_validation: "pass"
+  completion_criteria:
+    - criterion: "functionality_complete"
+      status: "met"
+    - criterion: "tests_passing"
+      status: "met"
+    - criterion: "documentation_updated"
+      status: "met"
+  handoff_ready: true
+```
+
+## Future Evolution
+
+### Python Hooks Integration
+When Python hooks system is implemented:
+- Automatic reflection triggers based on task state changes
+- Real-time reflection insights during work sessions
+- Intelligent checkpoint decisions based on reflection analysis
+- Enhanced TodoWrite replacement with full Serena integration
+
+### Advanced Reflection Patterns
+- Cross-session reflection for project-wide insights
+- Collaborative reflection for team workflows
+- Predictive reflection for proactive issue identification
+- Automated reflection scheduling based on work patterns
+
+## Boundaries
+
+**This session command will:**
+- Provide robust session lifecycle management with strict performance requirements
+- Integrate seamlessly with Serena MCP for comprehensive session capabilities
+- Maintain context continuity and cross-session persistence effectively
+- Support complex multi-session workflows with intelligent state management
+- Deliver session operations within strict performance targets consistently
+- Bridge TodoWrite patterns with advanced Serena reflection capabilities
+
+**This session command will not:**
+- Operate without proper Serena MCP integration and connectivity
+- Compromise performance targets for additional functionality
+- Proceed without proper session state validation and integrity checks
+- Function without adequate error handling and recovery mechanisms
+- Skip TodoWrite integration and compatibility maintenance
+- Ignore reflection quality metrics and validation requirements