mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-17 17:56:46 +00:00
659 lines
17 KiB
Markdown
659 lines
17 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```yaml
|
|
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)
|
|
```yaml
|
|
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
|
|
```yaml
|
|
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
|
|
```python
|
|
# 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
|
|
```python
|
|
# 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`
|
|
```python
|
|
# 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
|
|
```markdown
|
|
## 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):
|
|
```bash
|
|
uv run superclaude install --minimal
|
|
```
|
|
|
|
**Recommended** (most users):
|
|
```bash
|
|
uv run superclaude install --recommended
|
|
```
|
|
|
|
**Full** (power users):
|
|
```bash
|
|
uv run superclaude install --all
|
|
```
|
|
|
|
### Custom Installation
|
|
|
|
Select specific components:
|
|
```bash
|
|
uv run superclaude install --components core modes commands
|
|
```
|
|
|
|
Select specific MCP servers:
|
|
```bash
|
|
uv run superclaude install --components core mcp_docs --mcp-servers airis-mcp-gateway context7
|
|
```
|
|
|
|
### Interactive Mode
|
|
|
|
If you prefer the guided installation:
|
|
```bash
|
|
uv run superclaude install --interactive
|
|
```
|
|
|
|
### Automation (CI/CD)
|
|
|
|
For automated installations:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
$ 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
|
|
```python
|
|
# 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
|
|
```python
|
|
# 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
|
|
```bash
|
|
# 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)
|
|
```yaml
|
|
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
|
|
```yaml
|
|
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)
|
|
```yaml
|
|
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
|
|
```yaml
|
|
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
|
|
```yaml
|
|
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](./install-process-analysis.md)
|
|
- [Performance Benchmark Suite](../../tests/performance/test_installation_performance.py)
|
|
- [PM Agent Parallel Architecture](./pm-agent-parallel-architecture.md)
|
|
|
|
---
|
|
|
|
**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.
|