External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Comprehensive documentation update for SuperClaude V4 Beta

Browse Source 
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>
This commit is contained in:
NomenAK
2025-08-05 14:44:37 +02:00
parent 1d03832f2d
commit 8ab6e9ebbe
15 changed files with 2258 additions and 576 deletions
Download Patch File Download Diff File Expand all files Collapse all files

298
CONTRIBUTING.md
View File

@@ -2,7 +2,7 @@
Thanks for your interest in contributing! 🙏
SuperClaude is a community-driven project that enhances Claude Code through modular hooks and intelligent orchestration. Every contribution helps make the framework more useful for developers.
SuperClaude is a community-driven project that enhances Claude Code through modular hooks, intelligent orchestration, specialized agents, and behavioral modes. Every contribution helps make the framework more useful for developers.
## 🚀 Quick Start
@@ -10,19 +10,24 @@ SuperClaude is a community-driven project that enhances Claude Code through modu
- Python 3.12+ (standard library only)
- Node.js 18+ (for MCP servers)
- Claude Code installed and authenticated
- uv package manager (recommended for development)
### Development Setup
```bash
# Clone the repository
git clone https://github.com/your-username/SuperClaude.git
cd SuperClaude
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# Install SuperClaude
./install.sh --standard
# Install dependencies with uv
uv sync
# Install SuperClaude V4 Beta
python -m pip install -e .
# Run tests
python Tests/comprehensive_test.py
python Tests/v4_integration_test.py
```
## 🎯 Ways to Contribute
@@ -46,53 +51,95 @@ python Tests/comprehensive_test.py
- Translate documentation (especially for Scribe persona)
### 🔧 Code Contributions
- Focus on hooks, commands, or core framework components
- Focus on hooks, commands, agents, modes, or core framework components
- Follow existing patterns and conventions
- Include tests for new functionality
- Update documentation as needed
### 🤖 Agents & Modes
- Create specialized agents for domain expertise
- Develop behavioral modes for enhanced workflow patterns
- Ensure proper integration with MCP servers
- Follow the SuperClaude orchestration principles
## 🏗️ Architecture Overview
### Core Components
```
SuperClaude/
SuperClaude_Framework/
├── SuperClaude/
│ ├── Hooks/ # 15 Python hooks (main extension points)
│ ├── Commands/ # 14 slash commands
│ ├── Core/ # Framework documentation
│ └── Settings/ # Configuration files
├── Scripts/ # Installation and utility scripts
└── Tests/ # Test suite
│ ├── Agents/ # 13 specialized domain agents
│ ├── Commands/ # 21 slash commands (/sc:load, /sc:save, etc.)
│ ├── Core/ # Framework documentation and rules
│ ├── Config/ # Configuration management
│ ├── Hooks/ # 22+ Python hooks (main extension points)
│ ├── MCP/ # 6 MCP server integrations
│ └── Modes/ # 4 behavioral modes
├── SuperClaude-Lite/ # Lightweight framework variant
├── Templates/ # Document and code templates
└── Tests/ # Comprehensive test suite
```
### Hook System
Hooks are the primary extension mechanism:
- **PreToolUse**: Intercept before tool execution
- **PostToolUse**: Process after tool completion
- **SubagentStop**: Handle sub-agent lifecycle
- **Stop**: Session cleanup and synthesis
- **Notification**: Real-time event processing
### V4 Beta Architecture
#### Agents System
Domain-specialized agents for expert capabilities:
- **system-architect.md**: System design and architecture
- **performance-optimizer.md**: Performance analysis and optimization
- **security-auditor.md**: Security assessment and hardening
- **frontend-specialist.md**: UI/UX and frontend development
- **brainstorm-PRD.md**: Requirements discovery and PRD generation
#### Modes System
Behavioral modes that modify Claude's operational approach:
- **MODE_Brainstorming.md**: Interactive requirements discovery
- **MODE_Task_Management.md**: Multi-layer task orchestration
- **MODE_Token_Efficiency.md**: Intelligent compression and optimization
- **MODE_Introspection.md**: Meta-cognitive analysis and troubleshooting
#### MCP Integration
Advanced server coordination for enhanced capabilities:
- **MCP_Serena.md**: Semantic code analysis and memory management
- **MCP_Sequential.md**: Multi-step problem solving
- **MCP_Magic.md**: UI component generation
- **MCP_Context7.md**: Library documentation lookup
- **MCP_Morphllm.md**: Intelligent file editing
- **MCP_Playwright.md**: Browser automation and testing
#### Hook System
Enhanced hooks with session lifecycle and performance monitoring:
- **Session Lifecycle**: Load, checkpoint, save operations
- **Performance Monitoring**: Real-time metrics and optimization
- **Quality Gates**: 8-step validation framework
- **Framework Coordination**: Agent and mode orchestration
## 🧪 Testing
### Running Tests
```bash
# Full test suite
# Full V4 test suite
python Tests/comprehensive_test.py
python Tests/v4_integration_test.py
# Specific components
python Tests/task_management_test.py
python Tests/performance_test_suite.py
# Component-specific tests
python Tests/agent_system_test.py
python Tests/mode_coordination_test.py
python Tests/mcp_integration_test.py
python Tests/session_lifecycle_test.py
# Hook integration tests
python SuperClaude/Hooks/test_orchestration_integration.py
python SuperClaude/Hooks/test_session_lifecycle.py
python SuperClaude/Hooks/test_performance_monitoring.py
```
### Writing Tests
- Test hook behavior with mock data
- Include performance benchmarks
- Test error conditions and recovery
- Validate cross-component integration
- Test hook behavior with mock data and session context
- Include performance benchmarks for V4 features
- Test error conditions and recovery mechanisms
- Validate cross-component integration (agents, modes, MCP)
- Test session lifecycle operations (/sc:load, /sc:save)
- Validate mode coordination and behavioral patterns
## 📋 Code Standards
@@ -101,33 +148,121 @@ python SuperClaude/Hooks/test_orchestration_integration.py
#!/usr/bin/env python3
"""
Brief description of hook purpose.
Part of SuperClaude Framework v3.0
Part of SuperClaude Framework V4 Beta
"""
import json
import sys
from typing import Dict, Any
from typing import Dict, Any, Optional
from pathlib import Path
def process_hook_data(data: Dict[str, Any]) -> Dict[str, Any]:
"""Process hook data with proper error handling."""
"""Process hook data with V4 session lifecycle support."""
try:
# Implementation here
return {"status": "success", "data": result}
# V4 features: session context, performance metrics
session_id = data.get('session_id')
context = data.get('context', {})
# Implementation here with V4 patterns
result = {
"status": "success",
"data": result_data,
"session_id": session_id,
"metrics": {"execution_time_ms": elapsed_time}
}
return result
except Exception as e:
return {"status": "error", "message": str(e)}
return {
"status": "error",
"message": str(e),
"session_id": data.get('session_id')
}
if __name__ == "__main__":
# Standard hook entry point
# V4 standard hook entry point with session support
input_data = json.loads(sys.stdin.read())
result = process_hook_data(input_data)
print(json.dumps(result))
```
### Agent Documentation (Markdown)
```markdown
---
name: agent-name
description: "Brief description of agent's domain expertise"
type: domain-specialist
category: [architecture|performance|security|frontend|backend]
complexity: [basic|standard|advanced|expert]
scope: [module|system|enterprise]
# Integration Configuration
framework-integration:
mcp-servers: [serena, sequential, context7]
commands: [relevant-commands]
modes: [relevant-modes]
quality-gates: [relevant-validation-steps]
# Performance Profile
performance-profile: [lightweight|standard|intensive]
---
# Agent Name
**Domain expertise description** with specific capabilities.
## Core Capabilities
- Specific technical expertise
- Domain-specific analysis
- Integration patterns
## Integration Points
- MCP server coordination
- Command workflows
- Mode interactions
```
### Mode Documentation (YAML + Markdown)
```markdown
---
name: mode-name
description: "Behavioral modification description"
type: behavioral
# Mode Classification
category: [orchestration|optimization|analysis]
complexity: [basic|standard|advanced]
scope: [session|project|framework]
# Activation Configuration
activation:
automatic: true
manual-flags: ["--flag"]
confidence-threshold: 0.7
detection-patterns: ["pattern keywords"]
# Integration Configuration
framework-integration:
mcp-servers: [relevant-servers]
commands: [relevant-commands]
modes: [coordinated-modes]
quality-gates: [validation-steps]
# Performance Profile
performance-profile: [lightweight|standard|intensive]
---
# Mode Name
Mode description and behavioral patterns.
```
### Documentation (Markdown)
- Use clear headings and structure
- Include code examples where helpful
- Use clear headings and structure with V4 component organization
- Include code examples for agents, modes, and MCP integration
- Add emoji sparingly for clarity 🎯
- Keep language humble and developer-focused
- Follow YAML frontmatter standards for agents and modes
- Document integration points and behavioral patterns
### Commit Messages
```
@@ -138,9 +273,11 @@ Longer explanation if needed.
- Specific changes made
- Why the change was needed
- Any breaking changes noted
- V4 component impacts (agents, modes, hooks)
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
Scopes: `agents`, `modes`, `hooks`, `mcp`, `core`, `commands`, `lifecycle`
## 🔄 Development Workflow
@@ -150,15 +287,18 @@ git checkout -b feature/your-feature-name
```
### 2. Develop & Test
- Make focused, atomic changes
- Test locally with `--standard` installation
- Ensure hooks don't break existing functionality
- Make focused, atomic changes aligned with V4 architecture
- Test locally with V4 Beta installation (`python -m pip install -e .`)
- Ensure hooks, agents, and modes don't break existing functionality
- Test session lifecycle operations (/sc:load, /sc:save)
- Validate MCP server integration and coordination
### 3. Submit Pull Request
- Clear title and description
- Reference related issues
- Include test results
- Update documentation if needed
- Clear title and description with V4 component impact
- Reference related issues and architectural decisions
- Include test results for affected components (agents, modes, hooks)
- Update documentation for new features and integration points
- Demonstrate compatibility with existing V4 systems
### 4. Code Review
- Address feedback promptly
@@ -169,16 +309,20 @@ git checkout -b feature/your-feature-name
### Version Management
- Follow [Semantic Versioning](https://semver.org/)
- Update `VERSION` file
- Document changes in `CHANGELOG.md`
- Tag releases: `git tag v3.0.1`
- Update `VERSION` file and `pyproject.toml`
- Document changes in `CHANGELOG.md` with V4 component impacts
- Tag releases: `git tag v4.0.0-beta.1`
- Consider V4 Beta stability and migration path
### Release Checklist
- [ ] All tests pass
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version bumped
- [ ] Installation tested on clean system
- [ ] All V4 tests pass (comprehensive, integration, component-specific)
- [ ] Documentation updated for new agents, modes, and features
- [ ] CHANGELOG.md updated with V4 component changes
- [ ] Version bumped in `VERSION` and `pyproject.toml`
- [ ] V4 Beta installation tested on clean system
- [ ] Session lifecycle operations validated
- [ ] MCP server coordination tested
- [ ] Agent and mode integration verified
## 🤝 Community Guidelines
@@ -206,14 +350,50 @@ git checkout -b feature/your-feature-name
### Common Questions
**Q: How do I debug hook execution?**
A: Check logs in `~/.claude/` and use verbose logging for detailed output.
**Q: How do I debug V4 hook execution and session lifecycle?**
A: Check logs in `~/.claude/` and use verbose logging. Monitor session state with `/sc:load` and `/sc:save` operations.
**Q: Can I add new MCP servers?**
A: Yes! Follow the pattern in `settings.json` and add integration hooks.
**Q: Can I add new MCP servers or agents?**
A: Yes! Follow the patterns in `SuperClaude/MCP/` for servers and `SuperClaude/Agents/` for domain specialists. Include proper YAML frontmatter and integration points.
**Q: How do I test changes without affecting my global setup?**
A: Use a separate test environment or backup your `~/.claude` directory before testing.
**Q: How do I test V4 changes without affecting my global setup?**
A: Use a separate test environment with `python -m pip install -e .` for development installation. Backup your `~/.claude` directory and test session operations.
**Q: How do I create a new behavioral mode?**
A: Follow the pattern in `SuperClaude/Modes/` with proper YAML frontmatter, activation patterns, and framework integration configuration.
**Q: What's the difference between agents and modes?**
A: Agents provide domain expertise (system-architect, performance-optimizer), while modes modify Claude's behavioral approach (brainstorming, task management, token efficiency).
## 🚀 Contributing to V4 Components
### Creating New Agents
1. **Domain Research**: Identify specific expertise area and common patterns
2. **Template Usage**: Use existing agents as templates (e.g., `system-architect.md`)
3. **YAML Configuration**: Include proper frontmatter with integration points
4. **Capability Documentation**: Define core capabilities and integration patterns
5. **Testing**: Create agent-specific tests and validate MCP coordination
### Developing Behavioral Modes
1. **Behavioral Analysis**: Define how the mode modifies Claude's approach
2. **Activation Patterns**: Specify automatic and manual triggers
3. **Framework Integration**: Document MCP servers, commands, and quality gates
4. **Performance Profiling**: Define lightweight/standard/intensive characteristics
5. **Mode Coordination**: Ensure compatibility with existing modes
### Enhancing Session Lifecycle
1. **Hook Integration**: Understand session lifecycle hooks and patterns
2. **Performance Targets**: Meet <500ms load times and <200ms memory operations
3. **Context Management**: Implement proper session state preservation
4. **Error Recovery**: Handle checkpoint failures and session restoration
5. **Memory Optimization**: Follow selective compression patterns
### MCP Server Integration
1. **Server Capabilities**: Understand server specializations and coordination
2. **Performance Benchmarks**: Meet server-specific performance targets
3. **Fallback Strategies**: Implement graceful degradation patterns
4. **Quality Gates**: Integrate with validation frameworks
5. **Cross-Server Coordination**: Enable hybrid intelligence patterns
## 📄 License
@@ -221,4 +401,4 @@ By contributing, you agree that your contributions will be licensed under the MI
## 🙏 Acknowledgments
Thanks to all contributors who help make SuperClaude better for the development community!
Thanks to all contributors who help make SuperClaude V4 Beta better for the development community! Special recognition for those contributing to the new agents system, behavioral modes, session lifecycle, and MCP server coordination that make V4's intelligent orchestration possible.