SuperClaude/docs/Development/cli-install-improvements.md

SuperClaude Installation CLI Improvements

Date: 2025-10-17 Status: Proposed Enhancement Goal: Replace interactive prompts with efficient CLI flags for better developer experience

🎯 Objectives

1. Speed: One-command installation without interactive prompts
2. Scriptability: CI/CD and automation-friendly
3. Clarity: Clear, self-documenting flags
4. Flexibility: Support both simple and advanced use cases
5. Backward Compatibility: Keep interactive mode as fallback

🚨 Current Problems

Problem 1: Slow Interactive Flow

# Current: Interactive (slow, manual)
$ uv run superclaude install

Stage 1: MCP Server Selection (Optional)
  Select MCP servers to configure:
  1. [ ] sequential-thinking
  2. [ ] context7
  ...
  > [user must manually select]

Stage 2: Framework Component Selection
  Select components (Core is recommended):
  1. [ ] core
  2. [ ] modes
  ...
  > [user must manually select again]

# Total time: ~60 seconds of clicking
# Automation: Impossible (requires human interaction)

Problem 2: Ambiguous Recommendations

Stage 2: "Select components (Core is recommended):"

User Confusion:
  - Does "Core" include everything needed?
  - What about mcp_docs? Is it needed?
  - Should I select "all" instead?
  - What's the difference between "recommended" and "Core"?

Problem 3: No Quick Profiles

# User wants: "Just install everything I need to get started"
# Current solution: Select ~8 checkboxes manually across 2 stages
# Better solution: `--recommended` flag

✅ Proposed Solution

New CLI Flags

# Installation Profiles (Quick Start)
--minimal           # Minimal installation (core only)
--recommended       # Recommended for most users (complete working setup)
--all               # Install everything (all components + all MCP servers)

# Explicit Component Selection
--components NAMES  # Specific components (space-separated)
--mcp-servers NAMES # Specific MCP servers (space-separated)

# Interactive Override
--interactive       # Force interactive mode (default if no flags)
--yes, -y           # Auto-confirm (skip confirmation prompts)

# Examples
uv run superclaude install --recommended
uv run superclaude install --minimal
uv run superclaude install --all
uv run superclaude install --components core modes --mcp-servers airis-mcp-gateway

📋 Profile Definitions

Profile 1: Minimal

Profile: minimal
Purpose: Testing, development, minimal footprint
Components:
  - core
MCP Servers:
  - None
Use Cases:
  - Quick testing
  - CI/CD pipelines
  - Minimal installations
  - Development environments
Estimated Size: ~5 MB
Estimated Tokens: ~50K

Profile 2: Recommended (DEFAULT for --recommended)

Profile: recommended
Purpose: Complete working installation for most users
Components:
  - core
  - modes (7 behavioral modes)
  - commands (slash commands)
  - agents (15 specialized agents)
  - mcp_docs (documentation for MCP servers)
MCP Servers:
  - airis-mcp-gateway (dynamic tool loading, zero-token baseline)
Use Cases:
  - First-time installation
  - Production use
  - Recommended for 90% of users
Estimated Size: ~30 MB
Estimated Tokens: ~150K
Rationale:
  - Complete PM Agent functionality (sub-agent delegation)
  - Zero-token baseline with airis-mcp-gateway
  - All essential features included
  - No missing dependencies

Profile 3: Full

Profile: full
Purpose: Install everything available
Components:
  - core
  - modes
  - commands
  - agents
  - mcp
  - mcp_docs
MCP Servers:
  - airis-mcp-gateway
  - sequential-thinking
  - context7
  - magic
  - playwright
  - serena
  - morphllm-fast-apply
  - tavily
  - chrome-devtools
Use Cases:
  - Power users
  - Comprehensive installations
  - Testing all features
Estimated Size: ~50 MB
Estimated Tokens: ~250K

🔧 Implementation Changes

File: setup/cli/commands/install.py

Change 1: Add Profile Arguments

# Line ~64 (after --components argument)

parser.add_argument(
    "--minimal",
    action="store_true",
    help="Minimal installation (core only, no MCP servers)"
)

