refactor: Standardize @include reference system across all command files

- Fix @include references to use underscore format (Universal_Legend, Standard_Messages_Templates) - Add missing ultracompressed.yml shared pattern file - Update broken reference paths in all 18 command files - Ensure consistent template naming across command system - Optimize command file structure with standardized includes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-29 16:16:08 +00:00 · 2025-06-25 00:21:27 +02:00
parent 219ff3905a
commit 23a103d5dc
36 changed files with 3139 additions and 1375 deletions
--- a/MCP.md
+++ b/MCP.md
@@ -1,4 +1,4 @@
-# MCP.md - Model Context Protocol Ops
+# MCP.md - Professional Model Context Protocol Integration

 ## Legend
 | Symbol | Meaning | | Abbrev | Meaning |
@@ -6,132 +6,270 @@
 | → | leads to | | ops | operations |
 | & | and/with | | UI | user interface |
 | w/ | with | | impl | implementation |
+| @ | at/located | | perf | performance |

-## Decision Matrix
+## Professional MCP Architecture

 ```yaml
-Flag Control:
-  --c7: Force Context7→docs | --seq: Force Sequential→analysis | --magic: Force Magic→UI
-  --pup: Force Puppeteer→browser | --all-mcp: Enable all | --no-mcp: Disable all
-
-MCP Server Integration:
-  Configuration: "claude mcp add server-name --transport stdio/sse/http"
-  Resource_Access: "@server:protocol://resource/path" syntax
-  Slash_Commands: "/mcp__servername__promptname" format
-  Scopes: local|project|user configuration levels
-  Security: OAuth 2.0 authentication | Verify third-party servers
-
-User Triggers (no flags):
-  "docs for X" → C7(resolve-library-id: X) → get-docs
-  "how to use Y in Z" → C7(resolve-library-id: Z) → get-docs(topic: Y)
-  "need button/form/component" → Magic(builder) → integrate
-  "why slow/broken" → Sequential(analysis) → impl fix
-  "design architecture" → Sequential(system design) → C7(patterns)
-
-Context Triggers (flags override):
-  Import errors → C7(resolve-library-id) → verify docs
-  Complex debugging → Sequential(root cause) → native impl
-  UI requests → Magic(builder/refiner) → Puppeteer(test)
-  Perf issues → Sequential(analysis) → optimize impl
-
-Research-First (shared/research-first.yml):
-  External lib detected → C7 lookup REQUIRED (blocks w/o docs)
-  New component → Magic search REQUIRED or existing pattern
-  API integration → WebSearch REQUIRED for official docs
-  Unknown pattern → Sequential thinking + research REQUIRED
-  Low confidence → Impl BLOCKED until research complete
-
-Task Complexity:
-  Simple queries → Native tools only (unless flagged)
-  Lib questions → C7 progressive loading (or --c7)
-  Multi-step problems → Sequential adaptive thinking (or --seq)
-  UI generation → Magic + integration (or --magic)
-  Full workflows → Multi-MCP orchestration (or --all-mcp)
+Server_Integration: Context7|Sequential|Magic|Puppeteer | Advanced orchestration patterns
+Flag_Control: Individual server control | Combined activation | Intelligent defaults
+Research_Standards: Evidence-based methodology | Official documentation requirements
+Quality_Assurance: Validation patterns | Error recovery | Professional standards
+Token_Economics: Cost optimization | Intelligent escalation | Efficient workflows
 ```

-## Execution Playbooks
+## MCP Server Control Matrix

 ```yaml
-Lib Research: C7 resolve-library-id w/ user term → options if multiple → C7 get-docs w/ topic → Sequential if insufficient → impl
-Ex: "React forms?" → C7 resolve("react") → C7 get-docs(topic:"forms") → impl form code
+Individual_Control:
+  --c7/--no-c7: Context7 documentation lookup | Library research | API documentation
+  --seq/--no-seq: Sequential thinking analysis | Complex problem solving | Root cause analysis
+  --magic/--no-magic: Magic UI component generation | React/Vue components | Design systems
+  --pup/--no-pup: Puppeteer browser automation | E2E testing | Performance monitoring

-Complex Analysis: Sequential problem decomposition → guide C7 docs lookup → combine analysis+docs→impl plan → execute w/ native
-Ex: "App slow debug" → Sequential(analyze perf bottlenecks) → C7 get-docs optimization patterns → impl fixes
+Combined_Control:
+  --all-mcp: Enable all MCP servers | Maximum capability mode | Complex workflows
+  --no-mcp: Disable all MCP servers | Native tools only | Token conservation

-UI Generation: Magic builder w/ user requirements+project context → Magic refiner if needed → integrate component → Puppeteer validation
-Ex: "Dashboard w/ charts" → Magic builder("dashboard","charts") → edit files integrate → Puppeteer screenshot
+Priority_System: "Explicit flags > Persona preferences > Auto-activation > Context triggers"
+Override_Rules: "--no-mcp overrides all individual flags | User control supreme"
 ```

