SuperClaude/CONTRIBUTING.md

Contributing to SuperClaude Framework

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.

🚀 Quick Start

Prerequisites

• Python 3.12+ (standard library only)
• Node.js 18+ (for MCP servers)
• Claude Code installed and authenticated

Development Setup

# Clone the repository
git clone https://github.com/your-username/SuperClaude.git
cd SuperClaude

# Install SuperClaude
./install.sh --standard

# Run tests
python Tests/comprehensive_test.py

🎯 Ways to Contribute

🐛 Bug Reports

• Use GitHub Issues with the "bug" label
• Include system info (OS, Python/Node versions)
• Provide minimal reproduction steps
• Include relevant hook logs from ~/.claude/

💡 Feature Requests

• Check existing issues and roadmap first
• Use GitHub Issues with the "enhancement" label
• Describe the use case and expected behavior
• Consider if it fits the framework's modular philosophy

📝 Documentation

• Fix typos or unclear explanations
• Add examples and use cases
• Improve installation guides
• Translate documentation (especially for Scribe persona)

🔧 Code Contributions

• Focus on hooks, commands, or core framework components
• Follow existing patterns and conventions
• Include tests for new functionality
• Update documentation as needed

🏗️ Architecture Overview

Core Components

SuperClaude/
├── 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

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

🧪 Testing

Running Tests

# Full test suite
python Tests/comprehensive_test.py

# Specific components
python Tests/task_management_test.py
python Tests/performance_test_suite.py

# Hook integration tests
python SuperClaude/Hooks/test_orchestration_integration.py

Writing Tests

• Test hook behavior with mock data
• Include performance benchmarks
• Test error conditions and recovery
• Validate cross-component integration

📋 Code Standards

Python Code (Hooks)

#!/usr/bin/env python3
"""
Brief description of hook purpose.
Part of SuperClaude Framework v3.0
"""

import json
import sys
from typing import Dict, Any

def process_hook_data(data: Dict[str, Any]) -> Dict[str, Any]:
    """Process hook data with proper error handling."""
    try:
        # Implementation here
        return {"status": "success", "data": result}
    except Exception as e:
        return {"status": "error", "message": str(e)}

if __name__ == "__main__":
    # Standard hook entry point
    input_data = json.loads(sys.stdin.read())
    result = process_hook_data(input_data)
    print(json.dumps(result))

Documentation (Markdown)

• Use clear headings and structure
• Include code examples where helpful
• Add emoji sparingly for clarity 🎯
• Keep language humble and developer-focused

Commit Messages

type(scope): brief description

Longer explanation if needed.

- Specific changes made
- Why the change was needed
- Any breaking changes noted

Types: feat, fix, docs, test, refactor, perf, chore

🔄 Development Workflow

1. Fork & Branch

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

3. Submit Pull Request

• Clear title and description
• Reference related issues
• Include test results
• Update documentation if needed

4. Code Review

• Address feedback promptly
• Keep discussions focused and respectful
• Be open to suggestions and improvements

📦 Release Process

Version Management

• Follow Semantic Versioning
• Update VERSION file
• Document changes in CHANGELOG.md
• Tag releases: git tag v3.0.1

Release Checklist

• All tests pass
• Documentation updated
• CHANGELOG.md updated
• Version bumped
• Installation tested on clean system

🤝 Community Guidelines

Be Respectful

• Welcome newcomers and different experience levels
• Focus on the code and ideas, not personal attributes
• Help others learn and improve

Stay Focused

• Keep discussions relevant to SuperClaude's goals
• Avoid scope creep in feature requests
• Consider if changes fit the modular philosophy

Quality First

• Test your changes thoroughly
• Consider performance impact
• Think about maintainability

💬 Getting Help

Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions and ideas
• Documentation: Check existing guides first

Common Questions

Q: How do I debug hook execution? A: Check logs in ~/.claude/ and use verbose logging for detailed output.

Q: Can I add new MCP servers? A: Yes! Follow the pattern in settings.json and add integration hooks.

Q: How do I test changes without affecting my global setup? A: Use a separate test environment or backup your ~/.claude directory before testing.

📄 License

By contributing, you agree that your contributions will be licensed under the MIT License.

🙏 Acknowledgments

Thanks to all contributors who help make SuperClaude better for the development community!