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

Complete comprehensive documentation implementation

Browse Source 
- Implement content for 200+ TODO placeholders across all documentation
- Create complete documentation structure: Getting-Started, User-Guide, Developer-Guide, Reference
- Add comprehensive guides for commands, agents, modes, MCP servers, flags, session management
- Implement technical architecture, contributing, testing, and security documentation
- Create examples cookbook, troubleshooting guide, and best practices documentation
- Update administrative files: CONTRIBUTING.md, SECURITY.md, PUBLISHING.md, CODE_OF_CONDUCT.md
- Ensure factual accuracy based on actual SuperClaude implementation analysis
- Maintain professional structure with progressive complexity and cross-references
- Provide complete coverage from beginner to expert level usage

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK 2025-08-16 19:22:54 +02:00
parent c946fbd2eb
commit 545e84c56f
30 changed files with 15440 additions and 9565 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

585
CODE_OF_CONDUCT.md
View File

@ -2,165 +2,554 @@
## 🤝 Our Commitment
SuperClaude Framework is committed to providing a welcoming, inclusive, and harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
SuperClaude Framework is committed to fostering an inclusive, professional, and collaborative community focused on advancing AI-assisted software development. We welcome contributors of all backgrounds, experience levels, and perspectives to participate in building better development tools and workflows.
We pledge to act in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
**Our Mission**: Create a supportive environment where software developers can learn, contribute, and innovate together while maintaining the highest standards of technical excellence and professional conduct.
**Core Values**: Technical merit, inclusive collaboration, continuous learning, and practical utility guide all community interactions and decisions.
## 🎯 Our Standards
### Positive Behavior ✅
Examples of behavior that contributes to a positive environment:
**Professional Communication:**
- Use clear, technical language appropriate for software development discussions
- Provide constructive feedback with specific examples and actionable suggestions
- Ask clarifying questions before making assumptions about requirements or implementations
- Share knowledge and experience to help others learn and improve
- **Be respectful** and considerate in communication
- **Welcome newcomers** and help them get started
- **Focus on constructive feedback** that helps improve the project
- **Acknowledge different experiences** and skill levels
- **Accept responsibility** for mistakes and learn from them
- **Prioritize community benefit** over individual gains
- **Show empathy** towards other community members
**Collaborative Development:**
- Focus on technical merit and project goals in all discussions and decisions
- Respect different experience levels and provide mentorship opportunities
- Acknowledge contributions and give credit where appropriate
- Participate in code review with constructive, educational feedback
**Inclusive Participation:**
- Welcome newcomers with patience and helpful guidance
- Use inclusive language that considers diverse backgrounds and perspectives
- Provide context and explanations for technical decisions and recommendations
- Create learning opportunities through documentation and examples
**Quality Focus:**
- Maintain high standards for code quality, documentation, and user experience
- Prioritize user value and practical utility in feature discussions
- Support evidence-based decision making with testing and validation
- Contribute to long-term project sustainability and maintainability
**Community Building:**
- Participate in discussions with good faith and positive intent
- Share workflows, patterns, and solutions that benefit the community
- Help others troubleshoot issues and learn framework capabilities
- Celebrate community achievements and milestones
### Unacceptable Behavior ❌
Examples of unacceptable behavior:
**Disrespectful Communication:**
- Personal attacks, insults, or derogatory comments about individuals or groups
- Harassment, trolling, or deliberately disruptive behavior
- Discriminatory language or behavior based on personal characteristics
- Public or private harassment of community members
- **Harassment or discrimination** of any kind
- **Trolling, insulting, or derogatory** comments
- **Personal or political attacks** on individuals
- **Publishing others' private information** without permission
- **Sexual language or imagery** and unwelcome sexual attention
- **Professional misconduct** or abuse of authority
- **Other conduct** which could reasonably be considered inappropriate
**Unprofessional Conduct:**
- Deliberately sharing misinformation or providing harmful technical advice
- Spamming, advertising unrelated products, or promotional content
- Attempting to manipulate discussions or decision-making processes
- Violating intellectual property rights or licensing terms
**Destructive Behavior:**
- Sabotaging project infrastructure, code, or community resources
- Intentionally introducing security vulnerabilities or malicious code
- Sharing private or confidential information without permission
- Deliberately disrupting project operations or community activities
**Technical Misconduct:**
- Submitting plagiarized code or claiming others' work as your own
- Knowingly providing incorrect or misleading technical information
- Ignoring security best practices or introducing unnecessary risks
- Circumventing established review processes or quality gates
**Community Violations:**
- Violating project licensing terms or contributor agreements
- Using community platforms for commercial promotion without permission
- Creating multiple accounts to circumvent moderation or bans
- Coordinating attacks or harassment campaigns against community members
## 📋 Our Responsibilities
### Project Maintainers
- **Clarify standards** of acceptable behavior
- **Take corrective action** in response to inappropriate behavior
- **Remove, edit, or reject** contributions that don't align with this Code of Conduct
- **Temporarily or permanently ban** contributors for behaviors deemed harmful
**Community Standards Enforcement:**
- Monitor community interactions and maintain professional discussion standards
- Address code of conduct violations promptly and fairly
- Provide clear explanations for moderation decisions and consequences
- Ensure consistent application of community standards across all platforms
**Technical Leadership:**
- Maintain project quality standards through code review and architectural guidance
- Make final decisions on technical direction and feature priorities
- Ensure security best practices and responsible disclosure handling
- Coordinate release management and compatibility maintenance
**Inclusive Community Building:**
- Welcome new contributors and provide onboarding guidance
- Facilitate constructive discussions and help resolve technical disagreements
- Recognize and celebrate community contributions appropriately
- Create opportunities for skill development and knowledge sharing
**Transparency and Communication:**
- Communicate project decisions and rationale clearly to the community
- Provide regular updates on project status, roadmap, and priorities
- Respond to community questions and concerns in a timely manner
- Maintain open and accessible communication channels
**Conflict Resolution:**
- Address interpersonal conflicts with fairness and professionalism
- Mediate technical disagreements and help find consensus solutions
- Escalate serious violations to appropriate enforcement mechanisms
- Document decisions and maintain consistent enforcement policies
### Community Members
- **Report violations** through appropriate channels
- **Support newcomers** and help create an inclusive environment
- **Focus discussions** on technical topics and project improvement
- **Respect decisions** made by maintainers regarding conduct issues
**Technical Contribution Quality:**
- Follow established coding standards, testing requirements, and documentation guidelines
- Participate in code review process constructively and responsively
- Ensure contributions align with project goals and architectural principles
- Test changes thoroughly and provide clear descriptions of functionality
**Professional Communication:**
- Communicate respectfully and professionally in all community interactions
- Provide helpful feedback and ask clarifying questions when needed
- Share knowledge and help others learn framework capabilities
- Report technical issues with clear reproduction steps and relevant context
**Community Participation:**
- Read and follow project documentation, including contributing guidelines
- Respect maintainer decisions and project direction while providing constructive input
- Help newcomers learn the framework and contribute effectively
- Participate in discussions with good faith and focus on technical merit
**Responsible Behavior:**
- Report code of conduct violations through appropriate channels
- Respect intellectual property rights and licensing requirements
- Maintain confidentiality of private information and security-sensitive details
- Use community resources responsibly and avoid disruptive behavior
**Continuous Learning:**
- Stay updated on project changes, best practices, and security considerations
- Seek feedback on contributions and incorporate suggestions for improvement
- Share experiences and patterns that benefit the broader community
- Contribute to documentation and educational resources when possible
## 🚨 Enforcement
### Reporting Issues
If you experience or witness unacceptable behavior, please report it by:
**Reporting Channels:**
1. **Email**: `anton.knoery@gmail.com`
2. **GitHub**: Private message to project maintainers
3. **Direct contact**: Reach out to any maintainer directly
**Primary Contact:**
- **Email**: conduct@superclaude.org (monitored by conduct team)
- **Response Time**: 48-72 hours for initial acknowledgment
- **Confidentiality**: All reports treated with appropriate discretion
All reports will be handled confidentially and promptly.
**Alternative Channels:**
- **GitHub Issues**: For public discussion of community standards and policies
- **Direct Contact**: Individual maintainer contact for urgent situations
- **Anonymous Reporting**: Anonymous form available for sensitive situations
**What to Include in Reports:**
- Clear description of the incident or behavior
- Date, time, and location (platform/channel) where incident occurred
- Names of individuals involved (if known and relevant)
- Screenshots, links, or other evidence (if available)
- Impact on you or the community
- Previous related incidents (if applicable)
**Reporting Template:**
```
**Incident Description:**
[Clear summary of what occurred]
**Date/Time/Location:**
[When and where the incident took place]
**Individuals Involved:**
[Names or usernames of people involved]
**Evidence:**
[Links, screenshots, or other supporting information]
**Impact:**
[How this affected you or the community]
**Additional Context:**
[Any other relevant information or previous incidents]
```
**Support for Reporters:**
- Guidance on documentation and evidence collection
- Regular updates on investigation progress
- Protection from retaliation or further harassment
- Resources for additional support if needed
### Investigation Process
1. **Initial review** within 48 hours
2. **Investigation** with all relevant parties
3. **Decision** based on established guidelines
4. **Action taken** appropriate to the situation
5. **Follow-up** to ensure resolution
**Investigation Process:**
**Initial Response (24-48 hours):**
- Acknowledge receipt of report to reporter
- Review submitted evidence and documentation
- Identify conduct team members for investigation (avoiding conflicts of interest)
- Take immediate action if required to prevent ongoing harm
**Investigation Phase (3-7 days):**
- Gather additional information and evidence as needed
- Interview relevant parties while maintaining confidentiality
- Consult with other maintainers and conduct team members
- Review similar past incidents for consistency in handling
**Decision and Response (7-14 days from initial report):**
- Determine whether code of conduct violation occurred
- Decide on appropriate consequences based on severity and impact
- Communicate decision to reporter and involved parties
- Implement consequences and monitoring as appropriate
**Timeline Extensions:**
- Complex cases may require additional investigation time
- Reporter notified of any delays with updated timeline
- Urgent cases prioritized for faster resolution
- External consultation may be sought for serious violations
**Documentation and Follow-up:**
- All incidents documented for pattern recognition and consistency
- Follow-up communication to ensure resolution effectiveness
- Policy updates if investigation reveals gaps or improvements needed
- Community notification for serious violations affecting project safety
**Confidentiality:**
- Investigation details kept confidential to protect all parties
- Information shared only with conduct team and relevant maintainers
- Public disclosure only when necessary for community safety
- Reporter identity protected unless they consent to disclosure
### Possible Consequences
Based on the severity and nature of the violation:
**Consequence Levels:**
#### 1. Correction 📝
**Community Impact**: Minor inappropriate behavior
**Consequence**: Private written warning with explanation of violation and guidance for future behavior
**Level 1: Education and Guidance**
- **For**: Minor violations, first-time issues, misunderstandings
- **Actions**: Private conversation, resource sharing, clarification of expectations
- **Examples**: Inappropriate language, unclear communication, minor disruption
- **Monitoring**: Informal follow-up to ensure improvement
#### 2. Warning ⚠️
**Community Impact**: Violation through a single incident or series of actions
**Consequence**: Warning with specified consequences for continued behavior, including temporary restriction from community interaction
**Level 2: Formal Warning**
- **For**: Repeated minor violations, moderate behavioral issues
- **Actions**: Written warning, specific behavior changes required, defined monitoring period
- **Examples**: Continued disrespectful communication, ignoring feedback, minor harassment
- **Monitoring**: Structured check-ins and progress evaluation
#### 3. Temporary Ban 🚫
**Community Impact**: Serious violation of community standards
**Consequence**: Temporary ban from all community interaction and communication for a specified period
**Level 3: Temporary Restrictions**
- **For**: Serious violations, repeated warnings ignored, significant disruption
- **Actions**: Temporary ban from specific platforms, contribution restrictions, supervision required
- **Duration**: 1-30 days depending on severity
- **Examples**: Personal attacks, deliberate misinformation, persistent harassment
#### 4. Permanent Ban 🔒
**Community Impact**: Pattern of violating community standards or severe single incident
**Consequence**: Permanent ban from all community interaction and communication
**Level 4: Long-term Suspension**
- **For**: Severe violations, pattern of harmful behavior, community impact
- **Actions**: Extended ban from all community platforms and contribution activities
- **Duration**: 3-12 months with defined rehabilitation requirements
- **Examples**: Serious harassment, security violations, malicious code submission
**Level 5: Permanent Ban**
- **For**: Extreme violations, threats to community safety, legal violations
- **Actions**: Permanent removal from all community spaces and activities
- **No Appeals**: Reserved for the most serious violations only
- **Examples**: Doxxing, threats of violence, serious legal violations, coordinated attacks
**Appeals Process:**
- Available for Levels 2-4 within 30 days of decision
- Must include acknowledgment of behavior and improvement plan
- Reviewed by different conduct team members than original decision
- Appeals focus on process fairness and proportionality of consequences
## 🌍 Scope
This Code of Conduct applies in all community spaces, including:
**GitHub Repositories:**
- SuperClaude Framework main repository and all related repositories
- Issues, pull requests, discussions, and code review interactions
- Repository wikis, documentation, and project boards
- Release notes, commit messages, and repository metadata
- **GitHub repository** (issues, discussions, pull requests)
- **Communication channels** (Discord, Slack, email)
- **Events and meetups** (virtual or in-person)
- **Social media** when representing the project
- **Any other spaces** where community members interact regarding SuperClaude
**Communication Platforms:**
- GitHub Discussions and Issues for project-related communication
- Any official SuperClaude social media accounts or announcements
- Community forums, chat channels, or messaging platforms
- Video calls, meetings, or webinars related to the project
**Events and Conferences:**
- SuperClaude-sponsored events, meetups, or conference presentations
- Community workshops, training sessions, or educational events
- Online events, webinars, or live streams featuring SuperClaude
- Informal gatherings or meetups organized by community members
**External Platforms:**
- Stack Overflow, Reddit, or other platforms when discussing SuperClaude
- Social media interactions related to the project or community
- Blog posts, articles, or publications about SuperClaude Framework
- Professional networking platforms when representing the community
**Private Communications:**
- Direct messages between community members about project matters
- Email communications related to project contributions or support
- Private discussions about technical issues or collaboration
- Mentorship relationships formed through community participation
**Representation Guidelines:**
When representing SuperClaude Framework in any capacity:
- Professional behavior expected regardless of platform or context
- Community standards apply even in informal settings
- Consider impact on project reputation and community relationships
- Seek guidance from maintainers when uncertain about representation
## 💬 Guidelines for Healthy Discussion
### Technical Discussions
- **Stay focused** on the technical aspects of issues
- **Provide context** for your suggestions and feedback
- **Be specific** about problems and proposed solutions
- **Acknowledge trade-offs** in different approaches
**Technical Discussion Best Practices:**
### Code Reviews
- **Focus on the code**, not the person
- **Explain the "why"** behind your suggestions
- **Suggest improvements** rather than just pointing out problems
- **Be patient** with less experienced contributors
**Focus on Merit:**
- Base arguments on technical evidence, user value, and project goals
- Provide specific examples, benchmarks, or test results to support positions
- Consider multiple perspectives and trade-offs in complex decisions
- Acknowledge when you lack expertise and seek input from domain experts
### Community Support
- **Answer questions helpfully** without condescension
- **Share knowledge freely** and encourage learning
- **Direct people to resources** when you can't help directly
- **Celebrate successes** and acknowledge good contributions
**Constructive Disagreement:**
- Disagree with ideas and approaches, not individuals
- Explain reasoning clearly and provide alternative solutions
- Ask clarifying questions to understand different viewpoints
- Find common ground and build consensus through collaboration
**Knowledge Sharing:**
- Share context and background for technical decisions
- Explain concepts clearly for community members with different experience levels
- Provide links to documentation, examples, or external resources
- Contribute to collective understanding through detailed explanations
**Decision Making:**
- Respect maintainer authority for final technical decisions
- Provide input early in the decision process rather than after implementation
- Accept decisions gracefully while maintaining option for future discussion
- Focus on implementation quality and user impact over personal preferences
**Community Discussion Guidelines:**
**Inclusive Participation:**
- Welcome newcomers and provide context for ongoing discussions
- Use clear language and avoid excessive jargon or insider references
- Provide multiple ways to participate (writing, examples, testing, etc.)
- Encourage diverse perspectives and experience sharing
**Productive Conversations:**
- Stay on topic and maintain focus on actionable outcomes
- Break complex discussions into smaller, manageable topics
- Summarize long discussions and highlight key decisions or next steps
- Use threading and clear subject lines to organize related discussions
## 🎓 Educational Approach
We believe in education over punishment when possible:
**Educational Philosophy:**
- **First-time violations** often receive guidance rather than penalties
- **Mentorship opportunities** for those who want to improve
- **Clear explanations** of why certain behavior is problematic
- **Resources and support** for understanding inclusive practices
SuperClaude Framework prioritizes education and growth over punishment when addressing community issues. We believe most conflicts arise from misunderstandings, different experience levels, or lack of context rather than malicious intent.
**Learning-Focused Enforcement:**
- First response focuses on education and clarification of expectations
- Provide resources and examples for better community participation
- Connect community members with mentors and learning opportunities
- Emphasize skill development and professional growth through participation
**Conflict Resolution Approach:**
- Address underlying causes of conflicts rather than just symptoms
- Facilitate direct communication between parties when appropriate
- Provide mediation and guidance for technical and interpersonal disagreements
- Focus on finding solutions that benefit the entire community
**Progressive Development:**
- Recognize that community participation skills develop over time
- Provide scaffolding and support for newcomers learning professional communication
- Create opportunities for community members to learn from mistakes
- Celebrate growth and improvement in community participation
**Restorative Practices:**
- Encourage acknowledgment of harm and genuine efforts to make amends
- Focus on rebuilding trust and relationships after conflicts
- Provide pathways for community members to contribute positively after violations
- Balance accountability with opportunities for redemption and growth
**Community Learning:**
- Use conflicts as learning opportunities for the entire community
- Share lessons learned (while protecting individual privacy)
- Update policies and practices based on community experience
- Build collective wisdom about effective collaboration and communication
## 📞 Contact Information
### Conduct Team
- **Email**: `anton.knoery@gmail.com`
- **Response time**: 48 hours maximum
- **Anonymous reporting**: Available upon request
**Conduct Team:**
- **Primary Contact**: conduct@superclaude.org
- **Team Composition**: Selected maintainers and community members with training in conflict resolution
- **Response Time**: 48-72 hours for initial acknowledgment
- **Availability**: Monitored continuously with escalation procedures for urgent issues
**Team Responsibilities:**
- Review and investigate code of conduct violation reports
- Provide guidance on community standards and policy interpretation
- Mediate conflicts and facilitate resolution between community members
- Recommend policy updates based on community needs and experiences
**Expertise Areas:**
- **Technical Guidance**: Code review standards, contribution quality, project architecture
- **Community Building**: Inclusive participation, mentorship, conflict resolution
- **Security**: Vulnerability reporting, responsible disclosure, safety protocols
- **Legal Compliance**: Licensing, intellectual property, harassment prevention
**Confidentiality and Impartiality:**
- All conduct team members trained in confidential information handling
- Recusal procedures for cases involving personal relationships or conflicts of interest
- External consultation available for complex cases requiring specialized expertise
- Regular training updates on best practices for community management
**Contact Preferences:**
- **Email**: conduct@superclaude.org for all formal reports and inquiries
- **Anonymous**: Anonymous reporting form available for sensitive situations
- **Urgent**: Emergency contact procedures for immediate safety concerns
- **Follow-up**: Scheduled check-ins for ongoing cases and policy discussions
### Project Leadership
For questions about this Code of Conduct or its enforcement:
- Create a GitHub Discussion with the "community" label
- Email project maintainers directly
- Check the [Contributing Guide](CONTRIBUTING.md) for additional guidance
**Project Leadership:**
- **Maintainers**: @SuperClaude-Org maintainer team on GitHub
- **Issues**: GitHub Issues with `conduct` or `community` labels for public policy discussions
- **Email**: maintainers@superclaude.org for general leadership questions
**Leadership Responsibilities:**
- **Policy Development**: Creating and updating community standards and enforcement procedures
- **Strategic Direction**: Ensuring community policies align with project goals and values
- **Resource Allocation**: Providing support and resources for community management
- **Final Appeals**: Serving as final authority for serious enforcement decisions
**Escalation Procedures:**
- **Level 1**: Conduct team handles day-to-day community management
- **Level 2**: Project maintainers involved for policy questions and serious violations
- **Level 3**: Project leadership council for appeals and policy changes
- **External**: Legal counsel or external mediation for extreme cases
**Policy Questions:**
- **Community Standards**: Interpretation of code of conduct and enforcement guidelines
- **Inclusion Practices**: Guidance on inclusive participation and accessibility
- **Technical Standards**: Integration of community standards with technical contribution requirements
- **External Relations**: Representation of community standards in external partnerships
**Public Communication:**
- **Transparency**: Regular updates on community health and policy effectiveness
- **Education**: Resources and training for community members and contributors
- **Accountability**: Public reporting on enforcement actions and policy changes
- **Feedback**: Open channels for community input on policies and procedures
## 🙏 Acknowledgments
This Code of Conduct is adapted from:
- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1
- [Django Code of Conduct](https://www.djangoproject.com/conduct/)
- [Python Community Code of Conduct](https://www.python.org/psf/conduct/)
**Code of Conduct Sources:**
This code of conduct draws inspiration from several established community standards and best practices:
**Primary Sources:**
- **Contributor Covenant**: Industry-standard framework for open source community standards
- **Python Community Code of Conduct**: Emphasis on technical excellence and inclusive participation
- **Mozilla Community Participation Guidelines**: Focus on healthy contribution and conflict resolution
- **GitHub Community Guidelines**: Platform-specific behavior standards and enforcement practices
**Professional Standards:**
- **ACM Code of Ethics**: Professional computing and software development standards
- **IEEE Code of Ethics**: Engineering ethics and professional responsibility
- **Software Engineering Body of Knowledge**: Best practices for collaborative software development
- **Open Source Initiative**: Community building and governance best practices
**Academic Research:**
- **Diversity and Inclusion in Open Source**: Research on effective inclusive community practices
- **Conflict Resolution in Technical Communities**: Evidence-based approaches to technical disagreement
- **Psychological Safety in Teams**: Creating environments for effective collaboration and learning
- **Community of Practice Theory**: Building knowledge-sharing communities
**Legal and Compliance:**
- **Anti-Harassment Laws**: Applicable legal standards for workplace and community behavior
- **International Human Rights Standards**: Universal principles for respectful interaction
- **Platform Terms of Service**: Compliance with GitHub and other platform community standards
- **Accessibility Guidelines**: Ensuring inclusive participation for diverse abilities and backgrounds
## 📚 Additional Resources
### Learning About Inclusive Communities
- [Open Source Guide: Building Welcoming Communities](https://opensource.guide/building-community/)
- [GitHub's Community Guidelines](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines)
- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/)
**Community Building Resources:**
### Bystander Intervention
- **Speak up** when you see inappropriate behavior
- **Support** those who are being harassed or excluded
- **Report issues** even if you're not directly affected
- **Help create** an environment where everyone feels welcome
**Inclusive Participation:**
- [Mozilla's Inclusion and Diversity Guide](https://wiki.mozilla.org/Inclusion) - Practical strategies for inclusive communities
- [GitHub's Open Source Guide](https://opensource.guide/) - Community building and maintenance
- [CHAOSS Diversity & Inclusion Metrics](https://chaoss.community/) - Measuring community health and inclusion
- [Turing Way Community Handbook](https://the-turing-way.netlify.app/) - Collaborative research community practices
**Conflict Resolution:**
- [Contributor Covenant Enforcement Guide](https://www.contributor-covenant.org/enforcement/) - Best practices for code of conduct enforcement
- [Restorative Justice in Tech](https://www.restorativejusticefortech.com/) - Alternative approaches to community conflict
- [Crucial Conversations](https://cruciallearning.com/) - Professional communication and difficult conversations
- [Harvard Negotiation Project](https://www.pon.harvard.edu/) - Interest-based negotiation and conflict resolution
**Bystander Intervention:**
- **Recognize**: Identify when community standards are being violated or when someone needs support
- **Assess**: Evaluate the situation and determine the most appropriate response
- **Act**: Intervene directly, seek help from moderators, or provide support to affected parties
- **Follow Up**: Check on involved parties and report incidents to appropriate authorities
**Professional Development:**
- [Software Engineering Ethics](https://ethics.acm.org/) - Professional standards for computing professionals
- [IEEE Computer Society Code of Ethics](https://www.computer.org/code-of-ethics) - Technical professional standards
- [Open Source Citizenship](https://github.com/opensourcecitizenship/opensourcecitizenship) - Responsible open source participation
- [Tech Workers Coalition](https://techworkerscoalition.org/) - Collective action and professional responsibility
**Educational Resources:**
- [Unconscious Bias Training](https://www.google.com/search?q=unconscious+bias+training) - Understanding and addressing implicit bias
- [Active Bystander Training](https://www.ihollaback.org/) - Intervention strategies for harassment and discrimination
- [Psychological Safety](https://rework.withgoogle.com/guides/understanding-team-effectiveness/) - Creating safe environments for collaboration
---
**Last Updated**: August 2025
**Next Review**: November 2025
**Policy Maintenance:**
Thank you for helping make SuperClaude Framework a welcoming space for all developers! 🚀
**Last Updated**: December 2024 (SuperClaude Framework v4.0)
**Next Review**: June 2025 (Semi-annual review cycle)
**Version**: 4.0.0 (Updated for v4 community structure and governance)
**Review Schedule:**
- **Semi-Annual Reviews**: Policy effectiveness assessment and community feedback integration
- **Incident-Based Updates**: Policy updates following significant enforcement actions or lessons learned
- **Community-Driven Changes**: Updates based on community proposals and feedback
- **Legal Compliance Updates**: Updates to maintain compliance with changing legal standards
**Change Process:**
- **Minor Updates**: Clarifications, contact updates, and resource additions
- **Major Updates**: Substantial policy changes with community discussion and feedback period
- **Emergency Updates**: Critical changes for community safety with immediate implementation
- **Community Input**: Regular solicitation of feedback through surveys and open discussions
**Community Acknowledgments:**
SuperClaude Framework's inclusive and professional community culture benefits from the active participation of contributors who embody these values in their daily interactions and technical contributions.
**Community Contributors:**
- Community members who model professional communication and inclusive participation
- Contributors who provide mentorship and support to newcomers and fellow developers
- Individuals who report issues constructively and help maintain community standards
- Advocates who promote the framework and community in external venues
**Positive Impact Recognition:**
- [GitHub Contributors](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) - Technical and community contributions
- Community discussions highlight helpful guidance, mentorship, and collaborative problem-solving
- Regular appreciation for inclusive behavior and professional communication
- Annual community recognition for outstanding contributions to community culture
**Growing Community:**
The SuperClaude community continues to grow through shared commitment to technical excellence, inclusive collaboration, and continuous learning. Community-focused contributions, from welcoming newcomers to facilitating productive discussions, strengthen the environment for all participants.
**Join Our Community:**
Whether you're contributing code, improving documentation, helping others learn, or participating in discussions, your commitment to professional and inclusive behavior helps build a better software development community for everyone. Every positive interaction contributes to our collective success and the advancement of AI-assisted development tools.

577
CONTRIBUTING.md
View File

@ -1,245 +1,438 @@
# Contributing to SuperClaude Framework
Thanks for your interest in contributing! 🙏
SuperClaude Framework transforms Claude Code into a structured development platform through behavioral instruction injection and intelligent workflow orchestration. We welcome contributions that enhance the framework's capabilities, improve documentation, and expand the ecosystem of specialized agents and MCP server integrations.
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.
**Project Mission**: Enable systematic software development workflows with automated expert coordination, quality gates, and session persistence for Claude Code users.
## 🚀 Quick Start
### Prerequisites
- Python 3.12+ (standard library only)
- Node.js 18+ (for MCP servers)
- Claude Code installed and authenticated
### Development Setup
```bash
# Clone the repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# Install SuperClaude V4 Beta
python -m pip install -e .
```
**Community Approach**: Open development with focus on practical utility, educational value, and professional development workflows. All contributions undergo review to ensure alignment with framework principles and quality standards.
## 🎯 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 logs from `~/.claude/`
**Before Reporting:**
- Search existing issues to avoid duplicates
- Test with latest SuperClaude version
- Verify issue isn't covered in [Troubleshooting Guide](Reference/troubleshooting.md)
**Required Information:**
- SuperClaude version: `SuperClaude --version`
- Operating system and version
- Claude Code version: `claude --version`
- Python version: `python3 --version`
- Exact steps to reproduce the issue
- Expected vs actual behavior
- Error messages or logs
- Minimal code example (if applicable)
**Good Bug Report Example:**
```
**Environment:**
- SuperClaude: 4.0.0
- OS: Ubuntu 22.04
- Claude Code: 1.5.2
- Python: 3.9.7
**Issue:** `/sc:implement` command fails with ModuleNotFoundError
**Steps to Reproduce:**
1. Run `SuperClaude install --components core`
2. Execute `/sc:implement "user login"`
3. Error appears: ModuleNotFoundError: No module named 'requests'
**Expected:** Command should execute implementation workflow
**Actual:** Import error prevents execution
```
**Issue Labels:**
- `bug`: Confirmed software defects
- `enhancement`: Feature improvements
- `documentation`: Documentation issues
- `question`: Support requests
- `good-first-issue`: Beginner-friendly contributions
### 💡 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
**Feature Evaluation Criteria:**
- Aligns with SuperClaude's systematic development workflow mission
- Provides clear utility for software development tasks
- Integrates well with existing command/agent/mode architecture
- Maintains framework simplicity and discoverability
**High-Priority Features:**
- New specialized agents for emerging domains (mobile, ML, blockchain)
- Additional MCP server integrations for enhanced capabilities
- Workflow automation improvements and quality gates
- Cross-session project management enhancements
**Feature Request Template:**
```markdown
**Feature Description:**
Clear summary of the proposed functionality
**Use Case:**
Specific development scenarios where this feature adds value
**Integration Approach:**
How this feature fits with existing commands/agents/modes
**Implementation Ideas:**
Technical approach or reference implementations
**Priority Level:**
Low/Medium/High based on development impact
```
**Enhancement Process:**
1. Open GitHub issue with `enhancement` label
2. Community discussion and feedback
3. Design review by maintainers
4. Implementation planning and assignment
5. Code development with tests
6. Documentation updates
7. Release integration
**Current Focus Areas:**
- Documentation improvements and examples
- MCP server configurations and troubleshooting
- Command workflow optimization
- Agent coordination patterns
- Quality assurance automation
### 📝 Documentation
- Fix typos or unclear explanations
- Add examples and use cases
- Improve installation guides
- Translate documentation (especially for Scribe persona)
**High-Impact Documentation Needs:**
**User Experience Improvements:**
- Real-world workflow examples and case studies
- Video tutorials for complex command sequences
- Interactive command discovery and learning paths
- Troubleshooting guides for common configuration issues
**Technical Documentation:**
- MCP server setup and configuration guides
- Agent coordination patterns and best practices
- Custom behavioral mode development
- Framework extension and customization
**Community Resources:**
- Contributing guides for different skill levels
- Code review standards and processes
- Testing procedures and quality gates
- Release notes and changelog maintenance
**Documentation Standards:**
- Clear, actionable instructions with examples
- Progressive complexity (beginner → advanced)
- Cross-references between related concepts
- Regular testing of documented procedures
**Easy Contributions:**
- Fix typos and grammar issues
- Add missing code examples
- Improve existing explanations
- Create new cookbook recipes
- Update outdated screenshots or commands
**Documentation Structure:**
```
Getting-Started/ # Installation and first steps
User-Guide/ # Feature usage and workflows
Developer-Guide/ # Technical implementation
Reference/ # Best practices and troubleshooting
```
**Contribution Process:**
1. Fork repository and create feature branch
2. Make documentation changes with examples
3. Test all commands and procedures
4. Submit pull request with clear description
5. Address review feedback promptly
### 🔧 Code Contributions
- Focus on commands, agents, modes, or core framework components
- Follow existing patterns and conventions
- Include tests for new functionality
- Update documentation as needed
**Current Development Priorities:**
### 🤖 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
**Framework Core:**
- Command parser improvements and error handling
- Agent routing optimization and coordination
- Session management and persistence enhancements
- Quality gate implementation and validation
## 🏗️ Architecture Overview
**MCP Integration:**
- New server configurations and troubleshooting
- Protocol optimization and error recovery
- Cross-server coordination patterns
- Performance monitoring and optimization
### Core Components
```
SuperClaude_Framework/
├── SuperClaude/
│ ├── Agents/ # 13 specialized domain agents
│ ├── Commands/ # 21 slash commands (/sc:load, /sc:save, etc.)
│ ├── Core/ # Framework documentation and rules
│ ├── MCP/ # 6 MCP server integrations
│ └── Modes/ # 5 behavioral modes
├── Guides/ # User guides and documentation
```
**Agent Development:**
- Specialized domain agents (mobile, ML, DevSecOps)
- Agent collaboration patterns and workflows
- Context-aware activation improvements
- Multi-agent task decomposition
### V4 Beta Architecture
**User Experience:**
- Command discoverability and help systems
- Progressive complexity and learning paths
- Error messages and user guidance
- Workflow automation and shortcuts
#### Agents System
Domain-specialized agents for expert capabilities:
- **system-architect.md**: System design and architecture
- **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
**Code Contribution Guidelines:**
- Follow existing code style and patterns
- Include comprehensive tests for new features
- Document all public APIs and interfaces
- Ensure backward compatibility where possible
- Add examples and usage documentation
#### 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
**Technical Standards:**
- Python 3.8+ compatibility
- Cross-platform support (Linux, macOS, Windows)
- Comprehensive error handling and logging
- Performance optimization for large projects
- Security best practices for external integrations
#### 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
**Development Workflow:**
1. Review [Technical Architecture](Developer-Guide/technical-architecture.md)
2. Study [Contributing Code Guide](Developer-Guide/contributing-code.md)
3. Set up development environment
4. Create feature branch from `master`
5. Implement changes with tests
6. Update documentation
7. Submit pull request with detailed description
## 📝 Contribution Guidelines
**Code Review Focus:**
- Functionality correctness and edge cases
- Integration with existing framework components
- Performance impact and resource usage
- Documentation completeness and clarity
- Test coverage and quality
### Documentation (Markdown)
- 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
```
type(scope): brief description
Longer explanation if needed.
- Specific changes made
- Why the change was needed
- Any breaking changes noted
- V4 component impacts (agents, modes, core components)
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
Scopes: `agents`, `modes`, `mcp`, `core`, `commands`, `lifecycle`
## 🔄 Development Workflow
### 1. Fork & Branch
```bash
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 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, framework)
- Update documentation for new features and integration points
- Demonstrate compatibility with existing V4 systems
### 4. Code Review
- Address feedback promptly
- Keep discussions focused and respectful
- Be open to suggestions and improvements
## 📦 Release Process
### Version Management
- Follow [Semantic Versioning](https://semver.org/)
- 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 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
For detailed development guidelines, see [Contributing Code Guide](Developer-Guide/contributing-code.md).
## 🤝 Community Guidelines
### Be Respectful
- Welcome newcomers and different experience levels
- Focus on the code and ideas, not personal attributes
- Help others learn and improve
All community interactions should embody professional software development standards:
**Professional Communication:**
- Use clear, technical language appropriate for software development
- Provide specific, actionable feedback with examples
- Focus discussions on technical merit and project goals
- Respect different experience levels and learning approaches
**Constructive Collaboration:**
- Assume positive intent in all interactions
- Ask clarifying questions before making assumptions
- Provide helpful context and reasoning for decisions
- Acknowledge good contributions and helpful community members
**Technical Focus:**
- Keep discussions centered on software development and framework improvement
- Base decisions on technical merit, user value, and project alignment
- Use evidence and examples to support arguments
- Maintain focus on practical utility over theoretical perfection
**Inclusive Environment:**
- Welcome contributors of all skill levels and backgrounds
- Provide mentorship and guidance for new contributors
- Create learning opportunities through code review and discussion
- Celebrate diverse perspectives and solution approaches
### Stay Focused
- Keep discussions relevant to SuperClaude's goals
- Avoid scope creep in feature requests
- Consider if changes fit the modular philosophy
**Project Focus:**
SuperClaude Framework enhances Claude Code for systematic software development workflows. Contributions should align with this core mission.
**In Scope:**
- Software development workflow automation
- Domain-specific agent development (security, performance, architecture)
- MCP server integrations for enhanced capabilities
- Quality assurance and validation systems
- Session management and project persistence
- Educational content for software development practices
**Out of Scope:**
- General-purpose AI applications unrelated to software development
- Features that significantly increase complexity without clear developer value
- Platform-specific implementations that don't support cross-platform usage
- Commercial or proprietary integrations without open alternatives
**Decision Framework:**
1. **Developer Value**: Does this help software developers build better systems?
2. **Framework Integration**: Does this work well with existing commands/agents/modes?
3. **Maintenance Burden**: Can this be maintained with available resources?
4. **Educational Merit**: Does this teach good software development practices?
**Scope Boundaries:**
- Focus on software development, not general productivity
- Enhance existing workflows rather than creating entirely new paradigms
- Maintain simplicity while adding powerful capabilities
- Support professional development practices and quality standards
### Quality First
- Test your changes thoroughly
- Consider performance impact
- Think about maintainability
**Code Quality Standards:**
**Technical Excellence:**
- All code must pass existing test suites
- New features require comprehensive test coverage (>90%)
- Follow established coding patterns and architectural principles
- Include proper error handling and edge case management
- Optimize for performance and resource efficiency
**Documentation Requirements:**
- All public APIs must have clear documentation with examples
- User-facing features need usage guides and cookbook recipes
- Code changes require updated relevant documentation
- Breaking changes must include migration guides
**User Experience Standards:**
- Commands should be discoverable and self-explanatory
- Error messages must be actionable and helpful
- Features should follow progressive complexity principles
- Maintain consistency with existing interface patterns
**Quality Gates:**
- Automated testing for all core functionality
- Manual testing for user workflows and integration scenarios
- Code review by at least one maintainer
- Documentation review for clarity and completeness
- Performance impact assessment for changes
**Professional Standards:**
- Code should be production-ready, not prototype quality
- Follow security best practices for external integrations
- Ensure cross-platform compatibility and proper dependency management
- Maintain backward compatibility or provide clear migration paths
## 💬 Getting Help
### Channels
- **GitHub Issues**: Bug reports and feature requests
- **GitHub Discussions**: General questions and ideas
- **Documentation**: Check existing guides first
**GitHub Issues** (Primary Support)
- Bug reports and technical issues
- Feature requests and enhancement proposals
- Documentation improvements and clarifications
- General troubleshooting with community help
**GitHub Discussions**
- General questions about usage and best practices
- Sharing workflows and success stories
- Community-driven tips and patterns
- Design discussions for major features
**Documentation Resources**
- [Troubleshooting Guide](Reference/troubleshooting.md) - Common issues and solutions
- [Examples Cookbook](Reference/examples-cookbook.md) - Practical usage patterns
- [Best Practices](Reference/best-practices.md) - Optimization strategies
- [Technical Architecture](Developer-Guide/technical-architecture.md) - Framework design
**Development Support**
- [Contributing Code Guide](Developer-Guide/contributing-code.md) - Development setup
- [Testing & Debugging](Developer-Guide/testing-debugging.md) - Quality procedures
- Code review process through pull requests
- Maintainer guidance on complex contributions
**Response Expectations:**
- Bug reports: 1-3 business days
- Feature requests: Review within 1 week
- Pull requests: Initial review within 3-5 days
- Documentation issues: Quick turnaround when straightforward
**Self-Help First:**
Before seeking support, please:
1. Check existing documentation and troubleshooting guides
2. Search GitHub issues for similar problems
3. Verify you're using the latest SuperClaude version
4. Test with minimal reproduction case
### Common Questions
**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.
**Development Environment Issues:**
**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: "SuperClaude install fails with permission errors"**
A: Use `pip install --user SuperClaude` or create virtual environment. See [Installation Guide](Getting-Started/installation.md) for details.
**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: "Commands not recognized after installation"**
A: Restart Claude Code session. Verify installation with `SuperClaude install --list-components`. Check ~/.claude directory exists.
**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: "MCP servers not connecting"**
A: Check Node.js installation for MCP servers. Verify ~/.claude/.claude.json configuration. Try `SuperClaude install --components mcp --force`.
**Q: What's the difference between agents and modes?**
A: Agents provide domain expertise (system-architect, performance-engineer), while modes modify Claude's behavioral approach (brainstorming, task management, token efficiency).
**Code Development:**
## 🚀 Contributing to V4 Components
**Q: "How do I add a new agent?"**
A: Follow agent patterns in setup/components/agents.py. Include trigger keywords, capabilities description, and integration tests.
### 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
**Q: "Testing framework setup?"**
A: See [Testing & Debugging Guide](Developer-Guide/testing-debugging.md). Use pytest for Python tests, include component validation.
### 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
**Q: "Documentation structure?"**
A: Follow existing patterns: Getting-Started → User-Guide → Developer-Guide → Reference. Include examples and progressive complexity.
### Enhancing Session Lifecycle
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
5. **Memory Optimization**: Follow selective compression patterns
**Feature Development:**
### 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
**Q: "How do I propose a new command?"**
A: Open GitHub issue with use case, integration approach, and technical design. Reference similar existing commands.
**Q: "MCP server integration process?"**
A: Study existing MCP configurations in setup/components/mcp.py. Include server documentation, configuration examples, and troubleshooting.
**Q: "Performance optimization guidelines?"**
A: Profile before optimizing. Focus on common workflows. Maintain cross-platform compatibility. Document performance characteristics.
## 📄 License
By contributing, you agree that your contributions will be licensed under the MIT License.
**MIT License Agreement:**
By contributing to SuperClaude Framework, you agree that your contributions will be licensed under the same MIT License that covers the project. This ensures the framework remains open and accessible for educational and commercial use.
**Contribution Terms:**
- All contributions become part of the SuperClaude Framework under MIT License
- Contributors retain copyright to their original work
- No contributor license agreement (CLA) required for simple contributions
- Complex contributions may require explicit license confirmation
**Third-Party Content:**
- Do not include copyrighted code without proper attribution and compatible licensing
- External libraries must use MIT-compatible licenses (Apache 2.0, BSD, etc.)
- Document any third-party dependencies in requirements and documentation
- Respect intellectual property and attribution requirements
**Original Work:**
- Ensure all contributed code is your original work or properly attributed
- Reference external sources, algorithms, or patterns appropriately
- Include proper attribution for adapted or derived code
- Document any patent or licensing considerations
**Commercial Usage:**
The MIT License explicitly allows commercial use of SuperClaude Framework, including contributions. This supports the project's goal of enabling professional software development workflows.
## 🙏 Acknowledgments
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.
**Project Contributors:**
SuperClaude Framework benefits from community contributions across documentation, code development, testing, and user experience improvements.
**Recognition:**
- [GitHub Contributors Graph](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) - Complete contributor list
- Release notes acknowledge significant contributions
- Documentation contributors credited in relevant guides
- Community discussions highlight helpful patterns and solutions
**Community Impact:**
- Enhanced developer productivity through systematic workflows
- Educational value for software development practices
- Open-source contribution to AI-assisted development tools
- Cross-platform compatibility and accessibility
**Contribution Types:**
- **Code Development**: Framework features, agents, MCP integrations
- **Documentation**: Guides, examples, troubleshooting resources
- **Testing**: Quality assurance, edge case discovery, platform validation
- **Community**: Support, pattern sharing, feedback, and usage examples
**Special Thanks:**
- Early adopters providing feedback and real-world usage patterns
- Documentation contributors improving clarity and completeness
- Testers identifying platform-specific issues and edge cases
- Community members sharing workflows and best practices
**Growth:**
The SuperClaude Framework community continues growing through shared commitment to systematic software development and AI-assisted workflows. Every contribution, from typo fixes to major features, strengthens the framework for all users.
**Join Us:**
Whether you're fixing documentation, adding features, or sharing usage patterns, your contributions help build better software development tools for the entire community.

728
Developer-Guide/contributing-code.md Normal file
View File

@ -0,0 +1,728 @@
# Contributing Code to SuperClaude Framework 🛠️
Welcome to SuperClaude Framework development! This guide provides everything you need to contribute to the meta-programming framework that transforms Claude Code into a structured development platform.
**Project Purpose**: SuperClaude enhances Claude Code through behavioral instruction injection, intelligent agent coordination, and MCP server integration. We're building the next generation of AI-assisted development tools.
**Community Approach**: Open collaboration focused on expanding capabilities, improving user experience, and maintaining high-quality code standards. Every contribution, from bug fixes to new features, helps advance AI-assisted development.
## 🚀 Development Setup
### Prerequisites
**Required:**
- Python 3.8+ with pip
- Git for version control
- Claude Code installed and working
- Node.js 16+ (for MCP server development)
**Recommended:**
- VS Code or PyCharm for development
- Docker for containerized testing
- 8GB RAM for full development environment
- 2GB disk space for repositories and dependencies
**System Check:**
```bash
# Verify prerequisites
python3 --version # Should be 3.8+
node --version # Should be 16+
git --version # Any recent version
claude --version # Verify Claude Code works
```
### Development Environment Setup
**1. Fork and Clone Repository:**
```bash
# Fork SuperClaude_Framework on GitHub first
git clone https://github.com/YOUR_USERNAME/SuperClaude_Framework.git
cd SuperClaude_Framework
```
**2. Set Up Python Environment:**
```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# For Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
```
**3. Configure Development Environment:**
```bash
# Set up development configuration
export SUPERCLAUDE_DEV=true
export CLAUDE_CONFIG_DIR=./dev-config
# Create development configuration
mkdir -p dev-config
cp -r SuperClaude/Core/* dev-config/
```
**4. Verify Installation:**
```bash
# Test installation
python -m SuperClaude --version
python -m SuperClaude install --dry-run --install-dir ./dev-config
# Run tests
python -m pytest tests/
python scripts/validate_pypi_ready.py
```
**5. Development Tools Setup:**
```bash
# Install development tools
pip install black pylint mypy pre-commit
# Set up pre-commit hooks
pre-commit install
# Configure IDE (VS Code example)
cp .vscode/settings.json.template .vscode/settings.json
```
## 🏗️ Architecture Overview
### Core Components
**SuperClaude Framework Structure:**
```
SuperClaude_Framework/
├── SuperClaude/ # Framework components
│ ├── Core/ # Core behavioral instructions
│ │ ├── FLAGS.md # Behavioral flags system
│ │ ├── RULES.md # Development rules
│ │ └── PRINCIPLES.md # Engineering principles
│ ├── Modes/ # 6 behavioral modes
│ │ ├── MODE_Brainstorming.md
│ │ ├── MODE_Introspection.md
│ │ └── MODE_*.md
│ ├── MCP/ # MCP server integrations
│ │ ├── MCP_Context7.md
│ │ ├── MCP_Sequential.md
│ │ └── configs/
│ ├── Commands/ # 21 slash commands
│ │ ├── brainstorm.md
│ │ └── *.md
│ └── Agents/ # 13 specialized agents
├── setup/ # Installation system
│ ├── components/ # Component definitions
│ ├── core/ # Installation logic
│ ├── services/ # System services
│ └── utils/ # Utilities
├── User-Guide/ # User documentation
├── Developer-Guide/ # Technical documentation
├── Reference/ # Reference materials
└── tests/ # Test suite
```
**Key Architectural Concepts:**
- **Meta-Framework**: Enhances Claude Code through configuration injection
- **Component System**: Modular installation with dependency resolution
- **Behavioral Programming**: AI behavior modification through .md files
- **Intelligent Orchestration**: Dynamic coordination of agents and tools
### V4 Beta Architecture
#### Agents System
**13 Specialized AI Agents:**
- **Architecture**: system-architect, backend-architect, frontend-architect, devops-architect
- **Quality**: security-engineer, performance-engineer, quality-engineer, refactoring-expert
- **Analysis**: root-cause-analyst, requirements-analyst
- **Specialized**: python-expert, technical-writer, learning-guide
**Agent Development Pattern:**
```python
# setup/components/agents.py
class AgentComponent(BaseComponent):
def get_agent_definitions(self):
return {
'agent-id': {
'triggers': ['keyword1', 'keyword2'],
'capabilities': ['capability1', 'capability2'],
'expertise_level': 0.9,
'collaboration_style': 'strategic_lead'
}
}
```
#### Modes System
**6 Behavioral Modes:**
- **Brainstorming**: Interactive discovery and requirements exploration
- **Introspection**: Meta-cognitive analysis and reasoning transparency
- **Task Management**: Hierarchical organization for complex operations
- **Orchestration**: Intelligent tool selection and coordination
- **Token Efficiency**: Compressed communication (30-50% reduction)
- **Standard**: Balanced default behavior
**Mode Development Pattern:**
```markdown
# MODE_CustomMode.md
**Purpose**: Brief description of mode's behavioral changes
## Activation Triggers
- keyword1, keyword2, specific patterns
## Behavioral Changes
- Change 1: Description and impact
- Change 2: Description and impact
## Examples
- Usage scenario with input/output examples
```
#### MCP Integration
**6 MCP Servers:**
- **Context7**: Official library documentation and patterns
- **Sequential**: Multi-step reasoning and systematic analysis
- **Magic**: Modern UI component generation from 21st.dev
- **Playwright**: Browser automation and E2E testing
- **Morphllm**: Pattern-based code transformation
- **Serena**: Semantic understanding and project memory
**MCP Development Pattern:**
```python
# setup/components/mcp.py
class MCPComponent(BaseComponent):
def get_mcp_servers(self):
return {
'server-name': {
'command': 'node',
'args': ['/path/to/server'],
'capabilities': ['capability1', 'capability2'],
'auto_activation': ['trigger1', 'trigger2']
}
}
```
## 📝 Code Contribution Guidelines
### Documentation (Markdown)
**Documentation Standards:**
- **Clarity**: Clear, concise writing accessible to target audience
- **Structure**: Logical organization with consistent heading hierarchy
- **Examples**: Practical code examples for all concepts
- **Accuracy**: Technical accuracy verified through testing
- **Completeness**: Cover all use cases and edge cases
**Markdown Conventions:**
```markdown
# Main Title (H1) - Once per document
## Section (H2) - Major sections
### Subsection (H3) - Detailed topics
#### Detail (H4) - Specific implementation details
**Bold** for emphasis and important concepts
`code` for inline code and commands
```code blocks``` for examples
**Flags**: Use consistent flag notation (--flag-name)
**Commands**: Use consistent command notation (/sc:command)
```
**Code Example Standards:**
```bash
# Good: Complete, runnable examples
/sc:implement "user authentication system"
# → Auto-activates: security-engineer + backend-architect
# Bad: Incomplete or non-functional examples
/sc:implement auth # Not descriptive enough
```
### Commit Messages
**Commit Message Format:**
```
type(scope): brief description
Detailed explanation if needed, including:
- What changed and why
- Any breaking changes
- Related issue references
Closes #123
```
**Commit Types:**
- **feat**: New feature or enhancement
- **fix**: Bug fix or correction
- **docs**: Documentation changes
- **refactor**: Code restructuring without behavior change
- **test**: Test additions or improvements
- **chore**: Maintenance tasks, dependency updates
**Examples:**
```bash
# Good commit messages
feat(agents): add data-scientist agent with ML capabilities
fix(mcp): resolve Context7 connection timeout issues
docs(modes): update behavioral modes with examples
refactor(components): simplify component registration logic
# Bad commit messages
fix stuff
update files
changes
```
## 🔄 Development Workflow
### 1. Fork & Branch
**Git Workflow:**
```bash
# 1. Fork repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/SuperClaude_Framework.git
cd SuperClaude_Framework
# 3. Add upstream remote
git remote add upstream https://github.com/SuperClaude-Org/SuperClaude_Framework.git
# 4. Create feature branch
git checkout -b feature/your-feature-name
# Examples: feature/data-scientist-agent, fix/mcp-connection-timeout
```
**Branch Naming Conventions:**
- **feature/**: New features (`feature/research-mode`)
- **fix/**: Bug fixes (`fix/installation-error`)
- **docs/**: Documentation (`docs/contributing-guide`)
- **refactor/**: Code restructuring (`refactor/component-system`)
### 2. Develop & Test
**Development Process:**
```bash
# 1. Make changes following coding standards
# 2. Test changes locally
python -m pytest tests/
python scripts/validate_pypi_ready.py
# 3. Test installation
SuperClaude install --dry-run --components your-component
# 4. Run linting and formatting
black .
pylint setup/
mypy setup/
# 5. Update documentation if needed
# 6. Add tests for new functionality
```
**Testing Requirements:**
- **Unit Tests**: Test individual components and functions
- **Integration Tests**: Test component interactions
- **Installation Tests**: Verify installation process
- **Documentation Tests**: Ensure examples work
### 3. Submit Pull Request
**Pull Request Process:**
```bash
# 1. Commit changes with descriptive messages
git add .
git commit -m "feat(agents): add research agent with citation management"
# 2. Push to your fork
git push origin feature/your-feature-name
# 3. Create Pull Request on GitHub with:
# - Clear title and description
# - Link to related issues
# - Test results and verification
# - Breaking changes documentation
```
**Pull Request Template:**
```markdown
## Description
Brief description of changes and motivation
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Breaking change
## Testing
- [ ] Tests pass locally
- [ ] Installation tested
- [ ] Documentation updated
- [ ] Examples verified
## Checklist
- [ ] Code follows project standards
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
```
### 4. Code Review
**Code Review Process:**
1. **Automated Checks**: GitHub Actions run tests and validation
2. **Maintainer Review**: Core team reviews code quality and design
3. **Community Feedback**: Community members provide input
4. **Revision**: Address feedback and make requested changes
5. **Approval**: Final approval and merge by maintainers
**Review Criteria:**
- **Functionality**: Code works as intended
- **Quality**: Follows coding standards and best practices
- **Testing**: Adequate test coverage and validation
- **Documentation**: Clear documentation and examples
- **Impact**: No breaking changes without justification
- **Performance**: No significant performance degradation
**Addressing Feedback:**
```bash
# 1. Make requested changes
# 2. Commit with clear messages
git add .
git commit -m "address review: improve error handling in component loader"
# 3. Push updates
git push origin feature/your-feature-name
# 4. Respond to review comments
# 5. Request re-review when ready
```
## 📦 Release Process
### Version Management
**Semantic Versioning (SemVer):**
- **Major (X.0.0)**: Breaking changes requiring user action
- **Minor (X.Y.0)**: New features, backward compatible
- **Patch (X.Y.Z)**: Bug fixes, backward compatible
**Version Update Process:**
```bash
# 1. Update version in setup.py and __init__.py
# 2. Update CHANGELOG.md with release notes
# 3. Create version tag
git tag -a v4.1.0 -m "Release v4.1.0: Add research agent and enhanced MCP integration"
# 4. Push tag
git push upstream v4.1.0
```
**Release Branches:**
- **master**: Stable releases
- **SuperClaude_V4_Beta**: Beta releases and development
- **hotfix/***: Critical fixes for production
### Release Checklist
**Pre-Release Validation:**
- [ ] All tests pass (`python -m pytest tests/`)
- [ ] Installation validation (`python scripts/validate_pypi_ready.py`)
- [ ] Documentation updated and accurate
- [ ] CHANGELOG.md updated with release notes
- [ ] Version numbers updated consistently
- [ ] Breaking changes documented
- [ ] Migration guides created if needed
**Release Process:**
- [ ] Create release branch from master
- [ ] Final testing on clean environment
- [ ] Generate release notes
- [ ] Create GitHub release with tag
- [ ] Publish to PyPI (`python setup.py sdist bdist_wheel && twine upload dist/*`)
- [ ] Update NPM wrapper package
- [ ] Announce release in community channels
**Post-Release:**
- [ ] Monitor for critical issues
- [ ] Update documentation sites
- [ ] Prepare hotfix procedures if needed
- [ ] Plan next release cycle
## 🚀 Contributing to V4 Components
### Creating New Agents
**Agent Development Process:**
1. **Identify Need**: Clear use case and domain expertise gap
2. **Define Specialization**: Unique capabilities and triggers
3. **Implement Component**: Following agent development pattern
4. **Create Documentation**: Agent description and examples
5. **Test Integration**: Verify activation and coordination
**Agent Implementation Example:**
```python
# setup/components/custom_agent.py
from setup.components.base import BaseComponent
class DataScienceAgentComponent(BaseComponent):
def get_metadata(self):
return {
'name': 'data_science_agent',
'description': 'Specialized agent for data science and ML workflows',
'dependencies': ['core']
}
def install(self, install_dir):
agent_file = install_dir / 'AGENT_DataScientist.md'
self._write_agent_definition(agent_file, {
'expertise': ['data_analysis', 'machine_learning', 'statistical_modeling'],
'triggers': ['data', 'analytics', 'machine learning', 'statistics'],
'capabilities': ['data_preprocessing', 'model_development', 'visualization'],
'collaboration_style': 'analytical_contributor'
})
```
**Agent Documentation Template:**
```markdown
# Data Scientist Agent 📊
**Purpose**: Advanced data science and machine learning expertise
**Auto-Activation Triggers:**
- Keywords: data, analytics, ML, statistics, pandas, numpy
- File types: .ipynb, .csv, .parquet
- Domain: data science workflows
**Capabilities:**
- Data analysis and preprocessing
- Statistical modeling and hypothesis testing
- Machine learning model development
- Data visualization and reporting
**Examples:**
- Exploratory data analysis workflows
- ML model selection and optimization
- Statistical significance testing
- Data pipeline development
```
### Developing Behavioral Modes
**Mode Development Guidelines:**
1. **Clear Purpose**: Specific behavioral modification goal
2. **Distinct Triggers**: Unique activation patterns
3. **Measurable Impact**: Quantifiable behavioral changes
4. **Documentation**: Complete usage examples
5. **Integration**: Compatibility with existing modes
**Mode Implementation Example:**
```markdown
# MODE_Research.md
**Purpose**: Academic and technical research with systematic methodology
## Activation Triggers
- Research keywords: research, study, investigate, literature
- Academic contexts: citation, peer review, hypothesis
- Manual flags: --research, --academic
## Behavioral Changes
- **Systematic Methodology**: Structure research with clear phases
- **Source Validation**: Verify information credibility and currency
- **Citation Management**: Proper attribution and reference formatting
- **Evidence-Based**: Support claims with verifiable sources
## Examples
Standard: "Tell me about microservices"
Research: "📚 Research Methodology:
1. Literature review of microservices patterns
2. Industry case studies and implementations
3. Performance benchmarks and trade-offs
📖 Sources: [Academic papers, industry reports]"
```
### Enhancing Session Lifecycle
**Session Enhancement Areas:**
1. **Memory Management**: Improve context preservation and retrieval
2. **Cross-Session Learning**: Enhance pattern recognition and adaptation
3. **Multi-User Coordination**: Team session coordination features
4. **Performance Optimization**: Memory efficiency and loading speed
5. **Recovery Mechanisms**: Robust session recovery and backup
**Session Development Pattern:**
```python
# Extending session management
class SessionEnhancement:
def enhance_memory_retention(self, session_context):
# Implement improved memory compression
# Add intelligent context pruning
# Enhance pattern recognition
pass
def add_collaboration_features(self, session_id):
# Multi-developer session coordination
# Shared project context
# Conflict resolution mechanisms
pass
```
**Session Contribution Requirements:**
- **Backward Compatibility**: Existing sessions must work unchanged
- **Performance**: No degradation in session load/save times
- **Testing**: Comprehensive session lifecycle testing
- **Documentation**: Clear session enhancement examples
### MCP Server Integration
**MCP Server Development Process:**
1. **Capability Definition**: Clear server purpose and functions
2. **Protocol Implementation**: Standard MCP protocol compliance
3. **SuperClaude Integration**: Auto-activation and coordination
4. **Testing**: Server functionality and integration testing
5. **Documentation**: Usage patterns and examples
**MCP Server Integration Example:**
```python
# setup/components/custom_mcp.py
class DatabaseAnalyzerMCPComponent(BaseComponent):
def get_metadata(self):
return {
'name': 'database_analyzer_mcp',
'description': 'Database query optimization and schema analysis',
'dependencies': ['core', 'mcp']
}
def install(self, install_dir):
# Add to MCP configuration
self._add_mcp_server_config({
'database-analyzer': {
'command': 'node',
'args': ['/path/to/database-analyzer-server.js'],
'capabilities': ['query_optimization', 'schema_analysis'],
'auto_activation': ['database', 'sql', 'query optimization']
}
})
# Create server instruction file
self._create_mcp_instructions('MCP_DatabaseAnalyzer.md')
```
**MCP Integration Requirements:**
- **Protocol Compliance**: Standard MCP protocol implementation
- **Error Handling**: Robust connection and error recovery
- **Performance**: Acceptable latency and resource usage
- **Documentation**: Clear capability and usage documentation
## 💬 Getting Help
### Development Channels
**Primary Support Channels:**
- **GitHub Issues**: Bug reports, feature requests, technical questions
- **GitHub Discussions**: General questions, ideas, community chat
- **Pull Request Reviews**: Code-specific feedback and guidance
- **Documentation**: Comprehensive guides and examples
**Channel Guidelines:**
- **Issues**: Specific, reproducible problems with detailed information
- **Discussions**: Open-ended questions, ideas, and community interaction
- **Pull Requests**: Code review, implementation feedback, technical guidance
**Response Expectations:**
- **Critical Issues**: 24-48 hours
- **General Questions**: 2-5 days
- **Feature Requests**: Weekly review cycle
- **Pull Requests**: 3-7 days initial review
### Common Development Questions
**Q: How do I test my component changes locally?**
```bash
# Install in development mode
pip install -e ".[dev]"
# Test specific component
SuperClaude install --dry-run --components your-component
# Run test suite
python -m pytest tests/test_your_component.py
```
**Q: Where should I add my custom agent?**
```
# Agent files go in:
SuperClaude/Agents/AGENT_YourAgent.md
# Component definition goes in:
setup/components/your_agent.py
# Tests go in:
tests/test_your_agent.py
```
**Q: How do I handle component dependencies?**
```python
def get_dependencies(self):
return ['core', 'mcp'] # Required components
def get_metadata(self):
return {
'dependencies': ['core', 'mcp'],
'optional_dependencies': ['agents']
}
```
**Q: What's the difference between agents and MCP servers?**
- **Agents**: Behavioral specializations within Claude Code
- **MCP Servers**: External tools that extend capabilities
- **Agents** coordinate; **MCP servers** provide enhanced functionality
**Q: How do I contribute documentation?**
1. Find documentation TODOs in relevant files
2. Follow markdown conventions and examples
3. Test all code examples
4. Submit PR with documentation changes
**Q: My MCP server isn't activating automatically. Why?**
Check:
1. Server defined in MCP configuration
2. Auto-activation triggers properly configured
3. Server starts successfully
4. Triggers match user input patterns
## 📄 License
**MIT License**: SuperClaude Framework is licensed under the MIT License, providing maximum freedom for use, modification, and distribution.
**Contribution License Agreement:**
By contributing to SuperClaude Framework, you agree that your contributions will be licensed under the same MIT License. You retain copyright to your contributions while granting the project perpetual rights to use, modify, and distribute your code.
**Third-Party Dependencies:**
Ensure any dependencies you add are compatible with MIT License. Common compatible licenses: MIT, Apache 2.0, BSD. Avoid GPL and other copyleft licenses.
## 🙏 Acknowledgments
**Core Contributors:**
- Framework architecture and implementation
- Community management and support
- Documentation and user experience
- Testing and quality assurance
**Community Impact:**
SuperClaude Framework exists because of the collaborative effort of developers, users, and contributors who believe in advancing AI-assisted development. Every bug report, feature suggestion, documentation improvement, and code contribution makes the framework better for everyone.
**Special Recognition:**
- **Early Adopters**: Testing and feedback during beta development
- **Documentation Contributors**: Improving accessibility and usability
- **Bug Hunters**: Finding and reporting issues that improve stability
- **Feature Contributors**: Adding capabilities that expand framework utility
**Contributing Recognition:**
All contributors are recognized in our GitHub contributors page and release notes. Significant contributions may be highlighted in project announcements and community updates.
**Join the Community:**
Your expertise and perspective make SuperClaude Framework better. Whether you're fixing typos, adding features, or helping other users, every contribution advances the goal of more effective AI-assisted development.
**Thank you for contributing to the future of AI-enhanced development tools! 🚀**

1729
Developer-Guide/technical-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

1668
Developer-Guide/testing-debugging.md Normal file
View File

File diff suppressed because it is too large Load Diff

446
Getting-Started/installation.md Normal file
View File

@ -0,0 +1,446 @@
# SuperClaude Installation Guide 📦
## 🎯 It's Easier Than It Looks!
SuperClaude installs in under 2 minutes with an interactive installer. The process involves installing the Python package and running the component installer to configure your Claude Code environment.
## Quick Start 🚀
**Method 1: Python (Recommended)**
```bash
pip install SuperClaude
SuperClaude install
```
**Method 2: NPM (Cross-platform)**
```bash
npm install -g superclaude
superclaude install
```
**Method 3: Development**
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install -e ".[dev]"
SuperClaude install --dry-run
```
---
**What Gets Installed:**
- 21 slash commands (/sc:*) for workflow automation
- 13 specialized AI agents with domain expertise
- 6 behavioral modes for different contexts
- 6 MCP server configurations for enhanced capabilities
- Core instruction files in ~/.claude directory
**Dry-run Preview:**
```bash
SuperClaude install --dry-run # Preview changes without installing
```
## Before You Start 🔍
### What You Need 💻
**Required:**
- Python 3.8+ with pip
- Claude Code installed and working
- 50MB free space for components
**Optional but Recommended:**
- Node.js 16+ (for MCP servers like Context7, Magic)
- Git (for version control integration)
- 1GB RAM for optimal performance
### Quick Check 🔍
Run these commands to verify your system is ready:
```bash
# Verify Python (should be 3.8+)
python3 --version
# Verify Claude Code availability
claude --version
# Optional: Check Node.js for MCP servers
node --version
# Check available disk space
df -h ~
```
If any checks fail, see [Prerequisites Setup](#prerequisites-setup-🛠️) below.
```bash
# Check Python version (should be 3.8+)
python3 --version
# Check if Claude Code is available
claude --version
# Check Node.js (optional, for MCP servers)
node --version
```
If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below.
## Installation Options 🎛️
### 🎯 Interactive Installation (Default - Recommended)
### ⚡ Component-Specific Installation
### 🔍 Other Useful Options
**Node.js Installation:**
```bash
# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
# macOS
brew install node
# Windows
winget install OpenJS.NodeJS
# Or download from https://nodejs.org/
```
### Getting SuperClaude 📥
**Choose Your Preferred Method:**
**Python Users:**
```bash
pip install SuperClaude
```
**JavaScript/Node.js Users:**
```bash
npm install -g superclaude
```
**Development/Contributors:**
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install -e ".[dev]"
```
### Running the Installer 🎬
**Interactive Installation (Default):**
```bash
SuperClaude install
```
The installer will:
1. Detect your system configuration
2. Show available components with descriptions
3. Let you select which components to install
4. Configure MCP servers if desired
5. Create backups before making changes
**Command-line Options:**
```bash
SuperClaude install --components core mcp modes # Specific components
SuperClaude install --dry-run # Preview only
SuperClaude install --force --yes # Skip confirmations
SuperClaude install --install-dir /custom/path # Custom location
```
### During Installation 📱
**Installation Steps:**
1. **System Check** - Validates Python, Claude Code, permissions
2. **Component Discovery** - Scans available components and dependencies
3. **User Selection** - Interactive menu for component choices
4. **Backup Creation** - Saves existing ~/.claude configuration
5. **File Installation** - Copies framework files with merge logic
6. **MCP Configuration** - Sets up .claude.json for selected servers
7. **Verification** - Tests installation and provides next steps
**Progress Indicators:**
- ✅ Step completion checkmarks
- 🔄 Real-time progress bars for file operations
- ⚠️ Warnings for potential issues
- 📊 Summary statistics (files installed, space used)
## After Installation ✅
### Quick Test 🧪
**Verify Installation:**
```bash
# Check SuperClaude version
SuperClaude --version
# List installed components
SuperClaude install --list-components
# Test basic functionality
echo "Test analysis" | claude
# Then try: /sc:analyze README.md
# Verify MCP servers (if installed)
ls ~/.claude/.claude.json
```
**Expected Results:**
- ✅ Version number displays correctly
- ✅ Components list shows installed items
- ✅ Slash commands available in Claude Code
- ✅ MCP servers connect successfully
### What Got Installed 📂
**Files in ~/.claude:**
```
~/.claude/
├── CLAUDE.md # Main instruction file with @imports
├── FLAGS.md # Behavioral flags system
├── RULES.md # Development rules
├── PRINCIPLES.md # Engineering principles
├── MCP_*.md # MCP server instructions
├── MODE_*.md # Behavioral modes
├── .claude.json # MCP server configurations
└── [your files] # Preserved customizations
```
**Component Breakdown:**
- **Core**: Essential framework files and behavioral instructions
- **Commands**: 21 slash commands for workflow automation
- **Modes**: 6 behavioral modes for different contexts
- **Agents**: 13 specialized AI personas
- **MCP**: Configuration for 6 MCP servers
- **MCP Docs**: Documentation for MCP server usage
### First Steps 🎯
**Try These Commands:**
```bash
# Interactive requirements discovery
/sc:brainstorm "mobile app idea"
# Analyze existing code
/sc:analyze src/
# Generate implementation workflow
/sc:workflow "user authentication system"
# Get command help
/sc:index
```
**Learning Path:**
1. Start with `/sc:brainstorm` for project discovery
2. Use `/sc:analyze` to understand existing code
3. Try `/sc:implement` for feature development
4. Explore `/sc:index` for command discovery
## Managing Your Installation 🛠️
### Updates 📅
**Update SuperClaude:**
```bash
# Update core package
pip install --upgrade SuperClaude
# or: npm update -g superclaude
# Update components
SuperClaude update
# Update specific components
SuperClaude install --components mcp modes --force
```
**Version Management:**
- Updates preserve user customizations
- New components available via `SuperClaude install --list-components`
- Selective updates possible for individual components
### Backups 💾
**Automatic Backups:**
- Created before every installation/update
- Stored in ~/.claude.backup.YYYYMMDD_HHMMSS
- Include all customizations and configurations
**Manual Backup Management:**
```bash
# Create backup
SuperClaude backup --create
# List available backups
SuperClaude backup --list
# Restore from backup
SuperClaude backup --restore ~/.claude.backup.20241201_143022
# Manual backup (alternative)
cp -r ~/.claude ~/.claude.backup.manual
```
### Uninstallation 🗑️
**Complete Removal:**
```bash
# Remove SuperClaude components (preserves user files)
SuperClaude uninstall
# Remove Python package
pip uninstall SuperClaude
# or: npm uninstall -g superclaude
# Manual cleanup (if needed)
rm -rf ~/.claude/FLAGS.md ~/.claude/RULES.md ~/.claude/MODE_*.md
```
**What Gets Preserved:**
- Your custom CLAUDE.md content
- Personal configuration files
- Project-specific customizations
- Created backups (manual removal required)
## Prerequisites Setup 🛠️
**Missing Python?**
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip
# macOS
brew install python3
# Windows
# Download from https://python.org/downloads/
# Or use winget
winget install python
```
**Missing Claude Code?**
- Visit https://claude.ai/code for installation instructions
- SuperClaude enhances Claude Code, so you need it first
**MCP Server Requirements:**
Some MCP servers require Node.js for optimal functionality:
- Context7: Library documentation lookup
- Magic: UI component generation
- Sequential: Advanced reasoning
Install Node.js 16+ for full MCP capabilities.
## Troubleshooting 🔧
**Common Issues:**
**Permission Denied:**
```bash
# Linux/macOS: Use --user flag
pip install --user SuperClaude
# Or fix permissions
sudo chown -R $USER ~/.claude
```
**Python Version Issues:**
```bash
# Verify Python 3.8+
python3 --version
# Use specific Python version
python3.9 -m pip install SuperClaude
```
**Claude Code Not Found:**
- Install Claude Code from https://claude.ai/code
- Verify with: `claude --version`
- Check PATH configuration
**Get Help:**
- GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
- Include: OS, Python version, error message, steps to reproduce
## Advanced Options ⚙️
**Custom Installation Directory:**
```bash
# Install to custom location
SuperClaude install --install-dir /path/to/custom/claude
# Set environment variable
export CLAUDE_CONFIG_DIR=/path/to/custom/claude
SuperClaude install
```
**Development Setup:**
```bash
# Clone repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Install in development mode
pip install -e ".[dev]"
# Run tests
SuperClaude install --dry-run
python scripts/validate_pypi_ready.py
```
## What's Next? 🚀
**Recommended Next Steps:**
1. **Learn Commands**: Start with [Commands Guide](../User-Guide/commands.md)
2. **Try Examples**: Explore [Examples Cookbook](../Reference/examples-cookbook.md)
3. **Configure MCP**: Set up [MCP Servers](../User-Guide/mcp-servers.md)
4. **Understand Modes**: Read [Behavioral Modes](../User-Guide/modes.md)
5. **Join Community**: Follow development on [GitHub](https://github.com/SuperClaude-Org/SuperClaude_Framework)
**Essential Guides:**
- 🚀 [Quick Start Guide](quick-start.md) - 5-minute setup
- 🔧 [Commands Reference](../User-Guide/commands.md) - All 21 commands
- 🧐 [Best Practices](../Reference/best-practices.md) - Optimization tips
- 🎆 [Troubleshooting](../Reference/troubleshooting.md) - Problem solving
---
## Final Notes 📝
**Installation Summary:**
- **Time**: 2-5 minutes typical installation
- **Space**: 50MB for full installation
- **Requirements**: Python 3.8+, Claude Code, 1GB RAM recommended
- **Platform**: Linux, macOS, Windows supported
- **Usage**: Immediate access to 21 commands and 6 behavioral modes
**What's Next**: Your Claude Code now has enhanced capabilities. Try `/sc:brainstorm` for your first SuperClaude experience!
---
## Related Guides
**Documentation Roadmap:**
**Beginner** (🌱 Start Here)
- [Quick Start Guide](quick-start.md) - 5-minute setup
- [Commands Reference](../User-Guide/commands.md) - Basic usage
**Intermediate** (🌿 Growing)
- [Behavioral Modes](../User-Guide/modes.md) - Context optimization
- [MCP Servers](../User-Guide/mcp-servers.md) - Enhanced capabilities
- [Examples Cookbook](../Reference/examples-cookbook.md) - Practical patterns
**Advanced** (🌲 Expert)
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - System design
- [Contributing Code](../Developer-Guide/contributing-code.md) - Development
- [Best Practices](../Reference/best-practices.md) - Optimization strategies

172
Getting-Started/quick-start.md Normal file
View File

@ -0,0 +1,172 @@
# SuperClaude Quick Start Guide
## The Simple Truth
SuperClaude transforms Claude Code into a structured development framework with just one installation command. Behind the simple interface, intelligent routing automatically selects the right tools, activates domain experts, and coordinates complex workflows.
**5-Minute Start**: Install → Try `/sc:brainstorm` → Watch the magic happen.
## Just Start Here
**Installation (2 minutes):**
```bash
pip install SuperClaude && SuperClaude install
```
**First Commands (3 minutes):**
```bash
# Interactive project discovery
/sc:brainstorm "web app for task management"
# Analyze existing code
/sc:analyze src/
# Generate implementation plan
/sc:workflow "add user authentication"
```
**What Happens Automatically:**
- Domain experts activate based on context (frontend, backend, security)
- MCP servers connect for enhanced capabilities
- Behavioral modes adapt to task complexity
- Progress tracking and session management
---
## What is SuperClaude Really?
SuperClaude is a meta-programming framework that enhances Claude Code with:
**21 Slash Commands** for workflow automation (/sc:brainstorm, /sc:implement, /sc:analyze)
**13 AI Specialists** with domain expertise (architect, security, frontend, backend)
**6 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration)
**6 MCP Servers** for enhanced capabilities (Context7, Sequential, Magic, Playwright)
**Version 4.0** delivers production-ready workflow orchestration with intelligent agent coordination and session persistence.
## How It Works
**User Experience:**
You type `/sc:implement "user login"` → SuperClaude analyzes requirements → activates security specialist → connects to Context7 for authentication patterns → generates complete implementation with tests.
**Technical Workflow:**
1. **Command Parser** analyzes intent and complexity
2. **Agent Router** selects appropriate domain specialists
3. **MCP Coordinator** activates relevant servers (Context7, Sequential, etc.)
4. **Session Manager** tracks progress and maintains context
5. **Quality Gates** ensure completeness and validation
---
## First Steps Workflow
**First Session Pattern:**
```bash
# 1. Project Discovery
/sc:brainstorm "e-commerce mobile app"
# 2. Load Context (existing projects)
/sc:load src/
# 3. Analyze Current State
/sc:analyze --focus architecture
# 4. Plan Implementation
/sc:workflow "add payment integration"
# 5. Implement Features
/sc:implement "Stripe payment flow"
# 6. Validate Quality
/sc:test --coverage
# 7. Save Session
/sc:save "payment-integration-complete"
```
**Domain-Specific Workflows:**
- **Frontend**: Magic MCP activates for UI components
- **Backend**: Security specialist ensures proper validation
- **DevOps**: Infrastructure specialist handles deployment
- **Testing**: QA specialist creates comprehensive test suites
---
## Key Takeaways
### SuperClaude's Core Value
SuperClaude transforms Claude Code from a general-purpose AI assistant into a **specialized development framework** with:
- **Systematic Workflows** instead of ad-hoc requests
- **Domain Expertise** through specialized agents
- **Tool Coordination** with MCP server integration
- **Session Persistence** for long-term project continuity
- **Quality Assurance** through built-in validation gates
### The Power is in the Coordination
**Intelligent Coordination Benefits:**
- **Auto-activation**: Right tools for the right tasks
- **Multi-agent Workflows**: Frontend + Backend + Security working together
- **Context Preservation**: No losing track of complex projects
- **Parallel Processing**: Multiple operations running simultaneously
- **Progressive Enhancement**: Simple tasks stay simple, complex tasks get expert attention
### Start Simple, Scale Intelligently
**Learning Path:**
**Week 1**: Master core commands (`/sc:brainstorm`, `/sc:analyze`, `/sc:implement`)
**Week 2**: Explore behavioral modes and flag combinations
**Week 3**: Configure MCP servers for enhanced capabilities
**Week 4**: Create custom workflows and session management patterns
**Usage Recommendations:**
- Start with simple commands and let complexity emerge naturally
- Use `/sc:index` to discover relevant commands for your context
- Enable MCP servers gradually as you understand their benefits
- Save successful patterns with `/sc:save` for reuse
### When to Use SuperClaude
**Use SuperClaude When:**
- Building software projects (any language/framework)
- Need systematic workflows and quality gates
- Working on complex, multi-component systems
- Require session persistence across development cycles
- Want specialized domain expertise (security, performance, etc.)
**Use Standard Claude Code When:**
- Simple questions or explanations
- One-off coding tasks
- Learning programming concepts
- Quick prototypes or experiments
**SuperClaude Excellence**: Multi-step development workflows with quality requirements
---
## Next Steps
**Learning Progression:**
**🌱 Beginner (First Week)**
- [Installation Guide](installation.md) - Get set up
- [Commands Reference](../User-Guide/commands.md) - Learn core commands
- [Examples Cookbook](../Reference/examples-cookbook.md) - Try practical examples
**🌿 Intermediate (Growing Skills)**
- [Behavioral Modes](../User-Guide/modes.md) - Optimize for context
- [Agents Guide](../User-Guide/agents.md) - Understand specialists
- [Session Management](../User-Guide/session-management.md) - Long-term projects
**🌲 Advanced (Expert Usage)**
- [MCP Servers](../User-Guide/mcp-servers.md) - Enhanced capabilities
- [Best Practices](../Reference/best-practices.md) - Optimization strategies
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Deep understanding
**🚑 Support**
- [Troubleshooting](../Reference/troubleshooting.md) - Problem solving
- [Contributing](../Developer-Guide/contributing-code.md) - Join development

547
Guides/agents-guide.md
View File

@ -1,547 +0,0 @@
# SuperClaude Agents Guide 🤖
## Overview
The SuperClaude Framework features 13 specialized domain expert agents that automatically activate based on your task context. These intelligent agents provide expert-level assistance across all aspects of software development, from architecture design to documentation writing.
**The simple truth**: You don't need to pick agents or memorize what they do. SuperClaude automatically brings in the right experts for each situation!
**Here's what actually happens:**
- You type `/analyze auth.js` → Security engineer automatically jumps in 🛡️
- You work on React components → Frontend architect often takes over 🎨
- You debug performance issues → Performance engineer often helps ⚡
- You write documentation → Technical writer usually helps out ✍️
**It's like having a smart team** that knows when to jump in and help, without you managing who does what.
## 🚀 Just Try These (No Agent Knowledge Required)
```bash
# These automatically activate the right experts:
/analyze payment-system/ # → Security + backend experts auto-activate
/build react-app/ # → Frontend architect takes over
/improve slow-queries.sql # → Performance engineer jumps in
/troubleshoot "auth failing" # → Root cause analyst + security expert coordinate
/brainstorm "task manager app" # → Requirements analyst guides discovery
```
**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. See [Examples Cookbook](examples-cookbook.md) for many more examples like these.
---
## The SuperClaude Agent Team 👥
### Architecture & System Design Agents 🏗️
#### 🏗️ `system-architect` - Large-Scale Design Expert
**What they do**: Design scalable system architecture with focus on maintainability and long-term technical decisions
**Auto-activation triggers**:
- Keywords: "architecture", "design", "scalability", "system", "patterns", "microservices"
- Large-scale system design and architectural decisions
- Cross-system integration and design pattern implementation
**Specialized capabilities**:
- **System Design**: Component boundaries, interfaces, and interaction patterns
- **Scalability Architecture**: Horizontal scaling strategies, bottleneck identification
- **Dependency Management**: Coupling analysis, dependency mapping, risk assessment
- **Architectural Patterns**: Microservices, CQRS, event sourcing, domain-driven design
- **Technology Strategy**: Tool selection based on long-term impact and ecosystem fit
**Example use cases**:
```bash
/design microservices-architecture # → System architecture and service design
/analyze --focus architecture system/ # → Architectural review and improvement
/plan scalability-improvements # → Scaling strategy and implementation
```
---
#### ⚙️ `backend-architect` - Reliable Backend Systems Expert
**What they do**: Design reliable backend systems with focus on data integrity, security, and fault tolerance
**Auto-activation triggers**:
- Backend system design and API development requests
- Database design and optimization needs
- Security, reliability, and performance requirements
- Server-side architecture and scalability challenges
**Specialized capabilities**:
- **API Design**: RESTful services, GraphQL, proper error handling, validation
- **Database Architecture**: Schema design, ACID compliance, query optimization
- **Security Implementation**: Authentication, authorization, encryption, audit trails
- **System Reliability**: Circuit breakers, graceful degradation, monitoring
- **Performance Optimization**: Caching strategies, connection pooling, scaling patterns
**Example use cases**:
```bash
/design user-management-api # → Reliable API with proper auth
/optimize database-queries/ # → Performance tuning and indexing
/implement payment-processing # → Secure, reliable payment system
```
---
#### 🎨 `frontend-architect` - Accessible UI Systems Expert
**What they do**: Create accessible, performant user interfaces with focus on user experience and modern frameworks
**Auto-activation triggers**:
- UI component development and design system requests
- Accessibility compliance and WCAG implementation needs
- Performance optimization and Core Web Vitals improvements
- Responsive design and mobile-first development requirements
**Specialized capabilities**:
- **Accessibility**: WCAG 2.1 AA compliance, keyboard navigation, screen reader support
- **Performance**: Core Web Vitals, bundle optimization, loading strategies
- **Responsive Design**: Mobile-first approach, flexible layouts, device adaptation
- **Component Architecture**: Reusable systems, design tokens, maintainable patterns
- **Modern Frameworks**: React, Vue, Angular with best practices and optimization
**Example use cases**:
```bash
/build dashboard-components/ # → Accessible React components
/improve --focus accessibility ui/ # → WCAG compliance and optimization
/optimize bundle-performance # → Core Web Vitals improvement
```
---
#### 🚀 `devops-architect` - Infrastructure Automation Expert
**What they do**: Automate infrastructure and deployment processes with focus on reliability and observability
**Auto-activation triggers**:
- Infrastructure automation and CI/CD pipeline development needs
- Deployment strategy and zero-downtime release requirements
- Monitoring, observability, and reliability engineering requests
- Infrastructure as code and configuration management tasks
**Specialized capabilities**:
- **CI/CD Pipelines**: Automated testing, deployment strategies, rollback capabilities
- **Infrastructure as Code**: Version-controlled, reproducible infrastructure management
- **Observability**: Comprehensive monitoring, logging, alerting, and metrics
- **Container Orchestration**: Kubernetes, Docker, microservices architecture
- **Cloud Automation**: Multi-cloud strategies, resource optimization, compliance
**Example use cases**:
```bash
/deploy production-app # → Zero-downtime deployment pipeline
/build monitoring-stack # → Comprehensive observability setup
/secure infrastructure/ # → Security hardening and compliance
```
### Quality & Analysis Agents 🔍
#### 🛡️ `security-engineer` - Threat Modeling Expert
**What they do**: Identify security vulnerabilities and ensure compliance with security standards and best practices
**Auto-activation triggers**:
- Security vulnerability assessment and code audit requests
- Compliance verification and security standards implementation needs
- Threat modeling and attack vector analysis requirements
- Authentication, authorization, and data protection implementation reviews
**Specialized capabilities**:
- **Vulnerability Assessment**: OWASP Top 10, CWE patterns, code security analysis
- **Threat Modeling**: Attack vector identification, risk assessment, security controls
- **Compliance Verification**: Industry standards, regulatory requirements, security frameworks
- **Authentication & Authorization**: Identity management, access controls, privilege escalation
- **Data Protection**: Encryption implementation, secure data handling, privacy compliance
**Example use cases**:
```bash
/scan --focus security auth-system/ # → Comprehensive security audit
/analyze payment-flow --security # → Threat modeling and risk assessment
/improve --fix vulnerabilities api/ # → Security hardening and fixes
```
---
#### ⚡ `performance-engineer` - Bottleneck Detection Expert
**What they do**: Optimize system performance through measurement-driven analysis and bottleneck elimination
**Auto-activation triggers**:
- Performance optimization requests and bottleneck resolution needs
- Speed and efficiency improvement requirements
- Load time, response time, and resource usage optimization requests
- Core Web Vitals and user experience performance issues
**Specialized capabilities**:
- **Frontend Performance**: Core Web Vitals, bundle optimization, asset delivery
- **Backend Performance**: API response times, query optimization, caching strategies
- **Resource Optimization**: Memory usage, CPU efficiency, network performance
- **Critical Path Analysis**: User journey bottlenecks, load time optimization
- **Benchmarking**: Before/after metrics validation, performance regression detection
**Example use cases**:
```bash
/analyze --focus performance slow-api/ # → Bottleneck identification and fixes
/optimize database-queries/ # → Query performance tuning
/benchmark application-performance # → Load testing and capacity planning
```
---
#### 🔍 `root-cause-analyst` - Systematic Investigation Expert
**What they do**: Systematically investigate complex problems to identify underlying causes through evidence-based analysis and hypothesis testing
**Auto-activation triggers**:
- Complex debugging scenarios requiring systematic investigation and evidence-based analysis
- Multi-component failure analysis and pattern recognition needs
- Problem investigation requiring hypothesis testing and verification
- Root cause identification for recurring issues and system failures
**Specialized capabilities**:
- **Evidence Collection**: Log analysis, error pattern recognition, system behavior investigation
- **Hypothesis Formation**: Multiple theory development, assumption validation, systematic testing approach
- **Pattern Analysis**: Correlation identification, symptom mapping, system behavior tracking
- **Investigation Documentation**: Evidence preservation, timeline reconstruction, conclusion validation
- **Problem Resolution**: Clear remediation path definition, prevention strategy development
**Example use cases**:
```bash
/troubleshoot "payment processing fails randomly" # → Systematic investigation
/analyze mysterious-bug/ # → Evidence-based debugging
/investigate system-outage-logs/ # → Root cause analysis
```
---
#### 🧪 `quality-engineer` - Quality Assurance Expert
**What they do**: Ensure software quality through comprehensive testing strategies and systematic edge case detection
**Auto-activation triggers**:
- Testing strategy design and comprehensive test plan development requests
- Quality assurance process implementation and edge case identification needs
- Test coverage analysis and risk-based testing prioritization requirements
- Automated testing framework setup and integration testing strategy development
**Specialized capabilities**:
- **Test Strategy Design**: Comprehensive test planning, risk assessment, coverage analysis
- **Edge Case Detection**: Boundary conditions, failure scenarios, negative testing
- **Test Automation**: Framework selection, CI/CD integration, automated test development
- **Quality Metrics**: Coverage analysis, defect tracking, quality risk assessment
- **Testing Methodologies**: Unit, integration, performance, security, and usability testing
**Example use cases**:
```bash
/test --comprehensive user-service/ # → Full testing strategy and implementation
/validate --quality critical-features/ # → Quality gate implementation
/analyze --focus testing legacy-code/ # → Testing strategy for existing code
```
---
#### 🔄 `refactoring-expert` - Clean Code Specialist
**What they do**: Improve code quality and reduce technical debt through systematic refactoring and clean code principles
**Auto-activation triggers**:
- Code complexity reduction and technical debt elimination requests
- SOLID principles implementation and design pattern application needs
- Code quality improvement and maintainability enhancement requirements
- Refactoring methodology and clean code principle application requests
**Specialized capabilities**:
- **Code Simplification**: Complexity reduction, readability improvement, cognitive load minimization
- **Technical Debt Reduction**: Duplication elimination, anti-pattern removal, quality metric improvement
- **Pattern Application**: SOLID principles, design patterns, refactoring catalog techniques
- **Quality Metrics**: Cyclomatic complexity, maintainability index, code duplication measurement
- **Safe Transformation**: Behavior preservation, incremental changes, comprehensive testing validation
**Example use cases**:
```bash
/improve --focus quality legacy-module/ # → Comprehensive code quality improvement
/refactor --safe complex-functions/ # → Safe refactoring with test coverage
/cleanup --technical-debt codebase/ # → Systematic technical debt reduction
```
### Specialized Development Agents 🎯
#### 🐍 `python-expert` - Master Python Specialist
**What they do**: Deliver production-ready, secure, high-performance Python code following SOLID principles and modern best practices
**Auto-activation triggers**:
- Python development requests requiring production-quality code and architecture decisions
- Code review and optimization needs for performance and security enhancement
- Testing strategy implementation and comprehensive coverage requirements
- Modern Python tooling setup and best practices implementation
**Specialized capabilities**:
- **Production Quality**: Security-first development, comprehensive testing, error handling, performance optimization
- **Modern Architecture**: SOLID principles, clean architecture, dependency injection, separation of concerns
- **Testing Excellence**: TDD approach, unit/integration/property-based testing, 95%+ coverage, mutation testing
- **Security Implementation**: Input validation, OWASP compliance, secure coding practices, vulnerability prevention
- **Performance Engineering**: Profiling-based optimization, async programming, efficient algorithms, memory management
**Example use cases**:
```bash
/build python-api --focus security # → Production-ready FastAPI with security
/improve legacy-python/ --focus quality # → Refactor to SOLID principles
/test python-service/ --comprehensive # → Full test suite with coverage
```
---
#### 📋 `requirements-analyst` - Requirements Discovery Expert
**What they do**: Transform ambiguous project ideas into concrete specifications through systematic requirements discovery and structured analysis
**Auto-activation triggers**:
- Ambiguous project requests requiring requirements clarification and specification development
- PRD creation and formal project documentation needs from conceptual ideas
- Stakeholder analysis and user story development requirements
- Project scope definition and success criteria establishment requests
**Specialized capabilities**:
- **Requirements Discovery**: Systematic questioning, stakeholder analysis, user need identification
- **Specification Development**: PRD creation, user story writing, acceptance criteria definition
- **Scope Definition**: Boundary setting, constraint identification, feasibility validation
- **Success Metrics**: Measurable outcome definition, KPI establishment, acceptance condition setting
- **Stakeholder Alignment**: Perspective integration, conflict resolution, consensus building
**Example use cases**:
```bash
/brainstorm "task management app" # → Interactive discovery session
# → Automatic handoff to requirements analyst
# → PRD generation with structured requirements
```
### Communication & Learning Agents 📚
#### ✍️ `technical-writer` - Documentation Excellence Expert
**What they do**: Create clear, comprehensive technical documentation tailored to specific audiences with focus on usability and accessibility
**Auto-activation triggers**:
- API documentation and technical specification creation requests
- User guide and tutorial development needs for technical products
- Documentation improvement and accessibility enhancement requirements
- Technical content structuring and information architecture development
**Specialized capabilities**:
- **Audience Analysis**: User skill level assessment, goal identification, context understanding
- **Content Structure**: Information architecture, navigation design, logical flow development
- **Clear Communication**: Plain language usage, technical precision, concept explanation
- **Practical Examples**: Working code samples, step-by-step procedures, real-world scenarios
- **Accessibility Design**: WCAG compliance, screen reader compatibility, inclusive language
**Example use cases**:
```bash
/document api-endpoints/ # → Comprehensive API documentation
/write user-guide --audience beginner # → User-friendly tutorial and guides
/improve --docs project-documentation/ # → Documentation quality enhancement
```
---
#### 👨‍🏫 `learning-guide` - Learning & Mentorship Expert
**What they do**: Teach programming concepts and explain code with focus on understanding through progressive learning and practical examples
**Auto-activation triggers**:
- Code explanation and programming concept education requests
- Tutorial creation and progressive learning path development needs
- Algorithm breakdown and step-by-step analysis requirements
- Educational content design and skill development guidance requests
**Specialized capabilities**:
- **Concept Explanation**: Clear breakdowns, practical examples, real-world application demonstration
- **Progressive Learning**: Step-by-step skill building, prerequisite mapping, difficulty progression
- **Educational Examples**: Working code demonstrations, variation exercises, practical implementation
- **Understanding Verification**: Knowledge assessment, skill application, comprehension validation
- **Learning Path Design**: Structured progression, milestone identification, skill development tracking
**Example use cases**:
```bash
/explain complex-algorithm --educational # → Step-by-step learning guide
/teach react-patterns --beginner # → Progressive React tutorial
/mentor junior-developer --focus testing # → Personalized learning guidance
```
---
## Agent Coordination & Integration 🤝
### Automatic Agent Collaboration
Agents often work together automatically. Here are common collaboration patterns:
#### **Multi-Domain Projects**
```bash
/build full-stack-app/
# Auto-coordinates: backend-architect + frontend-architect + system-architect
```
#### **Security-Focused Development**
```bash
/analyze --focus security payment-system/
# Auto-coordinates: security-engineer + backend-architect + performance-engineer
```
#### **Quality Improvement**
```bash
/improve --focus quality legacy-codebase/
# Auto-coordinates: refactoring-expert + quality-engineer + system-architect
```
### Integration with MCP Servers
Each agent leverages specific MCP servers for enhanced capabilities:
- **Context7**: Documentation patterns, framework best practices, compliance standards
- **Sequential**: Complex analysis, systematic problem solving, architectural planning
- **Magic**: UI component generation, design system integration, modern frameworks
- **Playwright**: Cross-browser testing, visual validation, performance testing
- **Morphllm**: Intelligent code transformations, pattern application, optimization
- **Serena**: Memory operations, cross-reference management, symbol-level analysis
### Integration with Commands
Agents seamlessly integrate with SuperClaude's command system:
```bash
# Commands automatically select appropriate agents
/analyze → root-cause-analyst or system-architect (context-dependent)
/build → frontend-architect, backend-architect, or python-expert
/test → quality-engineer with domain-specific coordination
/brainstorm → requirements-analyst for requirements discovery
/document → technical-writer with audience-appropriate formatting
```
## Quick Reference 📋
### Agent Selection Cheat Sheet
| Agent | Best For | Auto-Activates On | Example Use |
|-------|----------|-------------------|-------------|
| 🏗️ system-architect | System design | Architecture, scalability | Large-scale system design |
| ⚙️ backend-architect | Backend systems | APIs, databases, services | Reliable backend systems |
| 🎨 frontend-architect | User interfaces | UI components, accessibility | Accessible web interfaces |
| 🚀 devops-architect | Infrastructure | CI/CD, deployment, monitoring | Deployment automation |
| 🛡️ security-engineer | Security analysis | Security keywords, auth code | Vulnerability assessment |
| ⚡ performance-engineer | Performance tuning | "slow", "bottleneck", profiling | System optimization |
| 🔍 root-cause-analyst | Problem solving | "debug", "investigate", bugs | Complex bug investigation |
| 🧪 quality-engineer | Quality assurance | Testing, validation, QA | Comprehensive test strategy |
| 🔄 refactoring-expert | Code improvement | Refactoring, cleanup, quality | Clean code practices |
| 🐍 python-expert | Python development | .py files, Python frameworks | Production Python APIs |
| 📋 requirements-analyst | Requirements discovery | Ambiguous projects, brainstorming | Project specification |
| ✍️ technical-writer | Documentation | Documentation requests | API documentation |
| 👨‍🏫 learning-guide | Learning & teaching | "explain", "learn", tutorials | Educational content |
### Most Useful Agent Combinations
**Full-Stack Development**:
```bash
# Automatically coordinates backend + frontend + architecture
/build modern-web-app/
```
**Security & Performance Review**:
```bash
# Coordinates security + performance + quality analysis
/analyze --comprehensive production-system/
```
**Learning & Development**:
```bash
# Coordinates learning guide + technical writer + domain expert
/explain complex-system --educational
```
**Project Discovery to Implementation**:
```bash
# Requirements → Architecture → Implementation
/brainstorm "e-commerce platform"
# → Automatic handoff through agent coordination
```
## Best Practices 💡
### Getting Started (The Simple Way)
1. **Just use normal commands** - Agents auto-activate based on your needs
2. **Trust the automation** - SuperClaude usually picks better experts than manual selection
3. **Focus on your work** - Not on managing which agent helps you
4. **Let coordination happen** - Multiple agents work together automatically
### Advanced Usage (When You Want Control)
1. **Manual agent selection** - Use agent names in commands when you want specific expertise
2. **Cross-domain perspectives** - Ask security agents about frontend code for different viewpoints
3. **Learning mode** - Use learning-guide for explanation-focused assistance
4. **Quality focus** - Combine quality-engineer with domain experts for comprehensive quality
### Common Patterns
**For New Projects**:
```bash
/brainstorm "your project idea" # → Requirements discovery
# → Automatic PRD generation and handoff
# → Ready for implementation workflow
```
**For Existing Code**:
```bash
/analyze existing-system/ # → Appropriate domain expert auto-selected
/improve --focus quality code/ # → Quality-focused agent coordination
/secure legacy-application/ # → Security-focused analysis and hardening
```
**For Learning**:
```bash
/explain complex-concept --educational # → Learning guide with domain expert
/document api/ --audience beginner # → Technical writer with appropriate level
```
---
## Final Notes 📝
**The real truth about agents** 💯:
- **Auto-activation works remarkably well** - Usually better than trying to pick experts yourself
- **You can completely ignore agent details** and still get excellent expert assistance
- **Agents exist to help you** - Not to create complexity you need to manage
- **Learning happens naturally** through use, not through studying agent descriptions
**Don't feel overwhelmed by the team** 🧘‍♂️:
- You don't need to know what each agent does
- SuperClaude handles expert selection intelligently
- The detailed descriptions above are for curiosity, not necessity
- Focus on your work - the right experts will show up when needed
**When you might want to know about agents**:
- **Curiosity** - "What would a security expert think about this frontend code?"
- **Learning** - "How would different experts approach this problem?"
- **Specialization** - "I specifically need Python architecture expertise"
- **Quality focus** - "I want comprehensive quality analysis from multiple angles"
**Keep it simple** 🎯:
- Use normal commands like `/analyze some-code/` and `/build my-app/`
- Let the right experts automatically show up
- Agent coordination is available when you want it, not because you need it
- Focus on building great software - we'll handle the expertise coordination
---
## Related Guides
**🚀 Getting Started (Essential)**
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
- [Examples Cookbook](examples-cookbook.md) - See agents in action with real examples
**🛠️ Working with Agents (Recommended)**
- [Commands Guide](commands-guide.md) - Commands that activate specific agents
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How agents work within different modes
- [Session Management Guide](session-management.md) - Agent coordination across sessions
**⚙️ Control and Optimization (Advanced)**
- [Flags Guide](flags-guide.md) - Manual agent control with --agent flags
- [Best Practices Guide](best-practices.md) - Proven patterns for agent coordination
- [Technical Architecture Guide](technical-architecture.md) - Agent system implementation
**🔧 When Things Go Wrong**
- [Troubleshooting Guide](troubleshooting-guide.md) - Agent activation and coordination issues
**📖 Recommended Learning Path:**
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation in action
2. [Commands Guide](commands-guide.md) - Understand agent triggers
3. [Best Practices Guide](best-practices.md) - Master agent coordination patterns
---
*Behind this sophisticated team of 13 specialists, the SuperClaude Framework remains simple to use. Just start coding and the right experts show up when needed! 🚀*

713
Guides/behavioral-modes-guide.md
View File

@ -1,713 +0,0 @@
# SuperClaude Behavioral Modes Guide 🧠
## 💡 The Simple Truth About Modes
**You don't need to understand behavioral modes to use SuperClaude.** They work automatically in the background, adapting how Claude Code behaves based on what you're trying to do.
**Here's what actually happens:**
- Type `/sc:brainstorm "app idea"` → Brainstorming mode kicks in with discovery questions 🤔
- Work on complex debugging → Introspection mode helps with systematic analysis 🔍
- Handle large refactoring → Task Management mode breaks it into coordinated steps 📋
- Need multiple tools → Orchestration mode picks the best ones automatically 🎯
- Context getting full → Token Efficiency mode compresses without losing meaning ⚡
**Think of it like this**: SuperClaude has different "personalities" that automatically show up when they'd be most helpful. You just work normally, and the right approach appears! ✨
---
**TL;DR**: Behavioral modes are SuperClaude's way of being smarter about how it helps you. They activate automatically. You don't manage them, they manage themselves.
---
## 🚀 Just Try These (See Modes in Action)
```bash
# Brainstorming Mode - Interactive discovery
/sc:brainstorm "task management app" # → Gets curious, asks discovery questions
# Introspection Mode - Deep thinking
/sc:troubleshoot "weird auth behavior" # → Analyzes reasoning patterns systematically
# Task Management Mode - Complex coordination
/sc:implement user-dashboard # → Breaks into phases, delegates subtasks
# Orchestration Mode - Smart tool selection
/sc:analyze large-codebase/ # → Picks best tools, coordinates efficiently
# Token Efficiency Mode - Compressed communication
/sc:improve --uc legacy-code/ # → Uses symbols, abbreviations, stays clear
```
**See the pattern?** You just say what you want to do. SuperClaude figures out the best way to help. The modes are the "how" - you focus on the "what". See [Examples Cookbook](examples-cookbook.md) for more working examples. 🎯
---
## The Five Behavioral Modes 🌟
### 🧠 Brainstorming Mode - Interactive Discovery
**What it does**: Turns SuperClaude into a collaborative discovery partner who helps you figure out what you actually want to build.
#### Automatic Activation 🪄
- **Vague requests**: "I want to build something...", "Maybe we could..."
- **Exploration words**: brainstorm, explore, discuss, figure out, not sure
- **Uncertainty**: "possibly", "thinking about", "could we"
- **Manual trigger**: `--brainstorm` or `--bs`
#### How It Changes SuperClaude 🔄
- **Socratic Dialogue**: Asks probing questions instead of jumping to solutions
- **Non-Presumptive**: Doesn't assume what you want, lets you guide discovery
- **Collaborative**: Partners with you rather than directing you
- **Brief Generation**: Turns conversations into structured requirement documents
#### Real Examples 📝
**Standard response:**
```
User: "I want to build a web app"
Claude: "I'll help you build a web application. What framework would you like to use?"
```
**Brainstorming mode:**
```
User: "I want to build a web app"
Claude: "🤔 Let's explore this together! Discovery questions:
- What problem does this solve for your users?
- Who are your target users and what are their main workflows?
- What's your expected user volume and performance needs?
- Any existing systems it needs to integrate with?
- What's your timeline and technical constraints?
📝 Once we explore these, I'll generate a structured brief for implementation!"
```
#### Perfect For 💫
- Early project planning and ideation
- Requirements discovery from vague ideas
- Turning "I need something that does..." into concrete specs
- Preventing scope creep through upfront exploration
---
### 🔍 Introspection Mode - Meta-Cognitive Analysis
**What it does**: Makes SuperClaude consciously analyze its own reasoning and decision-making process, especially when things go wrong or get complex.
#### Automatic Activation 🪄
- **Self-analysis requests**: "analyze my reasoning", "reflect on decision"
- **Error recovery**: When outcomes don't match expectations
- **Complex problems**: Multi-layered issues requiring conscious oversight
- **Pattern recognition**: Recurring behaviors or optimization needs
- **Manual trigger**: `--introspect` or `--introspection`
#### How It Changes SuperClaude 🔄
- **Self-Examination**: Consciously analyzes decision logic and reasoning chains
- **Transparency**: Exposes thinking with markers (🤔, 🎯, ⚡, 📊, 💡)
- **Pattern Detection**: Identifies recurring cognitive patterns and behaviors
- **Learning Focus**: Extracts insights for continuous improvement
#### Real Examples 📝
**Standard response:**
```
User: "The solution didn't work as expected"
Claude: "Let me look at the code and find the issue."
```
**Introspection mode:**
```
User: "The solution didn't work as expected"
Claude: "🎯 Decision Analysis: Expected X → got Y
🔍 Pattern Check: Similar logic errors in auth.js:15, config.js:22
📊 Framework Compliance: Missed validation step from quality gates
🤔 Reasoning: Why did I choose async/await over promises here?
💡 Insight: Need systematic validation before implementation
Let me apply this learning to fix the current issue properly."
```
#### Perfect For 💫
- Debugging complex problems that require meta-thinking
- Understanding why certain approaches were chosen
- Learning from mistakes and improving patterns
- Framework compliance checking and optimization
---
### 📋 Task Management Mode - Orchestration & Delegation
**What it does**: Transforms SuperClaude into a project coordinator that breaks complex work into systematic phases and coordinates multiple sub-tasks efficiently.
#### Automatic Activation 🪄
- **Multi-step operations**: 3+ steps (build, implement, create, fix, refactor)
- **Complex scope**: system-wide, feature-complete, comprehensive changes
- **File thresholds**: >2 directories OR >3 files OR complexity >0.4
- **Quality improvements**: polish, refine, enhance keywords
- **Manual triggers**: `--delegate`, `--loop`, `--concurrency`
#### How It Changes SuperClaude 🔄
- **Orchestration Mindset**: Breaks complex work into coordinated layers
- **Delegation Strategy**: Parallel processing with intelligent sub-task routing
- **State Management**: Single focus protocol with real-time progress tracking
- **Quality Gates**: Evidence-based validation before task completion
- **Progressive Systems**: Systematic enhancement through compound intelligence
#### Real Examples 📝
**Standard response:**
```
User: "I need to refactor this authentication system"
Claude: "I'll refactor the authentication system for you."
```
**Task Management mode:**
```
User: "I need to refactor this authentication system"
Claude: "📋 Detected: system-wide auth refactor → delegation mode activated
🔄 Phase 1: Security Analysis & Dependencies
- Analyze current auth.js, middleware.js, session.js
- Map security vulnerabilities and performance bottlenecks
- Document current API contracts and integrations
🔄 Phase 2: Core Implementation
- Refactor authentication logic with modern patterns
- Update middleware for improved security
- Enhance session management with proper cleanup
🔄 Phase 3: Integration & Validation
- Update all dependent components and routes
- Run comprehensive security and integration tests
- Performance benchmarking and optimization
📊 Progress tracking: Each phase validates before proceeding
✅ Quality gates: Security, performance, compatibility checks"
```
#### Perfect For 💫
- Large refactoring projects that span multiple files
- Feature implementation requiring coordination
- System-wide changes that need careful orchestration
- Complex builds that benefit from parallel processing
---
### 🎯 Orchestration Mode - Intelligent Tool Selection
**What it does**: Optimizes SuperClaude's tool selection and resource usage, automatically choosing the most powerful and efficient approach for each task.
#### Automatic Activation 🪄
- **Multi-tool operations**: Tasks requiring coordination between different tools
- **Performance constraints**: >75% resource usage detected
- **Parallel opportunities**: >3 files or independent operations possible
- **Complex routing**: Multiple valid approaches available
- **Manual trigger**: `--orchestrate`
#### How It Changes SuperClaude 🔄
- **Smart Tool Selection**: Always chooses the most powerful tool for each task type
- **Resource Awareness**: Adapts approach based on system constraints
- **Parallel Thinking**: Identifies independent operations for concurrent execution
- **Efficiency Focus**: Optimizes for speed and effectiveness over familiarity
#### Tool Selection Matrix 🛠️
| Task Type | Best Tool | Alternative | Why Better |
|-----------|-----------|-------------|------------|
| UI components | Magic MCP | Manual coding | Modern patterns, accessibility |
| Deep analysis | Sequential MCP | Native reasoning | Structured multi-step thinking |
| Symbol operations | Serena MCP | Manual search | Semantic understanding |
| Pattern edits | Morphllm MCP | Individual edits | Bulk operations, consistency |
| Documentation | Context7 MCP | Web search | Official patterns, versioned |
| Browser testing | Playwright MCP | Unit tests | Real user interactions |
| Multi-file edits | MultiEdit | Sequential Edits | Atomic operations, rollback |
#### Resource Management Zones 📊
**🟢 Green Zone (0-75%)**
- Full capabilities available
- Use all tools and features
- Normal verbosity and detail
**🟡 Yellow Zone (75-85%)**
- Activate efficiency mode
- Reduce verbosity intelligently
- Defer non-critical operations
**🔴 Red Zone (85%+)**
- Essential operations only
- Minimal output, maximum efficiency
- Fail fast on complex requests
#### Real Examples 📝
**Standard response:**
```
User: "/sc:analyze large-project/"
Claude: "I'll analyze your project files."
[Uses basic file reading and native analysis]
```
**Orchestration mode:**
```
User: "/sc:analyze large-project/"
Claude: "🎯 Orchestration: large-project analysis
📊 Resource Status: 45% → Green Zone
🛠️ Tool Selection Matrix:
- File discovery: Glob (batch patterns)
- Code analysis: Sequential MCP (structured reasoning)
- Documentation: Context7 MCP (framework patterns)
- Parallel execution: 3 concurrent analysis threads
⚡ Executing optimized analysis workflow..."
```
#### Perfect For 💫
- Large codebases requiring efficient analysis
- Performance-critical operations
- Tasks benefiting from parallel processing
- Resource-constrained environments
---
### ⚡ Token Efficiency Mode - Compressed Communication
**What it does**: Transforms SuperClaude's communication style to use symbols, abbreviations, and compressed formats while preserving 95%+ of information quality.
#### Automatic Activation 🪄
- **Context pressure**: >75% context usage or resource constraints
- **Large operations**: Complex analysis workflows needing optimization
- **User requests**: `--uc`, `--ultracompressed` flags
- **Efficiency needs**: When speed and conciseness are priorities
#### How It Changes SuperClaude 🔄
- **Symbol Communication**: Visual symbols for logic, status, and technical domains
- **Abbreviation Systems**: Context-aware compression for technical terms
- **30-50% Compression**: Significant token reduction while preserving meaning
- **Structured Output**: Bullet points, tables, concise explanations
#### Symbol Reference 🔤
**Core Logic & Flow**
- `→` leads to, implies (`auth.js:45 → 🛡️ security risk`)
- `⇒` transforms to (`input ⇒ validated_output`)
- `←` rollback, reverse (`migration ← rollback`)
- `⇄` bidirectional (`sync ⇄ remote`)
- `&` and, combine (`🛡️ security & ⚡ performance`)
- `|` separator, or (`react|vue|angular`)
- `:` define, specify (`scope: file|module`)
- `»` sequence, then (`build » test » deploy`)
- `∴` therefore (`tests ❌ ∴ code broken`)
- `∵` because (`slow ∵ O(n²) algorithm`)
**Status & Progress**
- `✅` completed, passed
- `❌` failed, error
- `⚠️` warning, review needed
- `🔄` in progress
- `⏳` waiting, pending
- `🚨` critical, urgent
**Technical Domains**
- `⚡` Performance (speed, optimization)
- `🔍` Analysis (search, investigation)
- `🔧` Configuration (setup, tools)
- `🛡️` Security (protection, safety)
- `📦` Deployment (package, bundle)
- `🎨` Design (UI, frontend)
- `🏗️` Architecture (system structure)
#### Abbreviation Systems 📝
**System & Architecture**
`cfg` config • `impl` implementation • `arch` architecture • `perf` performance • `ops` operations • `env` environment
**Development Process**
`req` requirements • `deps` dependencies • `val` validation • `test` testing • `docs` documentation • `std` standards
**Quality & Analysis**
`qual` quality • `sec` security • `err` error • `rec` recovery • `sev` severity • `opt` optimization
#### Real Examples 📝
**Standard response:**
```
User: "Analyze the authentication system performance"
Claude: "I'll analyze the authentication system's performance. The user validation function in auth.js line 45 has a security vulnerability. The build process completed successfully, now running tests, then deploying. Performance analysis shows the algorithm is slow because it's O(n²) complexity."
```
**Token Efficiency mode:**
```
User: "Analyze the authentication system performance"
Claude: "⚡ auth.js perf analysis:
🛡️ auth.js:45 → sec risk in user val()
📊 build ✅ » test 🔄 » deploy ⏳
🔍 perf: slow ∵ O(n²) algo
∴ rec: impl O(log n) lookup & fix sec val"
```
#### Perfect For 💫
- Large context situations requiring efficiency
- Complex analysis that would normally be verbose
- Performance-critical operations
- Users who prefer concise, information-dense output
---
## How Modes Work Together 🤝
### Mode Coordination Examples
**Building a New Feature** (Multiple Modes)
```bash
# Starts in Brainstorming Mode
/sc:brainstorm "user dashboard"
# 🧠 Discovery questions about requirements
# Transitions to Task Management Mode
/sc:implement user-dashboard-feature
# 📋 Breaks into coordinated implementation phases
# Orchestration Mode kicks in for complex parts
# 🎯 Chooses best tools for UI (Magic MCP), testing (Playwright MCP)
# Token Efficiency if context gets full
# ⚡ Compresses communication while maintaining quality
```
**Debugging Complex Issues**
```bash
# Starts in Introspection Mode
/sc:troubleshoot "authentication randomly failing"
# 🔍 Systematic analysis of reasoning and patterns
# Orchestration Mode for tool selection
# 🎯 Uses Sequential MCP for structured investigation
# Task Management if solution is complex
# 📋 Coordinates fix across multiple files and systems
```
### Mode Priority System 📊
1. **User-Triggered** (`--brainstorm`, `--uc`, etc.) - Always override automatic
2. **Context-Critical** (Token Efficiency when context >85%) - High priority
3. **Task-Appropriate** (Task Management for 3+ steps) - Standard priority
4. **Enhancement** (Orchestration for optimization) - Background priority
### Mode Switching 🔄
Modes can:
- **Layer together**: Task Management + Orchestration + Token Efficiency
- **Switch dynamically**: Brainstorming → Task Management → Orchestration
- **Enhance each other**: Introspection + Task Management for better quality
---
## Manual Control 🎛️
### Force Specific Modes
```bash
# Force Brainstorming Mode
/sc:analyze --brainstorm project-requirements
# Force Token Efficiency
/sc:implement --uc user-authentication
# Force Task Management
/sc:refactor --delegate large-codebase/
# Force Orchestration
/sc:build --orchestrate complex-project/
# Force Introspection
/sc:troubleshoot --introspect "reasoning issues"
# Disable all modes (baseline Claude)
/sc:analyze --no-modes legacy-code/
```
### When to Use Manual Control 🤔
**Force Brainstorming when:**
- You have specific requirements but want to explore alternatives
- Working with stakeholders who need guided discovery
- Converting existing features into comprehensive specs
**Force Token Efficiency when:**
- Working in resource-constrained environments
- Need maximum information density
- Dealing with very large contexts
**Force Task Management when:**
- Want explicit task breakdown for complex work
- Need to coordinate multiple team members
- Require detailed progress tracking
**Force Orchestration when:**
- Performance is critical
- Want to see tool selection reasoning
- Working with multiple MCP servers
**Force Introspection when:**
- Learning how SuperClaude makes decisions
- Debugging framework behavior
- Want transparent reasoning for auditing
---
## Real-World Scenarios 🌍
### Scenario 1: Building a Task Management App
**Phase 1: Discovery** (Brainstorming Mode)
```bash
/sc:brainstorm "task management app for development teams"
# Mode activates automatically, provides discovery questions:
# - What problems do current tools not solve?
# - How do teams currently track tasks?
# - Integration needs with existing tools?
# - Expected team size and usage patterns?
# Result: Structured requirements brief ready for implementation
```
**Phase 2: Implementation** (Task Management Mode)
```bash
/sc:implement task-management-app --from-brief requirements.md
# Mode activates for complex implementation:
# Phase 1: Data models and API design
# Phase 2: Core functionality and business logic
# Phase 3: UI components and user experience
# Phase 4: Integration, testing, and deployment
# Each phase validates before proceeding
```
**Phase 3: Optimization** (Orchestration + Token Efficiency)
```bash
/sc:improve performance task-management-app/
# Orchestration selects best tools for analysis
# Token Efficiency kicks in for large codebase analysis
# Result: Optimized, production-ready application
```
### Scenario 2: Debugging Authentication Issues
**Investigation** (Introspection Mode)
```bash
/sc:troubleshoot "users can't log in on mobile but desktop works"
# Introspection mode analyzes systematically:
# 🔍 Pattern analysis: Mobile vs desktop differences
# 🤔 Reasoning: What could cause platform-specific auth issues?
# 📊 Evidence gathering: Session handling, cookies, API calls
# 💡 Hypothesis formation and testing approach
```
**Systematic Fix** (Task Management + Orchestration)
```bash
/sc:implement auth-mobile-fix
# Task Management coordinates the fix:
# Phase 1: Mobile session analysis (Playwright MCP for testing)
# Phase 2: API compatibility fixes (Sequential MCP for logic)
# Phase 3: Cross-platform validation (multiple tools)
# Orchestration ensures optimal tool usage throughout
```
### Scenario 3: Large Codebase Refactoring
**Planning** (Brainstorming + Introspection)
```bash
/sc:brainstorm "refactor legacy PHP app to modern architecture"
# Brainstorming explores scope and requirements
# Introspection analyzes current architecture patterns
# Result: Clear migration strategy and requirements
```
**Execution** (Task Management + Token Efficiency)
```bash
/sc:refactor --delegate legacy-app/ --target modern-architecture
# Task Management breaks into systematic phases
# Token Efficiency handles large codebase analysis efficiently
# Phase coordination ensures no breaking changes
```
---
## FAQ 🙋
### Do I need to understand behavioral modes?
**No!** They work automatically. You focus on what you want to do, modes handle how SuperClaude helps you. Think of them like having different experts who automatically step in when needed.
### How do I know which mode is active?
Look for **behavioral markers**:
- 🤔 **Questions and exploration** = Brainstorming Mode
- 🔍 **Reasoning analysis symbols** = Introspection Mode
- 📋 **Phase breakdowns and delegation** = Task Management Mode
- 🎯 **Tool selection matrices** = Orchestration Mode
- ⚡ **Symbols and abbreviations** = Token Efficiency Mode
### Can I disable behavioral modes?
**Yes!** Use `--no-modes` flag:
```bash
/sc:analyze --no-modes simple-file.js
```
This gives you baseline Claude behavior without mode enhancements.
### Which mode should I use manually?
**Usually none!** Automatic activation works well 95% of the time. Manual control is for:
- **Learning**: Force modes to see how they work
- **Special cases**: Unusual requirements or constraints
- **Team coordination**: Explicit task breakdowns for collaboration
- **Performance**: Force efficiency in resource-constrained environments
### Can multiple modes be active at once?
**Yes!** Modes often layer together:
- Task Management + Orchestration (complex projects with optimal tools)
- Introspection + Token Efficiency (deep analysis with compressed output)
- Brainstorming + Task Management (discovery → implementation pipeline)
### Do modes work with all commands?
Most commands work with modes, but some have natural affinities:
- `/sc:brainstorm` → Always Brainstorming Mode
- `/sc:troubleshoot` → Often Introspection Mode
- `/sc:implement` (complex) → Usually Task Management Mode
- Large operations → Often trigger Orchestration Mode
- High context → May activate Token Efficiency Mode
### Are modes related to agents?
**Yes, but differently!**
- **Agents** = Who helps (security-engineer, frontend-architect, etc.)
- **Modes** = How they help (systematically, efficiently, collaboratively)
Modes determine the behavioral approach, agents provide domain expertise. A security-engineer might work in Task Management mode for complex security implementations, or Introspection mode for security analysis.
---
## Technical Reference 🔧
### Complete Trigger Lists
**Brainstorming Mode Triggers**
- **Keywords**: brainstorm, explore, discuss, figure out, not sure, maybe, possibly, thinking about, could we
- **Phrases**: "I want to build...", "thinking about creating...", "not sure how to...", "maybe we could..."
- **Context**: Vague requirements, early planning, stakeholder discussions
- **Manual**: `--brainstorm`, `--bs`
**Introspection Mode Triggers**
- **Keywords**: analyze reasoning, reflect on, why did, decision logic, pattern check
- **Context**: Error recovery, unexpected results, complex problem solving, framework discussions
- **Indicators**: Multiple failed approaches, recurring issues, need for meta-analysis
- **Manual**: `--introspect`, `--introspection`
**Task Management Mode Triggers**
- **Operations**: build, implement, create, fix, refactor (3+ steps)
- **Scope**: system, feature, comprehensive, complete, end-to-end
- **Thresholds**: >2 directories OR >3 files OR complexity score >0.4
- **Keywords**: polish, refine, enhance, coordinate, manage
- **Manual**: `--delegate`, `--loop`, `--concurrency`
**Orchestration Mode Triggers**
- **Conditions**: Multi-tool operations, >3 files, parallel opportunities
- **Performance**: >75% resource usage, efficiency requirements
- **Complexity**: Multiple valid approaches, tool selection decisions
- **Manual**: `--orchestrate`
**Token Efficiency Mode Triggers**
- **Resource**: Context >75%, large-scale operations, memory constraints
- **User requests**: `--uc`, `--ultracompressed`, brevity requirements
- **Workflow**: Complex analysis needing optimization, high information density
- **Manual**: `--uc`, `--ultracompressed`, `--token-efficient`
### Flag Reference Table 🏳️
| Flag | Mode | Purpose | Usage |
|------|------|---------|-------|
| `--brainstorm`, `--bs` | Brainstorming | Force discovery mode | Requirements exploration |
| `--introspect` | Introspection | Force reasoning analysis | Decision transparency |
| `--delegate` | Task Management | Force delegation mode | Complex coordination |
| `--delegate` | Task Management | Enable delegation mode | Parallel processing |
| `--loop` | Task Management | Enable iteration cycles | Improvement workflows |
| `--orchestrate` | Orchestration | Force tool optimization | Performance priority |
| `--uc`, `--ultracompressed` | Token Efficiency | Force compression | Resource constraints |
| `--no-modes` | None | Disable all modes | Baseline behavior |
### Integration with Framework Components
**With Agents** 🤖
- Modes determine **how** agents work
- Agents provide **domain expertise**
- Example: security-engineer in Task Management mode = systematic security implementation
**With Commands** 🛠️
- Commands trigger mode activation
- Modes enhance command execution
- Example: `/sc:implement` complex features → Task Management mode activation
**With MCP Servers** 🔧
- Orchestration mode optimizes MCP usage
- Task Management coordinates multi-MCP operations
- Token Efficiency compresses MCP communications
### Performance Metrics 📊
**Mode Efficiency Gains**
- **Brainstorming**: 60-80% better requirement clarity
- **Introspection**: 40-60% improved decision quality
- **Task Management**: 40-70% time savings via delegation
- **Orchestration**: 20-40% performance improvement via optimal tools
- **Token Efficiency**: 30-50% token reduction with 95%+ information preservation
**Resource Impact**
- Brainstorming: Low overhead, high value for unclear requirements
- Introspection: Medium overhead, high value for complex problems
- Task Management: Variable overhead, scales with task complexity
- Orchestration: Low overhead, improves overall efficiency
- Token Efficiency: Negative overhead (saves resources), maintains quality
---
*Behavioral modes are SuperClaude's intelligence system - they make Claude Code smarter about how it helps you. You don't manage them, they manage themselves to give you the best experience! 🧠✨*
---
## Related Guides
**🚀 Getting Started (Essential)**
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
- [Examples Cookbook](examples-cookbook.md) - See modes in action with real examples
**🛠️ Working with Modes (Recommended)**
- [Commands Guide](commands-guide.md) - Commands that trigger different modes
- [Agents Guide](agents-guide.md) - How agents work within different modes
- [Session Management Guide](session-management.md) - Mode persistence across sessions
**⚙️ Control and Optimization (Advanced)**
- [Flags Guide](flags-guide.md) - Manual mode control with flags like --brainstorm, --uc
- [Best Practices Guide](best-practices.md) - Proven patterns for mode utilization
- [Technical Architecture Guide](technical-architecture.md) - Mode detection and activation system
**🔧 When Modes Don't Work as Expected**
- [Troubleshooting Guide](troubleshooting-guide.md) - Mode activation and behavioral issues
**📖 Recommended Learning Path:**
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation in practice
2. [Commands Guide](commands-guide.md) - Understand mode triggers
3. [Best Practices Guide](best-practices.md) - Master mode coordination patterns

945
Guides/best-practices.md
View File

@ -1,945 +0,0 @@
# SuperClaude Best Practices Guide
*A comprehensive guide to maximizing your effectiveness with SuperClaude through proven patterns and optimization strategies*
## Table of Contents
1. [Getting Started Right](#getting-started-right)
2. [Command Mastery](#command-mastery)
3. [Flag Optimization](#flag-optimization)
4. [Agent Coordination](#agent-coordination)
5. [MCP Server Strategy](#mcp-server-strategy)
6. [Workflow Patterns](#workflow-patterns)
7. [Performance Optimization](#performance-optimization)
8. [Quality & Safety](#quality--safety)
9. [Advanced Patterns](#advanced-patterns)
10. [Learning & Growth](#learning--growth)
---
## Getting Started Right
### The SuperClaude Mindset
**Core Principle**: SuperClaude is designed to handle complexity for you. Focus on expressing your intent clearly, and let the system optimize execution. For working examples of these principles, see [Examples Cookbook](examples-cookbook.md).
**✅ DO**: Trust the intelligent routing system
- Just type `/analyze auth.js` - SuperClaude picks appropriate tools
- Use basic commands first, learn advanced features gradually
- Let behavioral modes activate automatically
**❌ DON'T**: Try to micromanage every detail
- Don't memorize all flags and agents upfront
- Don't specify tools unless you need to override defaults
- Don't overcomplicate simple tasks
### Essential First Session Pattern
```bash
# The proven startup sequence
/sc:load # Initialize session with project context
/sc:analyze . # Understand project structure and patterns
/sc:brainstorm "goals" # Interactive discovery for unclear requirements
/sc:implement feature # Development with auto-optimization
/sc:save # Persist session insights
```
**Why this works**: Establishes persistent context, gathers intelligence, enables cross-session learning.
### Foundation Practices
**Session Initialization**
```bash
# Always start sessions properly
/sc:load --deep # Deep project understanding
/sc:load --summary # Quick context for familiar projects
```
**Evidence-Based Development**
```bash
# Validate before building
/sc:analyze existing-code # Understand patterns first
/sc:test --coverage # Verify current state
/sc:implement feature # Build on solid foundation
/sc:test feature # Validate implementation
```
**Progressive Enhancement**
```bash
# Start simple, add complexity intelligently
/sc:build # Basic implementation
/sc:improve --performance # Targeted optimization
/sc:test --comprehensive # Full validation
```
---
## Command Mastery
### Essential Command Patterns
**Analysis Commands** - Understanding before action
```bash
/sc:analyze path --focus domain # Targeted analysis
/sc:explain complex-code.js # Educational breakdown
/sc:troubleshoot "specific issue" # Problem investigation
```
**Development Commands** - Building with intelligence
```bash
/sc:implement feature-name # Smart feature creation
/sc:build --optimize # Optimized builds
/sc:design component --type ui # Architecture/UI design
```
**Quality Commands** - Maintaining excellence
```bash
/sc:improve legacy-code/ # Systematic improvement
/sc:cleanup technical-debt/ # Targeted cleanup
/sc:test --with-coverage # Quality validation
```
### Command Combination Strategies
**Analysis → Implementation Pattern**
```bash
/sc:analyze auth/ --focus security # Understand security landscape
/sc:implement user-auth --secure # Build with security insights
/sc:test auth --security # Validate security implementation
```
**Brainstorm → Design → Implement Pattern**
```bash
/sc:brainstorm "user dashboard" # Requirements discovery
/sc:design dashboard --type component # Architecture planning
/sc:implement dashboard # Informed implementation
```
**Load → Analyze → Improve Pattern**
```bash
/sc:load --deep # Establish context
/sc:analyze . --focus quality # Identify improvement areas
/sc:improve problematic-areas/ # Systematic enhancement
```
### Command Selection Matrix
| Task Type | Primary Command | Secondary Commands | Expected Outcome |
|-----------|----------------|-------------------|------------------|
| **New Feature** | `/sc:implement` | `/sc:design`, `/sc:test` | Complete working feature |
| **Code Issues** | `/sc:troubleshoot` | `/sc:analyze`, `/sc:improve` | Root cause + solution |
| **Quality Problems** | `/sc:improve` | `/sc:cleanup`, `/sc:test` | Enhanced code quality |
| **Architecture Review** | `/sc:analyze --focus architecture` | `/sc:reflect`, `/sc:document` | System understanding |
| **Unclear Requirements** | `/sc:brainstorm` | `/sc:estimate`, `/sc:task` | Clear specifications |
---
## Flag Optimization
### Flag Selection Strategy
**Core Principle**: Flags should enhance, not complicate. Most flags activate automatically - use manual flags only for overrides or specific needs.
### High-Impact Flag Combinations
**Deep Analysis Pattern**
```bash
/sc:analyze codebase/ --think-hard --focus architecture --validate
# Triggers: Sequential MCP + Context7 + Architecture agent + validation gates
# Result: Comprehensive system analysis with safety checks
```
**Performance Optimization Pattern**
```bash
/sc:improve app/ --focus performance --loop --iterations 3
# Triggers: Performance engineer + iterative improvement cycles
# Result: Systematically optimized performance with measurement
```
**Security Assessment Pattern**
```bash
/sc:analyze auth/ --focus security --ultrathink --safe-mode
# Triggers: Security engineer + Sequential MCP + maximum validation
# Result: Comprehensive security analysis with conservative execution
```
### Flag Efficiency Rules
**Flag Priority Hierarchy**
1. **Safety flags** (`--safe-mode`, `--validate`) - Always take precedence
2. **Scope flags** (`--scope project`) - Define boundaries first
3. **Focus flags** (`--focus security`) - Target expertise second
4. **Optimization flags** (`--loop`, `--uc`) - Enhance performance last
**Automatic vs Manual Flags**
- **Let auto-activate**: `--brainstorm`, `--introspect`, `--orchestrate`
- **Manually specify**: `--focus`, `--scope`, `--think-hard`
- **Rarely needed**: `--concurrency`, `--iterations`
### Flag Combination Templates
**For Complex Debugging**
```bash
/sc:troubleshoot issue --think-hard --focus root-cause --validate
```
**For Large Codebase Analysis**
```bash
/sc:analyze . --delegate auto --scope project --uc
```
**For Production Changes**
```bash
/sc:implement feature --safe-mode --validate --with-tests
```
---
## Agent Coordination
### Understanding Agent Auto-Activation
**How Agent Selection Works**
1. **Request Analysis**: SuperClaude analyzes your request for domain keywords
2. **Context Evaluation**: Considers project type, files involved, previous session history
3. **Agent Matching**: Activates appropriate specialist based on expertise mapping
4. **Multi-Agent Coordination**: Enables multiple agents for cross-domain issues
### Strategic Agent Usage
**Single-Domain Tasks** - Let auto-activation work
```bash
/sc:analyze auth.js # → Security Engineer
/sc:implement responsive-navbar # → Frontend Architect
/sc:troubleshoot performance-issue # → Performance Engineer
```
**Multi-Domain Tasks** - Strategic combinations
```bash
/sc:implement payment-system # → Backend + Security + Quality Engineers
/sc:analyze system-architecture # → System + Performance + Security Architects
/sc:improve legacy-application # → Quality + Refactoring + System experts
```
### Agent Coordination Patterns
**Security-First Development**
```bash
/sc:analyze codebase --focus security # Security Engineer analyzes
/sc:implement auth --secure # Security Engineer oversees implementation
/sc:test auth --security # Security + Quality Engineers validate
```
**Performance-Driven Optimization**
```bash
/sc:analyze performance-bottlenecks # Performance Engineer identifies issues
/sc:improve slow-components # Performance + Quality Engineers optimize
/sc:test performance --benchmarks # Performance Engineer validates improvements
```
**Architecture Evolution**
```bash
/sc:analyze current-architecture # System Architect reviews existing design
/sc:design new-architecture # System + Domain Architects collaborate
/sc:implement migration-plan # Multiple specialists coordinate transition
```
### Agent Specialization Matrix
| Domain | Primary Agent | Supporting Agents | Best Commands |
|--------|---------------|------------------|---------------|
| **Security** | Security Engineer | Quality Engineer, Root Cause Analyst | `/sc:analyze --focus security` |
| **Performance** | Performance Engineer | System Architect, Quality Engineer | `/sc:improve --focus performance` |
| **Frontend** | Frontend Architect | Quality Engineer, Learning Guide | `/sc:design --type component` |
| **Backend** | Backend Architect | Security Engineer, Performance Engineer | `/sc:implement --type api` |
| **Architecture** | System Architect | Performance Engineer, Security Engineer | `/sc:analyze --focus architecture` |
| **Quality** | Quality Engineer | Refactoring Expert, Root Cause Analyst | `/sc:improve --with-tests` |
---
## MCP Server Strategy
### MCP Server Selection Matrix
**Choose MCP servers based on task complexity and domain requirements**
| Task Type | Recommended MCP | Alternative | Trigger Conditions |
|-----------|----------------|-------------|-------------------|
| **UI Components** | Magic | Manual coding | UI keywords, React/Vue mentions |
| **Complex Analysis** | Sequential | Native reasoning | >3 components, architectural questions |
| **Documentation Lookup** | Context7 | Web search | Import statements, framework questions |
| **Code Editing** | Morphllm | Individual edits | >3 files, pattern-based changes |
| **Symbol Operations** | Serena | Manual search | Refactoring, large codebase navigation |
| **Browser Testing** | Playwright | Unit tests | E2E scenarios, visual validation |
### High-Performance MCP Combinations
**Frontend Development Stack**
```bash
# Magic + Context7 + Sequential
/sc:implement dashboard component --magic --c7 --seq
# Magic generates UI → Context7 provides framework patterns → Sequential coordinates
```
**Backend Analysis Stack**
```bash
# Sequential + Context7 + Serena
/sc:analyze api-architecture --seq --c7 --serena
# Sequential structures analysis → Context7 provides docs → Serena maps dependencies
```
**Quality Improvement Stack**
```bash
# Morphllm + Serena + Sequential
/sc:improve legacy-codebase --morph --serena --seq
# Sequential plans improvements → Serena maps symbols → Morphllm applies changes
```
### MCP Optimization Strategies
**Token Efficiency with MCP**
- Use `--uc` flag with complex MCP operations
- Sequential + Morphllm combination provides compressed analysis
- Magic components reduce UI implementation tokens significantly
**Parallel MCP Processing**
```bash
# Enable concurrent MCP server usage
/sc:analyze frontend/ --magic --c7 --concurrency 5
```
**MCP Server Resource Management**
```bash
# Conservative MCP usage for production
/sc:implement feature --safe-mode --validate
# Auto-enables appropriate MCP servers with safety constraints
```
### When NOT to Use MCP Servers
**Simple tasks that don't benefit from external tools:**
- Basic explanations: "explain this function"
- Single file edits: "fix this typo"
- General questions: "what is React?"
- Quick analysis: "is this code correct?"
**Use `--no-mcp` flag when:**
- Performance is critical and you need fastest response
- Working in air-gapped environments
- Simple tasks where MCP overhead isn't justified
- Debugging MCP-related issues
---
## Workflow Patterns
### The Universal SuperClaude Workflow
**Phase 1: Context Establishment**
```bash
/sc:load --deep # Initialize project understanding
/sc:analyze . --scope project # Map current state
```
**Phase 2: Requirement Clarification**
```bash
/sc:brainstorm "unclear requirements" # Interactive discovery
/sc:estimate task-scope # Resource planning
```
**Phase 3: Implementation**
```bash
/sc:implement features # Development with auto-optimization
/sc:test implementation # Quality validation
```
**Phase 4: Iteration & Persistence**
```bash
/sc:improve --loop # Continuous enhancement
/sc:save --checkpoint # Preserve insights
```
### Domain-Specific Workflows
**New Project Setup**
```bash
/sc:load --deep # Understand project structure
/sc:analyze . --focus architecture # Map existing patterns
/sc:brainstorm "development goals" # Clarify objectives
/sc:task "setup development env" # Plan setup tasks
/sc:build --optimize # Establish build pipeline
/sc:document --type guide "setup" # Create setup documentation
/sc:save # Preserve project insights
```
**Feature Development**
```bash
/sc:load # Load project context
/sc:brainstorm "feature idea" # Requirements discovery
/sc:design feature --type component # Architecture planning
/sc:implement feature # Development with validation
/sc:test feature --comprehensive # Quality assurance
/sc:improve feature --performance # Optimization
/sc:document feature # Documentation
/sc:save --checkpoint # Save session state
```
**Bug Investigation & Resolution**
```bash
/sc:load --summary # Quick context loading
/sc:troubleshoot "bug description" # Root cause analysis
/sc:analyze affected-areas # Impact assessment
/sc:implement fix --validate # Safe fix implementation
/sc:test fix --comprehensive # Comprehensive validation
/sc:reflect --type completion # Verify resolution
/sc:save # Persist insights
```
**Code Quality Improvement**
```bash
/sc:load # Establish context
/sc:analyze . --focus quality # Identify quality issues
/sc:improve problem-areas/ # Systematic improvements
/sc:cleanup technical-debt/ # Debt reduction
/sc:test --coverage # Validation with coverage
/sc:reflect --type quality # Quality assessment
/sc:save # Preserve improvements
```
### Workflow Optimization Principles
**Parallelization Opportunities**
```bash
# Parallel analysis
/sc:analyze frontend/ & # Background frontend analysis
/sc:analyze backend/ & # Background backend analysis
/sc:analyze tests/ & # Background test analysis
wait && /sc:reflect --type summary # Consolidate findings
```
**Checkpoint Strategy**
- **Every 30 minutes**: `/sc:save --checkpoint`
- **Before risky operations**: `/sc:save --backup`
- **After major completions**: `/sc:save --milestone`
- **End of sessions**: `/sc:save --final`
**Context Preservation**
```bash
# Start of each session
/sc:load --recent # Load recent context
/sc:reflect --type session-start # Understand current state
# End of each session
/sc:reflect --type completion # Assess achievements
/sc:save --insights # Preserve learnings
```
---
## Performance Optimization
### Token Efficiency Strategies
**Automatic Token Optimization**
SuperClaude automatically enables token efficiency when:
- Context usage >75%
- Large-scale operations (>50 files)
- Complex multi-step workflows
**Manual Token Optimization**
```bash
/sc:analyze large-codebase --uc # Ultra-compressed analysis
/sc:implement complex-feature --token-efficient # Compressed implementation
```
**Symbol Communication Patterns**
When token efficiency mode activates, expect:
- `✅ ❌ ⚠️` for status indicators
- `→ ⇒ ⇄` for logic flow
- `🔍 🔧 ⚡ 🛡️` for domain indicators
- Abbreviated technical terms: `cfg`, `impl`, `perf`, `arch`
### Execution Speed Optimization
**Parallel Processing Templates**
```bash
# Multiple file analysis
/sc:analyze src/ tests/ docs/ --concurrency 8
# Batch operations
/sc:improve file1.js file2.js file3.js --batch
# Delegated processing for large projects
/sc:analyze . --delegate auto --scope project
```
**Resource-Aware Processing**
```bash
# Conservative resource usage
/sc:build --safe-mode # Auto-limits resource usage
# Controlled concurrency
/sc:test --concurrency 3 # Explicit concurrency limits
# Priority-based processing
/sc:improve critical/ --priority high
```
### Memory and Context Optimization
**Session Context Management**
```bash
# Lightweight context for familiar projects
/sc:load --summary
# Deep context for complex projects
/sc:load --deep
# Context compression for large projects
/sc:load --uc
```
**Progressive Context Building**
```bash
# Start minimal, build context progressively
/sc:load --minimal # Basic project loading
/sc:analyze core-areas # Focus on essential components
/sc:load --expand critical-paths # Expand context as needed
```
### Performance Measurement
**Built-in Performance Tracking**
```bash
# Commands automatically track performance metrics:
/sc:analyze . --performance-metrics
/sc:build --timing
/sc:test --benchmark
```
**Performance Validation Patterns**
```bash
# Before optimization
/sc:analyze performance-bottlenecks --baseline
# After optimization
/sc:test performance --compare-baseline
# Continuous monitoring
/sc:reflect --type performance --trend
```
---
## Quality & Safety
### Safety-First Development
**Core Safety Principles**
1. **Validate before execution** - Always run analysis before changes
2. **Incremental changes** - Small, verifiable steps over large changes
3. **Rollback capability** - Maintain ability to undo changes
4. **Evidence-based decisions** - All claims must be verifiable
**Critical Safety Patterns**
```bash
# Always check git status first
git status && git branch
# Read before any file operations
/sc:analyze file.js # Understand before changing
# Use safe mode for production changes
/sc:implement feature --safe-mode
# Create checkpoints before risky operations
/sc:save --backup && /sc:implement risky-change
```
### Quality Assurance Patterns
**Quality Gates Framework**
```bash
# Analysis quality gate
/sc:analyze code --validate # Validates analysis accuracy
# Implementation quality gate
/sc:implement feature --with-tests # Includes quality validation
# Deployment quality gate
/sc:build --quality-check # Pre-deployment validation
```
**Comprehensive Testing Strategy**
```bash
# Unit testing
/sc:test components/ --unit
# Integration testing
/sc:test api/ --integration
# E2E testing (triggers Playwright MCP)
/sc:test user-flows/ --e2e
# Security testing
/sc:test auth/ --security
# Performance testing
/sc:test critical-paths/ --performance
```
### Error Prevention & Recovery
**Proactive Error Prevention**
```bash
# Validate before risky operations
/sc:analyze risky-area --focus safety --validate
# Use conservative execution for critical systems
/sc:implement critical-feature --safe-mode --validate
# Enable comprehensive testing
/sc:test critical-feature --comprehensive --security
```
**Error Recovery Patterns**
```bash
# Systematic debugging approach
/sc:troubleshoot error --think-hard --root-cause
# Multi-perspective analysis
/sc:analyze error-context --focus debugging --ultrathink
# Validated fix implementation
/sc:implement fix --validate --with-tests --safe-mode
```
### Code Quality Standards
**Quality Enforcement Rules**
- **No partial features** - Complete everything you start
- **No TODO comments** - Finish implementations, don't leave placeholders
- **No mock implementations** - Build real, working code
- **Evidence-based claims** - All technical statements must be verifiable
**Quality Validation Commands**
```bash
# Code quality assessment
/sc:analyze . --focus quality --comprehensive
# Technical debt identification
/sc:analyze . --focus debt --report
# Quality improvement planning
/sc:improve low-quality-areas/ --plan
# Quality trend analysis
/sc:reflect --type quality --trend
```
---
## Advanced Patterns
### Multi-Layer Orchestration
**Complex Project Coordination**
```bash
# Enable advanced orchestration for large projects
/sc:task "modernize legacy system" --orchestrate --delegate auto
# Multi-agent coordination for cross-domain problems
/sc:implement payment-system --all-mcp --think-hard --safe-mode
# Systematic refactoring with multiple specialists
/sc:improve legacy-codebase/ --delegate folders --loop --iterations 5
```
**Resource-Constrained Optimization**
```bash
# Maximum efficiency for large operations
/sc:analyze enterprise-codebase --uc --delegate auto --concurrency 15
# Token-optimized multi-step workflows
/sc:task complex-migration --token-efficient --orchestrate
# Performance-optimized batch processing
/sc:improve multiple-modules/ --batch --performance-mode
```
### Session Lifecycle Mastery
**Advanced Session Management**
```bash
# Intelligent session initialization
/sc:load --adaptive # Adapts loading strategy to project complexity
# Cross-session learning
/sc:reflect --type learning # Extract insights for future sessions
# Session comparison and evolution
/sc:reflect --type evolution --compare-previous
# Advanced checkpointing
/sc:save --milestone "major feature complete" --analytics
```
**Session Intelligence Patterns**
```bash
# Context-aware session resumption
/sc:load --context-aware # Resumes with intelligent context
# Predictive session planning
/sc:task session-goals --predict-resources --estimate-time
# Session optimization recommendations
/sc:reflect --type optimization --recommendations
```
### Expert-Level Command Combinations
**Architecture Evolution Workflow**
```bash
/sc:load --deep
/sc:analyze current-architecture --ultrathink --focus architecture
/sc:design target-architecture --think-hard --validate
/sc:task migration-plan --orchestrate --delegate auto
/sc:implement migration --safe-mode --validate --loop
/sc:test migration --comprehensive --performance
/sc:reflect --type architecture --evolution
/sc:save --milestone "architecture evolved"
```
**Security Hardening Workflow**
```bash
/sc:load --security-focused
/sc:analyze . --focus security --ultrathink --all-mcp
/sc:troubleshoot security-vulnerabilities --think-hard --root-cause
/sc:implement security-fixes --safe-mode --validate --with-tests
/sc:test security/ --security --comprehensive --e2e
/sc:reflect --type security --assessment
/sc:save --security-audit-complete
```
**Performance Optimization Workflow**
```bash
/sc:load --performance-focused
/sc:analyze performance-bottlenecks --focus performance --think-hard
/sc:implement optimizations --validate --loop --iterations 3
/sc:test performance --benchmark --compare-baseline
/sc:reflect --type performance --improvement-metrics
/sc:save --performance-optimized
```
### Custom Workflow Development
**Creating Repeatable Patterns**
```bash
# Define custom workflow templates
/sc:task "define code-review workflow" --template
# Parameterized workflow execution
/sc:execute code-review-workflow --target auth/ --depth comprehensive
# Workflow optimization and refinement
/sc:improve workflow-template --based-on results
```
---
## Learning & Growth
### Progressive Learning Strategy
**Phase 1: Foundation (Weeks 1-2)**
- Master basic commands: `/sc:load`, `/sc:analyze`, `/sc:implement`, `/sc:save`
- Trust auto-activation - don't manually manage flags and agents
- Establish consistent session patterns
- Focus on quality workflows over advanced features
**Phase 2: Specialization (Weeks 3-6)**
- Experiment with domain-specific commands for your primary work
- Learn flag combinations that enhance your specific workflows
- Understand when different agents activate and why
- Develop personal workflow templates
**Phase 3: Optimization (Weeks 7-12)**
- Master advanced flag combinations for complex scenarios
- Leverage MCP servers for specialized tasks
- Develop multi-session workflows with persistent context
- Create custom orchestration patterns
**Phase 4: Expertise (Months 4+)**
- Design sophisticated multi-agent coordination workflows
- Optimize for token efficiency and performance at scale
- Mentor others using proven patterns you've developed
- Contribute workflow innovations back to the community
### Learning Acceleration Techniques
**Experimentation Framework**
```bash
# Try unfamiliar commands in safe environments
/sc:analyze sample-project --think-hard # Observe how deep analysis works
/sc:brainstorm "imaginary project" # See requirements discovery in action
/sc:reflect --type learning # Review what you learned
```
**Pattern Recognition Development**
- **Notice auto-activations**: Pay attention to which agents and flags activate automatically
- **Compare approaches**: Try the same task with different commands/flags
- **Measure outcomes**: Use reflection commands to assess effectiveness
- **Document discoveries**: Save insights about what works best for your projects
**Knowledge Reinforcement Patterns**
```bash
# Weekly learning review
/sc:reflect --type learning --timeframe week
# Monthly skill assessment
/sc:reflect --type skills --improvement-areas
# Quarterly workflow optimization
/sc:reflect --type workflows --optimization-opportunities
```
### Building Expertise
**Advanced Skill Development Areas**
**1. Agent Coordination Mastery**
- Learn to predict which agents will activate for different requests
- Understand cross-domain collaboration patterns
- Develop skills in manual agent coordination for edge cases
**2. MCP Server Optimization**
- Master the decision matrix for when to use each MCP server
- Learn optimal MCP combinations for complex workflows
- Understand performance implications of different MCP strategies
**3. Performance Engineering**
- Develop intuition for token efficiency opportunities
- Master parallel processing and resource optimization
- Learn to balance quality vs. speed based on context
**4. Quality Assurance Excellence**
- Internalize quality gate patterns for different project types
- Develop systematic testing strategies using SuperClaude
- Master error prevention and recovery patterns
### Continuous Improvement Framework
**Self-Assessment Questions**
- Which SuperClaude patterns save you the most time?
- What types of problems do you still solve manually that could be automated?
- How has your code quality improved since using SuperClaude systematically?
- Which advanced features haven't you explored yet that might benefit your work?
**Measurement Strategies**
```bash
# Track productivity improvements
/sc:reflect --type productivity --baseline vs-current
# Assess code quality trends
/sc:reflect --type quality --trend-analysis
# Measure learning velocity
/sc:reflect --type learning --skill-development
```
**Community Engagement**
- Share effective workflow patterns you discover
- Learn from others' optimization strategies
- Contribute to SuperClaude documentation improvements
- Mentor newcomers using proven teaching patterns
---
## Quick Reference
### Essential Commands Cheat Sheet
```bash
# Session Management
/sc:load # Initialize session context
/sc:save # Persist session insights
/sc:reflect # Review session outcomes
# Core Development
/sc:analyze path # Intelligent analysis
/sc:implement feature # Smart implementation
/sc:improve code # Systematic enhancement
/sc:test target # Comprehensive testing
# Problem Solving
/sc:brainstorm topic # Requirements discovery
/sc:troubleshoot issue # Root cause analysis
/sc:explain concept # Educational breakdown
```
### High-Impact Flag Combinations
```bash
--think-hard --focus domain --validate # Deep domain analysis with safety
--safe-mode --with-tests --quality-check # Production-ready implementation
--uc --orchestrate --delegate auto # Large-scale efficient processing
--loop --iterations 3 --performance # Iterative optimization cycles
```
### Emergency Troubleshooting
```bash
# When things go wrong
/sc:troubleshoot issue --ultrathink --safe-mode --root-cause
# When performance is critical
/sc:analyze problem --uc --no-mcp --focus performance
# When you need maximum safety
/sc:implement fix --safe-mode --validate --with-tests --quality-check
```
---
## Conclusion
SuperClaude's power lies in its intelligent automation of complex development workflows. The key to mastery is:
1. **Trust the automation** - Let SuperClaude handle complexity while you focus on intent
2. **Start simple** - Master basic patterns before exploring advanced features
3. **Learn progressively** - Add sophistication as your understanding deepens
4. **Measure outcomes** - Use reflection to validate that your patterns actually improve results
5. **Stay curious** - Experiment with new approaches and contribute discoveries back to the community
Remember: These best practices emerge from real usage. The most valuable patterns are often discovered through experimentation and adapted to your specific context. Use this guide as a foundation, but don't hesitate to develop your own optimized workflows based on your unique needs and discoveries.
**Start with the essentials, trust the intelligence, and let your expertise emerge through practice.**
## Related Guides
**🚀 Foundation (Essential Before Best Practices)**
- [Installation Guide](installation-guide.md) - Get SuperClaude set up properly
- [SuperClaude User Guide](superclaude-user-guide.md) - Understanding the framework philosophy
- [Examples Cookbook](examples-cookbook.md) - Working examples to practice with
**📚 Core Knowledge (Apply These Practices)**
- [Commands Guide](commands-guide.md) - All 21 commands with optimization opportunities
- [Session Management Guide](session-management.md) - Session lifecycle mastery
- [Agents Guide](agents-guide.md) - Agent coordination best practices
**⚙️ Advanced Optimization (Power User Techniques)**
- [Flags Guide](flags-guide.md) - Advanced flag combinations and control
- [Behavioral Modes Guide](behavioral-modes-guide.md) - Mode coordination patterns
- [Technical Architecture Guide](technical-architecture.md) - System understanding for optimization
**🔧 Quality and Safety (Prevention Strategies)**
- [Troubleshooting Guide](troubleshooting-guide.md) - Prevention patterns and issue avoidance
**📖 How to Use This Guide:**
1. Start with [Getting Started Right](#getting-started-right) for foundational patterns
2. Apply [Command Mastery](#command-mastery) to your daily workflow
3. Use [Workflow Patterns](#workflow-patterns) for specific development scenarios
4. Graduate to [Advanced Patterns](#advanced-patterns) for complex projects
**🎯 Implementation Strategy:**
- **Week 1-2**: Focus on [Getting Started Right](#getting-started-right) and basic [Command Mastery](#command-mastery)
- **Week 3-4**: Implement [Workflow Patterns](#workflow-patterns) for your common tasks
- **Month 2**: Explore [Agent Coordination](#agent-coordination) and [MCP Server Strategy](#mcp-server-strategy)
- **Month 3+**: Master [Advanced Patterns](#advanced-patterns) and [Performance Optimization](#performance-optimization)

1041
Guides/commands-guide.md
View File

File diff suppressed because it is too large Load Diff

808
Guides/examples-cookbook.md
View File

@ -1,808 +0,0 @@
# SuperClaude Examples Cookbook 🍳
*A practical guide to real-world SuperClaude usage with hands-on examples*
## How to Use This Cookbook
This cookbook is your **practical reference** for using SuperClaude effectively. Unlike comprehensive guides, this focuses entirely on **working examples** and **real scenarios** you can try immediately.
**Structure:**
- **Quick Examples** - One-liner commands for common tasks
- **Development Scenarios** - Complete workflows for typical development situations
- **Troubleshooting Scenarios** - Real problem-solving examples
- **Advanced Patterns** - Complex multi-step workflows
- **Command Combinations** - Effective flag and agent combinations
- **Best Practices in Action** - Examples showing optimal SuperClaude usage
**How to read this:**
- 📋 **Copy-paste commands** - All examples are working commands you can use
- 🎯 **Expected outcomes** - What you should see after running each command
- 💡 **Why it works** - Brief explanation of the approach
- ⚠️ **Gotchas** - Common issues and how to avoid them
---
## Quick Examples - Just Try These! 🚀
### Essential One-Liners
```bash
# Initialize and understand your project
/sc:load # Load project context
/sc:analyze . # Analyze entire project
/sc:build # Smart build with auto-optimization
# Development workflows
/sc:implement user-auth # Create authentication system
/sc:improve messy-file.js # Clean up code automatically
/sc:troubleshoot "login not working" # Debug specific issues
# Session management
/sc:save --checkpoint # Save progress with analysis
/sc:reflect --type completion # Validate task completion
```
### Quick Analysis Commands
```bash
# Security focus
/sc:analyze src/auth --focus security --depth deep
# Performance analysis
/sc:analyze --focus performance --format report
# Quick quality check
/sc:analyze src/components --focus quality --depth quick
# Architecture review
/sc:analyze --focus architecture .
```
### Rapid Development Commands
```bash
# UI components (triggers Magic MCP + Frontend agent)
/sc:implement dashboard component --type component --framework react
# API development (triggers Backend agent + Context7)
/sc:implement user management API --type api --safe
# Full features (triggers multiple agents)
/sc:implement payment processing --type feature --with-tests
```
---
## Development Scenarios 📋
### Scenario 1: New Team Member Onboarding
**Situation**: New developer joining project, needs to understand codebase and setup development environment.
**Step-by-step workflow:**
```bash
# 1. Initialize session and load project context
/sc:load --deep --summary
# 🎯 Expected: Comprehensive project analysis with structure, tech stack, and key components
# 2. Understand architecture and dependencies
/sc:analyze --focus architecture
# 🎯 Expected: System design overview, dependency mapping, and component relationships
# 3. Check code quality and identify areas needing attention
/sc:analyze --focus quality --format report
# 🎯 Expected: HTML report with quality metrics, technical debt, and improvement areas
# 4. Verify test coverage and quality
/sc:test --coverage
# 🎯 Expected: Test execution results with coverage percentages and missing test areas
# 5. Generate onboarding documentation
/sc:document --type guide "getting started with this project"
# 🎯 Expected: Comprehensive getting started guide with setup instructions
# 6. Save insights for future reference
/sc:save --checkpoint "onboarding analysis complete"
# 🎯 Expected: Session saved with all analysis insights and documentation
```
**💡 Why this works:**
- `/sc:load --deep` activates comprehensive project analysis
- Multiple analysis focuses provide complete understanding
- Documentation generation creates permanent reference materials
- Session persistence preserves insights for future use
**⚠️ Gotchas:**
- Large projects may take time for deep analysis
- Test command requires existing test configuration
- Documentation quality depends on project structure clarity
---
### Scenario 2: Security Vulnerability Investigation
**Situation**: Security scan flagged potential vulnerabilities, need systematic investigation and remediation.
**Step-by-step workflow:**
```bash
# 1. Initialize focused security analysis
/sc:analyze --focus security --depth deep
# 🎯 Expected: Comprehensive security vulnerability assessment with severity ratings
# 2. Investigate specific suspicious components
/sc:troubleshoot "potential SQL injection in user queries" --type security --trace
# 🎯 Expected: Systematic analysis of SQL injection vectors and vulnerable code patterns
# 3. Analyze authentication and authorization systems
/sc:analyze src/auth --focus security --format report
# 🎯 Expected: Detailed auth security analysis with specific vulnerability details
# 4. Apply security improvements
/sc:improve auth-service --type security --safe
# 🎯 Expected: Automatic application of security best practices and vulnerability fixes
# 5. Validate security improvements with testing
/sc:test --type security
# 🎯 Expected: Security-focused test execution with validation of fixes
# 6. Document security findings and remediation
/sc:document --type report "security vulnerability assessment"
# 🎯 Expected: Comprehensive security report with findings and remediation steps
# 7. Save security analysis for compliance
/sc:save --type security-audit "vulnerability remediation complete"
# 🎯 Expected: Complete security audit trail saved for future reference
```
**💡 Why this works:**
- Security-focused analysis activates Security Engineer agent automatically
- Systematic troubleshooting provides comprehensive investigation methodology
- Safe improvements apply fixes without breaking existing functionality
- Documentation creates audit trail for compliance requirements
**⚠️ Gotchas:**
- Security analysis may flag false positives requiring manual review
- Improvements should be tested thoroughly before production deployment
- Complex security issues may require expert security engineer consultation
---
### Scenario 3: Performance Optimization Sprint
**Situation**: Application performance has degraded, need systematic optimization across frontend and backend.
**Step-by-step workflow:**
```bash
# 1. Comprehensive performance baseline analysis
/sc:analyze --focus performance --depth deep
# 🎯 Expected: Performance bottleneck identification with specific metrics and recommendations
# 2. Profile API performance issues
/sc:troubleshoot "API response times degraded" --type performance
# 🎯 Expected: Systematic analysis of API bottlenecks, database queries, and caching issues
# 3. Optimize backend performance
/sc:improve api-endpoints --type performance --interactive
# 🎯 Expected: Performance engineer provides optimization recommendations with guided implementation
# 4. Optimize frontend bundle and rendering
/sc:improve src/components --type performance --safe
# 🎯 Expected: Frontend optimization including code splitting, lazy loading, and rendering improvements
# 5. Build optimized production artifacts
/sc:build --type prod --optimize --verbose
# 🎯 Expected: Optimized production build with minification, tree-shaking, and performance analysis
# 6. Validate performance improvements with testing
/sc:test --type performance --coverage
# 🎯 Expected: Performance test execution with before/after metrics comparison
# 7. Monitor and document optimization results
/sc:reflect --type completion "performance optimization"
# 🎯 Expected: Validation of optimization effectiveness with recommendations for monitoring
# 8. Save optimization insights and metrics
/sc:save --checkpoint "performance optimization sprint complete"
# 🎯 Expected: Complete optimization documentation with metrics and ongoing monitoring recommendations
```
**💡 Why this works:**
- Performance focus automatically activates Performance Engineer agent
- Interactive improvements provide guided optimization decisions
- Production build validation ensures optimizations work in deployment
- Comprehensive testing validates improvement effectiveness
**⚠️ Gotchas:**
- Performance improvements may introduce subtle bugs requiring thorough testing
- Production builds should be tested in staging environment first
- Performance metrics should be monitored continuously after deployment
---
### Scenario 4: Legacy Code Modernization
**Situation**: Large legacy codebase needs modernization to current standards and frameworks.
**Step-by-step workflow:**
```bash
# 1. Assess legacy codebase comprehensively
/sc:load --deep --summary
# 🎯 Expected: Complete legacy system analysis with technology stack assessment
# 2. Identify modernization opportunities and technical debt
/sc:analyze --focus architecture --depth deep
# 🎯 Expected: Technical debt assessment with modernization recommendations and migration strategy
# 3. Plan systematic modernization approach
/sc:select-tool "migrate 100+ files to TypeScript" --analyze
# 🎯 Expected: Tool selection recommendations for large-scale code transformation
# 4. Begin with code quality improvements
/sc:improve legacy-modules --type maintainability --preview
# 🎯 Expected: Preview of maintainability improvements without applying changes
# 5. Apply safe modernization improvements
/sc:improve legacy-modules --type maintainability --safe
# 🎯 Expected: Application of safe refactoring and modernization patterns
# 6. Clean up technical debt systematically
/sc:cleanup src/ --dead-code --safe
# 🎯 Expected: Removal of dead code, unused imports, and outdated patterns
# 7. Validate modernization with comprehensive testing
/sc:test --type all --coverage
# 🎯 Expected: Complete test suite execution with coverage analysis
# 8. Document modernization progress and next steps
/sc:document --type report "legacy modernization progress"
# 🎯 Expected: Comprehensive modernization report with completed work and future recommendations
# 9. Save modernization insights for iterative improvement
/sc:save --checkpoint "legacy modernization phase 1"
# 🎯 Expected: Complete modernization context saved for continued iterative improvement
```
**💡 Why this works:**
- Deep analysis provides comprehensive understanding of legacy system complexity
- Tool selection optimization ensures efficient modernization approach
- Preview mode allows safe exploration of changes before application
- Iterative approach with checkpoints enables manageable modernization process
**⚠️ Gotchas:**
- Large legacy systems require multiple iteration cycles
- Preview changes carefully before applying to critical systems
- Comprehensive testing essential to prevent breaking legacy functionality
- Modernization should be planned in phases to manage risk
---
### Scenario 5: Multi-Team API Design
**Situation**: Multiple teams need to collaborate on API design requiring coordination across frontend, backend, and security concerns.
**Step-by-step workflow:**
```bash
# 1. Brainstorm API requirements with stakeholder exploration
/sc:brainstorm "multi-service API architecture" --strategy enterprise --depth deep
# 🎯 Expected: Comprehensive requirements discovery with cross-team considerations
# 2. Generate structured API implementation workflow
/sc:workflow api-requirements.md --strategy systematic --parallel
# 🎯 Expected: Detailed implementation plan with multi-team coordination and dependencies
# 3. Design API architecture with security considerations
/sc:design --type api user-management --format spec
# 🎯 Expected: Formal API specification with security, performance, and integration considerations
# 4. Implement API with multi-domain expertise
/sc:implement user management API --type api --with-tests --safe
# 🎯 Expected: Complete API implementation with automated testing and security validation
# 5. Validate API design with cross-team testing
/sc:test --type integration --coverage
# 🎯 Expected: Integration testing with frontend/backend coordination validation
# 6. Generate comprehensive API documentation
/sc:document --type api src/controllers/ --style detailed
# 🎯 Expected: Complete API documentation with usage examples and integration guidance
# 7. Reflect on multi-team coordination effectiveness
/sc:reflect --type completion "API design collaboration"
# 🎯 Expected: Analysis of coordination effectiveness with recommendations for future collaboration
# 8. Save API design insights for team knowledge sharing
/sc:save --type collaboration "multi-team API design complete"
# 🎯 Expected: Complete API design context saved for future multi-team projects
```
**💡 Why this works:**
- Brainstorming mode facilitates cross-team requirements discovery
- Workflow generation provides structured coordination approach
- Multi-persona activation ensures comprehensive domain coverage
- Documentation supports ongoing team collaboration
**⚠️ Gotchas:**
- Multi-team coordination requires clear communication channels
- API design decisions should be validated with all stakeholder teams
- Integration testing requires coordination of development environments
- Documentation should be maintained as API evolves
---
## Troubleshooting Scenarios 🔧
### Problem: Build Failures After Dependency Updates
**Symptoms**: Build process failing with cryptic error messages after updating dependencies.
**Troubleshooting workflow:**
```bash
# 1. Systematic build failure investigation
/sc:troubleshoot "TypeScript compilation errors" --type build --trace
# 🎯 Expected: Systematic analysis of build logs and TypeScript configuration issues
# 2. Analyze dependency compatibility
/sc:analyze package.json --focus dependencies
# 🎯 Expected: Dependency conflict analysis with compatibility recommendations
# 3. Attempt automatic build fixes
/sc:troubleshoot "build failing" --type build --fix
# 🎯 Expected: Application of common build fixes with validation
# 4. Clean build with optimization
/sc:build --clean --verbose
# 🎯 Expected: Clean build execution with detailed error analysis
```
**💡 Why this works:** Systematic troubleshooting provides structured diagnosis, automatic fixes handle common issues, verbose output reveals detailed error information.
---
### Problem: Authentication System Security Vulnerabilities
**Symptoms**: Security scan revealed potential authentication vulnerabilities.
**Troubleshooting workflow:**
```bash
# 1. Deep security analysis of authentication system
/sc:analyze src/auth --focus security --depth deep
# 🎯 Expected: Comprehensive security vulnerability assessment with specific findings
# 2. Investigate specific authentication vulnerabilities
/sc:troubleshoot "JWT token vulnerability" --type security --trace
# 🎯 Expected: Systematic analysis of JWT implementation with security recommendations
# 3. Apply security hardening improvements
/sc:improve auth-service --type security --safe
# 🎯 Expected: Application of security best practices and vulnerability fixes
# 4. Validate security fixes with testing
/sc:test --type security auth-tests/
# 🎯 Expected: Security-focused testing with validation of vulnerability fixes
```
**💡 Why this works:** Security-focused analysis activates security expertise, systematic troubleshooting provides comprehensive investigation, safe improvements ensure no functionality breaks.
---
### Problem: Performance Degradation in Production
**Symptoms**: Application response times increased significantly in production environment.
**Troubleshooting workflow:**
```bash
# 1. Performance bottleneck identification
/sc:troubleshoot "API response times degraded" --type performance
# 🎯 Expected: Systematic performance analysis with bottleneck identification
# 2. Analyze performance across application layers
/sc:analyze --focus performance --format report
# 🎯 Expected: Comprehensive performance report with optimization recommendations
# 3. Optimize critical performance paths
/sc:improve api-endpoints --type performance --interactive
# 🎯 Expected: Performance optimization with guided decision-making
# 4. Validate performance improvements
/sc:test --type performance --coverage
# 🎯 Expected: Performance testing with before/after metrics comparison
```
**💡 Why this works:** Performance-focused troubleshooting provides systematic bottleneck analysis, interactive improvements guide complex optimization decisions, testing validates improvement effectiveness.
---
## Advanced Patterns 🎓
### Pattern: Cross-Session Project Development
**Use case**: Working on complex features across multiple development sessions with context preservation.
```bash
# Session 1: Requirements and Planning
/sc:load # Initialize project context
/sc:brainstorm "user dashboard feature" --prd # Explore requirements
/sc:workflow dashboard-requirements.md # Generate implementation plan
/sc:save --checkpoint "dashboard planning" # Save planning context
# Session 2: Implementation Start
/sc:load # Resume project context
/sc:implement dashboard component --type component --framework react
/sc:save --checkpoint "dashboard component created"
# Session 3: Testing and Refinement
/sc:load # Resume project context
/sc:test dashboard-component --coverage # Validate implementation
/sc:improve dashboard-component --type quality --safe
/sc:save --checkpoint "dashboard implementation complete"
# Session 4: Integration and Documentation
/sc:load # Resume project context
/sc:reflect --type completion "dashboard feature"
/sc:document --type component dashboard-component
/sc:save "dashboard feature complete"
```
**💡 Why this works:** Session persistence maintains context across development cycles, checkpoints provide recovery points, progressive enhancement builds on previous work.
---
### Pattern: Multi-Tool Complex Analysis
**Use case**: Complex system analysis requiring coordination of multiple specialized tools and expertise.
```bash
# Step 1: Intelligent tool selection for complex task
/sc:select-tool "comprehensive security and performance audit" --analyze
# 🎯 Expected: Recommended tool combination and coordination strategy
# Step 2: Coordinated multi-domain analysis
/sc:analyze --focus security --depth deep &
/sc:analyze --focus performance --depth deep &
/sc:analyze --focus architecture --depth deep
# 🎯 Expected: Parallel analysis across multiple domains
# Step 3: Systematic troubleshooting with expert coordination
/sc:troubleshoot "complex system behavior" --type system --sequential
# 🎯 Expected: Structured debugging with multiple expert perspectives
# Step 4: Comprehensive improvement with validation
/sc:improve . --type quality --interactive --validate
# 🎯 Expected: Guided improvements with comprehensive validation gates
```
**💡 Why this works:** Tool selection optimization ensures efficient approach, parallel analysis maximizes efficiency, expert coordination provides comprehensive coverage.
---
### Pattern: Large-Scale Code Transformation
**Use case**: Systematic transformation of large codebase with pattern-based changes.
```bash
# Step 1: Analyze scope and plan transformation approach
/sc:select-tool "migrate 100+ files to TypeScript" --efficiency
# 🎯 Expected: Optimal tool selection for large-scale transformation
# Step 2: Systematic transformation with progress tracking
/sc:spawn migrate-typescript --parallel --monitor
# 🎯 Expected: Parallel transformation with progress monitoring
# Step 3: Validate transformation quality and completeness
/sc:test --type all --coverage
/sc:analyze --focus quality transformed-files/
# 🎯 Expected: Comprehensive validation of transformation quality
# Step 4: Cleanup and optimization post-transformation
/sc:cleanup transformed-files/ --safe
/sc:improve transformed-files/ --type maintainability --safe
# 🎯 Expected: Final cleanup and optimization of transformed code
```
**💡 Why this works:** Scope analysis ensures appropriate tool selection, parallel processing maximizes efficiency, comprehensive validation ensures quality maintenance.
---
## Command Combinations That Work Well 🔗
### Security-Focused Development Workflow
```bash
# Analysis → Improvement → Validation → Documentation
/sc:analyze --focus security --depth deep
/sc:improve src/ --type security --safe
/sc:test --type security --coverage
/sc:document --type security-guide
```
### Performance Optimization Workflow
```bash
# Profiling → Optimization → Building → Validation
/sc:analyze --focus performance --format report
/sc:improve api/ --type performance --interactive
/sc:build --type prod --optimize
/sc:test --type performance
```
### Quality Improvement Workflow
```bash
# Assessment → Preview → Application → Cleanup → Testing
/sc:analyze --focus quality
/sc:improve src/ --type quality --preview
/sc:improve src/ --type quality --safe
/sc:cleanup src/ --safe
/sc:test --coverage
```
### New Feature Development Workflow
```bash
# Planning → Implementation → Testing → Documentation → Session Save
/sc:brainstorm "feature idea" --prd
/sc:implement feature-name --type feature --with-tests
/sc:test feature-tests/ --coverage
/sc:document --type feature feature-name
/sc:save --checkpoint "feature complete"
```
### Legacy Code Modernization Workflow
```bash
# Assessment → Planning → Safe Improvement → Cleanup → Validation
/sc:load --deep --summary
/sc:select-tool "legacy modernization" --analyze
/sc:improve legacy/ --type maintainability --preview
/sc:improve legacy/ --type maintainability --safe
/sc:cleanup legacy/ --safe
/sc:test --type all
```
---
## Best Practices in Action 🌟
### Effective Flag Usage Patterns
**Safe Development Pattern:**
```bash
# Always preview before applying changes
/sc:improve src/ --preview # See what would change
/sc:improve src/ --safe # Apply only safe changes
/sc:test --coverage # Validate changes work
```
**Progressive Analysis Pattern:**
```bash
# Start broad, then focus deep
/sc:analyze . # Quick overview
/sc:analyze src/auth --focus security --depth deep # Deep dive specific areas
/sc:analyze --focus performance --format report # Detailed reporting
```
**Session Management Pattern:**
```bash
# Initialize → Work → Checkpoint → Validate → Save
/sc:load # Start session
# ... work commands ...
/sc:save --checkpoint "work in progress" # Regular checkpoints
/sc:reflect --type completion "task name" # Validate completion
/sc:save "task complete" # Final save
```
### Expert Activation Optimization
**Let auto-activation work:**
```bash
# These automatically activate appropriate experts
/sc:analyze src/auth --focus security # → Security Engineer
/sc:implement user dashboard --framework react # → Frontend Architect + Magic MCP
/sc:troubleshoot "API performance issues" # → Performance Engineer + Backend Architect
/sc:improve legacy-code --type maintainability # → Architect + Quality Engineer
```
**Manual coordination when needed:**
```bash
# Complex scenarios benefit from explicit tool selection
/sc:select-tool "enterprise authentication system" --analyze
/sc:brainstorm "multi-service architecture" --strategy enterprise
/sc:workflow complex-feature.md --strategy systematic --parallel
```
### Error Recovery Patterns
**When commands don't work as expected:**
```bash
# 1. Start with broader scope
/sc:analyze src/component.js # Instead of very specific file
/sc:troubleshoot "build failing" # Instead of specific error
# 2. Use safe flags
/sc:improve --safe --preview # Check before applying
/sc:cleanup --safe # Conservative cleanup only
# 3. Validate systematically
/sc:reflect --type task "what I'm trying to do" # Check approach
/sc:test --coverage # Ensure nothing broke
```
### Performance Optimization
**For large projects:**
```bash
# Use focused analysis instead of analyzing everything
/sc:analyze src/components --focus quality # Not entire project
/sc:analyze api/ --focus performance # Specific performance focus
# Use depth control
/sc:analyze --depth quick # Fast overview
/sc:analyze critical-files/ --depth deep # Deep dive where needed
```
**For resource constraints:**
```bash
# Use efficient command combinations
/sc:select-tool "complex operation" --efficiency # Get optimal approach
/sc:spawn complex-task --parallel # Parallel processing
/sc:save --checkpoint # Frequent saves to preserve work
```
---
## Troubleshooting Command Issues 🔧
### Common Command Problems and Solutions
**"Command not working as expected":**
```bash
# Try these diagnostic approaches
/sc:index --search "keyword" # Find relevant commands
/sc:select-tool "what you're trying to do" # Get tool recommendations
/sc:reflect --type task "your goal" # Validate approach
```
**"Analysis taking too long":**
```bash
# Use scope and depth control
/sc:analyze src/specific-folder --depth quick # Narrow scope
/sc:analyze --focus specific-area # Focus analysis
/sc:analyze file.js # Single file analysis
```
**"Build commands failing":**
```bash
# Systematic build troubleshooting
/sc:troubleshoot "build issue description" --type build
/sc:analyze package.json --focus dependencies
/sc:build --clean --verbose # Clean build with details
```
**"Not sure which command to use":**
```bash
# Command discovery
/sc:index # Browse all commands
/sc:index --category analysis # Commands by category
/sc:index --search "performance" # Search by keyword
```
### When to Use Which Approach
**Quick tasks (< 5 minutes):**
- Use direct commands: `/sc:analyze`, `/sc:build`, `/sc:improve`
- Skip session management for one-off tasks
- Use `--quick` depth for fast results
**Medium tasks (30 minutes - 2 hours):**
- Initialize with `/sc:load`
- Use checkpoints: `/sc:save --checkpoint`
- Use `--preview` before making changes
- Validate with `/sc:reflect`
**Long-term projects (days/weeks):**
- Always use session lifecycle: `/sc:load` → work → `/sc:save`
- Use `/sc:brainstorm` for requirements discovery
- Plan with `/sc:workflow` for complex features
- Regular reflection and validation
**Emergency fixes:**
- Start with `/sc:troubleshoot` for diagnosis
- Use `--safe` flags for all changes
- Test immediately: `/sc:test`
- Document fixes: `/sc:document --type fix`
---
## Quick Reference Cheat Sheet 📝
### Most Useful Commands
```bash
/sc:load # Start session
/sc:analyze . # Understand project
/sc:implement feature-name # Build features
/sc:improve messy-code # Clean up code
/sc:troubleshoot "issue" # Debug problems
/sc:build # Build project
/sc:test --coverage # Test everything
/sc:save # Save session
```
### Best Flag Combinations
```bash
--safe # Conservative changes only
--preview # Show changes before applying
--depth deep # Thorough analysis
--focus security|performance|quality # Domain-specific focus
--with-tests # Include testing
--interactive # Guided assistance
--format report # Generate detailed reports
```
### Emergency Commands
```bash
/sc:troubleshoot "critical issue" --fix # Emergency fixes
/sc:analyze --focus security --depth deep # Security emergencies
/sc:build --clean --verbose # Build emergencies
/sc:reflect --type completion # Validate fixes work
```
### Session Management
```bash
/sc:load # Start/resume session
/sc:save --checkpoint "description" # Save progress
/sc:reflect --type completion # Validate completion
/sc:save "final description" # End session
```
---
## Remember: Learning Through Doing 🎯
**The SuperClaude Philosophy:**
- **Start simple** - Try `/sc:analyze` or `/sc:implement` first
- **Let auto-activation work** - SuperClaude picks experts for you
- **Experiment freely** - Use `--preview` to see what would happen
- **Progressive enhancement** - Start basic, add complexity as needed
**Most important patterns:**
1. Initialize sessions: `/sc:load`
2. Save progress: `/sc:save --checkpoint`
3. Validate completion: `/sc:reflect`
4. Preview before applying: `--preview` flag
5. Use safe modes: `--safe` flag
**Remember:** You don't need to memorize everything in this cookbook. SuperClaude is designed to be discoverable through use. Start with the Quick Examples section and experiment from there!
---
## Related Guides
**🚀 Foundation Knowledge (Start Here)**
- [Installation Guide](installation-guide.md) - Get SuperClaude set up first
- [SuperClaude User Guide](superclaude-user-guide.md) - Understand the framework philosophy
**📚 Deep Understanding (After Trying Examples)**
- [Commands Guide](commands-guide.md) - Complete reference for all 21 commands
- [Session Management Guide](session-management.md) - Master /sc:load and /sc:save workflows
- [Agents Guide](agents-guide.md) - Understanding the 13 specialists behind the scenes
**⚙️ Advanced Usage (When You Want Control)**
- [Flags Guide](flags-guide.md) - Manual control and optimization flags
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How SuperClaude adapts automatically
- [Best Practices Guide](best-practices.md) - Proven patterns for effective usage
**🔧 When Examples Don't Work**
- [Troubleshooting Guide](troubleshooting-guide.md) - Solutions for common command issues
**🏗️ Technical Understanding (Optional)**
- [Technical Architecture Guide](technical-architecture.md) - How the system works internally
**📖 Learning Path Using This Cookbook:**
1. Try [Quick Examples](#quick-examples---just-try-these-) for immediate results
2. Follow [Development Scenarios](#development-scenarios-) for complete workflows
3. Use [Command Combinations](#command-combinations-that-work-well-) for your specific needs
4. Reference [Best Practices](#best-practices-in-action-) for optimization
---
*Ready to start? Try `/sc:load` to initialize your session and pick any example that matches your current need! 🚀*

619
Guides/flags-guide.md
View File

@ -1,619 +0,0 @@
# SuperClaude Framework Flags User Guide 🏁
## 🤖 Most Flags Activate Automatically - Don't Stress About It!
**The honest truth**: You don't need to memorize these flags. SuperClaude usually tries to add helpful ones based on what you're doing!
**Here's what actually happens:**
- You type `/analyze auth.js`
- SuperClaude detects it's security-related code
- **Usually activates** security-engineer agent, `--focus security`, `--validate`
- You often get expert security analysis without managing any flags
**When might you manually use flags?**
- You want to **override** what SuperClaude picked (rare)
- You're **curious** about specific aspects (`--focus performance`)
- You want to **experiment** with different approaches
**Bottom line**: Just use basic commands and let the auto-activation work. These flags are here when you want them, not because you need them. 🎯
---
## 🚀 Just Try These (No Flag Knowledge Required)
```bash
# These work great with zero flag knowledge:
/sc:analyze src/ # Auto-activates appropriate expert agents
/sc:build # Auto-optimizes based on your project
/sc:improve messy-code.js # Auto-activates quality agents and safety flags
/sc:troubleshoot "weird error" # Auto-activates root-cause-analyst and debugging flags
/sc:brainstorm "my app idea" # Auto-activates requirements-analyst agent for discovery
```
**See? No flags needed.** Everything below is for when you get curious about what's happening behind the scenes. For many more working examples, see [Examples Cookbook](examples-cookbook.md).
---
A practical guide to SuperClaude's flag system. Flags are like command-line options that change how SuperClaude behaves - think of them as superpowers for your commands.
## What Are Flags? 🤔
**Flags are modifiers** that change how SuperClaude processes your requests. They come after commands and start with `--`.
**Basic syntax** (but you usually don't need to know this):
```bash
/sc:command --flag-name
/sc:command --flag-name value
/sc:analyze src/ --focus security --depth deep
```
**How flags actually work in practice**:
1. **Auto-activation** - SuperClaude adds them based on context (this is the main way! 🎯)
2. **Manual override** - You can add them explicitly if you want different behavior
**Why flags exist** (mostly automatic benefits):
- Get better, more focused results
- Auto-enable the right thinking depth
- Connect to special capabilities when useful
- Optimize for speed or detail based on your task
- Direct attention to what you're actually working on
**The key point**: SuperClaude handles flag selection intelligently so you don't have to think about it! 🧠
## Flag Categories 📂
### Planning & Analysis Flags 🧠
These control how deeply SuperClaude thinks about your request.
#### `--plan`
**What it does**: Shows execution plan before doing anything
**When to use**: When you want to see what SuperClaude will do first
**Example**: `/build --plan` - See build steps before running
#### `--think`
**What it does**: Multi-file analysis (~4K tokens)
**When to use**: Complex problems involving several files
**Auto-activates**: Import chains >5 files, cross-module calls >10 references
**Example**: `/analyze complex-system/ --think`
#### `--think-hard`
**What it does**: Deep architectural analysis (~10K tokens)
**When to use**: System-wide problems, architectural decisions
**Auto-activates**: System refactoring, bottlenecks >3 modules
**Example**: `/improve legacy-system/ --think-hard`
#### `--ultrathink`
**What it does**: Maximum depth analysis (~32K tokens)
**When to use**: Critical system redesign, complex debugging
**Auto-activates**: Legacy modernization, critical vulnerabilities
**Example**: `/troubleshoot "entire auth system broken" --ultrathink`
**💡 Tip**: Start with `--think`, only go deeper if needed. More thinking = slower but more thorough.
---
### Efficiency & Control Flags ⚡
Control output style, safety, and performance.
#### `--uc` / `--ultracompressed`
**What it does**: 60-80% token reduction using symbols
**When to use**: Large operations, when context is getting full
**Auto-activates**: Context usage >75%, large-scale operations
**Example**: `/analyze huge-codebase/ --uc`
#### `--safe-mode`
**What it does**: Maximum validation, conservative execution
**When to use**: Production environments, risky operations
**Auto-activates**: Resource usage >85%, production environment
**Example**: `/improve production-code/ --safe-mode`
#### `--validate`
**What it does**: Pre-operation validation and risk assessment
**When to use**: Want to check before making changes
**Auto-activates**: Risk score >0.7
**Example**: `/cleanup legacy/ --validate`
#### `--verbose`
**What it does**: Maximum detail and explanation
**When to use**: Learning, debugging, need full context
**Example**: `/build --verbose` - See every build step
#### `--answer-only`
**What it does**: Direct response without task creation
**When to use**: Quick questions, don't want workflow automation
**Example**: `/explain React hooks --answer-only`
**💡 Tip**: `--uc` is great for big operations. `--safe-mode` for anything important. `--verbose` when you're learning.
---
### MCP Server Flags 🔧
Enable specialized capabilities through MCP servers.
#### `--c7` / `--context7`
**What it does**: Enables Context7 for official library documentation
**When to use**: Working with frameworks, need official docs
**Auto-activates**: External library imports, framework questions
**Example**: `/build react-app/ --c7` - Get React best practices
#### `--seq` / `--sequential`
**What it does**: Enables Sequential for complex multi-step analysis
**When to use**: Complex debugging, system design
**Auto-activates**: Complex debugging, `--think` flags
**Example**: `/troubleshoot "auth flow broken" --seq`
#### `--magic`
**What it does**: Enables Magic for UI component generation
**When to use**: Creating UI components, design systems
**Auto-activates**: UI component requests, frontend architect agent
**Example**: `/build dashboard --magic` - Get modern UI components
#### `--play` / `--playwright`
**What it does**: Enables Playwright for browser automation and testing
**When to use**: E2E testing, performance monitoring
**Auto-activates**: Test workflows, QA specialist agent
**Example**: `/test e2e --play`
#### `--morph` / `--morphllm`
**What it does**: Enables Morphllm for intelligent file editing and pattern transformations
**When to use**: Multi-file edits, pattern-based transformations
**Auto-activates**: Complex refactoring, bulk file updates
**Example**: `/refactor --morph pattern-updates/`
#### `--serena` / `--semantic`
**What it does**: Enables Serena for semantic analysis and memory operations
**When to use**: Symbol analysis, project-wide context, session management
**Auto-activates**: Complex symbol operations, memory commands
**Example**: `/analyze --serena --semantic large-codebase/`
#### `--all-mcp`
**What it does**: Enables all MCP servers simultaneously
**When to use**: Complex multi-domain problems
**Auto-activates**: Problem complexity >0.8, multi-domain indicators
**Example**: `/analyze entire-app/ --all-mcp`
#### `--no-mcp`
**What it does**: Disables all MCP servers, native tools only
**When to use**: Faster execution, don't need specialized features
**Example**: `/analyze simple-script.js --no-mcp`
**💡 Tip**: MCP servers add capabilities but use more tokens. `--c7` for docs, `--seq` for thinking, `--magic` for UI, `--serena` for memory & semantic analysis.
---
### Advanced Orchestration Flags 🎭
For complex operations and workflows.
#### `--delegate [files|folders|auto]`
**What it does**: Enables sub-agent delegation for parallel processing
**When to use**: Large codebases, complex analysis
**Auto-activates**: >7 directories or >50 files
**Options**:
- `files` - Delegate individual file analysis
- `folders` - Delegate directory-level analysis
- `auto` - Smart delegation strategy
**Example**: `/analyze monorepo/ --delegate auto`
#### `--loop`
**What it does**: Iterative improvement mode
**When to use**: Quality improvement, refinement operations
**Auto-activates**: Polish, refine, enhance keywords
**Example**: `/improve messy-code.js --loop`
#### `--iterations [n]`
**What it does**: Control number of improvement cycles (1-10)
**When to use**: Controlling iterative enhancement depth
**Example**: `/improve --loop --iterations 5`
#### `--interactive`
**What it does**: Enables user confirmation between iterations
**When to use**: Want control over iterative process
**Example**: `/improve --loop --interactive`
#### `--concurrency [n]`
**What it does**: Control max concurrent sub-agents (1-15)
**When to use**: Controlling resource usage
**Example**: `/analyze --delegate auto --concurrency 3`
**💡 Tip**: These are powerful but complex. Start with `--delegate auto` for big projects, `--loop` for improvements.
---
### Session & Workflow Flags 🔄
These SuperClaude Framework flags control session management and advanced workflows.
#### `--brainstorm`
**What it does**: Activates brainstorming mode for requirements discovery
**When to use**: Ambiguous project ideas, need specification development
**Auto-activates**: Exploration keywords, "not sure", project planning
**Example**: `/brainstorm "task management app" --brainstorm`
#### `--max-rounds [n]`
**What it does**: Controls brainstorming dialogue rounds (default: 15)
**When to use**: Controlling brainstorming session depth
**Example**: `/brainstorm idea --max-rounds 10`
#### `--prd`
**What it does**: Generates Product Requirements Document from brainstorming
**When to use**: Convert discussions to formal specifications
**Auto-activates**: End of successful brainstorming sessions
**Example**: `/brainstorm app-idea --prd`
**💡 Tip**: SuperClaude Framework introduces powerful session management - let brainstorming mode guide requirement discovery naturally.
---
### Focus & Scope Flags 🎯
Direct SuperClaude's attention to specific areas.
#### `--scope [level]`
**Options**: file, module, project, system
**What it does**: Sets analysis scope
**Example**: `/analyze --scope module auth/`
#### `--focus [domain]`
**Options**: performance, security, quality, architecture, accessibility, testing
**What it does**: Focuses analysis on specific domain
**Example**: `/analyze --focus security --scope project`
#### Agent Flags
**Available agents**: system-architect, backend-architect, frontend-architect, devops-architect, security-engineer, performance-engineer, root-cause-analyst, quality-engineer, refactoring-expert, python-expert, requirements-analyst, technical-writer, learning-guide
**What they do**: Activates specialized domain expert agents (SuperClaude Framework enhancement)
**Example**: `/analyze --agent security-engineer` - Security-focused analysis with expert agent
**💡 Tip**: `--focus` is great for targeted analysis. Expert agents auto-activate but manual control helps.
---
## Common Flag Patterns 🔄
### Quick Analysis
```bash
/sc:analyze src/ --focus quality # Quick quality check
/sc:analyze --uc --focus security # Fast security scan
```
### Deep Investigation
```bash
/sc:troubleshoot "bug" --think --seq # Systematic debugging
/sc:analyze --think-hard --focus architecture # Architectural analysis
```
### Large Project Work
```bash
/sc:analyze monorepo/ --delegate auto --uc # Efficient large analysis
/sc:improve legacy/ --loop --safe-mode # Safe iterative improvement
```
### Learning & Documentation
```bash
/sc:explain React hooks --c7 --verbose # Detailed explanation with docs
/sc:document api/ --agent technical-writer # Professional documentation
```
### Performance-Focused
```bash
/sc:analyze --focus performance --play # Performance analysis with testing
/sc:build --uc --no-mcp # Fast build without extra features
```
### Security-Focused
```bash
/sc:analyze --focus security --think --validate # Thorough security analysis
/sc:scan --agent security-engineer --safe-mode # Conservative security scan
```
## Practical Examples 💡
### Before/After: Basic Analysis
**Before** (basic):
```bash
/sc:analyze auth.js
# → Simple file analysis
```
**After** (with flags):
```bash
/sc:analyze auth.js --focus security --think --c7
# → Security-focused analysis with deep thinking and official docs
# → Much more thorough, finds security patterns, checks against best practices
```
### Before/After: Large Project
**Before** (slow):
```bash
/sc:analyze huge-monorepo/
# → Tries to analyze everything at once, may timeout or use too many tokens
```
**After** (efficient):
```bash
/sc:analyze huge-monorepo/ --delegate auto --uc --focus architecture
# → Delegates work to sub-agents, compresses output, focuses on architecture
# → Faster, more focused, better results
```
### Before/After: Improvement Work
**Before** (risky):
```bash
/sc:improve legacy-system/
# → May make too many changes, could break things
```
**After** (safe):
```bash
/sc:improve legacy-system/ --safe-mode --loop --validate
# → Safe changes only, iterative approach, validates first, systematic improvement
# → Much safer, progressive improvement
```
## Auto-Activation Examples 🤖
SuperClaude usually adds flags based on context. Here's when it tries:
### Complexity-Based
```bash
/sc:analyze huge-codebase/
# Auto-adds: --delegate auto --uc
# Why: >50 files detected, context management needed
/sc:troubleshoot "complex system issue"
# Auto-adds: --think --seq
# Why: Multi-component problem detected
```
### Domain-Based
```bash
/sc:build react-app/
# Auto-activates: frontend-architect agent + --c7
# Why: Frontend framework detected
/sc:analyze --focus security
# Auto-activates: security-engineer agent + --validate
# Why: Security focus triggers security specialist
```
### Performance-Based
```bash
# When context usage >75%
/sc:analyze large-project/
# Auto-adds: --uc
# Why: Token optimization needed
# When risk score >0.7
/sc:improve production-code/
# Auto-adds: --safe-mode --validate
# Why: High-risk operation detected
```
## Advanced Usage 🚀
### Complex Flag Combinations
**Comprehensive Code Review**:
```bash
/sc:review codebase/ --agent quality-engineer --think-hard --focus quality --validate --c7
# → Quality engineer agent + deep thinking + quality focus + validation + docs
```
**Legacy System Modernization**:
```bash
/sc:improve legacy/ --delegate auto --agent system-architect --safe-mode --loop --c7
# → Systematic orchestration + architect agent + safety + iteration + docs
```
**Security Audit**:
```bash
/sc:scan --agent security-engineer --ultrathink --focus security --validate --seq
# → Security engineer agent + maximum thinking + security focus + validation + systematic analysis
```
### Performance Optimization
**For Speed**:
```bash
/sc:analyze --no-mcp --uc --scope file
# → Disable extra features, compress output, limit scope
```
**For Thoroughness**:
```bash
/sc:analyze --all-mcp --think-hard --delegate auto
# → All capabilities, deep thinking, parallel processing
```
### Custom Workflows
**Bug Investigation Workflow**:
```bash
/sc:troubleshoot "specific error" --seq --think --validate
/sc:analyze affected-files/ --focus quality --agent root-cause-analyst
/sc:test --play --coverage
```
**Feature Development Workflow**:
```bash
/sc:design new-feature --agent system-architect --c7
/sc:build --magic --agent frontend-architect --validate
/sc:test --play --coverage
/sc:document --agent technical-writer --c7
```
## Quick Reference 📋
### Most Useful Flags
| Flag | Purpose | When to Use |
|------|---------|-------------|
| `--think` | Deeper analysis | Complex problems |
| `--uc` | Compress output | Large operations |
| `--safe-mode` | Conservative execution | Important code |
| `--c7` | Official docs | Framework work |
| `--seq` | Systematic analysis | Debugging |
| `--focus security` | Security focus | Security concerns |
| `--delegate auto` | Parallel processing | Large codebases |
| `--validate` | Check before action | Risky operations |
| `--brainstorm` | Requirements discovery | Ambiguous projects |
| `--serena` | Semantic analysis | Symbol operations |
### Flag Combinations That Work Well
```bash
# Safe improvement
--safe-mode --validate
# Deep analysis
--think --seq --c7
# Large project
--delegate auto --uc --focus
# Learning
--verbose --c7 --agent learning-guide
# Security work
--agent security-engineer --focus security --validate
# Performance work
--agent performance-engineer --focus performance --play
# Requirements discovery
--brainstorm --max-rounds 10 --prd
```
### Auto-Activation Triggers
- **--think**: Complex imports, cross-module calls
- **--uc**: Context >75%, large operations
- **--safe-mode**: Resource usage >85%, production
- **--delegate**: >7 directories or >50 files
- **--c7**: Framework imports, documentation requests
- **--seq**: Debugging keywords, --think flags
- **--serena**: Symbol operations, memory commands
- **--brainstorm**: Exploration keywords, ambiguous requests
- **Expert Agents**: Domain-specific keywords and patterns
## Troubleshooting Flag Issues 🚨
### Common Problems
**"Flags don't seem to work"**
- Check spelling (common typos: `--ultracompresed`, `--agent frontend-architect`)
- Some flags need values: `--scope project`, `--focus security`
- Flag conflicts: `--no-mcp` overrides `--c7`, `--seq`, `--serena`, etc.
**"Operation too slow"**
- Try `--uc` for compression
- Use `--no-mcp` to disable extra features
- Limit scope: `--scope file` instead of `--scope project`
**"Too much output"**
- Add `--uc` for compression
- Remove `--verbose` if present
- Use `--answer-only` for simple questions
**"Not thorough enough"**
- Add `--think` or `--think-hard`
- Enable relevant MCP servers: `--seq`, `--c7`
- Use appropriate agent: `--agent root-cause-analyst`
**"Changes too risky"**
- Always use `--safe-mode` for important code
- Add `--validate` to check first
- Use `--validate` to check changes before applying
### Flag Conflicts
**These override others**:
- `--no-mcp` overrides all MCP flags (`--c7`, `--seq`, `--serena`, etc.)
- `--safe-mode` overrides optimization flags
- Last agent flag wins: `--agent frontend-architect --agent backend-architect` → backend-architect
**Precedence order**:
1. Safety flags (`--safe-mode`) beat optimization
2. Explicit flags beat auto-activation
3. Thinking depth: `--ultrathink` > `--think-hard` > `--think`
4. Scope: system > project > module > file
## Tips for Effective Flag Usage 💡
### Starting Out (The Honest Truth)
1. **Just ignore flags at first** - Auto-activation handles most cases pretty well
2. **Watch what gets auto-activated** - You'll learn by seeing what SuperClaude picks
3. **Use `--help` when curious** - Many commands show what flags are available
4. **Trust the automation** - SuperClaude usually picks reasonable defaults
### Getting Advanced (If You Want To)
1. **Experiment with overrides** - Try `--agent security-engineer` on non-security code for different perspectives
2. **Learn the useful combos** - `--safe-mode --validate` for important stuff, `--brainstorm --prd` for new projects
3. **Understand the performance trade-offs** - Fast (`--uc --no-mcp`) vs thorough (`--think-hard --all-mcp`)
4. **Use flags for learning** - `--verbose` when you want to understand what's happening
### Performance Tips (For Power Users)
- **For speed**: `--uc --no-mcp --scope file`
- **For thoroughness**: `--think-hard --all-mcp --delegate auto`
- **For safety**: `--safe-mode --validate`
- **For learning**: `--verbose --c7 --agent learning-guide`
- **For project discovery**: `--brainstorm --max-rounds 15 --prd`
---
## Final Notes 📝
**The real truth about flags** 💯:
- **Auto-activation usually works pretty well** compared to manual flag selection
- **You can ignore most of this guide** and just use basic commands
- **Flags are here when you want them** - not because you need them
- **Learning happens naturally** through use, not through studying guides 😊
**Don't feel overwhelmed** 🧘‍♂️:
- SuperClaude tries to work well without flag knowledge
- The detailed info above is for curiosity, not necessity
- Auto-activation keeps getting smarter based on usage patterns
- You're not missing out by not memorizing flags
**When you actually need flags**:
- Overriding auto-activation (rare)
- Experimenting with different approaches (fun)
- Optimizing for specific performance needs (advanced)
- Learning about what happened (educational)
**Start simple, stay simple** 🎯:
- Use basic commands: `/analyze`, `/build`, `/improve`
- Let auto-activation handle the complexity
- Add manual flags only when you want to experiment
- Trust that SuperClaude knows what it's doing
---
## Related Guides
**🚀 Getting Started (Essential)**
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
- [Examples Cookbook](examples-cookbook.md) - See flags in action with working examples
- [Commands Guide](commands-guide.md) - Commands that work with flags
**🤝 Understanding the System (Recommended)**
- [Agents Guide](agents-guide.md) - How flags activate different agents
- [Behavioral Modes Guide](behavioral-modes-guide.md) - Flags that control modes
- [Session Management Guide](session-management.md) - Session-related flags
**⚙️ Optimization and Control (Advanced)**
- [Best Practices Guide](best-practices.md) - Proven flag combinations and patterns
- [Technical Architecture Guide](technical-architecture.md) - How flag processing works
**🔧 When Flags Don't Work**
- [Troubleshooting Guide](troubleshooting-guide.md) - Flag conflicts and issues
**📖 Recommended Learning Path:**
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation without flags
2. [Commands Guide](commands-guide.md) - Learn which commands benefit from manual flags
3. [Best Practices Guide](best-practices.md) - Master advanced flag patterns
---
*Remember: Behind all this apparent complexity, SuperClaude is actually simple to use. Just start typing commands! 🚀*

520
Guides/installation-guide.md
View File

@ -1,520 +0,0 @@
# SuperClaude Installation Guide 📦
## 🎯 It's Easier Than It Looks!
**The honest truth**: This guide looks comprehensive because we want to cover all the details, but installation is actually simple. Most people are done in 2 minutes with one command!
## Quick Start 🚀
**🏆 The "Just Get It Working" Approach (Recommended for 90% of Users)**
### Option A: From PyPI (Recommended)
```bash
pip install SuperClaude
# Install with interactive selection
SuperClaude install
# That's it! 🎉
```
### Option B: From Source
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install .
# Install with interactive selection
SuperClaude install
# That's it! 🎉
```
### Option C: From npm (Global, after publishing this won't works for now)
```bash
npm install -g superclaude
superclaude --help
```
- Requires package to be published on npmjs.org.
- Installs the npm wrapper and sets up SuperClaude via pip.
### Option D: From npm (Local Project this won't works for now)
```bash
npm install superclaude
npx superclaude --help
```
- Installs SuperClaude wrapper inside your project.
- Use `npx` to run it locally.
- Also requires publishing to npmjs.org.
### Option E: From GitHub (Works without npm publish)
```bash
# Global install directly from GitHub
yarn global add github:SuperClaude-Org/SuperClaude_Framework
# or
npm install -g github:SuperClaude-Org/SuperClaude_Framework
superclaude --help
```
```bash
# Local project install from GitHub
npm install github:SuperClaude-Org/SuperClaude_Framework
npx superclaude --help
```
- Works immediately without publishing to npm registry.
- Runs SuperClaude instantly.
- First run may install Python package via pip.
- Subsequent runs skip reinstallation unless explicitly updated.
---
**What you just got:**
- ✅ 21 intelligent commands that auto-activate specialized capabilities
- ✅ 13 specialized AI agents with domain expertise and smart routing
- ✅ 5 behavioral modes for different types of work
- ✅ 6 MCP servers for extended functionality (optional)
- ✅ Session lifecycle management with persistent context
- ✅ About 2 minutes of your time and ~50MB disk space
**Nervous about what it will do?** See first with:
```bash
SuperClaude install --dry-run
```
## Before You Start 🔍
### What You Need 💻
SuperClaude works on **Windows**, **macOS**, and **Linux**. Here's what you need:
**Required:**
- **Python 3.8 or newer** - The framework is written in Python
- **Claude Code** - SuperClaude enhances Claude Code, so you need it installed first
**Optional (but recommended):**
- **Node.js 16+** - Only needed if you want MCP server integration
- **Git** - Helpful for development workflows
### Quick Check 🔍
Before installing, let's make sure you have the basics:
```bash
# Check Python version (should be 3.8+)
python3 --version
# Check if Claude Code is available
claude --version
# Check Node.js (optional, for MCP servers)
node --version
```
If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below.
## Installation Options 🎛️
### 🎯 Interactive Installation (Default - Recommended)
```bash
SuperClaude install
```
- **Stage 1**: Select MCP servers (Context7, Sequential, Magic, Playwright, etc.)
- **Stage 2**: Choose framework components (Core, Commands, Agents, Modes)
- **Time**: ~3-5 minutes depending on selections
- **Space**: ~50-100MB depending on selections
- **Good for**: All users - gives you full control over what gets installed
- **Interactive**: Shows detailed descriptions and lets you pick exactly what you want
### ⚡ Component-Specific Installation
```bash
SuperClaude install --components core commands modes
```
- **What**: Install only specific components you need
- **Available components**: core, commands, agents, modes, mcp, mcp_docs
- **Good for**: Users who know exactly what they want
### 🔍 Other Useful Options
```bash
# See all available components
SuperClaude install --list-components
# See what would be installed without doing it
SuperClaude install --dry-run
# System diagnostics and installation help
SuperClaude install --diagnose
# Quiet installation (minimal output)
SuperClaude install --quiet
# Install everything
SuperClaude install --components all
```
## Step-by-Step Installation 📋
### Prerequisites Setup 🛠️
**Missing Python?**
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip
# macOS
brew install python3
# Windows
# Download from https://python.org/downloads/
# Or use winget
winget install python
```
**Missing Claude Code?**
- Visit https://claude.ai/code for installation instructions
- SuperClaude enhances Claude Code, so you need it first
**Missing Node.js? (Optional)**
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install nodejs npm
# macOS
brew install node
# Windows
# Download from https://nodejs.org/
# Or use winget
winget install nodejs
```
### Getting SuperClaude 📥
**Option 1: From PyPI (Recommended)**
```bash
pip install SuperClaude
```
**Option 2: Clone from Git**
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install .
```
### Running the Installer 🎬
The installer is smart and will guide you through the process:
```bash
# See all available options
SuperClaude install --help
# Interactive installation (recommended)
SuperClaude install
# Want to see what would happen first?
SuperClaude install --dry-run
# Install specific components
SuperClaude install --components core commands agents modes
# Quiet installation (minimal output)
SuperClaude install --quiet
```
### During Installation 📱
Here's what happens when you install:
1. **System Check** - Verifies you have required dependencies
2. **Component Selection** - Interactive selection of what to install
3. **MCP Server Setup** - Downloads and configures MCP servers (if selected)
4. **API Key Collection** - Prompts for required API keys for selected servers
5. **Framework Installation** - Copies framework documentation files
6. **Configuration Setup** - Creates settings and CLAUDE.md imports
7. **Validation** - Tests that everything works
The installer shows progress and will tell you if anything goes wrong.
## After Installation ✅
### Quick Test 🧪
Let's make sure everything worked:
```bash
# Check if files were installed
ls ~/.claude/
# Should show: CLAUDE.md, RULES.md, PRINCIPLES.md, etc.
```
**Test with Claude Code:**
1. Open Claude Code
2. Try typing `/sc:help` - you should see SuperClaude commands
3. Try `/sc:analyze --help` - should show command options
### What Got Installed 📂
SuperClaude installs to `~/.claude/` by default. Here's what you'll find:
```
~/.claude/
├── CLAUDE.md # Main framework entry point
├── FLAGS.md # Command flags and options
├── PRINCIPLES.md # Development principles
├── RULES.md # Operational rules
├── MCP_*.md # MCP server configurations
├── MODE_*.md # Behavioral modes
├── settings.json # Configuration file (if created)
└── SuperClaude/ # Framework components
├── Core/ # Core framework files
├── Commands/ # 21 command definitions
├── Agents/ # 13 specialized agents
├── Modes/ # 5 behavioral modes
└── MCP/ # MCP server configurations
```
**What each file does:**
- **CLAUDE.md** - Tells Claude Code about SuperClaude and loads other files
- **RULES.md** - Operational rules and workflow patterns
- **PRINCIPLES.md** - Development principles and decision frameworks
- **FLAGS.md** - Command flags and behavioral controls
- **SuperClaude/** - Complete framework with commands, agents, and modes
### First Steps 🎯
Try these commands to get started:
```bash
# In Claude Code, try these:
/sc:help # See available commands
/sc:analyze README.md # Analyze a file
/sc:build --help # See build options
/sc:improve --help # See improvement options
/sc:brainstorm "my app idea" # Try brainstorming mode
/sc:load # Initialize session with context
```
**Don't worry if it seems overwhelming** - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want.
## Managing Your Installation 🛠️
### Updates 📅
Keep SuperClaude up to date:
```bash
# Update the package
pip install --upgrade SuperClaude
# Reinstall components
SuperClaude install --force
# Update specific components only
SuperClaude install --components core commands --force
```
### Backups 💾
SuperClaude automatically creates backups during installation. You can also create manual backups of your `~/.claude/` directory:
```bash
# Create a backup
cp -r ~/.claude/ ~/.claude_backup_$(date +%Y%m%d)
# Restore from backup
rm -rf ~/.claude/
cp -r ~/.claude_backup_20250115/ ~/.claude/
```
### Uninstallation 🗑️
If you need to remove SuperClaude:
```bash
# Remove just the package
pip uninstall SuperClaude
# Remove all SuperClaude files (keeps your other Claude settings)
rm -rf ~/.claude/SuperClaude/
rm -f ~/.claude/CLAUDE.md ~/.claude/RULES.md ~/.claude/PRINCIPLES.md ~/.claude/FLAGS.md
rm -f ~/.claude/MCP_*.md ~/.claude/MODE_*.md
```
**What gets removed:**
- All SuperClaude files in `~/.claude/`
- The SuperClaude Python package
**What stays:**
- Your other Claude Code settings
- Your projects and other files
- Any backups you created
## Troubleshooting 🔧
### Common Issues 🚨
**"Python not found"**
```bash
# Try python instead of python3
python --version
# Or check if it's installed but not in PATH
which python3
```
**"Claude Code not found"**
- Make sure Claude Code is installed first
- Visit https://claude.ai/code for installation help
**"Permission denied"**
```bash
# Try with explicit Python path
/usr/bin/python3 -m SuperClaude install
# Or check if you need different permissions
ls -la ~/.claude/
```
**"MCP servers won't install"**
- Check that Node.js is installed: `node --version`
- Check that npm is available: `npm --version`
- Try installing without MCP first: select "Skip MCP Server installation" during interactive setup
**"Installation fails partway through"**
```bash
# Try with verbose output to see what's happening
SuperClaude install --verbose
# Or try a dry run first
SuperClaude install --dry-run
# Try system diagnostics
SuperClaude install --diagnose
```
### Platform-Specific Issues 🖥️
**Windows:**
- Use `python` instead of `python3` if you get "command not found"
- Run Command Prompt as Administrator if you get permission errors
- Make sure Python is in your PATH
**macOS:**
- You might need to approve SuperClaude in Security & Privacy settings
- Use `brew install python3` if you don't have Python 3.8+
- Try using `python3` explicitly instead of `python`
**Linux:**
- Make sure you have `python3-pip` installed
- You might need `sudo` for some package installations
- Check that `~/.local/bin` is in your PATH
### Still Having Issues? 🤔
**Check our troubleshooting resources:**
- GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
- Look for existing issues similar to yours
- Create a new issue if you can't find a solution
**When reporting bugs, please include:**
- Your operating system and version
- Python version (`python3 --version`)
- Claude Code version (`claude --version`)
- The exact command you ran
- The complete error message
- What you expected to happen
## Advanced Options ⚙️
### Custom Installation Directory
```bash
# Install to custom location
SuperClaude install --install-dir /custom/path
# Use environment variable
export SUPERCLAUDE_DIR=/custom/path
SuperClaude install
```
### Development Setup
If you're planning to contribute or modify SuperClaude:
```bash
# Clone the repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# Install in development mode
pip install -e .
# Install all components
SuperClaude install --components all
```
## What's Next? 🚀
**Now that SuperClaude is installed:**
1. **Just start using it** - Try `/sc:analyze some-file.js` or `/sc:build` and see what happens ✨
2. **Don't stress about learning** - SuperClaude usually figures out what you need
3. **Experiment freely** - Commands like `/sc:improve` and `/sc:troubleshoot` are pretty forgiving
4. **Use session management** - Try `/sc:load` and `/sc:save` for persistent context ([Session Management Guide](session-management.md))
5. **Explore behavioral modes** - Let SuperClaude adapt to your workflow automatically ([Behavioral Modes Guide](behavioral-modes-guide.md))
6. **Give feedback** - Let us know what works and what doesn't
**The real secret**: SuperClaude is designed to enhance your existing workflow without you having to learn a bunch of new stuff. Just use it like you'd use regular Claude Code, but notice how much smarter it gets! 🎯
**Still feeling uncertain?** Start with just `/sc:help` and `/sc:analyze README.md` - you'll see how approachable it actually is.
**Next Steps:**
- [Examples Cookbook](examples-cookbook.md) - Copy-paste commands for common tasks
- [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview
- [Commands Guide](commands-guide.md) - All 21 commands with examples
---
## Final Notes 📝
- **Installation takes 1-5 minutes** depending on what you choose
- **Disk space needed: 20-100MB** (not much!)
- **Works alongside existing tools** - doesn't interfere with your setup
- **Easy to uninstall** if you change your mind
- **Community supported** - we actively read and respond to issues
- **Available commands**: Use `SuperClaude [command]`, `python3 -m SuperClaude [command]`, or `/sc:[command]` in Claude Code
Thanks for trying SuperClaude! We hope it makes your development workflow smoother and more intelligent. 🙂
---
## Related Guides
**🚀 What to Do Next (Essential)**
- [Examples Cookbook](examples-cookbook.md) - Copy-paste commands to get started immediately
- [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview and philosophy
**📚 Learning the System (Recommended)**
- [Commands Guide](commands-guide.md) - All 21 commands with practical examples
- [Session Management Guide](session-management.md) - Persistent context and project memory
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How SuperClaude adapts automatically
**🔧 When You Need Help**
- [Troubleshooting Guide](troubleshooting-guide.md) - Solutions for installation and usage issues
- [Best Practices Guide](best-practices.md) - Proven patterns for effective usage
**🎯 Advanced Usage (Optional)**
- [Agents Guide](agents-guide.md) - Understanding the 13 specialized AI experts
- [Flags Guide](flags-guide.md) - Manual control and optimization options
- [Technical Architecture Guide](technical-architecture.md) - Internal system design
**📖 Recommended Reading Path After Installation:**
1. [Examples Cookbook](examples-cookbook.md) - Try commands immediately
2. [Commands Guide](commands-guide.md) - Learn your toolkit
3. [Session Management Guide](session-management.md) - Enable persistent context
4. [Best Practices Guide](best-practices.md) - Optimize your workflow
---
*Last updated: August 2025 - Let us know if anything in this guide is wrong or confusing!*

882
Guides/session-management.md
View File

@ -1,882 +0,0 @@
# SuperClaude Session Management Guide
## Introduction
SuperClaude's session management system transforms Claude Code into a persistent, context-aware development partner. Unlike traditional AI interactions that reset with each conversation, SuperClaude maintains project memory, learning patterns, and development context across multiple sessions. See [Examples Cookbook](examples-cookbook.md) for practical session workflows.
### What Session Management Provides
**Persistent Context**: Your project understanding, architectural decisions, and development patterns survive session boundaries and accumulate over time.
**Cross-Session Learning**: SuperClaude builds comprehensive project knowledge, remembering code patterns, design decisions, and implementation approaches.
**Intelligent Checkpoints**: Automatic state preservation ensures you never lose progress on complex development tasks.
**Memory-Driven Workflows**: Task hierarchies, discovered patterns, and project insights are preserved and enhanced across sessions.
**Seamless Resumption**: Pick up exactly where you left off with full context restoration and intelligent state analysis.
## Core Concepts
### Session States
SuperClaude sessions exist in distinct states that determine available capabilities and behavior:
**Uninitialized Session**
- No project context loaded
- Limited to basic Claude Code capabilities
- No memory persistence or cross-session learning
- Manual project discovery required for each task
**Active Session**
- Project context loaded via `/sc:load`
- Full SuperClaude capabilities available
- Memory persistence enabled through Serena MCP
- Cross-session learning and pattern recognition active
- Automatic checkpoint creation based on activity
**Checkpointed Session**
- Critical states preserved for recovery
- Task hierarchies and progress maintained
- Discoveries and patterns archived
- Recovery points for complex operations
**Archived Session**
- Completed projects with preserved insights
- Historical context available for future reference
- Pattern libraries built from successful implementations
- Learning artifacts maintained for similar projects
### Context Types
SuperClaude manages multiple context layers:
**Project Context**
- Directory structure and file organization
- Dependency mappings and architectural patterns
- Code style preferences and team conventions
- Build systems and development workflows
**Task Context**
- Current work objectives and completion criteria
- Multi-step operations with dependency tracking
- Quality gates and validation requirements
- Progress checkpoints and recovery states
**Learning Context**
- Discovered patterns and successful approaches
- Architectural decisions and their outcomes
- Problem-solving strategies that worked
- Anti-patterns and approaches to avoid
**Session Metadata**
- Temporal information and session duration
- Tool usage patterns and efficiency metrics
- Quality assessments and reflection insights
- Cross-session relationship tracking
### Memory Organization
SuperClaude organizes persistent memory using a structured hierarchy:
```
plan_[timestamp]: Overall goals and objectives
phase_[1-5]: Major milestone descriptions
task_[phase].[number]: Specific deliverable status
todo_[task].[number]: Atomic action completion
checkpoint_[timestamp]: State snapshots for recovery
blockers: Active impediments requiring attention
decisions: Key architectural choices made
patterns: Successful approaches discovered
insights: Cross-session learning artifacts
```
## Session Commands
### /sc:load - Project Context Loading
**Purpose**: Initialize session with project context and cross-session memory retrieval
**Syntax**:
```bash
/sc:load [target] [--type project|config|deps|checkpoint] [--refresh] [--analyze]
```
**Behavioral Flow**:
1. **Initialize**: Establish Serena MCP connection for memory management
2. **Discover**: Analyze project structure and identify context requirements
3. **Load**: Retrieve memories, checkpoints, and cross-session persistence data
4. **Activate**: Establish project context and prepare development workflow
5. **Validate**: Ensure loaded context integrity and session readiness
**Examples**:
```bash
# Basic project loading - most common usage
/sc:load
# Loads current directory with memory integration
# Establishes session context for development work
# Specific project with analysis
/sc:load /path/to/project --type project --analyze
# Loads specific project with comprehensive analysis
# Activates context and retrieves cross-session memories
# Checkpoint restoration
/sc:load --type checkpoint --checkpoint session_123
# Restores specific checkpoint with session context
# Continues previous work with full context preservation
# Dependency context refresh
/sc:load --type deps --refresh
# Updates dependency understanding and mappings
# Refreshes project analysis with current state
```
**Performance**: Target <500ms initialization, <200ms for core operations
### /sc:save - Session Context Persistence
**Purpose**: Preserve session context, discoveries, and progress for cross-session continuity
**Syntax**:
```bash
/sc:save [--type session|learnings|context|all] [--summarize] [--checkpoint]
```
**Behavioral Flow**:
1. **Analyze**: Examine session progress and identify discoveries worth preserving
2. **Persist**: Save context and learnings using Serena MCP memory management
3. **Checkpoint**: Create recovery points for complex sessions
4. **Validate**: Ensure data integrity and cross-session compatibility
5. **Prepare**: Ready context for seamless future session continuation
**Examples**:
```bash
# Basic session save - automatic checkpoint if >30min
/sc:save
# Saves discoveries and context to Serena MCP
# Creates checkpoint for sessions exceeding 30 minutes
# Comprehensive checkpoint with recovery state
/sc:save --type all --checkpoint
# Complete session preservation with recovery capability
# Includes learnings, context, and progress state
# Session summary with discovery documentation
/sc:save --summarize
# Creates session summary with discovery patterns
# Updates cross-session learning and project insights
# Discovery-only persistence
/sc:save --type learnings
# Saves only new patterns and insights
# Updates project understanding without full preservation
```
**Automatic Triggers**:
- Session duration >30 minutes
- Complex task completion
- Major architectural decisions
- Error recovery scenarios
- Quality gate completions
### /sc:reflect - Task Reflection and Validation
**Purpose**: Analyze session progress, validate task adherence, and capture learning insights
**Syntax**:
```bash
/sc:reflect [--type task|session|completion] [--analyze] [--validate]
```
**Behavioral Flow**:
1. **Analyze**: Examine task state and session progress using Serena reflection tools
2. **Validate**: Assess task adherence, completion quality, and requirement fulfillment
3. **Reflect**: Apply deep analysis of collected information and insights
4. **Document**: Update session metadata and capture learning patterns
5. **Optimize**: Provide recommendations for process improvement
**Examples**:
```bash
# Task adherence validation
/sc:reflect --type task --analyze
# Validates current approach against project goals
# Identifies deviations and recommends course corrections
# Session progress analysis
/sc:reflect --type session --validate
# Comprehensive analysis of session work and information gathering
# Quality assessment and gap identification
# Completion criteria evaluation
/sc:reflect --type completion
# Evaluates task completion against actual progress
# Determines readiness and identifies remaining blockers
```
**Reflection Tools Integration**:
- `think_about_task_adherence`: Goal alignment validation
- `think_about_collected_information`: Session work analysis
- `think_about_whether_you_are_done`: Completion assessment
## Session Lifecycle
### Session Initialization Workflow
**Step 1: Environment Assessment**
```bash
# SuperClaude analyzes current environment
- Directory structure and project type detection
- Existing configuration and dependency analysis
- Previous session memory availability check
- Development tool and framework identification
```
**Step 2: Context Loading**
```bash
/sc:load
# Triggers comprehensive context establishment:
- Serena MCP connection initialization
- Project memory retrieval from previous sessions
- Code pattern analysis and architectural understanding
- Development workflow preference loading
```
**Step 3: Session Activation**
```bash
# SuperClaude prepares active development environment:
- Agent specialization activation based on project type
- MCP server integration for enhanced capabilities
- Memory-driven task management preparation
- Cross-session learning pattern application
```
### Active Session Operations
**Continuous Context Management**:
- Real-time memory updates during development work
- Pattern recognition and learning capture
- Automatic checkpoint creation at critical junctures
- Cross-session insight accumulation and refinement
**Task Management Integration**:
```bash
# Task Management Mode with Memory
📋 Plan → write_memory("plan", goal_statement)
→ 🎯 Phase → write_memory("phase_X", milestone)
→ 📦 Task → write_memory("task_X.Y", deliverable)
→ ✓ Todo → TodoWrite + write_memory("todo_X.Y.Z", status)
```
**Quality Gate Integration**:
- Validation checkpoints with memory persistence
- Reflection triggers for major decisions
- Learning capture during problem resolution
- Pattern documentation for future reference
### Session Completion and Persistence
**Step 1: Progress Assessment**
```bash
/sc:reflect --type completion
# Evaluates session outcomes:
- Task completion against original objectives
- Quality assessment of delivered work
- Learning insights and pattern discoveries
- Blockers and remaining work identification
```
**Step 2: Context Preservation**
```bash
/sc:save --type all --summarize
# Comprehensive session archival:
- Complete context state preservation
- Discovery documentation and pattern capture
- Cross-session learning artifact creation
- Recovery checkpoint establishment
```
**Step 3: Session Closure**
```bash
# SuperClaude completes session lifecycle:
- Memory optimization and cleanup
- Temporary state removal
- Cross-session relationship establishment
- Future session preparation
```
### Session Resumption Workflow
**Context Restoration**:
```bash
/sc:load
# Intelligent session restoration:
1. list_memories() → Display available context
2. read_memory("current_plan") → Resume primary objectives
3. think_about_collected_information() → Understand progress state
4. Project context reactivation with full capability restoration
```
**State Analysis**:
```bash
# SuperClaude analyzes restoration context:
- Progress evaluation against previous session objectives
- Context gap identification and resolution
- Workflow continuation strategy determination
- Enhanced capability activation based on accumulated learning
```
## Context Management
### Project Context Layers
**File System Context**:
- Directory structure and organization patterns
- File naming conventions and categorization
- Configuration file relationships and dependencies
- Build artifact and output directory management
**Code Context**:
- Architectural patterns and design principles
- Code style and formatting preferences
- Dependency usage patterns and import conventions
- Testing strategies and quality assurance approaches
**Development Context**:
- Workflow patterns and tool preferences
- Debugging strategies and problem-solving approaches
- Performance optimization patterns and techniques
- Security considerations and implementation strategies
**Team Context**:
- Collaboration patterns and communication preferences
- Code review standards and quality criteria
- Documentation approaches and maintenance strategies
- Deployment and release management patterns
### Context Persistence Strategies
**Incremental Context Building**:
- Session-by-session context enhancement
- Pattern recognition and abstraction
- Anti-pattern identification and avoidance
- Success strategy documentation and refinement
**Context Validation**:
- Regular context integrity checks
- Outdated information identification and removal
- Context relationship validation and maintenance
- Cross-session consistency enforcement
**Context Optimization**:
- Memory usage optimization for large projects
- Context relevance scoring and prioritization
- Selective context loading based on task requirements
- Performance-critical context caching strategies
### Memory Management Patterns
**Memory Types**:
**Temporary Memory**: Session-specific, cleanup after completion
```bash
checkpoint_[timestamp]: Recovery states
todo_[task].[number]: Atomic action tracking
blockers: Current impediments
working_context: Active development state
```
**Persistent Memory**: Cross-session preservation
```bash
plan_[timestamp]: Project objectives
decisions: Architectural choices
patterns: Successful approaches
insights: Learning artifacts
```
**Archived Memory**: Historical reference
```bash
completed_phases: Finished milestone documentation
resolved_patterns: Successful problem solutions
performance_optimizations: Applied improvements
security_implementations: Implemented protections
```
## Checkpointing
### Automatic Checkpoint Creation
**Time-Based Triggers**:
- Session duration exceeding 30 minutes
- Continuous development work >45 minutes
- Complex task sequences >1 hour
- Daily development session boundaries
**Event-Based Triggers**:
- Major architectural decision implementation
- Significant code refactoring completion
- Error recovery and problem resolution
- Quality gate completion and validation
**Progress-Based Triggers**:
- Task phase completion in complex workflows
- Multi-file operation completion
- Testing milestone achievement
- Documentation generation completion
### Manual Checkpoint Strategies
**Strategic Checkpoints**:
```bash
/sc:save --checkpoint --type all
# Before risky operations:
- Major refactoring initiatives
- Architectural pattern changes
- Dependency updates or migrations
- Performance optimization attempts
```
**Milestone Checkpoints**:
```bash
/sc:save --summarize --checkpoint
# At development milestones:
- Feature completion and testing
- Integration points and API implementations
- Security feature implementations
- Performance target achievements
```
**Recovery Checkpoints**:
```bash
/sc:save --type context --checkpoint
# Before complex debugging:
- Multi-component failure investigation
- Performance bottleneck analysis
- Security vulnerability remediation
- Integration issue resolution
```
### Checkpoint Management
**Checkpoint Naming Conventions**:
```bash
session_[timestamp]: Regular session preservation
milestone_[feature]: Feature completion states
recovery_[issue]: Problem resolution points
decision_[architecture]: Major choice documentation
```
**Checkpoint Validation**:
- Context integrity verification
- Memory consistency checking
- Cross-session compatibility validation
- Recovery state functionality testing
**Checkpoint Cleanup**:
- Automatic removal of outdated temporary checkpoints
- Consolidation of related checkpoint sequences
- Archive creation for completed project phases
- Memory optimization through selective retention
## Cross-Session Workflows
### Long-Term Project Development
**Project Initiation Session**:
```bash
Session 1: Project Analysis and Planning
/sc:load # Initialize new project
/sc:analyze . # Comprehensive project analysis
/sc:brainstorm "modernization strategy" # Interactive requirement discovery
/sc:save --type all --summarize # Preserve initial insights
```
**Implementation Sessions**:
```bash
Session 2-N: Iterative Development
/sc:load # Resume with full context
/sc:reflect --type session # Validate progress continuation
[Development work with automatic checkpointing]
/sc:save --checkpoint # Preserve progress state
```
**Completion Session**:
```bash
Final Session: Project Completion
/sc:load # Final context restoration
/sc:reflect --type completion # Comprehensive completion assessment
/sc:save --type all --summarize # Archive complete project insights
```
### Collaborative Development Patterns
**Context Sharing Strategies**:
- Team-specific memory organization
- Shared pattern libraries and conventions
- Collaborative checkpoint management
- Cross-team insight documentation
**Handoff Workflows**:
```bash
Developer A Completion:
/sc:save --type all --summarize
# Complete context documentation for handoff
Developer B Resumption:
/sc:load --analyze
# Context restoration with comprehension validation
```
### Multi-Project Context Management
**Project Isolation**:
- Separate memory namespaces per project
- Context switching with state preservation
- Project-specific pattern libraries
- Independent checkpoint management
**Cross-Project Learning**:
- Pattern sharing between related projects
- Architecture decision documentation
- Solution library accumulation
- Best practice consolidation
### Complex Task Continuation
**Multi-Session Task Management**:
```bash
Session 1: Task Initiation
write_memory("plan_auth", "Implement JWT authentication")
write_memory("phase_1", "Analysis and design")
TodoWrite: Create detailed task breakdown
Session 2: Implementation Continuation
list_memories() → Shows previous context
read_memory("plan_auth") → Resume objectives
think_about_collected_information() → Progress assessment
Continue implementation with full context
```
**Cross-Session Quality Gates**:
- Validation checkpoints across session boundaries
- Quality criteria persistence and evaluation
- Cross-session testing strategy continuation
- Performance monitoring across development phases
## Session Optimization
### Best Practices for Effective Sessions
**Session Initialization Optimization**:
```bash
# Efficient session startup pattern
/sc:load --analyze # Load with immediate analysis
/sc:reflect --type session # Validate continuation strategy
[Focused development work]
/sc:save --checkpoint # Regular progress preservation
```
**Memory Management Optimization**:
- Regular memory cleanup of temporary artifacts
- Strategic memory organization for quick retrieval
- Context relevance validation and maintenance
- Performance monitoring for large project contexts
**Task Management Optimization**:
- Clear objective definition and persistence
- Progress tracking with meaningful checkpoints
- Quality gate integration with validation
- Learning capture and pattern documentation
### Performance Considerations
**Session Startup Performance**:
- Target <500ms for context loading
- <200ms for memory operations
- <1s for checkpoint creation
- Optimal balance between completeness and speed
**Memory Performance**:
- Efficient storage patterns for large codebases
- Selective context loading based on task scope
- Memory compression for archived sessions
- Cache optimization for frequently accessed patterns
**Cross-Session Performance**:
- Context relationship optimization
- Pattern matching acceleration
- Learning algorithm efficiency
- Cleanup automation for memory optimization
### Session Efficiency Patterns
**Focused Session Design**:
- Clear session objectives and success criteria
- Scope limitation for manageable complexity
- Quality gate integration for validation
- Learning capture for future efficiency
**Context Reuse Strategies**:
- Pattern library development and maintenance
- Solution template creation and application
- Architecture decision documentation and reuse
- Best practice consolidation and application
**Automation Integration**:
- Automatic checkpoint creation based on activity
- Quality gate automation with context persistence
- Pattern recognition and application automation
- Learning capture automation for efficiency
## Advanced Session Patterns
### Multi-Layer Context Management
**Context Hierarchies**:
```bash
Global Context: Organization patterns and standards
Project Context: Specific project architecture and decisions
Feature Context: Feature-specific patterns and implementations
Task Context: Immediate work objectives and constraints
```
**Context Inheritance Patterns**:
- Global patterns inherited by projects
- Project decisions applied to features
- Feature patterns available to tasks
- Task insights contributed to higher levels
**Context Specialization**:
- Domain-specific context layers (frontend, backend, security)
- Technology-specific patterns and conventions
- Quality-specific criteria and validation approaches
- Performance-specific optimization strategies
### Adaptive Session Management
**Context-Aware Session Adaptation**:
- Session behavior modification based on project type
- Tool selection optimization based on context history
- Agent activation patterns based on accumulated learning
- Quality gate customization based on project requirements
**Learning-Driven Session Evolution**:
- Session pattern optimization based on success metrics
- Context organization improvement through usage analysis
- Memory management refinement through performance monitoring
- Checkpoint strategy optimization through recovery analysis
**Predictive Session Features**:
- Next-step suggestion based on context patterns
- Resource requirement prediction based on task analysis
- Quality issue prediction based on historical patterns
- Performance bottleneck prediction based on context analysis
### Power User Techniques
**Session Orchestration**:
```bash
# Complex multi-session orchestration
/sc:load --type checkpoint --analyze # Strategic restoration
/sc:reflect --type task --validate # Comprehensive validation
[Orchestrated development with multiple agents and tools]
/sc:save --type all --summarize # Complete preservation
```
**Memory Pattern Development**:
- Custom memory schemas for specialized workflows
- Pattern template creation for repeated tasks
- Context relationship modeling for complex projects
- Learning acceleration through pattern recognition
**Cross-Session Analytics**:
- Session efficiency analysis and optimization
- Context usage pattern analysis and refinement
- Quality outcome correlation with session patterns
- Performance optimization through session analytics
**Advanced Integration Patterns**:
- Multi-MCP server coordination with context awareness
- Agent specialization with session-specific optimization
- Tool selection matrix optimization based on session history
- Quality gate customization with context-aware validation
## Troubleshooting Sessions
### Common Session Issues
**Context Loading Problems**:
**Symptom**: Session fails to load project context
```bash
Error: "Failed to activate project context"
Solution:
1. Verify Serena MCP server connection
2. Check project directory permissions
3. Validate memory integrity with list_memories()
4. Reinitialize with /sc:load --refresh
```
**Symptom**: Incomplete context restoration
```bash
Issue: Missing project patterns or decisions
Diagnosis:
1. /sc:reflect --type session --analyze
2. Check memory completeness with list_memories()
3. Validate context relationships
Resolution:
1. Manual context restoration from checkpoints
2. Pattern rediscovery through analysis
3. Context rebuild with /sc:load --analyze
```
**Memory Management Issues**:
**Symptom**: Memory operations timeout or fail
```bash
Error: "Memory operation exceeded timeout"
Solution:
1. Check Serena MCP server health
2. Optimize memory size through cleanup
3. Validate memory schema consistency
4. Reinitialize session with fresh context
```
**Symptom**: Context inconsistency across sessions
```bash
Issue: Different behavior between sessions
Diagnosis:
1. Compare memory states with list_memories()
2. Validate context integrity
3. Check for corrupted checkpoints
Resolution:
1. Restore from known-good checkpoint
2. Rebuild context through fresh analysis
3. Consolidate memory with cleanup
```
### Performance Troubleshooting
**Slow Session Initialization**:
**Diagnosis**:
```bash
# Performance analysis
/sc:load --analyze # Time context loading
list_memories() # Check memory size
/sc:reflect --type session --analyze # Assess context complexity
```
**Optimization**:
```bash
# Memory optimization
/sc:save --type learnings # Preserve insights only
[Clean up temporary memories]
/sc:load --refresh # Fresh initialization
```
**Memory Performance Issues**:
**Large Project Context Management**:
- Selective context loading based on task scope
- Memory compression for archived sessions
- Context segmentation for performance
- Cleanup automation for memory optimization
**Cross-Session Performance Optimization**:
- Context relationship streamlining
- Pattern matching algorithm optimization
- Learning algorithm efficiency improvement
- Memory access pattern optimization
### Recovery Procedures
**Complete Session Recovery**:
```bash
# When session state is completely lost
1. /sc:load --type checkpoint --checkpoint [last_known_good]
2. /sc:reflect --type session --validate
3. Manual context verification and supplementation
4. /sc:save --checkpoint # Create new recovery point
```
**Partial Context Recovery**:
```bash
# When some context is available but incomplete
1. list_memories() # Assess available context
2. /sc:load --analyze # Attempt restoration
3. /sc:reflect --type completion # Identify gaps
4. Manual gap filling through analysis
5. /sc:save --type all # Preserve recovered state
```
**Memory Corruption Recovery**:
```bash
# When memory contains inconsistent or corrupted data
1. Backup current state: /sc:save --checkpoint
2. Clean corrupted memories: delete_memory([corrupted_keys])
3. Restore from archived checkpoints
4. Rebuild context through fresh analysis
5. Validate recovery: /sc:reflect --type session --validate
```
### Session Health Monitoring
**Session Health Indicators**:
- Context loading time (<500ms target)
- Memory operation performance (<200ms target)
- Cross-session consistency validation
- Learning accumulation and pattern recognition
**Proactive Health Management**:
- Regular memory optimization and cleanup
- Context integrity validation
- Performance monitoring and optimization
- Checkpoint validation and maintenance
**Health Diagnostics**:
```bash
# Comprehensive session health check
/sc:load --analyze # Context loading assessment
list_memories() # Memory state evaluation
/sc:reflect --type session --validate # Context integrity check
[Performance monitoring during operations]
/sc:save --summarize # Health documentation
```
This comprehensive session management system transforms SuperClaude from a stateless AI assistant into a persistent, learning development partner that accumulates project knowledge and improves its assistance over time. The combination of intelligent memory management, automatic checkpointing, and cross-session learning creates a development experience that truly adapts to your projects and workflows.
## Related Guides
**🚀 Foundation (Start Here First)**
- [Installation Guide](installation-guide.md) - Ensure SuperClaude is properly installed with MCP servers
- [SuperClaude User Guide](superclaude-user-guide.md) - Understanding persistent intelligence concepts
- [Examples Cookbook](examples-cookbook.md) - Working session workflows and patterns
**🛠️ Core Session Usage (Essential)**
- [Commands Guide](commands-guide.md) - Session commands (/sc:load, /sc:save, /sc:reflect)
- [Agents Guide](agents-guide.md) - How agents coordinate across sessions
- [Behavioral Modes Guide](behavioral-modes-guide.md) - Mode persistence and adaptation
**⚙️ Advanced Session Techniques (Power Users)**
- [Best Practices Guide](best-practices.md) - Session optimization and workflow patterns
- [Flags Guide](flags-guide.md) - Session-related flags and control options
- [Technical Architecture Guide](technical-architecture.md) - Memory system and checkpoint implementation
**🔧 Session Troubleshooting**
- [Troubleshooting Guide](troubleshooting-guide.md) - Session loading, memory, and persistence issues
**📖 Recommended Learning Path:**
1. [Examples Cookbook](examples-cookbook.md) - Try basic session workflows
2. [Commands Guide](commands-guide.md) - Master /sc:load, /sc:save, /sc:reflect
3. [Best Practices Guide](best-practices.md) - Learn checkpoint and workflow patterns
4. Advanced techniques in this guide for complex projects
**🎯 Session Management Mastery:**
- **Beginner**: Basic /sc:load and /sc:save usage
- **Intermediate**: Checkpoint strategies and cross-session workflows
- **Advanced**: Memory optimization and custom session patterns
- **Expert**: Multi-project context management and session analytics

312
Guides/superclaude-user-guide.md
View File

@ -1,312 +0,0 @@
# SuperClaude User Guide
## The Simple Truth
**Behind the apparent complexity, SuperClaude is actually simple to use.**
You don't need to learn all the commands, flags, and agents. Just start using it!
SuperClaude has an **intelligent routing system** that tries to figure out what you need:
- Type `/analyze some-code/` → It picks the right analysis tools
- Ask about security → Security expert auto-activates
- Work on frontend → UI specialist takes over
- Debug something → Investigation mode kicks in
**Learning emerges during use** - you'll naturally discover what works without studying manuals first.
The detailed guides below? They're here **when you want to understand** what just happened or dive deeper. But honestly? Most of the time you can just wing it.
---
**TL;DR**: Install it ([Installation Guide](installation-guide.md)), try `/analyze` or `/build` on your code, watch the magic happen. See [Examples Cookbook](examples-cookbook.md) for copy-paste commands.
---
## Just Start Here
**Want to skip the reading and jump right in?** Here's your 2-minute getting started:
```bash
# Try these commands in Claude Code:
/sc:load # Initialize session with project context
/sc:analyze README.md # SuperClaude analyzes your project
/sc:brainstorm "task app" # Interactive requirements discovery
/sc:implement user-auth # Create features and components
/sc:build # Smart build with auto-optimization
/sc:improve messy-file.js # Clean up code automatically
/sc:save # Save session state and insights
```
**What just happened?** SuperClaude automatically:
- Initialized persistent session context
- Picked the right tools for each task
- Activated appropriate specialized agents
- Applied intelligent flags and optimizations
- Provided evidence-based suggestions
- Saved insights for future sessions
**See how easy that was?** No studying required - SuperClaude figures out the complexity so you don't have to.
Want to understand how it works? Keep reading. Want to just keep experimenting? Go for it!
---
## Welcome & Overview
### What is SuperClaude Really?
SuperClaude makes Claude Code smarter for development work. Instead of generic responses, you get specialized help from different agents (security, performance, frontend, etc.) who know their stuff, plus session persistence and behavioral intelligence.
**The honest truth**: SuperClaude v4.0.0 represents a major architectural evolution with new session lifecycle management and behavioral modes. It's significantly more capable than v3, with better context management and intelligent agent coordination.
**The neat part?** You don't need to manage any of this complexity. Just use normal commands like `/analyze` or `/build` and SuperClaude usually figures out which experts to involve and what tools to use.
### What SuperClaude Adds
**21 Specialized Commands** ([Commands Guide](commands-guide.md))
- **Planning tools**: `/estimate`, `/task`, `/brainstorm`
- **Development tools**: `/implement`, `/build`, `/design`, `/select-tool`
- **Analysis tools**: `/analyze`, `/troubleshoot`, `/explain`
- **Quality tools**: `/improve`, `/cleanup`, `/test`
- **Session tools**: `/load`, `/save`, `/reflect` ([Session Management Guide](session-management.md))
- **Plus utilities** for documentation, git, deployment, and more
**13 Specialized Agents** *(that know when to jump in)* ([Agents Guide](agents-guide.md))
- AI agents that adapt behavior for different domains
- **Auto-activate based on your requests** (security agent for security tasks, etc.)
- Manual control available, but usually not needed
**6 MCP Server Integrations** *(smart external tools)*
- **Context7**: Official library documentation lookup
- **Sequential**: Complex multi-step analysis
- **Magic**: Modern UI component generation
- **Playwright**: Browser automation and testing
- **Morphllm**: Intelligent file editing
- **Serena**: Semantic code analysis and memory
- **Auto-connects when needed** - you don't manage this stuff
**5 Behavioral Modes** *(intelligent adaptation)* ([Behavioral Modes Guide](behavioral-modes-guide.md))
- **Brainstorming Mode**: Interactive requirements discovery
- **Introspection Mode**: Meta-cognitive analysis and debugging
- **Task Management Mode**: Multi-layer orchestration and systematic delegation
- **Token Efficiency Mode**: Smart compression and optimization
- **Orchestration Mode**: Intelligent tool selection and resource efficiency
- **Auto-activate based on context** - you don't configure them
**Session Lifecycle System** *(persistent intelligence)*
- Session initialization with `/sc:load`
- Persistent context and memory across sessions
- Automatic checkpoints and progress tracking
- Session reflection and insights with `/sc:reflect`
- **Cross-session learning** - SuperClaude remembers and improves
### How It Works
**The simple version**: You type something like `/analyze auth.js` and SuperClaude figures out the rest.
**The slightly more detailed version**:
1. **Smart routing** - Analyzes what you're asking for
2. **Auto-expert selection** - Picks the right specialist (security, performance, etc.)
3. **Tool coordination** - Connects to external systems when helpful
4. **Quality assurance** - Makes sure suggestions are solid
**You don't see any of this complexity** - it just feels like Claude got way smarter about development stuff.
---
## Core Components Overview
### Commands: Your Toolkit
Commands are specialized tools that handle specific types of development work. Instead of generic "help me with this," you get purpose-built tools for different scenarios.
**Development**: `/build`, `/design`, `/implement`
**Analysis**: `/analyze`, `/troubleshoot`, `/explain`
**Quality**: `/improve`, `/cleanup`, `/test`
**Session Management**: `/load`, `/save`, `/reflect`
**Planning & Discovery**: `/brainstorm`, `/estimate`, `/task`
**Utilities**: `/document`, `/git`, `/select-tool`, `/spawn`, `/index`
Each command auto-activates appropriate agents and integrates with relevant MCP servers.
### Agents: AI Specialists
13 specialized agents with domain expertise that activate automatically based on your requests:
**🏗️ System Architect** - Architecture design and technical decisions
**🛡️ Security Engineer** - Security analysis and vulnerability assessment
**⚡ Performance Engineer** - Optimization and scalability
**🎨 Frontend Architect** - UI/UX and client-side development
**⚙️ Backend Architect** - Server-side architecture and APIs
**🔍 Root Cause Analyst** - Debugging and problem investigation
**✨ Quality Engineer** - Code quality and testing strategies
**📚 Learning Guide** - Educational explanations and mentoring
**📋 Requirements Analyst** - Requirements discovery and PRDs
**🛠️ DevOps Architect** - Infrastructure and deployment
**🔧 Refactoring Expert** - Code improvement and technical debt
**🐍 Python Expert** - Python-specific development
**📝 Technical Writer** - Documentation and communication
### MCP Servers: External Capabilities
6 specialized external tools that enhance SuperClaude's capabilities:
**Context7** - Official documentation lookup for libraries and frameworks
**Sequential** - Complex multi-step reasoning and analysis
**Magic** - Modern UI component generation from 21st.dev patterns
**Playwright** - Browser automation and E2E testing
**Morphllm** - Pattern-based code editing with token optimization
**Serena** - Semantic code understanding and project memory
### Behavioral Modes: Adaptive Intelligence
5 modes that automatically adapt SuperClaude's behavior:
**Brainstorming Mode** - Activates for vague requests, guides requirement discovery
**Introspection Mode** - Activates for error recovery and complex problem solving
**Task Management Mode** - Activates for multi-step operations and large scope
**Orchestration Mode** - Activates for multi-tool operations and performance needs
**Token Efficiency Mode** - Activates for large operations and resource constraints
---
## Getting Started Workflows
### Your First Session
```bash
# 1. Initialize session context
/sc:load
# 2. Explore your project
/sc:analyze .
# 3. Try interactive discovery
/sc:brainstorm "improve user experience"
# 4. Save your session
/sc:save
```
### Common Development Tasks
**Code Analysis**
```bash
/sc:analyze auth.js --focus security
/sc:explain complex-algorithm.py
/sc:troubleshoot failing-tests/
```
**Feature Development**
```bash
/sc:brainstorm "user dashboard"
/sc:design user-dashboard --type component
/sc:implement user-dashboard
/sc:test user-dashboard
```
**Code Quality**
```bash
/sc:improve legacy-code/
/sc:cleanup technical-debt/
/sc:build --optimize
```
### Working with Different Domains
**Frontend Development**
- Use `/sc:design` for UI components
- Magic MCP auto-activates for modern patterns
- Frontend agent provides specialized guidance
**Backend Development**
- Use `/sc:analyze` for API design
- Context7 MCP provides framework documentation
- Backend agent handles server-side architecture
**Security Analysis**
- Use `/sc:analyze --focus security`
- Security agent auto-activates
- Sequential MCP provides systematic analysis
---
## Key Takeaways
### SuperClaude's Core Value
SuperClaude v4.0.0 transforms Claude Code into an intelligent development partner through:
- **21 specialized commands** including session management and brainstorming
- **13 expert agents** with enhanced coordination and specialization
- **5 behavioral modes** that adapt intelligently to different work types
- **Session persistence** that remembers and learns across sessions
- **Advanced orchestration** with quality gates
- **6 MCP servers** including intelligent editing and semantic analysis
### The Power is in the Coordination
SuperClaude's power comes from intelligent system integration:
- **Session lifecycle** maintains context across all interactions
- **Behavioral modes** adapt automatically to different work patterns
- **Agents coordinate** seamlessly for multi-domain problems
- **MCP servers** integrate intelligently based on task requirements
- **Quality gates** ensure consistent, reliable outcomes
- **Memory system** enables continuous learning and improvement
### Start Simple, Scale Intelligently
The best approach to SuperClaude v4.0.0 is progressive:
1. **Initialize sessions** with `/sc:load` to experience persistent context
2. **Try brainstorming** with `/sc:brainstorm` for interactive discovery
3. **Trust behavioral modes** to adapt automatically to your work patterns
4. **Use session persistence** with `/sc:save` to build continuous context
5. **Experiment with advanced features** like multi-layer orchestration
### When to Use SuperClaude
**SuperClaude v4.0.0 Excels At:**
- Persistent development workflows with cross-session context
- Interactive requirements discovery and project brainstorming
- Intelligent code analysis with semantic understanding
- Adaptive task management with behavioral intelligence
- Cross-domain coordination requiring multiple agents and modes
- Session-based learning that builds project understanding over time
**When to Use Standard Claude Code:**
- Simple questions that don't need specialized tools
- Creative writing or non-technical content creation
- General research topics outside software development
- Open-ended ideation without specific implementation needs
---
## Related Guides
**🚀 Getting Started (Essential)**
- [Installation Guide](installation-guide.md) - Complete setup and configuration
- [Examples Cookbook](examples-cookbook.md) - Copy-paste examples for common tasks
- [Troubleshooting Guide](troubleshooting-guide.md) - Quick solutions when things go wrong
**📚 Core Knowledge (Recommended)**
- [Commands Guide](commands-guide.md) - All 21 commands with real examples
- [Agents Guide](agents-guide.md) - 13 AI specialists and when they help
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How SuperClaude adapts automatically
- [Flags Guide](flags-guide.md) - Manual control and optimization options
**💼 Practical Application (Next Steps)**
- [Session Management Guide](session-management.md) - Persistent context across sessions
- [Best Practices Guide](best-practices.md) - Proven patterns for maximum effectiveness
**🔧 Advanced Understanding (Optional)**
- [Technical Architecture Guide](technical-architecture.md) - Internal system design
**📖 Reading Path Recommendations:**
*For New Users*: Installation → Examples Cookbook → Commands → Start Building!
*For Power Users*: Best Practices → Session Management → Technical Architecture
*When Stuck*: Troubleshooting → Examples Cookbook → Ask in Issues
Remember: You can use SuperClaude effectively without reading any of these guides. They're here when you get curious about how it works or want to unlock advanced capabilities!

1145
Guides/technical-architecture.md
View File

File diff suppressed because it is too large Load Diff

1011
Guides/troubleshooting-guide.md
View File

File diff suppressed because it is too large Load Diff

1008
PUBLISHING.md
View File

File diff suppressed because it is too large Load Diff

448
README.md
View File

@ -8,431 +8,61 @@
[![Contributors](https://img.shields.io/github/contributors/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)
[![Website](https://img.shields.io/website?url=https://superclaude-org.github.io/SuperClaude_Website/)](https://superclaude-org.github.io/SuperClaude_Website/)
An intelligent framework that transforms Claude Code into a comprehensive development environment with specialized agents, behavioral modes, and advanced MCP integration.
SuperClaude is a meta-programming configuration framework that transforms Claude Code into a structured development platform through behavioral instruction injection and component orchestration. It enhances Claude Code with 21 slash commands, 13 specialized agents, 6 behavioral modes, and 6 MCP server integrations for systematic workflow automation.
**📢 Status**: v4.0.0 is here! Major architecture overhaul with new behavioral modes, session lifecycle, and comprehensive agent system.
## Quick Start
## What is SuperClaude v4.0.0? 🤔
```bash
# Via Python (recommended)
pip install SuperClaude && SuperClaude install
SuperClaude v4.0.0 represents a complete evolution of the development framework, now featuring:
- 🛠️ **21 specialized commands** for comprehensive development workflows
- 🤖 **13 specialized agents** with domain expertise and intelligent routing
- 🧠 **5 Behavioral Modes** for different types of work (Brainstorming, Introspection, Task Management, Orchestration, Token Efficiency)
- 🔧 **6 MCP servers** including the powerful new Morphllm and Serena agents
- 💾 **Session Lifecycle** with persistent context via /sc:load and /sc:save
This is a complete rethink of how AI-assisted development should work - more intelligent, more capable, and more adaptable to your workflow! 🎯
# Via NPM (cross-platform)
npm install -g superclaude && superclaude install
```
## Support SuperClaude Development 💎
Help us continue advancing the future of AI-assisted development! SuperClaude v4.0.0 represents a major architectural evolution with significant improvements:
SuperClaude Framework development requires ongoing support to maintain MCP server integrations, expand the command system, and provide comprehensive documentation. Your support enables continuous improvement and new capabilities.
### What Your Support Enables 🚀
- **Framework Evolution** - Continued development of behavioral modes and agent intelligence
- **Claude Code Subscriptions** - Essential API access for framework development and testing
- **Documentation Quality** - Comprehensive guides and technical writing improvements
- **Community Resources** - Better tooling, examples, and educational materials
[![GitHub Sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#white)](https://github.com/sponsors/SuperClaude-Org)
### Ways to Support 🤝
## Documentation
[![Support on Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Development-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/superclaude)
[![GitHub Sponsors](https://img.shields.io/badge/GitHub-Sponsor-EA4AAA?logo=github-sponsors&logoColor=white)](https://github.com/sponsors/SuperClaude-Org)
[![Support on Patreon](https://img.shields.io/badge/Patreon-Support%20Us-F96854?logo=patreon&logoColor=white)](https://patreon.com/superclaude)
### Getting Started
- [Quick Start Guide](Getting-Started/quick-start.md)
- [Installation Guide](Getting-Started/installation.md)
## Current Status 📊
### User Guides
- [Commands Reference](User-Guide/commands.md)
- [Agents Guide](User-Guide/agents.md)
- [Behavioral Modes](User-Guide/modes.md)
- [Flags Guide](User-Guide/flags.md)
- [MCP Servers](User-Guide/mcp-servers.md)
- [Session Management](User-Guide/session-management.md)
✅ **What's New in v4.0.0:**
- Complete rework of behavioral foundation with 30-50% token efficiency gains
- 13 specialized agents with domain expertise and collaborative coordination
- Context-aware adaptive behavior with automatic activation
- Persistent development context across sessions with smart checkpointing
- Significant weight reduction while expanding capabilities
- Advanced MCP integration with Morphllm and Serena
### Developer Resources
- [Technical Architecture](Developer-Guide/technical-architecture.md)
- [Contributing Code](Developer-Guide/contributing-code.md)
- [Testing & Debugging](Developer-Guide/testing-debugging.md)
✅ **What's Working Well:**
- All 21 commands with enhanced capabilities
- Full MCP server integration suite
- Session lifecycle with /sc:load and /sc:save
- Behavioral modes with automatic activation
- Intelligent agent routing and coordination
### Reference
- [Best Practices](Reference/best-practices.md)
- [Examples Cookbook](Reference/examples-cookbook.md)
- [Troubleshooting](Reference/troubleshooting.md)
✅ **Production Ready:**
- Stable release with comprehensive testing
- Full documentation and user guides
- Performance optimizations implemented
## Contributing
## Key Features ✨
**Current Priorities:**
- 📝 Documentation improvements and examples
- 🔧 MCP server integrations and configurations
- 🎯 Command workflow examples and patterns
- 🧪 Testing and validation procedures
- 🌐 Translation and internationalization
### 21 Specialized Commands 🛠️
Enhanced command suite for comprehensive development workflows:
**Development**: `/sc:implement`, `/sc:build`, `/sc:design`
**Analysis**: `/sc:analyze`, `/sc:troubleshoot`, `/sc:explain`
**Quality**: `/sc:improve`, `/sc:test`, `/sc:cleanup`
**Session**: `/sc:load`, `/sc:save`, `/sc:brainstorm`, `/sc:reflect`
**Workflow**: `/sc:task`, `/sc:spawn`, `/sc:workflow`, `/sc:select-tool`
**Others**: `/sc:document`, `/sc:git`, `/sc:estimate`, `/sc:index`
### 13 Specialized Agents 🤖
AI specialists with deep domain expertise and intelligent coordination:
- 🏗️ **system-architect** - System design and architecture
- 🎨 **frontend-architect** - UI/UX and modern frontend development
- ⚙️ **backend-architect** - APIs, infrastructure, and server-side logic
- 🔍 **root-cause-analyst** - Systematic investigation and debugging
- 🛡️ **security-engineer** - Security assessment and vulnerability analysis
- ✍️ **technical-writer** - Technical documentation and writing
- ⚡ **performance-engineer** - Optimization and performance engineering
- 🧪 **quality-engineer** - Quality assurance and testing strategies
- 🐍 **python-expert** - Python development and best practices
- 🤖 **devops-architect** - Infrastructure and deployment automation
- 🔧 **refactoring-expert** - Code refactoring and clean code principles
- 📋 **requirements-analyst** - Requirements discovery and analysis
- 🎯 **learning-guide** - Teaching and educational explanations
*These agents feature intelligent routing, context awareness, and collaborative problem-solving capabilities.*
### 5 Behavioral Modes 🧠
Revolutionary behavioral system that adapts SuperClaude's approach:
#### Brainstorming Mode
- **Purpose**: Interactive requirements discovery and ideation
- **Triggers**: Ambiguous requests, exploration keywords, uncertainty indicators
- **Features**: Socratic dialogue, collaborative discovery, automated brief generation
#### Introspection Mode
- **Purpose**: Meta-cognitive analysis and framework troubleshooting
- **Triggers**: Self-analysis requests, complex problem solving, error recovery
- **Features**: Reasoning analysis, decision validation, pattern recognition
#### Task Management Mode
- **Purpose**: Multi-layer orchestration and systematic delegation
- **Triggers**: Multi-step operations, complex builds, system-wide changes
- **Features**: Progressive orchestration, sub-agent delegation, performance analytics
#### Orchestration Mode
- **Purpose**: Intelligent tool selection and resource optimization
- **Triggers**: Multi-tool operations, performance constraints, parallel execution
- **Features**: Smart tool selection, parallel thinking, resource management
#### Token Efficiency Mode
- **Purpose**: Intelligent optimization with symbol systems and compression
- **Triggers**: Resource constraints, large contexts, performance needs
- **Features**: 30-50% token reduction, quality preservation, adaptive compression
### 6 MCP Server Integration 🔧
Comprehensive external tool ecosystem:
- **Context7** - Official library documentation and patterns
- **Sequential** - Multi-step analysis and complex reasoning
- **Magic** - Modern UI component generation
- **Playwright** - Browser automation and E2E testing
- **Morphllm** - Intelligent file editing with Fast Apply capability
- **Serena** - Semantic code analysis and project-wide operations
### Session Lifecycle System 💾
Persistent development context with intelligent management:
- **`/sc:load`** - Initialize projects with full context restoration
- **`/sc:save`** - Create checkpoints and preserve session state
- **Automatic Checkpoints** - Task completion, time-based, risk-based triggers
- **Cross-Session Learning** - Accumulated insights and pattern recognition
### Advanced Framework Features
Intelligent architecture with built-in capabilities:
- **Framework Coordinator** - Cross-component orchestration
- **Performance Monitor** - Real-time metrics and optimization
- **Quality Gates** - 8-step validation pipeline
- **Session Lifecycle** - Event-driven session management
## ⚠️ Upgrading from v3? Important!
SuperClaude v4.0.0 is a major architectural upgrade. Clean installation recommended:
1. **Backup Important Data** - Save any custom configurations
2. **Clean Previous Installation**:
```bash
python3 -m SuperClaude uninstall # If available
rm -rf ~/.claude/SuperClaude/
rm -rf ~/.claude/shared/
```
3. **Install v4.0.0** - Follow installation instructions below
### 🔄 **Key Changes for v3 Users**
- **New Commands**: `/sc:brainstorm`, `/sc:reflect`, `/sc:save`, `/sc:select-tool`
- **Session Management**: Use `/sc:load` to initialize projects, `/sc:save` for persistence
- **Agent System**: Enhanced from personas to full agent coordination
- **Behavioral Modes**: Automatic activation based on context and needs
## Installation 📦
SuperClaude v4.0.0 installation with enhanced capabilities:
### Step 1: Install the Package
**Option A: From PyPI (Recommended)**
```bash
pip install SuperClaude
```
**Option B: From Source**
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install -e .
```
**Option C: From npm (Global, requires publish this method won't works for now)**
```bash
npm install -g superclaude
superclaude --help
```
**Option D: From npm (Local Project, requires publish this method won't works for now)**
```bash
npm install superclaude
npx superclaude --help
```
**Option E: From GitHub (Works now, no publish needed)**
```bash
# Global
npm install -g github:SuperClaude-Org/SuperClaude_Framework#SuperClaude_V4_Beta
superclaude --help
# Local
npm install github:SuperClaude-Org/SuperClaude_Framework#SuperClaude_V4_Beta
npx superclaude --help
```
---
**Missing Python?** Install Python 3.8+ first:
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip
# macOS
brew install python3
# Windows
# Download from https://python.org/downloads/
```
### Step 2: Run the v4.0.0 Installer
Enhanced installer with behavioral modes and session lifecycle:
```bash
# v4.0.0 setup (recommended for most users)
python3 -m SuperClaude install
# See all v4.0.0 options
python3 -m SuperClaude install --help
```
### Simple bash Command Usage
```bash
# v4.0.0 setup
SuperClaude install
```
**That's it! 🎉** The v4.0.0 installer configures everything: behavioral modes, MCP servers, and session lifecycle.
## How v4.0.0 Works 🔄
SuperClaude v4.0.0 transforms Claude Code through intelligent architecture:
1. **Behavioral Modes** - Adaptive behavior based on context and task requirements
2. **Agent Coordination** - 13 specialized agents with intelligent routing and collaboration
3. **Session Lifecycle** - Persistent context with /sc:load and /sc:save commands
4. **MCP Integration** - 6 powerful servers for extended capabilities
The system intelligently adapts to your workflow, automatically activating appropriate modes and agents. 🧠
## v4.0.0 Architecture Highlights 🏗️
### Behavioral Intelligence
- **Automatic Mode Detection** - Context-aware behavioral adaptation
- **Cross-Mode Coordination** - Seamless integration between behavioral patterns
- **Progressive Enhancement** - Capabilities scale with complexity
### Agent Orchestration
- **Intelligent Routing** - Smart agent selection based on domain expertise
- **Collaborative Problem-Solving** - Multi-agent coordination for complex tasks
- **Context Preservation** - Agents maintain awareness across interactions
### Session Management
- **Persistent Context** - Full project state preservation across sessions
- **Intelligent Checkpointing** - Automatic saves based on risk and completion
- **Cross-Session Learning** - Accumulated insights and pattern recognition
## Configuration ⚙️
v4.0.0 configuration with enhanced behavioral controls:
- `~/.claude/*.md` - Behavioral mode configurations
- `~/.claude/agents/` - Agent-specific customizations
- `~/.claude/commands/` - Command definitions and configurations
- `~/.serena/` - Session lifecycle and memory management
Most users can use defaults - v4.0.0 intelligently adapts to your workflow! 🎛️
## Documentation 📖
Comprehensive v4.0.0 guides and documentation:
- 📚 [**v4.0.0 User Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/superclaude-user-guide.md) - Complete v4.0.0 overview and getting started
- 🛠️ [**Commands Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/commands-guide.md) - All 21 commands with v4.0.0 enhancements
- 🧠 [**Behavioral Modes Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/behavioral-modes-guide.md) - Understanding the 5 behavioral modes
- 🤖 [**Agent System Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/agent-system-guide.md) - Working with 13 specialized agents
- 🏳️ [**Flags Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/flags-guide.md) - v4.0.0 command flags and behavioral controls
- 📦 [**Installation Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/installation-guide.md) - Detailed v4.0.0 installation and setup
## Contributing 🤝
v4.0.0 opens new contribution opportunities:
- 🐛 **Bug Reports** - Help us improve the stable release
- 📝 **Documentation** - v4.0.0 features need clear explanation
- 🧪 **Testing** - Community participation across different environments
- 🔧 **Framework Development** - Extend the framework capabilities
- 🤖 **Agent Enhancement** - Improve specialized agent capabilities
- 🧠 **Behavioral Modes** - Contribute to mode intelligence
The v4.0.0 architecture is modular - many ways to contribute!
### Documentation & Community 📝
While we strive for accuracy, the rapid v4.0.0 evolution means documentation may contain errors. We rely on our community to:
- **Report Issues** - Help us identify documentation gaps or technical problems
- **Submit Improvements** - PRs for documentation fixes and enhancements are always welcome
- **Share Feedback** - Your experience helps shape future development priorities
*Every contribution, whether code, documentation, or financial support, helps make SuperClaude better for the entire development community! 🌟*
## Project Structure 📁
```
SuperClaude_Framework/
├── 📁 SuperClaude/ # Core framework documentation & behavioral definitions
│ ├── 🤖 Agents/ # 13 specialized agents with domain expertise
│ │ ├── backend-architect.md # API & server-side architecture specialist
│ │ ├── devops-architect.md # Infrastructure & deployment automation
│ │ ├── frontend-architect.md # UI/UX & modern frontend development
│ │ ├── learning-guide.md # Educational explanations & tutorials
│ │ ├── performance-engineer.md # Optimization & performance engineering
│ │ ├── python-expert.md # Python development & best practices
│ │ ├── quality-engineer.md # QA strategies & testing frameworks
│ │ ├── refactoring-expert.md # Code cleanup & architectural improvements
│ │ ├── requirements-analyst.md # Requirements discovery & analysis
│ │ ├── root-cause-analyst.md # Systematic debugging & investigation
│ │ ├── security-engineer.md # Security assessment & vulnerability analysis
│ │ ├── system-architect.md # High-level system design & architecture
│ │ └── technical-writer.md # Technical documentation & communication
│ ├── 🛠️ Commands/ # 21 specialized slash commands
│ │ ├── analyze.md # Code & project analysis
│ │ ├── brainstorm.md # Interactive requirements discovery
│ │ ├── build.md # Smart build with auto-optimization
│ │ ├── cleanup.md # Code cleanup & organization
│ │ ├── design.md # Architecture & design planning
│ │ ├── document.md # Technical documentation generation
│ │ ├── estimate.md # Project estimation & planning
│ │ ├── explain.md # Code explanation & education
│ │ ├── git.md # Advanced git operations
│ │ ├── implement.md # Feature implementation & development
│ │ ├── improve.md # Code enhancement & optimization
│ │ ├── index.md # Command registry & coordination
│ │ ├── load.md # Session initialization & context loading
│ │ ├── reflect.md # Session reflection & analysis
│ │ ├── save.md # Session persistence & context saving
│ │ ├── select-tool.md # Intelligent tool selection
│ │ ├── spawn.md # Agent spawning & coordination
│ │ ├── task.md # Task management & orchestration
│ │ ├── test.md # Testing strategies & execution
│ │ ├── troubleshoot.md # Problem diagnosis & resolution
│ │ └── workflow.md # Workflow automation & management
│ ├── 🧠 Core/ # Foundational behavioral rules & principles
│ │ ├── FLAGS.md # Behavioral flags for execution modes
│ │ ├── PRINCIPLES.md # Software engineering principles
│ │ └── RULES.md # Operational rules & guidelines
│ ├── 🔧 MCP/ # MCP server integration & configs
│ │ └── configs/ # MCP server configuration files
│ └── 🎭 Modes/ # 5 behavioral modes for adaptive behavior
│ ├── MODE_Brainstorming.md # Interactive discovery & ideation
│ ├── MODE_Introspection.md # Meta-cognitive analysis & reflection
│ ├── MODE_Orchestration.md # Intelligent tool selection & coordination
│ ├── MODE_Task_Management.md # Multi-layer orchestration & delegation
│ └── MODE_Token_Efficiency.md # Symbol-enhanced compression & optimization
├── 📚 Guides/ # Comprehensive user documentation
│ └── superclaude-user-guide.md # Complete usage guide & workflows
├── 🏗️ setup/ # Modular installation & configuration system
│ ├── cli/ # Command-line interface & operations
│ │ ├── commands/ # CLI command implementations
│ │ ├── install.py # Installation orchestration
│ │ ├── update.py # Update management
│ │ └── uninstall.py # Clean uninstallation
│ ├── components/ # Component-based installation modules
│ ├── core/ # Core installation logic & registry
│ │ ├── installer.py # Installation orchestration engine
│ │ └── registry.py # Component discovery & dependency resolution
│ ├── data/ # Installation data & metadata
│ └── services/ # Configuration management services
│ ├── claude_md.py # Dynamic CLAUDE.md generation
│ ├── config.py # Configuration management
│ └── file_ops.py # File operation utilities
├── 🔨 scripts/ # Build, validation & publishing automation
│ ├── build_and_upload.py # PyPI package building & publishing
│ ├── publish.sh # Production publishing workflow
│ └── validate_pypi_ready.py # Package validation & compliance
├── 📄 Configuration Files
│ ├── CLAUDE.md # Project-specific Claude Code instructions
│ ├── pyproject.toml # Python project configuration & dependencies
│ ├── uv.lock # Dependency lock file for reproducible builds
│ └── README.md # This comprehensive project overview
└── 📋 Documentation
├── CHANGELOG.md # Version history & release notes
├── CONTRIBUTING.md # Contribution guidelines & development setup
├── CODE_OF_CONDUCT.md # Community standards & expectations
├── SECURITY.md # Security policies & vulnerability reporting
└── PUBLISHING.md # Publishing guidelines & release procedures
```
## v4.0.0 Architecture Notes 🏗️
The v4.0.0 architecture focuses on:
- **Behavioral Intelligence** - Context-aware adaptive behavior
- **Agent Orchestration** - Sophisticated multi-agent coordination
- **Session Persistence** - Continuous learning and context preservation
- **Performance** - Token efficiency and resource optimization
v4.0.0 represents a fundamental evolution in AI-assisted development frameworks.
## FAQ 🙋
**Q: What's new in v4.0.0 compared to V3?**
A: Complete architecture overhaul with behavioral modes, session lifecycle, 13 agents, and 6 MCP servers.
**Q: How does the new architecture work?**
A: Built on behavioral modes, intelligent agents, and session persistence for adaptive development workflows.
**Q: Should I upgrade from V3?**
A: v4.0.0 offers significant improvements, with clean installation recommended for best experience.
**Q: How stable is v4.0.0?**
A: Production-ready stable release with comprehensive testing and community validation!
## SuperClaude Contributors
[![Contributors](https://contrib.rocks/image?repo=SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
## License
MIT - [See LICENSE file for details](https://opensource.org/licenses/MIT)
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Star History
<a href="https://www.star-history.com/#SuperClaude-Org/SuperClaude_Framework&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date" />
</picture>
</a>
---
*v4.0.0: The future of AI-assisted development is here. Experience intelligent, adaptive, and powerful development workflows! 🚀*
---
**Contributors:** [View all contributors](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)

1338
Reference/best-practices.md Normal file
View File

File diff suppressed because it is too large Load Diff

1476
Reference/examples-cookbook.md Normal file
View File

File diff suppressed because it is too large Load Diff

1248
Reference/troubleshooting.md Normal file
View File

File diff suppressed because it is too large Load Diff

817
SECURITY.md
View File

@ -2,211 +2,760 @@
## 🔒 Reporting Security Vulnerabilities
We take security seriously. If you discover a security vulnerability in SuperClaude Framework, please help us address it responsibly.
SuperClaude Framework prioritizes security through secure-by-design principles, comprehensive input validation, and responsible vulnerability management. We are committed to maintaining a secure development platform while enabling powerful AI-assisted workflows.
**Security Commitment:**
- Timely response to security reports (48-72 hours)
- Transparent communication about security issues
- Regular security audits and dependency updates
- Community-driven security improvement
### Responsible Disclosure
**Please do NOT create public GitHub issues for security vulnerabilities.**
**Primary Contact:** security@superclaude.org (monitored by maintainers)
Instead, email us directly at: `anton.knoery@gmail.com` (or create a private GitHub Security Advisory)
**Process:**
1. **Report**: Send detailed vulnerability report to security@superclaude.org
2. **Acknowledgment**: We'll confirm receipt within 48 hours
3. **Investigation**: Initial assessment within 72 hours
4. **Coordination**: Work together on fix development and testing
5. **Disclosure**: Coordinated public disclosure after fix deployment
**Alternative Channels:**
- GitHub Security Advisories (for GitHub-hosted issues)
- Direct contact to maintainers for critical vulnerabilities
- Encrypted communication available upon request
**Please Do:**
- Provide detailed technical description and reproduction steps
- Allow reasonable time for investigation and fix development
- Maintain confidentiality until coordinated disclosure
**Please Don't:**
- Publicly disclose vulnerabilities before coordination
- Test vulnerabilities on systems you don't own
- Access or modify data beyond proof-of-concept demonstration
### What to Include
When reporting a vulnerability, please provide:
**Essential Information:**
- SuperClaude version: `SuperClaude --version`
- Operating system and version
- Python version: `python3 --version`
- Claude Code version: `claude --version`
- Vulnerability description and potential impact
- Detailed reproduction steps with minimal test case
- Proof-of-concept code or commands (if applicable)
- **Description** of the vulnerability and potential impact
- **Steps to reproduce** the issue with minimal examples
- **Affected versions** and components
- **Suggested fixes** if you have any ideas
- **Your contact information** for follow-up questions
**Helpful Additional Details:**
- MCP server configurations involved (if applicable)
- Network environment and proxy configurations
- Custom behavioral modes or agent configurations
- Log files or error messages (sanitized of personal data)
- Screenshots or recordings of the vulnerability demonstration
**Vulnerability Report Template:**
```
**SuperClaude Version:** [version]
**Environment:** [OS, Python version, Claude Code version]
**Vulnerability Summary:**
[Brief description of the security issue]
**Impact Assessment:**
[Potential security impact and affected components]
**Reproduction Steps:**
1. [Step-by-step instructions]
2. [Include exact commands or configuration]
3. [Show expected vs actual behavior]
**Proof of Concept:**
[Minimal code or commands demonstrating the issue]
**Suggested Fix:**
[Optional: your thoughts on remediation approach]
```
### Response Timeline
- **Initial response**: Within 48 hours of report
- **Severity assessment**: Within 1 week
- **Fix timeline**: Depends on severity (see below)
- **Public disclosure**: After fix is released and users have time to update
**Response Timeline:**
**Initial Response: 48 hours**
- Acknowledge receipt of vulnerability report
- Assign internal tracking identifier
- Provide initial impact assessment
**Investigation: 72 hours**
- Confirm vulnerability and assess severity
- Identify affected versions and components
- Begin fix development planning
**Status Updates: Weekly**
- Regular progress updates during investigation
- Timeline adjustments if complexity requires extension
- Coordination on disclosure timeline
**Fix Development: Severity-dependent**
- **Critical**: 7-14 days for patch development
- **High**: 14-30 days for comprehensive fix
- **Medium**: 30-60 days for thorough resolution
- **Low**: Next regular release cycle
**Disclosure Coordination:**
- Advance notice to reporter before public disclosure
- Security advisory preparation and review
- Coordinated release with fix deployment
- Public acknowledgment of responsible disclosure
**Emergency Response:**
For actively exploited vulnerabilities or critical security issues:
- Immediate response within 12 hours
- Emergency patch development and testing
- Expedited disclosure process with community notification
## 🚨 Severity Levels
### Critical (Fix within 24-48 hours)
- Remote code execution vulnerabilities
- Privilege escalation that affects system security
- Data exfiltration or unauthorized access to sensitive information
**Critical (CVSS 9.0-10.0)**
- **Examples**: Remote code execution, arbitrary file system access, credential theft
- **Response**: 12-hour acknowledgment, 7-day fix target
- **Impact**: Complete system compromise or data breach potential
### High (Fix within 1 week)
- Local code execution through framework component manipulation
- Unauthorized file system access beyond intended scope
- Authentication bypass in MCP server communication
**High (CVSS 7.0-8.9)**
- **Examples**: Privilege escalation, sensitive data exposure, authentication bypass
- **Response**: 24-hour acknowledgment, 14-day fix target
- **Impact**: Significant security control bypass or data access
### Medium (Fix within 1 month)
- Information disclosure of non-sensitive data
- Denial of service through resource exhaustion
- Input validation issues with limited impact
**Medium (CVSS 4.0-6.9)**
- **Examples**: Information disclosure, denial of service, configuration manipulation
- **Response**: 48-hour acknowledgment, 30-day fix target
- **Impact**: Limited security impact or specific attack scenarios
### Low (Fix in next release)
- Minor information leaks
- Configuration issues with security implications
- Dependency vulnerabilities with low exploitability
**Low (CVSS 0.1-3.9)**
- **Examples**: Minor information leaks, rate limiting bypass, non-critical validation errors
- **Response**: 72-hour acknowledgment, next release cycle
- **Impact**: Minimal security impact requiring specific conditions
**Severity Assessment Factors:**
- **Attack Vector**: Network accessible vs local access required
- **Attack Complexity**: Simple vs complex exploitation requirements
- **Privileges Required**: None vs authenticated access needed
- **User Interaction**: Automatic vs user action required
- **Scope**: Framework core vs specific component impact
- **Confidentiality/Integrity/Availability Impact**: Complete vs partial vs none
**Special Considerations:**
- MCP server vulnerabilities assessed based on worst-case configuration
- Agent coordination issues evaluated for privilege escalation potential
- Configuration file vulnerabilities considered for credential exposure risk
## 🔐 Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 4.0.0-beta.x | ✅ Active Development |
| 3.0.x | ⚠️ Security fixes only |
| < 3.0 | ❌ End of life |
**Currently Supported Versions:**
| Version | Security Support | End of Support |
|---------|------------------|----------------|
| 4.0.x | ✅ Full support | TBD (current) |
| 3.x.x | ⚠️ Critical only | June 2025 |
| 2.x.x | ❌ No support | December 2024 |
| 1.x.x | ❌ No support | June 2024 |
**Support Policy:**
- **Full Support**: All security issues addressed with regular patches
- **Critical Only**: Only critical vulnerabilities (CVSS 9.0+) receive patches
- **No Support**: No security patches; users should upgrade immediately
**Version Support Lifecycle:**
- **Current Major**: Full security support for entire lifecycle
- **Previous Major**: Critical security support for 12 months after new major release
- **Legacy Versions**: No support; upgrade required for security fixes
**Security Update Distribution:**
- Critical patches: Immediate release with emergency notification
- High severity: Coordinated release with regular update cycle
- Medium/Low: Included in next scheduled release
**Upgrade Recommendations:**
- Always use the latest stable version for best security posture
- Subscribe to security notifications for timely update information
- Test updates in development environment before production deployment
- Review security advisories for impact assessment
**Enterprise Support:**
For organizations requiring extended security support:
- Contact maintainers for custom support arrangements
- Consider contributing to development for priority handling
- Implement additional security controls for unsupported versions
## 🛡️ Security Features
### Framework Component Security (V4 Enhanced)
- **Timeout protection**: All components have configurable timeouts (default 30s)
- **Input validation**: JSON schema validation for all component inputs
- **Sandboxed execution**: Components run with limited system permissions
- **Error containment**: Component failures don't affect framework stability
- **Performance monitoring**: Real-time component execution tracking
- **Session lifecycle integration**: Secure checkpoint and recovery
**Input Validation & Sanitization:**
- Command parameter validation and type checking
- File path sanitization and directory traversal prevention
- Agent activation logic with controlled permissions
- Configuration parsing with strict schema validation
**Behavioral Mode Security:**
- Mode switching validation and access controls
- Isolation between different behavioral contexts
- Safe mode operation with restricted capabilities
- Automatic fallback to secure defaults on errors
**Agent Coordination Security:**
- Agent privilege separation and limited scope
- Secure inter-agent communication protocols
- Resource usage monitoring and limits
- Fail-safe agent deactivation on security violations
**Session Management:**
- Secure session persistence with data integrity validation
- Memory isolation between different projects and users
- Automatic session cleanup and resource deallocation
- Encrypted storage for sensitive session data
**Quality Gates:**
- Pre-execution security validation for all commands
- Runtime monitoring for suspicious activity patterns
- Post-execution verification and rollback capabilities
- Automated security scanning for generated code
**Dependency Management:**
- Regular dependency updates and vulnerability scanning
- Minimal privilege principle for external library usage
- Supply chain security validation for framework components
- Isolated execution environments for external tool integration
### File System Protection
- **Path validation**: Prevents directory traversal attacks
- **Permission checking**: Validates file system permissions before operations
- **Secure defaults**: Conservative file access patterns
- **Backup mechanisms**: Safe fallback when operations fail
**Path Validation:**
- Absolute path requirement for all file operations
- Directory traversal attack prevention (`../` sequences blocked)
- Symbolic link resolution with safety checks
- Whitelist-based path validation for sensitive operations
**File Access Controls:**
- User permission respect and validation
- Read-only mode enforcement where appropriate
- Temporary file cleanup and secure deletion
- Configuration file integrity validation
**Configuration Security:**
- ~/.claude directory permission validation (user-only access)
- Configuration file schema validation and sanitization
- Backup creation before configuration changes
- Rollback capabilities for configuration corruption
**Workspace Isolation:**
- Project-specific workspace boundaries
- Prevent cross-project data leakage
- Secure temporary file management within project scope
- Automatic cleanup of generated artifacts
**File Content Security:**
- Binary file detection and safe handling
- Text encoding validation and normalization
- Size limits for file operations to prevent resource exhaustion
- Content scanning for potential security indicators
**Backup and Recovery:**
- Automatic backup creation before destructive operations
- Secure backup storage with integrity verification
- Point-in-time recovery for configuration corruption
- User data preservation during framework updates
### MCP Server Security (6 Servers in V4)
- **Server validation**: Verify MCP server authenticity and integrity
- **Communication encryption**: Secure channels for all MCP communication
- **Timeout handling**: Prevent resource exhaustion from unresponsive servers
- **Fallback mechanisms**: Graceful degradation when servers are compromised
- **Serena MCP**: Secure memory management with access controls
- **Morphllm MCP**: Validated file editing with permission checks
**MCP Server Communication:**
- Secure protocol validation for all MCP server connections
- Request/response integrity verification
- Connection timeout and retry limits to prevent resource exhaustion
- Error handling that doesn't leak sensitive information
**Server Configuration Security:**
- Configuration file validation and schema enforcement
- Secure credential management for authenticated MCP servers
- Server capability verification and permission boundaries
- Isolation between different MCP server contexts
**Individual Server Security:**
**Context7**: Documentation lookup with request sanitization and rate limiting
**Sequential**: Reasoning engine with controlled execution scope and resource limits
**Magic**: UI generation with output validation and XSS prevention
**Playwright**: Browser automation with sandboxed execution environment
**Morphllm**: Code transformation with input validation and safety checks
**Serena**: Memory management with secure data persistence and access controls
**Network Security:**
- HTTPS enforcement for external MCP server connections
- Certificate validation and pinning where applicable
- Network timeout configuration to prevent hanging connections
- Request rate limiting and abuse prevention
**Data Protection:**
- No persistent storage of sensitive data in MCP communications
- Memory cleanup after MCP server interactions
- Audit logging for security-relevant MCP operations
- Data minimization in server requests and responses
**Failure Handling:**
- Graceful degradation when MCP servers are unavailable
- Secure fallback to native capabilities without data loss
- Error isolation to prevent MCP failures from affecting framework security
- Monitoring for suspicious MCP server behavior patterns
### Configuration Security
- **Input sanitization**: All configuration inputs are validated and sanitized
- **Secrets management**: Secure handling of API keys and sensitive data
- **Permission controls**: Fine-grained access controls in settings.json
- **Audit logging**: Track security-relevant configuration changes
**Configuration File Security:**
- ~/.claude directory with user-only permissions (700)
- Configuration files with restricted access (600)
- Schema validation for all configuration content
- Atomic configuration updates to prevent corruption
**Secrets Management:**
- No hardcoded secrets or API keys in framework code
- Environment variable preference for sensitive configuration
- Clear documentation about credential handling best practices
- Automatic redaction of sensitive data from logs and error messages
**API Key Handling:**
- User-managed API keys stored in secure system credential stores
- No framework storage of Claude API credentials
- Clear separation between framework configuration and user credentials
- Guidance for secure credential rotation
**MCP Server Credentials:**
- Individual MCP server authentication handled securely
- No cross-server credential sharing
- User control over MCP server authentication configuration
- Clear documentation for secure MCP server setup
**Configuration Validation:**
- JSON schema validation for all configuration files
- Type checking and range validation for configuration values
- Detection and rejection of malicious configuration attempts
- Automatic configuration repair for common corruption scenarios
**Default Security:**
- Secure-by-default configuration with minimal permissions
- Explicit opt-in for potentially risky features
- Regular review of default settings for security implications
- Clear warnings for configuration changes that reduce security
## 🔧 Security Best Practices
### For Users
#### Installation Security
```bash
# Verify installation scripts before running
cat install.sh | less
**Installation Security:**
- Download SuperClaude only from official sources (PyPI, npm, GitHub releases)
- Verify package signatures and checksums when available
- Use virtual environments to isolate dependencies
- Keep Python, Node.js, and system packages updated
# Use development mode for testing
./install.sh --dev
**Configuration Security:**
- Use secure file permissions for ~/.claude directory (user-only access)
- Store API credentials in system credential managers, not configuration files
- Regularly review and audit MCP server configurations
- Enable only needed MCP servers to minimize attack surface
# Check file permissions after installation
ls -la ~/.claude/
```
**Project Security:**
- Never run SuperClaude with elevated privileges unless absolutely necessary
- Review generated code before execution, especially for external API calls
- Use version control to track all SuperClaude-generated changes
- Regularly backup project configurations and important data
#### Configuration Security
```json
{
"permissions": {
"deny": [
"Bash(rm:-rf /*)",
"Bash(sudo:*)",
"WebFetch(domain:localhost)"
]
}
}
```
**Network Security:**
- Use HTTPS for all external MCP server connections
- Be cautious when using MCP servers that access external APIs
- Consider network firewalls for restrictive environments
- Monitor network traffic for unexpected external connections
#### Regular Maintenance
- **Update regularly**: Keep SuperClaude and dependencies current
- **Review logs**: Check `~/.claude/` for suspicious activity
- **Monitor permissions**: Ensure components have minimal required permissions
- **Validate configurations**: Use provided schemas to validate settings
**Data Privacy:**
- Be mindful of sensitive data in project files when using cloud-based MCP servers
- Review MCP server privacy policies and data handling practices
- Use local-only MCP servers for sensitive projects when possible
- Regularly clean up temporary files and session data
**Command Usage:**
- Use `--dry-run` flags to preview potentially destructive operations
- Understand command scope and permissions before execution
- Be cautious with commands that modify multiple files or system configurations
- Verify command output and results before proceeding with dependent operations
### For Developers
#### Component Development
```python
# Always validate inputs
def validate_input(data: Dict[str, Any]) -> bool:
required_fields = ["tool", "data"]
return all(field in data for field in required_fields)
**Secure Coding Standards:**
- Input validation for all user-provided data and configuration
- Use parameterized queries and prepared statements for database operations
- Implement proper error handling that doesn't leak sensitive information
- Follow principle of least privilege for all component interactions
# Handle errors gracefully
try:
result = process_data(input_data)
except Exception as e:
return {"status": "error", "message": "Processing failed"}
**Agent Development Security:**
- Validate all agent activation triggers and parameters
- Implement secure inter-agent communication protocols
- Use controlled execution environments for agent operations
- Include security-focused testing for all agent capabilities
# Use timeouts for external calls
import signal
signal.alarm(10) # 10-second timeout
```
**MCP Integration Security:**
- Validate all MCP server responses and data integrity
- Implement secure credential handling for authenticated servers
- Use sandboxed execution for external MCP server interactions
- Include comprehensive error handling for MCP communication failures
#### Secure Coding Guidelines
- **Input validation**: Validate all external inputs
- **Error handling**: Never expose internal state in error messages
- **Resource limits**: Implement timeouts and resource limits
- **Principle of least privilege**: Request minimal required permissions
**Command Implementation:**
- Sanitize all command parameters and file paths
- Implement proper authorization checks for privileged operations
- Use safe defaults and explicit opt-in for risky functionality
- Include comprehensive input validation and bounds checking
**Testing Requirements:**
- Security-focused unit tests for all security-critical functionality
- Integration tests that include adversarial inputs and edge cases
- Regular security scanning of dependencies and external integrations
- Penetration testing for new features with external communication
**Code Review Security:**
- Security-focused code review for all changes to core framework
- Automated security scanning integrated into CI/CD pipeline
- Regular dependency audits and update procedures
- Documentation review for security implications of new features
**External Integration:**
- Secure API communication with proper authentication and encryption
- Validation of all external data sources and third-party services
- Sandboxed execution for external tool integration
- Clear documentation of security boundaries and trust relationships
## 📋 Security Checklist
### Before Release
- [ ] All dependencies updated to latest secure versions
- [ ] Static security analysis run (bandit, safety)
- [ ] Input validation tests pass
- [ ] Permission model reviewed
- [ ] Documentation updated with security considerations
**Pre-Release Security Validation:**
**Dependency Security:**
- [ ] Run dependency vulnerability scanning (`pip audit`, `npm audit`)
- [ ] Update all dependencies to latest secure versions
- [ ] Review new dependencies for security implications
- [ ] Verify supply chain security for critical dependencies
**Code Security Review:**
- [ ] Security-focused code review for all new features
- [ ] Static analysis security testing (SAST) completion
- [ ] Manual review of security-critical functionality
- [ ] Validation of input sanitization and output encoding
**Configuration Security:**
- [ ] Review default configuration for secure-by-default settings
- [ ] Validate configuration schema and input validation
- [ ] Test configuration file permission requirements
- [ ] Verify backup and recovery functionality
**MCP Server Security:**
- [ ] Test MCP server connection security and error handling
- [ ] Validate MCP server authentication and authorization
- [ ] Review MCP server communication protocols
- [ ] Test MCP server failure scenarios and fallback behavior
**Integration Testing:**
- [ ] Security-focused integration tests with adversarial inputs
- [ ] Cross-platform security validation
- [ ] End-to-end workflow security testing
- [ ] Performance testing under security constraints
**Documentation Security:**
- [ ] Security documentation updates and accuracy review
- [ ] User security guidance validation and testing
- [ ] Developer security guidelines review
- [ ] Vulnerability disclosure process documentation update
### Regular Maintenance
- [ ] Monthly dependency security updates
- [ ] Quarterly security review of codebase
- [ ] Annual third-party security assessment
- [ ] Continuous monitoring of security advisories
**Daily Security Monitoring:**
- Automated dependency vulnerability scanning
- Security alert monitoring from GitHub and package registries
- Community-reported issue triage and assessment
- Log analysis for suspicious activity patterns
**Weekly Security Tasks:**
- Dependency update evaluation and testing
- Security-focused code review for incoming contributions
- MCP server security configuration review
- User-reported security issue investigation
**Monthly Security Maintenance:**
- Comprehensive dependency audit and update cycle
- Security documentation review and updates
- MCP server integration security testing
- Framework configuration security validation
**Quarterly Security Review:**
- Complete security architecture review
- Threat model updates and validation
- Security testing and penetration testing
- Security training and awareness updates for contributors
**Annual Security Assessment:**
- External security audit consideration
- Security policy and procedure review
- Incident response plan testing and updates
- Security roadmap planning and prioritization
**Continuous Monitoring:**
- Automated security scanning in CI/CD pipeline
- Real-time monitoring for new vulnerability disclosures
- Community security discussion monitoring
- Security research and best practice tracking
**Response Procedures:**
- Established incident response procedures for security events
- Communication plans for security advisories and updates
- Rollback procedures for security-related issues
- Community notification systems for critical security updates
## 🤝 Security Community
### Bug Bounty Program
Currently, we don't have a formal bug bounty program, but we recognize security researchers who help improve SuperClaude's security:
**Security Researcher Recognition:**
- **Public acknowledgment** in release notes and security advisories
- **Early access** to new features and versions
- **Direct communication** with the development team
**Hall of Fame:**
Security researchers who responsibly disclose vulnerabilities are recognized in:
- Security advisory acknowledgments
- Annual security report contributor recognition
- GitHub contributor recognition and special mentions
- Community newsletter and blog post acknowledgments
**Recognition Criteria:**
- Responsible disclosure following established timeline
- High-quality vulnerability reports with clear reproduction steps
- Constructive collaboration during fix development and testing
- Adherence to ethical security research practices
**Public Recognition:**
- CVE credit for qualifying vulnerabilities
- Security advisory co-authorship for significant discoveries
- Speaking opportunities at community events and conferences
- Priority review for future security research and contributions
**Current Incentive Structure:**
SuperClaude Framework currently operates as an open-source project without monetary bug bounty rewards. Recognition focuses on professional acknowledgment and community contribution value.
**Future Incentive Considerations:**
As the project grows and secures funding:
- Potential monetary rewards for critical vulnerability discoveries
- Exclusive access to pre-release security testing opportunities
- Enhanced collaboration opportunities with security team
- Priority support for security research and tooling requests
**Qualifying Vulnerability Types:**
- Framework core security vulnerabilities
- Agent coordination security issues
- MCP server integration security problems
- Configuration security and privilege escalation
- Data integrity and confidentiality issues
**Non-Qualifying Issues:**
- Issues in third-party dependencies (report to respective projects)
- Social engineering or physical security issues
- Denial of service through resource exhaustion (unless critical)
- Security issues requiring highly privileged access or custom configuration
### Security Advisory Process
1. **Internal assessment** of reported vulnerability
2. **Fix development** with thorough testing
3. **Coordinated disclosure** with security researcher
4. **Public advisory** published after fix release
5. **Post-mortem** to prevent similar issues
**Security Advisory Lifecycle:**
**Advisory Creation:**
1. **Initial Assessment**: Vulnerability validation and impact analysis
2. **Advisory Draft**: Technical description, affected versions, and impact assessment
3. **Fix Development**: Coordinated patch development with testing
4. **Pre-Release Review**: Advisory accuracy and completeness validation
**Stakeholder Coordination:**
- **Reporter Communication**: Regular updates and collaboration on fix validation
- **Maintainer Review**: Technical accuracy and fix verification
- **Community Preparation**: Pre-announcement for high-impact vulnerabilities
- **Downstream Notification**: Alert dependent projects and distributions
**Disclosure Timeline:**
- **Coordinated Disclosure**: 90-day standard timeline from fix availability
- **Emergency Disclosure**: Immediate for actively exploited vulnerabilities
- **Extended Coordination**: Additional time for complex fixes with prior agreement
- **Public Release**: Advisory publication with fix deployment
**Advisory Content:**
- **Vulnerability Description**: Clear technical explanation of the security issue
- **Impact Assessment**: CVSS score and real-world impact analysis
- **Affected Versions**: Complete list of vulnerable framework versions
- **Fix Information**: Patch details, workarounds, and upgrade instructions
- **Credit**: Responsible disclosure acknowledgment and researcher recognition
**Distribution Channels:**
- GitHub Security Advisories for primary notification
- Community mailing lists and discussion forums
- Social media announcements for high-impact issues
- Vulnerability databases (CVE, NVD) for formal tracking
**Post-Disclosure:**
- Community Q&A and support for advisory understanding
- Lessons learned analysis and process improvement
- Security documentation updates based on discovered issues
- Enhanced testing and validation for similar vulnerability classes
## 📞 Contact Information
### Security Team
- **Email**: `anton.knoery@gmail.com`
- **PGP Key**: Available on request
- **Response Time**: 48 hours maximum
**Primary Security Contact:**
- **Email**: security@superclaude.org
- **Monitored By**: Core maintainers and security-focused contributors
- **Response Time**: 48-72 hours for initial acknowledgment
- **Escalation**: Direct maintainer contact for critical issues requiring immediate attention
**Security Team Structure:**
- **Lead Security Maintainer**: Responsible for security policy and coordination
- **Code Security Reviewers**: Focus on secure coding practices and vulnerability assessment
- **Infrastructure Security**: MCP server security and integration validation
- **Community Security Liaisons**: Interface with security researchers and community
**GitHub Security Integration:**
- **Security Advisories**: https://github.com/SuperClaude-Org/SuperClaude_Framework/security/advisories
- **Security Policy**: Available in repository security tab
- **Vulnerability Reporting**: GitHub's private vulnerability reporting system
- **Security Team**: GitHub team with security focus and escalation procedures
**Encrypted Communication:**
For sensitive security discussions requiring encrypted communication:
- **GPG Key**: Available upon request to security@superclaude.org
- **Signal**: Secure messaging coordination available for complex cases
- **Private Channels**: Dedicated security discussion channels for verified researchers
**Emergency Contact:**
For critical vulnerabilities requiring immediate attention:
- **GitHub**: Direct message to @SuperClaude-Security team
- **Priority Email**: security-urgent@superclaude.org (monitored continuously)
- **Escalation Path**: Direct maintainer contact information provided upon first contact
### General Security Questions
For general security questions (not vulnerabilities):
- Create a GitHub Discussion with the "security" label
- Check existing documentation in this file
- Review the [Contributing Guide](CONTRIBUTING.md) for development security practices
**General Security Questions:**
- **GitHub Discussions**: https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions
- **Community Forums**: Security-focused discussion threads
- **Documentation**: [Security Best Practices](Reference/best-practices.md#security-practices)
- **Issue Tracker**: Non-sensitive security configuration questions
**Technical Security Support:**
- **Configuration Help**: MCP server security setup and validation
- **Best Practices**: Secure usage patterns and recommendations
- **Integration Security**: Third-party tool security considerations
- **Compliance Questions**: Security framework compliance and standards
**Educational Resources:**
- **Security Guides**: Framework security documentation and tutorials
- **Webinars**: Community security education and awareness sessions
- **Blog Posts**: Security tips, best practices, and case studies
- **Conference Talks**: Security-focused presentations and demonstrations
**Professional Support:**
For organizations requiring dedicated security support:
- **Consulting**: Security architecture review and recommendations
- **Custom Security**: Tailored security implementations and validation
- **Training**: Security-focused training for development teams
- **Compliance**: Assistance with security compliance and audit requirements
**Response Expectations:**
- **General Questions**: 3-5 business days through community channels
- **Technical Support**: 1-2 business days for configuration assistance
- **Best Practices**: Community-driven responses with maintainer oversight
- **Professional Inquiries**: Direct contact for custom arrangements
## 📚 Additional Resources
### Security-Related Documentation
- [Contributing Guidelines](CONTRIBUTING.md) - Secure development practices
- [Installation Guide](README.md) - Secure installation procedures
- [Configuration Reference](SuperClaude/Settings/settings.json) - Security settings
**Framework Security Documentation:**
- [Best Practices Guide](Reference/best-practices.md) - Security-focused usage patterns
- [Technical Architecture](Developer-Guide/technical-architecture.md) - Security design principles
- [Contributing Code Guide](Developer-Guide/contributing-code.md) - Secure development practices
- [Testing & Debugging Guide](Developer-Guide/testing-debugging.md) - Security testing procedures
**MCP Server Security:**
- [MCP Servers Guide](User-Guide/mcp-servers.md) - Server security configuration
- [Troubleshooting Guide](Reference/troubleshooting.md) - Security-related issue resolution
- MCP Server Documentation - Individual server security considerations
- Configuration Security - Secure MCP setup and credential management
**Agent Security:**
- [Agents Guide](User-Guide/agents.md) - Agent security boundaries and coordination
- Agent Development - Security considerations for agent implementation
- Behavioral Modes - Security implications of different operational modes
- Command Security - Security aspects of command execution and validation
**Session Management Security:**
- [Session Management Guide](User-Guide/session-management.md) - Secure session handling
- Memory Security - Secure handling of persistent session data
- Project Isolation - Security boundaries between different projects
- Context Security - Secure context loading and validation
### External Security Resources
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Python Security Best Practices](https://python.org/dev/security/)
- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
**Security Standards and Frameworks:**
- **OWASP Top 10**: Web application security risks and mitigation strategies
- **NIST Cybersecurity Framework**: Comprehensive security risk management
- **CIS Controls**: Critical security controls for effective cyber defense
- **ISO 27001**: Information security management systems standard
**Python Security Resources:**
- **Python Security**: https://python-security.readthedocs.io/
- **Bandit**: Security linting for Python code
- **Safety**: Python dependency vulnerability scanning
- **PyUp.io**: Automated Python security monitoring
**Node.js Security Resources:**
- **Node.js Security Working Group**: https://github.com/nodejs/security-wg
- **npm audit**: Dependency vulnerability scanning
- **Snyk**: Comprehensive dependency security monitoring
- **Node Security Platform**: Security advisories and vulnerability database
**AI/ML Security:**
- **OWASP AI Security**: AI/ML security guidance and best practices
- **NIST AI Risk Management Framework**: AI system security considerations
- **Microsoft Responsible AI**: AI security and privacy best practices
- **Google AI Safety**: AI system safety and security research
**Development Security:**
- **OWASP DevSecOps**: Security integration in development workflows
- **GitHub Security Features**: Security scanning and dependency management
- **SAST Tools**: Static application security testing resources
- **Secure Code Review**: Security-focused code review practices
---
**Last Updated**: August 2025 (V4 Beta)
**Next Review**: November 2025
**Security Policy Maintenance:**
Thank you for helping keep SuperClaude Framework secure! 🙏
**Last Updated**: December 2024 (SuperClaude Framework v4.0)
**Next Review**: March 2025 (Quarterly review cycle)
**Version**: 4.0.0 (Updated for v4 architectural changes)
**Review Schedule:**
- **Quarterly Reviews**: Security policy accuracy and completeness assessment
- **Release Reviews**: Policy updates for new features and architectural changes
- **Incident Reviews**: Policy updates based on security incidents and lessons learned
- **Annual Assessment**: Comprehensive security policy and procedure review
**Change Management:**
- **Minor Updates**: Clarifications and contact information updates
- **Major Updates**: Architectural changes, new security features, and process improvements
- **Emergency Updates**: Critical security policy changes requiring immediate implementation
- **Community Input**: Regular solicitation of community feedback and improvement suggestions
**Security Contributor Acknowledgments:**
SuperClaude Framework's security posture benefits from community-driven security research, responsible disclosure, and collaborative improvement efforts.
**Security Contributors:**
- Security researchers who responsibly disclose vulnerabilities
- Community members who identify and report security configuration issues
- Developers who contribute security-focused code improvements and testing
- Documentation contributors who improve security guidance and best practices
**Recognition:**
- [GitHub Contributors](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) - Complete contributor recognition
- Security advisories include researcher acknowledgment and credit
- Annual security report highlights significant security contributions
- Community discussions celebrate helpful security guidance and support
**Ongoing Security Community:**
The SuperClaude security community continues growing through shared commitment to secure AI-assisted development workflows. Security-focused contributions, from vulnerability reports to secure coding practices, strengthen the framework for all users.
**Join Security Efforts:**
Whether you're reporting security issues, improving security documentation, or contributing security-focused code, your efforts help build more secure software development tools for the entire community.

326
User-Guide/agents.md Normal file
View File

@ -0,0 +1,326 @@
# SuperClaude Agents Guide 🤖
## Overview
SuperClaude employs 13 specialized AI agents that automatically activate based on task context and keywords. The intelligent routing system analyzes your requests and coordinates the most relevant domain experts for optimal results.
**Automatic Activation**: Type `/sc:implement "secure user login"` and watch as the security-engineer, backend-architect, and frontend-architect agents coordinate automatically.
**Intelligent Coordination**: Multiple agents can work together on complex tasks, with each contributing their specialized expertise to different aspects of the problem.
## 🚀 Just Try These (No Agent Knowledge Required)
**Automatic Agent Examples:**
```bash
# Triggers: security-engineer + backend-architect
/sc:implement "JWT authentication with rate limiting"
# Triggers: frontend-architect + ux-designer
/sc:design "responsive dashboard with accessibility"
# Triggers: devops-architect + performance-engineer
/sc:troubleshoot "slow deployment pipeline"
# Triggers: qa-specialist + security-engineer
/sc:test "payment processing security"
```
**Pattern Recognition Logic:**
- **Keywords**: "auth", "security" → security-engineer
- **File types**: ".jsx", ".vue" → frontend-architect
- **Context**: API endpoints → backend-architect
- **Complexity**: Multi-domain tasks → Multiple agents
---
## The SuperClaude Agent Team 👥
### Architecture & System Design Agents 🏗️
#### system-architect 🏢
**Expertise**: Large-scale system design, microservices, distributed architectures
**Auto-Activation**: "architecture", "microservices", "scalability", "system design"
**Capabilities**: Service boundaries, data flow design, technology selection, scalability planning
**Examples**: Microservices architecture, event-driven systems, API gateway design, database sharding strategies
---
#### backend-architect ⚙️
**Expertise**: Reliable backend systems, APIs, data integrity, fault tolerance
**Auto-Activation**: "API", "backend", "server", "database", "REST", "GraphQL"
**Capabilities**: API design, database modeling, error handling, authentication, caching strategies
**Examples**: REST API architecture, database schema design, authentication flows, message queue implementation
---
#### frontend-architect 🎨
**Expertise**: Accessible UI design, modern frameworks, performance optimization
**Auto-Activation**: "UI", "frontend", "React", "Vue", "component", "accessibility"
**Capabilities**: Component architecture, state management, accessibility compliance, performance optimization
**Examples**: React component hierarchies, state management patterns, responsive design systems, accessibility implementations
---
#### devops-architect 🚀
**Expertise**: Infrastructure automation, CI/CD, deployment strategies, observability
**Auto-Activation**: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring"
**Capabilities**: Pipeline design, containerization, orchestration, monitoring setup, deployment strategies
**Examples**: CI/CD pipeline configuration, Docker containerization, Kubernetes deployments, monitoring dashboards
### Quality & Analysis Agents 🔍
#### security-engineer 🔒
**Expertise**: Threat modeling, vulnerability assessment, security compliance
**Auto-Activation**: "security", "auth", "vulnerability", "encryption", "compliance"
**Capabilities**: Security audits, threat analysis, compliance validation, secure coding practices
**Examples**: Authentication systems, data encryption, vulnerability scanning, compliance reporting
---
#### performance-engineer ⚡
**Expertise**: Performance optimization, bottleneck identification, scalability tuning
**Auto-Activation**: "performance", "slow", "optimization", "bottleneck", "latency"
**Capabilities**: Performance profiling, optimization strategies, load testing, caching solutions
**Examples**: Database query optimization, API response time improvement, memory leak detection, caching implementation
---
#### root-cause-analyst 🔍
**Expertise**: Systematic problem investigation, evidence-based analysis, hypothesis testing
**Auto-Activation**: "bug", "issue", "problem", "debugging", "investigation"
**Capabilities**: Error analysis, dependency tracking, systematic debugging, evidence collection
**Examples**: Complex bug investigation, system failure analysis, performance degradation diagnosis
---
#### quality-engineer ✅
**Expertise**: Quality assurance, testing strategies, edge case detection
**Auto-Activation**: "test", "quality", "QA", "validation", "coverage"
**Capabilities**: Test strategy design, edge case identification, quality metrics, validation frameworks
**Examples**: Test suite architecture, quality gate implementation, automated testing, compliance validation
---
#### refactoring-expert 🔧
**Expertise**: Code quality improvement, SOLID principles, technical debt reduction
**Auto-Activation**: "refactor", "clean code", "technical debt", "SOLID", "maintainability"
**Capabilities**: Code structure improvement, design pattern application, debt identification, clean code practices
**Examples**: Legacy code modernization, design pattern implementation, code smell elimination, architecture improvement
### Specialized Development Agents 🎯
#### python-expert 🐍
**Expertise**: Production-ready Python development, modern frameworks, best practices
**Auto-Activation**: ".py" files, "Python", "Django", "FastAPI", "Flask", "asyncio"
**Capabilities**: Python architecture, framework selection, performance optimization, security practices
**Examples**: FastAPI applications, Django systems, async programming, Python packaging, data processing pipelines
---
#### requirements-analyst 📝
**Expertise**: Requirements discovery, specification development, stakeholder analysis
**Auto-Activation**: "requirements", "specification", "PRD", "user story", "functional"
**Capabilities**: Requirements elicitation, specification writing, stakeholder mapping, acceptance criteria
**Examples**: Product requirement documents, user story creation, functional specifications, acceptance criteria definition
### Communication & Learning Agents 📚
#### technical-writer 📚
**Expertise**: Technical documentation, audience analysis, clear communication
**Auto-Activation**: "documentation", "readme", "API docs", "user guide", "technical writing"
**Capabilities**: Documentation architecture, audience targeting, clarity optimization, information design
**Examples**: API documentation, user guides, technical tutorials, architecture documentation
---
#### learning-guide 🎓
**Expertise**: Educational content design, progressive learning, mentorship
**Auto-Activation**: "explain", "learn", "tutorial", "beginner", "teaching"
**Capabilities**: Learning path design, concept explanation, skill progression, educational assessment
**Examples**: Programming tutorials, concept explanations, skill assessments, learning roadmaps
---
## Agent Coordination & Integration 🤝
**Agent Collaboration Patterns:**
**Full-Stack Development**: frontend-architect + backend-architect + security-engineer
**Quality Assurance**: quality-engineer + performance-engineer + security-engineer
**System Design**: system-architect + devops-architect + performance-engineer
**Problem Solving**: root-cause-analyst + performance-engineer + security-engineer
**Multi-Domain Coordination:**
Complex projects automatically activate multiple agents based on scope and requirements. Agents coordinate through shared context and complementary expertise.
**MCP Server Integration:**
- **Context7**: Provides domain-specific patterns and documentation
- **Sequential**: Enables systematic multi-step reasoning
- **Magic**: Enhances UI/UX capabilities for frontend agents
- **Playwright**: Enables browser automation for testing agents
- **Morphllm**: Accelerates code transformation for refactoring agents
- **Serena**: Provides project memory and context for all agents
**Command Integration:**
Each SuperClaude command automatically selects appropriate agents:
- `/sc:implement` → domain-specific architects (frontend, backend, security)
- `/sc:analyze` → quality-engineer + security-engineer + performance-engineer
- `/sc:troubleshoot` → root-cause-analyst + domain specialists
- `/sc:improve` → refactoring-expert + performance-engineer
- `/sc:document` → technical-writer + domain specialists
## Quick Reference 📋
| Agent | Domain | Key Triggers | Best For |
|-------|--------|--------------|----------|
| system-architect | Architecture | "architecture", "microservices" | Large-scale design |
| backend-architect | Backend | "API", "server", "database" | Server-side systems |
| frontend-architect | Frontend | "UI", "React", "component" | User interfaces |
| devops-architect | Infrastructure | "deploy", "CI/CD", "Docker" | DevOps & deployment |
| security-engineer | Security | "security", "auth", "vulnerability" | Security & compliance |
| performance-engineer | Performance | "performance", "optimization" | Speed & efficiency |
| quality-engineer | Quality | "test", "quality", "validation" | Testing & QA |
| refactoring-expert | Code Quality | "refactor", "clean code" | Code improvement |
| root-cause-analyst | Debugging | "bug", "issue", "debugging" | Problem investigation |
| python-expert | Python | ".py", "Python", "Django" | Python development |
| requirements-analyst | Analysis | "requirements", "PRD" | Requirements gathering |
| technical-writer | Documentation | "documentation", "API docs" | Technical writing |
| learning-guide | Education | "explain", "tutorial" | Teaching & learning |
**Most Useful Agent Combinations:**
**Web Application**: frontend-architect + backend-architect + security-engineer
**API Development**: backend-architect + security-engineer + technical-writer
**Legacy Modernization**: refactoring-expert + system-architect + quality-engineer
**Security Audit**: security-engineer + quality-engineer + root-cause-analyst
**Performance Optimization**: performance-engineer + system-architect + devops-architect
**Multi-Agent Workflow Examples:**
```bash
# E-commerce platform (4 agents activate)
/sc:implement "secure payment processing with fraud detection"
# → backend-architect + security-engineer + quality-engineer + performance-engineer
# Learning platform (3 agents activate)
/sc:design "interactive coding tutorial system"
# → frontend-architect + learning-guide + technical-writer
```
## Best Practices 💡
**Getting Started (Simple Approach):**
1. **Start Simple**: Just describe what you want - agents activate automatically
2. **Trust the System**: SuperClaude selects the right experts for your context
3. **Learn from Patterns**: Notice which agents activate for different tasks
4. **Gradual Complexity**: Add more detail to trigger additional specialist agents
**Advanced Agent Control:**
- **Cross-Domain Projects**: Combine keywords to trigger multiple agents
- **Specific Expertise**: Use domain-specific terminology for targeted activation
- **Quality Focus**: Include "security", "performance", "quality" for comprehensive coverage
- **Learning Mode**: Add "explain" or "tutorial" to include educational perspective
**Common Usage Patterns:**
**New Project Startup:**
```bash
/sc:brainstorm "fintech mobile app"
# → Activates: system-architect + frontend-architect + security-engineer
```
**Existing Code Analysis:**
```bash
/sc:analyze src/ --focus security
# → Activates: security-engineer + quality-engineer + refactoring-expert
```
**Learning & Understanding:**
```bash
/sc:explain "microservices architecture patterns"
# → Activates: system-architect + learning-guide + technical-writer
```
**Performance Investigation:**
```bash
/sc:troubleshoot "API response time > 2 seconds"
# → Activates: performance-engineer + root-cause-analyst + backend-architect
```
**Quality Improvement:**
```bash
/sc:improve legacy-code/ --focus maintainability
# → Activates: refactoring-expert + quality-engineer + technical-writer
```
---
## Final Notes 📝
**The Truth About Agent Usage:**
SuperClaude agents activate automatically based on keywords and context - you don't need to manage them. The system is designed to be sophisticated under the hood while remaining simple to use.
**Agent Knowledge Usefulness:**
- **Useful**: Understanding why certain agents activate can help you craft better commands
- **Useful**: Knowing agent specialties helps you choose the right keywords and approaches
- **Unnecessary**: Manual agent selection or micromanagement - the system handles this
- **Unnecessary**: Memorizing all agent capabilities - the system routes intelligently
**Simple Usage Approach:**
1. **Focus on Your Goal**: Describe what you want to accomplish clearly
2. **Use Natural Language**: Include domain keywords naturally ("security", "performance", "UI")
3. **Trust the System**: Let SuperClaude activate appropriate agents automatically
4. **Learn from Results**: Notice which agents activate and why, but don't force it
---
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../Getting-Started/quick-start.md) - Get up and running with basic commands
- [Installation Guide](../Getting-Started/installation.md) - Setup and configuration
- [Commands Guide](commands.md) - Master core commands that trigger agents
**🌿 Recommended (Week 2-3)**
- [Behavioral Modes](modes.md) - Context optimization and agent coordination
- [Examples Cookbook](../Reference/examples-cookbook.md) - Practical patterns and workflows
- [Best Practices](../Reference/best-practices.md) - Agent optimization strategies
**🌳 Advanced (Month 2+)**
- [MCP Servers](mcp-servers.md) - Enhanced capabilities through server integration
- [Session Management](session-management.md) - Long-term workflows and persistence
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - System understanding
**🔧 Expert Development**
- [Contributing Code](../Developer-Guide/contributing-code.md) - Framework development
- [Testing & Debugging](../Developer-Guide/testing-debugging.md) - Quality procedures
---
**Your SuperClaude Agent Journey:**
SuperClaude's agent system represents the best of both worlds: sophisticated coordination happening automatically behind a simple, intuitive interface. You get the benefit of 13 specialized experts without the complexity of managing them.
**The Magic is in the Simplicity:**
- Type `/sc:implement "secure user login"` and watch security engineers, backend architects, and frontend specialists coordinate seamlessly
- No agent configuration, no manual routing, no complex setup - just describe your goal and let the system work
- The more you use SuperClaude, the better you'll understand the patterns, but you never need to micromanage the agents
**Start Simple, Stay Simple:**
Begin with basic commands and let complexity emerge naturally. SuperClaude handles the orchestration so you can focus on building great software. The agent system grows with your needs while maintaining the same straightforward interface.
🚀 **Ready to experience intelligent agent coordination? Try `/sc:brainstorm` and watch the magic happen.**

767
User-Guide/commands.md Normal file
View File

@ -0,0 +1,767 @@
# SuperClaude Commands Guide 🛠️
## 💡 Don't Overthink It - SuperClaude Tries to Help
SuperClaude provides 21 specialized commands that automatically coordinate domain experts, MCP servers, and behavioral modes based on context. The system intelligently routes tasks to appropriate specialists while maintaining a simple, discoverable interface.
**Auto-Activation Philosophy**: Type `/sc:implement "user auth"` and watch as the security specialist activates, Context7 provides authentication patterns, and quality gates ensure completeness.
**Progressive Discovery**: Use `/sc:index` to explore commands relevant to your current context.
## Core Philosophy
**Core Principles:**
- **Context-Aware Routing**: Commands analyze intent and activate appropriate specialists
- **Safety First**: Dry-run options, backup creation, and validation gates
- **Progressive Enhancement**: Simple tasks stay simple, complex tasks get expert attention
- **Session Persistence**: Long-running workflows maintained across sessions
**Intelligent Activation:**
1. Parse command intent and parameters
2. Analyze complexity and domain requirements
3. Activate relevant specialists (frontend, backend, security, etc.)
4. Connect appropriate MCP servers (Context7, Sequential, Magic)
5. Apply behavioral modes (brainstorming, orchestration, etc.)
6. Execute with quality gates and progress tracking
---
## Quick "Just Try These" List 🚀
**Essential Commands (Start Here):**
```bash
/sc:brainstorm "mobile app idea" # Interactive discovery
/sc:analyze src/ # Code analysis
/sc:implement "user login" # Feature implementation
/sc:troubleshoot "API not working" # Problem solving
/sc:test --coverage # Quality assurance
```
**Discovery Pattern:**
1. Use `/sc:index` to explore available commands
2. Try `/sc:brainstorm` for project planning
3. Progress to `/sc:implement` for development
4. Use `/sc:reflect` to validate completion
---
**Realistic Command Assessment:**
**Highly Mature** (🔥 Production Ready): brainstorm, analyze, implement, troubleshoot
**Well Developed** (✅ Reliable): workflow, design, test, document, git
**Solid Foundation** (🔧 Functional): improve, cleanup, build, load, save
**Emerging** (🌱 Growing): spawn, task, estimate, reflect, select-tool
**Experimental** (🧪 Testing): index, explain
**Expectation**: Core commands deliver consistent results. Emerging commands are improving rapidly with each release.
## Quick Reference 📋
## Command Reference
| Command | Category | Specialists | MCP Servers | Best For |
|---------|----------|-------------|-------------|----------|
| **brainstorm** | Discovery | architect, analyst | sequential, context7 | Requirements exploration |
| **workflow** | Planning | architect, pm | sequential | Implementation planning |
| **implement** | Development | frontend, backend, security | context7, magic | Feature creation |
| **build** | Development | devops | - | Compilation, packaging |
| **design** | Planning | architect, ux | - | System architecture |
| **analyze** | Quality | analyzer | - | Code assessment |
| **troubleshoot** | Debug | analyzer, devops | sequential | Problem diagnosis |
| **explain** | Learning | - | - | Code explanation |
| **improve** | Quality | analyzer | morphllm | Code enhancement |
| **cleanup** | Quality | analyzer | morphllm | Technical debt |
| **test** | Quality | qa-specialist | playwright | Testing, validation |
| **document** | Quality | doc-specialist | - | Documentation |
| **estimate** | Planning | pm | - | Project estimation |
| **task** | Management | pm | serena | Task coordination |
| **spawn** | Management | pm | serena | Complex orchestration |
| **git** | Utility | devops | - | Version control |
| **index** | Utility | - | - | Command discovery |
| **load** | Session | - | serena | Context loading |
| **save** | Session | - | serena | Session persistence |
| **reflect** | Session | - | serena | Task validation |
| **select-tool** | Meta | - | all | Tool optimization |
**Selection Strategy**: Commands auto-activate based on keywords, file types, and project context. Use `/sc:select-tool` for optimization recommendations.
## Development Commands 🔨
### /sc:workflow - Implementation Planning
**Purpose**: Generate structured implementation workflows from PRDs and feature requirements
**Usage**:
```bash
/sc:workflow "user authentication system"
/sc:workflow --strategy agile --format markdown
/sc:workflow "payment integration" --depth detailed
```
**Expert Activation**: Architect + Project Manager
**MCP Integration**: Sequential for structured analysis
**Examples**:
```bash
# Basic workflow generation
/sc:workflow "real-time chat feature"
# Agile sprint planning
/sc:workflow "e-commerce cart" --strategy agile --format sprint
# Enterprise architecture
/sc:workflow "microservices migration" --strategy enterprise
```
**Output**: Structured tasks, dependency mapping, time estimates, risk assessment
### /sc:implement - Feature Implementation
**Purpose**: Feature and code implementation with intelligent persona activation and MCP integration
**Usage**:
```bash
/sc:implement "user login with JWT"
/sc:implement --type frontend --framework react
/sc:implement "REST API" --focus security --validate
```
**Expert Activation**: Context-dependent (frontend, backend, security, database)
**MCP Integration**: Context7 (patterns), Magic (UI), Sequential (complex logic)
**Examples**:
```bash
# Full-stack feature
/sc:implement "user registration with email verification"
# Frontend focus
/sc:implement "responsive dashboard" --type frontend
# Security-focused
/sc:implement "OAuth integration" --focus security
# API development
/sc:implement "GraphQL mutations" --type backend --validate
```
**Auto-Activation Patterns**:
- "UI", "component" → Frontend specialist + Magic MCP
- "API", "endpoint" → Backend specialist + Context7
- "auth", "security" → Security specialist + validation gates
- "database", "schema" → Database specialist
---
### /sc:build - Project Building
**Purpose**: Build, compile, and package projects with intelligent error handling and optimization
**Usage**:
```bash
/sc:build
/sc:build --optimize --parallel
/sc:build --target production --fix-errors
```
**Expert Activation**: DevOps specialist
**Build System Detection**: npm, webpack, cargo, maven, gradle, make
**Examples**:
```bash
# Basic build
/sc:build
# Production optimization
/sc:build --target production --optimize
# Parallel compilation
/sc:build --parallel --jobs 4
# Error fixing
/sc:build --fix-errors --verbose
```
**Common Issues & Solutions**:
- **Missing dependencies**: Auto-installs with confirmation
- **Version conflicts**: Suggests resolution strategies
- **Memory issues**: Optimizes build parameters
- **Type errors**: Provides TypeScript fixes
---
### /sc:design - System Design
**Purpose**: Design system architecture, APIs, and component interfaces with comprehensive specifications
**Usage**:
```bash
/sc:design "microservices architecture"
/sc:design --type api --format openapi
/sc:design "database schema" --focus performance
```
**Expert Activation**: Architect + UX Designer (for UI)
**Output Formats**: Markdown, Mermaid diagrams, OpenAPI specs, ERD
**Examples**:
```bash
# System architecture
/sc:design "e-commerce platform architecture"
# API specification
/sc:design "REST API for blog" --type api --format openapi
# Database design
/sc:design "user management schema" --type database
# Component architecture
/sc:design "React component hierarchy" --type frontend
```
**Design Types**:
- **system**: Full architecture with service boundaries
- **api**: REST/GraphQL specifications
- **database**: Schema design with relationships
- **frontend**: Component and state architecture
- **integration**: Service communication patterns
## Analysis Commands 🔍
### /sc:analyze - Code Analysis
**Purpose**: Comprehensive code analysis across quality, security, performance, and architecture domains
**Usage**:
```bash
/sc:analyze src/
/sc:analyze --focus security --depth deep
/sc:analyze . --format report --export html
```
**Expert Activation**: Analyzer + domain specialists based on focus
**Language Support**: Python, JavaScript, TypeScript, Java, C++, Rust, Go, and more
**Examples**:
```bash
# Full project analysis
/sc:analyze .
# Security audit
/sc:analyze src/ --focus security --depth deep
# Performance bottlenecks
/sc:analyze --focus performance --profile
# Architecture review
/sc:analyze --focus architecture --dependencies
```
**Focus Areas**:
- **quality**: Code smells, maintainability, complexity
- **security**: Vulnerabilities, best practices, compliance
- **performance**: Bottlenecks, optimization opportunities
- **architecture**: Dependencies, coupling, design patterns
---
### /sc:troubleshoot - Problem Diagnosis
**Purpose**: Diagnose and resolve issues in code, builds, deployments, and system behavior
**Usage**:
```bash
/sc:troubleshoot "API returns 500 error"
/sc:troubleshoot --logs server.log --focus performance
/sc:troubleshoot --type build --verbose
```
**Expert Activation**: Analyzer + DevOps (for deployment issues)
**MCP Integration**: Sequential for systematic debugging
**Examples**:
```bash
# General issue diagnosis
/sc:troubleshoot "users can't login"
# Build failures
/sc:troubleshoot --type build --fix-suggestions
# Performance issues
/sc:troubleshoot "slow page load" --logs access.log
# Database problems
/sc:troubleshoot "connection timeout" --focus database
```
**Systematic Methodology**:
1. **Symptom Analysis**: Parse error messages and logs
2. **Root Cause Investigation**: Follow dependency chains
3. **Hypothesis Testing**: Validate potential causes
4. **Solution Ranking**: Prioritize fixes by impact/effort
5. **Verification**: Ensure resolution doesn't break other components
---
### /sc:explain - Code & Concept Explanation
**Purpose**: Provide clear explanations of code, concepts, and system behavior with educational clarity
**Usage**:
```bash
/sc:explain "async/await in JavaScript"
/sc:explain src/auth.py --level beginner
/sc:explain --concept "dependency injection" --examples
```
**Teaching Approaches**: Beginner, intermediate, expert levels with progressive detail
**Educational Focus**: Concepts, patterns, best practices, common pitfalls
**Examples**:
```bash
# Code explanation
/sc:explain src/components/UserAuth.jsx
# Concept clarification
/sc:explain "microservices vs monolith" --pros-cons
# Pattern explanation
/sc:explain "observer pattern" --examples react
# Beginner-friendly
/sc:explain "what is REST API" --level beginner --examples
```
**Explanation Styles**:
- **code-walkthrough**: Line-by-line code analysis
- **concept**: High-level explanation with examples
- **pattern**: Design pattern with use cases
- **comparison**: Side-by-side analysis of approaches
- **tutorial**: Step-by-step learning progression
## Quality Commands ✨
### /sc:improve - Code Enhancement
**Purpose**: Apply systematic improvements to code quality, performance, and maintainability
**Usage**:
```bash
/sc:improve src/components/
/sc:improve --type performance --preview
/sc:improve . --focus maintainability --safe-mode
```
**Expert Activation**: Analyzer + Performance Engineer (for performance focus)
**MCP Integration**: Morphllm for pattern-based improvements
**Examples**:
```bash
# General improvements
/sc:improve src/
# Performance optimization
/sc:improve --type performance --measure-impact
# Code quality enhancement
/sc:improve --focus quality --preview --backup
# Safe refactoring
/sc:improve legacy/ --safe-mode --tests-required
```
**Improvement Types**:
- **performance**: Optimization, caching, algorithm improvements
- **quality**: Code smells, readability, maintainability
- **security**: Vulnerability fixes, best practices
- **accessibility**: UI/UX improvements
- **architecture**: Design pattern application
---
### /sc:cleanup - Technical Debt Reduction
**Purpose**: Systematically clean up code, remove dead code, and optimize project structure
**Usage**:
```bash
/sc:cleanup
/sc:cleanup --type imports --organize
/sc:cleanup --dead-code --confirm-before-delete
```
**Expert Activation**: Analyzer
**MCP Integration**: Morphllm for pattern-based cleanup
**Examples**:
```bash
# Full project cleanup
/sc:cleanup --comprehensive --backup
# Import optimization
/sc:cleanup --type imports --sort --remove-unused
# Dead code removal
/sc:cleanup --dead-code --analyze-usage
# File organization
/sc:cleanup --organize-files --follow-conventions
```
**Cleanup Operations**:
- **dead-code**: Unused functions, variables, imports
- **imports**: Sort, deduplicate, organize imports
- **formatting**: Consistent code style
- **files**: Directory organization and naming
- **dependencies**: Remove unused packages
---
### /sc:test - Testing & Quality Assurance
**Purpose**: Execute tests with coverage analysis and automated quality reporting
**Usage**:
```bash
/sc:test
/sc:test --type e2e --coverage
/sc:test --fix --watch
```
**Expert Activation**: QA Specialist
**MCP Integration**: Playwright (for E2E testing)
**Examples**:
```bash
# Run all tests
/sc:test --coverage --report
# Unit tests only
/sc:test --type unit --watch
# E2E browser testing
/sc:test --type e2e --browsers chrome,firefox
# Fix failing tests
/sc:test --fix --preview-changes
```
**Test Types**:
- **unit**: Individual function/component testing
- **integration**: Module interaction testing
- **e2e**: End-to-end browser automation
- **performance**: Load and stress testing
- **accessibility**: WCAG compliance validation
## Documentation Commands 📝
### /sc:document - Documentation Generation
**Purpose**: Generate focused documentation for components, functions, APIs, and features
**Usage**:
```bash
/sc:document src/api/
/sc:document --type api --format openapi
/sc:document . --style technical --audience developers
```
**Expert Activation**: Documentation Specialist
**Documentation Types**: API docs, README, inline comments, user guides
**Examples**:
```bash
# Component documentation
/sc:document src/components/ --inline-comments
# API documentation
/sc:document --type api --format swagger
# User documentation
/sc:document --type user-guide --audience end-users
# Technical documentation
/sc:document --style technical --diagrams
```
**Documentation Styles**:
- **technical**: Developer-focused with code examples
- **user**: End-user guides and tutorials
- **api**: REST/GraphQL API specifications
- **inline**: Code comments and docstrings
- **architectural**: System design documentation
## Project Management Commands 📊
### /sc:estimate - Project Estimation
**Purpose**: Provide development estimates for tasks, features, or projects with intelligent analysis
**Usage**: `/sc:estimate "user authentication system"`, `/sc:estimate --detailed --team-size 3`
**Expert Activation**: Project Manager
**Features**: Time estimates, complexity analysis, resource allocation, risk assessment
**Examples**: Project estimates, sprint planning, resource allocation, timeline forecasting
---
### /sc:task - Project Management
**Purpose**: Execute complex tasks with intelligent workflow management and delegation
**Usage**: `/sc:task "implement payment system"`, `/sc:task --breakdown --priority high`
**Expert Activation**: Project Manager
**MCP Integration**: Serena for task persistence
**Features**: Task breakdown, priority management, cross-session tracking, dependency mapping
---
### /sc:spawn - Meta-System Orchestration
**Purpose**: Meta-system task orchestration with intelligent breakdown and delegation
**Usage**: `/sc:spawn "full-stack e-commerce platform"`, `/sc:spawn --parallel --monitor`
**Expert Activation**: Project Manager + Multiple domain specialists
**Features**: Complex workflow orchestration, parallel execution, progress monitoring, resource management
## Version Control Commands 🔄
### /sc:git - Version Control
**Purpose**: Git operations with intelligent commit messages and workflow optimization
**Usage**: `/sc:git commit "add user auth"`, `/sc:git --smart-messages --conventional`
**Expert Activation**: DevOps specialist
**Features**: Smart commit messages, branch management, conflict resolution, workflow optimization
**Examples**: Intelligent commits, branch strategies, merge conflict resolution, release management
## Utility Commands 🔧
### /sc:index - Command Discovery
**Purpose**: Generate comprehensive project documentation and knowledge base with intelligent organization
**Usage**: `/sc:index`, `/sc:index --category development`, `/sc:index --search "testing"`
**Features**: Command discovery, capability exploration, contextual recommendations, usage patterns
**Examples**: Find relevant commands, explore capabilities, discover usage patterns, get contextual help
---
### /sc:load - Session Context Loading
**Purpose**: Session lifecycle management with Serena MCP integration for project context loading
**Usage**: `/sc:load src/`, `/sc:load --focus architecture`, `/sc:load "previous session"`
**Expert Activation**: Context analysis
**MCP Integration**: Serena for project memory
**Features**: Project structure analysis, context restoration, session initialization, intelligent onboarding
## Session & Intelligence Commands 🧠
### /sc:brainstorm - Interactive Requirements Discovery
**Purpose**: Interactive requirements discovery through Socratic dialogue and systematic exploration
**Usage**: `/sc:brainstorm "mobile app idea"`, `/sc:brainstorm --strategy systematic --depth deep`
**Expert Activation**: Architect + Analyst + PM
**MCP Integration**: Sequential for structured reasoning, Context7 for patterns
**Features**: Socratic dialogue, requirement elicitation, PRD generation, feasibility analysis, creative problem solving
---
### /sc:reflect - Task Reflection & Validation
**Purpose**: Task reflection and validation using Serena MCP analysis capabilities
**Usage**: `/sc:reflect`, `/sc:reflect --type completion`, `/sc:reflect "payment integration"`
**Expert Activation**: Context analysis
**MCP Integration**: Serena for intelligence analysis
**Features**: Progress analysis, completion validation, quality assessment, next steps recommendation
---
### /sc:save - Session Persistence
**Purpose**: Session lifecycle management with Serena MCP integration for session context persistence
**Usage**: `/sc:save "payment-integration-complete"`, `/sc:save --checkpoint --description "auth module done"`
**Expert Activation**: Session management
**MCP Integration**: Serena for context persistence
**Features**: Session checkpointing, context preservation, progress tracking, cross-session continuity
---
### /sc:select-tool - Intelligent Tool Selection
**Purpose**: Intelligent MCP tool selection based on complexity scoring and operation analysis
**Usage**: `/sc:select-tool "implement user auth"`, `/sc:select-tool --analyze-complexity --recommend`
**Expert Activation**: Meta-analysis
**MCP Integration**: All servers for capability assessment
**Features**: Complexity analysis, tool recommendation, MCP coordination, optimization strategies, resource planning
## Command Tips & Patterns 💡
**Effective Flag Combinations:**
```bash
# Development workflow
/sc:analyze --focus quality && /sc:improve --preview && /sc:test --coverage
# Production preparation
/sc:build --optimize --target production && /sc:test --type e2e
# Deep analysis
/sc:analyze --focus security --depth deep --export report
# Safe refactoring
/sc:improve --safe-mode --backup --tests-required
```
**Command Chaining Strategies:**
- **Analysis → Improvement → Testing**: Quality enhancement workflow
- **Brainstorm → Design → Implement**: Feature development lifecycle
- **Load → Analyze → Reflect**: Project onboarding pattern
- **Build → Test → Document**: Release preparation sequence
**Common Workflow Patterns:**
**New Project Onboarding:**
```bash
/sc:load . → /sc:analyze --comprehensive → /sc:document --type overview → /sc:save "project-analyzed"
```
**Feature Development:**
```bash
/sc:brainstorm "feature idea" → /sc:design → /sc:implement → /sc:test → /sc:document
```
**Bug Investigation:**
```bash
/sc:troubleshoot "issue description" → /sc:analyze --focus problem-area → /sc:improve --fix
```
**Pre-Deployment:**
```bash
/sc:test --comprehensive → /sc:analyze --focus security → /sc:build --production → /sc:git commit
```
**Quality Improvement:**
```bash
/sc:analyze --focus quality → /sc:cleanup → /sc:improve → /sc:test → /sc:reflect
```
**Common Issues & Solutions:**
**Command Not Found:**
- Verify SuperClaude installation: `SuperClaude --version`
- Check component installation: `SuperClaude install --list-components`
- Restart Claude Code session
**Slow Performance:**
- Use `--scope file` to limit analysis scope
- Enable specific MCP servers only: `--c7 --seq` instead of `--all-mcp`
- Use `--concurrency 2` to limit parallel operations
**MCP Server Issues:**
- Check server status: `ls ~/.claude/.claude.json`
- Restart with: `SuperClaude install --components mcp --force`
- Use `--no-mcp` for native-only execution
**Scope Management:**
- Use `--scope file|module|project` to control analysis depth
- Limit with `--focus` specific areas
- Use `--dry-run` for preview without execution
---
## Final Notes 📝
**Command Reliability & Evolution:**
SuperClaude commands are actively developed with regular improvements. Core commands (brainstorm, analyze, implement) are production-ready, while emerging commands (spawn, estimate) are rapidly maturing.
**Discovery-Based Learning:**
1. Start with `/sc:index` to explore available commands
2. Use `/sc:brainstorm` for project-specific guidance
3. Try commands in `--dry-run` mode first
4. Progress from simple to complex commands naturally
5. Save successful patterns with `/sc:save`
**Getting Help:**
- In-app: `/sc:index --help` or `/sc:explain "command name"`
- Documentation: [SuperClaude Guides](../README.md)
- Issues: [GitHub Repository](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
- Community: [Discussions](https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions)
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../Getting-Started/quick-start.md) - Get up and running
- [Installation Guide](../Getting-Started/installation.md) - Setup and configuration
- This Commands Guide - Master core commands
**🌿 Recommended (Week 2-3)**
- [Behavioral Modes](modes.md) - Context optimization
- [Agents Guide](agents.md) - Specialist coordination
- [Examples Cookbook](../Reference/examples-cookbook.md) - Practical patterns
**🌳 Advanced (Month 2+)**
- [MCP Servers](mcp-servers.md) - Enhanced capabilities
- [Best Practices](../Reference/best-practices.md) - Optimization mastery
- [Session Management](session-management.md) - Long-term workflows
**🔧 Expert**
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - System understanding
- [Contributing Code](../Developer-Guide/contributing-code.md) - Framework development
## Command Flags & Options
**Common Flags Across Commands:**
**Scope Control**: `--scope file|module|project|system`
**Focus Areas**: `--focus quality|security|performance|architecture`
**Output Control**: `--format text|json|html|markdown`
**Safety**: `--dry-run`, `--backup`, `--safe-mode`
**Performance**: `--parallel`, `--concurrency N`
**MCP Control**: `--c7`, `--seq`, `--magic`, `--morph`, `--serena`, `--play`
**Expert Activation System:**
- **Context-based**: Keywords trigger appropriate specialists
- **Domain-specific**: Frontend, backend, security, DevOps, QA
- **Progressive**: Simple tasks use fewer experts, complex tasks activate multiple
- **Intelligent routing**: Best expert for each subtask
**MCP Server Integration:**
- **Context7**: Documentation and patterns
- **Sequential**: Multi-step reasoning
- **Magic**: UI component generation
- **Playwright**: Browser automation
- **Morphllm**: Code transformation
- **Serena**: Session and memory management
---
**Your SuperClaude Journey:**
SuperClaude grows with you. Start simple with `/sc:brainstorm` and `/sc:analyze`, then discover advanced capabilities naturally. Each command learns from your usage patterns and becomes more helpful over time.
🚀 **The magic happens when you stop thinking about tools and start focusing on your goals.** SuperClaude handles the orchestration, expert coordination, and quality gates automatically.
**Remember**: There's no wrong way to explore. Use `/sc:index` whenever you need guidance, and don't hesitate to experiment with new commands and flag combinations.

780
User-Guide/flags.md Normal file
View File

@ -0,0 +1,780 @@
# SuperClaude Framework Flags User Guide 🏁
## 🤖 Most Flags Activate Automatically - Don't Stress About It!
SuperClaude's intelligent flag system automatically detects task complexity and context, then activates appropriate flags behind the scenes. You get optimized performance without memorizing flag combinations.
**Intelligent Auto-Activation**: Type `/sc:analyze large-codebase/` → `--think-hard` + `--serena` + `--orchestrate` activate automatically. Type complex multi-file operations → `--task-manage` + `--delegate` optimize execution. Work under resource pressure → `--uc` compresses output.
**Manual Override Available**: When you want specific behavior, flags provide precise control. But in most cases, SuperClaude's automatic selection delivers optimal results.
---
## 🚀 Just Try These (No Flag Knowledge Required)
**Commands Work Great Without Flags:**
```bash
# These automatically get optimal flags
/sc:brainstorm "mobile fitness app"
# → Auto-activates: --brainstorm, --think, --context7
/sc:analyze src/ --focus security
# → Auto-activates: --think-hard, --serena, --orchestrate
/sc:implement "user authentication system"
# → Auto-activates: --task-manage, --c7, --magic, --validate
/sc:troubleshoot "API performance issues"
# → Auto-activates: --think-hard, --seq, --serena, --introspect
/sc:improve legacy-code/ --focus maintainability
# → Auto-activates: --task-manage, --morph, --serena, --safe-mode
```
**Behind-the-Scenes Optimization:**
- **Context Analysis**: Keywords trigger appropriate specialists and tools
- **Complexity Detection**: Multi-file operations get coordination flags
- **Resource Awareness**: System load triggers efficiency optimizations
- **Quality Gates**: Risky operations automatically enable safety flags
- **Performance Tuning**: Optimal tool combinations selected automatically
**When Manual Flags Help:**
- Override automatic detection: `--no-mcp` for lightweight execution
- Force specific behavior: `--uc` for compressed output
- Learning and exploration: `--introspect` to see reasoning
- Resource control: `--concurrency 2` to limit parallel operations
---
## What Are Flags? 🤔
**Flags are Modifiers** that adjust SuperClaude's behavior for specific contexts and requirements:
**Flag Syntax:**
```bash
/sc:command [args] --flag-name [value]
# Examples
/sc:analyze src/ --focus security --depth deep
/sc:implement "auth" --brainstorm --task-manage --validate
/sc:troubleshoot issue/ --think-hard --uc --concurrency 3
```
**Two Types of Activation:**
1. **Automatic** (90% of use): SuperClaude detects context and activates optimal flags
2. **Manual** (10% of use): You override or specify exact behavior needed
**Flag Functions:**
- **Behavioral Modes**: `--brainstorm`, `--introspect`, `--task-manage`
- **Tool Selection**: `--c7`, `--seq`, `--magic`, `--morph`, `--serena`, `--play`
- **Analysis Depth**: `--think`, `--think-hard`, `--ultrathink`
- **Efficiency Control**: `--uc`, `--concurrency`, `--scope`
- **Safety & Quality**: `--safe-mode`, `--validate`, `--dry-run`
**Auto-Activation vs Manual Override:**
- **Auto**: `/sc:implement "React dashboard"` → Magic + Context7 + task coordination
- **Manual**: `/sc:implement "simple function" --no-mcp` → Native-only execution
## Flag Categories 📂
### Planning & Analysis Flags 🧠
**Thinking Depth Control:**
**`--think`** - Standard Analysis (~4K tokens)
- **Auto-Triggers**: Multi-component analysis, moderate complexity
- **Manual Use**: Force structured thinking for simple tasks
- **Enables**: Sequential MCP for systematic reasoning
```bash
/sc:analyze auth-system/ --think
# → Structured analysis with evidence-based reasoning
```
**`--think-hard`** - Deep Analysis (~10K tokens)
- **Auto-Triggers**: Architectural analysis, system-wide dependencies
- **Manual Use**: Force comprehensive analysis
- **Enables**: Sequential + Context7 for deep understanding
```bash
/sc:troubleshoot "performance degradation" --think-hard
# → Comprehensive root cause analysis with framework patterns
```
**`--ultrathink`** - Maximum Analysis (~32K tokens)
- **Auto-Triggers**: Critical system redesign, legacy modernization
- **Manual Use**: Force maximum analytical depth
- **Enables**: All MCP servers for comprehensive capability
```bash
/sc:analyze enterprise-architecture/ --ultrathink
# → Maximum depth with all tools and reasoning capacity
```
**Mode Activation Flags:**
**`--brainstorm`** / **`--bs`** - Interactive Discovery
- **Auto-Triggers**: Vague requests, exploration keywords
- **Manual Use**: Force collaborative requirement discovery
```bash
/sc:implement "better user experience" --brainstorm
# → Socratic questions to clarify requirements before implementation
```
**`--introspect`** - Reasoning Transparency
- **Auto-Triggers**: Error recovery, learning contexts
- **Manual Use**: Expose decision-making process for learning
```bash
/sc:analyze complex-algorithm/ --introspect
# → Transparent reasoning with 🤔, 🎯, ⚡ markers
```
### Efficiency & Control Flags ⚡
**Output Compression:**
**`--uc`** / **`--ultracompressed`** - Token Efficiency (30-50% reduction)
- **Auto-Triggers**: Context usage >75%, large operations, resource pressure
- **Manual Use**: Force compressed communication
- **Effect**: Symbol-enhanced output while preserving ≥95% information quality
```bash
/sc:analyze large-project/ --uc
# → "auth.js:45 → 🛡️ sec risk in user val()" vs verbose explanations
```
**`--token-efficient`** - Moderate Compression
- **Auto-Triggers**: Medium resource pressure, efficiency requirements
- **Manual Use**: Balance between detail and efficiency
```bash
/sc:troubleshoot "memory leak" --token-efficient
# → Structured but concise problem analysis
```
**Execution Control:**
**`--concurrency [n]`** - Parallel Operation Control (1-15)
- **Auto-Triggers**: Resource optimization needs
- **Manual Use**: Control system load and parallel processing
```bash
/sc:improve large-codebase/ --concurrency 3
# → Limit to 3 parallel operations for resource management
```
**`--scope [file|module|project|system]`** - Analysis Boundary
- **Auto-Triggers**: Analysis boundary detection
- **Manual Use**: Explicitly define operational scope
```bash
/sc:analyze src/auth/ --scope module
# → Focus analysis on authentication module only
```
**`--loop`** / **`--iterations [n]`** - Iterative Improvement
- **Auto-Triggers**: "polish", "refine", "enhance", "improve" keywords
- **Manual Use**: Force iterative improvement cycles
```bash
/sc:improve user-interface/ --loop --iterations 3
# → 3 improvement cycles with validation gates
```
### Focus & Specialization Flags 🎯
**Domain-Specific Analysis:**
**`--focus [domain]`** - Target Expertise Application
- **Available Domains**: `performance`, `security`, `quality`, `architecture`, `accessibility`, `testing`
- **Auto-Triggers**: Domain-specific keywords and file patterns
- **Manual Use**: Force specific analytical perspective
```bash
# Security-focused analysis
/sc:analyze payment-system/ --focus security
# → Security specialist + vulnerability assessment + compliance validation
# Performance optimization focus
/sc:improve api-endpoints/ --focus performance
# → Performance engineer + bottleneck analysis + optimization patterns
# Architecture evaluation
/sc:analyze microservices/ --focus architecture
# → System architect + design pattern analysis + scalability assessment
# Quality improvement
/sc:review codebase/ --focus quality
# → Quality engineer + code smell detection + maintainability analysis
```
**Task Management:**
**`--task-manage`** / **`--delegate`** - Complex Coordination
- **Auto-Triggers**: >3 steps, >2 directories, >3 files
- **Manual Use**: Force hierarchical task organization for simple tasks
```bash
/sc:implement "simple feature" --task-manage
# → Phase-based approach with progress tracking even for simple tasks
```
**`--delegate [auto|files|folders]`** - Orchestration Strategy
- **Auto-Triggers**: >7 directories OR >50 files OR complexity >0.8
- **Manual Use**: Control delegation strategy
```bash
/sc:refactor enterprise-codebase/ --delegate folders
# → Delegate by directory structure for systematic organization
```
### Tool Integration Flags 🛠️
**MCP Server Control:**
**Individual Server Flags:**
- **`--c7`** / **`--context7`**: Documentation and framework patterns
- **`--seq`** / **`--sequential`**: Structured multi-step reasoning
- **`--magic`**: Modern UI component generation
- **`--morph`** / **`--morphllm`**: Pattern-based code transformation
- **`--serena`**: Semantic understanding and project memory
- **`--play`** / **`--playwright`**: Browser automation and testing
```bash
# Specific server combinations
/sc:implement "dashboard" --magic --c7
# → UI generation + framework patterns
/sc:analyze complex-issue/ --seq --serena
# → Structured reasoning + project context
/sc:improve legacy-code/ --morph --serena --seq
# → Pattern transformation + context + systematic analysis
```
**Server Group Control:**
**`--all-mcp`** - Maximum Capability
- **Auto-Triggers**: Maximum complexity scenarios, multi-domain problems
- **Manual Use**: Force all tools for comprehensive capability
```bash
/sc:implement "enterprise-platform" --all-mcp
# → All 6 MCP servers coordinated for maximum capability
```
**`--no-mcp`** - Native-Only Execution
- **Auto-Triggers**: Performance priority, simple tasks
- **Manual Use**: Force lightweight execution without MCP overhead
```bash
/sc:explain "simple function" --no-mcp
# → Fast native response without MCP server coordination
```
**Tool Optimization:**
**`--orchestrate`** - Intelligent Tool Selection
- **Auto-Triggers**: Multi-tool operations, performance constraints, >3 files
- **Manual Use**: Force optimal tool coordination
```bash
/sc:refactor components/ --orchestrate
# → Optimal tool selection and parallel execution coordination
```
### Safety & Validation Flags 🛡️
**Risk Management:**
**`--validate`** - Pre-execution Risk Assessment
- **Auto-Triggers**: Risk score >0.7, resource usage >75%, production environment
- **Manual Use**: Force validation gates for any operation
```bash
/sc:implement "payment-processing" --validate
# → Risk assessment + validation gates before implementation
```
**`--safe-mode`** - Maximum Conservative Execution
- **Auto-Triggers**: Resource usage >85%, production environment, critical operations
- **Manual Use**: Force maximum safety protocols
- **Auto-Enables**: `--uc` for efficiency, `--validate` for safety
```bash
/sc:improve production-database/ --safe-mode
# → Conservative execution + auto-backup + rollback planning
```
**Preview & Testing:**
**`--dry-run`** - Preview Without Execution
- **Manual Use**: Preview changes without applying them
```bash
/sc:cleanup legacy-code/ --dry-run
# → Show what would be cleaned up without making changes
```
**`--backup`** - Force Backup Creation
- **Auto-Triggers**: Risky operations, file modifications
- **Manual Use**: Ensure backup creation before operations
```bash
/sc:refactor critical-module/ --backup
# → Create backup before refactoring operations
```
**`--tests-required`** - Mandate Test Validation
- **Auto-Triggers**: Critical code changes, production modifications
- **Manual Use**: Force test execution before proceeding
```bash
/sc:improve auth-system/ --tests-required
# → Run tests and require passing before improvement application
```
### Execution Control Flags 🎛️
**Workflow Management:**
**`--parallel`** - Force Parallel Execution
- **Auto-Triggers**: Independent operations, >3 files, multi-tool scenarios
- **Manual Use**: Force parallel processing for eligible operations
```bash
/sc:analyze multiple-modules/ --parallel
# → Analyze modules concurrently instead of sequentially
```
**`--sequential`** - Force Sequential Execution
- **Manual Use**: Override parallel processing for dependency reasons
```bash
/sc:implement "multi-step-feature" --sequential
# → Force step-by-step execution with dependencies
```
**Resource Control:**
**`--memory-limit [MB]`** - Memory Usage Control
- **Auto-Triggers**: Large operations, resource constraints
- **Manual Use**: Explicit memory management
```bash
/sc:analyze large-dataset/ --memory-limit 2048
# → Limit analysis to 2GB memory usage
```
**`--timeout [seconds]`** - Operation Timeout
- **Auto-Triggers**: Complex operations, MCP server timeouts
- **Manual Use**: Set explicit timeout boundaries
```bash
/sc:troubleshoot "complex-performance-issue" --timeout 300
# → 5-minute timeout for troubleshooting analysis
```
**Output Control:**
**`--format [text|json|html|markdown]`** - Output Format
- **Auto-Triggers**: Analysis export, documentation generation
- **Manual Use**: Specify exact output format
```bash
/sc:analyze api-performance/ --format json --export report.json
# → JSON-formatted analysis results for processing
```
**`--verbose`** / **`--quiet`** - Verbosity Control
- **Manual Use**: Override automatic verbosity decisions
```bash
/sc:build project/ --verbose
# → Detailed build output and progress information
/sc:test suite/ --quiet
# → Minimal output, results only
```
## Common Flag Combinations 🔗
**Development Workflow Patterns:**
**Full Analysis & Improvement:**
```bash
/sc:analyze codebase/ --think-hard --all-mcp --orchestrate
# → Deep analysis + all tools + optimal coordination
```
**Safe Production Changes:**
```bash
/sc:improve production-api/ --safe-mode --validate --backup --tests-required
# → Maximum safety protocols for production modifications
```
**Rapid Prototyping:**
```bash
/sc:implement "quick-feature" --magic --c7 --no-validate
# → Fast UI generation + patterns without safety overhead
```
**Large-Scale Refactoring:**
```bash
/sc:refactor legacy-system/ --task-manage --serena --morph --parallel --backup
# → Systematic coordination + context + transformation + safety
```
**Performance Investigation:**
```bash
/sc:troubleshoot "slow-performance" --think-hard --focus performance --seq --play
# → Deep analysis + performance focus + reasoning + browser testing
```
**Learning & Understanding:**
```bash
/sc:analyze new-codebase/ --introspect --brainstorm --c7 --think
# → Transparent reasoning + discovery + documentation + analysis
```
**Resource-Constrained Environments:**
```bash
/sc:implement "feature" --uc --concurrency 1 --no-mcp --scope file
# → Compressed output + limited resources + lightweight execution
```
**Quality Assurance Workflow:**
```bash
/sc:review code-changes/ --focus quality --validate --tests-required --think
# → Quality analysis + validation + testing + structured reasoning
```
**Documentation Generation:**
```bash
/sc:document api/ --c7 --magic --format markdown --focus accessibility
# → Documentation patterns + UI examples + accessible format
```
**Complex Architecture Design:**
```bash
/sc:design "microservices-platform" --ultrathink --brainstorm --all-mcp --orchestrate
# → Maximum analysis + discovery + all tools + optimal coordination
```
## Flag Reference Quick Cards 📋
### 🧠 Analysis & Thinking Flags
| Flag | Purpose | Auto-Trigger | Token Impact |
|------|---------|--------------|--------------|
| `--think` | Standard analysis | Multi-component tasks | ~4K tokens |
| `--think-hard` | Deep analysis | Architectural tasks | ~10K tokens |
| `--ultrathink` | Maximum analysis | Critical system work | ~32K tokens |
| `--brainstorm` | Interactive discovery | Vague requirements | Variable |
| `--introspect` | Reasoning transparency | Learning contexts | +10% detail |
### ⚡ Efficiency & Performance Flags
| Flag | Purpose | Auto-Trigger | Performance Impact |
|------|---------|--------------|-------------------|
| `--uc` | Token compression | >75% context usage | 30-50% reduction |
| `--token-efficient` | Moderate compression | Resource pressure | 15-30% reduction |
| `--concurrency N` | Parallel control | Multi-file ops | +45% speed |
| `--orchestrate` | Tool optimization | Complex coordination | +30% efficiency |
| `--scope [level]` | Boundary control | Analysis scope | Focused execution |
### 🛠️ Tool Integration Flags
| Flag | MCP Server | Auto-Trigger | Best For |
|------|------------|--------------|----------|
| `--c7` / `--context7` | Context7 | Library imports | Documentation, patterns |
| `--seq` / `--sequential` | Sequential | Complex debugging | Systematic reasoning |
| `--magic` | Magic | UI requests | Component generation |
| `--morph` / `--morphllm` | Morphllm | Multi-file edits | Pattern transformation |
| `--serena` | Serena | Symbol operations | Project memory |
| `--play` / `--playwright` | Playwright | Browser testing | E2E automation |
| `--all-mcp` | All servers | Max complexity | Comprehensive capability |
| `--no-mcp` | None | Simple tasks | Lightweight execution |
### 🎯 Focus & Specialization Flags
| Flag | Domain | Expert Activation | Use Case |
|------|--------|------------------|----------|
| `--focus security` | Security | Security engineer | Vulnerability analysis |
| `--focus performance` | Performance | Performance engineer | Optimization |
| `--focus quality` | Quality | Quality engineer | Code review |
| `--focus architecture` | Architecture | System architect | Design analysis |
| `--focus accessibility` | Accessibility | UX specialist | Compliance validation |
| `--focus testing` | Testing | QA specialist | Test strategy |
### 🛡️ Safety & Control Flags
| Flag | Purpose | Auto-Trigger | Safety Level |
|------|---------|--------------|--------------|
| `--safe-mode` | Maximum safety | Production ops | Maximum |
| `--validate` | Risk assessment | High-risk ops | High |
| `--backup` | Force backup | File modifications | Standard |
| `--dry-run` | Preview only | Manual testing | Preview |
| `--tests-required` | Mandate testing | Critical changes | Validation |
### 📋 Workflow & Task Flags
| Flag | Purpose | Auto-Trigger | Coordination |
|------|---------|--------------|--------------|
| `--task-manage` | Hierarchical organization | >3 steps | Phase-based |
| `--delegate [mode]` | Sub-task routing | >50 files | Intelligent routing |
| `--loop` | Iterative cycles | "improve" keywords | Quality cycles |
| `--iterations N` | Cycle count | Specific improvements | Controlled iteration |
| `--parallel` | Force concurrency | Independent ops | Performance |
## Advanced Flag Usage 🚀
### Context-Aware Flag Selection
**Adaptive Flagging Based on Project Type:**
**React/Frontend Projects:**
```bash
# Automatically optimized for React development
/sc:implement "user-dashboard"
# → Auto-flags: --magic --c7 --focus accessibility --orchestrate
# Manual optimization for specific needs
/sc:implement "dashboard" --magic --c7 --play --focus accessibility
# → UI generation + patterns + testing + accessibility validation
```
**Backend/API Projects:**
```bash
# Automatically optimized for backend development
/sc:implement "payment-api"
# → Auto-flags: --focus security --validate --c7 --seq
# Manual security-first approach
/sc:implement "api" --focus security --validate --backup --tests-required
# → Security analysis + validation + safety protocols
```
**Legacy Modernization:**
```bash
# Complex legacy work gets automatic coordination
/sc:improve legacy-monolith/
# → Auto-flags: --task-manage --serena --morph --think-hard --backup
# Manual control for specific modernization strategy
/sc:improve legacy/ --ultrathink --task-manage --serena --morph --safe-mode
# → Maximum analysis + coordination + transformation + safety
```
### Flag Precedence & Conflict Resolution
**Priority Hierarchy:**
1. **Safety First**: `--safe-mode` > `--validate` > optimization flags
2. **Explicit Override**: User flags > auto-detection
3. **Depth Hierarchy**: `--ultrathink` > `--think-hard` > `--think`
4. **MCP Control**: `--no-mcp` overrides all individual MCP flags
5. **Scope Precedence**: `system` > `project` > `module` > `file`
**Conflict Resolution Examples:**
```bash
# Safety overrides efficiency
/sc:implement "critical-feature" --uc --safe-mode
# → Result: Safe mode wins, auto-enables backup and validation
# Explicit scope overrides auto-detection
/sc:analyze large-project/ --scope file target.js
# → Result: Only analyzes target.js despite project size
# No-MCP overrides individual server flags
/sc:implement "feature" --magic --c7 --no-mcp
# → Result: No MCP servers used, native execution only
```
### Dynamic Flag Adaptation
**Resource-Responsive Flagging:**
```bash
# System automatically adapts based on available resources
/sc:analyze enterprise-codebase/
# → High resources: --all-mcp --parallel --think-hard
# → Medium resources: --c7 --seq --serena --think
# → Low resources: --no-mcp --uc --scope module
```
**Complexity-Driven Selection:**
```bash
# Flags scale with detected complexity
/sc:implement "simple helper function"
# → Auto-flags: minimal, fast execution
/sc:implement "microservices authentication"
# → Auto-flags: --ultrathink --all-mcp --task-manage --validate --orchestrate
```
### Expert Flag Patterns
**Security-First Development:**
```bash
# Progressive security validation
/sc:implement "auth-system" --focus security --validate --tests-required
/sc:review "payment-code" --focus security --think-hard --backup
/sc:analyze "user-data" --focus security --all-mcp --safe-mode
```
**Performance Optimization Workflow:**
```bash
# Systematic performance improvement
/sc:analyze --focus performance --think-hard --seq --play
/sc:improve --focus performance --morph --parallel --validate
/sc:test --focus performance --play --format json --export metrics.json
```
**Learning & Discovery Patterns:**
```bash
# Understanding complex systems
/sc:load new-codebase/ --introspect --brainstorm --serena
/sc:analyze architecture/ --introspect --think-hard --c7 --all-mcp
/sc:explain concepts/ --introspect --c7 --focus accessibility
```
## Flag Troubleshooting 🔧
### Common Issues & Solutions
**Flag Not Recognized:**
```bash
# Problem: Unknown flag error
/sc:analyze code/ --unknown-flag
# Solution: Check flag spelling and availability
SuperClaude --help flags
/sc:help --flags
```
**Conflicting Flags:**
```bash
# Problem: Contradictory flags
/sc:implement "feature" --all-mcp --no-mcp
# Solution: Use flag priority rules
# --no-mcp overrides --all-mcp (explicit override wins)
# Use: /sc:implement "feature" --no-mcp
```
**Resource Issues:**
```bash
# Problem: System overload with --all-mcp --ultrathink
/sc:analyze large-project/ --all-mcp --ultrathink
# Solution: Reduce resource usage
/sc:analyze large-project/ --c7 --seq --think --concurrency 2
# Or let auto-detection handle it: /sc:analyze large-project/
```
**MCP Server Connection Problems:**
```bash
# Problem: MCP flags not working
/sc:implement "dashboard" --magic # Magic server not responding
# Solutions:
# 1. Check MCP installation
SuperClaude install --list-components | grep mcp
# 2. Restart Claude Code session (MCP connections refresh)
# 3. Use fallback approach
/sc:implement "dashboard" --no-mcp # Native execution
# 4. Reinstall MCP servers
SuperClaude install --components mcp --force
```
**Performance Problems:**
```bash
# Problem: Slow execution with complex flags
/sc:analyze codebase/ --ultrathink --all-mcp --parallel
# Solutions:
# 1. Reduce complexity
/sc:analyze codebase/ --think --c7 --seq
# 2. Use scope limiting
/sc:analyze codebase/ --scope module --focus quality
# 3. Enable efficiency mode
/sc:analyze codebase/ --uc --concurrency 1
```
### Flag Debugging
**Check Auto-Activated Flags:**
```bash
# Add --verbose to see which flags were auto-activated
/sc:analyze project/ --verbose
# → Output shows: "Auto-activated: --think-hard, --serena, --orchestrate"
```
**Test Flag Combinations:**
```bash
# Use --dry-run to test flag effects without execution
/sc:improve code/ --task-manage --morph --dry-run
# → Shows planned execution without making changes
```
**Validate Flag Usage:**
```bash
# Check flag compatibility
SuperClaude validate-flags --think-hard --no-mcp --magic
# → Reports conflicts and suggests corrections
```
### Best Practices for Flag Usage
**Start Simple:**
1. **Trust Auto-Detection**: Let SuperClaude choose flags automatically
2. **Add Specific Flags**: Override only when you need specific behavior
3. **Use Common Patterns**: Start with proven flag combinations
4. **Monitor Performance**: Watch for resource usage and adjust accordingly
**Progressive Enhancement:**
```bash
# Week 1: Use commands without flags
/sc:analyze src/
/sc:implement "feature"
# Week 2: Add specific focus
/sc:analyze src/ --focus security
/sc:implement "feature" --magic
# Week 3: Combine for workflows
/sc:analyze src/ --focus security --think-hard
/sc:implement "feature" --magic --c7 --validate
# Month 2+: Advanced patterns
/sc:improve legacy/ --task-manage --serena --morph --safe-mode
```
**Flag Selection Strategy:**
1. **Purpose-First**: What do you want to achieve?
2. **Context-Aware**: Consider project type and complexity
3. **Resource-Conscious**: Monitor system load and adjust
4. **Safety-Minded**: Use validation flags for important changes
5. **Learning-Oriented**: Add `--introspect` when exploring
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../Getting-Started/quick-start.md) - Experience auto-flagging naturally
- [Commands Reference](commands.md) - Commands automatically select optimal flags
- [Installation Guide](../Getting-Started/installation.md) - Flag system setup
**🌿 Intermediate (Week 2-3)**
- [Behavioral Modes](modes.md) - How flags activate behavioral modes
- [Agents Guide](agents.md) - Flag interaction with specialized agents
- [MCP Servers](mcp-servers.md) - MCP server activation flags
**🌲 Advanced (Month 2+)**
- [Session Management](session-management.md) - Long-term flag patterns
- [Best Practices](../Reference/best-practices.md) - Flag optimization strategies
- [Examples Cookbook](../Reference/examples-cookbook.md) - Real-world flag combinations
**🔧 Expert**
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Flag system implementation
- [Contributing Code](../Developer-Guide/contributing-code.md) - Extending flag capabilities
**Flag-Specific Learning Paths:**
**🎯 Focus Flags Mastery:**
- **Security**: `--focus security` → Security engineer activation
- **Performance**: `--focus performance` → Performance optimization patterns
- **Quality**: `--focus quality` → Code review and improvement workflows
**🧠 Analysis Depth Progression:**
- **Basic**: No flags → automatic detection
- **Structured**: `--think` → systematic analysis
- **Deep**: `--think-hard` → comprehensive investigation
- **Maximum**: `--ultrathink` → complete analytical capability
**🛠️ Tool Integration Journey:**
- **Single Tools**: `--c7`, `--magic` → specific capabilities
- **Combinations**: `--c7 --seq` → coordinated workflows
- **Full Suite**: `--all-mcp` → maximum capability
- **Optimization**: `--orchestrate` → intelligent coordination
**💡 Pro Tips:**
- **Start Without Flags**: Experience automatic optimization first
- **Add One at a Time**: Learn flag effects incrementally
- **Use `--introspect`**: Understand decision-making process
- **Monitor Resources**: Watch system load and adjust accordingly
- **Save Patterns**: Document successful flag combinations for reuse

826
User-Guide/mcp-servers.md Normal file
View File

@ -0,0 +1,826 @@
# SuperClaude MCP Servers Guide 🔌
## 🎯 The Simple Truth About MCP Servers
MCP (Model Context Protocol) servers are specialized tools that extend Claude Code's capabilities beyond native functionality. SuperClaude integrates 6 carefully selected MCP servers that automatically activate based on your tasks, providing enhanced documentation access, advanced reasoning, UI generation, browser automation, code transformation, and project memory.
**Seamless Integration**: Type `/sc:implement "React dashboard"` → Magic MCP activates for UI generation. Type `/sc:analyze --think-hard` → Sequential MCP enables structured reasoning. The system intelligently selects the right tools for your context.
## Overview
**What MCP Servers Do:**
- **Context7**: Official library documentation and framework patterns
- **Sequential**: Multi-step reasoning and hypothesis testing
- **Magic**: Modern UI component generation from 21st.dev patterns
- **Playwright**: Real browser automation and E2E testing
- **Morphllm**: Efficient pattern-based code transformations
- **Serena**: Semantic code understanding with project memory
**How They Enhance SuperClaude:**
- **Automatic Activation**: Intelligent context-based server selection
- **Parallel Coordination**: Multiple servers working together on complex tasks
- **Quality Enhancement**: Specialized tools for specific domains
- **Efficiency Gains**: 30-50% improvement in complex workflows
- **Session Persistence**: Maintain context across development sessions
## Available MCP Servers
### Context7 Server 📚
**Purpose**: Official library documentation and framework pattern access
**Capabilities:**
- Curated documentation lookup for popular libraries
- Version-specific API references and examples
- Framework best practices and implementation patterns
- Up-to-date code examples from official sources
**Auto-Activation Triggers:**
- Library imports: `import`, `require`, `from`, `use`
- Framework keywords: React, Vue, Angular, Next.js, Express
- Documentation requests: "official docs", "API reference"
- Pattern queries: "best practices", "recommended approach"
**Usage Examples:**
```bash
# Automatic activation
/sc:implement "React useEffect for data fetching"
# → Context7 provides official React hooks documentation
# Manual activation
/sc:analyze auth-system/ --c7
# → Access authentication pattern libraries
```
**Best For:**
- Following official framework patterns
- Ensuring API compliance and best practices
- Learning new libraries with authoritative sources
- Version-specific implementation requirements
---
### Sequential Server 🧠
**Purpose**: Structured multi-step reasoning and systematic analysis
**Capabilities:**
- Hypothesis generation and testing workflows
- Complex problem decomposition
- Evidence-based reasoning chains
- Systematic debugging methodologies
**Auto-Activation Triggers:**
- Complex debugging scenarios with multiple layers
- Architectural analysis and system design
- `--think`, `--think-hard`, `--ultrathink` flags
- Multi-component failure investigation
**Usage Examples:**
```bash
# Automatic activation
/sc:troubleshoot "API performance degrading under load"
# → Sequential enables systematic root cause analysis
# Manual activation
/sc:analyze --think-hard microservices-architecture/
# → Deep architectural analysis with structured reasoning
```
**Best For:**
- Root cause analysis of complex issues
- System architecture design and evaluation
- Performance bottleneck identification
- Security vulnerability assessment
---
### Magic Server ✨
**Purpose**: Modern UI component generation from 21st.dev design patterns
**Capabilities:**
- Production-ready React, Vue, Angular components
- Accessibility-compliant UI elements
- Design system integration
- Responsive and interactive components
**Auto-Activation Triggers:**
- UI component requests: button, form, modal, table
- `/ui` or `/21` commands
- Frontend development keywords: responsive, accessible, component
- Design system implementation needs
**Usage Examples:**
```bash
# Automatic activation
/sc:implement "responsive dashboard with data visualization"
# → Magic generates modern UI components with accessibility
# Manual activation
/sc:design "e-commerce checkout flow" --magic
# → UI-focused design with component generation
```
**Best For:**
- Creating production-ready UI components
- Implementing accessible design systems
- Rapid frontend prototyping
- Modern framework component architecture
---
### Playwright Server 🎭
**Purpose**: Real browser automation and comprehensive E2E testing
**Capabilities:**
- Cross-browser testing automation
- Visual regression testing
- Accessibility compliance validation
- User interaction simulation
**Auto-Activation Triggers:**
- Browser testing and E2E scenarios
- Visual testing and screenshot requests
- Accessibility testing requirements
- User workflow validation needs
**Usage Examples:**
```bash
# Automatic activation
/sc:test --type e2e "user registration flow"
# → Playwright automates browser testing
# Manual activation
/sc:validate "form accessibility compliance" --play
# → Browser-based accessibility testing
```
**Best For:**
- End-to-end user workflow testing
- Cross-browser compatibility validation
- Visual regression testing
- Accessibility compliance verification
---
### Morphllm Server 🔄
**Purpose**: Efficient pattern-based code transformations and bulk editing
**Capabilities:**
- Multi-file pattern transformations
- Style guide enforcement across codebases
- Framework migration assistance
- Bulk code modernization
**Auto-Activation Triggers:**
- Multi-file edit operations
- Framework updates and migrations
- Code cleanup and standardization
- Pattern-based refactoring tasks
**Usage Examples:**
```bash
# Automatic activation
/sc:improve legacy-codebase/ --focus maintainability
# → Morphllm applies consistent patterns across files
# Manual activation
/sc:cleanup src/ --morph
# → Pattern-based code organization
```
**Best For:**
- Large-scale refactoring projects
- Code style standardization
- Framework migration projects
- Bulk code transformations
---
### Serena Server 🧭
**Purpose**: Semantic code understanding with persistent project memory
**Capabilities:**
- Symbol-level code navigation and analysis
- Cross-session project memory
- Semantic code transformations
- Large codebase architecture understanding
**Auto-Activation Triggers:**
- Symbol operations: rename, extract, move functions
- Project-wide code navigation
- Session management: `/sc:load`, `/sc:save`
- Large codebase analysis requirements
**Usage Examples:**
```bash
# Automatic activation
/sc:load existing-project/
# → Serena builds project understanding and memory
# Manual activation
/sc:refactor "extract UserService class" --serena
# → Semantic-aware code restructuring
```
**Best For:**
- Long-term project development
- Complex codebase navigation
- Semantic code refactoring
- Cross-session context preservation
## Installation & Configuration
### Automatic Installation (Recommended)
**During SuperClaude Setup:**
```bash
SuperClaude install
# → Interactive installer offers MCP server selection
# → Automatically configures selected servers
# → Creates .claude.json with server configurations
```
**Installation Options:**
- **All Servers**: Complete MCP capability (recommended for full features)
- **Essential Only**: Context7 + Sequential (minimal but powerful)
- **Custom Selection**: Choose specific servers for your workflow
- **Skip MCP**: Native-only installation for resource constraints
### Manual Configuration
**Server-Specific Installation:**
```bash
# Install specific MCP components
SuperClaude install --components mcp
# Individual server configuration
SuperClaude install --components mcp_context7 mcp_sequential
# Force reinstall with updated configurations
SuperClaude install --components mcp --force
```
**Configuration File (`.claude.json`):**
```json
{
"mcpServers": {
"context7": {
"command": "node",
"args": ["/path/to/context7-server"],
"env": {"NODE_ENV": "production"}
},
"sequential": {
"command": "node",
"args": ["/path/to/sequential-server"]
}
}
}
```
### Prerequisites by Server
**Node.js Required (Most Servers):**
- Context7, Magic, Sequential, Playwright require Node.js 16+
- Install: `brew install node` (macOS) or visit https://nodejs.org
**Python Required:**
- Morphllm, Serena work with Python environment
- Already satisfied by SuperClaude installation
**System Resources:**
- **Minimal**: 2GB RAM for basic MCP functionality
- **Recommended**: 4GB RAM for full MCP suite
- **Storage**: 200MB additional for MCP server installations
## Usage Patterns
### Automatic Server Selection
**Context-Based Activation:**
SuperClaude analyzes your request and automatically selects optimal MCP servers:
```bash
# Frontend development → Magic + Context7
/sc:implement "responsive navigation component"
# Performance investigation → Sequential + Playwright
/sc:troubleshoot "page load time >3 seconds"
# Large refactoring → Serena + Morphllm + Sequential
/sc:improve legacy-authentication-system/
# Documentation lookup → Context7
/sc:explain "React useCallback best practices"
# Browser testing → Playwright + Sequential
/sc:test --type e2e user-checkout-flow/
```
**Intelligence Behind Selection:**
- **Keywords**: "component", "UI" → Magic activation
- **File types**: `.jsx`, `.vue` → Magic + Context7
- **Complexity**: Multi-file operations → Serena + Morphllm
- **Analysis depth**: `--think-hard` → Sequential + Context7
- **Testing scope**: E2E workflows → Playwright + Sequential
### Manual Server Control
**Force Specific Servers:**
```bash
# Enable specific servers
/sc:analyze codebase/ --c7 --seq --serena
# Disable all MCP servers
/sc:implement "simple function" --no-mcp
# Enable all servers for maximum capability
/sc:design "complex system architecture" --all-mcp
# Lightweight execution
/sc:explain "function purpose" --no-mcp
```
**Server Combination Strategies:**
**Documentation + Analysis:**
```bash
/sc:analyze security-patterns/ --c7 --seq
# → Context7 provides security patterns + Sequential analyzes implementation
```
**UI Development:**
```bash
/sc:implement "dashboard interface" --magic --c7 --play
# → Magic generates components + Context7 patterns + Playwright testing
```
**Code Transformation:**
```bash
/sc:improve legacy-code/ --serena --morph --seq
# → Serena analyzes structure + Morphllm transforms + Sequential validates
```
### Multi-Server Coordination
**Complex Workflow Example:**
```bash
/sc:implement "e-commerce checkout system"
```
**Automatic Coordination:**
1. **Sequential**: Breaks down checkout workflow systematically
2. **Context7**: Provides payment integration patterns
3. **Magic**: Generates checkout UI components
4. **Serena**: Manages code organization and dependencies
5. **Playwright**: Creates E2E testing for checkout flow
**Efficiency Gains:**
- **30-50% faster development** through specialized tools
- **Higher quality output** through domain expertise
- **Reduced context switching** with intelligent automation
- **Comprehensive coverage** across all development aspects
## Advanced Features
### Multi-Server Orchestration
**Intelligent Workflow Coordination:**
SuperClaude orchestrates multiple MCP servers for complex tasks:
**Full-Stack Development Workflow:**
```bash
/sc:implement "real-time chat application"
```
1. **Sequential**: Analyzes requirements and architecture
2. **Context7**: Provides WebSocket and React patterns
3. **Magic**: Generates chat UI components
4. **Serena**: Manages project structure and dependencies
5. **Playwright**: Creates E2E tests for messaging flow
6. **Morphllm**: Applies consistent code patterns
**Performance Optimization Workflow:**
```bash
/sc:analyze --focus performance --ultrathink
```
1. **Sequential**: Systematic performance analysis methodology
2. **Serena**: Code structure and bottleneck identification
3. **Context7**: Framework-specific optimization patterns
4. **Playwright**: Real browser performance testing
5. **Morphllm**: Code optimization pattern application
### Resource Management
**Performance Optimization:**
**Smart Resource Allocation:**
- **Green Zone** (0-75% usage): All servers available
- **Yellow Zone** (75-85%): Priority servers only
- **Red Zone** (85%+): Essential servers, compressed output
**Server Priority Matrix:**
| Priority | Servers | Use Case |
|----------|---------|----------|
| **Essential** | Context7, Sequential | Core functionality |
| **High** | Magic, Serena | Development workflows |
| **Standard** | Playwright, Morphllm | Testing and optimization |
**Concurrency Control:**
```bash
# Limit concurrent server operations
/sc:implement "complex feature" --concurrency 2
# Maximum performance mode
/sc:analyze large-codebase/ --all-mcp --concurrency 6
# Resource-constrained mode
/sc:troubleshoot issue/ --c7 --seq --concurrency 1
```
### Advanced Configuration
**Custom Server Configurations:**
```json
{
"mcpServers": {
"context7": {
"command": "node",
"args": ["/custom/context7-server"],
"env": {
"CONTEXT7_CACHE_SIZE": "1000",
"CONTEXT7_TIMEOUT": "30000"
}
},
"sequential": {
"command": "node",
"args": ["/custom/sequential-server"],
"env": {
"MAX_THINKING_DEPTH": "10",
"REASONING_TIMEOUT": "60000"
}
}
}
}
```
**Performance Tuning:**
- **Context7**: Cache size, request timeout, documentation sources
- **Sequential**: Thinking depth, reasoning timeout, branch limits
- **Magic**: Component complexity, accessibility level, framework targets
- **Playwright**: Browser pool size, timeout values, screenshot quality
- **Morphllm**: Pattern matching precision, transformation scope
- **Serena**: Memory retention, project indexing depth, symbol resolution
### Integration Patterns
**Mode Integration:**
- **Brainstorming Mode**: Sequential for structured discovery
- **Task Management Mode**: Serena for session persistence
- **Orchestration Mode**: All servers for optimal tool selection
- **Token Efficiency Mode**: Selective activation for resource optimization
**Command Integration:**
- **Analysis Commands**: Sequential + Serena for deep understanding
- **Implementation Commands**: Magic + Context7 for development
- **Testing Commands**: Playwright + Sequential for comprehensive validation
- **Documentation Commands**: Context7 + Magic for pattern-rich docs
## Troubleshooting
### Common Issues & Solutions
**MCP Server Not Starting:**
```bash
# Check server configuration
ls ~/.claude/.claude.json
# Verify server installation
SuperClaude install --list-components
# Reinstall MCP configuration
SuperClaude install --components mcp --force
# Test specific server
SuperClaude test-mcp context7
```
**Node.js Dependency Issues:**
```bash
# Verify Node.js version (16+ required)
node --version
# Install missing dependencies
npm install -g @anthropic/context7-server
npm install -g @anthropic/sequential-server
# Clear Node.js cache
npm cache clean --force
```
**Performance Issues:**
```bash
# Reduce server load
/sc:command --concurrency 1
# Use selective servers
/sc:command --c7 --seq # Instead of --all-mcp
# Check system resources
top | grep node
ps aux | grep mcp
```
**Server Connection Timeouts:**
```bash
# Increase timeout in .claude.json
{
"mcpServers": {
"context7": {
"timeout": 60000 // Increase from default 30000
}
}
}
# Restart Claude Code session
# MCP connections refresh on restart
```
### Diagnostics
**MCP Server Status Check:**
```bash
# Check all server health
SuperClaude status --mcp
# Test individual servers
SuperClaude test-mcp --server context7
SuperClaude test-mcp --server sequential
# Detailed diagnostics
SuperClaude diagnose --verbose
```
**Log Analysis:**
```bash
# View MCP server logs
tail -f ~/.claude/logs/mcp-context7.log
tail -f ~/.claude/logs/mcp-sequential.log
# SuperClaude operation logs
tail -f ~/.claude/logs/superclaude.log
# Claude Code MCP logs
tail -f ~/.claude/logs/claude-mcp.log
```
**Manual Testing:**
```bash
# Test Context7 documentation lookup
echo "Test React hooks documentation" | claude --mcp context7
# Test Sequential reasoning
echo "Analyze this complex problem" | claude --mcp sequential
# Test server combination
echo "Complex analysis task" | claude --mcp context7,sequential
```
### Resolution Steps
**Step 1: Basic Verification**
1. Check SuperClaude installation: `SuperClaude --version`
2. Verify MCP component: `SuperClaude install --list-components`
3. Check Node.js: `node --version` (should be 16+)
4. Restart Claude Code session
**Step 2: Configuration Check**
1. Verify `.claude.json` exists: `ls ~/.claude/.claude.json`
2. Check server paths and permissions
3. Test configuration syntax: `SuperClaude validate-config`
**Step 3: Server Specific**
1. **Context7**: Check documentation server connection
2. **Sequential**: Verify reasoning engine startup
3. **Magic**: Test UI component generation endpoint
4. **Playwright**: Check browser automation setup
5. **Morphllm**: Verify code transformation pipeline
6. **Serena**: Test project memory and indexing
**Step 4: Full Reset (Last Resort)**
```bash
# Backup existing configuration
cp ~/.claude/.claude.json ~/.claude/.claude.json.backup
# Remove and reinstall MCP
SuperClaude uninstall --components mcp
SuperClaude install --components mcp
# Restore custom settings if needed
```
## Developer Integration
### MCP Server Development
**Creating Custom MCP Servers:**
**Server Structure:**
```javascript
// custom-mcp-server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
const server = new Server(
{
name: "custom-server",
version: "1.0.0"
},
{
capabilities: {
resources: {},
tools: {},
prompts: {}
}
}
);
// Tool implementation
server.setRequestHandler(
'tools/call',
async (request) => {
// Custom tool logic
return { content: [{ type: "text", text: result }] };
}
);
```
**SuperClaude Integration:**
```python
# setup/components/custom_mcp.py
from setup.components.base import BaseComponent
class CustomMCPComponent(BaseComponent):
def get_metadata(self):
return {
"name": "custom_mcp",
"description": "Custom MCP server integration",
"dependencies": ["core"]
}
def install(self, install_dir):
# Install custom server configuration
self._install_mcp_config(install_dir)
```
### Communication Protocols
**MCP Protocol Flow:**
1. **Initialization**: Claude Code connects to MCP server via JSON-RPC
2. **Capability Exchange**: Server announces available tools and resources
3. **Request/Response**: Claude sends requests, server processes and responds
4. **Session Management**: Maintain context across multiple interactions
**Message Structure:**
```json
{
"jsonrpc": "2.0",
"id": "request-id",
"method": "tools/call",
"params": {
"name": "analyze-code",
"arguments": {
"code": "function example() { return 'hello'; }",
"language": "javascript"
}
}
}
```
**SuperClaude MCP Interface:**
```python
class MCPCoordinator:
def select_servers(self, task_context):
"""Intelligent server selection based on task analysis"""
servers = []
if self._needs_documentation(task_context):
servers.append("context7")
if self._needs_reasoning(task_context):
servers.append("sequential")
if self._needs_ui_generation(task_context):
servers.append("magic")
return servers
def coordinate_request(self, servers, request):
"""Orchestrate multi-server workflows"""
results = []
for server in servers:
result = await self._send_request(server, request)
results.append(result)
return self._synthesize_results(results)
```
### Integration APIs
**Configuration API:**
```python
# Register custom MCP server
from setup.services.config_service import ConfigService
config_service = ConfigService()
config_service.add_mcp_server({
"name": "custom-server",
"command": "node",
"args": ["/path/to/custom-server.js"],
"env": {"CUSTOM_CONFIG": "value"}
})
```
**Tool Registration:**
```python
# Register server capabilities with SuperClaude
from setup.core.mcp_registry import MCPRegistry
registry = MCPRegistry()
registry.register_server("custom-server", {
"capabilities": ["code-analysis", "documentation"],
"triggers": ["custom", "analyze", "special-keyword"],
"priority": "standard"
})
```
**Integration Testing:**
```python
# Test custom MCP server integration
from setup.testing.mcp_test import MCPTestSuite
test_suite = MCPTestSuite()
test_suite.test_server_connection("custom-server")
test_suite.test_tool_functionality("custom-server", "analyze-code")
test_suite.test_integration_workflow(["custom-server", "sequential"])
```
---
## MCP Server Quick Reference 📋
| Server | Purpose | Auto-Triggers | Manual Flags | Best For |
|--------|---------|---------------|--------------|----------|
| **Context7** | Documentation | Library imports, API questions | `--c7`, `--context7` | Official patterns, framework docs |
| **Sequential** | Reasoning | Complex debugging, analysis | `--seq`, `--sequential` | Systematic thinking, root cause |
| **Magic** | UI Generation | Component requests, frontend | `--magic` | Modern UI, accessibility |
| **Playwright** | Browser Testing | E2E testing, visual validation | `--play`, `--playwright` | User workflows, cross-browser |
| **Morphllm** | Code Transform | Multi-file edits, refactoring | `--morph`, `--morphllm` | Pattern application, bulk changes |
| **Serena** | Project Memory | Symbol operations, large codebases | `--serena` | Session persistence, navigation |
**Server Combinations:**
- **Full-Stack Development**: Magic + Context7 + Serena
- **Quality Analysis**: Sequential + Playwright + Serena
- **Large Refactoring**: Serena + Morphllm + Sequential
- **Learning/Documentation**: Context7 + Sequential + Magic
**Performance Control:**
- `--all-mcp`: Enable all servers (max capability)
- `--no-mcp`: Disable all servers (lightweight)
- `--concurrency N`: Control parallel operations
- Resource awareness: Auto-scaling based on system load
---
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../Getting-Started/quick-start.md) - Experience MCP servers naturally
- [Installation Guide](../Getting-Started/installation.md) - MCP server setup
- [Commands Reference](commands.md) - Commands that activate MCP servers
**🌿 Intermediate (Week 2-3)**
- [Behavioral Modes](modes.md) - How modes coordinate MCP servers
- [Agents Guide](agents.md) - Agent-MCP server integration
- [Examples Cookbook](../Reference/examples-cookbook.md) - MCP workflow patterns
**🌲 Advanced (Month 2+)**
- [Session Management](session-management.md) - Serena MCP workflows
- [Best Practices](../Reference/best-practices.md) - MCP optimization strategies
- [Flags Guide](flags.md) - Advanced MCP control
**🔧 Expert**
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - MCP integration details
- [Contributing Code](../Developer-Guide/contributing-code.md) - Custom MCP development
- [Testing & Debugging](../Developer-Guide/testing-debugging.md) - MCP troubleshooting
**MCP-Specific Resources:**
- **Official MCP Documentation**: https://modelcontextprotocol.io/
- **Context7 Server**: Enhanced documentation lookup capabilities
- **Sequential Thinking**: Advanced reasoning and analysis
- **Magic UI**: Modern component generation from 21st.dev
- **Community MCP Servers**: https://github.com/modelcontextprotocol/servers

696
User-Guide/modes.md Normal file
View File

@ -0,0 +1,696 @@
# SuperClaude Behavioral Modes Guide 🧠
## 💡 The Simple Truth About Modes
SuperClaude employs 6 behavioral modes that automatically adapt Claude Code's communication style, tool selection, and workflow approach based on task context and complexity. Modes work seamlessly in the background - you don't need to think about them.
**Automatic Intelligence**: Type `/sc:brainstorm "mobile app"` → Brainstorming mode activates with Socratic questions. Type `/sc:analyze src/` → Introspection mode provides transparent reasoning. Type complex multi-file operations → Task Management coordinates execution phases.
**Behind the Scenes**: Modes enhance your experience by optimizing communication patterns, resource usage, and workflow orchestration based on what you're trying to accomplish.
---
## 🚀 Just Try These (See Modes in Action)
**Automatic Mode Examples:**
```bash
# Brainstorming mode activates automatically
/sc:brainstorm "fitness tracking app"
# → Socratic questions about users, features, goals
# Introspection mode shows reasoning
/sc:analyze --focus security
# → Transparent thinking: "🤔 Why security first? 🎯 Risk assessment shows..."
# Task Management coordinates complex work
/sc:implement "user authentication with email verification"
# → Phases: analysis → design → implementation → testing
# Orchestration optimizes tool selection
/sc:improve src/ --focus performance
# → Magic + Morphllm + Sequential coordination
# Token Efficiency compresses output
"--uc implement auth API"
# → "auth.js:45 → 🔧 JWT middleware ⇒ validated_user"
```
**Mode Detection Logic:**
- **Keywords**: "brainstorm", "maybe" → Brainstorming
- **Complexity**: >3 files → Task Management
- **Performance**: Resource pressure → Token Efficiency
- **Multi-tool**: Complex analysis → Orchestration
- **Error recovery**: Problems → Introspection
---
## The Six Behavioral Modes 🌟
### 🧠 Brainstorming Mode - Interactive Discovery
**Purpose**: Collaborative requirements exploration through Socratic dialogue
**Auto-Activation Triggers:**
- Vague requests: "I want to build...", "Thinking about creating..."
- Exploration keywords: brainstorm, explore, discuss, figure out, not sure
- Uncertainty: "maybe", "possibly", "could we"
- Manual flags: `--brainstorm`, `--bs`
**What Changes:**
- **Socratic Questions**: Probing questions to uncover hidden requirements
- **Non-Presumptive**: Avoid assumptions, let you guide discovery
- **Collaborative**: Partner in exploration rather than directive consultation
- **Brief Generation**: Synthesize insights into structured requirements
**Example Experience:**
```
You: "I want to build a web app"
Brainstorming: "🤔 Discovery Questions:
- What problem does this solve for users?
- Who are your target users and workflows?
- Expected user volume and performance needs?
- Any existing systems to integrate with?"
```
---
### 🔍 Introspection Mode - Meta-Cognitive Analysis
**Purpose**: Transparent reasoning and self-analysis for learning optimization
**Auto-Activation Triggers:**
- Self-analysis requests: "analyze my reasoning", "reflect on decision"
- Error recovery: unexpected results or outcomes
- Complex problem solving requiring meta-cognition
- Manual flag: `--introspect`
**What Changes:**
- **Transparency**: Expose thinking with markers (🤔, 🎯, ⚡, 📊, 💡)
- **Pattern Detection**: Identify recurring behaviors and optimizations
- **Self-Examination**: Analyze decision logic and reasoning chains
- **Learning Focus**: Extract insights for continuous improvement
**Example Experience:**
```
Standard: "I'll analyze this code structure"
Introspective: "🧠 Reasoning: Why structural over functional analysis?
🔄 Alternative: Could start with data flow patterns
💡 Learning: Structure-first works for OOP, not functional"
```
---
### 📋 Task Management Mode - Orchestration & Delegation
**Purpose**: Hierarchical organization with persistent memory for complex multi-step operations
**Auto-Activation Triggers:**
- Operations >3 steps requiring coordination
- Multiple file/directory scope (>2 directories OR >3 files)
- Complex dependencies requiring phases
- Manual flags: `--task-manage`, `--delegate`
**What Changes:**
- **Memory Integration**: Session persistence and context preservation
- **Phase Coordination**: Break complex work into manageable phases
- **Progress Tracking**: TodoWrite + memory updates for state management
- **Quality Gates**: Systematic validation at each phase
**Task Hierarchy:**
```
📋 Plan → 🎯 Phase → 📦 Task → ✓ Todo
```
**Example Experience:**
```
/sc:implement "payment system"
→ Phase 1: Security analysis
→ Phase 2: API design
→ Phase 3: Implementation
→ Phase 4: Testing & validation
→ Session persistence across interruptions
```
---
### 🎯 Orchestration Mode - Intelligent Tool Selection
**Purpose**: Optimal task routing and resource efficiency through smart tool coordination
**Auto-Activation Triggers:**
- Multi-tool operations requiring coordination
- Performance constraints (>75% resource usage)
- Parallel execution opportunities (>3 files)
- Complex routing decisions
**What Changes:**
- **Smart Tool Selection**: Choose optimal tool for each task type
- **Resource Awareness**: Adapt approach based on system constraints
- **Parallel Thinking**: Identify independent operations for concurrency
- **Efficiency Focus**: Optimize tool usage for speed and effectiveness
**Tool Selection Matrix:**
- UI components → Magic MCP > Manual coding
- Deep analysis → Sequential MCP > Native reasoning
- Pattern edits → Morphllm MCP > Individual edits
- Documentation → Context7 MCP > Web search
**Example Experience:**
```
Complex multi-file refactoring:
→ Serena: Symbol analysis
→ Sequential: Strategy planning
→ Morphllm: Pattern application
→ Parallel execution coordination
```
---
### ⚡ Token Efficiency Mode - Compressed Communication
**Purpose**: Symbol-enhanced communication for 30-50% token reduction while preserving clarity
**Auto-Activation Triggers:**
- Context usage >75% or resource constraints
- Large-scale operations requiring efficiency
- User flags: `--uc`, `--ultracompressed`
- Complex analysis workflows
**What Changes:**
- **Symbol Communication**: Visual symbols for logic, status, domains
- **Abbreviation Systems**: Context-aware compression for technical terms
- **Structured Output**: Bullet points, tables over verbose paragraphs
- **Information Density**: Maximum clarity per token
**Symbol Examples:**
```
Standard: "The authentication system has a security vulnerability"
Compressed: "auth.js:45 → 🛡️ sec risk in user val()"
Standard: "Build completed, now testing, then deploying"
Compressed: "build ✅ » test 🔄 » deploy ⏳"
```
---
### 🎨 Standard Mode - Balanced Default
**Purpose**: Balanced communication for general-purpose development tasks
**Default Behavior:**
- Clear, professional communication
- Moderate detail level
- Standard tool selection
- Quality-focused workflows
**When Active:**
- Simple, straightforward tasks
- No complexity triggers detected
- User preference for standard behavior
- Balanced resource usage scenarios
---
### 🔍 Introspection Mode - Meta-Cognitive Analysis
**Purpose**: Meta-cognitive analysis and reasoning transparency for complex problem solving and decision optimization.
**Auto-Activation Triggers:**
- Self-analysis requests: "analyze my reasoning", "reflect on decision"
- Error recovery scenarios and unexpected results
- Complex problem solving requiring multi-step reasoning
- Pattern recognition needs and optimization opportunities
- Manual flag: `--introspect`
**Capabilities:**
- **Reasoning Transparency**: Expose thinking process with clear markers (🤔, 🎯, ⚡, 📊, 💡)
- **Decision Analysis**: Evaluate choice logic and alternative approaches
- **Pattern Detection**: Identify recurring behaviors and optimization opportunities
- **Learning Optimization**: Extract insights for continuous improvement
**Examples:**
```bash
# Decision analysis after unexpected results
"The API optimization didn't improve performance as expected"
# 🤔 Decision Analysis: Why did I choose caching over database optimization?
# 📊 Evidence Review: Database queries actually the bottleneck
# 💡 Learning: Profile first, then optimize based on data
# Pattern recognition for improvement
"I keep having authentication issues"
# 🎯 Pattern Analysis: Similar auth failures in projects X, Y, Z
# ⚡ Root Cause: Consistent token refresh logic gap
# 📊 Solution Strategy: Centralized auth state management
```
---
### 📋 Task Management Mode - Orchestration & Delegation
**Purpose**: Hierarchical task organization with intelligent delegation for complex multi-step operations.
**Auto-Activation Triggers:**
- Operations with >3 steps requiring coordination
- Multiple file/directory scope (>2 directories OR >3 files)
- Complex dependencies requiring phases
- Manual flags: `--task-manage`, `--delegate`
**Capabilities:**
- **Phase Management**: Break complex tasks into manageable phases with dependencies
- **Intelligent Delegation**: Route subtasks to appropriate specialist agents
- **Progress Tracking**: Monitor completion across multiple parallel operations
- **Quality Gates**: Validation checkpoints between phases
**Examples:**
```bash
# E-commerce platform development (auto-delegates to multiple agents)
/sc:implement "complete e-commerce platform with payment integration"
# Phase 1: Architecture → system-architect
# Phase 2: Backend APIs → backend-architect + security-engineer
# Phase 3: Frontend UI → frontend-architect + quality-engineer
# Phase 4: Payment Integration → security-engineer + backend-architect
# Phase 5: Testing & Deployment → devops-architect + quality-engineer
# Large codebase refactoring (delegates by file type and complexity)
/sc:improve legacy-codebase/ --comprehensive
# Delegation: Python files → python-expert + refactoring-expert
# Delegation: React components → frontend-architect + refactoring-expert
# Delegation: API endpoints → backend-architect + security-engineer
```
---
### 🎯 Orchestration Mode - Intelligent Tool Selection
**Purpose**: Intelligent tool selection and resource optimization for maximum efficiency and parallel execution.
**Auto-Activation Triggers:**
- Multi-tool operations requiring coordination
- Performance constraints (>75% resource usage)
- Parallel execution opportunities (>3 independent operations)
- Complex routing decisions with multiple valid approaches
**Capabilities:**
- **Smart Tool Selection**: Choose optimal tools for each task type (MCP servers, native tools)
- **Resource Awareness**: Adapt approach based on system constraints and availability
- **Parallel Optimization**: Identify and execute independent operations concurrently
- **Efficiency Focus**: Maximize speed and effectiveness through intelligent coordination
**Tool Selection Matrix:**
| Task Type | Optimal Tool | Fallback | Parallel Opportunity |
|-----------|-------------|----------|---------------------|
| UI Components | Magic MCP | Native coding | ✅ Multiple components |
| Code Analysis | Sequential MCP | Native reasoning | ✅ Multiple files |
| Documentation | Context7 MCP | Web search | ✅ Multiple topics |
| Multi-file edits | MultiEdit | Sequential edits | ❌ Dependencies exist |
**Resource Management Zones:**
- **🟢 Green (0-75%)**: Full capabilities, all tools available
- **🟡 Yellow (75-85%)**: Efficiency mode, reduced verbosity
- **🔴 Red (85%+)**: Essential operations only, minimal output
---
### ⚡ Token Efficiency Mode - Compressed Communication
**Purpose**: Symbol-enhanced communication achieving 30-50% token reduction while preserving information quality.
**Auto-Activation Triggers:**
- Context usage >75% or resource constraints
- Large-scale operations requiring efficiency
- User requests brevity: `--uc`, `--ultracompressed`
- Complex analysis workflows needing optimization
**Symbol Systems:**
**Core Logic**: → (leads to), ⇒ (transforms), ← (rollback), ⇄ (bidirectional)
**Status**: ✅ (completed), ❌ (failed), ⚠️ (warning), 🔄 (in progress)
**Technical**: ⚡ (performance), 🔍 (analysis), 🔧 (config), 🛡️ (security)
**Abbreviation Systems:**
- **System**: `cfg` config, `impl` implementation, `arch` architecture, `perf` performance
- **Process**: `req` requirements, `deps` dependencies, `val` validation, `test` testing
- **Quality**: `qual` quality, `sec` security, `err` error, `opt` optimization
**Examples (30-50% compression):**
```
Standard: "The authentication system has a security vulnerability in the user validation function"
Compressed: "auth.js:45 → 🛡️ sec risk in user val()"
Standard: "Performance analysis shows the algorithm is slow because of O(n²) complexity"
Compressed: "⚡ perf analysis: slow ∵ O(n²) complexity"
Standard: "Build process completed successfully, now running tests, then deploying"
Compressed: "build ✅ » test 🔄 » deploy ⏳"
```
---
## How Modes Work Together 🤝
**Mode Coordination Patterns:**
**Discovery → Implementation Workflow:**
```bash
# Brainstorming discovers requirements
/sc:brainstorm "e-commerce platform"
→ Requirements brief generated
# Task Management coordinates implementation
/sc:implement "payment integration"
→ Phase 1: Architecture (Orchestration mode for tool selection)
→ Phase 2: Implementation (Token Efficiency if complex)
→ Phase 3: Testing (Introspection for quality analysis)
```
**Multi-Mode Complex Scenarios:**
**Large Codebase Refactoring:**
1. **Brainstorming**: Explore improvement goals and priorities
2. **Introspection**: Analyze current code patterns and issues
3. **Task Management**: Coordinate multi-phase refactoring plan
4. **Orchestration**: Select optimal tools (Morphllm + Sequential + Serena)
5. **Token Efficiency**: Compress communication during execution
**Performance Optimization:**
1. **Task Management**: Break into analysis → optimization → validation phases
2. **Orchestration**: Coordinate Sequential (analysis) + Magic (UI fixes) + Playwright (testing)
3. **Introspection**: Transparent reasoning about bottleneck identification
4. **Token Efficiency**: Compress performance metrics and results
**Mode Priority System:**
- **Safety First**: Introspection overrides efficiency when quality matters
- **Context Adaptation**: Modes layer based on complexity and scope
- **Resource Management**: Token Efficiency activates under pressure
- **User Intent**: Manual flags override automatic detection
---
## Manual Control 🎛️
**Force Specific Modes:**
**Mode Activation Flags:**
```bash
# Force brainstorming for requirement exploration
/sc:implement "user auth" --brainstorm
# Enable introspection for learning/debugging
/sc:analyze src/ --introspect
# Activate task management for complex coordination
/sc:improve legacy-code/ --task-manage
# Enable orchestration for optimal tool selection
/sc:refactor components/ --orchestrate
# Force token efficiency for compressed output
/sc:analyze large-project/ --uc
```
**When to Use Manual Control:**
**Override Automatic Detection:**
- Simple task needs structured approach → `--task-manage`
- Want transparent reasoning → `--introspect`
- Need compressed output → `--uc`
- Force collaborative discovery → `--brainstorm`
**Learning and Development:**
- Study reasoning patterns → `--introspect`
- Practice requirement discovery → `--brainstorm`
- Understand tool coordination → `--orchestrate`
- Optimize token usage → `--token-efficient`
**Resource Management:**
- High memory pressure → `--uc`
- Complex multi-tool scenarios → `--orchestrate`
- Large scope coordination → `--task-manage`
**Mode Combination:**
```bash
# Multiple modes for complex scenarios
/sc:implement "microservices architecture" --brainstorm --task-manage --orchestrate
# Analysis with reasoning transparency
/sc:analyze security-audit/ --introspect --uc
```
---
## Real-World Scenarios 🌍
**Scenario 1: New Project Startup**
```bash
# Phase 1: Discovery (Brainstorming Mode)
/sc:brainstorm "task management mobile app"
```
*Experience*: Socratic questions about users, features, platform choice, backend needs
*Outcome*: Structured requirements brief with technical specifications
```bash
# Phase 2: Planning (Task Management Mode)
/sc:workflow "implement core task features"
```
*Experience*: Multi-phase breakdown with dependencies and time estimates
*Outcome*: Systematic implementation plan with quality gates
```bash
# Phase 3: Implementation (Orchestration Mode)
/sc:implement "user authentication with social login"
```
*Experience*: Magic (UI) + Context7 (auth patterns) + Security specialist coordination
*Outcome*: Complete auth system with tests and documentation
---
**Scenario 2: Authentication Debugging**
```bash
# Step 1: Problem Analysis (Introspection Mode)
/sc:troubleshoot "users getting 401 errors intermittently"
```
*Experience*:
```
🤔 Reasoning: Why intermittent? Session timing vs token expiry
🔍 Investigation: Check auth middleware, session storage, token validation
🎯 Hypothesis: Race condition in token refresh
📊 Evidence: Log patterns show timing correlation
💡 Solution: Implement token refresh queue
```
```bash
# Step 2: Systematic Fix (Task Management Mode)
/sc:implement "token refresh queue with retry logic"
```
*Experience*: Phase coordination across middleware, frontend, and testing
*Outcome*: Robust authentication flow with comprehensive error handling
---
**Scenario 3: Large Codebase Refactoring**
```bash
# Phase 1: Assessment (Token Efficiency + Introspection)
/sc:analyze legacy-codebase/ --focus maintainability --uc
```
*Experience*:
```
🔍 Analysis:
auth.js:142 → 🛡️ sec vuln (hardcoded keys)
ui-comp/ → 🎨 inconsistent patterns
api/ → ⚡ perf bottlenecks (N+1 queries)
📊 Debt: 847 lines need refactoring
💡 Priority: sec → perf → patterns
```
```bash
# Phase 2: Planning (Task Management + Orchestration)
/sc:improve legacy-codebase/ --task-manage --orchestrate
```
*Experience*: Multi-phase plan with Morphllm (patterns) + Sequential (analysis) + Serena (context)
*Outcome*: Systematic refactoring with progress tracking and rollback safety
```bash
# Phase 3: Quality Validation (Introspection)
/sc:reflect "refactoring impact assessment"
```
*Experience*: Transparent analysis of improvements, remaining debt, and success metrics
*Outcome*: Evidence-based completion assessment with next steps
---
**Scenario 4: Performance Optimization**
```bash
# Discovery (Brainstorming Mode for unclear performance issues)
/sc:brainstorm "app feels slow but unclear where"
```
*Experience*: Questions about user workflows, data volumes, environment differences
*Outcome*: Focused performance investigation scope
```bash
# Systematic Analysis (Task Management + Token Efficiency)
/sc:analyze --focus performance --task-manage --uc
```
*Experience*:
```
Phase 1: Frontend metrics → ⚡ bundle size 2.4MB
Phase 2: API latency → 📊 db queries avg 1.2s
Phase 3: Infrastructure → 🔧 memory usage 85%
Priority: db opt → bundle split → memory tuning
```
```bash
# Coordinated Fixes (Orchestration Mode)
/sc:improve --focus performance --orchestrate
```
*Experience*: Sequential (analysis) + Morphllm (code patterns) + Context7 (optimization patterns)
*Outcome*: 60% performance improvement with systematic validation
---
## FAQ 🙋
**Q: How do I know which mode is active?**
A: Modes work transparently, but you can identify them by communication patterns:
- 🤔 Questions and discovery → Brainstorming
- 🧠 🎯 Reasoning markers → Introspection
- Phase breakdowns → Task Management
- Tool coordination mentions → Orchestration
- Symbol-compressed output → Token Efficiency
**Q: Can I disable modes?**
A: Modes enhance rather than restrict. For minimal behavior, avoid complexity triggers:
- Simple, single-task requests
- Specific file operations
- Clear, unambiguous instructions
**Q: Do modes affect performance?**
A: Modes optimize performance:
- **Token Efficiency**: 30-50% reduction in context usage
- **Orchestration**: Parallel processing and optimal tool selection
- **Task Management**: Systematic execution prevents rework
**Q: Can modes conflict with each other?**
A: Modes are designed to work together:
- **Hierarchical**: Task Management coordinates other modes
- **Contextual**: Token Efficiency activates under resource pressure
- **Complementary**: Introspection provides transparency for any mode
**Q: How do modes relate to agents and commands?**
A: Integrated coordination:
- **Commands** trigger appropriate modes automatically
- **Agents** work within mode communication patterns
- **MCP servers** are selected by Orchestration mode logic
**Q: What if automatic detection is wrong?**
A: Manual override available:
```bash
/sc:command --brainstorm # Force discovery approach
/sc:command --no-introspect # Suppress reasoning markers
/sc:command --uc # Force compression
```
---
## Technical Reference 🔧
**Mode Activation Triggers:**
| Mode | Automatic Triggers | Manual Flags |
|------|-------------------|--------------|
| **Brainstorming** | "brainstorm", "explore", "maybe", "not sure" | `--brainstorm`, `--bs` |
| **Introspection** | Error recovery, self-analysis requests | `--introspect` |
| **Task Management** | >3 steps, >2 directories, >3 files | `--task-manage`, `--delegate` |
| **Orchestration** | Multi-tool ops, >75% resources, >3 files | `--orchestrate` |
| **Token Efficiency** | >75% context, large ops, resource pressure | `--uc`, `--ultracompressed` |
| **Standard** | Simple tasks, no complexity triggers | Default |
**Flag Reference:**
**Mode Control Flags:**
- `--brainstorm` / `--bs`: Force collaborative discovery
- `--introspect`: Enable reasoning transparency
- `--task-manage`: Activate hierarchical coordination
- `--orchestrate`: Optimize tool selection and parallelization
- `--token-efficient` / `--uc`: Enable symbol compression
**Mode Integration Flags:**
- `--think`: Enable Sequential MCP (moderate analysis)
- `--think-hard`: Deep analysis with Sequential + Context7
- `--ultrathink`: Maximum analysis with all MCP servers
- `--safe-mode`: Conservative execution with validation
**Mode Interaction with Framework Components:**
**Agent Coordination:**
- Modes influence agent communication patterns
- Task Management coordinates multi-agent workflows
- Orchestration optimizes agent-tool combinations
- Token Efficiency compresses agent outputs
**Command Integration:**
- Commands auto-select appropriate modes
- Mode flags override automatic selection
- Complex commands activate Task Management
- Analysis commands trigger Introspection
**MCP Server Selection:**
- Orchestration mode optimizes MCP coordination
- Token Efficiency mode minimizes MCP overhead
- Task Management preserves MCP context across phases
- Brainstorming leverages Sequential for structured thinking
**Performance Metrics:**
| Mode | Token Reduction | Processing Speed | Quality Impact |
|------|----------------|------------------|----------------|
| **Brainstorming** | 0% | Standard | +Requirements clarity |
| **Introspection** | -10% (detail) | -15% (analysis) | +Learning, +Debugging |
| **Task Management** | +20% (structure) | +30% (parallel) | +Completeness |
| **Orchestration** | +15% (efficiency) | +45% (parallel) | +Tool optimization |
| **Token Efficiency** | +30-50% | +25% (less context) | Maintained (95%+) |
| **Standard** | Baseline | Baseline | Baseline |
---
## The Magic of Intelligent Adaptation ✨
SuperClaude's behavioral modes represent a breakthrough in AI framework design: **intelligence that adapts to you, not the other way around**. The system observes your context, analyzes task complexity, and seamlessly adjusts its communication style, tool selection, and workflow approach.
**You Don't Need to Think About Modes** - they work transparently in the background, enhancing your experience without adding complexity. Start a vague project idea and watch Brainstorming mode guide discovery. Tackle complex refactoring and see Task Management coordinate phases. Work under resource pressure and observe Token Efficiency compress communication while preserving clarity.
**The Result**: Claude Code transforms from a capable assistant into an **intelligent partner** that matches your needs at every step of the development journey.
---
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../Getting-Started/quick-start.md) - Experience modes naturally
- [Commands Reference](commands.md) - Commands automatically activate modes
- [Installation Guide](../Getting-Started/installation.md) - Set up behavioral modes
**🌿 Intermediate (Week 2-3)**
- [Agents Guide](agents.md) - How modes coordinate with specialists
- [Flags Guide](flags.md) - Manual mode control and optimization
- [Examples Cookbook](../Reference/examples-cookbook.md) - Mode patterns in practice
**🌲 Advanced (Month 2+)**
- [MCP Servers](mcp-servers.md) - Mode integration with enhanced capabilities
- [Session Management](session-management.md) - Task Management mode workflows
- [Best Practices](../Reference/best-practices.md) - Mode optimization strategies
**🔧 Expert**
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Mode implementation details
- [Contributing Code](../Developer-Guide/contributing-code.md) - Extend mode capabilities
**Mode-Specific Guides:**
- **Brainstorming**: [Requirements Discovery Patterns](../Reference/examples-cookbook.md#requirements)
- **Task Management**: [Session Management Guide](session-management.md)
- **Orchestration**: [MCP Servers Guide](mcp-servers.md)
- **Token Efficiency**: [Performance Optimization](../Reference/best-practices.md#efficiency)

827
User-Guide/session-management.md Normal file
View File

@ -0,0 +1,827 @@
# SuperClaude Session Management Guide 🧠
## Introduction
SuperClaude transforms Claude Code from a stateless assistant into a **persistent development partner** through intelligent session management. Sessions preserve project context, accumulated insights, and development progress across interruptions, creating continuity that builds expertise over time.
**Persistent Intelligence**: Load project context with `/sc:load`, work naturally with accumulated understanding, save progress with `/sc:save`, and resume exactly where you left off. SuperClaude remembers your codebase structure, decisions made, patterns discovered, and project goals.
**Cross-Session Learning**: Each session builds on previous understanding, creating a development partner that becomes more effective with your specific project over time.
## Session Fundamentals
**What is a SuperClaude Session?**
A session is a persistent development context that includes:
- **Project Understanding**: Codebase structure, architecture patterns, dependencies
- **Development History**: Decisions made, problems solved, patterns applied
- **Current State**: Active tasks, progress tracking, next steps
- **Learned Insights**: Code conventions, team preferences, domain knowledge
**Session Intelligence vs Standard Claude:**
- **Standard Claude**: Each conversation starts fresh, no project memory
- **SuperClaude Sessions**: Cumulative understanding that builds over time
**Session Types:**
**Project Sessions**: Long-term development context for specific codebases
- Persistent across weeks/months of development
- Accumulates architectural understanding
- Remembers team conventions and decisions
**Task Sessions**: Focused context for specific features or problems
- Short to medium-term (hours to days)
- Maintains task-specific context and progress
- Integrates with project sessions for broader context
**Learning Sessions**: Educational context for understanding complex systems
- Preserves learning progress and insights
- Builds conceptual understanding over time
- Connects theoretical knowledge with practical application
**Session Persistence Powered by Serena MCP:**
- Semantic code understanding with symbol-level navigation
- Project memory that survives Claude Code restarts
- Intelligent context loading based on current work
- Cross-session insight accumulation and pattern recognition
## Session Commands
### /sc:load - Session Initialization
**Purpose**: Load project context and initialize persistent development session
**Usage Patterns:**
```bash
# Load existing project context
/sc:load src/
# Load with specific focus
/sc:load --focus architecture existing-project/
# Load previous session by name
/sc:load "payment-integration-session"
# Load with fresh analysis
/sc:load --refresh large-codebase/
```
**What Happens During Load:**
1. **Project Structure Analysis**: Serena MCP scans codebase organization
2. **Context Restoration**: Previous session memory and insights loaded
3. **Pattern Recognition**: Code conventions and architecture patterns identified
4. **Dependency Mapping**: Component relationships and data flow understood
5. **Session Initialization**: Persistent context established for continued work
**Load Modes:**
**Smart Load (Default):**
```bash
/sc:load project-directory/
```
- Automatically detects project type and structure
- Loads relevant previous session context
- Optimizes analysis based on project size and complexity
**Focused Load:**
```bash
/sc:load --focus security payment-system/
/sc:load --focus performance api-endpoints/
/sc:load --focus architecture microservices/
```
- Specialized analysis for specific concerns
- Activates domain experts and relevant tools
- Loads context specific to focus area
**Fresh Load:**
```bash
/sc:load --refresh --comprehensive legacy-system/
```
- Re-analyzes project from scratch
- Updates understanding with latest changes
- Comprehensive re-indexing of codebase
**Example Load Experience:**
```bash
/sc:load e-commerce-platform/
→ 🔍 Analyzing project structure...
→ 📂 Detected: React frontend + Node.js API + PostgreSQL
→ 🧠 Loading previous session: "checkout-optimization-work"
→ 📝 Restored context: 847 files analyzed, 23 patterns identified
→ ✅ Session ready: Continue checkout flow optimization
→ 💡 Next: Complete payment validation implementation
```
### /sc:save - Session Persistence
**Purpose**: Preserve session context and development progress for future continuation
**Usage Patterns:**
```bash
# Save current session with automatic naming
/sc:save
# Save with descriptive name
/sc:save "authentication-module-complete"
# Save checkpoint during long work
/sc:save --checkpoint "api-endpoints-analysis-done"
# Save with summary
/sc:save --description "Completed user registration flow, ready for testing"
```
**What Gets Saved:**
- **Project Understanding**: Current codebase analysis and insights
- **Work Progress**: Completed tasks, current focus, next steps
- **Decision History**: Architectural choices, patterns applied, trade-offs made
- **Code Context**: Modified files, dependencies, integration points
- **Learning Insights**: Discovered patterns, conventions, best practices
**Save Types:**
**Milestone Save:**
```bash
/sc:save "payment-integration-complete"
```
- Major feature completion or phase end
- Comprehensive context preservation
- Clear handoff point for future sessions
**Checkpoint Save:**
```bash
/sc:save --checkpoint "database-schema-analysis"
```
- Periodic progress preservation
- Intermediate work state capture
- Recovery point for complex work
**Automatic Save:**
```bash
# Triggered automatically during:
- Long-running tasks (every 30 minutes)
- Before risky operations
- Session interruption detection
- Context limit approaching
```
**Save Output Example:**
```bash
/sc:save "user-dashboard-feature-complete"
→ 💾 Saving session context...
→ 📊 Progress summary:
✅ 3 components implemented
✅ 12 tests passing
✅ API integration complete
📝 Documentation updated
→ 🧠 Context preserved:
- 247 files in working memory
- 15 architectural patterns identified
- 8 integration points mapped
→ ✅ Session saved: "user-dashboard-feature-complete"
→ 🔄 Ready for future continuation
```
### /sc:reflect - Session Validation
**Purpose**: Analyze session progress, validate task completion, and assess development quality
**Usage Patterns:**
```bash
# General session reflection
/sc:reflect
# Specific task validation
/sc:reflect "payment-processing-implementation"
# Quality assessment
/sc:reflect --type quality-review
# Completion verification
/sc:reflect --type completion-check
```
**Reflection Types:**
**Progress Analysis:**
```bash
/sc:reflect --type progress
```
- Current task status and completion percentage
- Blockers and dependencies identified
- Next steps and priority recommendations
- Timeline and effort assessment
**Quality Review:**
```bash
/sc:reflect --type quality
```
- Code quality assessment and improvements needed
- Test coverage and validation gaps
- Security and performance considerations
- Documentation and maintainability review
**Completion Verification:**
```bash
/sc:reflect --type completion
```
- Task completion criteria assessment
- Integration and testing verification
- Deployment readiness evaluation
- Handoff preparation and next steps
**Learning Assessment:**
```bash
/sc:reflect --type learning
```
- Insights gained and patterns discovered
- Decision rationale and trade-offs made
- Knowledge gaps and learning opportunities
- Best practices and conventions established
**Example Reflection Output:**
```bash
/sc:reflect --type completion "user-authentication-system"
→ 🎯 Task Completion Analysis:
✅ JWT authentication implemented
✅ Password hashing and validation
✅ Session management
⚠️ Email verification pending
❌ OAuth integration incomplete
→ 📊 Quality Assessment:
✅ Security best practices followed
✅ 89% test coverage achieved
⚠️ Performance testing needed
✅ Documentation complete
→ 🔄 Next Steps:
1. Complete email verification flow
2. Implement OAuth providers
3. Performance optimization
4. Production deployment preparation
→ 💡 Session Status: 75% complete, 2-3 days remaining
```
## Session Lifecycle Management
**Complete Session Workflow:**
### Phase 1: Session Initialization
```bash
# 1. Project Discovery and Loading
/sc:load new-project/
→ Project analysis and context establishment
# 2. Goal Setting and Planning
/sc:brainstorm "improve user onboarding experience"
→ Requirements discovery and strategic planning
# 3. Initial Analysis
/sc:analyze --focus user-experience --think-hard
→ Comprehensive system understanding
```
### Phase 2: Active Development
```bash
# 4. Implementation Planning
/sc:workflow "streamlined-onboarding-flow"
→ Systematic implementation strategy
# 5. Feature Development (Iterative)
/sc:implement "progressive-user-registration"
→ Coordinated development with automatic progress tracking
# 6. Regular Checkpoints
/sc:save --checkpoint "registration-flow-complete"
→ Periodic progress preservation
```
### Phase 3: Validation and Quality
```bash
# 7. Progress Review
/sc:reflect --type progress
→ Status assessment and next steps
# 8. Quality Assurance
/sc:test --comprehensive user-onboarding/
→ Testing and validation workflows
# 9. Quality Review
/sc:reflect --type quality
→ Code review and improvement identification
```
### Phase 4: Completion and Handoff
```bash
# 10. Completion Verification
/sc:reflect --type completion
→ Task completion criteria validation
# 11. Final Documentation
/sc:document --type user-guide onboarding-system/
→ Documentation and knowledge transfer
# 12. Session Archive
/sc:save "onboarding-improvement-complete"
→ Final context preservation and handoff preparation
```
**Session State Transitions:**
**Active Session States:**
- **Discovery**: Requirements exploration and goal setting
- **Analysis**: System understanding and strategy development
- **Implementation**: Active development and feature creation
- **Validation**: Testing, review, and quality assurance
- **Completion**: Final verification and handoff preparation
**Session Continuity Patterns:**
- **Daily Sessions**: Load → Work → Checkpoint → Save
- **Weekly Sprints**: Load → Sprint planning → Daily work → Sprint review → Save
- **Feature Cycles**: Load → Analysis → Implementation → Testing → Completion → Save
## Memory and Context
**Serena MCP-Powered Memory System:**
**Project Memory Components:**
- **Structural Memory**: Codebase organization, file relationships, dependencies
- **Semantic Memory**: Code meaning, business logic, domain concepts
- **Historical Memory**: Development decisions, evolution patterns, change history
- **Contextual Memory**: Working sessions, current focus, progress state
**Memory Operations:**
**Memory Accumulation:**
```bash
# As you work, memory automatically builds:
/sc:analyze user-service/
→ Records: Service patterns, data flows, API contracts
/sc:implement "user-preferences"
→ Records: Implementation patterns, coding conventions, integration points
/sc:troubleshoot "performance-issue"
→ Records: Problem patterns, solution strategies, optimization techniques
```
**Memory Recall:**
```bash
# Previous insights automatically inform current work:
/sc:implement "user-notifications"
→ Recalls: User service patterns, preference storage, communication flows
→ Applies: Established conventions, tested patterns, integration strategies
```
**Memory Types:**
**Architectural Memory:**
```json
{
"patterns": ["MVC", "Repository Pattern", "Dependency Injection"],
"conventions": ["camelCase variables", "async/await preferred"],
"decisions": ["PostgreSQL for persistence", "JWT for authentication"],
"integrations": ["Stripe API", "SendGrid", "Redis cache"]
}
```
**Development Memory:**
```json
{
"workflows": ["TDD approach", "Feature branch strategy"],
"quality_gates": ["ESLint rules", "Test coverage >80%"],
"preferences": ["Functional components", "Hooks over classes"],
"tooling": ["Jest testing", "Prettier formatting"]
}
```
**Context Preservation:**
```json
{
"current_task": "implement-user-dashboard",
"progress": "components-complete-api-pending",
"next_steps": ["API integration", "state management", "testing"],
"blockers": ["API rate limiting", "design system tokens"]
}
```
**Memory Intelligence:**
**Smart Context Loading:**
- Loads relevant memory based on current work
- Prioritizes recent and frequently accessed patterns
- Connects related concepts and components
**Pattern Recognition:**
- Identifies recurring code patterns and conventions
- Suggests consistent approaches based on project history
- Detects deviations from established patterns
**Predictive Context:**
- Anticipates needed information based on current task
- Pre-loads related components and dependencies
- Suggests next steps based on similar previous work
## Session Workflows
**Common Session Patterns:**
### Daily Development Session
```bash
# Morning: Resume previous work
/sc:load project/
→ Context restoration and progress review
# Planning: Review and plan day's work
/sc:reflect --type progress
→ Status assessment and priority setting
# Work: Active development with periodic saves
/sc:implement "current-feature"
/sc:save --checkpoint "feature-milestone"
# Evening: End-of-day preservation
/sc:reflect --type completion
/sc:save "end-of-day-progress"
```
### Feature Development Cycle
```bash
# Discovery Phase
/sc:load project/
/sc:brainstorm "new-feature-requirements"
/sc:save --checkpoint "requirements-complete"
# Planning Phase
/sc:workflow "feature-implementation-plan"
/sc:design "feature-architecture"
/sc:save --checkpoint "planning-complete"
# Implementation Phase
/sc:implement "feature-core-functionality"
/sc:save --checkpoint "core-complete"
/sc:implement "feature-integration"
/sc:save --checkpoint "integration-complete"
# Validation Phase
/sc:test --comprehensive feature/
/sc:reflect --type quality
/sc:save "feature-complete"
```
### Bug Investigation Session
```bash
# Load with focus on problem area
/sc:load --focus debugging problematic-module/
# Systematic investigation
/sc:troubleshoot "specific-bug-description"
/sc:analyze --focus root-cause affected-components/
# Solution implementation
/sc:implement "bug-fix-solution"
/sc:test --focus regression bug-area/
# Validation and documentation
/sc:reflect --type completion
/sc:document --type bug-report "issue-resolution"
/sc:save "bug-fix-complete"
```
### Learning and Exploration Session
```bash
# Focused learning context
/sc:load --focus architecture new-codebase/
# Systematic exploration
/sc:analyze --introspect --think-hard codebase-structure/
/sc:explain "complex-architectural-patterns"
# Knowledge consolidation
/sc:reflect --type learning
/sc:document --type architecture-notes findings/
/sc:save "architecture-understanding-session"
```
### Code Review Session
```bash
# Load changes context
/sc:load --focus quality pending-changes/
# Comprehensive review
/sc:analyze --focus quality --think-hard changes/
/sc:test --focus regression change-areas/
# Quality assessment
/sc:reflect --type quality
/sc:document --type review-notes quality-assessment/
/sc:save "code-review-complete"
```
**Session Optimization Patterns:**
**Short Sessions (1-2 hours):**
- Quick load with specific focus
- Targeted work on single component
- Checkpoint saves for continuity
**Medium Sessions (Half-day):**
- Comprehensive load and planning
- Multi-component development
- Regular checkpoints and quality reviews
**Long Sessions (Full-day):**
- Full context loading and analysis
- Complex feature development cycles
- Multiple validation and reflection points
## Multi-Session Projects
**Long-Term Project Management:**
### Project Session Architecture
```bash
# Master Project Session
/sc:load enterprise-platform/
→ Maintains overall project context and architecture understanding
# Feature Branch Sessions
/sc:load --branch feature/user-management user-service/
/sc:load --branch feature/payment-integration payment-service/
→ Focused context for specific feature development
# Integration Sessions
/sc:load --integration-focus platform-services/
→ Cross-service integration and system-level concerns
```
### Session Hierarchy Management
**Project Level (Months):**
- Overall architecture and system understanding
- Cross-cutting concerns and integration patterns
- Long-term technical decisions and evolution
**Epic Level (Weeks):**
- Feature set implementation and integration
- Domain-specific patterns and conventions
- Epic-level progress and quality tracking
**Story Level (Days):**
- Individual feature implementation
- Component-level development and testing
- Story completion and handoff
**Session Coordination Patterns:**
**Team Coordination:**
```bash
# Shared Project Context
/sc:load --shared team-project/
→ Common understanding accessible to all team members
# Individual Developer Sessions
/sc:load --developer alice team-project/user-auth/
/sc:load --developer bob team-project/payment-system/
→ Personal development context within shared project
# Integration Sessions
/sc:load --integration team-project/
→ Cross-developer integration and system-level work
```
**Cross-Session Continuity:**
**Session Handoff:**
```bash
# End of developer session
/sc:save --handoff "alice-user-auth-complete" --next-developer bob
# New developer pickup
/sc:load --handoff "alice-user-auth-complete"
→ Complete context transfer with work continuation
```
**Progress Synchronization:**
```bash
# Daily standup preparation
/sc:reflect --type team-progress
→ Team-level progress summary and coordination
# Sprint planning context
/sc:load --sprint-context team-project/
→ Sprint-level understanding and planning context
```
**Long-Term Memory Evolution:**
**Memory Consolidation:**
- Weekly: Consolidate daily insights into persistent patterns
- Monthly: Archive completed features, preserve key learnings
- Quarterly: Architectural review and pattern evolution
**Memory Inheritance:**
- New features inherit patterns from completed work
- Team members inherit shared conventions and decisions
- Project evolution builds on accumulated architectural understanding
## Session Troubleshooting
**Common Session Issues:**
### Session Context Lost
**Problem**: `/sc:load` doesn't restore expected context
```bash
# Symptoms
/sc:load project/
→ "No previous session found" or minimal context restored
```
**Solutions:**
```bash
# 1. Check available sessions
/sc:load --list-sessions
# 2. Load by specific session name
/sc:load "session-name"
# 3. Fresh analysis if needed
/sc:load --refresh --comprehensive project/
# 4. Check Serena MCP status
SuperClaude status --mcp serena
```
### Memory Fragmentation
**Problem**: Session memory becomes inconsistent or incomplete
```bash
# Symptoms
- Conflicting pattern suggestions
- Missing context for recent work
- Inconsistent architectural understanding
```
**Solutions:**
```bash
# 1. Memory consolidation
/sc:reflect --type memory-health
/sc:save --consolidate "clean-session-state"
# 2. Selective memory refresh
/sc:load --refresh-memory specific-area/
# 3. Clean session restart
/sc:save --archive "old-session"
/sc:load --fresh project/
```
### Session Performance Issues
**Problem**: Slow session loading or excessive memory usage
```bash
# Symptoms
- Long load times (>30 seconds)
- Memory warnings during operation
- Reduced response quality
```
**Solutions:**
```bash
# 1. Optimize session scope
/sc:load --scope module target-area/
# 2. Use focused loading
/sc:load --focus performance specific-concern/
# 3. Memory cleanup
/sc:save --cleanup "optimized-session"
# 4. Check system resources
SuperClaude diagnose --memory
```
### Integration Conflicts
**Problem**: Multi-session project coordination issues
```bash
# Symptoms
- Conflicting architectural decisions
- Integration pattern mismatches
- Cross-team context confusion
```
**Solutions:**
```bash
# 1. Sync with master session
/sc:load --sync-master project/
# 2. Resolve conflicts explicitly
/sc:reflect --type integration-conflicts
/sc:resolve-conflicts --strategy team-lead-wins
# 3. Re-establish shared context
/sc:load --shared-refresh team-project/
```
**Session Recovery Procedures:**
### Emergency Session Recovery
```bash
# 1. Check session backups
/sc:load --list-backups
# 2. Restore from backup
/sc:load --restore-backup "backup-timestamp"
# 3. Partial recovery if needed
/sc:load --partial-restore specific-components/
# 4. Rebuild from artifacts
/sc:load --rebuild-from git-history project/
```
### Session Health Monitoring
```bash
# Regular health checks
/sc:reflect --type session-health
→ Memory consistency, context completeness, performance metrics
# Memory optimization
/sc:save --optimize "clean-session"
→ Consolidate insights, remove redundant context
# Performance tuning
/sc:load --performance-mode project/
→ Optimized loading for resource-constrained environments
```
**Best Practices for Session Reliability:**
1. **Regular Saves**: Save at natural breakpoints and end of work
2. **Descriptive Names**: Use clear, descriptive session names
3. **Health Monitoring**: Regular reflection and health checks
4. **Backup Strategy**: Multiple checkpoint saves during long work
5. **Scope Management**: Load only necessary context for current work
6. **Memory Hygiene**: Periodic consolidation and cleanup
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../Getting-Started/quick-start.md) - First session experience
- [Commands Reference](commands.md) - Session commands (/sc:load, /sc:save, /sc:reflect)
- [Installation Guide](../Getting-Started/installation.md) - Serena MCP setup for sessions
**🌿 Intermediate (Week 2-3)**
- [MCP Servers Guide](mcp-servers.md) - Serena MCP for persistent memory
- [Behavioral Modes](modes.md) - Task Management mode for session coordination
- [Agents Guide](agents.md) - Agent persistence across sessions
**🌲 Advanced (Month 2+)**
- [Best Practices](../Reference/best-practices.md) - Session optimization strategies
- [Examples Cookbook](../Reference/examples-cookbook.md) - Multi-session project patterns
- [Flags Guide](flags.md) - Session control flags and optimization
**🔧 Expert**
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Session implementation details
- [Contributing Code](../Developer-Guide/contributing-code.md) - Extending session capabilities
**Session-Specific Learning:**
**🎯 Session Command Mastery:**
- **Load Patterns**: `/sc:load` variations for different contexts
- **Save Strategies**: Checkpoint vs milestone vs completion saves
- **Reflection Types**: Progress, quality, completion, learning assessments
**🧠 Memory Management:**
- **Context Building**: How memory accumulates and evolves
- **Pattern Recognition**: Understanding session intelligence
- **Memory Optimization**: Efficient context management
**👥 Team Coordination:**
- **Shared Sessions**: Multi-developer session coordination
- **Handoff Patterns**: Session transfer and continuity
- **Integration Sessions**: Cross-team collaboration
**🔄 Project Lifecycle:**
- **Daily Workflows**: Effective day-to-day session patterns
- **Feature Cycles**: Multi-session feature development
- **Long-term Projects**: Enterprise-scale session management
**💡 Session Mastery Tips:**
- **Start Small**: Begin with simple load-work-save patterns
- **Build Habits**: Regular reflection and checkpoint saves
- **Learn Memory**: Understand how context builds over time
- **Optimize Gradually**: Advanced patterns as projects grow
- **Monitor Health**: Regular session health and performance checks
**Common Session Workflows:**
- **New Project**: Load → Analyze → Plan → Save
- **Daily Work**: Load → Progress check → Work → Checkpoint → Save
- **Feature Development**: Load → Brainstorm → Implement → Test → Reflect → Save
- **Bug Investigation**: Load focused → Troubleshoot → Fix → Validate → Save
- **Code Review**: Load changes → Analyze quality → Review → Document → Save