-## Token Economics
+## Professional Server Capabilities

 ```yaml
-Budget: Native:0 | Light MCP:minimal | Medium MCP:moderate | Heavy MCP:extensive
-Escalation: 1.Native first simple tasks 2.C7 lib questions 3.Sequential complex analysis 4.Combine MCPs synergy
-Abort: High context usage→native | MCP timeout/error→fallback | Diminishing returns→stop MCP
-Cost: Quick→C7 only | Architecture→Sequential | UI→Magic | Else→Native
-UltraCompressed: --uc flag|High context|Token budget | Substantial reduction | Clarity→conciseness | Legend auto-gen
+Context7:
+  Purpose: Official library documentation & code examples | Professional research standards
+  Capabilities: resolve-library-id | get-library-docs | version-specific documentation
+  Best_For: API integration | Framework patterns | Library adoption | Official standards
+  Professional_Use: Research-first methodology | Evidence-based implementation
+  Token_Cost: Low-Medium | High accuracy | Authoritative sources
+  
+Sequential:
+  Purpose: Multi-step complex problem solving | Architectural thinking | Professional analysis  
+  Capabilities: sequentialthinking | adaptive reasoning | systematic problem decomposition
+  Best_For: System design | Root cause analysis | Complex debugging | Architecture review
+  Professional_Use: Deep technical analysis | Evidence-based reasoning | Quality investigation
+  Token_Cost: Medium-High | Comprehensive analysis | Professional insights
+
+Magic:
+  Purpose: Professional UI component generation | Design system integration
+  Capabilities: component-builder | component-refiner | component-inspiration | logo-search
+  Best_For: React/Vue components | Design systems | Professional UI patterns | Rapid prototyping
+  Professional_Use: Consistent design implementation | Pattern adherence | Quality components
+  Token_Cost: Medium | High-quality output | Design system compliance
+
+Puppeteer:
+  Purpose: Professional browser automation | E2E testing | Performance validation
+  Capabilities: browser-connect | navigation | testing | screenshots | performance-monitoring
+  Best_For: E2E testing | Performance monitoring | Visual validation | User interaction testing
+  Professional_Use: Quality assurance | Performance validation | User experience testing
+  Token_Cost: Low (action-based) | High reliability | Professional testing
 ```

-## Quality Control
+## Professional Execution Patterns

 ```yaml
-C7: ✓Relevant docs→Proceed | ⚠Partial→Try different terms | ✗No match→Sequential alternatives
-Sequential: ✓Clear analysis+steps→Impl | ⚠Partial→Continue thoughts | ✗Unclear/timeout→Native+user questions
-Magic: ✓Component matches→Integrate | ⚠Close needs changes→Refiner | ✗Poor→Try different terms
-Multi-MCP: Results enhance each other | Conflict→Most authoritative | Redundant→Stop calls
+Library_Research_Workflow:
+  Trigger: External library detection | Import statement analysis | Framework questions
+  Process: C7 resolve-library-id → validate documentation → extract patterns → implement with citations
+  Standards: Official documentation required | Version compatibility checked | Best practices documented
+  Example: "React hooks implementation" → C7("react") → get-docs("hooks") → professional implementation
+  
+Complex_Analysis_Workflow:
+  Trigger: Multi-step problems | System design | Architecture questions | Performance issues
+  Process: Sequential decomposition → guided research → comprehensive analysis → action plan
+  Standards: Evidence-based reasoning | Professional methodology | Documented decision process
+  Example: "Performance optimization" → Sequential(analyze bottlenecks) → C7(optimization patterns) → implementation
+
+UI_Development_Workflow:
+  Trigger: Component requirements | Design system needs | Frontend development
+  Process: Magic component generation → design system integration → quality validation → testing
+  Standards: Accessibility compliance | Design system adherence | Professional patterns
+  Example: "Dashboard components" → Magic("dashboard") → integrate patterns → Puppeteer validation
+
+Professional_Testing_Workflow:
+  Trigger: Quality assurance needs | E2E testing | Performance validation
+  Process: Puppeteer automation → comprehensive testing → performance monitoring → quality reports
+  Standards: Professional testing patterns | Coverage requirements | Performance standards  
+  Example: "E2E testing" → Puppeteer(test scenarios) → performance monitoring → quality reports
 ```

