mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 17:56:46 +00:00

Revert "feat: comprehensive framework improvements (#447 )" (#453 )

This reverts commit 00706f0ea99aa04f54a3ddf5244738b0a9b37a91.

2025-10-21 09:48:41 +05:30

17 KiB

Raw Blame History

SuperClaude Installation CLI Improvements

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

🎯 Objectives

Speed: One-command installation without interactive prompts
Scriptability: CI/CD and automation-friendly
Clarity: Clear, self-documenting flags
Flexibility: Support both simple and advanced use cases
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

✅ Document CLI improvements proposal (this file)
⏳ Implement profile resolution logic
⏳ Add CLI argument parsing
⏳ Write unit tests for profile resolution
⏳ Write integration tests for installations
⏳ Run performance benchmarks (minimal, recommended, full)
⏳ Update documentation (README, CONTRIBUTING, installation guide)
⏳ Gather user feedback
⏳ 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

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.

17 KiB Raw Blame History