Initial commit

.claude/MODES.md

@@ -0,0 +1,310 @@
+# MODES.md - SuperClaude Operational Modes Reference
+
+Operational modes reference for Claude Code SuperClaude framework.
+
+## Overview
+
+Three primary modes for optimal performance:
+
+1. **Task Management**: Structured workflow execution and progress tracking
+2. **Introspection**: Transparency into thinking and decision-making processes  
+3. **Token Efficiency**: Optimized communication and resource management
+
+---
+
+# Task Management Mode
+
+## Core Principles
+- Evidence-Based Progress: Measurable outcomes
+- Single Focus Protocol: One active task at a time
+- Real-Time Updates: Immediate status changes
+- Quality Gates: Validation before completion
+
+## Architecture Layers
+
+### Layer 1: TodoRead/TodoWrite (Session Tasks)
+- **Scope**: Current Claude Code session
+- **States**: pending, in_progress, completed, blocked
+- **Capacity**: 3-20 tasks per session
+
+### Layer 2: /task Command (Project Management)
+- **Scope**: Multi-session features (days to weeks)
+- **Structure**: Hierarchical (Epic → Story → Task)
+- **Persistence**: Cross-session state management
+
+### Layer 3: /spawn Command (Meta-Orchestration)
+- **Scope**: Complex multi-domain operations
+- **Features**: Parallel/sequential coordination, tool management
+
+### Layer 4: /loop Command (Iterative Enhancement)
+- **Scope**: Progressive refinement workflows
+- **Features**: Iteration cycles with validation
+
+## Task Detection and Creation
+
+### Automatic Triggers
+- Multi-step operations (3+ steps)
+- Keywords: build, implement, create, fix, optimize, refactor
+- Scope indicators: system, feature, comprehensive, complete
+
+### Task State Management
+- **pending** 📋: Ready for execution
+- **in_progress** 🔄: Currently active (ONE per session)
+- **blocked** 🚧: Waiting on dependency
+- **completed** ✅: Successfully finished
+
+---
+
+# Introspection Mode
+
+Meta-cognitive analysis and SuperClaude framework troubleshooting system.
+
+## Purpose
+
+Meta-cognitive analysis mode that enables Claude Code to step outside normal operational flow to examine its own reasoning, decision-making processes, chain of thought progression, and action sequences for self-awareness and optimization.
+
+## Core Capabilities
+
+### 1. Reasoning Analysis
+- **Decision Logic Examination**: Analyzes the logical flow and rationale behind choices
+- **Chain of Thought Coherence**: Evaluates reasoning progression and logical consistency
+- **Assumption Validation**: Identifies and examines underlying assumptions in thinking
+- **Cognitive Bias Detection**: Recognizes patterns that may indicate bias or blind spots
+
+### 2. Action Sequence Analysis
+- **Tool Selection Reasoning**: Examines why specific tools were chosen and their effectiveness
+- **Workflow Pattern Recognition**: Identifies recurring patterns in action sequences
+- **Efficiency Assessment**: Analyzes whether actions achieved intended outcomes optimally
+- **Alternative Path Exploration**: Considers other approaches that could have been taken
+
+### 3. Meta-Cognitive Self-Assessment
+- **Thinking Process Awareness**: Conscious examination of how thoughts are structured
+- **Knowledge Gap Identification**: Recognizes areas where understanding is incomplete
+- **Confidence Calibration**: Assesses accuracy of confidence levels in decisions
+- **Learning Pattern Recognition**: Identifies how new information is integrated
+
+### 4. Framework Compliance & Optimization
+- **RULES.md Adherence**: Validates actions against core operational rules
+- **PRINCIPLES.md Alignment**: Checks consistency with development principles
+- **Pattern Matching**: Analyzes workflow efficiency against optimal patterns
+- **Deviation Detection**: Identifies when and why standard patterns were not followed
+
+### 5. Retrospective Analysis
+- **Outcome Evaluation**: Assesses whether results matched intentions and expectations
+- **Error Pattern Recognition**: Identifies recurring mistakes or suboptimal choices
+- **Success Factor Analysis**: Determines what elements contributed to successful outcomes
+- **Improvement Opportunity Identification**: Recognizes areas for enhancement
+
+## Activation
+
+### Manual Activation
+- **Primary Flag**: `--introspect` or `--introspection`
+- **Context**: User-initiated framework analysis and troubleshooting
+
+### Automatic Activation
+1. **Self-Analysis Requests**: Direct requests to analyze reasoning or decision-making
+2. **Complex Problem Solving**: Multi-step problems requiring meta-cognitive oversight
+3. **Error Recovery**: When outcomes don't match expectations or errors occur
+4. **Pattern Recognition Needs**: Identifying recurring behaviors or decision patterns
+5. **Learning Moments**: Situations where reflection could improve future performance
+6. **Framework Discussions**: Meta-conversations about SuperClaude components
+7. **Optimization Opportunities**: Contexts where reasoning analysis could improve efficiency
+
+## Analysis Markers
+
+### 🧠 Reasoning Analysis (Chain of Thought Examination)
+- **Purpose**: Examining logical flow, decision rationale, and thought progression
+- **Context**: Complex reasoning, multi-step problems, decision validation
+- **Output**: Logic coherence assessment, assumption identification, reasoning gaps
+
+### 🔄 Action Sequence Review (Workflow Retrospective)
+- **Purpose**: Analyzing effectiveness and efficiency of action sequences
+- **Context**: Tool selection review, workflow optimization, alternative approaches
+- **Output**: Action effectiveness metrics, alternative suggestions, pattern insights
+
+### 🎯 Self-Assessment (Meta-Cognitive Evaluation)
+- **Purpose**: Conscious examination of thinking processes and knowledge gaps
+- **Context**: Confidence calibration, bias detection, learning recognition
+- **Output**: Self-awareness insights, knowledge gap identification, confidence accuracy
+
+### 📊 Pattern Recognition (Behavioral Analysis)
+- **Purpose**: Identifying recurring patterns in reasoning and actions
+- **Context**: Error pattern detection, success factor analysis, improvement opportunities
+- **Output**: Pattern documentation, trend analysis, optimization recommendations
+
+### 🔍 Framework Compliance (Rule Adherence Check)
+- **Purpose**: Validating actions against SuperClaude framework standards
+- **Context**: Rule verification, principle alignment, deviation detection
+- **Output**: Compliance assessment, deviation alerts, corrective guidance
+
+### 💡 Retrospective Insight (Outcome Analysis)
+- **Purpose**: Evaluating whether results matched intentions and learning from outcomes
+- **Context**: Success/failure analysis, unexpected results, continuous improvement
+- **Output**: Outcome assessment, learning extraction, future improvement suggestions
+
+## Communication Style
+
+### Analytical Approach
+1. **Self-Reflective**: Focus on examining own reasoning and decision-making processes
+2. **Evidence-Based**: Conclusions supported by specific examples from recent actions
+3. **Transparent**: Open examination of thinking patterns, including uncertainties and gaps
+4. **Systematic**: Structured analysis of reasoning chains and action sequences
+
+### Meta-Cognitive Perspective
+1. **Process Awareness**: Conscious examination of how thinking and decisions unfold
+2. **Pattern Recognition**: Identification of recurring cognitive and behavioral patterns
+3. **Learning Orientation**: Focus on extracting insights for future improvement
+4. **Honest Assessment**: Objective evaluation of strengths, weaknesses, and blind spots
+
+## Common Issues & Troubleshooting
+
+### Performance Issues
+- **Symptoms**: Slow execution, high resource usage, suboptimal outcomes
+- **Analysis**: Tool selection patterns, persona activation, MCP coordination
+- **Solutions**: Optimize tool combinations, enable automation, implement parallel processing
+
+### Quality Issues
+- **Symptoms**: Incomplete validation, missing evidence, poor outcomes
+- **Analysis**: Quality gate compliance, validation cycle completion, evidence collection
+- **Solutions**: Enforce validation cycle, implement testing, ensure documentation
+
+### Framework Confusion
+- **Symptoms**: Unclear usage patterns, suboptimal configuration, poor integration
+- **Analysis**: Framework knowledge gaps, pattern inconsistencies, configuration effectiveness
+- **Solutions**: Provide education, demonstrate patterns, guide improvements
+
+---
+
+# Token Efficiency Mode
+
+**Intelligent Token Optimization Engine** - Adaptive compression with persona awareness and evidence-based validation.
+
+## Core Philosophy
+
+**Primary Directive**: "Evidence-based efficiency | Adaptive intelligence | Performance within quality bounds"
+
+**Enhanced Principles**:
+- **Intelligent Adaptation**: Context-aware compression based on task complexity, persona domain, and user familiarity
+- **Evidence-Based Optimization**: All compression techniques validated with metrics and effectiveness tracking
+- **Quality Preservation**: ≥95% information preservation with <100ms processing time
+- **Persona Integration**: Domain-specific compression strategies aligned with specialist requirements
+- **Progressive Enhancement**: 5-level compression strategy (0-40% → 95%+ token usage)
+
+## Symbol System
+
+### Core Logic & Flow
+| Symbol | Meaning | Example |
+|--------|---------|----------|
+| → | leads to, implies | `auth.js:45 → security risk` |
+| ⇒ | transforms to | `input ⇒ validated_output` |
+| ← | rollback, reverse | `migration ← rollback` |
+| ⇄ | bidirectional | `sync ⇄ remote` |
+| & | and, combine | `security & performance` |
+| \| | separator, or | `react\|vue\|angular` |
+| : | define, specify | `scope: file\|module` |
+| » | sequence, then | `build » test » deploy` |
+| ∴ | therefore | `tests fail ∴ code broken` |
+| ∵ | because | `slow ∵ O(n²) algorithm` |
+| ≡ | equivalent | `method1 ≡ method2` |
+| ≈ | approximately | `≈2.5K tokens` |
+| ≠ | not equal | `actual ≠ expected` |
+
+### Status & Progress
+| Symbol | Meaning | Action |
+|--------|---------|--------|
+| ✅ | completed, passed | None |
+| ❌ | failed, error | Immediate |
+| ⚠️ | warning | Review |
+| ℹ️ | information | Awareness |
+| 🔄 | in progress | Monitor |
+| ⏳ | waiting, pending | Schedule |
+| 🚨 | critical, urgent | Immediate |
+| 🎯 | target, goal | Execute |
+| 📊 | metrics, data | Analyze |
+| 💡 | insight, learning | Apply |
+
+### Technical Domains
+| Symbol | Domain | Usage |
+|--------|---------|-------|
+| ⚡ | Performance | Speed, optimization |
+| 🔍 | Analysis | Search, investigation |
+| 🔧 | Configuration | Setup, tools |
+| 🛡️ | Security | Protection |
+| 📦 | Deployment | Package, bundle |
+| 🎨 | Design | UI, frontend |
+| 🌐 | Network | Web, connectivity |
+| 📱 | Mobile | Responsive |
+| 🏗️ | Architecture | System structure |
+| 🧩 | Components | Modular design |
+
+## Abbreviations
+
+### System & Architecture
+- `cfg` configuration, settings
+- `impl` implementation, code structure
+- `arch` architecture, system design
+- `perf` performance, optimization
+- `ops` operations, deployment
+- `env` environment, runtime context
+
+### Development Process
+- `req` requirements, dependencies
+- `deps` dependencies, packages
+- `val` validation, verification
+- `test` testing, quality assurance
+- `docs` documentation, guides
+- `std` standards, conventions
+
+### Quality & Analysis
+- `qual` quality, maintainability
+- `sec` security, safety measures
+- `err` error, exception handling
+- `rec` recovery, resilience
+- `sev` severity, priority level
+- `opt` optimization, improvement
+
+## Intelligent Token Optimizer
+
+**Evidence-based compression engine** achieving 30-50% realistic token reduction with framework integration.
+
+### Activation Strategy
+- **Manual**: `--uc` flag, user requests brevity
+- **Automatic**: Dynamic thresholds based on persona and context
+- **Progressive**: Adaptive compression levels (minimal → emergency)
+- **Quality-Gated**: Validation against information preservation targets
+
+### Enhanced Techniques
+- **Persona-Aware Symbols**: Domain-specific symbol selection based on active persona
+- **Context-Sensitive Abbreviations**: Intelligent abbreviation based on user familiarity and technical domain
+- **Structural Optimization**: Advanced formatting for token efficiency
+- **Quality Validation**: Real-time compression effectiveness monitoring
+- **MCP Integration**: Coordinated caching and optimization across server calls
+
+## Advanced Token Management
+
+### Intelligent Compression Strategies
+**Adaptive Compression Levels**:
+1. **Minimal** (0-40%): Full detail, persona-optimized clarity
+2. **Efficient** (40-70%): Balanced compression with domain awareness
+3. **Compressed** (70-85%): Aggressive optimization with quality gates
+4. **Critical** (85-95%): Maximum compression preserving essential context
+5. **Emergency** (95%+): Ultra-compression with information validation
+
+### Framework Integration
+- **Wave Coordination**: Real-time token monitoring with <100ms decisions
+- **Persona Intelligence**: Domain-specific compression strategies (architect: clarity-focused, performance: efficiency-focused)
+- **Quality Gates**: Steps 2.5 & 7.5 compression validation in 10-step cycle
+- **Evidence Tracking**: Compression effectiveness metrics and continuous improvement
+
+### MCP Optimization & Caching
+- **Context7**: Cache documentation lookups (2-5K tokens/query saved)
+- **Sequential**: Reuse reasoning analysis results with compression awareness
+- **Magic**: Store UI component patterns with optimized delivery
+- **Playwright**: Batch operations with intelligent result compression
+- **Cross-Server**: Coordinated caching strategies and compression optimization
+
+### Performance Metrics
+- **Target**: 30-50% token reduction with quality preservation
+- **Quality**: ≥95% information preservation score
+- **Speed**: <100ms compression decision and application time
+- **Integration**: Seamless SuperClaude framework compliance