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

| Command | Description | |---------|-------------| | /init-project | 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

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