refactor: PEP8 compliance - directory rename and code formatting (#425)

* fix(orchestration): add WebFetch auto-trigger for infrastructure configuration Problem: Infrastructure configuration changes (e.g., Traefik port settings) were being made based on assumptions without consulting official documentation, violating the 'Evidence > assumptions' principle in PRINCIPLES.md. Solution: - Added Infrastructure Configuration Validation section to MODE_Orchestration.md - Auto-triggers WebFetch for infrastructure tools (Traefik, nginx, Docker, etc.) - Enforces MODE_DeepResearch activation for investigation - BLOCKS assumption-based configuration changes Testing: Verified WebFetch successfully retrieves Traefik official docs (port 80 default) This prevents production outages from infrastructure misconfiguration by ensuring all technical recommendations are backed by official documentation. * feat: Add PM Agent (Project Manager Agent) for seamless orchestration Introduces PM Agent as the default orchestration layer that coordinates all sub-agents and manages workflows automatically. Key Features: - Default orchestration: All user interactions handled by PM Agent - Auto-delegation: Intelligent sub-agent selection based on task analysis - Docker Gateway integration: Zero-token baseline with dynamic MCP loading - Self-improvement loop: Automatic documentation of patterns and mistakes - Optional override: Users can specify sub-agents explicitly if desired Architecture: - Agent spec: SuperClaude/Agents/pm-agent.md - Command: SuperClaude/Commands/pm.md - Updated docs: README.md (15→16 agents), agents.md (new Orchestration category) User Experience: - Default: PM Agent handles everything (seamless, no manual routing) - Optional: Explicit --agent flag for direct sub-agent access - Both modes available simultaneously (no user downside) Implementation Status: - ✅ Specification complete - ✅ Documentation complete - ⏳ Prototype implementation needed - ⏳ Docker Gateway integration needed - ⏳ Testing and validation needed Refs: kazukinakai/docker-mcp-gateway (IRIS MCP Gateway integration) * feat: Add Agent Orchestration rules for PM Agent default activation Implements PM Agent as the default orchestration layer in RULES.md. Key Changes: - New 'Agent Orchestration' section (CRITICAL priority) - PM Agent receives ALL user requests by default - Manual override with @agent-[name] bypasses PM Agent - Agent Selection Priority clearly defined: 1. Manual override → Direct routing 2. Default → PM Agent → Auto-delegation 3. Delegation based on keywords, file types, complexity, context User Experience: - Default: PM Agent handles everything (seamless) - Override: @agent-[name] for direct specialist access - Transparent: PM Agent reports delegation decisions This establishes PM Agent as the orchestration layer while respecting existing auto-activation patterns and manual overrides. Next Steps: - Local testing in agiletec project - Iteration based on actual behavior - Documentation updates as needed * refactor(pm-agent): redesign as self-improvement meta-layer Problem Resolution: PM Agent's initial design competed with existing auto-activation for task routing, creating confusion about orchestration responsibilities and adding unnecessary complexity. Design Change: Redefined PM Agent as a meta-layer agent that operates AFTER specialist agents complete tasks, focusing on: - Post-implementation documentation and pattern recording - Immediate mistake analysis with prevention checklists - Monthly documentation maintenance and noise reduction - Pattern extraction and knowledge synthesis Two-Layer Orchestration System: 1. Task Execution Layer: Existing auto-activation handles task routing (unchanged) 2. Self-Improvement Layer: PM Agent meta-layer handles documentation (new) Files Modified: - SuperClaude/Agents/pm-agent.md: Complete rewrite with meta-layer design - Category: orchestration → meta - Triggers: All user interactions → Post-implementation, mistakes, monthly - Behavioral Mindset: Continuous learning system - Self-Improvement Workflow: BEFORE/DURING/AFTER/MISTAKE RECOVERY/MAINTENANCE - SuperClaude/Core/RULES.md: Agent Orchestration section updated - Split into Task Execution Layer + Self-Improvement Layer - Added orchestration flow diagram - Clarified PM Agent activates AFTER task completion - README.md: Updated PM Agent description - "orchestrates all interactions" → "ensures continuous learning" - Docs/User-Guide/agents.md: PM Agent section rewritten - Section: Orchestration Agent → Meta-Layer Agent - Expertise: Project orchestration → Self-improvement workflow executor - Examples: Task coordination → Post-implementation documentation - PR_DOCUMENTATION.md: Comprehensive PR documentation added - Summary, motivation, changes, testing, breaking changes - Two-layer orchestration system diagram - Verification checklist Integration Validated: Tested with agiletec project's self-improvement-workflow.md: ✅ PM Agent aligns with existing BEFORE/DURING/AFTER/MISTAKE RECOVERY phases ✅ Complements (not competes with) existing workflow ✅ agiletec workflow defines WHAT, PM Agent defines WHO executes it Breaking Changes: None - Existing auto-activation continues unchanged - Specialist agents unaffected - User workflows remain the same - New capability: Automatic documentation and knowledge maintenance Value Proposition: Transforms SuperClaude into a continuously learning system that accumulates knowledge, prevents recurring mistakes, and maintains fresh documentation without manual intervention. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add Claude Code conversation history management research Research covering .jsonl file structure, performance impact, and retention policies. Content: - Claude Code .jsonl file format and message types - Performance issues from GitHub (memory leaks, conversation compaction) - Retention policies (consumer vs enterprise) - Rotation recommendations based on actual data - File history snapshot tracking mechanics Source: Moved from agiletec project (research applicable to all Claude Code projects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add Development documentation structure Phase 1: Documentation Structure complete - Add Docs/Development/ directory for development documentation - Add ARCHITECTURE.md - System architecture with PM Agent meta-layer - Add ROADMAP.md - 5-phase development plan with checkboxes - Add TASKS.md - Daily task tracking with progress indicators - Add PROJECT_STATUS.md - Current status dashboard and metrics - Add pm-agent-integration.md - Implementation guide for PM Agent mode This establishes comprehensive documentation foundation for: - System architecture understanding - Development planning and tracking - Implementation guidance - Progress visibility Related: #pm-agent-mode #documentation #phase-1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: PM Agent session lifecycle and PDCA implementation Phase 2: PM Agent Mode Integration (Design Phase) Commands/pm.md updates: - Add "Always-Active Foundation Layer" concept - Add Session Lifecycle (Session Start/During Work/Session End) - Add PDCA Cycle (Plan/Do/Check/Act) automation - Add Serena MCP Memory Integration (list/read/write_memory) - Document auto-activation triggers Agents/pm-agent.md updates: - Add Session Start Protocol (MANDATORY auto-activation) - Add During Work PDCA Cycle with example workflows - Add Session End Protocol with state preservation - Add PDCA Self-Evaluation Pattern - Add Documentation Strategy (temp → patterns/mistakes) - Add Memory Operations Reference Key Features: - Session start auto-activation for context restoration - 30-minute checkpoint saves during work - Self-evaluation with think_about_* operations - Systematic documentation lifecycle - Knowledge evolution to CLAUDE.md Implementation Status: - ✅ Design complete (Commands/pm.md, Agents/pm-agent.md) - ⏳ Implementation pending (Core components) - ⏳ Serena MCP integration pending Salvaged from mistaken development in ~/.claude directory Related: #pm-agent-mode #session-lifecycle #pdca-cycle #phase-2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: disable Serena MCP auto-browser launch Disable web dashboard and GUI log window auto-launch in Serena MCP server to prevent intrusive browser popups on startup. Users can still manually access the dashboard at http://localhost:24282/dashboard/ if needed. Changes: - Add CLI flags to Serena run command: - --enable-web-dashboard false - --enable-gui-log-window false - Ensures Git-tracked configuration (no reliance on ~/.serena/serena_config.yml) - Aligns with AIRIS MCP Gateway integration approach 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename directories to lowercase for PEP8 compliance - Rename superclaude/Agents -> superclaude/agents - Rename superclaude/Commands -> superclaude/commands - Rename superclaude/Core -> superclaude/core - Rename superclaude/Examples -> superclaude/examples - Rename superclaude/MCP -> superclaude/mcp - Rename superclaude/Modes -> superclaude/modes This change follows Python PEP8 naming conventions for package directories. * style: fix PEP8 violations and update package name to lowercase Changes: - Format all Python files with black (43 files reformatted) - Update package name from 'SuperClaude' to 'superclaude' in pyproject.toml - Fix import statements to use lowercase package name - Add missing imports (timedelta, __version__) - Remove old SuperClaude.egg-info directory PEP8 violations reduced from 2672 to 701 (mostly E501 line length due to black's 88 char vs flake8's 79 char limit). * docs: add PM Agent development documentation Add comprehensive PM Agent development documentation: - PM Agent ideal workflow (7-phase autonomous cycle) - Project structure understanding (Git vs installed environment) - Installation flow understanding (CommandsComponent behavior) - Task management system (current-tasks.md) Purpose: Eliminate repeated explanations and enable autonomous PDCA cycles 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(pm-agent): add self-correcting execution and warning investigation culture ## Changes ### superclaude/commands/pm.md - Add "Self-Correcting Execution" section with root cause analysis protocol - Add "Warning/Error Investigation Culture" section enforcing zero-tolerance for dismissal - Define error detection protocol: STOP → Investigate → Hypothesis → Different Solution → Execute - Document anti-patterns (retry without understanding) and correct patterns (research-first) ### docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md - Add PDCA workflow hypothesis document for PM Agent autonomous enhancement ## Rationale PM Agent must never retry failed operations without understanding root causes. All warnings and errors require investigation via context7/WebFetch/documentation to ensure production-quality code and prevent technical debt accumulation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(installer): add airis-mcp-gateway MCP server option ## Changes - Add airis-mcp-gateway to MCP server options in installer - Configuration: GitHub-based installation via uvx - Repository: https://github.com/oraios/airis-mcp-gateway - Purpose: Dynamic MCP Gateway for zero-token baseline and on-demand tool loading ## Implementation Added to setup/components/mcp.py self.mcp_servers dictionary with: - install_method: github - install_command: uvx test installation - run_command: uvx runtime execution - required: False (optional server) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local> Co-authored-by: Claude <noreply@anthropic.com>
2025-12-29 16:16:08 +00:00 · 2025-10-14 12:17:09 +09:00
parent 302c5851b1
commit 050d5ea2ab
194 changed files with 9698 additions and 3693 deletions
--- a/superclaude/mcp/MCP_Chrome-DevTools.md
+++ b/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/superclaude/mcp/MCP_Context7.md
+++ b/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/superclaude/mcp/MCP_Magic.md
+++ b/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/superclaude/mcp/MCP_Morphllm.md
+++ b/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/superclaude/mcp/MCP_Playwright.md
+++ b/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/superclaude/mcp/MCP_Sequential.md
+++ b/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/superclaude/mcp/MCP_Serena.md
+++ b/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/superclaude/mcp/MCP_Tavily.md
+++ b/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/superclaude/mcp/init.py
+++ b/superclaude/mcp/init.py
--- a/superclaude/mcp/configs/context7.json
+++ b/superclaude/mcp/configs/context7.json
@@ -0,0 +1,9 @@
+{
+  "context7": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@upstash/context7-mcp@latest"
+    ]
+  }
+}
--- a/superclaude/mcp/configs/magic.json
+++ b/superclaude/mcp/configs/magic.json
@@ -0,0 +1,12 @@
+{
+  "magic": {
+    "type": "stdio",
+    "command": "npx",
+    "args": [
+      "@21st-dev/magic"
+    ],
+    "env": {
+      "TWENTYFIRST_API_KEY": ""
+    }
+  }
+}
--- a/superclaude/mcp/configs/morphllm.json
+++ b/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/superclaude/mcp/configs/playwright.json
+++ b/superclaude/mcp/configs/playwright.json
@@ -0,0 +1,8 @@
+{
+  "playwright": {
+    "command": "npx",
+    "args": [
+      "@playwright/mcp@latest"
+    ]
+  }
+}
--- a/superclaude/mcp/configs/sequential.json
+++ b/superclaude/mcp/configs/sequential.json
@@ -0,0 +1,9 @@
+{
+  "sequential-thinking": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@modelcontextprotocol/server-sequential-thinking"
+    ]
+  }
+}
--- a/superclaude/mcp/configs/serena-docker.json
+++ b/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/superclaude/mcp/configs/serena.json
+++ b/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/superclaude/mcp/configs/tavily.json
+++ b/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}"
+    }
+  }
+}