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.

Features

• 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

Installation

Via npm (Recommended)

# Install globally
npm install -g bmad-harmony

# Install the Claude Code plugin
bmad-harmony install

Via npx (No Installation)

npx bmad-harmony install

Manual Installation

# Clone the repository
git clone https://github.com/Finn-ML/FMad-Method.git ~/.claude/plugins/bmad-harmony

Quick Start

1. Install the Plugin

npm install -g bmad-harmony
bmad-harmony install

2. Initialize Your Project

cd your-project

# Using CLI
bmad-harmony init

# Or using Claude Code
claude
> /init-project

This creates:

• CLAUDE.md - 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. Add Features

# 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

4. Start Building

Manual mode (one feature at a time):

> /next-feature

Autonomous mode (Ralph Wiggum loop):

bmad-harmony loop

5. Monitor Progress

# CLI
bmad-harmony status

# Or in Claude Code
> /status

CLI Commands

bmad-harmony <command>

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

How It Works

The Feature Cycle

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.

State Files

features_list.json - The source of truth:

{
  "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:

{
  "bugs": [
    {
      "id": "bug-001",
      "severity": "high",
      "status": "open",
      "title": "Cart total not updating"
    }
  ]
}

Visual QA

For UI features, BMAD-Harmony integrates with browser automation:

1. Feature implementation completes
2. Queue file created in .claude/visual-queue/
3. Visual QA captures screenshots at multiple viewports
4. Results written to .claude/visual-results/
5. Next cycle processes results (fix or complete)

The Ralph Wiggum Loop

Named after the Simpsons character who keeps trying despite everything:

bmad-harmony loop

Or manually:

#!/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

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

features_list.json Config Section

{
  "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:

Stop Hook (verify-completion.js)

Prevents Claude from exiting if:

• A feature is still "in-progress" without commits
• A recently completed feature has no commit hash

PostCommit Hook (update-progress.js)

Syncs progress.md with current state after every commit.

PreStart Hook (check-visual-queue.js)

Alerts about pending visual QA results at session start.

Best Practices

Feature Design

• Keep features atomic (completable in one session)
• Define clear acceptance criteria in description
• Specify routes for UI features
• Set appropriate dependencies

Dependency Management

• Map dependencies before starting implementation
• Don't create circular dependencies
• Complete foundational features first

Testing

• Always specify test requirements
• Run tests before marking complete
• Use visual QA for UI features

Git Hygiene

• One commit per feature
• Clear commit messages: feat(feat-001): User Authentication
• Don't push until feature is complete

Troubleshooting

"Feature stuck in in-progress"

# Check what's blocking
> /status --verbose

# Manually update status if needed
# Edit features_list.json directly

"Tests failing repeatedly"

# Check if feature has hit max attempts
cat features_list.json | jq '.features[] | select(.status == "blocked")'

# Review notes and fix manually

"Visual QA not processing"

# Check queue
ls -la .claude/visual-queue/

# Process manually
> /visual-qa feat-003

"Loop keeps failing"

# Check logs
tail -f .claude/history/ralph-wiggum.log

# Run single cycle manually
> /next-feature

Philosophy

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.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with a sample project
5. Submit a pull request

License

MIT - see LICENSE

Credits

• Named "Ralph Wiggum" loop after the Simpsons character's eternal optimism
• Inspired by BMAD methodology and Engineering Harmony workflows
• Built for Claude Code CLI

Links

• npm Package
• GitHub Repository
• Issue Tracker

"Me fail English? That's unpossible!" - Ralph Wiggum

"Me fail to ship features? That's unpossible!" - BMAD-Harmony