SuperClaude/Guides/behavioral-modes-guide.md

SuperClaude Behavioral Modes Guide 🧠

💡 The Simple Truth About Modes

You don't need to understand behavioral modes to use SuperClaude. They work automatically in the background, adapting how Claude Code behaves based on what you're trying to do.

Here's what actually happens:

• Type /sc:brainstorm "app idea" → Brainstorming mode kicks in with discovery questions 🤔
• Work on complex debugging → Introspection mode helps with systematic analysis 🔍
• Handle large refactoring → Task Management mode breaks it into coordinated steps 📋
• Need multiple tools → Orchestration mode picks the best ones automatically 🎯
• Context getting full → Token Efficiency mode compresses without losing meaning ⚡

Think of it like this: SuperClaude has different "personalities" that automatically show up when they'd be most helpful. You just work normally, and the right approach appears! ✨

---

TL;DR: Behavioral modes are SuperClaude's way of being smarter about how it helps you. They activate automatically. You don't manage them, they manage themselves.

---

🚀 Just Try These (See Modes in Action)

# Brainstorming Mode - Interactive discovery
/sc:brainstorm "task management app"     # → Gets curious, asks discovery questions

# Introspection Mode - Deep thinking
/sc:troubleshoot "weird auth behavior"   # → Analyzes reasoning patterns systematically

# Task Management Mode - Complex coordination  
/sc:implement user-dashboard             # → Breaks into phases, delegates subtasks

# Orchestration Mode - Smart tool selection
/sc:analyze large-codebase/              # → Picks best tools, coordinates efficiently  

# Token Efficiency Mode - Compressed communication
/sc:improve --uc legacy-code/            # → Uses symbols, abbreviations, stays clear

See the pattern? You just say what you want to do. SuperClaude figures out the best way to help. The modes are the "how" - you focus on the "what". See Examples Cookbook for more working examples. 🎯

---

The Five Behavioral Modes 🌟

🧠 Brainstorming Mode - Interactive Discovery

What it does: Turns SuperClaude into a collaborative discovery partner who helps you figure out what you actually want to build.

Automatic Activation 🪄

• Vague requests: "I want to build something...", "Maybe we could..."
• Exploration words: brainstorm, explore, discuss, figure out, not sure
• Uncertainty: "possibly", "thinking about", "could we"
• Manual trigger: --brainstorm or --bs

How It Changes SuperClaude 🔄

• Socratic Dialogue: Asks probing questions instead of jumping to solutions
• Non-Presumptive: Doesn't assume what you want, lets you guide discovery
• Collaborative: Partners with you rather than directing you
• Brief Generation: Turns conversations into structured requirement documents

Real Examples 📝

Standard response:

User: "I want to build a web app"
Claude: "I'll help you build a web application. What framework would you like to use?"

Brainstorming mode:

User: "I want to build a web app"
Claude: "🤔 Let's explore this together! Discovery questions:
         - What problem does this solve for your users?
         - Who are your target users and what are their main workflows?
         - What's your expected user volume and performance needs?
         - Any existing systems it needs to integrate with?
         - What's your timeline and technical constraints?
         
         📝 Once we explore these, I'll generate a structured brief for implementation!"

Perfect For 💫

• Early project planning and ideation
• Requirements discovery from vague ideas
• Turning "I need something that does..." into concrete specs
• Preventing scope creep through upfront exploration

---

🔍 Introspection Mode - Meta-Cognitive Analysis

What it does: Makes SuperClaude consciously analyze its own reasoning and decision-making process, especially when things go wrong or get complex.

Automatic Activation 🪄

• Self-analysis requests: "analyze my reasoning", "reflect on decision"
• Error recovery: When outcomes don't match expectations
• Complex problems: Multi-layered issues requiring conscious oversight
• Pattern recognition: Recurring behaviors or optimization needs
• Manual trigger: --introspect or --introspection

How It Changes SuperClaude 🔄