parser.add_argument(
    "--recommended",
    action="store_true",
    help="Recommended installation (core + modes + commands + agents + mcp_docs + airis-mcp-gateway)"
)

parser.add_argument(
    "--all",
    action="store_true",
    help="Install all components and all MCP servers"
)

parser.add_argument(
    "--mcp-servers",
    type=str,
    nargs="+",
    help="Specific MCP servers to install (space-separated list)"
)

parser.add_argument(
    "--interactive",
    action="store_true",
    help="Force interactive mode (default if no profile flags)"
)

Change 2: Profile Resolution Logic

# Add new function after line ~172

def resolve_profile(args: argparse.Namespace) -> tuple[List[str], List[str]]:
    """
    Resolve installation profile from CLI arguments

    Returns:
        (components, mcp_servers)
    """

    # Check for conflicting profiles
    profile_flags = [args.minimal, args.recommended, args.all]
    if sum(profile_flags) > 1:
        raise ValueError("Only one profile flag can be specified: --minimal, --recommended, or --all")

    # Minimal profile
    if args.minimal:
        return ["core"], []

    # Recommended profile (default for --recommended)
    if args.recommended:
        return (
            ["core", "modes", "commands", "agents", "mcp_docs"],
            ["airis-mcp-gateway"]
        )

    # Full profile
    if args.all:
        components = ["core", "modes", "commands", "agents", "mcp", "mcp_docs"]
        mcp_servers = [
            "airis-mcp-gateway",
            "sequential-thinking",
            "context7",
            "magic",
            "playwright",
            "serena",
            "morphllm-fast-apply",
            "tavily",
            "chrome-devtools"
        ]
        return components, mcp_servers

    # Explicit component selection
    if args.components:
        components = args.components if isinstance(args.components, list) else [args.components]
        mcp_servers = args.mcp_servers if args.mcp_servers else []

        # Auto-include mcp_docs if any MCP servers selected
        if mcp_servers and "mcp_docs" not in components:
            components.append("mcp_docs")
            logger.info("Auto-included mcp_docs for MCP server documentation")

        # Auto-include mcp component if MCP servers selected
        if mcp_servers and "mcp" not in components:
            components.append("mcp")
            logger.info("Auto-included mcp component for MCP server support")

        return components, mcp_servers

    # No profile specified: return None to trigger interactive mode
    return None, None

Change 3: Update get_components_to_install

# Modify function at line ~126

def get_components_to_install(
    args: argparse.Namespace, registry: ComponentRegistry, config_manager: ConfigService
) -> Optional[List[str]]:
    """Determine which components to install"""
    logger = get_logger()

    # Try to resolve from profile flags first
    components, mcp_servers = resolve_profile(args)

    if components is not None:
        # Profile resolved, store MCP servers in config
        if not hasattr(config_manager, "_installation_context"):
            config_manager._installation_context = {}
        config_manager._installation_context["selected_mcp_servers"] = mcp_servers

        logger.info(f"Profile selected: {len(components)} components, {len(mcp_servers)} MCP servers")
        return components

    # No profile flags: fall back to interactive mode
    if args.interactive or not (args.minimal or args.recommended or args.all or args.components):
        return interactive_component_selection(registry, config_manager)

    # Should not reach here
    return None

📖 Updated Documentation

README.md Installation Section

## Installation

### Quick Start (Recommended)
```bash
# One-command installation with everything you need
uv run superclaude install --recommended

This installs:

• Core framework
• 7 behavioral modes
• SuperClaude slash commands
• 15 specialized AI agents
• airis-mcp-gateway (zero-token baseline)
• Complete documentation

Installation Profiles

Minimal (testing/development):

uv run superclaude install --minimal

Recommended (most users):

uv run superclaude install --recommended

Full (power users):

uv run superclaude install --all

Custom Installation

Select specific components:

uv run superclaude install --components core modes commands

Select specific MCP servers:

uv run superclaude install --components core mcp_docs --mcp-servers airis-mcp-gateway context7

Interactive Mode

If you prefer the guided installation:

uv run superclaude install --interactive

Automation (CI/CD)

For automated installations:

uv run superclaude install --recommended --yes

The --yes flag skips confirmation prompts.

### CONTRIBUTING.md Developer Quickstart
```markdown
## Developer Setup