-## Persona Integration
+## Professional Token Economics

 ```yaml
-Persona Flag System:
-  Activation: "--persona-[name] flag (e.g., --persona-architect, --persona-frontend)"
-  Reference: "See shared/persona-patterns.yml for full behavioral profiles"
+Cost_Optimization_Strategy:
+  Budget_Allocation: Native(0) | Light_MCP(minimal) | Medium_MCP(moderate) | Heavy_MCP(extensive)
+  Intelligent_Escalation: Native→C7→Sequential→Multi-MCP | Cost-aware progression
+  Abort_Conditions: High context usage | MCP timeout/error | Diminishing returns
+  Efficiency_Patterns: Batch similar operations | Cache results | Progressive loading

-Persona Preferences:
-  --persona-architect: Sequential(design)+C7(patterns)+avoid Magic | Long Sequential system design
-  --persona-frontend: Magic(UI)+Puppeteer(test)+C7(React/Vue docs) | Quick Magic components
-  --persona-backend: C7(API docs)+Sequential(scale analysis)+avoid Magic | API & scalability focus
-  --persona-analyzer: Sequential(root cause) primary+C7(solutions) secondary | Deep Sequential before solutions
-  --persona-security: Sequential(threats)+C7(security patterns)+Puppeteer(test) | Threat modeling priority
-  --persona-mentor: C7(learning)+Sequential(explanations)+avoid Magic | Teaching-focused approach
-  --persona-refactorer: Sequential(analysis)+C7(patterns)+avoid Magic/Puppeteer | Code quality emphasis
-  --persona-performance: Sequential(bottlenecks)+Puppeteer(metrics)+C7(optimization) | Profiling first
-  --persona-qa: Puppeteer(testing)+Sequential(edge cases)+C7(testing frameworks) | Test coverage focus
-
-Flag Integration:
-  Combination: "Personas work with other flags: --persona-architect --ultrathink"
-  Override: "Persona MCP preferences can be overridden: --persona-frontend --no-magic"
-  Priority: "Explicit MCP flags > Persona preferences > Auto-activation"
+Professional_Usage_Guidelines:
+  Research_Operations: C7 for all external libraries | Official documentation requirements
+  Complex_Analysis: Sequential for system design | Multi-step problem solving
+  UI_Development: Magic for component generation | Design system compliance
+  Quality_Assurance: Puppeteer for testing | Performance validation | E2E workflows
+  
+UltraCompressed_Integration:
+  Activation: --uc flag | High context usage | Token budget constraints
+  Compression: 70% token reduction | Maintained information density | Professional brevity
+  Quality: Technical accuracy preserved | Evidence-based standards maintained
 ```

-## Command Integration
+## Professional Quality Control

 ```yaml
-Planning: Default execute immediately | --plan flag→Forces planning mode | --skip-plan→Skip (redundant w/ default)
-MCP Flags: --c7/--no-c7 | --seq/--no-seq | --magic/--no-magic | --pup/--no-pup | --all-mcp | --no-mcp
-Persona Flags: --persona-[name] activates behavioral profile | See flag-inheritance.yml#Persona_Control
-Auto-Activation (no flags): /build→Magic(UI) if frontend | /analyze→Sequential complex | /design→Sequential+C7
-/explain→C7 if lib mentioned else native | /improve→Sequential→C7 | /scan→Native only (security)
-Persona Activation: /analyze --persona-security→security focus | /build --persona-frontend→UI emphasis
-Priority: Explicit flags>Persona preferences>Auto-activation>Context triggers | --no-mcp overrides all
-Context Share: Sequential→feeds C7 topic selection | C7 docs→inform Magic generation | Magic→tested w/ Puppeteer | All cached
-Execution: Default→Execute immediately | --plan flag→Show plan before changes | User controls→Full control
+Context7_Validation:
+  Success_Criteria: Relevant documentation found | Official sources confirmed | Version compatibility verified
+  Partial_Results: Try alternative search terms | Validate with official sources | Document limitations
+  Failure_Recovery: WebSearch official documentation | Cache partial results | Continue with warnings
+
+Sequential_Validation:
+  Success_Criteria: Clear analysis provided | Logical step progression | Actionable recommendations
+  Partial_Results: Use available analysis | Note limitations | Request clarification if needed
+  Failure_Recovery: Break down problem further | Use native analysis | Document reasoning gaps
+
+Magic_Validation: 
+  Success_Criteria: Component matches requirements | Design system compliance | Accessibility standards
+  Partial_Results: Component refinement needed | Pattern integration required | Customization needed
+  Failure_Recovery: Search existing patterns | Manual implementation | Document component requirements
+
+Puppeteer_Validation:
+  Success_Criteria: Test execution successful | Performance metrics collected | User interactions validated
+  Partial_Results: Limited testing possible | Performance data incomplete | Interaction issues
+  Failure_Recovery: Native testing guidance | Manual validation steps | Alternative testing approaches
 ```