• Self-Examination: Consciously analyzes decision logic and reasoning chains
• Transparency: Exposes thinking with markers (🤔, 🎯, ⚡, 📊, 💡)
• Pattern Detection: Identifies recurring cognitive patterns and behaviors
• Learning Focus: Extracts insights for continuous improvement

Real Examples 📝

Standard response:

User: "The solution didn't work as expected"
Claude: "Let me look at the code and find the issue."

Introspection mode:

User: "The solution didn't work as expected"
Claude: "🎯 Decision Analysis: Expected X → got Y
         🔍 Pattern Check: Similar logic errors in auth.js:15, config.js:22
         📊 Framework Compliance: Missed validation step from quality gates
         🤔 Reasoning: Why did I choose async/await over promises here?
         💡 Insight: Need systematic validation before implementation
         
         Let me apply this learning to fix the current issue properly."

Perfect For 💫

• Debugging complex problems that require meta-thinking
• Understanding why certain approaches were chosen
• Learning from mistakes and improving patterns
• Framework compliance checking and optimization

---

📋 Task Management Mode - Orchestration & Delegation

What it does: Transforms SuperClaude into a project coordinator that breaks complex work into systematic phases and coordinates multiple sub-tasks efficiently.

Automatic Activation 🪄

• Multi-step operations: 3+ steps (build, implement, create, fix, refactor)
• Complex scope: system-wide, feature-complete, comprehensive changes
• File thresholds: >2 directories OR >3 files OR complexity >0.4
• Quality improvements: polish, refine, enhance keywords
• Manual triggers: --delegate, --loop, --concurrency

How It Changes SuperClaude 🔄

• Orchestration Mindset: Breaks complex work into coordinated layers
• Delegation Strategy: Parallel processing with intelligent sub-task routing
• State Management: Single focus protocol with real-time progress tracking
• Quality Gates: Evidence-based validation before task completion
• Progressive Systems: Systematic enhancement through compound intelligence

Real Examples 📝

Standard response:

User: "I need to refactor this authentication system"
Claude: "I'll refactor the authentication system for you."

Task Management mode:

User: "I need to refactor this authentication system"
Claude: "📋 Detected: system-wide auth refactor → delegation mode activated

         🔄 Phase 1: Security Analysis & Dependencies
         - Analyze current auth.js, middleware.js, session.js
         - Map security vulnerabilities and performance bottlenecks
         - Document current API contracts and integrations
         
         🔄 Phase 2: Core Implementation  
         - Refactor authentication logic with modern patterns
         - Update middleware for improved security
         - Enhance session management with proper cleanup
         
         🔄 Phase 3: Integration & Validation
         - Update all dependent components and routes
         - Run comprehensive security and integration tests
         - Performance benchmarking and optimization
         
         📊 Progress tracking: Each phase validates before proceeding
         ✅ Quality gates: Security, performance, compatibility checks"

Perfect For 💫

• Large refactoring projects that span multiple files
• Feature implementation requiring coordination
• System-wide changes that need careful orchestration
• Complex builds that benefit from parallel processing

---

🎯 Orchestration Mode - Intelligent Tool Selection

What it does: Optimizes SuperClaude's tool selection and resource usage, automatically choosing the most powerful and efficient approach for each task.

Automatic Activation 🪄

• Multi-tool operations: Tasks requiring coordination between different tools
• Performance constraints: >75% resource usage detected
• Parallel opportunities: >3 files or independent operations possible
• Complex routing: Multiple valid approaches available
• Manual trigger: --orchestrate

How It Changes SuperClaude 🔄

• Smart Tool Selection: Always chooses the most powerful tool for each task type
• Resource Awareness: Adapts approach based on system constraints
• Parallel Thinking: Identifies independent operations for concurrent execution
• Efficiency Focus: Optimizes for speed and effectiveness over familiarity

Tool Selection Matrix 🛠️

