SuperClaude/Templates/Template_Flag.md

[Flag Name] Flag

--[flag-name] / --[alias] (if applicable)

Metadata

name: --[flag-name]
aliases: [--[alias1], --[alias2]]  # Optional
category: [Planning|Efficiency|MCP Control|Delegation|Scope|Focus|Iteration|Introspection]
priority: [1-10]  # Higher number = higher precedence
token_impact: [low|medium|high|variable]

Purpose

[One-line description of what this flag does and when to use it]

Behavior

[Detailed explanation of flag behavior in 2-3 sentences. Include what happens when the flag is active, any side effects, and performance implications.]

Auto-Activation Rules

Conditions:

• [Condition 1 that triggers auto-activation]
• [Condition 2 that triggers auto-activation]
• [Threshold or metric if applicable]

Detection Patterns:

• Keywords: [keyword1], [keyword2], [keyword3]
• File patterns: [pattern1], [pattern2]
• Complexity indicators: [describe complexity metrics]
• Resource thresholds: [describe resource conditions]

Precedence: [Describe any special precedence rules]

Token Impact

• Base Usage: [Estimated token usage]
• Scaling Factor: [How usage scales with project size]
• Optimization: [Any token-saving features when active]

Conflicts & Resolution

Incompatible With:

• --[flag1]: [Reason for incompatibility]
• --[flag2]: [Reason for incompatibility]

Resolution Strategy:

1. [Step 1 for conflict resolution]
2. [Step 2 for conflict resolution]

Overrides:

• Overridden by: --[higher-priority-flag]
• Overrides: --[lower-priority-flag]

Integration Points

Compatible Commands

• /sc:[command1] - [How the flag enhances this command]
• /sc:[command2] - [How the flag enhances this command]
• /sc:[command3] - [How the flag enhances this command]

MCP Servers

• [Server Name]: [How this flag interacts with the server]
• [Server Name]: [How this flag interacts with the server]

Synergistic Flags

• --[flag1]: [How they work together]
• --[flag2]: [How they work together]

Usage Examples

Basic Usage

claude "your request here" --[flag-name]

With Parameters (if applicable)

claude "your request here" --[flag-name] [parameter]

Combined with Other Flags

claude "your request here" --[flag-name] --[other-flag]

Real-World Scenario

# [Describe a real use case]
claude "[specific request example]" --[flag-name]

Implementation Notes

Performance Considerations:

• [Note about performance impact]
• [Resource usage patterns]

Best Practices:

• [When to use this flag]
• [When NOT to use this flag]
• [Common pitfalls to avoid]

---

Flag Template Usage Guide

Overview

This template provides a standardized format for documenting flags in the SuperClaude framework. Each flag should have its own section in FLAGS.md following this structure.

Creating a New Flag

1. Choose Appropriate Naming

• Use lowercase with hyphens: --flag-name
• Be descriptive but concise
• Consider aliases for common variations
• Examples: --think-hard, --safe-mode, --wave-mode

2. Select Category

Choose from these standard categories:

• Planning & Analysis: Thinking modes, analysis depth
• Compression & Efficiency: Token optimization, output control
• MCP Control: Server activation/deactivation
• Delegation: Sub-agent and task distribution
• Scope & Focus: Operation boundaries and domains
• Iteration: Loop and refinement controls
• Wave Orchestration: Multi-stage execution
• Introspection: Transparency and debugging

3. Set Priority (1-10)

Priority determines precedence in conflicts:

• 10: Safety flags (--safe-mode)
• 8-9: Explicit user flags
• 6-7: Performance and efficiency flags
• 4-5: Feature flags
• 1-3: Convenience flags

4. Define Auto-Activation

Specify clear, measurable conditions:

• Threshold-based: "complexity > 0.7"
• Count-based: "files > 50"
• Pattern-based: "import statements detected"
• Composite: "complexity > 0.8 AND domains > 2"

5. Document Token Impact

Classify token usage:

• Low: <1K additional tokens
• Medium: 1K-10K additional tokens
• High: 10K+ additional tokens
• Variable: Depends on operation scope

Best Practices

Do's

✅ Provide clear auto-activation conditions ✅ Document all conflicts explicitly ✅ Include real-world usage examples ✅ Specify token impact estimates ✅ List integration points comprehensively ✅ Test flag interactions thoroughly

Don'ts

❌ Create overlapping flags without clear differentiation ❌ Use vague auto-activation conditions ❌ Ignore precedence rules ❌ Forget to update integration sections ❌ Skip conflict resolution documentation

Testing Your Flag

1. Manual Testing

# Test basic functionality
claude "test request" --your-flag

# Test with parameters
claude "test request" --your-flag parameter

# Test combinations
claude "test request" --your-flag --other-flag

2. Auto-Activation Testing

• Create scenarios that should trigger activation
• Verify activation occurs at correct thresholds
• Ensure no false positives

3. Conflict Testing

• Test with known incompatible flags
• Verify resolution strategy works
• Check precedence ordering

4. Integration Testing

• Test with relevant commands
• Verify MCP server interactions
• Check synergistic flag combinations

Common Flag Patterns

Analysis Flags

category: Planning & Analysis
auto_activation: complexity-based
token_impact: high
integrates_with: Sequential MCP

Control Flags

category: MCP Control
auto_activation: context-based
token_impact: variable
conflicts_with: opposite controls

Performance Flags

category: Efficiency
auto_activation: resource-based
token_impact: reduces overall
integrates_with: all operations

Safety Flags

category: Safety
priority: 10
auto_activation: risk-based
overrides: most other flags

Flag Categories Reference

Category	Purpose	Common Patterns
Planning & Analysis	Deep thinking modes	--think, --analyze
Efficiency	Token optimization	--uc, --compress
MCP Control	Server management	--seq, --no-mcp
Delegation	Task distribution	--delegate, --concurrency
Scope	Operation boundaries	--scope, --focus
Iteration	Refinement loops	--loop, --iterations
Wave	Multi-stage execution	--wave-mode, --wave-strategy
Introspection	Debugging/transparency	--introspect, --debug

Integration with FLAGS.md

When adding a new flag to FLAGS.md:

1. Find the appropriate section based on category
2. Maintain alphabetical order within sections
3. Update the Flag System Architecture if introducing new concepts
4. Add to Integration Patterns section if relevant
5. Update any affected precedence rules

Version Compatibility

• Document which version introduced the flag
• Note any breaking changes in behavior
• Specify minimum Claude Code version required
• List deprecated flags this replaces (if any)

Examples of Well-Documented Flags

Example 1: Thinking Flag

**`--think`**
- Multi-file analysis (~4K tokens)
- Enables Sequential MCP for structured problem-solving
- Auto-activates: Import chains >5 files, cross-module calls >10 references
- Auto-enables `--seq` for systematic analysis

Example 2: Delegation Flag

**`--delegate [files|folders|auto]`**
- Enable Task tool sub-agent delegation for parallel processing
- **files**: Delegate individual file analysis to sub-agents
- **folders**: Delegate directory-level analysis to sub-agents  
- **auto**: Auto-detect delegation strategy based on scope and complexity
- Auto-activates: >7 directories or >50 files
- 40-70% time savings for suitable operations

Example 3: Safety Flag

**`--safe-mode`**
- Maximum validation with conservative execution
- Auto-activates: Resource usage >85% or production environment
- Enables validation checks, forces --uc mode, blocks risky operations

---

This template ensures consistent, comprehensive documentation for all SuperClaude flags, making them easy to understand, implement, and maintain.