From ff61676f747fc766237d84994e33590fc70b5be0 Mon Sep 17 00:00:00 2001 From: NomenAK Date: Tue, 24 Jun 2025 22:02:29 +0200 Subject: [PATCH] refactor: Remove all hard claims, metrics, and numeric targets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive update to remove specific performance claims and replace with qualitative descriptions: - Replace percentage claims (65%, 70%, 99.9%) with descriptive terms - Convert time metrics (<2s, <30s) to categories (fast, moderate) - Transform numeric thresholds to guidelines - Update token budgets to usage levels (minimal, moderate, extensive) - Soften reliability/uptime promises - Maintain functionality while providing more honest representation Changes across 17 files ensure consistent, claim-free documentation while preserving the framework's usefulness and clarity. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../commands/shared/compression-patterns.yml | 16 ++-- .claude/commands/shared/docs-patterns.yml | 2 +- .../commands/shared/execution-patterns.yml | 74 ++++++++-------- .claude/commands/shared/flag-inheritance.yml | 8 +- .claude/commands/shared/performance.yml | 54 ++++++------ .claude/commands/shared/quality-patterns.yml | 48 +++++------ .claude/commands/shared/security-patterns.yml | 2 +- .claude/commands/shared/session-recovery.yml | 2 +- .claude/commands/shared/system-config.yml | 2 +- .../commands/shared/universal-constants.yml | 54 ++++++------ .claude/commands/shared/user-experience.yml | 6 +- CLAUDE.md | 8 +- COMMANDS.md | 14 ++-- MCP.md | 10 +-- PERSONAS.md | 6 +- README.md | 12 +-- RULES.md | 84 +++++++++---------- 17 files changed, 198 insertions(+), 204 deletions(-) diff --git a/.claude/commands/shared/compression-patterns.yml b/.claude/commands/shared/compression-patterns.yml index 25d1e2c..da4ddc4 100644 --- a/.claude/commands/shared/compression-patterns.yml +++ b/.claude/commands/shared/compression-patterns.yml @@ -21,7 +21,7 @@ Activation_Triggers: Manual_Flags: ["--ultracompressed", "--uc"] Natural_Language: ["ultracompressed", "minimal tokens", "telegram style", "compress output"] Automatic_Triggers: - Context_Threshold: ">70% context used" + Context_Threshold: "High context usage" Token_Budget: "User specifies token limit" Session_History: "User previously requested compression" Task_Operations: "Always for task files" @@ -205,12 +205,12 @@ Error_Messages: ```yaml Compression_Metrics: Token_Reduction: - Target: "70% reduction" - Minimum: "50% reduction" + Target: "Substantial reduction" + Minimum: "Significant reduction" Measure: "Compare before/after token count" Clarity_Preservation: - Requirement: ">80% information retained" + Requirement: "Essential information retained" Test: "Key facts still accessible" Validation: "No critical info lost" @@ -240,7 +240,7 @@ Performance_Guidelines: ```yaml Context_Sensitive_Compression: High_Context_Usage: - Threshold: ">70%" + Threshold: "High context usage" Action: "Auto-enable UC mode" Notice: "⚡ UC mode: high context" @@ -256,15 +256,15 @@ Context_Sensitive_Compression: Progressive_Compression: Level_1_Light: - Context: "50-70%" + Context: "Moderate to high usage" Actions: "Remove articles, use common abbreviations" Level_2_Medium: - Context: "70-85%" + Context: "High usage" Actions: "Full UC mode, all rules active" Level_3_Heavy: - Context: ">85%" + Context: "Very high usage" Actions: "Extreme compression, summary only" ``` diff --git a/.claude/commands/shared/docs-patterns.yml b/.claude/commands/shared/docs-patterns.yml index 1baf8c7..0b62256 100644 --- a/.claude/commands/shared/docs-patterns.yml +++ b/.claude/commands/shared/docs-patterns.yml @@ -99,7 +99,7 @@ Document_Standards: Duration: "Operation time" UltraCompressed_Mode: - Token_Reduction: "~70% from standard format" + Token_Reduction: "Substantial reduction from standard format" Symbols_Required: "→ & @ ∀ ∃ ∴ ∵ based on legend" Structure: "YAML > Tables > Lists > Prose" Legend_Requirement: "Auto-generate symbol/abbreviation legend" diff --git a/.claude/commands/shared/execution-patterns.yml b/.claude/commands/shared/execution-patterns.yml index 72d356d..f02bf30 100644 --- a/.claude/commands/shared/execution-patterns.yml +++ b/.claude/commands/shared/execution-patterns.yml @@ -18,13 +18,13 @@ Standard_Lifecycle: Pre_Execution: Risk_Assessment: - Calculate: "Score operation risk 1-10" + Calculate: "Assess operation risk level" Factors: ["Data loss potential", "Irreversibility", "Scope", "Security"] Actions: - Low_1_3: "Proceed w/ monitoring" - Med_4_6: "Warn & log" - High_7_9: "Require confirmation" - Critical_10: "Block & alert" + Low: "Proceed w/ monitoring" + Medium: "Warn & log" + High: "Require confirmation" + Critical: "Block & alert" Environment_Validation: Check: ["Required tools", "Permissions", "Resources", "Dependencies"] Verify: ["Git state", "Network access", "Disk space", "Memory"] @@ -65,32 +65,32 @@ Servers: Context7: Purpose: "Library documentation and code examples" Best_For: ["API usage", "framework patterns", "library integration"] - Token_Cost: "Low-Medium (100-2000 tokens)" + Token_Cost: "Low-Medium usage" Capabilities: - resolve-library-id: "Find Context7-compatible library ID" - get-library-docs: "Fetch up-to-date documentation" - Success_Rate: "95% for popular libraries" + Success_Rate: "Very high for popular libraries" Fallback: "WebSearch official docs" Sequential: Purpose: "Step-by-step complex problem solving" Best_For: ["Architecture", "debugging", "system design", "root cause analysis"] - Token_Cost: "Medium-High (500-10000 tokens)" + Token_Cost: "Medium-High usage" Capabilities: - sequentialthinking: "Adaptive multi-step reasoning" - Success_Rate: "90% for complex problems" + Success_Rate: "High for complex problems" Fallback: "Native step-by-step analysis" Magic: Purpose: "UI component generation with 21st.dev" Best_For: ["React/Vue components", "UI patterns", "prototypes"] - Token_Cost: "Medium (500-2000 tokens)" + Token_Cost: "Medium usage" Capabilities: - 21st_magic_component_builder: "Generate UI components" - 21st_magic_component_refiner: "Improve existing components" - 21st_magic_component_inspiration: "Search component library" - logo_search: "Find company logos in TSX/JSX/SVG" - Success_Rate: "85% for common components" + Success_Rate: "High for common components" Fallback: "Search existing components in project" Puppeteer: @@ -104,7 +104,7 @@ Servers: - click: "Click elements" - fill: "Fill form inputs" - evaluate: "Execute JavaScript" - Success_Rate: "98% for standard web interactions" + Success_Rate: "Very high for standard web interactions" Fallback: "Manual testing guidance" MCP_Control_Flags: @@ -181,7 +181,7 @@ Full_Stack_Development: Chain: "load→analyze→design→build→test→scan→deploy" Flags: ["--think", "--magic", "--validate"] MCP_Usage: ["--c7 for docs", "--magic for UI", "--seq for design"] - Time: "45-90 minutes" + Time: "Typical development session" Context_Handoff: load→analyze: "Project understanding" analyze→design: "Issues & architecture" @@ -194,19 +194,19 @@ Feature_Implementation: Chain: "analyze --code→design --feature→build --feature→test→git --commit" Flags: ["--think", "--magic"] MCP_Usage: ["--magic for components", "--c7 for patterns"] - Time: "20-45 minutes" + Time: "Moderate duration" Bug_Investigation_Fix: Chain: "troubleshoot --investigate→analyze --code→improve --quality→test→git --commit" Flags: ["--think-hard", "--seq"] MCP_Usage: ["--seq for investigation", "--c7 for solutions"] - Time: "15-60 minutes" + Time: "Variable duration" Tech_Debt_Reduction: Chain: "analyze --architecture→design --refactor→improve --quality→test→document" Flags: ["--think-hard", "--refactor", "--quality"] MCP_Usage: ["--seq for analysis", "--c7 for patterns"] - Time: "60-180 minutes" + Time: "Extended session" ``` ## Git Integration Patterns @@ -270,10 +270,10 @@ Checkpoint_Management: - "Production deployments" - "Data migrations" Risk_Based: - Score_7_9: "Create checkpoint" - Score_10: "Checkpoint + backup" + High_Score: "Create checkpoint" + Critical_Score: "Checkpoint + backup" Time_Based: - Interval: "Every 30 min during long ops" + Interval: "Regular intervals during long ops" Checkpoint_Contents: State_Snapshot: @@ -309,10 +309,10 @@ Checkpoint_Management: ```yaml Cost_Categories: - Native_Tools: "0 tokens" - Light_MCP: "100-500 tokens" - Medium_MCP: "500-2000 tokens" - Heavy_MCP: "2000-10000 tokens" + Native_Tools: "No token cost" + Light_MCP: "Minimal usage" + Medium_MCP: "Moderate usage" + Heavy_MCP: "Extensive usage" Budget_Escalation: 1: "Native first for simple tasks" @@ -321,7 +321,7 @@ Budget_Escalation: 4: "Combine MCPs for synergy" Abort_Conditions: - Context_Usage: ">50% context → native tools" + Context_Usage: "High context usage → native tools" Timeout_Errors: "MCP timeout/error → fallback" Diminishing_Returns: "Poor results → stop MCP usage" @@ -367,19 +367,19 @@ Performance_Tracking: Update: "Update weekly" Analysis: "Identify regressions" Alert_Thresholds: - Build_Time: "> 50% from baseline" - Bundle_Size: "> 20% from baseline" - Test_Time: "> 30% from baseline" - Memory: "> 2x baseline" - MCP_Timeout: "> 30 seconds" + Build_Time: "Significant increase from baseline" + Bundle_Size: "Notable increase from baseline" + Test_Time: "Substantial increase from baseline" + Memory: "Major increase from baseline" + MCP_Timeout: "Extended duration" Storage: ".claudedocs/metrics/performance-{YYYY-MM-DD}.jsonl" Server_Performance: Response_Times: - Context7: "1-5 seconds (network dependent)" - Sequential: "5-30 seconds (complexity dependent)" - Magic: "3-15 seconds (component complexity)" - Puppeteer: "1-10 seconds (page load dependent)" + Context7: "Fast response (network dependent)" + Sequential: "Moderate duration (complexity dependent)" + Magic: "Fast to moderate (component complexity)" + Puppeteer: "Fast to moderate (page load dependent)" Resource_Usage: Context7: "Low CPU, Medium Network" @@ -388,10 +388,10 @@ Server_Performance: Puppeteer: "Medium CPU, Low Network" Reliability_Scores: - Context7: "95% (dependent on library availability)" - Sequential: "98% (internal processing)" - Magic: "90% (external service dependency)" - Puppeteer: "95% (browser dependency)" + Context7: "Very high (dependent on library availability)" + Sequential: "Very high (internal processing)" + Magic: "High (external service dependency)" + Puppeteer: "Very high (browser dependency)" ``` ## Command Integration diff --git a/.claude/commands/shared/flag-inheritance.yml b/.claude/commands/shared/flag-inheritance.yml index b5c2ab1..221c3c1 100644 --- a/.claude/commands/shared/flag-inheritance.yml +++ b/.claude/commands/shared/flag-inheritance.yml @@ -17,7 +17,7 @@ Universal_Always: --plan: "Show execution plan before running" Compression: - --uc: "UltraCompressed mode (~70% token reduction)" + --uc: "UltraCompressed mode (substantial token reduction)" --ultracompressed: "Alias for --uc" Thinking_Modes: @@ -56,7 +56,7 @@ Quality_Assurance: Performance: --profile: "Detailed performance profiling & metrics" --iterate: "Iterative improvement until threshold met" - --threshold: "Set target percentage (default 85%)" + --threshold: "Set quality target (default high)" --watch-perf: "Continuous performance monitoring" Development: @@ -95,7 +95,7 @@ Quality_Commands: --coverage: "Generate comprehensive test coverage" --quality: "Focus on code quality improvements" --iterate: "Iterative improvement until threshold" - --threshold: "Set target percentage (default 85%)" + --threshold: "Set quality target (default high)" --all: "Comprehensive operation across all areas" --quick: "Fast operation focusing on critical issues" @@ -204,7 +204,7 @@ Template_Usage: Duplication_Reduction: Before: "~400 lines of flag definitions across 18 commands" After: "~80 lines in template + ~120 lines command-specific" - Savings: "~200 lines (50% reduction in flag definitions)" + Savings: "Significant reduction in flag definitions" Consistency_Improvements: Standardized_Descriptions: "Single source of truth for flag meanings" diff --git a/.claude/commands/shared/performance.yml b/.claude/commands/shared/performance.yml index 3d0f43e..3420db6 100644 --- a/.claude/commands/shared/performance.yml +++ b/.claude/commands/shared/performance.yml @@ -61,43 +61,43 @@ Success_Rate_Monitoring: ```yaml Command_Benchmarks: Simple_Commands: - read_file: "<2s, <200 tokens" - edit_file: "<3s, <300 tokens" - analyze_single_file: "<5s, <500 tokens" - git_status: "<3s, <100 tokens" + read_file: "fast, minimal tokens" + edit_file: "fast, minimal tokens" + analyze_single_file: "fast, minimal tokens" + git_status: "fast, minimal tokens" Medium_Commands: - build_component: "<30s, <2000 tokens" - test_execution: "<45s, <1500 tokens" - security_scan: "<60s, <3000 tokens" - analyze_multiple_files: "<45s, <2500 tokens" + build_component: "moderate duration, moderate tokens" + test_execution: "moderate duration, moderate tokens" + security_scan: "moderate duration, moderate tokens" + analyze_multiple_files: "moderate duration, moderate tokens" Complex_Commands: - full_codebase_analysis: "<120s, <5000 tokens" - architecture_design: "<180s, <8000 tokens" - comprehensive_security_audit: "<300s, <10000 tokens" + full_codebase_analysis: "extended duration, extensive tokens" + architecture_design: "extended duration, extensive tokens" + comprehensive_security_audit: "extended duration, extensive tokens" MCP_Server_Performance: - Context7: "<5s response, 100-2000 tokens typical" - Sequential: "<30s analysis, 500-10000 tokens typical" - Magic: "<10s generation, 500-2000 tokens typical" - Puppeteer: "<15s operation, minimal tokens" + Context7: "fast response, minimal to moderate tokens typical" + Sequential: "moderate analysis time, moderate to extensive tokens typical" + Magic: "fast generation, moderate tokens typical" + Puppeteer: "fast operation, minimal tokens" Performance_Thresholds: Time_Limits: - Yellow_Warning: ">30s operations → Consider alternatives" - Red_Alert: ">60s → Force timeout, explain delay, offer cancellation" - Critical: ">120s → Immediate intervention required" + Yellow_Warning: "Extended operations → Consider alternatives" + Red_Alert: "Very long operations → Force timeout, explain delay, offer cancellation" + Critical: "Excessive duration → Immediate intervention required" Token_Limits: - Moderate_Usage: ">2K tokens single op → Simplify approach" - High_Usage: ">5K session → Suggest /compact mode" - Critical_Usage: ">10K → Force optimization" + Moderate_Usage: "High token usage single op → Simplify approach" + High_Usage: "Very high session usage → Suggest /compact mode" + Critical_Usage: "Excessive usage → Force optimization" Error_Patterns: - Concern_Level: "3+ retries same operation → Switch strategy" + Concern_Level: "Multiple retries same operation → Switch strategy" Critical_Level: "Repeated failures → Escalate to manual approach" - System_Issue: "5+ consecutive failures → System health check" + System_Issue: "Many consecutive failures → System health check" ``` ## Adaptive Optimization Strategies @@ -105,7 +105,7 @@ Performance_Thresholds: ```yaml Real_Time_Performance_Optimization: Slow_Operations_Response: - Detection: "Operations exceeding 30s threshold" + Detection: "Operations exceeding moderate duration threshold" Immediate_Actions: - Switch to faster tools (rg vs grep, parallel processing) - Reduce operation scope (specific files vs full scan) @@ -113,7 +113,7 @@ Real_Time_Performance_Optimization: - Break large operations into smaller chunks High_Token_Usage_Response: - Detection: ">70% context or >5K tokens in single operation" + Detection: "High context usage or extensive tokens in single operation" Immediate_Actions: - Auto-suggest UltraCompressed mode (--uc) - Cache repeated content and use references @@ -122,7 +122,7 @@ Real_Time_Performance_Optimization: Error_Pattern_Response: Repeated_Failures: - Detection: "3+ failures of same operation type" + Detection: "Multiple failures of same operation type" Actions: - Switch to alternative tool/approach - Adjust strategy based on error type @@ -165,7 +165,7 @@ When_Errors_Occur: ```yaml Data_Collection: Lightweight_Tracking: - Performance_Impact: "<1% overhead on operations" + Performance_Impact: "Minimal overhead on operations" Background_Collection: "No user interruption during monitoring" Privacy_Preserving: "Local storage only, no external transmission" User_Configurable: "Can be disabled via settings" diff --git a/.claude/commands/shared/quality-patterns.yml b/.claude/commands/shared/quality-patterns.yml index fa239b7..aa1f627 100644 --- a/.claude/commands/shared/quality-patterns.yml +++ b/.claude/commands/shared/quality-patterns.yml @@ -13,28 +13,28 @@ ```yaml Severity_Levels: - CRITICAL_10: + CRITICAL: Definition: "Data loss, security breach, production down" Response: "Immediate stop, alert, rollback, incident response" Recovery: "Manual intervention required" - Response_Time: "< 1 second" + Response_Time: "Immediate" Examples: ["Delete prod data", "Expose secrets", "Force push main"] - HIGH_7_9: + HIGH: Definition: "Build failure, test failure, deployment issues" Response: "Stop workflow, notify user, suggest fixes" Recovery: "Automated retry w/ backoff" - Response_Time: "< 10 seconds" + Response_Time: "Rapid" Examples: ["Syntax error", "Permission denied", "Test failure"] - MEDIUM_4_6: + MEDIUM: Definition: "Warning conditions, performance issues, code quality" Response: "Continue w/ warning, log for review" Recovery: "Attempt optimization, monitor" - Response_Time: "< 60 seconds" + Response_Time: "Standard" Examples: ["Slow operation", "Deprecated API", "Large file"] - LOW_1_3: + LOW: Definition: "Info messages, style violations, suggestions" Response: "Note in output, continue" Recovery: "Background fixes, cleanup" @@ -67,15 +67,15 @@ Validation_Sequence: Risk_Assessment: Score_Factors: - Data_Loss: "+3 | Irreversibility: +2" - Scope: "+2 | Security: +3" - Backup: "-2 | Test_Coverage: -1" - Sandbox: "-2 | Checkpoint: -1" + Data_Loss: "High impact | Irreversibility: Moderate impact" + Scope: "Moderate impact | Security: High impact" + Backup: "Reduces risk | Test_Coverage: Slightly reduces risk" + Sandbox: "Reduces risk | Checkpoint: Slightly reduces risk" Thresholds: - Low_1_3: "Proceed w/ info" - Medium_4_6: "Warn & confirm" - High_7_9: "Require approval" - Critical_10: "Block completely" + Low: "Proceed w/ info" + Medium: "Warn & confirm" + High: "Require approval" + Critical: "Block completely" ``` ## Error Handling Patterns @@ -85,7 +85,7 @@ Error_Categories: Transient: Types: ["Network timeout", "Resource busy", "Rate limit"] Strategy: "Exponential backoff retry" - Retry: "Base 1s, Max 60s, 3 attempts, ±25% jitter" + Retry: "Base short, Max moderate duration, multiple attempts, with jitter" Permanent: Types: ["Syntax error", "Permission denied", "Not found"] @@ -101,8 +101,8 @@ Error_Categories: Strategy: "Monitor, cleanup, queue management" Circuit_Breaker: - Threshold: "3 consecutive failures" - Recovery: "5 minutes before re-enable" + Threshold: "Multiple consecutive failures" + Recovery: "Brief pause before re-enable" States: Closed: "Normal operation" Open: "Blocking calls after threshold" @@ -114,8 +114,8 @@ Circuit_Breaker: ```yaml Automatic_Recovery: Retry_Patterns: - Simple: "3 attempts, 1s delay" - Exponential: "1s→2s→4s→8s w/ jitter" + Simple: "Multiple attempts, short delay" + Exponential: "Progressive backoff w/ jitter" Circuit: "Stop after threshold" Fallback_Options: Alternative: "Use native if MCP fails" @@ -192,10 +192,10 @@ Context_Preservation: Partial: "Use completed work in recovery" Health_Monitoring: - Frequency: "Every 5 min during active use" - Timeout: "3 seconds per check" - Degradation: ">30s response → switch alternatives" - Recovery: "Re-enable after 5 minutes" + Frequency: "Regular intervals during active use" + Timeout: "Brief timeout per check" + Degradation: "Slow response → switch alternatives" + Recovery: "Re-enable after brief pause" ``` ## Command-Specific Recovery diff --git a/.claude/commands/shared/security-patterns.yml b/.claude/commands/shared/security-patterns.yml index 77fb289..d86c712 100644 --- a/.claude/commands/shared/security-patterns.yml +++ b/.claude/commands/shared/security-patterns.yml @@ -221,7 +221,7 @@ Infrastructure_Security: Validation_Levels: Quick_Scan: Scope: "Critical security issues only" - Time: "< 30 seconds" + Time: "Brief duration" Focus: ["Hardcoded secrets", "SQL injection", "XSS", "Known CVEs"] Output: "High-priority findings only" diff --git a/.claude/commands/shared/session-recovery.yml b/.claude/commands/shared/session-recovery.yml index 7d0bef0..514895e 100644 --- a/.claude/commands/shared/session-recovery.yml +++ b/.claude/commands/shared/session-recovery.yml @@ -104,7 +104,7 @@ checkpoint_restoration: ```yaml graceful_pause: auto_triggers: - - context >90% full + - context very high usage - long inactivity - error thresholds diff --git a/.claude/commands/shared/system-config.yml b/.claude/commands/shared/system-config.yml index d364fa2..735e1a5 100644 --- a/.claude/commands/shared/system-config.yml +++ b/.claude/commands/shared/system-config.yml @@ -13,7 +13,7 @@ ```yaml Session_Settings: Memory_Management: - Context_Limit: "70% warning, 90% critical" + Context_Limit: "High usage warning, very high critical" Cache_Duration: "30 minutes active session" Auto_Cleanup: "Clear expired context every 5 minutes" Persistence: "Store successful workflows across sessions" diff --git a/.claude/commands/shared/universal-constants.yml b/.claude/commands/shared/universal-constants.yml index 2c01a40..b204523 100644 --- a/.claude/commands/shared/universal-constants.yml +++ b/.claude/commands/shared/universal-constants.yml @@ -168,32 +168,32 @@ Severity_Levels: ```yaml Time_Limits: - Quick_Operation: "< 5 seconds" - Standard_Operation: "< 30 seconds" - Long_Operation: "< 120 seconds" - Critical_Timeout: "300 seconds (5 minutes)" - Session_Timeout: "1800 seconds (30 minutes)" + Quick_Operation: "Fast" + Standard_Operation: "Moderate duration" + Long_Operation: "Extended duration" + Critical_Timeout: "Maximum allowed duration" + Session_Timeout: "Extended session limit" Token_Limits: - Small_Response: "< 500 tokens" - Medium_Response: "< 2000 tokens" - Large_Response: "< 5000 tokens" - Context_Warning: "> 70% context size" - Context_Critical: "> 90% context size" + Small_Response: "Minimal usage" + Medium_Response: "Moderate usage" + Large_Response: "Extensive usage" + Context_Warning: "High context usage" + Context_Critical: "Very high context usage" File_Size_Limits: - Small_File: "< 10 KB" - Medium_File: "< 100 KB" - Large_File: "< 1 MB" - Huge_File: "> 1 MB" - Max_Analysis: "5 MB" + Small_File: "Minimal size" + Medium_File: "Moderate size" + Large_File: "Large size" + Huge_File: "Very large size" + Max_Analysis: "Maximum analyzable size" Retry_Limits: - Default_Retries: 3 - Network_Retries: 5 - File_Lock_Retries: 3 - MCP_Server_Retries: 3 - Max_Consecutive_Failures: 5 + Default_Retries: "Multiple attempts" + Network_Retries: "Several attempts" + File_Lock_Retries: "Multiple attempts" + MCP_Server_Retries: "Multiple attempts" + Max_Consecutive_Failures: "Several failures" ``` ## Standard Priority & Status Values @@ -206,16 +206,10 @@ Priority_Levels: Low: "low" Severity_Numbers: - Critical: 10 - High_Max: 9 - High_Mid: 8 - High_Min: 7 - Medium_Max: 6 - Medium_Mid: 5 - Medium_Min: 4 - Low_Max: 3 - Low_Mid: 2 - Low_Min: 1 + Critical: "Maximum severity" + High: "High severity" + Medium: "Medium severity" + Low: "Low severity" Status_Values: Pending: "pending" diff --git a/.claude/commands/shared/user-experience.yml b/.claude/commands/shared/user-experience.yml index 2fcf2f9..06bfd04 100644 --- a/.claude/commands/shared/user-experience.yml +++ b/.claude/commands/shared/user-experience.yml @@ -98,9 +98,9 @@ Learning from Errors: ```yaml Response Time Expectations: - Immediate (<100ms): Command acknowledgment, simple queries - Fast (<1s): File operations, simple analysis - Moderate (<10s): Complex analysis, building, testing + Immediate: Command acknowledgment, simple queries + Fast: File operations, simple analysis + Moderate: Complex analysis, building, testing Long (>10s): Deployment, migration, comprehensive operations Progress Communication: diff --git a/CLAUDE.md b/CLAUDE.md index dfa7fd2..6b0f1cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,7 +34,7 @@ Examples: /analyze --code --think | /design --api --ultrathink ## Token Economy ```yaml -Targets: Minimal commands | Responses<4 lines | Concise docs +Targets: Minimal commands | Concise responses | Concise docs Symbols: →(leads to) |(separator) &(combine) :(define) »(sequence) Remove: the|a|very|really|that|which | "in order to"→to | and→& ``` @@ -42,8 +42,8 @@ Remove: the|a|very|really|that|which | "in order to"→to | and→& ## UltraCompressed Mode ```yaml -Purpose: ~70% token reduction | Telegram-style docs | Symbols & abbrevs -Activation: --uc flag | Natural language | Auto when context>70% +Purpose: Substantial token reduction | Telegram-style docs | Symbols & abbrevs +Activation: --uc flag | Natural language | Auto when context usage high Rules: shared/ultracompressed.yml | Remove filler | Use symbols Output: Direct info only | No intros/outros | Lists>prose Legend: Auto-generate | Used symbols/abbrevs only | Start of docs @@ -79,7 +79,7 @@ Tasks: Auto-detect complexity→seamless task creation | ./claudedocs/tasks/in-p ```yaml Mode: Automatic | No user prompts | Seamless activation -Detection: ≥8 complexity points→auto-create | 5-7→brief notify | <5→normal +Detection: High complexity→auto-create | Medium complexity→brief notify | Low complexity→normal Triggers: "build|create|implement" + "system|feature" + complexity flags Flow: requirement→analyze→create→breakdown→implement | Background operation Recovery: Auto-resume active tasks | Context preservation | Git integration diff --git a/COMMANDS.md b/COMMANDS.md index e5324d5..e302ceb 100644 --- a/COMMANDS.md +++ b/COMMANDS.md @@ -7,7 +7,7 @@ | & | and/with | | impl | implementation | ## Quick Reference -All commands use `/` prefix. Built with @pattern template system for 65% efficiency gains. +All commands use `/` prefix. Built with @pattern template system for significant efficiency gains. Example: `/analyze --code --security --think` @@ -15,12 +15,12 @@ Example: `/analyze --code --security --think` ### Planning & Thinking - `--plan` - Show execution plan before running -- `--think` - Multi-file analysis (~4K tokens) -- `--think-hard` - Architecture-level depth (~10K tokens) -- `--ultrathink` - Critical system analysis (~32K tokens) +- `--think` - Multi-file analysis (moderate depth) +- `--think-hard` - Architecture-level depth (comprehensive) +- `--ultrathink` - Critical system analysis (maximum depth) ### Documentation Control -- `--uc` / `--ultracompressed` - ~70% token reduction mode +- `--uc` / `--ultracompressed` - Substantial token reduction mode ### MCP Server Control - `--c7` / `--no-c7` - Enable/disable Context7 docs lookup @@ -72,7 +72,7 @@ Example: `/analyze --code --security --think` - `--quality` - Code structure improvement - `--performance` - Performance optimization - `--iterate` - Iterative improvement -- `--threshold N%` - Quality threshold (default: 85%) +- `--threshold N%` - Quality threshold (default: high) ### `/explain` - Technical explanations - `--depth [ELI5/Beginner/Intermediate/Expert]` - Explanation depth @@ -216,7 +216,7 @@ Example: `/analyze --code --security --think` ### @pattern Reference System - **Command Templates**: Standardized flag & structure definitions - **Validation System**: `validate-references.sh` ensures integrity -- **Token Efficiency**: 65% reduction in command duplication +- **Token Efficiency**: Significant reduction in command duplication - **Maintenance**: Single source of truth for common elements ### Quality Assurance diff --git a/MCP.md b/MCP.md index 9b9820a..10d9ab7 100644 --- a/MCP.md +++ b/MCP.md @@ -39,7 +39,7 @@ Research-First (shared/research-first.yml): New component → Magic search REQUIRED or existing pattern API integration → WebSearch REQUIRED for official docs Unknown pattern → Sequential thinking + research REQUIRED - Confidence < 90% → Impl BLOCKED until research complete + Low confidence → Impl BLOCKED until research complete Task Complexity: Simple queries → Native tools only (unless flagged) @@ -65,11 +65,11 @@ Ex: "Dashboard w/ charts" → Magic builder("dashboard","charts") → edit files ## Token Economics ```yaml -Budget: Native:0 | Light MCP:100-500 | Medium MCP:500-2K | Heavy MCP:2K-10K +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: >50% context→native | MCP timeout/error→fallback | Diminishing returns→stop MCP +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 | ~70% reduction | Clarity→conciseness | Legend auto-gen +UltraCompressed: --uc flag|High context|Token budget | Substantial reduction | Clarity→conciseness | Legend auto-gen ``` ## Quality Control @@ -116,7 +116,7 @@ Multi-MCP: Conflict→most reliable source | Resource exhaustion→single best M 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 50% context | Retry failed w/o change | MCPs when immediate needed +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 ``` diff --git a/PERSONAS.md b/PERSONAS.md index e7be2c5..1a73a75 100644 --- a/PERSONAS.md +++ b/PERSONAS.md @@ -15,7 +15,7 @@ ```yaml Core_Belief: Systems evolve, design for change | Primary_Question: "How will this scale & evolve?" Decision_Pattern: Long-term maintainability > short-term efficiency -Risk_Tolerance: Conservative, proven patterns | Success_Metric: System survives 5+ years w/o major refactor +Risk_Tolerance: Conservative, proven patterns | Success_Metric: System survives long-term w/o major refactor Communication_Style: Diagrams, trade-offs, future scenarios Problem_Solving: Think in systems, minimize coupling, design boundaries | MCP_Tools: Sequential, Context7 ``` @@ -30,9 +30,9 @@ Problem_Solving: Mobile-first, assume users will break things | MCP_Tools: Magic ### backend ```yaml -Core_Belief: Reliability & perf enable everything else | Primary_Question: "Will this handle 10x load?" +Core_Belief: Reliability & perf enable everything else | Primary_Question: "Will this handle high scalability?" Decision_Pattern: Reliability > features > convenience | Risk_Tolerance: Conservative on data, aggressive on optimization -Success_Metric: 99.9% uptime, sub-second response times | Communication_Style: Metrics, benchmarks, API contracts +Success_Metric: High reliability, fast response times | Communication_Style: Metrics, benchmarks, API contracts Problem_Solving: Design for failure, monitor everything, automate ops | MCP_Tools: Context7, Sequential ``` diff --git a/README.md b/README.md index 44e482f..5f74eed 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ **A lightweight framework that transforms generic Claude Code into your specialized development partner – no external tools, no complex setup, just pure configuration magic.** -> **New in v4.0.0**: Template reference system achieves 65% efficiency gains with @pattern includes and validation system +> **New in v4.0.0**: Template reference system achieves significant efficiency improvements with @pattern includes and validation system ## 🎯 The Problem @@ -22,7 +22,7 @@ Claude Code is powerful, but let's be honest – it's generic. You find yourself Think of it as a brain upgrade for Claude Code. Drop it in once, and suddenly Claude: - **Remembers everything** with Git-based checkpoints - **Thinks like you want** with 9 specialized personas -- **Works 65% more efficiently** with @pattern template system (v4.0.0) +- **Works significantly more efficiently** with @pattern template system (v4.0.0) - **Never guesses** – always finds the official docs first ## 🚀 Zero-Friction Install @@ -75,7 +75,7 @@ Real shortcuts for real work: - **Magic** generates UI components that actually match your style - **Puppeteer** tests everything in a real browser -### 🚄 **70% More Efficient** +### 🚄 **Substantially More Efficient** Our UltraCompressed mode strips unnecessary tokens without losing clarity. Plus, the new @pattern template system eliminates command duplication. More context, longer conversations, bigger projects – same token budget. ## 🎮 Quick Start Examples @@ -95,7 +95,7 @@ Our UltraCompressed mode strips unnecessary tokens without losing clarity. Plus, /troubleshoot --investigate --prod /analyze --profile # Find the real bottleneck /persona:performance -/improve --performance --threshold 90% +/improve --performance --threshold high ``` ### The "Make It Pretty" Flow @@ -181,7 +181,7 @@ Check out our [Contributing Guide](CONTRIBUTING.md) and join the conversation! |---------|-------------------|------------------| | **Context** | Lost after errors | Git checkpoints preserve everything | | **Personas** | Generic responses | Specialized thinking modes | -| **Tokens** | Verbose outputs | 65-70% reduction, same information | +| **Tokens** | Verbose outputs | Substantial reduction, same information | | **Docs** | "I think this works" | Always finds official sources | | **Workflows** | Repeat instructions | One command, complete flow | | **Quality** | Hope for the best | Evidence-based standards | @@ -200,7 +200,7 @@ Check out our [Contributing Guide](CONTRIBUTING.md) and join the conversation! > "The frontend persona just *gets* UX. It asks questions I didn't even think of." – *Full-Stack Dev* -> "65-70% token reduction means I can keep entire codebases in context. The @pattern system is brilliant." – *Tech Lead* +> "Significant token reduction means I can keep entire codebases in context. The @pattern system is brilliant." – *Tech Lead* ## 🎯 Is SuperClaude For You? diff --git a/RULES.md b/RULES.md index 1290094..d901472 100644 --- a/RULES.md +++ b/RULES.md @@ -13,9 +13,9 @@ ## 1. Core Protocols -### Critical Thinking [H:8] +### Critical Thinking [HIGH] ```yaml -Evaluate: CRIT[10]→Block | HIGH[8-9]→Warn | MED[5-7]→Advise +Evaluate: CRITICAL→Block | HIGH→Warn | MEDIUM→Advise Git: Uncommitted→"Commit?" | Wrong branch→"Feature?" | No backup→"Save?" Efficiency: Question→Think | Suggest→Action | Explain→2-3 lines | Iterate>Analyze Feedback: Point out flaws | Suggest alternatives | Challenge assumptions @@ -23,7 +23,7 @@ Avoid: Excessive agreement | Unnecessary praise | Blind acceptance Approach: "Consider X instead" | "Risk: Y" | "Alternative: Z" ``` -### Evidence-Based [C:10] +### Evidence-Based [CRITICAL] ```yaml Prohibited: best|optimal|faster|secure|better|improved|enhanced|always|never|guaranteed Required: may|could|potentially|typically|often|sometimes @@ -33,13 +33,13 @@ Evidence: testing confirms|metrics show|benchmarks prove|data indicates ### Thinking Modes ```yaml Triggers: Natural language OR flags (--think|--think-hard|--ultrathink) -none: 1file <10lines | think: Multi-file 4K | hard: Architecture 10K | ultra: Critical 32K +none: Simple operations | think: Multi-file analysis | hard: Architecture-level depth | ultra: Comprehensive analysis Usage: /analyze --think | "think about X" | /design --ultrathink ``` ## 2. Severity System -### CRITICAL [10] → Block +### CRITICAL → Block ```yaml Security: NEVER commit secrets|execute untrusted|expose PII Ops: NEVER force push shared|delete no backup|skip validation @@ -48,23 +48,23 @@ Research: NEVER impl w/o docs|ALWAYS WebSearch/C7→unfamiliar libs|ALWAYS verif Docs: ALWAYS Claude reports→.claudedocs/|project docs→/docs|NEVER mix ops w/ project docs ``` -### HIGH [7-9] → Fix Required +### HIGH → Fix Required ```yaml -[9] Security|Production: Best practices|No debug in prod|Evidence-based -[8] Quality|Performance: Error handling|N+1 prevention|Test coverage|SOLID -[7] Standards|Efficiency: Caching|Git workflow|Task mgmt|Context mgmt +Security|Production: Best practices|No debug in prod|Evidence-based +Quality|Performance: Error handling|N+1 prevention|Test coverage|SOLID +Standards|Efficiency: Caching|Git workflow|Task mgmt|Context mgmt ``` -### MEDIUM [4-6] → Warn +### MEDIUM → Warn ```yaml -[6] DRY|Module boundaries|Complex docs -[5] Naming|SOLID|Examples|Doc structure -[4] Formatting|Tech terms|Organization +DRY|Module boundaries|Complex docs +Naming|SOLID|Examples|Doc structure +Formatting|Tech terms|Organization ``` -### LOW [1-3] → Suggest +### LOW → Suggest ```yaml -[3] Changelog|Algorithms [2] Doc examples [1] Modern syntax +Changelog|Algorithms | Doc examples | Modern syntax ``` ## 3. Ops Standards @@ -75,7 +75,7 @@ Rules: Read→Write | Edit>Write | No docs unless asked | Atomic ops Code: Clean|Conventions|Error handling|No duplication|NO COMMENTS ``` -### Tasks [H:7] +### Tasks [HIGH] ```yaml TodoWrite: 3+ steps|Multiple requests | TodoRead: Start|Frequent Rules: One in_progress|Update immediate|Track blockers @@ -88,26 +88,26 @@ Native: Appropriate tool|Batch|Validate|Handle failures|Native>MCP(simple) MCP: C7→Docs | Seq→Complex | Pup→Browser | Magic→UI | Monitor tokens ``` -### Performance [H:8] +### Performance [HIGH] ```yaml Parallel: Unrelated files|Independent|Multiple sources Efficiency: Min tokens|Cache|Skip redundant|Batch similar ``` -### Git [H:8] +### Git [HIGH] ```yaml Before: status→branch→fetch→pull --rebase | Commit: status→diff→add -p→commit | Small|Descriptive|Test first Checkpoint: shared/checkpoint.yml | Auto before risky | /rollback ``` -### Communication [H:8] +### Communication [HIGH] ```yaml Mode: 🎭Persona|🔧Command|✅Complete|🔄Switch | Style: Concise|Structured|Evidence-based|Actionable Code output: Minimal comments | Concise names | No explanatory text Responses: Consistent format | Done→Issues→Next | Remember context ``` -### Constructive Pushback [H:8] +### Constructive Pushback [HIGH] ```yaml When: Inefficient approach | Security risk | Over-engineering | Bad practice How: Direct>subtle | Alternative>criticism | Evidence>opinion @@ -115,7 +115,7 @@ Ex: "Simpler: X" | "Risk: SQL injection" | "Consider: existing lib" Never: Personal attacks | Condescension | Absolute rejection ``` -### Efficiency [C:9] +### Efficiency [CRITICAL] ```yaml Speed: Simple→Direct | Stuck→Pivot | Focus→Impact | Iterate>Analyze Output: Minimal→first | Expand→if asked | Actionable>theory @@ -123,14 +123,14 @@ Keywords: "quick"→Skip | "rough"→Minimal | "urgent"→Direct | "just"→Min Actions: Do>explain | Assume obvious | Skip permissions | Remember session ``` -### Error Recovery [H:9] +### Error Recovery [HIGH] ```yaml On failure: Try alternative → Explain clearly → Suggest next step Ex: Command fails→Try variant | File not found→Search nearby | Permission→Suggest fix Never: Give up silently | Vague errors | Pattern: What failed→Why→Alternative→User action ``` -### Session Awareness [H:9] +### Session Awareness [HIGH] ```yaml Track: Recent edits | User corrections | Found paths | Key facts Remember: "File is in X"→Use X | "I prefer Y"→Do Y | Edited file→It's changed @@ -143,7 +143,7 @@ Sequences: build→test→deploy | scan→fix→verify | review→refactor→tes Offer: "Notice X→Y→Z. Create shortcut?" | Remember if declined ``` -### Action & Command Efficiency [H:8] +### Action & Command Efficiency [HIGH] ```yaml Just do: Read→Edit→Test | No "I will now..." | No "Should I?" Skip: Permission for obvious | Explanations before action | Ceremonial text @@ -154,7 +154,7 @@ Workflows: analyze→fix→test | build→test→deploy | scan→patch Batch: Similar fixes together | Related files parallel | Group by type ``` -### Smart Defaults & Handling [H:8-9] +### Smart Defaults & Handling [HIGH] ```yaml File Discovery: Recent edits | Common locations | Git status | Project patterns Commands: "test"→package.json scripts | "build"→project cfg | "start"→main entry @@ -163,7 +163,7 @@ Interruption: "stop"|"wait"|"pause"→Immediate ack | State: Save progress | Cle Solution: Simple→Moderate→Complex | Try obvious first | Escalate if needed ``` -### Project Quality [H:7-8] +### Project Quality [HIGH] ```yaml Opportunistic: Notice improvements | Mention w/o fixing | "Also spotted: X" Cleanliness: Remove cruft while working | Clean after ops | Suggest cleanup @@ -171,7 +171,7 @@ Standards: No debug code in commits | Clean build artifacts | Updated deps Balance: Primary task first | Secondary observations last | Don't overwhelm ``` -## 4. Security Standards [C:10] +## 4. Security Standards [CRITICAL] ```yaml Sandboxing: Project dir|localhost|Doc APIs ✓ | System|~/.ssh|AWS ✗ | Timeout|Memory|Storage limits @@ -182,7 +182,7 @@ Levels: READ→WRITE→EXECUTE→ADMIN | Start low→Request→Temp→Revoke Emergency: Stop→Alert→Log→Checkpoint→Fix ``` -## 5. Ambiguity Resolution [H:7] +## 5. Ambiguity Resolution [HIGH] ```yaml Keywords: "something like"|"maybe"|"fix it"|"etc" | Missing: No paths|Vague scope|No criteria @@ -194,25 +194,25 @@ Risk: HIGH→More Qs | LOW→Safe defaults | Flow: Detect→CRIT block|HIGH opti ## 6. Dev Practices ```yaml -Design: KISS[H:7]: Simple>clever | YAGNI[M:6]: Immediate only | SOLID[H:8]: Single resp|Open/closed -DRY[M:6]: Extract common|cfg>duplicate | Clean Code[C:9]: <20lines|<5cyclo|<3nest -Code Gen[C:10]: NO comments unless asked | Short>long names | Minimal boilerplate -Docs[C:9]: Bullets>paragraphs | Essential only | No "Overview"|"Introduction" -UltraCompressed[C:10]: --uc flag | Context>70% | ~70% reduction | Legend REQUIRED -Architecture[H:8]: DDD: Bounded contexts|Aggregates|Events | Event→Pub/Sub | Microservices→APIs -Testing[H:8]: TDD cycle|AAA pattern|Unit>Integration>E2E | Test all|Mock deps|Edge cases -Performance[H:7]: Measure→Profile→Optimize | Cache smart|Async I/O | Avoid: Premature opt|N+1 +Design: KISS[HIGH]: Simple>clever | YAGNI[MEDIUM]: Immediate only | SOLID[HIGH]: Single resp|Open/closed +DRY[MEDIUM]: Extract common|cfg>duplicate | Clean Code[CRITICAL]: Concise functions|Low complexity|Minimal nesting +Code Gen[CRITICAL]: NO comments unless asked | Short>long names | Minimal boilerplate +Docs[CRITICAL]: Bullets>paragraphs | Essential only | No "Overview"|"Introduction" +UltraCompressed[CRITICAL]: --uc flag | High context usage | Substantial reduction | Legend REQUIRED +Architecture[HIGH]: DDD: Bounded contexts|Aggregates|Events | Event→Pub/Sub | Microservices→APIs +Testing[HIGH]: TDD cycle|AAA pattern|Unit>Integration>E2E | Test all|Mock deps|Edge cases +Performance[HIGH]: Measure→Profile→Optimize | Cache smart|Async I/O | Avoid: Premature opt|N+1 ``` ## 7. Efficiency & Mgmt ```yaml -Context[C:9]: >60%→/compact | >90%→Force | Keep decisions|Remove redundant -Tokens[C:10]: Symbols>words|YAML>prose|Bullets>paragraphs | Remove the|that|which -Cost[H:8]: Simple→sonnet$ | Complex→sonnet4$$ | Critical→opus4$$$ | Response<4lines -Advanced: Orchestration[H:7]: Parallel|Shared context | Iterative[H:8]: Boomerang|Measure|Refine -Root Cause[H:7]: Five whys|Document|Prevent | Memory[M:6]: Store decisions|Share context -Automation[H:7-8]: Validate env|Error handling|Timeouts | CI/CD: Idempotent|Retry|Secure creds +Context[CRITICAL]: High usage→/compact | Very high→Force | Keep decisions|Remove redundant +Tokens[CRITICAL]: Symbols>words|YAML>prose|Bullets>paragraphs | Remove the|that|which +Cost[HIGH]: Simple→sonnet$ | Complex→sonnet4$$ | Critical→opus4$$$ | Concise responses +Advanced: Orchestration[HIGH]: Parallel|Shared context | Iterative[HIGH]: Boomerang|Measure|Refine +Root Cause[HIGH]: Five whys|Document|Prevent | Memory[MEDIUM]: Store decisions|Share context +Automation[HIGH]: Validate env|Error handling|Timeouts | CI/CD: Idempotent|Retry|Secure creds Integration: Security: shared/*.yml | Ambiguity: analyzer→clarify | shared/impl.yml ```