feat: restore complete SuperClaude framework from commit d4a17fc

Comprehensive restoration of all agents, modes, MCP integrations, and documentation. ## 🤖 Agents Restored (20 total) Added 17 new agent definitions to existing 3: - backend-architect, business-panel-experts, deep-research-agent - devops-architect, frontend-architect, learning-guide - performance-engineer, pm-agent, python-expert - quality-engineer, refactoring-expert, requirements-analyst - root-cause-analyst, security-engineer, socratic-mentor - system-architect, technical-writer ## 🎨 Behavioral Modes (7) - MODE_Brainstorming - Multi-perspective ideation - MODE_Business_Panel - Executive strategic analysis - MODE_DeepResearch - Autonomous research - MODE_Introspection - Meta-cognitive analysis - MODE_Orchestration - Tool coordination - MODE_Task_Management - Systematic organization - MODE_Token_Efficiency - Context optimization ## 🔌 MCP Server Integration (8) Documentation and configs for: - Tavily (web search) - Serena (session persistence) - Sequential (token-efficient reasoning) - Context7 (documentation lookup) - Playwright (browser automation) - Magic (UI components) - Morphllm (model transformation) - Chrome DevTools (performance) ## 📚 Core Documentation (6) - PRINCIPLES.md, RULES.md, FLAGS.md - RESEARCH_CONFIG.md - BUSINESS_PANEL_EXAMPLES.md, BUSINESS_SYMBOLS.md ## 📖 Documentation Restored (152 files) - User-Guide (en, jp, kr, zh) - 24 files - Developer-Guide - 5 files - Development docs - 10 files - Reference docs - 10 files - Getting-Started - 2 files - Plus examples and templates ## 📦 Package Configuration Updated pyproject.toml and MANIFEST.in to include: - modes/**/*.md - mcp/**/*.md, **/*.json - core/**/*.md - examples/**/*.md - Comprehensive docs in distribution ## 📁 Directory Structure plugins/superclaude/ and src/superclaude/: - agents/ (20 files) - modes/ (7 files) - mcp/ (8 docs + 8 configs) - core/ (6 files) - examples/ (workflow examples) docs/: - 152 markdown files - Multi-language support (en, jp, kr, zh) - Comprehensive guides and references ## 📊 Statistics - Commands: 30 - Agents: 20 - Modes: 7 - MCP Servers: 8 - Documentation Files: 152 - Total Resource Files: 200+ Created docs/reference/comprehensive-features.md with complete inventory. Source: commit d4a17fc Total changes: 150+ files added/modified 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-29 16:16:08 +00:00 · 2025-11-13 16:16:05 +01:00
parent ab8904bc8c
commit 3762d6ab24
158 changed files with 32205 additions and 19 deletions
--- a/src/superclaude/mcp/MCP_Chrome-DevTools.md
+++ b/src/superclaude/mcp/MCP_Chrome-DevTools.md
@@ -0,0 +1,32 @@
+# Chrome DevTools MCP Server
+
+**Purpose**: Performance analysis, debugging, and real-time browser inspection
+
+## Triggers
+- Performance auditing and analysis requests
+- Debugging of layout issues (e.g., CLS)
+- Investigation of slow loading times (e.g., LCP)
+- Analysis of console errors and network requests
+- Real-time inspection of the DOM and CSS
+
+## Choose When
+- **For deep performance analysis**: When you need to understand performance bottlenecks.
+- **For live debugging**: To inspect the runtime state of a web page and debug live issues.
+- **For network analysis**: To inspect network requests and identify issues like CORS errors.
+- **Not for E2E testing**: Use Playwright for end-to-end testing scenarios.
+- **Not for static analysis**: Use native Claude for code review and logic validation.
+
+## Works Best With
+- **Sequential**: Sequential plans a performance improvement strategy → Chrome DevTools analyzes and verifies the improvements.
+- **Playwright**: Playwright automates a user flow → Chrome DevTools analyzes the performance of that flow.
+
+## Examples
+```
+"analyze the performance of this page" → Chrome DevTools (performance analysis)
+"why is this page loading slowly?" → Chrome DevTools (performance analysis)
+"debug the layout shift on this element" → Chrome DevTools (live debugging)
+"check for console errors on the homepage" → Chrome DevTools (live debugging)
+"what network requests are failing?" → Chrome DevTools (network analysis)
+"test the login flow" → Playwright (browser automation)
+"review this function's logic" → Native Claude (static analysis)
+```
--- a/src/superclaude/mcp/MCP_Context7.md
+++ b/src/superclaude/mcp/MCP_Context7.md
@@ -0,0 +1,30 @@
+# Context7 MCP Server
+
+**Purpose**: Official library documentation lookup and framework pattern guidance
+
+## Triggers
+- Import statements: `import`, `require`, `from`, `use`
+- Framework keywords: React, Vue, Angular, Next.js, Express, etc.
+- Library-specific questions about APIs or best practices
+- Need for official documentation patterns vs generic solutions
+- Version-specific implementation requirements
+
+## Choose When
+- **Over WebSearch**: When you need curated, version-specific documentation
+- **Over native knowledge**: When implementation must follow official patterns
+- **For frameworks**: React hooks, Vue composition API, Angular services
+- **For libraries**: Correct API usage, authentication flows, configuration
+- **For compliance**: When adherence to official standards is mandatory
+
+## Works Best With
+- **Sequential**: Context7 provides docs → Sequential analyzes implementation strategy
+- **Magic**: Context7 supplies patterns → Magic generates framework-compliant components
+
+## Examples
+```
+"implement React useEffect" → Context7 (official React patterns)
+"add authentication with Auth0" → Context7 (official Auth0 docs)
+"migrate to Vue 3" → Context7 (official migration guide)
+"optimize Next.js performance" → Context7 (official optimization patterns)
+"just explain this function" → Native Claude (no external docs needed)
+```
--- a/src/superclaude/mcp/MCP_Magic.md
+++ b/src/superclaude/mcp/MCP_Magic.md
@@ -0,0 +1,31 @@
+# Magic MCP Server
+
+**Purpose**: Modern UI component generation from 21st.dev patterns with design system integration
+
+## Triggers
+- UI component requests: button, form, modal, card, table, nav
+- Design system implementation needs
+- `/ui` or `/21` commands
+- Frontend-specific keywords: responsive, accessible, interactive
+- Component enhancement or refinement requests
+
+## Choose When
+- **For UI components**: Use Magic, not native HTML/CSS generation
+- **Over manual coding**: When you need production-ready, accessible components
+- **For design systems**: When consistency with existing patterns matters
+- **For modern frameworks**: React, Vue, Angular with current best practices
+- **Not for backend**: API logic, database queries, server configuration
+
+## Works Best With
+- **Context7**: Magic uses 21st.dev patterns → Context7 provides framework integration
+- **Sequential**: Sequential analyzes UI requirements → Magic implements structured components
+
+## Examples
+```
+"create a login form" → Magic (UI component generation)
+"build a responsive navbar" → Magic (UI pattern with accessibility)
+"add a data table with sorting" → Magic (complex UI component)
+"make this component accessible" → Magic (UI enhancement)
+"write a REST API" → Native Claude (backend logic)
+"fix database query" → Native Claude (non-UI task)
+```
--- a/src/superclaude/mcp/MCP_Morphllm.md
+++ b/src/superclaude/mcp/MCP_Morphllm.md
@@ -0,0 +1,31 @@
+# Morphllm MCP Server
+
+**Purpose**: Pattern-based code editing engine with token optimization for bulk transformations
+
+## Triggers
+- Multi-file edit operations requiring consistent patterns
+- Framework updates, style guide enforcement, code cleanup
+- Bulk text replacements across multiple files
+- Natural language edit instructions with specific scope
+- Token optimization needed (efficiency gains 30-50%)
+
+## Choose When
+- **Over Serena**: For pattern-based edits, not symbol operations
+- **For bulk operations**: Style enforcement, framework updates, text replacements
+- **When token efficiency matters**: Fast Apply scenarios with compression needs
+- **For simple to moderate complexity**: <10 files, straightforward transformations
+- **Not for semantic operations**: Symbol renames, dependency tracking, LSP integration
+
+## Works Best With
+- **Serena**: Serena analyzes semantic context → Morphllm executes precise edits
+- **Sequential**: Sequential plans edit strategy → Morphllm applies systematic changes
+
+## Examples
+```
+"update all React class components to hooks" → Morphllm (pattern transformation)
+"enforce ESLint rules across project" → Morphllm (style guide application)
+"replace all console.log with logger calls" → Morphllm (bulk text replacement)
+"rename getUserData function everywhere" → Serena (symbol operation)
+"analyze code architecture" → Sequential (complex analysis)
+"explain this algorithm" → Native Claude (simple explanation)
+```
--- a/src/superclaude/mcp/MCP_Playwright.md
+++ b/src/superclaude/mcp/MCP_Playwright.md
@@ -0,0 +1,32 @@
+# Playwright MCP Server
+
+**Purpose**: Browser automation and E2E testing with real browser interaction
+
+## Triggers
+- Browser testing and E2E test scenarios
+- Visual testing, screenshot, or UI validation requests
+- Form submission and user interaction testing
+- Cross-browser compatibility validation
+- Performance testing requiring real browser rendering
+- Accessibility testing with automated WCAG compliance
+
+## Choose When
+- **For real browser interaction**: When you need actual rendering, not just code
+- **Over unit tests**: For integration testing, user journeys, visual validation
+- **For E2E scenarios**: Login flows, form submissions, multi-page workflows
+- **For visual testing**: Screenshot comparisons, responsive design validation
+- **Not for code analysis**: Static code review, syntax checking, logic validation
+
+## Works Best With
+- **Sequential**: Sequential plans test strategy → Playwright executes browser automation
+- **Magic**: Magic creates UI components → Playwright validates accessibility and behavior
+
+## Examples
+```
+"test the login flow" → Playwright (browser automation)
+"check if form validation works" → Playwright (real user interaction)
+"take screenshots of responsive design" → Playwright (visual testing)
+"validate accessibility compliance" → Playwright (automated WCAG testing)
+"review this function's logic" → Native Claude (static analysis)
+"explain the authentication code" → Native Claude (code review)
+```
--- a/src/superclaude/mcp/MCP_Sequential.md
+++ b/src/superclaude/mcp/MCP_Sequential.md
@@ -0,0 +1,33 @@
+# Sequential MCP Server
+
+**Purpose**: Multi-step reasoning engine for complex analysis and systematic problem solving
+
+## Triggers
+- Complex debugging scenarios with multiple layers
+- Architectural analysis and system design questions
+- `--think`, `--think-hard`, `--ultrathink` flags
+- Problems requiring hypothesis testing and validation
+- Multi-component failure investigation
+- Performance bottleneck identification requiring methodical approach
+
+## Choose When
+- **Over native reasoning**: When problems have 3+ interconnected components
+- **For systematic analysis**: Root cause analysis, architecture review, security assessment
+- **When structure matters**: Problems benefit from decomposition and evidence gathering
+- **For cross-domain issues**: Problems spanning frontend, backend, database, infrastructure
+- **Not for simple tasks**: Basic explanations, single-file changes, straightforward fixes
+
+## Works Best With
+- **Context7**: Sequential coordinates analysis → Context7 provides official patterns
+- **Magic**: Sequential analyzes UI logic → Magic implements structured components
+- **Playwright**: Sequential identifies testing strategy → Playwright executes validation
+
+## Examples
+```
+"why is this API slow?" → Sequential (systematic performance analysis)
+"design a microservices architecture" → Sequential (structured system design)
+"debug this authentication flow" → Sequential (multi-component investigation)
+"analyze security vulnerabilities" → Sequential (comprehensive threat modeling)
+"explain this function" → Native Claude (simple explanation)
+"fix this typo" → Native Claude (straightforward change)
+```
--- a/src/superclaude/mcp/MCP_Serena.md
+++ b/src/superclaude/mcp/MCP_Serena.md
@@ -0,0 +1,32 @@
+# Serena MCP Server
+
+**Purpose**: Semantic code understanding with project memory and session persistence
+
+## Triggers
+- Symbol operations: rename, extract, move functions/classes
+- Project-wide code navigation and exploration
+- Multi-language projects requiring LSP integration
+- Session lifecycle: `/sc:load`, `/sc:save`, project activation
+- Memory-driven development workflows
+- Large codebase analysis (>50 files, complex architecture)
+
+## Choose When
+- **Over Morphllm**: For symbol operations, not pattern-based edits
+- **For semantic understanding**: Symbol references, dependency tracking, LSP integration
+- **For session persistence**: Project context, memory management, cross-session learning
+- **For large projects**: Multi-language codebases requiring architectural understanding
+- **Not for simple edits**: Basic text replacements, style enforcement, bulk operations
+
+## Works Best With
+- **Morphllm**: Serena analyzes semantic context → Morphllm executes precise edits
+- **Sequential**: Serena provides project context → Sequential performs architectural analysis
+
+## Examples
+```
+"rename getUserData function everywhere" → Serena (symbol operation with dependency tracking)
+"find all references to this class" → Serena (semantic search and navigation)
+"load my project context" → Serena (/sc:load with project activation)
+"save my current work session" → Serena (/sc:save with memory persistence)
+"update all console.log to logger" → Morphllm (pattern-based replacement)
+"create a login form" → Magic (UI component generation)
+```
--- a/src/superclaude/mcp/MCP_Tavily.md
+++ b/src/superclaude/mcp/MCP_Tavily.md
@@ -0,0 +1,285 @@
+# Tavily MCP Server
+
+**Purpose**: Web search and real-time information retrieval for research and current events
+
+## Triggers
+- Web search requirements beyond Claude's knowledge cutoff
+- Current events, news, and real-time information needs
+- Market research and competitive analysis tasks
+- Technical documentation not in training data
+- Academic research requiring recent publications
+- Fact-checking and verification needs
+- Deep research investigations requiring multi-source analysis
+- `/sc:research` command activation
+
+## Choose When
+- **Over WebSearch**: When you need structured search with advanced filtering
+- **Over WebFetch**: When you need multi-source search, not single page extraction
+- **For research**: Comprehensive investigations requiring multiple sources
+- **For current info**: Events, updates, or changes after knowledge cutoff
+- **Not for**: Simple questions answerable from training, code generation, local file operations
+
+## Works Best With
+- **Sequential**: Tavily provides raw information → Sequential analyzes and synthesizes
+- **Playwright**: Tavily discovers URLs → Playwright extracts complex content
+- **Context7**: Tavily searches for updates → Context7 provides stable documentation
+- **Serena**: Tavily performs searches → Serena stores research sessions
+
+## Configuration
+Requires TAVILY_API_KEY environment variable from https://app.tavily.com
+
+## Search Capabilities
+- **Web Search**: General web searches with ranking algorithms
+- **News Search**: Time-filtered news and current events
+- **Academic Search**: Scholarly articles and research papers
+- **Domain Filtering**: Include/exclude specific domains
+- **Content Extraction**: Full-text extraction from search results
+- **Freshness Control**: Prioritize recent content
+- **Multi-Round Searching**: Iterative refinement based on gaps
+
+## Examples
+```
+"latest TypeScript features 2024" → Tavily (current technical information)
+"OpenAI GPT updates this week" → Tavily (recent news and updates)
+"quantum computing breakthroughs 2024" → Tavily (recent research)
+"best practices React Server Components" → Tavily (current best practices)
+"explain recursion" → Native Claude (general concept explanation)
+"write a Python function" → Native Claude (code generation)
+```
+
+## Search Patterns
+
+### Basic Search
+```
+Query: "search term"
+→ Returns: Ranked results with snippets
+```
+
+### Domain-Specific Search  
+```
+Query: "search term"
+Domains: ["arxiv.org", "github.com"]
+→ Returns: Results from specified domains only
+```
+
+### Time-Filtered Search
+```
+Query: "search term"
+Recency: "week" | "month" | "year"
+→ Returns: Recent results within timeframe
+```
+
+### Deep Content Search
+```
+Query: "search term"
+Extract: true
+→ Returns: Full content extraction from top results
+```
+
+## Quality Optimization
+- **Query Refinement**: Iterate searches based on initial results
+- **Source Diversity**: Ensure multiple perspectives in results
+- **Credibility Filtering**: Prioritize authoritative sources
+- **Deduplication**: Remove redundant information across sources
+- **Relevance Scoring**: Focus on most pertinent results
+
+## Integration Flows
+
+### Research Flow
+```
+1. Tavily: Initial broad search
+2. Sequential: Analyze and identify gaps
+3. Tavily: Targeted follow-up searches
+4. Sequential: Synthesize findings
+5. Serena: Store research session
+```
+
+### Fact-Checking Flow
+```
+1. Tavily: Search for claim verification
+2. Tavily: Find contradicting sources
+3. Sequential: Analyze evidence
+4. Report: Present balanced findings
+```
+
+### Competitive Analysis Flow
+```
+1. Tavily: Search competitor information
+2. Tavily: Search market trends
+3. Sequential: Comparative analysis
+4. Context7: Technical comparisons
+5. Report: Strategic insights
+```
+
+### Deep Research Flow (DR Agent)
+```
+1. Planning: Decompose research question
+2. Tavily: Execute planned searches
+3. Analysis: Assess URL complexity
+4. Routing: Simple → Tavily extract | Complex → Playwright
+5. Synthesis: Combine all sources
+6. Iteration: Refine based on gaps
+```
+
+## Advanced Search Strategies
+
+### Multi-Hop Research
+```yaml
+Initial_Search:
+  query: "core topic"
+  depth: broad
+  
+Follow_Up_1:
+  query: "entities from initial"
+  depth: targeted
+  
+Follow_Up_2:
+  query: "relationships discovered"
+  depth: deep
+  
+Synthesis:
+  combine: all_findings
+  resolve: contradictions
+```
+
+### Adaptive Query Generation
+```yaml
+Simple_Query:
+  - Direct search terms
+  - Single concept focus
+  
+Complex_Query:
+  - Multiple search variations
+  - Boolean operators
+  - Domain restrictions
+  - Time filters
+  
+Iterative_Query:
+  - Start broad
+  - Refine based on results
+  - Target specific gaps
+```
+
+### Source Credibility Assessment
+```yaml
+High_Credibility:
+  - Academic institutions
+  - Government sources
+  - Established media
+  - Official documentation
+  
+Medium_Credibility:
+  - Industry publications
+  - Expert blogs
+  - Community resources
+  
+Low_Credibility:
+  - User forums
+  - Social media
+  - Unverified sources
+```
+
+## Performance Considerations
+
+### Search Optimization
+- Batch similar searches together
+- Cache search results for reuse
+- Prioritize high-value sources
+- Limit depth based on confidence
+
+### Rate Limiting
+- Maximum searches per minute
+- Token usage per search
+- Result caching duration
+- Parallel search limits
+
+### Cost Management
+- Monitor API usage
+- Set budget limits
+- Optimize query efficiency
+- Use caching effectively
+
+## Integration with DR Agent Architecture
+
+### Planning Strategy Support
+```yaml
+Planning_Only:
+  - Direct query execution
+  - No refinement needed
+  
+Intent_Planning:
+  - Clarify search intent
+  - Generate focused queries
+  
+Unified:
+  - Present search plan
+  - Adjust based on feedback
+```
+
+### Multi-Hop Execution
+```yaml
+Hop_Management:
+  - Track search genealogy
+  - Build on previous results
+  - Detect circular references
+  - Maintain hop context
+```
+
+### Self-Reflection Integration
+```yaml
+Quality_Check:
+  - Assess result relevance
+  - Identify coverage gaps
+  - Trigger additional searches
+  - Calculate confidence scores
+```
+
+### Case-Based Learning
+```yaml
+Pattern_Storage:
+  - Successful query formulations
+  - Effective search strategies
+  - Domain preferences
+  - Time filter patterns
+```
+
+## Error Handling
+
+### Common Issues
+- API key not configured
+- Rate limit exceeded
+- Network timeout
+- No results found
+- Invalid query format
+
+### Fallback Strategies
+- Use native WebSearch
+- Try alternative queries
+- Expand search scope
+- Use cached results
+- Simplify search terms
+
+## Best Practices
+
+### Query Formulation
+1. Start with clear, specific terms
+2. Use quotes for exact phrases
+3. Include relevant keywords
+4. Specify time ranges when needed
+5. Use domain filters strategically
+
+### Result Processing
+1. Verify source credibility
+2. Cross-reference multiple sources
+3. Check publication dates
+4. Identify potential biases
+5. Extract key information
+
+### Integration Workflow
+1. Plan search strategy
+2. Execute initial searches
+3. Analyze results
+4. Identify gaps
+5. Refine and iterate
+6. Synthesize findings
+7. Store valuable patterns
--- a/src/superclaude/mcp/init.py
+++ b/src/superclaude/mcp/init.py
--- a/src/superclaude/mcp/configs/context7.json
+++ b/src/superclaude/mcp/configs/context7.json
@@ -0,0 +1,9 @@
+{
+  "context7": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@upstash/context7-mcp@latest"
+    ]
+  }
+}
--- a/src/superclaude/mcp/configs/magic.json
+++ b/src/superclaude/mcp/configs/magic.json
@@ -0,0 +1,12 @@
+{
+  "magic": {
+    "type": "stdio",
+    "command": "npx",
+    "args": [
+      "@21st-dev/magic"
+    ],
+    "env": {
+      "TWENTYFIRST_API_KEY": ""
+    }
+  }
+}
--- a/src/superclaude/mcp/configs/morphllm.json
+++ b/src/superclaude/mcp/configs/morphllm.json
@@ -0,0 +1,13 @@
+{
+  "morphllm-fast-apply": {
+    "command": "npx",
+    "args": [
+      "@morph-llm/morph-fast-apply",
+      "/home/"
+    ],
+    "env": {
+      "MORPH_API_KEY": "",
+      "ALL_TOOLS": "true"
+    }
+  }
+}
--- a/src/superclaude/mcp/configs/playwright.json
+++ b/src/superclaude/mcp/configs/playwright.json
@@ -0,0 +1,8 @@
+{
+  "playwright": {
+    "command": "npx",
+    "args": [
+      "@playwright/mcp@latest"
+    ]
+  }
+}
--- a/src/superclaude/mcp/configs/sequential.json
+++ b/src/superclaude/mcp/configs/sequential.json
@@ -0,0 +1,9 @@
+{
+  "sequential-thinking": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@modelcontextprotocol/server-sequential-thinking"
+    ]
+  }
+}
--- a/src/superclaude/mcp/configs/serena-docker.json
+++ b/src/superclaude/mcp/configs/serena-docker.json
@@ -0,0 +1,14 @@
+{
+  "serena": {
+    "command": "docker",
+    "args": [
+      "run",
+      "--rm",
+      "-v", "${PWD}:/workspace",
+      "--workdir", "/workspace",
+      "python:3.11-slim",
+      "bash", "-c",
+      "pip install uv && uv tool install serena-ai && uv tool run serena-ai start-mcp-server --context ide-assistant --project /workspace"
+    ]
+  }
+}
--- a/src/superclaude/mcp/configs/serena.json
+++ b/src/superclaude/mcp/configs/serena.json
@@ -0,0 +1,13 @@
+{
+  "serena": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/oraios/serena",
+        "serena",
+        "start-mcp-server",
+        "--context",
+        "ide-assistant"
+      ]
+    }
+  }
--- a/src/superclaude/mcp/configs/tavily.json
+++ b/src/superclaude/mcp/configs/tavily.json
@@ -0,0 +1,13 @@
+{
+  "tavily": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "mcp-remote",
+      "https://mcp.tavily.com/mcp/?tavilyApiKey=${TAVILY_API_KEY}"
+    ],
+    "env": {
+      "TAVILY_API_KEY": "${TAVILY_API_KEY}"
+    }
+  }
+}