- Transform 28K+ token superclaude-user-guide.md into 4.5K token overview (84% reduction)
- Extract specialized guides: examples-cookbook.md, troubleshooting-guide.md, best-practices.md, session-management.md, technical-architecture.md
- Add comprehensive cross-references between all guides for improved navigation
- Maintain professional documentation quality with technical-writer agent approach
- Remove template files and consolidate agent naming (backend-engineer → backend-architect, etc.)
- Update all existing guides with cross-references and related guides sections
- Create logical learning paths from beginner to advanced users
- Eliminate content duplication while preserving all valuable information
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Version Management & Consistency
- Update to version 4.0.0b1 (proper beta versioning for PyPI)
- Add __version__ attribute to SuperClaude/__init__.py
- Ensure version consistency across pyproject.toml, __main__.py, setup/__init__.py
## Enhanced Package Configuration
- Improve pyproject.toml with comprehensive PyPI classifiers
- Add proper license specification and enhanced metadata
- Configure package discovery with inclusion/exclusion patterns
- Add development and test dependencies
## Publishing Scripts & Tools
- scripts/build_and_upload.py: Advanced Python script for building and uploading
- scripts/publish.sh: User-friendly shell wrapper for common operations
- scripts/validate_pypi_ready.py: Comprehensive validation and readiness checker
- All scripts executable with proper error handling and validation
## GitHub Actions Automation
- .github/workflows/publish-pypi.yml: Complete CI/CD pipeline
- Automatic publishing on GitHub releases
- Manual workflow dispatch for TestPyPI uploads
- Package validation and installation testing
## Documentation & Security
- PUBLISHING.md: Comprehensive PyPI publishing guide
- scripts/README.md: Detailed script usage documentation
- .env.example: Environment variable template
- Secure token handling with both .pypirc and environment variables
## Features
✅ Version consistency validation across all files
✅ Comprehensive PyPI metadata and classifiers
✅ Multi-environment publishing (TestPyPI + PyPI)
✅ Automated GitHub Actions workflow
✅ Security best practices for API token handling
✅ Complete documentation and troubleshooting guides
✅ Enterprise-grade validation and error handling
The SuperClaude Framework is now fully prepared for PyPI publication
with professional-grade automation, validation, and documentation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhanced uninstall operation with interactive component selection and precision targeting:
- **Safety Verification**: Added verify_superclaude_file() and verify_directory_safety()
functions to ensure only SuperClaude files are removed, preserving user customizations
- **Interactive Component Selection**: Multi-level menu system for granular uninstall control
with complete vs custom uninstall options
- **Precise File Targeting**: Commands only removes files from commands/sc/ subdirectory,
agents only removes SuperClaude agent files, preserving user's custom content
- **Environment Variable Management**: Optional API key cleanup with restore script generation
- **MCP Configuration Safety**: Only removes SuperClaude-managed MCP servers, preserves
user customizations in .claude.json
- **Enhanced Display**: Clear visualization of what will be removed vs preserved with
detailed safety guarantees and file counts
- **Error Recovery**: All verification functions default to preserve if uncertain
Enhanced update operation with API key collection:
- **API Key Collection**: Update now collects API keys for new MCP servers during updates
- **Environment Integration**: Seamless environment variable setup for collected keys
- **Cross-Platform Support**: Windows and Unix environment variable management
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Features:
- Secure API key collection via getpass (hidden input)
- Cross-platform environment variable setup
- Automatic .claude.json configuration with ${ENV_VAR} syntax
- Seamless integration with existing MCP server selection flow
- Skip options for manual configuration later
Implementation:
- Added prompt_api_key() function to setup/utils/ui.py
- Created setup/utils/environment.py for cross-platform env management
- Enhanced MCP server selection in setup/cli/commands/install.py
- Updated MCP component to handle API key configuration
- Preserves user customizations while adding environment variables
Security:
- Hidden input prevents API keys from being displayed
- No logging of sensitive data
- OS-native environment variable storage
- Basic validation with user confirmation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update installer backup to exclude local/ directory containing Claude Code files
- Update backup command to skip files in local/ and backups/ directories
- Prevent Claude Code installation files from being included in SuperClaude backups
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhanced MCP component to preserve user customizations while adding missing configs:
✨ Precision Merging:
- Only adds missing MCP server configurations
- Preserves all existing user customizations
- Never overwrites user-modified settings
- Logs what was preserved vs. added
🛡️ Smart Uninstall:
- Only removes SuperClaude-managed servers
- Detects user-customized configs and preserves them
- Compares against templates to identify SuperClaude vs. user configs
- Tracks installed servers via metadata
🔧 Key Features:
- _merge_mcp_server_config(): Intelligent key-by-key merging
- _is_superclaude_managed_server(): Template comparison for safe removal
- _get_installed_servers(): Metadata-based tracking
- Detailed logging of preservation vs. modification actions
Benefits:
- Respects user workflow and customizations
- Safe to re-run installations
- Clean uninstalls without data loss
- Professional configuration management
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed AttributeError where selected_servers was accessed before initialization.
The issue was that Component.__init__() calls _discover_component_files()
which tried to access self.selected_servers before it was set.
Solution: Initialize selected_servers and server_docs_map before calling
super().__init__() to ensure they're available when needed.
Fixes:
- mcp_docs component now properly discovered and listed
- Installation commands work correctly with mcp_docs
- Dry-run installations complete successfully
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major structural changes:
- Merged base/ into core/ directory for better organization
- Renamed managers/ to services/ for service-oriented architecture
- Moved operations/ to cli/commands/ for cleaner CLI structure
- Moved config/ to data/ for static configuration files
Class naming conventions:
- Renamed all *Manager classes to *Service classes
- Updated 200+ import references throughout codebase
- Maintained backward compatibility for all functionality
Modern Python packaging:
- Created comprehensive pyproject.toml with build configuration
- Modernized setup.py to defer to pyproject.toml
- Added development tools configuration (black, mypy, pytest)
- Fixed deprecation warnings for license configuration
Comprehensive testing:
- All 37 Python files compile successfully
- All 17 modules import correctly
- All CLI commands functional (install, update, backup, uninstall)
- Zero errors in syntax validation
- 100% working functionality maintained
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove profiles/ directory with all profile JSON files
- Update install.py to remove profile CLI options and simplify flow
- Make interactive two-stage selection (MCP → Components) the default
- Remove ConfigManager.load_profile() method
- Update documentation to reflect simplified installation process
- Add CLAUDEMdManager for intelligent CLAUDE.md import management
- Components now install to root directory with organized @imports
- Preserve user customizations while managing framework imports
This simplifies the installation experience while providing users
direct control over what gets installed through the intuitive
two-stage selection process.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Created AgentsComponent class in setup/components/agents.py
- Added agents component to features.json configuration
- Updated components __init__.py to import AgentsComponent
- Added agents to "all" components list in install.py
- Updated developer and quick installation profiles to include agents
- Agents component installs 13 specialized AI agent files to ~/.claude/agents/
The 13 specialized agents (system-architect, frontend-specialist, security-auditor,
etc.) are now properly exposed in the installation process, aligning with V4 Beta's
marketing of "13 specialized agents with domain expertise".
Users can now:
- Install agents via --components agents or --components all
- See agents in interactive component selection menu
- Get agents included in developer and quick installation profiles
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Commented out HooksComponent import and export in __init__.py
- Removed hooks from --components all installation list
- Set enabled=false in features.json configuration
- Updated descriptions to indicate "NOT YET IMPLEMENTED"
- Code remains intact for future re-enablement
The Hooks system is not yet fully implemented, so hiding it from
users prevents confusion while preserving the framework for future use.
🤖 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>
## 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 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>
* 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.
- Fixed `/dev/` pattern to `^/dev/` to only match system device directories
- Added start-of-path anchors (^) to all Unix and Windows system directory patterns
- Separated patterns into logical categories for better maintainability
- Enhanced cross-platform path normalization and error messages
- Improved platform-specific validation logic
This allows users with "dev", "tmp", "bin", etc. in their paths to install
SuperClaude while maintaining all existing security protections.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
fix /sc:implement missing from claude code command line
Signed-off-by: Hung Kwan Li <71382503+backpack-0x1337@users.noreply.github.com>
Co-authored-by: Hung Kwan Li <71382503+backpack-0x1337@users.noreply.github.com>
- Add --scope user flag to claude mcp add commands in MCP component
- Makes MCP servers globally available across all projects instead of local-only
- Updates all logging messages to reflect user scope installation
- Keeps remove commands scope-agnostic for better compatibility
- Resolves issue where MCP servers were only available in SuperClaude directory
Fixes#127🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add shell=True parameter to subprocess.run() calls on Windows platform
- Fixes issue #128 where Claude CLI, Node.js, and npm were not detected in PowerShell
- Affects validator.py and mcp.py components for better Windows compatibility
- Resolves PowerShell PATH inheritance issues with Python subprocess
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update all command documentation with improved clarity and examples
- Enhance user guides with simplified activation patterns
- Improve installation and setup documentation
- Refine command system implementation in setup components
- Update changelog with recent improvements
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Core component installation was missing the component registration step,
causing post-installation validation to fail with "Core component not
registered in metadata" while commands and MCP components passed.
Added missing add_component_registration() call in CoreComponent.install()
to match the pattern used by other components.
Fixes validation error without affecting functionality.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Enhanced Windows path validation with proper normalization
- Added junction point and symbolic link detection for security
- Improved Windows-specific error messages with actionable guidance
- Implemented security audit logging for installation decisions
- Maintained cross-platform compatibility and existing protections
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Separate SuperClaude metadata from Claude Code settings.json
- Create .superclaude-metadata.json for framework-specific data
- Fix JSON validation issues with settings management
- Update all components to use proper metadata storage
- Maintain compatibility with Claude Code settings format
- Add migration support for existing installations
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
The Claude CLI requires both name and command parameters for 'mcp add':
claude mcp add <name> <commandOrUrl>
This commit:
- Adds 'command' field to all MCP server definitions
- Updates _install_mcp_server to use both server name and command
- Fixes the subprocess call to include both required parameters
Fixes: Failed to install MCP server sequential-thinking: error: missing required argument 'commandOrUrl'
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
