Initial commit

INSTALLATION.md

@@ -0,0 +1,332 @@
+# Installation Guide
+
+Step-by-step guide to installing and using the Bubble Tea Maintenance Agent.
+
+---
+
+## Prerequisites
+
+**Required:**
+- Python 3.8+
+- Claude Code CLI installed
+
+**Optional (for full functionality):**
+- `/Users/williamvansickleiii/charmtuitemplate/charm-tui-template/tip-bubbltea-apps.md`
+- `/Users/williamvansickleiii/charmtuitemplate/charm-tui-template/lipgloss-readme.md`
+
+---
+
+## Installation Steps
+
+### 1. Navigate to Agent Directory
+
+```bash
+cd /Users/williamvansickleiii/charmtuitemplate/vinw/bubbletea-designer/bubbletea-maintenance
+```
+
+### 2. Verify Files
+
+Check that all required files exist:
+
+```bash
+ls -la
+```
+
+You should see:
+- `.claude-plugin/marketplace.json`
+- `SKILL.md`
+- `README.md`
+- `scripts/` directory
+- `references/` directory
+- `tests/` directory
+
+### 3. Install the Agent
+
+```bash
+/plugin marketplace add .
+```
+
+Or from within Claude Code:
+
+```
+/plugin marketplace add /Users/williamvansickleiii/charmtuitemplate/vinw/bubbletea-designer/bubbletea-maintenance
+```
+
+### 4. Verify Installation
+
+The agent should now appear in your Claude Code plugins list:
+
+```
+/plugin list
+```
+
+Look for: `bubbletea-maintenance`
+
+---
+
+## Testing the Installation
+
+### Quick Test
+
+Ask Claude Code:
+
+```
+"Analyze my Bubble Tea app at /path/to/your/app"
+```
+
+The agent should activate and run a comprehensive analysis.
+
+### Detailed Test
+
+Run the test suite:
+
+```bash
+cd /Users/williamvansickleiii/charmtuitemplate/vinw/bubbletea-designer/bubbletea-maintenance
+python3 -m pytest tests/ -v
+```
+
+Expected output:
+```
+tests/test_diagnose_issue.py ✓✓✓✓
+tests/test_best_practices.py ✓✓✓✓
+tests/test_performance.py ✓✓✓✓
+tests/test_architecture.py ✓✓✓✓
+tests/test_layout.py ✓✓✓✓
+tests/test_integration.py ✓✓✓
+
+======================== XX passed in X.XXs ========================
+```
+
+---
+
+## Configuration
+
+### Setting Up Local References
+
+For full best practices validation, ensure these files exist:
+
+1. **tip-bubbltea-apps.md**
+   ```bash
+   ls /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/tip-bubbltea-apps.md
+   ```
+
+   If missing, the agent will still work but best practices validation will be limited.
+
+2. **lipgloss-readme.md**
+   ```bash
+   ls /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/lipgloss-readme.md
+   ```
+
+### Customizing Paths
+
+If your reference files are in different locations, update paths in:
+- `scripts/apply_best_practices.py` (line 16: `TIPS_FILE`)
+
+---
+
+## Usage Examples
+
+### Example 1: Diagnose Issues
+
+```
+User: "My Bubble Tea app is slow, diagnose issues"
+
+Agent: [Runs diagnose_issue()]
+Found 3 issues:
+1. CRITICAL: Blocking HTTP request in Update() (main.go:45)
+2. WARNING: Hardcoded terminal width (main.go:89)
+3. INFO: Consider model tree pattern for 18 fields
+
+[Provides fixes for each]
+```
+
+### Example 2: Check Best Practices
+
+```
+User: "Check if my TUI follows best practices"
+
+Agent: [Runs apply_best_practices()]
+Overall Score: 75/100
+
+✅ PASS: Fast event loop
+✅ PASS: Terminal recovery
+⚠️  FAIL: No debug message dumping
+⚠️  FAIL: No tests with teatest
+INFO: No VHS demos (optional)
+
+[Provides recommendations]
+```
+
+### Example 3: Comprehensive Analysis
+
+```
+User: "Run full analysis on ./myapp"
+
+Agent: [Runs comprehensive_bubbletea_analysis()]
+
+=================================================================
+COMPREHENSIVE BUBBLE TEA ANALYSIS
+=================================================================
+
+Overall Health: 78/100
+Summary: Good health. Some improvements recommended.
+
+Priority Fixes (5):
+
+🔴 CRITICAL (1):
+  1. [Performance] Blocking HTTP request in Update() (main.go:45)
+
+⚠️  WARNINGS (2):
+  2. [Best Practices] Missing debug message dumping
+  3. [Layout] Hardcoded dimensions in View()
+
+💡 INFO (2):
+  4. [Architecture] Consider model tree pattern
+  5. [Performance] Cache lipgloss styles
+
+Estimated Fix Time: 2-4 hours
+
+Full report saved to: ./bubbletea_analysis_report.json
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Agent Not Activating
+
+**Solution 1: Check Installation**
+```bash
+/plugin list
+```
+
+If not listed, reinstall:
+```bash
+/plugin marketplace add /path/to/bubbletea-maintenance
+```
+
+**Solution 2: Use Explicit Activation**
+
+Instead of:
+```
+"Analyze my Bubble Tea app"
+```
+
+Try:
+```
+"Use the bubbletea-maintenance agent to analyze my app"
+```
+
+### Issue: "No .go files found"
+
+**Cause**: Wrong path provided
+
+**Solution**: Use absolute path or verify path exists:
+```bash
+ls /path/to/your/app
+```
+
+### Issue: "tip-bubbltea-apps.md not found"
+
+**Impact**: Best practices validation will be limited
+
+**Solutions**:
+
+1. **Get the file**:
+   ```bash
+   # If you have charm-tui-template
+   ls /Users/williamvansickleiii/charmtuitemplate/charm-tui-template/tip-bubbltea-apps.md
+   ```
+
+2. **Update path** in `scripts/apply_best_practices.py`:
+   ```python
+   TIPS_FILE = Path("/your/custom/path/tip-bubbltea-apps.md")
+   ```
+
+3. **Or skip best practices**:
+   The other 5 functions still work without it.
+
+### Issue: Tests Failing
+
+**Check Python Version**:
+```bash
+python3 --version  # Should be 3.8+
+```
+
+**Install Test Dependencies**:
+```bash
+pip3 install pytest
+```
+
+**Run Individual Tests**:
+```bash
+python3 tests/test_diagnose_issue.py
+```
+
+### Issue: Permission Denied
+
+**Solution**: Make scripts executable:
+```bash
+chmod +x scripts/*.py
+```
+
+---
+
+## Uninstallation
+
+To remove the agent:
+
+```bash
+/plugin marketplace remove bubbletea-maintenance
+```
+
+Or manually delete the plugin directory:
+```bash
+rm -rf /path/to/bubbletea-maintenance
+```
+
+---
+
+## Upgrading
+
+### To v1.0.1+
+
+1. **Backup your config** (if you customized paths)
+2. **Remove old version**:
+   ```bash
+   /plugin marketplace remove bubbletea-maintenance
+   ```
+3. **Install new version**:
+   ```bash
+   cd /path/to/new/bubbletea-maintenance
+   /plugin marketplace add .
+   ```
+4. **Verify**:
+   ```bash
+   cat VERSION  # Should show new version
+   ```
+
+---
+
+## Support
+
+**Issues**: Check SKILL.md for detailed documentation
+
+**Questions**:
+- Read `references/common_issues.md` for solutions
+- Check CHANGELOG.md for known limitations
+
+---
+
+## Next Steps
+
+After installation:
+
+1. **Try it out**: Analyze one of your Bubble Tea apps
+2. **Read documentation**: Check references/ for guides
+3. **Run tests**: Ensure everything works
+4. **Customize**: Update paths if needed
+
+---
+
+**Built with Claude Code agent-creator on 2025-10-19**