-## Failure Recovery & Best Practices
+## Professional Persona Integration

 ```yaml
-Failures: C7: Lib not found→broader terms | Docs incomplete→Sequential | API timeout→cache partial+native
-Sequential: Timeout→use partial+note limit | Token limit→summarize+native | Unclear→ask questions+avoid retry
-Magic: No components→try different terms once | Poor quality→refiner w/ context | Integration issues→document+native
-Multi-MCP: Conflict→most reliable source | Resource exhaustion→single best MCP | Partial failures→continue successful only
+Architectural_Development:
+  Persona: --persona-architect
+  MCP_Preferences: Sequential(primary) + Context7(secondary) | Avoid Magic for system design
+  Usage_Patterns: Sequential system analysis → C7 pattern research → architectural documentation
+  Professional_Focus: Long-term maintainability | Scalability analysis | Pattern compliance

-DO: Match MCP→user need | Set token budgets | Validate before impl | Cache patterns | Graceful fallback
-Use C7 ALL external lib docs (research-first.yml enforced) | Cite MCP sources in impl
-DON'T: MCPs for simple tasks native handles | Chain w/o validation | Exceed high context | Retry failed w/o change | MCPs when immediate needed
-OPTIMIZE: Batch similar calls | Reuse session results | Start least expensive | Prefer native file ops | Document successful patterns
+Frontend_Development:
+  Persona: --persona-frontend  
+  MCP_Preferences: Magic(primary) + Puppeteer(testing) + Context7(frameworks)
+  Usage_Patterns: Magic component generation → Puppeteer validation → C7 pattern research
+  Professional_Focus: User experience | Accessibility compliance | Design system adherence
+
+Backend_Development:
+  Persona: --persona-backend
+  MCP_Preferences: Context7(primary) + Sequential(scalability) | Avoid Magic for server logic
+  Usage_Patterns: C7 API documentation → Sequential scalability analysis → performance optimization
+  Professional_Focus: Reliability standards | Performance optimization | API design
+
+Security_Analysis:
+  Persona: --persona-security
+  MCP_Preferences: Sequential(threat modeling) + Context7(security patterns) + Puppeteer(testing)
+  Usage_Patterns: Sequential threat analysis → C7 security standards → Puppeteer security testing
+  Professional_Focus: Zero-trust architecture | Compliance standards | Vulnerability assessment
+
+Quality_Assurance:
+  Persona: --persona-qa
+  MCP_Preferences: Puppeteer(primary) + Sequential(edge cases) + Context7(testing frameworks)
+  Usage_Patterns: Puppeteer comprehensive testing → Sequential edge case analysis → C7 testing patterns
+  Professional_Focus: Coverage standards | Quality gates | Professional testing methodologies
+```
+
+## Professional Command Integration
+
+```yaml
+Development_Commands:
+  /build: Magic for UI components | C7 for framework documentation | Sequential for architecture
+  /dev-setup: C7 for tooling documentation | Sequential for environment optimization
+  /test: Puppeteer for E2E testing | C7 for testing frameworks | Sequential for coverage analysis
+
+Analysis_Commands:
+  /analyze: Sequential for complex analysis | C7 for pattern research | Puppeteer for performance
+  /troubleshoot: Sequential for root cause analysis | C7 for solution patterns | Puppeteer for reproduction
+  /improve: Sequential for optimization analysis | C7 for best practices | Puppeteer for validation
+  /explain: C7 for official documentation | Sequential for complex explanations | Magic for examples
+
+Operations_Commands:
+  /deploy: Sequential for deployment analysis | C7 for deployment patterns | Puppeteer for validation
+  /scan: Sequential for comprehensive analysis | C7 for security standards | Native for speed
+  /migrate: Sequential for migration planning | C7 for migration patterns | Puppeteer for validation
+  /cleanup: Sequential for impact analysis | Native for speed | C7 for best practices
+
+Design_Commands:
+  /design: Sequential for architectural thinking | C7 for design patterns | Magic for prototypes
+  /spawn: Intelligent MCP routing based on task type | Professional expertise matching
+  /document: C7 for documentation standards | Sequential for complex topics | Magic for examples
+```
+
+## Professional Error Recovery
+
+```yaml
+Context7_Recovery_Patterns:
+  Library_Not_Found: Broader search terms → WebSearch official docs → cache alternatives
+  Documentation_Incomplete: Try specific topics → search recent versions → note limitations
+  API_Timeout: Cache partial results → continue with native tools → document limitations
+  Version_Conflicts: Search specific versions → identify compatibility → document requirements
+
+Sequential_Recovery_Patterns:
+  Analysis_Timeout: Use partial analysis → note limitations → continue with available insights
+  Token_Limit: Summarize key findings → focus on critical issues → provide actionable recommendations
+  Complex_Problems: Break into smaller components → iterative analysis → progressive understanding
+  Unclear_Requirements: Request clarification → make reasonable assumptions → document assumptions
+
+Magic_Recovery_Patterns:
+  Component_Generation_Failed: Search existing patterns → provide template → manual implementation guidance
+  Design_System_Mismatch: Component refinement → pattern customization → integration guidance
+  Quality_Issues: Component review → improvement suggestions → alternative approaches
+  Integration_Problems: Document requirements → provide integration steps → troubleshooting guidance
+
+Puppeteer_Recovery_Patterns:
+  Browser_Connection_Failed: Native testing commands → manual testing guidance → validation steps
+  Test_Execution_Issues: Simplified test scenarios → manual validation → alternative approaches
+  Performance_Monitoring_Failed: Native performance tools → manual monitoring → metrics guidance
+  Automation_Limitations: Hybrid testing approach → manual verification → documented procedures
+```
+
+## Professional Best Practices
+
+```yaml
+Research_Standards:
+  External_Libraries: Context7 lookup REQUIRED | Official documentation only | Version validation
+  Unknown_Patterns: Research before implementation | Evidence-based decisions | Source citations
+  Low_Confidence: Block implementation until research complete | Professional standards maintained
+
+Implementation_Standards:
+  Source_Attribution: Document MCP sources | Credit authoritative documentation | Maintain evidence trail
+  Quality_Validation: Validate before implementation | Test comprehensively | Monitor performance
+  Professional_Patterns: Follow industry standards | Maintain consistency | Evidence-based choices
+
+Optimization_Guidelines:
+  Token_Efficiency: Match MCP to user need | Set appropriate budgets | Graceful fallbacks
+  Performance_Management: Monitor response times | Cache successful patterns | Batch similar operations
+  Quality_Assurance: Validate outputs | Test implementations | Maintain professional standards
+
+Professional_Workflows:
+  Complex_Projects: Multi-MCP orchestration | Intelligent coordination | Quality integration
+  Simple_Operations: Native tools preferred | MCP only when value-adding | Cost-conscious decisions
+  Quality_Focus: Evidence-based standards | Professional validation | Comprehensive testing
+```
+
+## Professional Session Management
+
+```yaml
+Context_Preservation:
+  MCP_State: Active servers | Token usage tracking | Performance monitoring
+  Result_Caching: Successful patterns | Documentation findings | Component libraries
+  Session_Continuity: Server health monitoring | Graceful degradation | State recovery
+
+Performance_Optimization:
+  Server_Health: Regular health checks | Performance monitoring | Load balancing
+  Resource_Management: Token budget tracking | Cost optimization | Intelligent routing
+  Quality_Monitoring: Success rate tracking | Error pattern analysis | Continuous improvement
+
+Professional_Standards:
+  Evidence_Requirements: Documentation for all external libraries | Metrics for performance claims
+  Quality_Gates: Validation before implementation | Testing after deployment | Monitoring in production
+  Research_Methodology: Official sources required | Evidence-based decisions | Professional standards
 ```

 ---
-*SuperClaude v4.0.0 | Ops MCP instructions for Claude Code intelligence*
+*SuperClaude v4.0.0 | Professional MCP integration | Evidence-based methodology | Advanced orchestration patterns*