Task Type	Best Tool	Alternative	Why Better
UI components	Magic MCP	Manual coding	Modern patterns, accessibility
Deep analysis	Sequential MCP	Native reasoning	Structured multi-step thinking
Symbol operations	Serena MCP	Manual search	Semantic understanding
Pattern edits	Morphllm MCP	Individual edits	Bulk operations, consistency
Documentation	Context7 MCP	Web search	Official patterns, versioned
Browser testing	Playwright MCP	Unit tests	Real user interactions
Multi-file edits	MultiEdit	Sequential Edits	Atomic operations, rollback

Resource Management Zones 📊

🟢 Green Zone (0-75%)

• Full capabilities available
• Use all tools and features
• Normal verbosity and detail

🟡 Yellow Zone (75-85%)

• Activate efficiency mode
• Reduce verbosity intelligently
• Defer non-critical operations

🔴 Red Zone (85%+)

• Essential operations only
• Minimal output, maximum efficiency
• Fail fast on complex requests

Real Examples 📝

Standard response:

User: "/sc:analyze large-project/"
Claude: "I'll analyze your project files."
[Uses basic file reading and native analysis]

Orchestration mode:

User: "/sc:analyze large-project/"
Claude: "🎯 Orchestration: large-project analysis
         📊 Resource Status: 45% → Green Zone
         🛠️ Tool Selection Matrix:
         - File discovery: Glob (batch patterns)
         - Code analysis: Sequential MCP (structured reasoning)  
         - Documentation: Context7 MCP (framework patterns)
         - Parallel execution: 3 concurrent analysis threads
         
         ⚡ Executing optimized analysis workflow..."

Perfect For 💫

• Large codebases requiring efficient analysis
• Performance-critical operations
• Tasks benefiting from parallel processing
• Resource-constrained environments

---

⚡ Token Efficiency Mode - Compressed Communication

What it does: Transforms SuperClaude's communication style to use symbols, abbreviations, and compressed formats while preserving 95%+ of information quality.

Automatic Activation 🪄

• Context pressure: >75% context usage or resource constraints
• Large operations: Complex analysis workflows needing optimization
• User requests: --uc, --ultracompressed flags
• Efficiency needs: When speed and conciseness are priorities

How It Changes SuperClaude 🔄

• Symbol Communication: Visual symbols for logic, status, and technical domains
• Abbreviation Systems: Context-aware compression for technical terms
• 30-50% Compression: Significant token reduction while preserving meaning
• Structured Output: Bullet points, tables, concise explanations

Symbol Reference 🔤

Core Logic & Flow

• → leads to, implies (auth.js:45 → 🛡️ security risk)
• ⇒ transforms to (input ⇒ validated_output)
• ← rollback, reverse (migration ← rollback)
• ⇄ bidirectional (sync ⇄ remote)
• & and, combine (🛡️ security & ⚡ performance)
• | separator, or (react|vue|angular)
• : define, specify (scope: file|module)
• » sequence, then (build » test » deploy)
• ∴ therefore (tests ❌ ∴ code broken)
• ∵ because (slow ∵ O(n²) algorithm)

Status & Progress

• ✅ completed, passed
• ❌ failed, error
• ⚠️ warning, review needed
• 🔄 in progress
• ⏳ waiting, pending
• 🚨 critical, urgent

Technical Domains

• ⚡ Performance (speed, optimization)
• 🔍 Analysis (search, investigation)
• 🔧 Configuration (setup, tools)
• 🛡️ Security (protection, safety)
• 📦 Deployment (package, bundle)
• 🎨 Design (UI, frontend)
• 🏗️ Architecture (system structure)

Abbreviation Systems 📝

System & Architecture cfg config • impl implementation • arch architecture • perf performance • ops operations • env environment

Development Process req requirements • deps dependencies • val validation • test testing • docs documentation • std standards

Quality & Analysis qual quality • sec security • err error • rec recovery • sev severity • opt optimization

Real Examples 📝

Standard response:

User: "Analyze the authentication system performance"
Claude: "I'll analyze the authentication system's performance. The user validation function in auth.js line 45 has a security vulnerability. The build process completed successfully, now running tests, then deploying. Performance analysis shows the algorithm is slow because it's O(n²) complexity."

