mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
9edf3f8802
Major documentation update focused on technical accuracy and developer clarity: Documentation Changes: - Rewrote README.md with focus on hooks system architecture - Updated all core docs (Overview, Integration, Performance) to match implementation - Created 6 missing configuration docs for undocumented YAML files - Updated all 7 hook docs to reflect actual Python implementations - Created docs for 2 missing shared modules (intelligence_engine, validate_system) - Updated all 5 pattern docs with real YAML examples - Added 4 essential operational docs (INSTALLATION, TROUBLESHOOTING, CONFIGURATION, QUICK_REFERENCE) Key Improvements: - Removed all marketing language in favor of humble technical documentation - Fixed critical configuration discrepancies (logging defaults, performance targets) - Used actual code examples and configuration from implementation - Complete coverage: 15 configs, 10 modules, 7 hooks, 3 pattern tiers - Based all documentation on actual file review and code analysis Technical Accuracy: - Corrected performance targets to match performance.yaml - Fixed timeout values from settings.json (10-15 seconds) - Updated module count and descriptions to match actual shared/ directory - Aligned all examples with actual YAML and Python implementations The documentation now provides accurate, practical information for developers working with the Framework-Hooks system, focusing on what it actually does rather than aspirational features. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
241 lines
6.3 KiB
Markdown
241 lines
6.3 KiB
Markdown
# Quick Reference
|
|
|
|
Essential commands and information for Framework-Hooks developers and users.
|
|
|
|
## System Overview
|
|
|
|
- **7 hooks**: Execute at specific Claude Code lifecycle events
|
|
- **9 shared modules**: Common functionality across hooks
|
|
- **12+ config files**: YAML-based configuration system
|
|
- **3-tier patterns**: minimal/dynamic/learned pattern system
|
|
- **Performance targets**: <50ms to <200ms per hook
|
|
|
|
## Installation Quick Check
|
|
|
|
```bash
|
|
# Verify Python version
|
|
python3 --version # Need 3.8+
|
|
|
|
# Check directory structure
|
|
ls Framework-Hooks/
|
|
# Should see: hooks/ config/ patterns/ cache/ docs/
|
|
|
|
# Test hook execution
|
|
python3 Framework-Hooks/hooks/session_start.py
|
|
|
|
# Validate system
|
|
cd Framework-Hooks/hooks/shared
|
|
python3 validate_system.py --check-installation
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
| File | Purpose | Key Settings |
|
|
|------|---------|-------------|
|
|
| `logging.yaml` | System logging | `enabled: false` (default) |
|
|
| `performance.yaml` | Timing targets | session_start: 50ms, pre_tool_use: 200ms |
|
|
| `session.yaml` | Session lifecycle | Context management, cleanup behavior |
|
|
| `compression.yaml` | Content compression | Selective compression rules |
|
|
| `mcp_orchestration.yaml` | MCP server routing | Server activation patterns |
|
|
|
|
## Performance Targets
|
|
|
|
| Hook | Target Time | Timeout |
|
|
|------|-------------|---------|
|
|
| session_start.py | <50ms | 10s |
|
|
| pre_tool_use.py | <200ms | 15s |
|
|
| post_tool_use.py | <100ms | 10s |
|
|
| pre_compact.py | <150ms | 15s |
|
|
| notification.py | <50ms | 10s |
|
|
| stop.py | <100ms | 15s |
|
|
| subagent_stop.py | <100ms | 15s |
|
|
|
|
## Common Operations
|
|
|
|
### Enable Logging
|
|
```yaml
|
|
# Edit config/logging.yaml
|
|
logging:
|
|
enabled: true
|
|
level: "INFO" # or DEBUG
|
|
```
|
|
|
|
### Check System Health
|
|
```bash
|
|
cd Framework-Hooks/hooks/shared
|
|
python3 validate_system.py --health-check
|
|
```
|
|
|
|
### Test Individual Hook
|
|
```bash
|
|
cd Framework-Hooks/hooks
|
|
python3 session_start.py # Test session initialization
|
|
python3 pre_tool_use.py # Test tool preparation
|
|
```
|
|
|
|
### Clear Cache
|
|
```bash
|
|
# Reset learning data and cache
|
|
rm -rf Framework-Hooks/cache/*
|
|
# System will recreate on next run
|
|
```
|
|
|
|
### View Recent Logs
|
|
```bash
|
|
# Check latest logs (if logging enabled)
|
|
tail -f Framework-Hooks/cache/logs/hooks-$(date +%Y-%m-%d).log
|
|
```
|
|
|
|
## Hook Execution Flow
|
|
|
|
```
|
|
Session Start → Load Config → Detect Project → Apply Patterns →
|
|
Activate Features → [Work Session with Tool Use Hooks] →
|
|
Record Learning → Save State → Session End
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
Framework-Hooks/
|
|
├── hooks/ # 7 hook scripts
|
|
│ ├── session_start.py # <50ms - Session init
|
|
│ ├── pre_tool_use.py # <200ms - Tool prep
|
|
│ ├── post_tool_use.py # <100ms - Usage recording
|
|
│ ├── pre_compact.py # <150ms - Context compression
|
|
│ ├── notification.py # <50ms - Notifications
|
|
│ ├── stop.py # <100ms - Session cleanup
|
|
│ ├── subagent_stop.py # <100ms - Subagent coordination
|
|
│ └── shared/ # 9 shared modules
|
|
├── config/ # 12+ YAML config files
|
|
├── patterns/ # 3-tier pattern system
|
|
│ ├── minimal/ # Always loaded (3-5KB each)
|
|
│ ├── dynamic/ # On-demand (8-12KB each)
|
|
│ └── learned/ # User adaptations (10-20KB each)
|
|
├── cache/ # Runtime cache and logs
|
|
└── docs/ # Documentation
|
|
```
|
|
|
|
## Shared Modules
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `framework_logic.py` | SuperClaude framework integration |
|
|
| `compression_engine.py` | Context compression and optimization |
|
|
| `learning_engine.py` | Adaptive learning from usage |
|
|
| `mcp_intelligence.py` | MCP server coordination |
|
|
| `pattern_detection.py` | Project and usage pattern detection |
|
|
| `intelligence_engine.py` | Central intelligence coordination |
|
|
| `logger.py` | Structured logging system |
|
|
| `yaml_loader.py` | Configuration loading utilities |
|
|
| `validate_system.py` | System validation and health checks |
|
|
|
|
## Troubleshooting Quick Fixes
|
|
|
|
### Hook Timeout
|
|
- Check performance targets in `config/performance.yaml`
|
|
- Clear cache: `rm -rf cache/*`
|
|
- Reduce pattern loading
|
|
|
|
### Import Errors
|
|
```bash
|
|
# Verify shared modules path
|
|
ls Framework-Hooks/hooks/shared/
|
|
# Should show all 9 .py files
|
|
|
|
# Check permissions
|
|
chmod +x Framework-Hooks/hooks/*.py
|
|
```
|
|
|
|
### YAML Errors
|
|
```bash
|
|
# Validate YAML files
|
|
python3 -c "
|
|
import yaml, glob
|
|
for f in glob.glob('config/*.yaml'):
|
|
yaml.safe_load(open(f))
|
|
print(f'{f}: OK')
|
|
"
|
|
```
|
|
|
|
### No Log Output
|
|
```yaml
|
|
# Enable in config/logging.yaml
|
|
logging:
|
|
enabled: true
|
|
level: "INFO"
|
|
hook_logging:
|
|
log_lifecycle: true
|
|
```
|
|
|
|
## Configuration Shortcuts
|
|
|
|
### Development Mode
|
|
```yaml
|
|
# config/logging.yaml
|
|
logging:
|
|
enabled: true
|
|
level: "DEBUG"
|
|
development:
|
|
debug_mode: true
|
|
verbose_errors: true
|
|
```
|
|
|
|
### Production Mode
|
|
```yaml
|
|
# config/logging.yaml
|
|
logging:
|
|
enabled: false
|
|
level: "ERROR"
|
|
```
|
|
|
|
### Reset to Defaults
|
|
```bash
|
|
# Backup first, then:
|
|
git checkout config/*.yaml
|
|
rm -rf cache/
|
|
rm -rf patterns/learned/
|
|
```
|
|
|
|
## File Locations
|
|
|
|
- **Hook scripts**: `hooks/*.py`
|
|
- **Configuration**: `config/*.yaml`
|
|
- **Logs**: `cache/logs/hooks-YYYY-MM-DD.log`
|
|
- **Learning data**: `cache/learning/`
|
|
- **Pattern cache**: `cache/patterns/`
|
|
- **Installation config**: `settings.json`, `superclaude-config.json`
|
|
|
|
## Debug Commands
|
|
|
|
```bash
|
|
# Full system validation
|
|
python3 hooks/shared/validate_system.py --full-check
|
|
|
|
# Check configuration integrity
|
|
python3 hooks/shared/validate_system.py --check-config
|
|
|
|
# Test pattern loading
|
|
python3 hooks/shared/pattern_detection.py --test-patterns
|
|
|
|
# Verify learning engine
|
|
python3 hooks/shared/learning_engine.py --test-learning
|
|
```
|
|
|
|
## System Behavior
|
|
|
|
### Default State
|
|
- All hooks **enabled** via settings.json
|
|
- Logging **disabled** for performance
|
|
- Conservative timeouts (10-15 seconds)
|
|
- Selective compression preserves user content
|
|
- Learning engine adapts to usage patterns
|
|
|
|
### What Happens Automatically
|
|
1. **Project detection** - Identifies project type and loads patterns
|
|
2. **Mode activation** - Enables relevant SuperClaude modes
|
|
3. **MCP coordination** - Routes to appropriate servers
|
|
4. **Performance optimization** - Applies compression and caching
|
|
5. **Learning adaptation** - Records and learns from usage
|
|
|
|
Framework-Hooks operates transparently without requiring manual intervention. |