Revolutionary transformation from hardcoded Python intelligence to hot-reloadable
YAML patterns, enabling dynamic configuration without code changes.
## Phase 1: Foundation Intelligence Complete
### YAML Intelligence Patterns (6 files)
- intelligence_patterns.yaml: Multi-dimensional pattern recognition with adaptive learning
- mcp_orchestration.yaml: Server selection decision trees with load balancing
- hook_coordination.yaml: Parallel execution patterns with dependency resolution
- performance_intelligence.yaml: Resource zones and auto-optimization triggers
- validation_intelligence.yaml: Health scoring and proactive diagnostic patterns
- user_experience.yaml: Project detection and smart UX adaptations
### Python Infrastructure Enhanced (4 components)
- intelligence_engine.py: Generic YAML pattern interpreter with hot-reload
- learning_engine.py: Enhanced with YAML intelligence integration
- yaml_loader.py: Added intelligence configuration helper methods
- validate_system.py: New YAML-driven validation with health scoring
### Key Features Implemented
- Hot-reload intelligence: Update patterns without code changes or restarts
- Declarative configuration: All intelligence logic expressed in YAML
- Graceful fallbacks: System works correctly even with missing YAML files
- Multi-pattern coordination: Intelligent recommendations from multiple sources
- Health scoring: Component-weighted validation with predictive diagnostics
- Generic architecture: Single engine consumes all intelligence pattern types
### Testing Results
✅ All components integrate correctly
✅ Hot-reload mechanism functional
✅ Graceful error handling verified
✅ YAML-driven validation operational
✅ Health scoring system working (detected real system issues)
This enables users to modify intelligence behavior by editing YAML files,
add new pattern types without coding, and hot-reload improvements in real-time.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update compression engine with improved YAML handling and error recovery
- Add comprehensive test suite with 10 test files covering edge cases
- Enhance hook system with better MCP intelligence and pattern detection
- Improve documentation with detailed configuration guides
- Add learned patterns for project optimization
- Strengthen notification and session lifecycle hooks
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Complete technical documentation for the SuperClaude Framework-Hooks system:
• Overview documentation explaining pattern-driven intelligence architecture
• Individual hook documentation for all 7 lifecycle hooks with performance targets
• Complete configuration documentation for all YAML/JSON config files
• Pattern system documentation covering minimal/dynamic/learned patterns
• Shared modules documentation for all core intelligence components
• Integration guide showing SuperClaude framework coordination
• Performance guide with optimization strategies and benchmarks
Key technical features documented:
- 90% context reduction through pattern-driven approach (50KB+ → 5KB)
- 10x faster bootstrap performance (500ms+ → <50ms)
- 7 lifecycle hooks with specific performance targets (50-200ms)
- 5-level compression system with quality preservation ≥95%
- Just-in-time capability loading with intelligent caching
- Cross-hook learning system for continuous improvement
- MCP server coordination for all 6 servers
- Integration with 4 behavioral modes and 8-step quality gates
Documentation provides complete technical reference for developers,
system administrators, and users working with the Framework-Hooks
system architecture and implementation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
Updated all root documentation to reflect V4 Beta capabilities:
Root Documentation:
- VERSION: Updated to 4.0.0-beta.1
- README.md: Complete rewrite with V4 features (21 commands, 13 agents, 6 MCP servers)
- ARCHITECTURE_OVERVIEW.md: Updated for V4 Beta with correct counts and new features
- CHANGELOG.md: Added comprehensive V4.0.0-beta.1 release section
- ROADMAP.md: Added V4 Beta current status and updated future vision
- CONTRIBUTING.md: Updated architecture, testing, and contribution guidelines
- SECURITY.md: Added V4 security features and version support table
- MANIFEST.in: Updated to include new V4 directories
- pyproject.toml: Updated URLs and description for V4 Beta
User Documentation:
- commands-guide.md: Updated to 21 commands with new V4 commands
- superclaude-user-guide.md: Comprehensive V4 Beta features documentation
- flags-guide.md: Updated with new V4 flags and agent system
- installation-guide.md: V4 Beta installation including hooks system
- agents-guide.md: NEW - Complete guide for 13 specialized agents
- personas-guide.md: Renamed to personas-guide-v3-legacy.md
Key V4 Beta Features Documented:
- 21 specialized commands (added: brainstorm, reflect, save, select-tool)
- 13 domain expert agents replacing persona system
- 6 MCP servers (added Morphllm and Serena)
- 4 Behavioral Modes (Brainstorming, Introspection, Task Management, Token Efficiency)
- Session Lifecycle with cross-session persistence
- Redesigned Hooks System with Python integration
- SuperClaude-Lite minimal implementation
- Comprehensive Templates system
All documentation maintains friendly, accessible tone while accurately reflecting V4 Beta's advanced capabilities.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Restructured core framework components
- Added new Agents, MCP servers, and Modes documentation
- Introduced SuperClaude-Lite minimal implementation
- Enhanced Commands with session management capabilities
- Added comprehensive Hooks system with Python integration
- Removed legacy setup and profile components
- Updated .gitignore to exclude Tests/, ClaudeDocs/, and .serena/
- Consolidated configuration into SuperClaude/Config/
- Added Templates for consistent component creation
This is the initial commit for the V4 Beta branch containing all recent framework improvements and architectural changes.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Description
Remove redundant `import sys` statement in SuperClaude/__main__.py that
was imported twice.
## Changes
- Removed duplicate `import sys` at line 22
- The sys module is already imported at line 14 with other standard
library imports
## Type of Change
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Documentation update
## Testing
- [x] Code still imports and runs correctly
- [x] No functionality is affected by this change
## Additional Notes
This is a minor code cleanup that improves code quality by removing
redundant imports.
## Summary
- Fix critical typo in playwright MCP server configuration
- Change @playright/mcp to @playwright/mcp in setup/components/mcp.py
- Prevents MCP installation failures due to package not found errors
## Test plan
- [x] Verify package name is correctly spelled as @playwright/mcp
- [x] Confirm no other playwright typos exist in codebase
- [x] Test MCP installation process works with corrected package name
🤖 Generated with [Claude Code](https://claude.ai/code)
# Fix Windows user directory validation for aliased usernames
## 🐛 Problem Description
The current security validation in `setup/utils/security.py` fails when
Windows users have an alias username that doesn't match their profile
directory name. This occurs because the validation constructs the
expected path using `%USERNAME%` but compares it against the actual
profile directory path.
### Issue Details
- **Error**: `Installation must be in current user's directory (A)`
- **Root Cause**: Username alias `A` != profile directory `User`
- **Affected Code**: `SecurityValidator.validate_installation_target()`
line ~390
### Example Scenario
```
USERNAME=A
USERPROFILE=C:\Users\User
Target Path=C:\Users\User\.claude
Expected by validation: \users\a\
Actual path contains: \users\user\
Result: Validation fails
```
## 🔧 Proposed Solution
Replace the username-based path construction with actual home directory
comparison
## 📋Changes Made
File: `setup/utils/security.py`
Lines ~385-395 in `validate_installation_target()` method:**
## ✅ Benefits
1. **Fixes alias username issue**: Works with any username/profile
directory combination
2. **More accurate validation**: Uses actual filesystem paths instead of
environment variables
3. **Maintains security**: Still prevents installation outside user
directory
4. **Better error messages**: Shows actual username when available
5. **Cross-platform compatibility**: `Path.home()` works on all
platforms
## 🧪 Test Cases
### Test Case 1: Alias Username (Current Bug)
```python
# Environment
USERNAME=A
USERPROFILE=C:\Users\User
# Test
target = Path("C:/Users/User/.claude")
result, errors = SecurityValidator.validate_installation_target(target)
# (currently fails)
assert result == True, "Expected success"
```
### Test Case 2: Matching Username (Currently Works)
```python
# Environment
USERNAME=User
USERPROFILE=C:\Users\User
# Test
target = Path("C:/Users/User/.claude")
result, errors = SecurityValidator.validate_installation_target(target)
assert result == True, "Expected success"
```
### Test Case 3: Outside User Directory (Should Fail)
```python
# Test
target = Path("C:/Users/OtherUser/.claude")
result, errors = SecurityValidator.validate_installation_target(target)
# Expected: Failure
assert result == False
assert "current user's directory" in errors[0]
```
## Related Issues
#190
The sys module was imported twice - once at line 14 with other standard
imports and again at line 22. The second import is redundant since sys
is already available from the first import.
Fix typo in playwright MCP server configuration where @playright/mcp
was incorrectly specified instead of @playwright/mcp, which would
cause installation failures.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
# summary
* this pr refactors superclaude’s install system to boost
maintainability, cut duplicate code, and most important fixes a bunch of
issues that ppl are having when trying to install v3
Fixes: #172#182#189#193#201#202#206#207
## key changes:
### architecture improvements
* moved shared logic to a base component class to reduce duplication.
* shifted config, file, and settings managers to a managers/ module for
better organization.
* streamlined installer logic by removing duplicate code patterns.
### component system refactoring
* unified install flow with custom hooks (_install(), _post_install()).
* components now auto-discover files, no hardcoding (sub)path names.
* centralized error handling and logging.
* security validation moved to base class for consistency.
### code organization
* simplified component files by leveraging base class logic.
* eliminated repetitive validation, install, and file management code.
* cleaned up imports after module restructure.
### loc impact
* 554 insertions, 863 deletions.
* net: 309 lines cut, with added functionality.
## next steps
### e2e tests
* test migration from v2: use an invalid `.claude/settings.json` with
superclaude config (i.e fields like `framework`, `components`) and
verify it migrates to the new metadata json.
### cleanup and chores
* there's still bits of dead code from the initial v3 commit that i've
noticed while refactoring this shit
* update documentation
* add guardrails (maybe use github actions?) so we can't push stuff that
breaks users envs onto master
* Consolidate installation check logic using SettingsManager methods
* Simplify component retrieval by delegating to SettingsManager
* Add 'all' components shorthand support in installer
* Component Base Class:
* Add constructor parameter for component subdirectory
* Move file discovery utilities to base class to avoid repetition in subclasses
* Same for validate_prerequisites, get_files_to_install, get_settings_modifications methods
* Split install method into _install and _post_install for better separation of concerns
* Add error handling wrapper around _install method
* All Component Subclasses:
* Remove duplicate code now handled by base class
* Use shared file discovery and installation logic
* Simplify metadata updates using base class methods
* Leverage base class file handling and validation
* Hooks Component:
* Fix the logic for handling both placeholder and actual hooks scenarios
* MCP Component:
* Fix npm package names and installation commands
* Move ConfigManager, SettingsManager, and FileManager from setup/core to setup/managers with new init.py for cleaner organization.
* Update SettingsManager with enhanced metadata handling methods and installation detection utilities.
While installing on my windows machine, I was getting error
```
python -m SuperClaude install
Traceback (most recent call last):
File "<frozen runpy>", line 189, in _run_module_as_main
File "<frozen runpy>", line 148, in _get_module_details
File "<frozen runpy>", line 159, in _get_module_details
File "<frozen importlib._bootstrap_external>", line 1160, in get_code
File "<frozen importlib._bootstrap_external>", line 1090, in source_to_code
File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
File "D:\prac_repo\AI\SuperClaude\SuperClaude\__main__.py", line 206
^
SyntaxError: invalid non-printable character U+00A0
```
* refactor: pyproject.toml to use Hatchling as the build backend and update project metadata
- Changed build backend from setuptools to hatchling.
- Updated project name, description, authors, and dependencies.
- Added project URLs and scripts section for SuperClaude.
- Configured versioning and build targets for wheel and sdist.
* feat: Update installation instructions in README.md to reflect new package management commands using 'uv' instead of 'pip'.
* feat: Add uv.lock file to manage package dependencies and versions for SuperClaude
* fix: Update library usage guidelines in RULES.md to reference pyproject.toml instead of requirements.txt