Token Efficiency mode:

User: "Analyze the authentication system performance"
Claude: "⚡ auth.js perf analysis:
         🛡️ auth.js:45 → sec risk in user val()
         📊 build ✅ » test 🔄 » deploy ⏳  
         🔍 perf: slow ∵ O(n²) algo
         
         ∴ rec: impl O(log n) lookup & fix sec val"

Perfect For 💫

• Large context situations requiring efficiency
• Complex analysis that would normally be verbose
• Performance-critical operations
• Users who prefer concise, information-dense output

---

How Modes Work Together 🤝

Mode Coordination Examples

Building a New Feature (Multiple Modes)

# Starts in Brainstorming Mode
/sc:brainstorm "user dashboard"
# 🧠 Discovery questions about requirements

# Transitions to Task Management Mode  
/sc:implement user-dashboard-feature
# 📋 Breaks into coordinated implementation phases

# Orchestration Mode kicks in for complex parts
# 🎯 Chooses best tools for UI (Magic MCP), testing (Playwright MCP)

# Token Efficiency if context gets full
# ⚡ Compresses communication while maintaining quality

Debugging Complex Issues

# Starts in Introspection Mode
/sc:troubleshoot "authentication randomly failing"
# 🔍 Systematic analysis of reasoning and patterns

# Orchestration Mode for tool selection
# 🎯 Uses Sequential MCP for structured investigation

# Task Management if solution is complex
# 📋 Coordinates fix across multiple files and systems

Mode Priority System 📊

1. User-Triggered (--brainstorm, --uc, etc.) - Always override automatic
2. Context-Critical (Token Efficiency when context >85%) - High priority
3. Task-Appropriate (Task Management for 3+ steps) - Standard priority
4. Enhancement (Orchestration for optimization) - Background priority

Mode Switching 🔄

Modes can:

• Layer together: Task Management + Orchestration + Token Efficiency
• Switch dynamically: Brainstorming → Task Management → Orchestration
• Enhance each other: Introspection + Task Management for better quality

---

Manual Control 🎛️

Force Specific Modes

# Force Brainstorming Mode
/sc:analyze --brainstorm project-requirements

# Force Token Efficiency
/sc:implement --uc user-authentication  

# Force Task Management
/sc:refactor --delegate large-codebase/

# Force Orchestration
/sc:build --orchestrate complex-project/

# Force Introspection
/sc:troubleshoot --introspect "reasoning issues"

# Disable all modes (baseline Claude)
/sc:analyze --no-modes legacy-code/

When to Use Manual Control 🤔

Force Brainstorming when:

• You have specific requirements but want to explore alternatives
• Working with stakeholders who need guided discovery
• Converting existing features into comprehensive specs

Force Token Efficiency when:

• Working in resource-constrained environments
• Need maximum information density
• Dealing with very large contexts

Force Task Management when:

• Want explicit task breakdown for complex work
• Need to coordinate multiple team members
• Require detailed progress tracking

Force Orchestration when:

• Performance is critical
• Want to see tool selection reasoning
• Working with multiple MCP servers

Force Introspection when:

• Learning how SuperClaude makes decisions
• Debugging framework behavior
• Want transparent reasoning for auditing

---

Real-World Scenarios 🌍

Scenario 1: Building a Task Management App

Phase 1: Discovery (Brainstorming Mode)

/sc:brainstorm "task management app for development teams"

# Mode activates automatically, provides discovery questions:
# - What problems do current tools not solve?
# - How do teams currently track tasks?
# - Integration needs with existing tools?
# - Expected team size and usage patterns?

# Result: Structured requirements brief ready for implementation

Phase 2: Implementation (Task Management Mode)

/sc:implement task-management-app --from-brief requirements.md

# Mode activates for complex implementation:
# Phase 1: Data models and API design
# Phase 2: Core functionality and business logic  
# Phase 3: UI components and user experience
# Phase 4: Integration, testing, and deployment

