mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor(docs): normalize documentation naming to lowercase for PEP8 compliance (#434)
* refactor(docs): rename directories to lowercase for PEP8 compliance - Developer-Guide → developer-guide - Getting-Started → getting-started - Reference → reference - Templates → templates - User-Guide → user-guide - User-Guide-jp → user-guide-jp - User-Guide-kr → user-guide-kr - User-Guide-zh → user-guide-zh This change aligns with Python PEP8 package naming conventions. All 43 files affected. * refactor: rename root documentation files to lowercase - CHANGELOG.md → changelog.md - CODE_OF_CONDUCT.md → code_of_conduct.md - CONTRIBUTING.md → contributing.md - SECURITY.md → security.md Aligns with Python package naming conventions (PEP8). README files remain uppercase as per convention. * refactor: move documentation files to docs/ for cleaner root Moved OSS standard files to docs/: - CHANGELOG.md → docs/CHANGELOG.md - CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md - CONTRIBUTING.md → docs/CONTRIBUTING.md - SECURITY.md → docs/SECURITY.md Root now contains only essential files: ✓ README files (表紙: en, ja, kr, zh) ✓ LICENSE (法的要件) ✓ Build configs (pyproject.toml, setup.py, MANIFEST.in) ✓ VERSION Rationale: Cleaner root structure following modern Python project conventions. All detailed documentation consolidated in docs/ directory. * refactor: update documentation links after restructure Auto-updated internal documentation links to reflect new structure: - docs/ subdirectories now lowercase (PEP8) - Root files moved to docs/ - All cross-references updated This commit includes linter-generated link updates. * chore(docs): keep OSS-standard uppercase root files (CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY) * chore(docs): remove duplicated PR docs from repo root (moved under docs) * docs: rename pm-agent-implementation-status.md -> PM_AGENT.md for clarity * docs: update links to PM_AGENT.md after rename --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local>
This commit is contained in:
kazuki nakai
@@ -1,172 +0,0 @@
|
||||
# SuperClaude Framework Developer Guide
|
||||
|
||||
A documentation suite for understanding and extending the SuperClaude Context-Oriented Configuration Framework.
|
||||
|
||||
## Documentation Overview
|
||||
|
||||
This Developer Guide provides documentation for understanding SuperClaude's context architecture and how to extend it:
|
||||
|
||||
### [Contributing Code Guide](contributing-code.md)
|
||||
**Purpose**: Guidelines for contributing context files and framework improvements
|
||||
**Audience**: Contributors and framework maintainers
|
||||
**Key Topics**: Adding context files, naming conventions, documentation standards
|
||||
|
||||
### [Context Architecture Guide](technical-architecture.md)
|
||||
**Purpose**: Understanding how context files work and are structured
|
||||
**Audience**: Anyone wanting to understand or extend SuperClaude
|
||||
**Key Topics**: Context file structure, import system, agent/command patterns
|
||||
|
||||
### [Verification & Troubleshooting Guide](testing-debugging.md)
|
||||
**Purpose**: Verifying installation and troubleshooting context file issues
|
||||
**Audience**: Users and maintainers
|
||||
**Key Topics**: File verification, common issues, diagnostic commands
|
||||
|
||||
### [Documentation Index](documentation-index.md)
|
||||
**Purpose**: Comprehensive navigation guide and topic-based organization
|
||||
**Audience**: All users seeking efficient information discovery
|
||||
**Key Features**: Skill level pathways, cross-references, quality validation, usage guidelines
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### For New Contributors
|
||||
1. Start with [Contributing Code Guide](contributing-code.md#development-setup) for environment setup
|
||||
2. Review [Technical Architecture Guide](technical-architecture.md#architecture-overview) for system understanding
|
||||
3. Use [Testing & Debugging Guide](testing-debugging.md#quick-start-testing-tutorial) for testing basics
|
||||
|
||||
### For System Architects
|
||||
1. Begin with [Technical Architecture Guide](technical-architecture.md) for complete system design
|
||||
2. Reference [Contributing Code Guide](contributing-code.md#architecture-overview) for component patterns
|
||||
3. Review [Testing & Debugging Guide](testing-debugging.md#integration-testing) for validation frameworks
|
||||
|
||||
### For Testing Engineers
|
||||
1. Start with [Testing & Debugging Guide](testing-debugging.md) for comprehensive testing procedures
|
||||
2. Reference [Contributing Code Guide](contributing-code.md#development-workflow) for development integration
|
||||
3. Use [Technical Architecture Guide](technical-architecture.md#quality-framework) for architecture context
|
||||
|
||||
## Key Framework Concepts
|
||||
|
||||
### Context-Oriented Configuration
|
||||
SuperClaude is a collection of `.md` instruction files that Claude Code reads to modify its behavior. It is NOT executing software.
|
||||
|
||||
**IMPORTANT**: SuperClaude is NOT a CLI tool or executable software. When you see `/sc:` commands in documentation, these are **context trigger patterns** you type in Claude Code conversations, not terminal commands.
|
||||
|
||||
### Agent Context Files
|
||||
Specialized instruction sets that provide domain expertise when activated by `@agent-[name]` or automatically by keywords.
|
||||
|
||||
### Command Context Files
|
||||
Workflow patterns triggered by `/sc:[command]` **context patterns** (not CLI commands) that guide Claude Code through structured development tasks when you type them in Claude Code conversations.
|
||||
|
||||
### MCP Integration
|
||||
External tools (actual software) that can be configured to provide additional capabilities like documentation lookup or code analysis.
|
||||
|
||||
## What SuperClaude Is NOT
|
||||
|
||||
- ❌ **Not Software**: No code executes, no processes run
|
||||
- ❌ **Not Testable**: Context files are instructions, not functions
|
||||
- ❌ **Not Optimizable**: No performance to measure or improve
|
||||
- ❌ **Not Persistent**: Each Claude conversation is independent
|
||||
|
||||
## Documentation Features
|
||||
|
||||
### Cross-Referenced Integration
|
||||
All three documents are strategically cross-referenced, enabling seamless navigation between development workflows, architectural understanding, and testing procedures.
|
||||
|
||||
### Accessibility & Inclusivity
|
||||
- **Screen Reader Support**: Full navigation guidance and diagram descriptions
|
||||
- **Skill Level Pathways**: Clear progression from beginner to advanced
|
||||
- **Comprehensive Glossaries**: 240+ technical terms with detailed definitions
|
||||
- **Learning Resources**: Time estimates and prerequisite guidance
|
||||
|
||||
### Consistent Terminology
|
||||
Unified technical vocabulary ensures clear communication across all documentation, with key terms defined consistently throughout comprehensive glossaries.
|
||||
|
||||
### Comprehensive Code Examples
|
||||
All code examples include proper documentation, error handling, and follow consistent formatting standards suitable for production use.
|
||||
|
||||
### Security-First Approach
|
||||
Security considerations are embedded throughout all documentation, from development practices to testing procedures to architectural design.
|
||||
|
||||
### Professional Quality Standards
|
||||
- **WCAG 2.1 Compliant**: Full accessibility standards compliance
|
||||
- **Technical Accuracy**: All examples tested and verified
|
||||
- **Framework Integration**: Documentation quality matches framework sophistication
|
||||
- **Community Focus**: Inclusive design for developers of all abilities
|
||||
|
||||
## Document Status
|
||||
|
||||
✅ **Phase 1 Complete**: Critical issues resolved, basic structure established
|
||||
✅ **Phase 2 Complete**: Cross-document consistency, navigation improvements, security integration
|
||||
✅ **Phase 3 Complete**: Advanced examples, visual diagrams, enhanced architecture documentation
|
||||
✅ **Phase 4 Complete**: Accessibility improvements, comprehensive glossaries, skill level guidance, professional polish
|
||||
|
||||
### Accessibility & Quality Enhancements (Phase 4)
|
||||
- **240+ Glossary Terms**: Comprehensive technical definitions across all documents
|
||||
- **Screen Reader Support**: Full accessibility with navigation guidance and diagram descriptions
|
||||
- **Skill Level Pathways**: Clear learning progressions from beginner to advanced
|
||||
- **Professional Polish**: Documentation quality aligned with framework sophistication
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Python 3.8+ (for installation tool)
|
||||
- Claude Code installed
|
||||
- Optional: Node.js 16+ for MCP servers
|
||||
|
||||
### Understanding the Framework
|
||||
```bash
|
||||
# Check installation
|
||||
ls ~/.claude/
|
||||
# You'll see context files, not executable code
|
||||
|
||||
# View a command context
|
||||
cat ~/.claude/commands/implement.md
|
||||
# You'll see instructions for Claude, not code
|
||||
|
||||
# View an agent context
|
||||
cat ~/.claude/agents/python-expert.md
|
||||
# You'll see expertise definitions, not programs
|
||||
```
|
||||
|
||||
### Extending SuperClaude
|
||||
1. **Add Commands**: Create new `.md` files in `~/.claude/commands/`
|
||||
2. **Add Agents**: Create new `.md` files in `~/.claude/agents/`
|
||||
3. **Add Modes**: Create new `.md` files in `~/.claude/modes/`
|
||||
|
||||
No compilation, no testing, no deployment - just add context files and Claude Code will read them automatically.
|
||||
|
||||
## Support and Resources
|
||||
|
||||
### Documentation Issues
|
||||
- **Broken Links**: Report cross-reference issues in GitHub issues
|
||||
- **Unclear Content**: Request clarification through GitHub discussions
|
||||
- **Missing Information**: Suggest improvements through pull requests
|
||||
|
||||
### Development Support
|
||||
- **Technical Questions**: Use GitHub discussions for architecture and implementation questions
|
||||
- **Bug Reports**: Submit detailed issues with reproduction steps
|
||||
- **Feature Requests**: Propose enhancements through GitHub issues
|
||||
|
||||
### Community Resources
|
||||
- **[GitHub Repository](https://github.com/SuperClaude-Org/SuperClaude_Framework)**: Main development and collaboration hub
|
||||
|
||||
## Contributing to Documentation
|
||||
|
||||
We welcome contributions to improve documentation quality, accuracy, and completeness:
|
||||
|
||||
### Documentation Standards
|
||||
- **Clarity**: Write for your target audience skill level
|
||||
- **Consistency**: Follow established terminology and formatting
|
||||
- **Completeness**: Provide working examples and complete procedures
|
||||
- **Cross-References**: Link related concepts across documents
|
||||
|
||||
### Submission Process
|
||||
1. Fork the repository and create a feature branch
|
||||
2. Make documentation improvements following our standards
|
||||
3. Test all code examples and verify cross-references
|
||||
4. Submit pull request with clear description of changes
|
||||
|
||||
---
|
||||
|
||||
**SuperClaude Framework**: Building the future of AI-assisted development through intelligent orchestration and behavioral programming.
|
||||
|
||||
For the latest updates and community discussions, visit our [GitHub repository](https://github.com/SuperClaude-Org/SuperClaude_Framework).
|
||||
@@ -1,401 +0,0 @@
|
||||
# Contributing Context Files to SuperClaude Framework 🛠️
|
||||
|
||||
Welcome to SuperClaude Framework development! This guide provides everything you need to contribute context files and behavioral instructions that enhance Claude Code through structured prompts and MCP server integration.
|
||||
|
||||
**Project Purpose**: SuperClaude provides Claude Code with structured context files and behavioral instructions. We're building the next generation of AI-assisted development through intelligent prompt engineering.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Development Setup](#development-setup) - Prerequisites and environment
|
||||
2. [Architecture Overview](#architecture-overview) - System components and design
|
||||
3. [Context File Guidelines](#context-file-guidelines) - Standards and practices
|
||||
4. [Development Workflow](#development-workflow) - Git workflow and submissions
|
||||
5. [Contributing to Components](#contributing-to-components) - Agents, commands, modes
|
||||
6. [File Validation](#file-validation) - Quality assurance
|
||||
7. [Getting Help](#getting-help) - Support and resources
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
**Required:**
|
||||
- Python 3.8+ with pip
|
||||
- Git for version control
|
||||
- Claude Code installed and working
|
||||
- Node.js 16+ (for MCP server configuration)
|
||||
|
||||
**Environment Setup:**
|
||||
```bash
|
||||
# Fork SuperClaude_Framework on GitHub first
|
||||
git clone https://github.com/YOUR_USERNAME/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
|
||||
# Test installation system
|
||||
PYTHONPATH=/path/to/SuperClaude_Framework python3 -m setup --help
|
||||
|
||||
# Install to development location
|
||||
PYTHONPATH=/path/to/SuperClaude_Framework python3 -m setup install --components core
|
||||
```
|
||||
|
||||
**Validation Check:**
|
||||
```bash
|
||||
# Verify Python version
|
||||
python3 --version # Should be 3.8+
|
||||
|
||||
# Check Node.js for MCP configuration
|
||||
node --version # Should be 16+
|
||||
|
||||
# Test Claude Code integration
|
||||
ls ~/.claude/ # Should show Claude Code directory
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Framework Structure
|
||||
|
||||
SuperClaude is a **Context-Oriented Configuration Framework** - not executing software, but instruction files that Claude Code reads to modify its behavior.
|
||||
|
||||
```
|
||||
SuperClaude_Framework/
|
||||
├── superclaude/ # Framework components (the source of truth)
|
||||
│ ├── Core/ # PRINCIPLES.md, RULES.md, FLAGS.md
|
||||
│ ├── Agents/ # 15 specialized domain experts
|
||||
│ ├── Commands/ # 21 context trigger patterns (/sc: behavioral instructions)
|
||||
│ ├── Modes/ # 6 behavioral modification patterns
|
||||
│ └── MCP/ # 6 MCP server configurations
|
||||
├── setup/ # Python installation system
|
||||
├── docs/ # Documentation (what you're reading)
|
||||
└── tests/ # File validation scripts
|
||||
```
|
||||
|
||||
**Key Concepts:**
|
||||
- **Context Files**: .md instruction files that guide Claude Code behavior
|
||||
- **Agents**: Domain specialists (e.g., security-engineer.md, python-expert.md)
|
||||
- **Commands**: Workflow patterns (e.g., implement.md, analyze.md)
|
||||
- **Modes**: Interaction modifiers (e.g., brainstorming, introspection)
|
||||
- **MCP Integration**: Configuration for Model Context Protocol servers
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
User Input → Claude Code → Reads SuperClaude Context → Modified Behavior → Enhanced Output
|
||||
```
|
||||
|
||||
1. User types `/sc:implement "auth system"` **in Claude Code conversation** (not terminal)
|
||||
2. Claude Code reads `superclaude/Commands/implement.md`
|
||||
3. Command activates security-engineer agent context
|
||||
4. Context7 MCP provides authentication patterns
|
||||
5. Claude generates complete, secure implementation
|
||||
|
||||
## Context File Guidelines
|
||||
|
||||
### File Organization
|
||||
|
||||
**Context Files (`.md`):**
|
||||
- Write clear, actionable instructions for Claude Code
|
||||
- Use frontmatter metadata for configuration
|
||||
- Follow existing patterns and naming conventions
|
||||
- Test instructions produce expected behaviors
|
||||
|
||||
**Installation Scripts (`.py`):**
|
||||
- Follow PEP 8 style guidelines
|
||||
- Include docstrings for functions and classes
|
||||
- Add type hints where beneficial
|
||||
- Focus on file copying and configuration
|
||||
|
||||
**Example Agent Structure:**
|
||||
```markdown
|
||||
---
|
||||
name: new-specialist
|
||||
description: Brief description of expertise
|
||||
category: specialized|architecture|quality
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
## Triggers
|
||||
- Keywords that activate this agent
|
||||
- File types that trigger activation
|
||||
|
||||
## Behavioral Mindset
|
||||
Core philosophy and approach
|
||||
|
||||
## Focus Areas
|
||||
- Domain expertise area 1
|
||||
- Domain expertise area 2
|
||||
|
||||
## Key Actions
|
||||
1. Specific behavior pattern
|
||||
2. Problem-solving approach
|
||||
```
|
||||
|
||||
### Context File Standards
|
||||
|
||||
**Structure Requirements:**
|
||||
- Clear, actionable instructions for Claude Code
|
||||
- Specific triggers and activation patterns
|
||||
- Examples demonstrating usage
|
||||
- Boundaries defining scope
|
||||
|
||||
**Quality Standards:**
|
||||
- Instructions are testable in Claude Code conversations
|
||||
- Examples produce expected behavioral changes
|
||||
- Clear activation triggers and context patterns
|
||||
- Professional language and formatting
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Git Workflow
|
||||
|
||||
1. **Fork and Clone:**
|
||||
```bash
|
||||
# Fork on GitHub, then:
|
||||
git clone https://github.com/YOUR_USERNAME/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
git remote add upstream https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||||
```
|
||||
|
||||
2. **Create Feature Branch:**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
# Work on your changes
|
||||
git add .
|
||||
git commit -m "Add: descriptive commit message"
|
||||
```
|
||||
|
||||
3. **Submit Pull Request:**
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
# Create PR on GitHub
|
||||
```
|
||||
|
||||
### Pull Request Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of context file changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix in context files
|
||||
- [ ] New feature (agent, command, mode)
|
||||
- [ ] Documentation improvement
|
||||
- [ ] Installation system enhancement
|
||||
|
||||
## Testing
|
||||
- [ ] Manual testing with Claude Code
|
||||
- [ ] Context file validation passes
|
||||
- [ ] Examples validated in Claude Code conversations
|
||||
|
||||
## Checklist
|
||||
- [ ] Files follow SuperClaude conventions
|
||||
- [ ] Self-review completed
|
||||
- [ ] Documentation updated
|
||||
- [ ] No breaking changes to existing context
|
||||
```
|
||||
|
||||
### Code Review Process
|
||||
|
||||
**Manual Review:**
|
||||
- Context file clarity and effectiveness
|
||||
- Agent/command logic and triggers
|
||||
- Documentation accuracy and completeness
|
||||
- Integration with existing components
|
||||
- Claude Code behavioral testing results
|
||||
|
||||
## Contributing to Components
|
||||
|
||||
### Adding New Agents
|
||||
|
||||
**Agent Development Process:**
|
||||
1. Identify domain expertise gap
|
||||
2. Create agent file in `superclaude/Agents/`
|
||||
3. Define triggers, behaviors, and boundaries
|
||||
4. Test with various Claude Code scenarios
|
||||
5. Document usage patterns and examples
|
||||
|
||||
**Agent Template:**
|
||||
```markdown
|
||||
---
|
||||
name: agent-name
|
||||
description: Domain expertise description
|
||||
category: specialized
|
||||
tools: Read, Write, Edit, Bash
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
## Triggers
|
||||
- Specific keywords: domain, expertise, area
|
||||
- File patterns: *.domain, specific frameworks
|
||||
- Complexity indicators: architectural decisions
|
||||
|
||||
## Behavioral Mindset
|
||||
- Focus on domain best practices
|
||||
- Systematic approach to problem-solving
|
||||
- Quality and security considerations
|
||||
|
||||
## Focus Areas
|
||||
- Core domain expertise
|
||||
- Related technical areas
|
||||
- Integration patterns
|
||||
|
||||
## Key Actions
|
||||
1. Analyze requirements within domain context
|
||||
2. Apply domain-specific best practices
|
||||
3. Coordinate with related specialists
|
||||
4. Validate solutions meet domain standards
|
||||
```
|
||||
|
||||
### Adding New Commands
|
||||
|
||||
**Command Structure:**
|
||||
```markdown
|
||||
---
|
||||
name: command-name
|
||||
description: Command purpose
|
||||
category: workflow|utility|analysis
|
||||
complexity: basic|standard|advanced
|
||||
mcp-servers: [context7, sequential]
|
||||
personas: [architect, engineer]
|
||||
---
|
||||
|
||||
# /sc:command-name
|
||||
|
||||
## Triggers
|
||||
- When to use this command
|
||||
- Context indicators
|
||||
|
||||
## Usage
|
||||
Type in Claude Code conversation:
|
||||
```
|
||||
/sc:command-name [target] [--options]
|
||||
```
|
||||
**Note**: This is a context trigger pattern, not a terminal command.
|
||||
|
||||
## Workflow Pattern
|
||||
1. Initial analysis
|
||||
2. Processing steps
|
||||
3. Validation and output
|
||||
|
||||
## Examples
|
||||
Practical usage examples
|
||||
```
|
||||
|
||||
### Adding New Modes
|
||||
|
||||
**Mode Development:**
|
||||
- Define activation triggers
|
||||
- Specify behavioral modifications
|
||||
- Create interaction patterns
|
||||
- Test across different Claude Code scenarios
|
||||
|
||||
## File Validation
|
||||
|
||||
### Context File Validation
|
||||
|
||||
**Manual Validation Process:**
|
||||
1. Install development version in Claude Code
|
||||
2. Test agent/command activation triggers in Claude Code conversations
|
||||
3. Verify behavioral modifications occur as expected
|
||||
4. Validate context file structure and formatting
|
||||
5. Test edge cases and error conditions
|
||||
|
||||
**Validation Checklist:**
|
||||
- [ ] Context files use valid markdown syntax
|
||||
- [ ] Triggers activate correctly in Claude Code
|
||||
- [ ] Behavior matches documentation
|
||||
- [ ] No conflicts with existing components
|
||||
- [ ] Examples produce expected results in Claude Code conversations
|
||||
|
||||
### File Structure Validation
|
||||
|
||||
```bash
|
||||
# Check file structure
|
||||
find ~/.claude -name "*.md" | head -10
|
||||
|
||||
# Verify context file format
|
||||
head ~/.claude/agents/python-expert.md
|
||||
|
||||
# Test import system
|
||||
grep "@import" ~/.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Development Support
|
||||
|
||||
**Documentation:**
|
||||
- [Technical Architecture](technical-architecture.md) - System design details
|
||||
- [Verification Guide](testing-debugging.md) - File validation procedures
|
||||
|
||||
**Community Channels:**
|
||||
- GitHub Issues: Bug reports and feature requests
|
||||
- GitHub Discussions: Development questions and ideas
|
||||
- Pull Request Reviews: Context file feedback and collaboration
|
||||
|
||||
**Code Review Guidelines:**
|
||||
- Provide constructive, specific feedback
|
||||
- Test changes locally when possible
|
||||
- Focus on maintainability and clarity
|
||||
- Respect contributor efforts and learning
|
||||
|
||||
### Issue Reporting
|
||||
|
||||
**Bug Reports:**
|
||||
1. Describe expected vs actual behavior in Claude Code
|
||||
2. Provide steps to reproduce with context triggers
|
||||
3. Include environment details and file versions
|
||||
4. Share relevant context file configurations
|
||||
|
||||
**Feature Requests:**
|
||||
1. Explain the behavioral enhancement being proposed
|
||||
2. Describe how users would benefit
|
||||
3. Consider integration with existing context patterns
|
||||
4. Provide usage examples
|
||||
|
||||
## Contributing Guidelines Summary
|
||||
|
||||
### Do's
|
||||
✅ **Follow existing patterns and conventions**
|
||||
✅ **Test context files thoroughly with Claude Code**
|
||||
✅ **Write clear, actionable behavioral instructions**
|
||||
✅ **Provide working examples**
|
||||
✅ **Focus on user experience improvements**
|
||||
✅ **Coordinate with related components**
|
||||
|
||||
### Don'ts
|
||||
❌ **Don't break existing functionality**
|
||||
❌ **Don't add untested context modifications**
|
||||
❌ **Don't ignore style guidelines**
|
||||
❌ **Don't create overly complex behavioral patterns**
|
||||
❌ **Don't duplicate existing functionality**
|
||||
|
||||
### Quality Standards
|
||||
|
||||
**Context Files:**
|
||||
- Clear activation triggers
|
||||
- Specific behavioral instructions
|
||||
- Practical examples
|
||||
- Defined scope boundaries
|
||||
|
||||
**Documentation:**
|
||||
- Accurate and up-to-date
|
||||
- Working context examples
|
||||
- Clear navigation structure
|
||||
- Accessibility considerations
|
||||
|
||||
## License and Attribution
|
||||
|
||||
**MIT License**: SuperClaude Framework is licensed under the MIT License, providing maximum freedom for use, modification, and distribution.
|
||||
|
||||
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 context files.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
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 context file contribution makes the framework better for everyone.
|
||||
|
||||
Your expertise and perspective make SuperClaude Framework better. Whether you're improving context files, adding features, or helping other users, every contribution advances the goal of more effective AI-assisted development.
|
||||
|
||||
---
|
||||
|
||||
**Welcome to the SuperClaude Framework contributor community!** Your contributions help build the future of AI-assisted development through intelligent context and behavioral programming.
|
||||
@@ -1,227 +0,0 @@
|
||||
# SuperClaude Framework Developer-Guide Index
|
||||
|
||||
## Document Navigation Guide
|
||||
|
||||
This index provides comprehensive access to all SuperClaude Framework development documentation, organized by topic and skill level for efficient information discovery.
|
||||
|
||||
### Quick Navigation
|
||||
|
||||
**For New Contributors**: Start with [Contributing Guide → Setup](contributing-code.md#development-setup)
|
||||
|
||||
**For System Understanding**: Begin with [Technical Architecture Guide → Context Architecture](technical-architecture.md#context-file-architecture)
|
||||
|
||||
**For Verification**: Start with [Verification Guide → Installation Check](testing-debugging.md#installation-verification)
|
||||
|
||||
---
|
||||
|
||||
## Primary Documentation
|
||||
|
||||
### 📋 [Contributing Context Files Guide](contributing-code.md)
|
||||
**Purpose**: Complete context file development and contribution guidelines
|
||||
**Target Audience**: Framework contributors and context file developers
|
||||
**Length**: ~1,000 lines focused on context file reality
|
||||
|
||||
**Key Sections**:
|
||||
- [Development Setup](contributing-code.md#development-setup) - Environment configuration and prerequisites
|
||||
- [Context File Guidelines](contributing-code.md#context-file-guidelines) - Standards and structure
|
||||
- [Development Workflow](contributing-code.md#development-workflow) - Git workflow and submission process
|
||||
- [Contributing to Components](contributing-code.md#contributing-to-components) - Agent, command, and mode development
|
||||
- [File Validation](contributing-code.md#file-validation) - Context file verification methods
|
||||
|
||||
### 🏗️ [Context Architecture Guide](technical-architecture.md)
|
||||
**Purpose**: Understanding how context files work and are structured
|
||||
**Target Audience**: Anyone wanting to understand or extend SuperClaude
|
||||
**Length**: ~800 lines focused on context file patterns and Claude Code integration
|
||||
|
||||
**Key Sections**:
|
||||
- [Context File Architecture](technical-architecture.md#context-file-architecture) - Directory structure and file types
|
||||
- [The Import System](technical-architecture.md#the-import-system) - How Claude Code loads context
|
||||
- [Agent Context Structure](technical-architecture.md#agent-context-structure) - Domain specialist contexts
|
||||
- [Command Context Structure](technical-architecture.md#command-context-structure) - Workflow patterns
|
||||
- [How Claude Code Reads Context](technical-architecture.md#how-claude-code-reads-context) - Processing sequence
|
||||
- [Extending the Framework](technical-architecture.md#extending-the-framework) - Adding new components
|
||||
|
||||
### 🧪 [Verification & Troubleshooting Guide](testing-debugging.md)
|
||||
**Purpose**: Verifying installation and troubleshooting context file issues
|
||||
**Target Audience**: Users and maintainers
|
||||
**Length**: ~500 lines focused on file verification and Claude Code integration
|
||||
|
||||
**Key Sections**:
|
||||
- [Installation Verification](testing-debugging.md#installation-verification) - Check context file installation
|
||||
- [Context File Verification](testing-debugging.md#context-file-verification) - File structure validation
|
||||
- [MCP Server Verification](testing-debugging.md#mcp-server-verification) - External tool configuration
|
||||
- [Common Issues](testing-debugging.md#common-issues) - Troubleshooting activation problems
|
||||
- [Troubleshooting Commands](testing-debugging.md#troubleshooting-commands) - Diagnostic procedures
|
||||
|
||||
---
|
||||
|
||||
## Topic-Based Index
|
||||
|
||||
### 🚀 Getting Started
|
||||
|
||||
**Complete Beginners**:
|
||||
1. [Contributing Guide → Setup](contributing-code.md#development-setup) - Environment setup
|
||||
2. [Architecture Guide → Overview](technical-architecture.md#overview) - Understanding context files
|
||||
3. [Verification Guide → Installation Check](testing-debugging.md#installation-verification) - Basic verification
|
||||
|
||||
**Environment Setup**:
|
||||
- [Development Setup](contributing-code.md#development-setup) - Prerequisites and configuration
|
||||
- [Installation Verification](testing-debugging.md#installation-verification) - File installation check
|
||||
|
||||
### 🏗️ Architecture & Design
|
||||
|
||||
**Context File Architecture**:
|
||||
- [Context File Architecture](technical-architecture.md#context-file-architecture) - Complete system design
|
||||
- [The Import System](technical-architecture.md#the-import-system) - How Claude Code loads context
|
||||
- [Agent Context Structure](technical-architecture.md#agent-context-structure) - Domain specialist patterns
|
||||
- [Command Context Structure](technical-architecture.md#command-context-structure) - Workflow definitions
|
||||
|
||||
**Component Development**:
|
||||
- [Contributing to Components](contributing-code.md#contributing-to-components) - Agent, command, mode development
|
||||
- [Adding New Agents](contributing-code.md#adding-new-agents) - Domain specialist creation
|
||||
- [Adding New Commands](contributing-code.md#adding-new-commands) - Workflow pattern development
|
||||
- [Extending the Framework](technical-architecture.md#extending-the-framework) - Framework expansion
|
||||
|
||||
### 🧪 Verification & Quality
|
||||
|
||||
**File Verification**:
|
||||
- [Context File Verification](testing-debugging.md#context-file-verification) - File structure validation
|
||||
- [File Validation](contributing-code.md#file-validation) - Context file verification methods
|
||||
|
||||
**Troubleshooting**:
|
||||
- [Common Issues](testing-debugging.md#common-issues) - Activation and configuration problems
|
||||
- [Troubleshooting Commands](testing-debugging.md#troubleshooting-commands) - Diagnostic procedures
|
||||
|
||||
### 🔧 Development Workflows
|
||||
|
||||
**Context File Development**:
|
||||
- [Development Workflow](contributing-code.md#development-workflow) - Git workflow
|
||||
- [Context File Guidelines](contributing-code.md#context-file-guidelines) - Standards and practices
|
||||
- [Pull Request Process](contributing-code.md#pull-request-template) - Submission process
|
||||
|
||||
**Component Development**:
|
||||
- [Agent Development](contributing-code.md#adding-new-agents) - Domain specialist creation
|
||||
- [Command Development](contributing-code.md#adding-new-commands) - Workflow pattern creation
|
||||
- [Mode Development](contributing-code.md#adding-new-modes) - Behavioral modification patterns
|
||||
|
||||
### 🛠️ MCP Integration
|
||||
|
||||
**MCP Configuration**:
|
||||
- [MCP Server Configuration](technical-architecture.md#mcp-server-configuration) - External tool setup
|
||||
- [MCP Server Verification](testing-debugging.md#mcp-server-verification) - Configuration validation
|
||||
|
||||
### 🚨 Support & Troubleshooting
|
||||
|
||||
**Common Issues**:
|
||||
- [Commands Not Working](testing-debugging.md#issue-commands-not-working) - Context trigger problems
|
||||
- [Agents Not Activating](testing-debugging.md#issue-agents-not-activating) - Activation issues
|
||||
- [Context Not Loading](testing-debugging.md#issue-context-not-loading) - Loading problems
|
||||
|
||||
**Support Resources**:
|
||||
- [Getting Help](contributing-code.md#getting-help) - Support channels
|
||||
- [Issue Reporting](contributing-code.md#issue-reporting) - Bug reports and features
|
||||
|
||||
---
|
||||
|
||||
## Skill Level Pathways
|
||||
|
||||
### 🟢 Beginner Path (Understanding SuperClaude)
|
||||
|
||||
**Week 1: Foundation**
|
||||
1. [Architecture Overview](technical-architecture.md#overview) - What SuperClaude is
|
||||
2. [Installation Verification](testing-debugging.md#installation-verification) - Check your setup
|
||||
3. [Context File Architecture](technical-architecture.md#context-file-architecture) - Directory structure
|
||||
|
||||
**Week 2: Basic Usage**
|
||||
1. [How Claude Code Reads Context](technical-architecture.md#how-claude-code-reads-context) - Processing sequence
|
||||
2. [Common Issues](testing-debugging.md#common-issues) - Troubleshooting basics
|
||||
3. [Context File Guidelines](contributing-code.md#context-file-guidelines) - File standards
|
||||
|
||||
### 🟡 Intermediate Path (Contributing Context Files)
|
||||
|
||||
**Month 1: Context Development**
|
||||
1. [Development Setup](contributing-code.md#development-setup) - Environment preparation
|
||||
2. [Agent Context Structure](technical-architecture.md#agent-context-structure) - Domain specialists
|
||||
3. [Command Context Structure](technical-architecture.md#command-context-structure) - Workflow patterns
|
||||
|
||||
**Month 2: Component Creation**
|
||||
1. [Adding New Agents](contributing-code.md#adding-new-agents) - Domain specialist development
|
||||
2. [Adding New Commands](contributing-code.md#adding-new-commands) - Workflow creation
|
||||
3. [File Validation](contributing-code.md#file-validation) - Context verification
|
||||
|
||||
### 🔴 Advanced Path (Framework Extension)
|
||||
|
||||
**Advanced Understanding**
|
||||
1. [The Import System](technical-architecture.md#the-import-system) - Context loading mechanics
|
||||
2. [Extending the Framework](technical-architecture.md#extending-the-framework) - Framework expansion
|
||||
3. [MCP Server Configuration](technical-architecture.md#mcp-server-configuration) - External tool integration
|
||||
|
||||
---
|
||||
|
||||
## Reference Materials
|
||||
|
||||
### 📚 Key Concepts
|
||||
|
||||
**Framework Fundamentals**:
|
||||
- Context-Oriented Configuration Framework
|
||||
- Agent Domain Specialists
|
||||
- Command Workflow Patterns
|
||||
- Mode Behavioral Modifications
|
||||
- MCP Integration Patterns
|
||||
|
||||
### 🔗 Cross-References
|
||||
|
||||
**Development → Architecture**:
|
||||
- [Context File Guidelines](contributing-code.md#context-file-guidelines) → [Context File Architecture](technical-architecture.md#context-file-architecture)
|
||||
- [Adding Components](contributing-code.md#contributing-to-components) → [Agent/Command Structure](technical-architecture.md#agent-context-structure)
|
||||
|
||||
**Development → Verification**:
|
||||
- [Development Workflow](contributing-code.md#development-workflow) → [File Verification](testing-debugging.md#context-file-verification)
|
||||
- [File Validation](contributing-code.md#file-validation) → [Installation Verification](testing-debugging.md#installation-verification)
|
||||
|
||||
**Architecture → Verification**:
|
||||
- [How Claude Code Reads Context](technical-architecture.md#how-claude-code-reads-context) → [Troubleshooting](testing-debugging.md#common-issues)
|
||||
- [MCP Configuration](technical-architecture.md#mcp-server-configuration) → [MCP Verification](testing-debugging.md#mcp-server-verification)
|
||||
|
||||
---
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### ✅ Documentation Accuracy
|
||||
- **Technical Precision**: All examples reflect SuperClaude reality (context files, not software)
|
||||
- **Command Accuracy**: Correct Python module execution paths and Claude Code context triggers
|
||||
- **No Fiction**: Removed all references to non-existent testing frameworks and performance systems
|
||||
|
||||
### ✅ Content Focus
|
||||
- **Context Files**: Documentation centers on .md instruction files and Claude Code behavior
|
||||
- **File Verification**: Practical approaches to validating context file installation and structure
|
||||
- **Real Workflows**: Actual development processes for context file contribution
|
||||
|
||||
### ✅ User Experience
|
||||
- **Clear Progression**: Skill-based learning paths from understanding to contribution
|
||||
- **Practical Examples**: Working context file examples and Claude Code integration
|
||||
- **Support Integration**: Clear guidance to help resources for real issues
|
||||
|
||||
---
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
### For Contributors
|
||||
1. **Start with**: [Development Setup](contributing-code.md#development-setup)
|
||||
2. **Context Development**: Follow [Context File Guidelines](contributing-code.md#context-file-guidelines)
|
||||
3. **Validation**: Use [File Validation](contributing-code.md#file-validation)
|
||||
4. **Support**: Reference [Getting Help](contributing-code.md#getting-help)
|
||||
|
||||
### For Architects
|
||||
1. **System Understanding**: [Context File Architecture](technical-architecture.md#context-file-architecture)
|
||||
2. **Component Patterns**: [Agent and Command Structure](technical-architecture.md#agent-context-structure)
|
||||
3. **Extension**: [Extending the Framework](technical-architecture.md#extending-the-framework)
|
||||
4. **Integration**: [MCP Configuration](technical-architecture.md#mcp-server-configuration)
|
||||
|
||||
### For Verification
|
||||
1. **Installation Check**: [Installation Verification](testing-debugging.md#installation-verification)
|
||||
2. **File Validation**: [Context File Verification](testing-debugging.md#context-file-verification)
|
||||
3. **Troubleshooting**: [Common Issues](testing-debugging.md#common-issues)
|
||||
4. **Diagnostics**: [Troubleshooting Commands](testing-debugging.md#troubleshooting-commands)
|
||||
|
||||
This comprehensive index reflects the reality of SuperClaude as a context-oriented configuration framework, focusing on practical context file development and Claude Code integration.
|
||||
@@ -1,356 +0,0 @@
|
||||
# SuperClaude Context Architecture Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide documents how SuperClaude's Context-Oriented Configuration Framework is structured and how Claude Code interprets these context files to modify its behavior.
|
||||
|
||||
**Important**: SuperClaude is NOT standalone software with running processes, execution layers, or performance systems. It is a collection of `.md` instruction files that Claude Code reads to adopt specialized behaviors.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Context File Architecture](#context-file-architecture)
|
||||
2. [The Import System](#the-import-system)
|
||||
3. [Agent Context Structure](#agent-context-structure)
|
||||
4. [Command Context Structure](#command-context-structure)
|
||||
5. [Mode Context Structure](#mode-context-structure)
|
||||
6. [MCP Server Configuration](#mcp-server-configuration)
|
||||
7. [How Claude Code Reads Context](#how-claude-code-reads-context)
|
||||
8. [Extending the Framework](#extending-the-framework)
|
||||
|
||||
## Context File Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/.claude/ (SuperClaude Framework Files Only)
|
||||
├── CLAUDE.md # Main context file with imports
|
||||
├── FLAGS.md # Flag definitions and triggers
|
||||
├── RULES.md # Core behavioral rules
|
||||
├── PRINCIPLES.md # Guiding principles
|
||||
├── ZIG.md # Zig language integration
|
||||
├── MCP_Context7.md # Context7 MCP integration
|
||||
├── MCP_Magic.md # Magic MCP integration
|
||||
├── MCP_Morphllm.md # Morphllm MCP integration
|
||||
├── MCP_Playwright.md # Playwright MCP integration
|
||||
├── MCP_Sequential.md # Sequential MCP integration
|
||||
├── MCP_Serena.md # Serena MCP integration
|
||||
├── MCP_Tavily.md # Tavily MCP integration
|
||||
├── MCP_Zig.md # Zig MCP integration
|
||||
├── MODE_Brainstorming.md # Collaborative discovery mode
|
||||
├── MODE_Business_Panel.md # Business expert panel mode
|
||||
├── MODE_DeepResearch.md # Deep research mode
|
||||
├── MODE_Introspection.md # Transparent reasoning mode
|
||||
├── MODE_Orchestration.md # Tool coordination mode
|
||||
├── MODE_Task_Management.md # Task orchestration mode
|
||||
├── MODE_Token_Efficiency.md # Compressed communication mode
|
||||
├── agents/ # Domain specialist contexts (19 total)
|
||||
│ ├── backend-architect.md # Backend expertise
|
||||
│ ├── business-panel-experts.md # Business strategy panel
|
||||
│ ├── deep-research-agent.md # Deep research expertise
|
||||
│ ├── devops-architect.md # DevOps expertise
|
||||
│ ├── frontend-architect.md # Frontend expertise
|
||||
│ ├── learning-guide.md # Educational expertise
|
||||
│ ├── performance-engineer.md # Performance expertise
|
||||
│ ├── python-expert.md # Python expertise
|
||||
│ ├── quality-engineer.md # Quality assurance expertise
|
||||
│ ├── refactoring-expert.md # Code quality expertise
|
||||
│ ├── requirements-analyst.md # Requirements expertise
|
||||
│ ├── root-cause-analyst.md # Problem diagnosis expertise
|
||||
│ ├── security-engineer.md # Security expertise
|
||||
│ ├── socratic-mentor.md # Educational expertise
|
||||
│ ├── spec-panel-experts.md # Specification review panel
|
||||
│ ├── system-architect.md # System design expertise
|
||||
│ ├── technical-writer.md # Documentation expertise
|
||||
│ ├── test-runner.md # Test execution expertise
|
||||
│ └── wave-orchestrator.md # Wave orchestration patterns
|
||||
└── commands/ # Workflow pattern contexts
|
||||
└── sc/ # SuperClaude command namespace (25 total)
|
||||
├── analyze.md # Analysis patterns
|
||||
├── brainstorm.md # Discovery patterns
|
||||
├── build.md # Build patterns
|
||||
├── business-panel.md # Business expert panel patterns
|
||||
├── cleanup.md # Cleanup patterns
|
||||
├── design.md # Design patterns
|
||||
├── document.md # Documentation patterns
|
||||
├── estimate.md # Estimation patterns
|
||||
├── explain.md # Explanation patterns
|
||||
├── git.md # Git workflow patterns
|
||||
├── help.md # Help and command listing
|
||||
├── implement.md # Implementation patterns
|
||||
├── improve.md # Improvement patterns
|
||||
├── index.md # Index patterns
|
||||
├── load.md # Context loading patterns
|
||||
├── reflect.md # Reflection patterns
|
||||
├── research.md # Deep research patterns
|
||||
├── save.md # Session persistence patterns
|
||||
├── select-tool.md # Tool selection patterns
|
||||
├── spawn.md # Multi-agent patterns
|
||||
├── spec-panel.md # Specification review panel
|
||||
├── task.md # Task management patterns
|
||||
├── test.md # Testing patterns
|
||||
├── troubleshoot.md # Troubleshooting patterns
|
||||
└── workflow.md # Workflow planning patterns
|
||||
|
||||
Note: Other directories (backups/, logs/, projects/, serena/, etc.) are Claude Code
|
||||
operational directories, not part of SuperClaude framework content.
|
||||
```
|
||||
|
||||
### Context File Types
|
||||
|
||||
| File Type | Purpose | Activation | Example |
|
||||
|-----------|---------|------------|---------|
|
||||
| **Commands** | Define workflow patterns | `/sc:[command]` (context trigger) | User types `/sc:implement` → reads `implement.md` |
|
||||
| **Agents** | Provide domain expertise | `@agent-[name]` or auto | `@agent-security` → reads `security-engineer.md` |
|
||||
| **Modes** | Modify interaction style | Flags or triggers | `--brainstorm` → activates brainstorming mode |
|
||||
| **Core** | Set fundamental rules | Always active | `RULES.md` always loaded |
|
||||
|
||||
## The Import System
|
||||
|
||||
### How CLAUDE.md Works
|
||||
|
||||
The main `CLAUDE.md` file uses an import system to load multiple context files:
|
||||
|
||||
```markdown
|
||||
# CLAUDE
|
||||
|
||||
*MANDATORY*
|
||||
@FLAGS.md # Flag definitions and triggers
|
||||
@RULES.md # Core behavioral rules
|
||||
@PRINCIPLES.md # Guiding principles
|
||||
*SECONDARY*
|
||||
@MCP_Context7.md # Context7 MCP integration
|
||||
@MCP_Magic.md # Magic MCP integration
|
||||
@MCP_Morphllm.md # Morphllm MCP integration
|
||||
@MCP_Playwright.md # Playwright MCP integration
|
||||
@MCP_Sequential.md # Sequential MCP integration
|
||||
@MCP_Serena.md # Serena MCP integration
|
||||
@MCP_Tavily.md # Tavily MCP integration
|
||||
@MCP_Zig.md # Zig MCP integration
|
||||
*CRITICAL*
|
||||
@MODE_Brainstorming.md # Collaborative discovery mode
|
||||
@MODE_Business_Panel.md # Business expert panel mode
|
||||
@MODE_DeepResearch.md # Deep research mode
|
||||
@MODE_Introspection.md # Transparent reasoning mode
|
||||
@MODE_Task_Management.md # Task orchestration mode
|
||||
@MODE_Orchestration.md # Tool coordination mode
|
||||
@MODE_Token_Efficiency.md # Compressed communication mode
|
||||
*LANGUAGE SPECIFIC*
|
||||
@ZIG.md # Zig language integration
|
||||
```
|
||||
|
||||
### Import Processing
|
||||
|
||||
1. Claude Code reads `CLAUDE.md`
|
||||
2. Encounters `@import` statements
|
||||
3. Loads referenced files into context
|
||||
4. Builds complete behavioral framework
|
||||
5. Applies relevant contexts based on user input
|
||||
|
||||
## Agent Context Structure
|
||||
|
||||
### Anatomy of an Agent File
|
||||
|
||||
Each agent `.md` file follows this structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: agent-name
|
||||
description: Brief description
|
||||
category: specialized|architecture|quality
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
## Triggers
|
||||
- Keywords that activate this agent
|
||||
- File types that trigger activation
|
||||
- Complexity thresholds
|
||||
|
||||
## Behavioral Mindset
|
||||
Core philosophy and approach
|
||||
|
||||
## Focus Areas
|
||||
- Domain expertise area 1
|
||||
- Domain expertise area 2
|
||||
|
||||
## Key Actions
|
||||
1. Specific behavior pattern
|
||||
2. Problem-solving approach
|
||||
```
|
||||
|
||||
### Agent Activation Logic
|
||||
|
||||
- **Manual**: User types `@agent-python-expert "task"`
|
||||
- **Automatic**: Keywords in request trigger agent loading
|
||||
- **Contextual**: File types or patterns activate relevant agents
|
||||
|
||||
## Command Context Structure
|
||||
|
||||
### Anatomy of a Command File
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: command-name
|
||||
description: Command purpose
|
||||
category: utility|orchestration|analysis
|
||||
complexity: basic|enhanced|advanced
|
||||
mcp-servers: [context7, sequential]
|
||||
personas: [architect, engineer]
|
||||
---
|
||||
|
||||
# /sc:command-name
|
||||
|
||||
## Triggers
|
||||
- When to use this command
|
||||
- Context indicators
|
||||
|
||||
## Usage
|
||||
/sc:command-name [target] [--options]
|
||||
|
||||
## Workflow Pattern
|
||||
1. Step 1: Initial action
|
||||
2. Step 2: Processing
|
||||
3. Step 3: Validation
|
||||
|
||||
## Examples
|
||||
Practical usage examples
|
||||
```
|
||||
|
||||
### Command Processing
|
||||
|
||||
When user types `/sc:implement "feature"` in Claude Code conversation:
|
||||
1. Claude reads `commands/sc/implement.md`
|
||||
2. Adopts implementation workflow pattern
|
||||
3. May auto-activate related agents
|
||||
4. Follows defined workflow steps
|
||||
|
||||
## Mode Context Structure
|
||||
|
||||
### Behavioral Modes
|
||||
|
||||
Modes modify Claude's interaction style:
|
||||
|
||||
```markdown
|
||||
# MODE_[Name].md
|
||||
|
||||
## Activation Triggers
|
||||
- Flag: --mode-name
|
||||
- Keywords: [triggers]
|
||||
- Complexity: threshold
|
||||
|
||||
## Behavioral Modifications
|
||||
- Communication style changes
|
||||
- Decision-making adjustments
|
||||
- Output format modifications
|
||||
|
||||
## Interaction Patterns
|
||||
- How to respond
|
||||
- What to prioritize
|
||||
```
|
||||
|
||||
## MCP Server Configuration
|
||||
|
||||
### Configuration Location
|
||||
|
||||
MCP servers are configured in `~/.claude.json` (NOT part of SuperClaude context):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"context7": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@upstash/context7-mcp@latest"]
|
||||
},
|
||||
"sequential-thinking": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "sequential-thinking-mcp@latest"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Integration
|
||||
|
||||
- **MCP Servers**: Actual software providing tools
|
||||
- **SuperClaude**: Context that tells Claude when to use them
|
||||
- **Activation**: Flags or keywords trigger MCP usage
|
||||
|
||||
## How Claude Code Reads Context
|
||||
|
||||
### Context Loading Sequence
|
||||
|
||||
```
|
||||
User Input (in Claude Code): "/sc:analyze src/ --focus security"
|
||||
↓
|
||||
1. Parse Command: identify 'analyze' command
|
||||
↓
|
||||
2. Load Context: read commands/sc/analyze.md
|
||||
↓
|
||||
3. Check Flags: --focus security
|
||||
↓
|
||||
4. Auto-Activation: load security-engineer.md
|
||||
↓
|
||||
5. Apply Patterns: follow analysis workflow
|
||||
↓
|
||||
6. Generate Output: using loaded contexts
|
||||
```
|
||||
|
||||
### Context Priority
|
||||
|
||||
1. **Explicit Commands**: `/sc:` commands take precedence
|
||||
2. **Manual Agents**: `@agent-` override auto-activation
|
||||
3. **Flags**: Modify behavior of commands/agents
|
||||
4. **Auto-Activation**: Based on keywords/context
|
||||
5. **Default Behavior**: Standard Claude Code
|
||||
|
||||
## Extending the Framework
|
||||
|
||||
### Adding New Commands
|
||||
|
||||
1. Create `~/.claude/commands/sc/new-command.md`
|
||||
2. Define metadata, triggers, and workflow
|
||||
3. No code changes needed - just context
|
||||
|
||||
### Adding New Agents
|
||||
|
||||
1. Create `~/.claude/agents/new-specialist.md`
|
||||
2. Define expertise, triggers, and behaviors
|
||||
3. Agent becomes available
|
||||
|
||||
### Adding New Modes
|
||||
|
||||
1. Create `~/.claude/MODE_NewMode.md`
|
||||
2. Define activation triggers and modifications
|
||||
3. Mode activates based on triggers
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Keep Context Focused**: One concept per file
|
||||
- **Clear Triggers**: Define when context activates
|
||||
- **Workflow Patterns**: Provide step-by-step guidance
|
||||
- **Examples**: Include practical usage examples
|
||||
- **Metadata**: Use frontmatter for configuration
|
||||
|
||||
## Important Clarifications
|
||||
|
||||
### What SuperClaude Is NOT
|
||||
|
||||
- ❌ **No Execution Engine**: No code runs, no processes execute
|
||||
- ❌ **No Performance System**: No optimization possible (it's just text)
|
||||
- ❌ **No Detection Engine**: Claude Code does pattern matching
|
||||
- ❌ **No Orchestration Layer**: Context files guide, not control
|
||||
- ❌ **No Quality Gates**: Just instructional patterns
|
||||
|
||||
### What SuperClaude IS
|
||||
|
||||
- ✅ **Context Files**: `.md` instructions for Claude Code
|
||||
- ✅ **Behavioral Patterns**: Workflows and approaches
|
||||
- ✅ **Domain Expertise**: Specialized knowledge contexts
|
||||
- ✅ **Configuration**: Settings for actual tools (MCP)
|
||||
- ✅ **Framework**: Structured prompt engineering
|
||||
|
||||
## Summary
|
||||
|
||||
SuperClaude's architecture is intentionally simple: it's a well-organized collection of context files that Claude Code reads to modify its behavior. The power comes from the careful crafting of these contexts and their systematic organization, not from any executing code or running processes.
|
||||
|
||||
The framework's elegance lies in its simplicity - by providing Claude Code with structured instructions through context files, we can achieve sophisticated behavioral modifications without any software complexity.
|
||||
@@ -1,324 +0,0 @@
|
||||
# SuperClaude Verification and Troubleshooting Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers how to verify your SuperClaude installation and troubleshoot common issues with context files and configurations.
|
||||
|
||||
**Important**: SuperClaude is a collection of context files, not executable software. This guide focuses on verifying context files are properly installed and accessible to Claude Code.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Installation Verification](#installation-verification)
|
||||
2. [Context File Verification](#context-file-verification)
|
||||
3. [MCP Server Verification](#mcp-server-verification)
|
||||
4. [Common Issues](#common-issues)
|
||||
5. [Troubleshooting Commands](#troubleshooting-commands)
|
||||
|
||||
## Installation Verification
|
||||
|
||||
### Check Installation Status
|
||||
|
||||
```bash
|
||||
# Verify SuperClaude installation system is available
|
||||
python3 -m SuperClaude --version
|
||||
# Expected: SuperClaude Framework installation help
|
||||
|
||||
# Verify Claude Code CLI integration
|
||||
claude --version
|
||||
# Expected: Claude Code version info
|
||||
|
||||
# Check if context files were installed
|
||||
ls ~/.claude/
|
||||
# Expected: CLAUDE.md, FLAGS.md, RULES.md, agents/, commands/, modes/
|
||||
|
||||
# Verify main context file
|
||||
head ~/.claude/CLAUDE.md
|
||||
# Expected: Should show import statements
|
||||
```
|
||||
|
||||
### Verify Directory Structure
|
||||
|
||||
```bash
|
||||
# Check all directories exist
|
||||
for dir in agents commands modes; do
|
||||
if [ -d ~/.claude/$dir ]; then
|
||||
echo "✅ $dir directory exists"
|
||||
ls ~/.claude/$dir | wc -l
|
||||
else
|
||||
echo "❌ $dir directory missing"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Count Installed Components
|
||||
|
||||
```bash
|
||||
# Should have 14 agents
|
||||
ls ~/.claude/agents/*.md | wc -l
|
||||
|
||||
# Should have 21 commands
|
||||
ls ~/.claude/commands/*.md | wc -l
|
||||
|
||||
# Should have 5 modes
|
||||
ls ~/.claude/modes/*.md | wc -l
|
||||
```
|
||||
|
||||
## Context File Verification
|
||||
|
||||
### Verify Core Files
|
||||
|
||||
```bash
|
||||
# Check core context files exist
|
||||
for file in CLAUDE.md FLAGS.md RULES.md PRINCIPLES.md; do
|
||||
if [ -f ~/.claude/$file ]; then
|
||||
echo "✅ $file exists ($(wc -l < ~/.claude/$file) lines)"
|
||||
else
|
||||
echo "❌ $file missing"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Verify Import System
|
||||
|
||||
```bash
|
||||
# Check CLAUDE.md has correct imports
|
||||
grep "@import" ~/.claude/CLAUDE.md
|
||||
# Expected output:
|
||||
# @import commands/*.md
|
||||
# @import agents/*.md
|
||||
# @import modes/*.md
|
||||
# @import FLAGS.md
|
||||
# @import RULES.md
|
||||
# @import PRINCIPLES.md
|
||||
```
|
||||
|
||||
### Check File Integrity
|
||||
|
||||
```bash
|
||||
# Verify files are readable text files
|
||||
file ~/.claude/CLAUDE.md
|
||||
# Expected: ASCII text or UTF-8 text
|
||||
|
||||
# Check for corruption
|
||||
for file in ~/.claude/**/*.md; do
|
||||
if file "$file" | grep -q "text"; then
|
||||
echo "✅ $file is valid text"
|
||||
else
|
||||
echo "❌ $file may be corrupted"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## MCP Server Verification
|
||||
|
||||
### Check MCP Configuration
|
||||
|
||||
```bash
|
||||
# Verify .claude.json exists
|
||||
if [ -f ~/.claude.json ]; then
|
||||
echo "✅ MCP configuration file exists"
|
||||
# Check which servers are configured
|
||||
grep -o '"[^"]*":' ~/.claude.json | grep -v mcpServers
|
||||
else
|
||||
echo "❌ No MCP configuration found"
|
||||
fi
|
||||
```
|
||||
|
||||
### Test MCP Server Availability
|
||||
|
||||
```bash
|
||||
# Check if Node.js is available (required for MCP)
|
||||
node --version
|
||||
# Expected: v16.0.0 or higher
|
||||
|
||||
# Check if npx is available
|
||||
npx --version
|
||||
# Expected: Version number
|
||||
|
||||
# Test Context7 MCP (if configured)
|
||||
npx -y @upstash/context7-mcp@latest --help 2>/dev/null && echo "✅ Context7 available" || echo "❌ Context7 not available"
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Commands Not Working
|
||||
|
||||
**Symptom**: `/sc:` context triggers don't produce expected Claude Code behavior
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
# Check if command file exists
|
||||
ls ~/.claude/commands/implement.md
|
||||
# If missing, reinstall SuperClaude
|
||||
|
||||
# Verify file content
|
||||
head -20 ~/.claude/commands/implement.md
|
||||
# Should show command metadata and instructions
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Reinstall commands component
|
||||
PYTHONPATH=/path/to/SuperClaude_Framework python3 -m setup install --components commands --force
|
||||
```
|
||||
|
||||
### Issue: Agents Not Activating
|
||||
|
||||
**Symptom**: `@agent-` invocations don't work in Claude Code
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
# List all agents
|
||||
ls ~/.claude/agents/
|
||||
|
||||
# Check specific agent
|
||||
cat ~/.claude/agents/python-expert.md | head -20
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Reinstall agents
|
||||
PYTHONPATH=/path/to/SuperClaude_Framework python3 -m setup install --components agents --force
|
||||
```
|
||||
|
||||
### Issue: Context Not Loading
|
||||
|
||||
**Symptom**: Claude Code doesn't seem to read SuperClaude context
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
# Check CLAUDE.md is in correct location
|
||||
ls -la ~/.claude/CLAUDE.md
|
||||
|
||||
# Verify Claude Code can access the directory
|
||||
# In Claude Code, check if context is loading properly
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
1. Restart Claude Code
|
||||
2. Ensure you're in a project directory
|
||||
3. Check file permissions: `chmod 644 ~/.claude/*.md`
|
||||
|
||||
### Issue: MCP Servers Not Working
|
||||
|
||||
**Symptom**: MCP features unavailable
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
# Check Node.js installation
|
||||
which node
|
||||
|
||||
# Verify .claude.json syntax
|
||||
python3 -c "import json; json.load(open('$HOME/.claude.json'))" && echo "✅ Valid JSON" || echo "❌ Invalid JSON"
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Install Node.js if missing
|
||||
# Ubuntu: sudo apt install nodejs npm
|
||||
# macOS: brew install node
|
||||
# Windows: Download from nodejs.org
|
||||
|
||||
# Fix JSON syntax if invalid
|
||||
PYTHONPATH=/path/to/SuperClaude_Framework python3 -m setup install --components mcp --force
|
||||
```
|
||||
|
||||
## Troubleshooting Commands
|
||||
|
||||
### Quick Diagnostic
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# SuperClaude Quick Diagnostic Script
|
||||
|
||||
echo "=== SuperClaude Diagnostic ==="
|
||||
echo ""
|
||||
|
||||
# Check installation system
|
||||
echo "1. Installation System:"
|
||||
if command -v SuperClaude &> /dev/null; then
|
||||
echo " ✅ SuperClaude installation available"
|
||||
python3 -m SuperClaude --version
|
||||
else
|
||||
echo " ❌ SuperClaude not found - install with: pipx install SuperClaude (or pip install SuperClaude)"
|
||||
fi
|
||||
|
||||
# Check context files
|
||||
echo ""
|
||||
echo "2. Context Files:"
|
||||
if [ -d ~/.claude ]; then
|
||||
echo " ✅ ~/.claude directory exists"
|
||||
echo " - Agents: $(ls ~/.claude/agents/*.md 2>/dev/null | wc -l)"
|
||||
echo " - Commands: $(ls ~/.claude/commands/*.md 2>/dev/null | wc -l)"
|
||||
echo " - Modes: $(ls ~/.claude/modes/*.md 2>/dev/null | wc -l)"
|
||||
else
|
||||
echo " ❌ ~/.claude directory not found"
|
||||
fi
|
||||
|
||||
# Check MCP
|
||||
echo ""
|
||||
echo "3. MCP Configuration:"
|
||||
if [ -f ~/.claude.json ]; then
|
||||
echo " ✅ MCP configuration exists"
|
||||
else
|
||||
echo " ❌ No MCP configuration"
|
||||
fi
|
||||
|
||||
# Check Node.js
|
||||
echo ""
|
||||
echo "4. Node.js (for MCP):"
|
||||
if command -v node &> /dev/null; then
|
||||
echo " ✅ Node.js installed: $(node --version)"
|
||||
else
|
||||
echo " ⚠️ Node.js not installed (optional, needed for MCP)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Diagnostic Complete ==="
|
||||
```
|
||||
|
||||
### File Permission Fix
|
||||
|
||||
```bash
|
||||
# Fix permissions on all context files
|
||||
chmod 644 ~/.claude/*.md
|
||||
chmod 644 ~/.claude/**/*.md
|
||||
chmod 755 ~/.claude ~/.claude/agents ~/.claude/commands ~/.claude/modes
|
||||
```
|
||||
|
||||
### Complete Reinstall
|
||||
|
||||
```bash
|
||||
# Backup existing configuration
|
||||
cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)
|
||||
|
||||
# Remove existing installation
|
||||
rm -rf ~/.claude
|
||||
|
||||
# Reinstall everything
|
||||
PYTHONPATH=/path/to/SuperClaude_Framework python3 -m setup install
|
||||
|
||||
# Restore any customizations from backup if needed
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
### What We're NOT Verifying
|
||||
|
||||
- **No Code Execution**: Context files don't execute, so no runtime verification needed
|
||||
- **No Performance Metrics**: No code runs, so no performance to measure
|
||||
- **No Unit Tests**: Context files are instructions, not functions
|
||||
- **No Integration Tests**: Claude Code reads files; verification is behavioral
|
||||
|
||||
### What We ARE Verifying
|
||||
|
||||
- **File Presence**: Context files exist in correct locations
|
||||
- **File Integrity**: Files are valid text and readable
|
||||
- **Directory Structure**: Proper organization maintained
|
||||
- **Configuration Validity**: JSON files are syntactically correct
|
||||
- **Dependencies Available**: Node.js for MCP servers (optional)
|
||||
- **Behavioral Testing**: Context files produce expected Claude Code behavior
|
||||
|
||||
## Summary
|
||||
|
||||
Verification for SuperClaude focuses on ensuring context files are properly installed and accessible to Claude Code. Since SuperClaude is not software but a configuration framework, verification centers on file presence, integrity, and behavioral testing in Claude Code conversations.
|
||||
Reference in New Issue
Block a user