📊 BMAD Progress Dashboard

Real-time progress tracking for BMAD Method projects
Beautiful visual dashboards • Interactive terminal UI • Zero configuration

Quick Start • Features • Usage • Documentation

✨ What is this?

BMAD Progress Dashboard automatically tracks your BMAD project progress by analyzing your documentation and story files. It generates beautiful visual dashboards showing:

• 📋 Planning progress (Brief, PRD, Architecture)
• 🚀 Development progress (Stories, Tasks, Epics)
• 🎯 Overall completion (Weighted combination)
• 📊 Visual 3x3 grid (All metrics at a glance)
• 🏁 Next milestones (What to work on next)

Compatible with BMAD v4 and v6 • Works standalone too!

🚀 Quick Start

Installation (3 steps)

# 1. Navigate to the installer
cd progress-tracking-bundle

# 2. Install dependencies
npm install

# 3. Run the installer
node installer.js install

The installer will:

• ✅ Detect your BMAD version (v4/v6)
• ✅ Copy all necessary files
• ✅ Update your package.json
• ✅ Install dependencies
• ✅ Test the installation

That's it! 🎉

🎯 Usage

After installation, you can track your progress using the convenient CLI:

CLI Commands (Recommended)

./bmad-progress              # Update dashboard
./bmad-progress terminal     # Interactive terminal view
./bmad-progress watch        # Auto-update on file changes
./bmad-progress live         # Terminal with auto-refresh
./bmad-progress help         # Show all commands

Short aliases available:

./bmad-progress t            # terminal
./bmad-progress w            # watch
./bmad-progress l            # live
./bmad-progress h            # help

NPM Scripts (Alternative)

npm run bmad-progress                # Update dashboard
npm run bmad-progress:terminal       # Interactive terminal
npm run bmad-progress:watch          # Auto-update on changes
npm run bmad-progress:live           # Terminal with auto-refresh
npm run bmad-progress:help           # Show help

View Your Dashboard

After running any update command, open:

docs/progress-dashboard.md

🎨 Features

📊 Visual Dashboard

• 3x3 Grid Layout - See all metrics at once
• Progress Bars - Visual completion indicators
• Color Coding - Quick status identification
• Milestone Tracking - Know what's next

🖥️ Interactive Terminal

• Real-time Updates - See changes as they happen
• Keyboard Controls - Refresh (r), Quit (q)
• Auto-refresh Mode - Set custom intervals
• Clean Interface - Beautiful terminal UI

🔄 Auto-Update

• File Watching - Monitors story changes
• Instant Updates - Dashboard updates automatically
• Background Process - Keep it running while you work

🎯 Smart Detection

• Version Auto-detect - Works with v4 and v6
• Zero Config - Works out of the box
• Flexible Structure - Adapts to your setup

📦 What Gets Installed

your-project/
├── .bmad-core/utils/               # For BMAD v4 (if detected)
│   ├── update-progress.js
│   ├── progress-watcher.js
│   ├── trigger-progress-update.js
│   └── progress-terminal.js
├── tools/progress-tracking/        # For BMAD v6 (if detected)
│   ├── update-progress.js
│   ├── progress-watcher.js
│   ├── trigger-progress-update.js
│   └── progress-terminal.js
├── bmad-progress                   # CLI wrapper script
├── package.json                    # Updated with new scripts
└── docs/
    └── progress-dashboard.md       # Your dashboard (generated)

📋 Requirements

Minimum Requirements

• Node.js >= 16.0.0
• NPM or Yarn

For Full Tracking

Your BMAD project should have:

• docs/stories/ - Story files with task checkboxes
• docs/prd.md or docs/prd/ - Product requirements (optional)
• docs/architecture.md or docs/architecture/ - Architecture docs (optional)
• Core config file - .bmad-core/core-config.yaml (v4) or bmad-core/core-config.yaml (v6)

Note: The dashboard works even if you only have story files!

🛠️ Advanced Usage

Installer Options

# Install without prompts
node installer.js install -y

# Install to specific directory
node installer.js install -d /path/to/project

# Check installation status
node installer.js status

# Update existing installation
node installer.js update

Customization

Edit your core-config.yaml to customize paths:

devStoryLocation: docs/stories
prd:
  prdFile: docs/prd.md
  prdShardedLocation: docs/prd
architecture:
  architectureFile: docs/architecture.md
  architectureShardedLocation: docs/architecture

Terminal Options

# Simple ASCII mode (no Unicode)
./bmad-progress terminal --simple

# Custom refresh interval
./bmad-progress live 60   # Refresh every 60 seconds

📊 How Progress is Calculated

Overall Progress

Overall = (Planning × 40%) + (Development × 60%)

Planning Phase (25% each)

• ✅ Project Brief exists
• ✅ PRD complete
• ✅ Architecture complete
• ✅ Documents sharded

Development Phase

• Epic completion percentage
• Story completion (tasks checked)
• Milestone achievements

Story Progress

Story % = (Completed Tasks ÷ Total Tasks) × 100

🎓 Tutorial

First Time Setup

1. Install the dashboard

   cd progress-tracking-bundle
   npm install
   node installer.js install

2. Generate your first dashboard

   ./bmad-progress

3. View in terminal

   ./bmad-progress terminal

4. Watch for changes

   ./bmad-progress watch

Daily Workflow

Keep the watcher running in a terminal:

./bmad-progress watch

Or use live terminal mode:

./bmad-progress live

Your dashboard updates automatically as you work!

🆘 Troubleshooting

Dashboard not updating?

• ✅ Check files are saved
• ✅ Verify core-config.yaml exists
• ✅ Run npm install to ensure dependencies

Permission errors?

# Make scripts executable
chmod +x bmad-progress
chmod +x .bmad-core/utils/*.js    # or tools/progress-tracking/*.js

Terminal shows weird characters?

# Use simple mode
./bmad-progress terminal --simple

Which BMAD version do I have?

The scripts will tell you:

• [INFO] Using BMAD v6... for v6
• [INFO] Using BMAD v4... for v4

Need help?

./bmad-progress help

Or check our documentation.

📚 Documentation

Installation Guides

• Quick Start - Get up and running fast
• QUICK-COPY.md - Quick reference guide
• MIGRATION-GUIDE.md - Upgrade from v1

BMAD Resources

• BMAD Method - The BMAD framework
• Core Configuration - Config guide

Getting Help

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email: support

🌟 Features Roadmap

• [x] BMAD v4 and v6 support
• [x] Interactive installer
• [x] CLI wrapper with aliases
• [x] Terminal dashboard
• [x] File watching
• [ ] NPM package (npx bmad-progress-dashboard)
• [ ] Global installation option
• [ ] Custom themes
• [ ] Export to JSON/CSV
• [ ] Multi-project management
• [ ] Web dashboard

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See CONTRIBUTING.md for details.

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

• Built for the BMAD Method
• Installer inspired by AgentVibes
• Terminal UI powered by Node.js

Made with ❤️ for BMAD developers
⭐ Star this repo if it helps you!

🚀 Quick Links

Version 2.0 • Last Updated: 2025-10-10 • View on GitHub