diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e2a38bd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,114 @@ +name: πŸ› Bug Report +description: Report a bug or issue with SuperClaude +title: "[Bug] " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug! Please provide the following information to help us fix it. + + - type: input + id: superclaude-version + attributes: + label: SuperClaude Version + description: What version of SuperClaude are you using? + placeholder: v4.0.0 + validations: + required: true + + - type: input + id: claude-code-version + attributes: + label: Claude Code Version + description: What version of Claude Code are you using? + placeholder: Latest + validations: + required: true + + - type: dropdown + id: operating-system + attributes: + label: Operating System + description: What operating system are you using? + options: + - macOS + - Windows + - Linux (Ubuntu) + - Linux (Other) + - Other + validations: + required: true + + - type: textarea + id: bug-description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Describe what happened... + validations: + required: true + + - type: textarea + id: reproduction-steps + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Run command: /user:analyze --code + 2. Open file X + 3. See error... + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: Command should analyze code successfully... + validations: + required: true + + - type: textarea + id: actual-behavior + attributes: + label: Actual Behavior + description: What actually happened? + placeholder: Command failed with error... + validations: + required: true + + - type: textarea + id: error-messages + attributes: + label: Error Messages + description: Include any error messages or logs + placeholder: | + ``` + Error: Cannot find file... + ``` + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context about the problem here + placeholder: Screenshots, configuration files, etc. + validations: + required: false + + - type: checkboxes + id: terms + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched for existing issues + required: true + - label: I have provided all required information + required: true + - label: I can reproduce this issue consistently + required: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..711945e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,119 @@ +name: ✨ Feature Request +description: Suggest a new feature or enhancement for SuperClaude +title: "[Feature] " +labels: ["enhancement", "needs-discussion"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please provide details to help us understand your request. + + - type: dropdown + id: feature-type + attributes: + label: Feature Type + description: What type of feature are you requesting? + options: + - New Slash Command + - New Persona + - MCP Integration + - Configuration Enhancement + - Documentation Improvement + - Installation/Setup + - Other + validations: + required: true + + - type: textarea + id: problem-description + attributes: + label: Problem Description + description: What problem does this feature solve? + placeholder: I'm frustrated when I try to... because... + validations: + required: true + + - type: textarea + id: proposed-solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see + placeholder: | + I would like to see... + + Example usage: + /user:newcommand --flag + validations: + required: true + + - type: textarea + id: alternative-solutions + attributes: + label: Alternative Solutions + description: Describe alternatives you've considered + placeholder: I also considered... but it doesn't work because... + validations: + required: false + + - type: textarea + id: use-cases + attributes: + label: Use Cases + description: Describe specific scenarios where this would be useful + placeholder: | + 1. When working on React projects... + 2. During code reviews... + 3. For debugging performance issues... + validations: + required: true + + - type: textarea + id: examples + attributes: + label: Examples + description: Provide concrete examples of how this feature would work + placeholder: | + Command: /user:example --new-flag + Output: Expected behavior... + + Persona usage: + /persona:newtype β†’ specialized behavior + validations: + required: false + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Nice to have + - Would be helpful + - Important for my workflow + - Critical/Blocking + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, or examples + placeholder: Links to similar features, mockups, related issues... + validations: + required: false + + - type: checkboxes + id: terms + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched for existing feature requests + required: true + - label: I have provided a clear use case + required: true + - label: I'm willing to help test this feature + required: false + - label: I'm willing to help implement this feature + required: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..91b0dcd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,87 @@ +name: ❓ Question +description: Ask a question about SuperClaude usage or configuration +title: "[Question] " +labels: ["question", "help-wanted"] +body: + - type: markdown + attributes: + value: | + Have a question about SuperClaude? We're here to help! + + **Tip:** Consider using [Discussions](../../discussions) for general questions and community help. + + - type: dropdown + id: question-type + attributes: + label: Question Type + description: What type of question is this? + options: + - Installation/Setup + - Command Usage + - Persona Configuration + - MCP Integration + - Troubleshooting + - Best Practices + - Other + validations: + required: true + + - type: textarea + id: question + attributes: + label: Your Question + description: What would you like to know? + placeholder: How do I... / Why does... / What's the best way to... + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context + description: Provide context about what you're trying to achieve + placeholder: | + I'm trying to... + My setup is... + I've already tried... + validations: + required: false + + - type: textarea + id: current-config + attributes: + label: Current Configuration + description: Share relevant configuration or commands you're using + placeholder: | + ``` + /user:command --flags + Persona: architect + Claude Code version: latest + ``` + validations: + required: false + + - type: textarea + id: attempted-solutions + attributes: + label: What Have You Tried? + description: What solutions have you already attempted? + placeholder: | + 1. I tried reading the documentation... + 2. I searched for similar issues... + 3. I tested with different settings... + validations: + required: false + + - type: checkboxes + id: terms + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have read the README.md + required: true + - label: I have searched existing issues and discussions + required: true + - label: This is not a bug report (use Bug Report template instead) + required: true \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..b617e3a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,62 @@ +# Pull Request + +## Legend +| Symbol | Meaning | | Abbrev | Meaning | +|--------|---------|---|--------|---------| +| β†’ | leads to | | cfg | configuration | +| βœ“ | completed | | PR | pull request | + +## Summary +Brief description of changes + +## Type of Change +- [ ] πŸ› 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 +- [ ] πŸ”§ Configuration change +- [ ] 🎨 Code style/formatting change +- [ ] ♻️ Refactoring (no functional changes) +- [ ] ⚑ Performance improvement +- [ ] πŸ”’ Security fix + +## Changes Made +- Change 1 +- Change 2 +- Change 3 + +## Testing +- [ ] Tested install.sh on clean system +- [ ] Verified slash commands work in Claude Code +- [ ] Checked YAML syntax validity +- [ ] Tested persona functionality +- [ ] Tested MCP integration +- [ ] Manual testing performed +- [ ] All existing tests pass + +## Related Issues +Fixes #(issue number) +Closes #(issue number) +Related to #(issue number) + +## Screenshots (if applicable) + + +## Checklist +- [ ] My code follows the project's style guidelines +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published + +## Additional Notes + + +## Breaking Changes + + +--- +**Ready for review!** πŸš€ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bd94731 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,109 @@ +# Changelog + +## Legend +| Symbol | Meaning | | Abbrev | Meaning | +|--------|---------|---|--------|---------| +| β†’ | leads to | | cfg | configuration | +| + | added | | MCP | Model Context Protocol | +| - | removed | | UI | user interface | +| ! | breaking | | deps | dependencies | + +All notable changes to SuperClaude will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] +### Added +- Community interaction files +- GitHub issue & PR templates +- Contributing guidelines + +## [4.0.0] - 2025-06-22 +### Added +- **Core Configuration Framework** + - CLAUDE.md β†’ Main cfg + ops rules + - RULES.md β†’ Governance + severity system (C/H/M/L) + - PERSONAS.md β†’ 9 cognitive archetypes + - MCP.md β†’ Model Context Protocol integration patterns + +- **Slash Commands (18)** + - Dev: build, dev-setup, test + - Analysis: analyze, troubleshoot, improve, explain + - Ops: deploy, migrate, scan, estimate, cleanup, git + - Design: design + - Workflow: spawn, document + - System: load + +- **Shared Resources (26)** + - YAML configuration files + - Workflow patterns & templates + - Performance monitoring + - Error recovery strategies + +- **Cognitive Personas (9)** + - architect β†’ System design & long-term thinking + - frontend β†’ UX & interface optimization + - backend β†’ Performance & reliability + - analyzer β†’ Root cause analysis + - security β†’ Threat modeling & secure design + - mentor β†’ Teaching & guided discovery + - refactorer β†’ Code quality & simplification + - performance β†’ Speed optimization + - qa β†’ Quality assurance & testing + +- **MCP Integration** + - Context7 β†’ Documentation lookup + - Sequential β†’ Complex analysis + - Magic β†’ UI component generation + - Puppeteer β†’ Browser automation + +- **Advanced Features** + - UltraCompressed mode (~70% token reduction) + - Token economy & smart model selection + - Research-first methodology + - Planning mode w/ --plan flag + - Thinking modes (basicβ†’standardβ†’deepβ†’critical) + - Evidence-based decision making + +- **Installation & Setup** + - Global deployment to ~/.claude/ + - Bash installation script + - Backup & migration support + - Verification & validation + +### Technical Details +- **Languages**: Bash, YAML, Markdown +- **Target**: Claude Code enhancement +- **License**: MIT +- **Compatibility**: Cross-platform (macOS, Windows, Linux) + +## Version History Notes + +### Versioning Strategy +- **Major** (X.0.0): Breaking changes to core architecture +- **Minor** (X.Y.0): New features, personas, or commands +- **Patch** (X.Y.Z): Bug fixes, documentation, minor improvements + +### Breaking Changes Policy +- Deprecated features β†’ 1 version warning +- Migration guides provided +- Backward compatibility when possible + +### Release Process +1. Feature development +2. Testing & validation +3. Documentation updates +4. CHANGELOG.md update +5. Version tag & release +6. Community notification + +--- + +**Links:** +- [Repository](https://github.com/NomenAK/SuperClaude) +- [Issues](https://github.com/NomenAK/SuperClaude/issues) +- [Contributing](CONTRIBUTING.md) +- [License](LICENSE) + +*SuperClaude v4.0.0 | Configuration framework for Claude Code* \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..af6b775 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,45 @@ +# Code of Conduct + +## Our Pledge + +We pledge to make participation in the SuperClaude community a welcoming experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +### Positive Behavior +- Being respectful and inclusive +- Providing constructive feedback +- Focusing on what is best for the community +- Showing empathy towards other community members +- Helping newcomers learn and contribute + +### Unacceptable Behavior +- Harassment, trolling, or discriminatory language +- Personal attacks or political arguments +- Publishing private information without permission +- Spam or off-topic content +- Any conduct that could reasonably be considered inappropriate + +## Responsibilities + +Project maintainers are responsible for clarifying standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +## Scope + +This Code of Conduct applies within all project spaces, including: +- GitHub repository (issues, PRs, discussions) +- Project documentation +- Community forums and chat +- Project events and meetups + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team through GitHub issues. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0. + +--- + +*SuperClaude v4.0.0 | Building a respectful community* \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..77f975f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,210 @@ +# Contributing to SuperClaude + +## Legend +| Symbol | Meaning | | Abbrev | Meaning | +|--------|---------|---|--------|---------| +| β†’ | leads to | | PR | pull request | +| & | and/with | | cfg | configuration | + +Thanks for contributing to SuperClaude! This guide helps you get started. + +## Quick Start + +1. **Fork & Clone** + ```bash + git clone https://github.com/YOUR_USERNAME/SuperClaude.git + cd SuperClaude + ``` + +2. **Create Branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +3. **Make Changes** β†’ Test β†’ Commit β†’ Push β†’ PR + +## Types of Contributions + +### πŸ› Bug Fixes +- Use issue template +- Include steps to reproduce +- Test fix before submitting + +### ✨ New Features +- Check existing issues first +- Create feature request issue +- Discuss approach before coding + +### πŸ“š Documentation +- Fix typos, improve clarity +- Add examples & use cases +- Update README if needed + +### πŸ”§ Configuration Improvements +- New slash commands (.claude/commands/) +- YAML resources (.claude/commands/shared/) +- Core configs (CLAUDE.md, RULES.md, etc.) + +## Development Guidelines + +### File Structure +``` +SuperClaude/ +β”œβ”€β”€ CLAUDE.md, RULES.md, PERSONAS.md, MCP.md # Core configs +β”œβ”€β”€ .claude/commands/ # Slash commands +β”œβ”€β”€ .claude/commands/shared/ # YAML resources +β”œβ”€β”€ install.sh # Installation script +└── README.md # Documentation +``` + +### Code Standards +- **YAML**: 2-space indentation, descriptive keys +- **Markdown**: Clear headers, consistent formatting +- **Shell**: Bash compatibility, error handling +- **No executables**: Config framework only + +### Testing +- Test install.sh on clean system +- Verify slash commands work in Claude Code +- Check YAML syntax validity +- Test personas & MCP integration + +## Submission Process + +### 1. Before You Start +- Search existing issues & PRs +- Create issue for discussion (features) +- Fork repository + +### 2. Development +- Create feature branch +- Make focused commits +- Follow naming conventions +- Test thoroughly + +### 3. Pull Request +- Use PR template +- Clear title & description +- Link related issues +- Request review + +### 4. Review Process +- Maintainer review required +- Address feedback promptly +- Keep PR up to date +- Squash commits if requested + +## Issue Guidelines + +### Bug Reports +Include: +- SuperClaude version +- Claude Code version +- Operating system +- Steps to reproduce +- Expected vs actual behavior +- Error messages + +### Feature Requests +Include: +- Use case description +- Proposed solution +- Alternative solutions considered +- Additional context + +## Slash Command Development + +### Creating New Commands +1. **File**: `.claude/commands/your-command.md` +2. **Format**: Follow existing command structure +3. **Flags**: Use consistent flag patterns +4. **Documentation**: Include examples +5. **Integration**: Update index.md + +### Command Structure +```markdown +# Command Name +Description & purpose + +## Flags +- --flag1: Description +- --flag2: Description + +## Examples +/user:command --flag1 +``` + +### YAML Resources +1. **Location**: `.claude/commands/shared/` +2. **Purpose**: Reusable configurations +3. **Naming**: descriptive-name.yml +4. **Structure**: Clear, documented sections + +## Persona Development + +### Guidelines +- **Core Belief**: What drives this persona +- **Primary Question**: Key question they ask +- **Decision Pattern**: How they prioritize +- **MCP Tools**: Which tools they prefer + +### Testing Personas +- Test with various scenarios +- Verify MCP integration +- Check decision consistency +- Document use cases + +## Documentation Standards + +### Writing Style +- Concise & clear +- Use symbols from legend +- Bullet points > prose +- Include examples + +### UltraCompressed Mode +- Use abbreviations +- Remove articles (the, a, that) +- Symbol shortcuts (β†’, &, w/) +- Auto-generate legends + +## Community Guidelines + +### Be Respectful +- Professional communication +- Constructive feedback only +- Help newcomers +- Credit contributions + +### Quality First +- Test before submitting +- Document changes +- Follow established patterns +- Consider maintenance impact + +## Getting Help + +### Resources +- README.md β†’ Overview & installation +- Issues β†’ Bug reports & discussions +- Wiki β†’ Extended documentation +- Discussions β†’ Community Q&A + +### Contact +- Create issue for bugs/features +- Use discussions for questions +- Tag maintainers for urgent issues + +## Recognition + +Contributors are recognized through: +- GitHub contributor graph +- CHANGELOG.md mentions +- Issue/PR acknowledgments +- Community discussions + +--- + +**Ready to contribute?** Create an issue or submit a PR! + +*SuperClaude v4.0.0 | Community-driven configuration framework* \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a4e5bc7 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,91 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| 4.0.x | βœ… Yes | +| < 4.0 | ❌ No | + +## Reporting Security Vulnerabilities + +We take security seriously. If you discover a security vulnerability, please follow these steps: + +### πŸ”’ Private Reporting (Preferred) + +1. **Do NOT** create a public issue +2. Email security details to: anton.knoery@gmail.com +3. Include "SuperClaude Security" in subject line +4. Provide detailed description of the vulnerability + +### πŸ“ Required Information + +Please include: +- Description of the vulnerability +- Steps to reproduce the issue +- Potential impact assessment +- Any suggested fixes or mitigations +- Your contact information for follow-up + +### ⏱️ Response Timeline + +- **24 hours**: Initial acknowledgment +- **72 hours**: Preliminary assessment +- **7 days**: Detailed response with next steps +- **30 days**: Resolution target (depending on complexity) + +## Security Considerations + +### Configuration Framework Security +- SuperClaude is a configuration framework, not executable software +- No network connections or data transmission +- Files are stored locally in ~/.claude/ +- Shell scripts have limited system access + +### Installation Security +- install.sh performs file operations only +- No sudo/admin privileges required +- Backup existing configurations before installation +- All operations within user home directory + +### Usage Security +- Configuration files are read-only for Claude Code +- No sensitive data stored in configurations +- Slash commands execute through Claude Code's security model +- MCP integrations follow Claude Code's sandbox restrictions + +## Best Practices + +### For Users +- Review install.sh before execution +- Keep SuperClaude updated +- Report suspicious behavior +- Use official installation methods only + +### For Contributors +- Follow secure coding practices +- No hardcoded secrets or credentials +- Validate all user inputs +- Test security implications of changes + +## Scope + +This security policy covers: +- SuperClaude configuration files +- Installation scripts +- GitHub repository security +- Community interaction security + +## Disclaimer + +SuperClaude is provided "as is" without warranty. While we strive for security, users are responsible for: +- Reviewing code before installation +- Using in appropriate environments +- Following Claude Code security guidelines +- Backing up existing configurations + +--- + +**Questions?** Contact anton.knoery@gmail.com + +*SuperClaude v4.0.0 | Security-conscious configuration framework* \ No newline at end of file