### Quick Setup
```bash
# Clone repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework

# Install development dependencies
uv sync

# Run tests
pytest tests/ -v

# Install SuperClaude (recommended profile)
uv run superclaude install --recommended

Testing Different Profiles

# Test minimal installation
uv run superclaude install --minimal --install-dir /tmp/test-minimal

# Test recommended installation
uv run superclaude install --recommended --install-dir /tmp/test-recommended

# Test full installation
uv run superclaude install --all --install-dir /tmp/test-full

Performance Benchmarking

# Run installation performance benchmarks
pytest tests/performance/test_installation_performance.py -v --benchmark

# Compare profiles
pytest tests/performance/test_installation_performance.py::test_compare_profiles -v

## 🎯 User Experience Improvements

### Before (Current)
```bash
$ uv run superclaude install
[Interactive Stage 1: MCP selection]
[User clicks through options]
[Interactive Stage 2: Component selection]
[User clicks through options again]
[Confirmation prompt]
[Installation starts]

Time: ~60 seconds of user interaction
Scriptable: No
Clear expectations: Ambiguous ("Core is recommended" unclear)

After (Proposed)

$ uv run superclaude install --recommended
[Installation starts immediately]
[Progress bar shown]
[Installation complete]

Time: 0 seconds of user interaction
Scriptable: Yes
Clear expectations: Yes (documented profile)

Comparison Table

Aspect	Current (Interactive)	Proposed (CLI Flags)
User Interaction Time	~60 seconds	0 seconds
Scriptable	No	Yes
CI/CD Friendly	No	Yes
Clear Expectations	Ambiguous	Well-documented
One-Command Install	No	Yes
Automation	Impossible	Easy
Profile Comparison	Manual	Benchmarked

🧪 Testing Plan

Unit Tests

# tests/test_install_cli_flags.py

def test_profile_minimal():
    """Test --minimal flag"""
    args = parse_args(["install", "--minimal"])
    components, mcp_servers = resolve_profile(args)

    assert components == ["core"]
    assert mcp_servers == []

def test_profile_recommended():
    """Test --recommended flag"""
    args = parse_args(["install", "--recommended"])
    components, mcp_servers = resolve_profile(args)

    assert "core" in components
    assert "modes" in components
    assert "commands" in components
    assert "agents" in components
    assert "mcp_docs" in components
    assert "airis-mcp-gateway" in mcp_servers

def test_profile_full():
    """Test --all flag"""
    args = parse_args(["install", "--all"])
    components, mcp_servers = resolve_profile(args)

    assert len(components) == 6  # All components
    assert len(mcp_servers) >= 5  # All MCP servers

def test_profile_conflict():
    """Test conflicting profile flags"""
    with pytest.raises(ValueError):
        args = parse_args(["install", "--minimal", "--recommended"])
        resolve_profile(args)

def test_explicit_components_auto_mcp_docs():
    """Test auto-inclusion of mcp_docs when MCP servers selected"""
    args = parse_args([
        "install",
        "--components", "core", "modes",
        "--mcp-servers", "airis-mcp-gateway"
    ])
    components, mcp_servers = resolve_profile(args)

    assert "core" in components
    assert "modes" in components
    assert "mcp_docs" in components  # Auto-included
    assert "mcp" in components  # Auto-included
    assert "airis-mcp-gateway" in mcp_servers

Integration Tests

# tests/integration/test_install_profiles.py

def test_install_minimal_profile(tmp_path):
    """Test full installation with --minimal"""
    install_dir = tmp_path / "minimal"

    result = subprocess.run(
        ["uv", "run", "superclaude", "install", "--minimal", "--install-dir", str(install_dir), "--yes"],
        capture_output=True,
        text=True
    )

    assert result.returncode == 0
    assert (install_dir / "CLAUDE.md").exists()
    assert (install_dir / "core").exists() or len(list(install_dir.glob("*.md"))) > 0

