BMAD (Build Measure Analyze Deploy) methodology plugin for Claude Code - Autonomous test-driven development with visual QA integration
npm install bmad-harmony
> Build Measure Analyze Deploy - Autonomous Test-Driven Development for Claude Code
BMAD-Harmony is a Claude Code plugin that enables fully autonomous, test-driven development with visual QA integration. It's designed to run indefinitely via the "Ralph Wiggum" loop pattern, allowing you to ship features while you sleep.
- Structured State Management - JSON-based tracking that survives context window decay
- Atomic Feature Cycles - One feature per session with mandatory git commits
- External Verification Hooks - Prevents false completion claims
- Visual QA Integration - Browser automation for UI verification
- Infinite Loop Execution - Ralph Wiggum pattern for autonomous building
``bashInstall globally
npm install -g bmad-harmony
$3
bash
npx bmad-harmony install
`$3
bash
Clone the repository
git clone https://github.com/Finn-ML/FMad-Method.git ~/.claude/plugins/bmad-harmony
`Quick Start
$3
bash
npm install -g bmad-harmony
bmad-harmony install
`$3
bash
cd your-projectUsing CLI
bmad-harmony initOr using Claude Code
claude
> /init-project
`This creates:
-
- Project brain with conventions and architecture
- features_list.json - Feature tracking and configuration
- bugs.json - Bug tracking
- progress.md - Human-readable progress overview
- .claude/ - Working directories for screenshots, queues, etc.$3
`bash
In Claude Code
> /add-feature "User Authentication" "Login form with email/password, JWT tokens, session persistence"
> /add-feature "Dashboard" "Main dashboard with user stats" --deps feat-001
> /add-feature "Settings Page" "User settings with profile edit" --deps feat-001
`$3
Manual mode (one feature at a time):
bash
> /next-feature
`Autonomous mode (Ralph Wiggum loop):
bash
bmad-harmony loop
`$3
bash
CLI
bmad-harmony statusOr in Claude Code
> /status
`CLI Commands
bash
bmad-harmony Commands:
install Install plugin to Claude Code plugins directory
init Initialize BMAD-Harmony in current project
loop Start the Ralph Wiggum autonomous loop
status Show current project status
version Show version information
help Show help message
`Claude Code Commands
| Command | Description |
|---------|-------------|
|
| Initialize BMAD-Harmony in current project |
| /next-feature | Implement exactly one feature cycle |
| /add-feature | Add a new feature to the backlog |
| /status | Display current project progress |
| /visual-qa | Trigger visual QA verification |
| /fix-bug | Address bugs or visual QA failures |
| /loop-prompt | Generate the autonomous loop prompt |How It Works
$3
Each
/next-feature invocation follows this exact flow:`
1. Check for critical bugs → Fix if found, EXIT
2. Check for visual QA failures → Fix if found, EXIT
3. Select next feature (by priority + dependencies)
4. Set status: "in-progress"
5. Implement the feature
6. Run tests
7. If visual QA needed → Queue and EXIT
8. Git commit
9. Set status: "completed"
10. Update progress.md
11. EXIT
One feature per cycle. Always.
$3
features_list.json - The source of truth:
json
{
"projectName": "my-app",
"features": [
{
"id": "feat-001",
"name": "User Authentication",
"status": "completed",
"completed": true,
"commits": ["abc1234"]
}
],
"config": {
"testCommand": "npm test",
"devServer": { "port": 3000 }
}
}
`bugs.json - Bug tracking:
json
{
"bugs": [
{
"id": "bug-001",
"severity": "high",
"status": "open",
"title": "Cart total not updating"
}
]
}
`$3
For UI features, BMAD-Harmony integrates with browser automation:
1. Feature implementation completes
2. Queue file created in
3. Visual QA captures screenshots at multiple viewports
4. Results written to
5. Next cycle processes results (fix or complete)$3
Named after the Simpsons character who keeps trying despite everything:
bash
bmad-harmony loop
`Or manually:
bash
#!/bin/bash
"I'm helping!" - Ralph Wiggum
while true; do
claude --print "$(cat .claude/loop-prompt.txt)"
if all_features_complete; then
echo "BUILD COMPLETE!"
exit 0
fi
sleep 5
done
`The loop continues until all features are complete, handling failures gracefully.
Programmatic Usage
javascript
const bmad = require('bmad-harmony');// Get available commands
const commands = bmad.getCommands();
// ['init-project', 'next-feature', 'add-feature', ...]
// Create a feature programmatically
const feature = bmad.createFeature('feat-001', 'User Login', 'Email/password auth', {
priority: 1,
routes: ['/login'],
visual: true
});
// Get default config
const config = bmad.getDefaultFeaturesConfig('my-project');
`Configuration
$3
json
{
"config": {
"testCommand": "npm test",
"e2eCommand": "npx playwright test",
"buildCommand": "npm run build",
"devServer": {
"command": "npm run dev",
"port": 3000,
"readyPattern": "ready on"
},
"visualQA": {
"enabled": true,
"screenshotDir": ".claude/screenshots",
"baseUrl": "http://localhost:3000",
"viewports": [
{"name": "mobile", "width": 375, "height": 667},
{"name": "desktop", "width": 1440, "height": 900}
]
},
"git": {
"autoCommit": true,
"commitPrefix": "feat"
},
"loop": {
"maxFeaturesPerSession": 1,
"pauseBetweenFeatures": 0
}
}
}
`Hooks
BMAD-Harmony uses hooks to enforce workflow integrity:
$3
Prevents Claude from exiting if:
- A feature is still "in-progress" without commits
- A recently completed feature has no commit hash$3
Syncs with current state after every commit.$3
Alerts about pending visual QA results at session start.Best Practices
$3
- Keep features atomic (completable in one session)
- Define clear acceptance criteria in description
- Specify routes for UI features
- Set appropriate dependencies$3
- Map dependencies before starting implementation
- Don't create circular dependencies
- Complete foundational features first$3
- Always specify test requirements
- Run tests before marking complete
- Use visual QA for UI features$3
- One commit per feature
- Clear commit messages: feat(feat-001): User Authentication
- Don't push until feature is completeTroubleshooting
$3
bash
Check what's blocking
> /status --verboseManually update status if needed
Edit features_list.json directly
`$3
bash
Check if feature has hit max attempts
cat features_list.json | jq '.features[] | select(.status == "blocked")'Review notes and fix manually
`$3
bash
Check queue
ls -la .claude/visual-queue/Process manually
> /visual-qa feat-003
`$3
bash
Check logs
tail -f .claude/history/ralph-wiggum.logRun single cycle manually
> /next-feature
``BMAD-Harmony is built on these principles:
1. Atomicity - One feature per cycle, always
2. Verification - No completion without proof
3. Persistence - Git and JSON as source of truth
4. Observability - Clear status at any point
5. Recoverability - Any session can resume from state files
The goal is a "dark factory" build process where features are implemented, tested, and committed autonomously while you focus on other things.
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with a sample project
5. Submit a pull request
MIT - see LICENSE
- Named "Ralph Wiggum" loop after the Simpsons character's eternal optimism
- Inspired by BMAD methodology and Engineering Harmony workflows
- Built for Claude Code CLI
- npm Package
- GitHub Repository
- Issue Tracker
---
"Me fail English? That's unpossible!" - Ralph Wiggum
"Me fail to ship features? That's unpossible!" - BMAD-Harmony