# Each phase validates before proceeding

Phase 3: Optimization (Orchestration + Token Efficiency)

/sc:improve performance task-management-app/

# Orchestration selects best tools for analysis
# Token Efficiency kicks in for large codebase analysis  
# Result: Optimized, production-ready application

Scenario 2: Debugging Authentication Issues

Investigation (Introspection Mode)

/sc:troubleshoot "users can't log in on mobile but desktop works"

# Introspection mode analyzes systematically:
# 🔍 Pattern analysis: Mobile vs desktop differences
# 🤔 Reasoning: What could cause platform-specific auth issues?
# 📊 Evidence gathering: Session handling, cookies, API calls
# 💡 Hypothesis formation and testing approach

Systematic Fix (Task Management + Orchestration)

/sc:implement auth-mobile-fix

# Task Management coordinates the fix:
# Phase 1: Mobile session analysis (Playwright MCP for testing)
# Phase 2: API compatibility fixes (Sequential MCP for logic)
# Phase 3: Cross-platform validation (multiple tools)

# Orchestration ensures optimal tool usage throughout

Scenario 3: Large Codebase Refactoring

Planning (Brainstorming + Introspection)

/sc:brainstorm "refactor legacy PHP app to modern architecture"

# Brainstorming explores scope and requirements
# Introspection analyzes current architecture patterns
# Result: Clear migration strategy and requirements

Execution (Task Management + Token Efficiency)

/sc:refactor --delegate legacy-app/ --target modern-architecture

# Task Management breaks into systematic phases
# Token Efficiency handles large codebase analysis efficiently
# Phase coordination ensures no breaking changes

---

FAQ 🙋

Do I need to understand behavioral modes?

No! They work automatically. You focus on what you want to do, modes handle how SuperClaude helps you. Think of them like having different experts who automatically step in when needed.

How do I know which mode is active?

Look for behavioral markers:

• 🤔 Questions and exploration = Brainstorming Mode
• 🔍 Reasoning analysis symbols = Introspection Mode
• 📋 Phase breakdowns and delegation = Task Management Mode
• 🎯 Tool selection matrices = Orchestration Mode
• ⚡ Symbols and abbreviations = Token Efficiency Mode

Can I disable behavioral modes?

Yes! Use --no-modes flag:

/sc:analyze --no-modes simple-file.js

This gives you baseline Claude behavior without mode enhancements.

Which mode should I use manually?

Usually none! Automatic activation works well 95% of the time. Manual control is for:

• Learning: Force modes to see how they work
• Special cases: Unusual requirements or constraints
• Team coordination: Explicit task breakdowns for collaboration
• Performance: Force efficiency in resource-constrained environments

Can multiple modes be active at once?

Yes! Modes often layer together:

• Task Management + Orchestration (complex projects with optimal tools)
• Introspection + Token Efficiency (deep analysis with compressed output)
• Brainstorming + Task Management (discovery → implementation pipeline)

Do modes work with all commands?

Most commands work with modes, but some have natural affinities:

• /sc:brainstorm → Always Brainstorming Mode
• /sc:troubleshoot → Often Introspection Mode
• /sc:implement (complex) → Usually Task Management Mode
• Large operations → Often trigger Orchestration Mode
• High context → May activate Token Efficiency Mode

Are modes related to agents?

Yes, but differently!

• Agents = Who helps (security-engineer, frontend-architect, etc.)
• Modes = How they help (systematically, efficiently, collaboratively)

Modes determine the behavioral approach, agents provide domain expertise. A security-engineer might work in Task Management mode for complex security implementations, or Introspection mode for security analysis.

---

Technical Reference 🔧

Complete Trigger Lists

Brainstorming Mode Triggers

• Keywords: brainstorm, explore, discuss, figure out, not sure, maybe, possibly, thinking about, could we
• Phrases: "I want to build...", "thinking about creating...", "not sure how to...", "maybe we could..."
• Context: Vague requirements, early planning, stakeholder discussions
• Manual: --brainstorm, --bs

