465 lines
8.2 KiB
Markdown
465 lines
8.2 KiB
Markdown
# BMad Method - Maintenance & Troubleshooting Guide
|
|
|
|
**Version:** v6 Alpha
|
|
**Last Updated:** 2025-10-07
|
|
|
|
---
|
|
|
|
## 🔧 Maintenance Scripts
|
|
|
|
### Quick Health Check
|
|
```bash
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-doctor.sh
|
|
```
|
|
|
|
**Shows:**
|
|
- Installation status
|
|
- Installed modules
|
|
- Slash commands count
|
|
- Global aliases
|
|
- Environment variables
|
|
- Project workspaces
|
|
|
|
### Full Validation
|
|
```bash
|
|
bash /Users/hbl/Documents/BMAD-METHOD/validate-bmad-setup.sh
|
|
```
|
|
|
|
**Checks:**
|
|
- All 10 critical components
|
|
- Detailed error reporting
|
|
- Specific fix suggestions
|
|
|
|
### Update & Sync
|
|
```bash
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh
|
|
```
|
|
|
|
**Options:**
|
|
```bash
|
|
bmad-update.sh update # Full update (git pull + npm install + commands)
|
|
bmad-update.sh commands-only # Only sync slash commands
|
|
bmad-update.sh verify # Verify installation
|
|
bmad-update.sh backup # Create backup
|
|
bmad-update.sh restore # Restore from backup
|
|
```
|
|
|
|
---
|
|
|
|
## 🩹 Common Issues & Fixes
|
|
|
|
### Issue 1: Slash Commands Not Showing
|
|
|
|
**Symptoms:**
|
|
- Type `/` in Claude Code
|
|
- No `/bmad:*` commands appear
|
|
|
|
**Fix:**
|
|
```bash
|
|
# Option 1: Use update script
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh commands-only
|
|
|
|
# Option 2: Manual copy
|
|
cp -r /Users/hbl/Documents/BMAD-METHOD/.claude/commands/bmad ~/.claude/commands/
|
|
|
|
# Option 3: Restart Claude Code
|
|
# Close and reopen Claude Code application
|
|
```
|
|
|
|
**Verify:**
|
|
```bash
|
|
ls ~/.claude/commands/bmad
|
|
# Should show: bmm/ core/
|
|
```
|
|
|
|
---
|
|
|
|
### Issue 2: BMad CLI Not Working
|
|
|
|
**Symptoms:**
|
|
```bash
|
|
bmad status
|
|
# Output: command not found: bmad
|
|
```
|
|
|
|
**Fix:**
|
|
```bash
|
|
# 1. Check if alias exists
|
|
grep "alias bmad=" ~/.zshrc
|
|
|
|
# 2. If missing, add it
|
|
echo 'alias bmad="node /Users/hbl/Documents/BMAD-METHOD/tools/cli/bmad-cli.js"' >> ~/.zshrc
|
|
|
|
# 3. Reload shell
|
|
source ~/.zshrc
|
|
|
|
# 4. Test
|
|
bmad status
|
|
```
|
|
|
|
---
|
|
|
|
### Issue 3: Module Installation Failed
|
|
|
|
**Symptoms:**
|
|
- CIS or BMB module not showing after installation
|
|
- Installer completed but module missing
|
|
|
|
**Fix:**
|
|
```bash
|
|
# 1. Check manifest
|
|
cat /Users/hbl/Documents/BMAD-METHOD/bmad/_cfg/manifest.yaml
|
|
|
|
# 2. Re-run installer
|
|
cd /Users/hbl/Documents/BMAD-METHOD
|
|
npm run install:bmad
|
|
# Select missing modules
|
|
|
|
# 3. Verify
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-doctor.sh
|
|
```
|
|
|
|
---
|
|
|
|
### Issue 4: Project Workspace Not Detected
|
|
|
|
**Symptoms:**
|
|
- BMad commands don't work in project
|
|
- `.bmad/` folder exists but not recognized
|
|
|
|
**Fix:**
|
|
```bash
|
|
# 1. Verify workspace structure
|
|
cd /path/to/your/project
|
|
ls -la .bmad
|
|
|
|
# Should show:
|
|
# .bmad/
|
|
# .bmadrc
|
|
# analysis/
|
|
# planning/
|
|
# stories/
|
|
# etc.
|
|
|
|
# 2. Check configuration
|
|
cat .bmad/.bmadrc
|
|
|
|
# 3. Re-create if broken
|
|
bmad-init $(pwd)
|
|
```
|
|
|
|
---
|
|
|
|
### Issue 5: Environment Variables Not Loading
|
|
|
|
**Symptoms:**
|
|
- `echo $BMAD_HOME` returns empty
|
|
- BMad functions not available
|
|
|
|
**Fix:**
|
|
```bash
|
|
# 1. Check if .bmadrc exists
|
|
ls -la ~/.bmadrc
|
|
|
|
# 2. Check if sourced in .zshrc
|
|
grep "source ~/.bmadrc" ~/.zshrc
|
|
|
|
# 3. If missing, add it
|
|
echo '[ -f ~/.bmadrc ] && source ~/.bmadrc' >> ~/.zshrc
|
|
|
|
# 4. Reload
|
|
source ~/.zshrc
|
|
|
|
# 5. Verify
|
|
echo $BMAD_HOME
|
|
# Should output: /Users/hbl/Documents/BMAD-METHOD/bmad
|
|
```
|
|
|
|
---
|
|
|
|
### Issue 6: Outdated BMad Version
|
|
|
|
**Symptoms:**
|
|
- Missing features mentioned in docs
|
|
- Old workflow behavior
|
|
|
|
**Fix:**
|
|
```bash
|
|
# 1. Check current version
|
|
cat /Users/hbl/Documents/BMAD-METHOD/bmad/_cfg/manifest.yaml | grep version
|
|
|
|
# 2. Pull latest changes
|
|
cd /Users/hbl/Documents/BMAD-METHOD
|
|
git pull origin v6-alpha
|
|
|
|
# 3. Update everything
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh
|
|
|
|
# 4. Verify
|
|
bmad-doctor
|
|
```
|
|
|
|
---
|
|
|
|
### Issue 7: Slash Command Files Corrupted
|
|
|
|
**Symptoms:**
|
|
- Commands exist but don't work
|
|
- Error messages when activating agents
|
|
|
|
**Fix:**
|
|
```bash
|
|
# 1. Backup current commands
|
|
mv ~/.claude/commands/bmad ~/.claude/commands/bmad-backup-$(date +%Y%m%d)
|
|
|
|
# 2. Fresh copy
|
|
cp -r /Users/hbl/Documents/BMAD-METHOD/.claude/commands/bmad ~/.claude/commands/
|
|
|
|
# 3. Restart Claude Code
|
|
|
|
# 4. Test
|
|
# Type / and look for /bmad:* commands
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Regular Maintenance Schedule
|
|
|
|
### Weekly
|
|
```bash
|
|
# Quick health check
|
|
bmad-doctor
|
|
```
|
|
|
|
### Monthly
|
|
```bash
|
|
# Update to latest version
|
|
cd /Users/hbl/Documents/BMAD-METHOD
|
|
bash bmad-update.sh
|
|
```
|
|
|
|
### Before Major Work
|
|
```bash
|
|
# Create backup
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh backup
|
|
```
|
|
|
|
### After Alpha Updates
|
|
```bash
|
|
# Full update process
|
|
cd /Users/hbl/Documents/BMAD-METHOD
|
|
git pull origin v6-alpha
|
|
npm install
|
|
bash bmad-update.sh commands-only
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Diagnostic Commands
|
|
|
|
### Check Installation
|
|
```bash
|
|
ls -la /Users/hbl/Documents/BMAD-METHOD/bmad
|
|
```
|
|
|
|
### Count Modules
|
|
```bash
|
|
grep -A 10 "^modules:" /Users/hbl/Documents/BMAD-METHOD/bmad/_cfg/manifest.yaml
|
|
```
|
|
|
|
### Count Slash Commands
|
|
```bash
|
|
find ~/.claude/commands/bmad -name "*.md" | wc -l
|
|
```
|
|
|
|
### List All BMad Projects
|
|
```bash
|
|
bmad-list
|
|
# Or manually:
|
|
find /Users/hbl/Documents -name ".bmadrc" -type f 2>/dev/null | while read rc; do dirname "$rc"; done
|
|
```
|
|
|
|
### Check Subagents
|
|
```bash
|
|
ls ~/.claude/agents/bmad-*
|
|
```
|
|
|
|
---
|
|
|
|
## 🚨 Emergency Recovery
|
|
|
|
### Complete Reinstallation
|
|
|
|
If everything is broken:
|
|
|
|
```bash
|
|
# 1. Backup important project workspaces
|
|
cp -r /Users/hbl/Documents/pages-health/.bmad ~/bmad-backup-pages-health
|
|
|
|
# 2. Remove broken installation
|
|
rm -rf /Users/hbl/Documents/BMAD-METHOD/bmad
|
|
rm -rf ~/.claude/commands/bmad
|
|
rm -rf ~/.claude/agents/bmad-*
|
|
|
|
# 3. Fresh install
|
|
cd /Users/hbl/Documents/BMAD-METHOD
|
|
npm install
|
|
npm run install:bmad
|
|
|
|
# 4. Restore project workspaces
|
|
cp -r ~/bmad-backup-pages-health /Users/hbl/Documents/pages-health/.bmad
|
|
|
|
# 5. Verify
|
|
bash bmad-doctor.sh
|
|
```
|
|
|
|
### Restore from Backup
|
|
|
|
If you used `bmad-update.sh`:
|
|
|
|
```bash
|
|
# Restore last backup
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh restore
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Health Check Interpretation
|
|
|
|
### ✅ Healthy System
|
|
```
|
|
✓ Central BMad installation
|
|
✓ 6+ modules installed
|
|
✓ 60+ slash commands
|
|
✓ Global aliases configured
|
|
✓ Environment variables
|
|
✓ 1+ project workspace(s)
|
|
|
|
✅ BMad is healthy!
|
|
```
|
|
|
|
### ⚠️ Warnings (Functional)
|
|
```
|
|
✓ Central BMad installation
|
|
✓ 4 modules installed
|
|
⚠ CIS module missing
|
|
⚠ BMB module missing
|
|
✓ 44 slash commands
|
|
✓ Global aliases configured
|
|
✓ Environment variables
|
|
✓ 1 project workspace(s)
|
|
|
|
⚠️ BMad functional with 2 warning(s)
|
|
```
|
|
|
|
**Action:** Install missing modules
|
|
|
|
### ❌ Critical Issues
|
|
```
|
|
✗ Central BMad missing
|
|
✗ Slash commands missing
|
|
✗ Aliases missing
|
|
|
|
❌ Found 3 critical issue(s)
|
|
```
|
|
|
|
**Action:** Run full validation for detailed diagnostics
|
|
|
|
---
|
|
|
|
## 🆘 Getting Help
|
|
|
|
### Before Asking for Help
|
|
|
|
Run these diagnostics:
|
|
|
|
```bash
|
|
# 1. Health check
|
|
bash /Users/hbl/Documents/BMAD-METHOD/bmad-doctor.sh
|
|
|
|
# 2. Full validation
|
|
bash /Users/hbl/Documents/BMAD-METHOD/validate-bmad-setup.sh
|
|
|
|
# 3. Check version
|
|
cat /Users/hbl/Documents/BMAD-METHOD/bmad/_cfg/manifest.yaml
|
|
|
|
# 4. Check shell config
|
|
grep -A 5 "BMad" ~/.zshrc
|
|
|
|
# 5. Test CLI
|
|
node /Users/hbl/Documents/BMAD-METHOD/tools/cli/bmad-cli.js status
|
|
```
|
|
|
|
### Support Resources
|
|
|
|
1. **Documentation:**
|
|
- `/Users/hbl/Documents/BMAD-METHOD/SETUP-INSTRUCTIONS.md`
|
|
- `/Users/hbl/Documents/BMAD-METHOD/QUICK-REFERENCE.md`
|
|
- `/Users/hbl/Documents/BMAD-METHOD/OPTIMIZATION-CHECKLIST.md`
|
|
|
|
2. **Community:**
|
|
- Discord: https://discord.gg/gk8jAdXWmj
|
|
- GitHub Issues: https://github.com/bmad-code-org/BMAD-METHOD/issues
|
|
|
|
3. **Alpha Release Notes:**
|
|
- Check: `/Users/hbl/Documents/BMAD-METHOD/v6-open-items.md`
|
|
|
|
---
|
|
|
|
## 📝 Logging & Debugging
|
|
|
|
### Enable Verbose Logging
|
|
|
|
```bash
|
|
# Set debug mode
|
|
export BMAD_DEBUG=true
|
|
|
|
# Run command
|
|
bmad status
|
|
|
|
# Disable debug mode
|
|
unset BMAD_DEBUG
|
|
```
|
|
|
|
### Check npm Logs
|
|
|
|
```bash
|
|
# If installation fails
|
|
npm install --loglevel verbose
|
|
```
|
|
|
|
### Git Status
|
|
|
|
```bash
|
|
cd /Users/hbl/Documents/BMAD-METHOD
|
|
git status
|
|
git log --oneline -5
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ Maintenance Checklist
|
|
|
|
Before starting work:
|
|
- [ ] Run `bmad-doctor`
|
|
- [ ] Check for updates (`git pull`)
|
|
- [ ] Verify slash commands working
|
|
- [ ] Test in a project: `cd project && claude-code .`
|
|
|
|
After updates:
|
|
- [ ] Run `bmad-update.sh`
|
|
- [ ] Verify installation: `bmad-doctor`
|
|
- [ ] Test slash commands in Claude Code
|
|
- [ ] Update project workspaces if needed
|
|
|
|
When troubleshooting:
|
|
- [ ] Run full validation
|
|
- [ ] Check all diagnostics
|
|
- [ ] Try manual fixes
|
|
- [ ] Create backup before major changes
|
|
- [ ] Document what worked
|
|
|
|
---
|
|
|
|
**BMad v6 Alpha** | Maintenance Guide
|