📊 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

📋 Multi-PRD Support (NEW!)

Automatic Discovery - Finds all PRDs in docs/ folder
Easy Switching - Track different PRDs with --prd=<name>
List All PRDs - See all available PRDs with ./bmad-progress list
Dashboard Display - Shows active PRD and available PRDs

📦 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

Multi-PRD Tracking

Track multiple PRDs in your project:

# List all available PRDs
./bmad-progress list

# Track a specific PRD
./bmad-progress --prd=worker-pool-error-handling

# Track main PRD
./bmad-progress --prd=main

# Use with watch mode
./bmad-progress watch --prd=my-feature

PRD Discovery Rules:

Files: docs/prd.md or docs/*-prd.md
Folders: docs/prd/ or docs/*-prd/
Automatically detects both single-file and sharded PRDs

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

Install the dashboard

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

Generate your first dashboard
```
./bmad-progress
```
View in terminal
```
./bmad-progress terminal
```
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

PRD not found?

# List all available PRDs to see the correct names
./bmad-progress list

# Use the exact name shown in the list
./bmad-progress --prd=<exact-name>

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

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
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

Resource	Link
📦 Installation	Quick Start
📖 Usage Guide	Usage
🐛 Report Bug	Issues
💡 Request Feature	Discussions
📝 Changelog	Releases
🤝 Contribute	Contributing

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

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
progress-tracking-bundle		progress-tracking-bundle
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md

paulpreibisch/bmad-progress-dashboard

Folders and files

Latest commit

History

Repository files navigation