Introspection Mode Triggers

• Keywords: analyze reasoning, reflect on, why did, decision logic, pattern check
• Context: Error recovery, unexpected results, complex problem solving, framework discussions
• Indicators: Multiple failed approaches, recurring issues, need for meta-analysis
• Manual: --introspect, --introspection

Task Management Mode Triggers

• Operations: build, implement, create, fix, refactor (3+ steps)
• Scope: system, feature, comprehensive, complete, end-to-end
• Thresholds: >2 directories OR >3 files OR complexity score >0.4
• Keywords: polish, refine, enhance, coordinate, manage
• Manual: --delegate, --loop, --concurrency

Orchestration Mode Triggers

• Conditions: Multi-tool operations, >3 files, parallel opportunities
• Performance: >75% resource usage, efficiency requirements
• Complexity: Multiple valid approaches, tool selection decisions
• Manual: --orchestrate

Token Efficiency Mode Triggers

• Resource: Context >75%, large-scale operations, memory constraints
• User requests: --uc, --ultracompressed, brevity requirements
• Workflow: Complex analysis needing optimization, high information density
• Manual: --uc, --ultracompressed, --token-efficient

Flag Reference Table 🏳️

Flag	Mode	Purpose	Usage
--brainstorm, --bs	Brainstorming	Force discovery mode	Requirements exploration
--introspect	Introspection	Force reasoning analysis	Decision transparency
--delegate	Task Management	Force delegation mode	Complex coordination
--delegate	Task Management	Enable delegation mode	Parallel processing
--loop	Task Management	Enable iteration cycles	Improvement workflows
--orchestrate	Orchestration	Force tool optimization	Performance priority
--uc, --ultracompressed	Token Efficiency	Force compression	Resource constraints
--no-modes	None	Disable all modes	Baseline behavior

Integration with Framework Components

With Agents 🤖

• Modes determine how agents work
• Agents provide domain expertise
• Example: security-engineer in Task Management mode = systematic security implementation

With Commands 🛠️

• Commands trigger mode activation
• Modes enhance command execution
• Example: /sc:implement complex features → Task Management mode activation

With MCP Servers 🔧

• Orchestration mode optimizes MCP usage
• Task Management coordinates multi-MCP operations
• Token Efficiency compresses MCP communications

Performance Metrics 📊

Mode Efficiency Gains

• Brainstorming: 60-80% better requirement clarity
• Introspection: 40-60% improved decision quality
• Task Management: 40-70% time savings via delegation
• Orchestration: 20-40% performance improvement via optimal tools
• Token Efficiency: 30-50% token reduction with 95%+ information preservation

Resource Impact

• Brainstorming: Low overhead, high value for unclear requirements
• Introspection: Medium overhead, high value for complex problems
• Task Management: Variable overhead, scales with task complexity
• Orchestration: Low overhead, improves overall efficiency
• Token Efficiency: Negative overhead (saves resources), maintains quality

---

Behavioral modes are SuperClaude's intelligence system - they make Claude Code smarter about how it helps you. You don't manage them, they manage themselves to give you the best experience! 🧠✨

---

Related Guides

🚀 Getting Started (Essential)

• SuperClaude User Guide - Framework overview and philosophy
• Examples Cookbook - See modes in action with real examples

🛠️ Working with Modes (Recommended)

• Commands Guide - Commands that trigger different modes
• Agents Guide - How agents work within different modes
• Session Management Guide - Mode persistence across sessions

⚙️ Control and Optimization (Advanced)

• Flags Guide - Manual mode control with flags like --brainstorm, --uc
• Best Practices Guide - Proven patterns for mode utilization
• Technical Architecture Guide - Mode detection and activation system

🔧 When Modes Don't Work as Expected

• Troubleshooting Guide - Mode activation and behavioral issues

📖 Recommended Learning Path:

1. Examples Cookbook - See auto-activation in practice
2. Commands Guide - Understand mode triggers
3. Best Practices Guide - Master mode coordination patterns