ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/MAINTENANCE-GUIDE.md

8.2 KiB
Raw Blame History

BMad Method - Maintenance & Troubleshooting Guide

Version: v6 Alpha Last Updated: 2025-10-07

🔧 Maintenance Scripts

Quick Health Check

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 /Users/hbl/Documents/BMAD-METHOD/validate-bmad-setup.sh

Checks:

  • All 10 critical components
  • Detailed error reporting
  • Specific fix suggestions

Update & Sync

bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh

Options:

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:

# 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:

ls ~/.claude/commands/bmad
# Should show: bmm/ core/

Issue 2: BMad CLI Not Working

Symptoms:

bmad status
# Output: command not found: bmad

Fix:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# Quick health check
bmad-doctor

Monthly

# Update to latest version
cd /Users/hbl/Documents/BMAD-METHOD
bash bmad-update.sh

Before Major Work

# Create backup
bash /Users/hbl/Documents/BMAD-METHOD/bmad-update.sh backup

After Alpha Updates

# 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

ls -la /Users/hbl/Documents/BMAD-METHOD/bmad

Count Modules

grep -A 10 "^modules:" /Users/hbl/Documents/BMAD-METHOD/bmad/_cfg/manifest.yaml

Count Slash Commands

find ~/.claude/commands/bmad -name "*.md" | wc -l

List All BMad Projects

bmad-list
# Or manually:
find /Users/hbl/Documents -name ".bmadrc" -type f 2>/dev/null | while read rc; do dirname "$rc"; done

Check Subagents

ls ~/.claude/agents/bmad-*

🚨 Emergency Recovery

Complete Reinstallation

If everything is broken:

# 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:

# 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:

# 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:

  3. Alpha Release Notes:

    • Check: /Users/hbl/Documents/BMAD-METHOD/v6-open-items.md

📝 Logging & Debugging

Enable Verbose Logging

# Set debug mode
export BMAD_DEBUG=true

# Run command
bmad status

# Disable debug mode
unset BMAD_DEBUG

Check npm Logs

# If installation fails
npm install --loglevel verbose

Git Status

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