def test_install_recommended_profile(tmp_path):
    """Test full installation with --recommended"""
    install_dir = tmp_path / "recommended"

    result = subprocess.run(
        ["uv", "run", "superclaude", "install", "--recommended", "--install-dir", str(install_dir), "--yes"],
        capture_output=True,
        text=True
    )

    assert result.returncode == 0
    assert (install_dir / "CLAUDE.md").exists()

    # Verify key components installed
    assert any(p.match("*MODE_*.md") for p in install_dir.glob("**/*.md"))  # Modes
    assert any(p.match("MCP_*.md") for p in install_dir.glob("**/*.md"))  # MCP docs

Performance Tests

# Use existing benchmark suite
pytest tests/performance/test_installation_performance.py -v

# Expected results:
# - minimal: ~5 MB, ~50K tokens
# - recommended: ~30 MB, ~150K tokens (3x minimal)
# - full: ~50 MB, ~250K tokens (5x minimal)

📋 Migration Path

Phase 1: Add CLI Flags (Backward Compatible)

Changes:
  - Add --minimal, --recommended, --all flags
  - Add --mcp-servers flag
  - Keep interactive mode as default
  - No breaking changes

Testing:
  - Run all existing tests (should pass)
  - Add new tests for CLI flags
  - Performance benchmarks

Release: v4.2.0 (minor version bump)

Phase 2: Update Documentation

Changes:
  - Update README.md with new flags
  - Update CONTRIBUTING.md with quickstart
  - Add installation guide (docs/installation-guide.md)
  - Update examples

Release: v4.2.1 (patch)

Phase 3: Promote CLI Flags (Optional)

Changes:
  - Make --recommended default if no args
  - Keep interactive available via --interactive flag
  - Update CLI help text

Testing:
  - User feedback collection
  - A/B testing (if possible)

Release: v4.3.0 (minor version bump)

🎯 Success Metrics

Quantitative Metrics

Installation Time:
  Current (Interactive): ~60 seconds of user interaction
  Target (CLI Flags): ~0 seconds of user interaction
  Goal: 100% reduction in manual interaction time

Scriptability:
  Current: 0% (requires human interaction)
  Target: 100% (fully scriptable)

CI/CD Adoption:
  Current: Not possible
  Target: >50% of automated deployments use CLI flags

Qualitative Metrics

User Satisfaction:
  Survey question: "How satisfied are you with the installation process?"
  Target: >90% satisfied or very satisfied

Clarity:
  Survey question: "Did you understand what would be installed?"
  Target: >95% clear understanding

Recommendation:
  Survey question: "Would you recommend this installation method?"
  Target: >90% would recommend

🚀 Next Steps

1. ✅ Document CLI improvements proposal (this file)
2. ⏳ Implement profile resolution logic
3. ⏳ Add CLI argument parsing
4. ⏳ Write unit tests for profile resolution
5. ⏳ Write integration tests for installations
6. ⏳ Run performance benchmarks (minimal, recommended, full)
7. ⏳ Update documentation (README, CONTRIBUTING, installation guide)
8. ⏳ Gather user feedback
9. ⏳ Prepare Pull Request with evidence

📊 Pull Request Checklist

Before submitting PR:

• All new CLI flags implemented
• Profile resolution logic added
• Unit tests written and passing (>90% coverage)
• Integration tests written and passing
• Performance benchmarks run (results documented)
• Documentation updated (README, CONTRIBUTING, installation guide)
• Backward compatibility maintained (interactive mode still works)
• No breaking changes
• User feedback collected (if possible)
• Examples tested manually
• CI/CD pipeline tested

📚 Related Documents

• Installation Process Analysis
• Performance Benchmark Suite
• PM Agent Parallel Architecture

---

Conclusion: CLI flags will dramatically improve the installation experience, making it faster, scriptable, and more suitable for CI/CD workflows. The recommended profile provides a clear, well-documented default that works for 90% of users while maintaining flexibility for advanced use cases.

User Benefit: One-command installation (--recommended) with zero interaction time, clear expectations, and full scriptability for automation.