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

Restructure documentation: Create focused guide ecosystem from oversized user guide

Browse Source 
- 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>
This commit is contained in:
NomenAK
2025-08-15 21:30:29 +02:00
parent 9a5e2a01ff
commit 40840dae0b
91 changed files with 7666 additions and 15055 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
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, intelligent orchestration, specialized agents, and behavioral modes. Every contribution helps make the framework more useful for developers.
SuperClaude is a community-driven project that enhances Claude Code through intelligent orchestration, specialized agents, and behavioral modes. Every contribution helps make the framework more useful for developers.
## 🚀 Quick Start
@@ -19,9 +19,6 @@ SuperClaude is a community-driven project that enhances Claude Code through modu
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# Install dependencies with uv
uv sync
# Install SuperClaude V4 Beta
python -m pip install -e .
@@ -36,7 +33,7 @@ python Tests/v4_integration_test.py
- Use GitHub Issues with the "bug" label
- Include system info (OS, Python/Node versions)
- Provide minimal reproduction steps
- Include relevant hook logs from `~/.claude/`
- Include relevant logs from `~/.claude/`
### 💡 Feature Requests
- Check existing issues and roadmap first
@@ -51,7 +48,7 @@ python Tests/v4_integration_test.py
- Translate documentation (especially for Scribe persona)
### 🔧 Code Contributions
- Focus on hooks, commands, agents, modes, or core framework components
- Focus on commands, agents, modes, or core framework components
- Follow existing patterns and conventions
- Include tests for new functionality
- Update documentation as needed
@@ -72,11 +69,9 @@ SuperClaude_Framework/
│ ├── 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
│ └── Modes/ # 5 behavioral modes
├── Guides/ # User guides and documentation
└── Tests/ # Comprehensive test suite
```
@@ -85,10 +80,10 @@ SuperClaude_Framework/
#### 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
- **performance-engineer.md**: Performance analysis and optimization
- **security-engineer.md**: Security assessment and hardening
- **frontend-architect.md**: UI/UX and frontend development
- **requirements-analyst.md**: Requirements discovery and analysis
#### Modes System
Behavioral modes that modify Claude's operational approach:
@@ -106,155 +101,7 @@ Advanced server coordination for enhanced capabilities:
- **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 V4 test suite
python Tests/comprehensive_test.py
python Tests/v4_integration_test.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 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
### Python Code (Hooks)
```python
#!/usr/bin/env python3
"""
Brief description of hook purpose.
Part of SuperClaude Framework V4 Beta
"""
import json
import sys
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 V4 session lifecycle support."""
try:
# 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),
"session_id": data.get('session_id')
}
if __name__ == "__main__":
# 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.
```
## 📝 Contribution Guidelines
### Documentation (Markdown)
- Use clear headings and structure with V4 component organization
@@ -273,11 +120,11 @@ Longer explanation if needed.
- Specific changes made
- Why the change was needed
- Any breaking changes noted
- V4 component impacts (agents, modes, hooks)
- V4 component impacts (agents, modes, core components)
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
Scopes: `agents`, `modes`, `hooks`, `mcp`, `core`, `commands`, `lifecycle`
Scopes: `agents`, `modes`, `mcp`, `core`, `commands`, `lifecycle`
## 🔄 Development Workflow
@@ -289,14 +136,14 @@ git checkout -b feature/your-feature-name
### 2. Develop & Test
- 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
- Ensure 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 with V4 component impact
- Reference related issues and architectural decisions
- Include test results for affected components (agents, modes, hooks)
- Include test results for affected components (agents, modes, framework)
- Update documentation for new features and integration points
- Demonstrate compatibility with existing V4 systems
@@ -350,7 +197,7 @@ git checkout -b feature/your-feature-name
### Common Questions
**Q: How do I debug V4 hook execution and session lifecycle?**
**Q: How do I debug V4 framework 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 or agents?**
@@ -363,7 +210,7 @@ A: Use a separate test environment with `python -m pip install -e .` for develop
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).
A: Agents provide domain expertise (system-architect, performance-engineer), while modes modify Claude's behavioral approach (brainstorming, task management, token efficiency).
## 🚀 Contributing to V4 Components
@@ -382,7 +229,7 @@ A: Agents provide domain expertise (system-architect, performance-optimizer), wh
5. **Mode Coordination**: Ensure compatibility with existing modes
### Enhancing Session Lifecycle
1. **Hook Integration**: Understand session lifecycle hooks and patterns
1. **Framework Integration**: Understand session lifecycle 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