evo-bmad

Self-evolving multi-agent orchestration for AI-assisted development. One command to run an entire dev team powered by AI — and it gets smarter with every task.

Works with Claude Code, Cursor, Windsurf, Claude Projects, or any LLM.

What is this?

You write one command: /bmad build a login page.

Your AI then acts as an entire dev team — product owner, architect, developer, tester, QA — running each role in sequence with dedicated prompts. After every task, the system scores agent performance and rewrites underperforming prompts automatically.

You: /bmad build a login page

AI runs:
  1. Orchestrator  → classifies task, creates plan
  2. Story Mapper  → breaks into stories & tasks
  3. PO            → writes requirements
  4. Architect     → designs solution
  5. Dev           → writes code
  6. Gate          → runs typecheck + lint + tests
  7. QA            → reviews everything

After QA:
  8. Evaluator     → scores each agent (0-100)
  9. Knowledge     → extracts patterns for next time
  10. Evolution    → rewrites weak agents automatically

No API keys for the orchestration. No external services. Everything runs as prompts inside your existing AI tool.

Installation

npm install -g evo-bmad

Requires Node.js 18+.

Quick Start

1. Initialize in your project

cd your-project
evo-bmad init

Interactive wizard (6 steps):

• Stack: Next.js, React+Tauri, React SPA, Node API, Python+FastAPI, Landing, Generic
• Target: Claude Code, Cursor, Windsurf, Claude Projects, Generic LLM
• Evolution: Enable self-improving agents (recommended)
• Language: English, Russian, Spanish, German, Chinese, Auto
• Gates: Typecheck/lint/test commands (auto-detected)
• Git: Commit style (conventional, simple, none)

Or skip prompts with defaults:

evo-bmad init -y

2. Start using it

Claude Code:

claude
> /bmad fix the broken auth flow

Cursor / Windsurf: Open project, type in chat:

/bmad add dark mode toggle

Claude Projects (claude.ai): Upload the generated CLAUDE.md to Project Knowledge, then:

/bmad refactor the database layer

3. That's it

The AI reads the agent prompts from .bmad/agents/, follows the pipeline, tracks tasks on a kanban board, and runs quality gates automatically.

What gets created

your-project/
├── .bmad/
│   ├── agents/              # 16 agent prompts (.md files)
│   │   ├── orchestrator.md  # Routes tasks, manages pipeline
│   │   ├── story-mapper.md  # Decomposes into Epic → Stories → Tasks
│   │   ├── po.md            # Product requirements
│   │   ├── architect.md     # System design
│   │   ├── dev-frontend.md  # Frontend development
│   │   ├── dev-backend.md   # Backend development
│   │   ├── qa.md            # Quality assurance
│   │   ├── validation-gate.md
│   │   ├── testing.md
│   │   ├── tech-debt.md
│   │   ├── changelog.md
│   │   ├── release.md
│   │   ├── retrospective.md
│   │   ├── spark.md         # Ideation & brainstorming
│   │   ├── backlog.md
│   │   ├── _registry.json   # Agent versions & scores
│   │   └── _versions/       # Frozen agent versions (v1, v2...)
│   ├── evolution/           # Self-improvement agents
│   │   ├── evaluator.md     # Scores agent output (0-100)
│   │   ├── knowledge-curator.md
│   │   ├── prompt-evolver.md # Rewrites weak agent prompts
│   │   ├── topology-evolver.md
│   │   ├── agent-spawner.md # Creates new specialist agents
│   │   └── rules.md        # Safety guardrails
│   ├── knowledge/           # Project-specific knowledge base
│   │   ├── patterns/        # "Do this" — reusable solutions
│   │   ├── anti-patterns/   # "Don't do this" — known pitfalls
│   │   └── metrics/         # Scores, evolution log
│   └── artifacts/
│       └── BOARD.md         # Kanban board (auto-updated)
├── .bmadrc.yaml             # Project config
└── CLAUDE.md                # Entry point (or .cursorrules / .windsurfrules)

CLI Commands

evo-bmad init

Initialize .bmad/ in your project. Auto-detects stack, creates agents, generates entry point.

evo-bmad init                        # Interactive wizard
evo-bmad init -y                     # Use detected defaults
evo-bmad init --preset react-tauri   # Specify stack
evo-bmad init --target cursor        # Specify AI tool

evo-bmad gate

Run quality gates (typecheck, lint, test) from .bmadrc.yaml.

evo-bmad gate          # Human-readable output
evo-bmad gate --json   # JSON output (for agent consumption)

evo-bmad status

Show kanban board state.

evo-bmad status

# Output:
#   📋 Todo (3)
#     • SMZ-134 — Remove user_email from telemetry
#   🔄 In Progress (1)
#     • SMZ-135 — Split AppContext
#   ✅ Done (12)
#     • SMZ-130 — Auto-focus input

evo-bmad context

Output git context (diff, recent commits, changed files) for your AI.

evo-bmad context          # Markdown output — paste into chat
evo-bmad context --json   # JSON output
evo-bmad context --no-diff  # Skip diff (faster)

evo-bmad learn

Record patterns, anti-patterns, or agent scores.

# Record a pattern (what works well)
evo-bmad learn --pattern "Always use IPlatformBridge for cross-platform calls"

# Record an anti-pattern (what to avoid)
evo-bmad learn --anti-pattern "Never call invoke() directly in shared/"

# Score an agent after task completion
evo-bmad learn --agent dev-frontend --score 85

# Interactive mode
evo-bmad learn

evo-bmad evolve

Manage agent evolution.

evo-bmad evolve status              # Dashboard: scores, trends, health
evo-bmad evolve history dev-frontend  # Version history of an agent
evo-bmad evolve rollback dev-frontend # Rollback to previous version
evo-bmad evolve report              # Full evolution report

evo-bmad update

Update agents from latest evo-bmad templates. Safe — skips agents that have been evolved or customized.

evo-bmad update

evo-bmad sync

Share evolution improvements across projects (opt-in, privacy-safe — only prompt diffs, no code).

evo-bmad sync          # Push and pull
evo-bmad sync --push   # Share your improvements
evo-bmad sync --pull   # Get community improvements

How Evolution Works

After every completed task:

1. Evaluator scores the dev agent (0-100) on correctness, code quality, test coverage, process compliance
2. Knowledge Curator extracts patterns ("do this") and anti-patterns ("avoid this") into .bmad/knowledge/
3. Before the next task, the orchestrator injects relevant knowledge into the dev agent's context

If an agent's average score drops below 70:

4. Prompt Evolver diagnoses the root cause (missing rules, ambiguity, wrong focus)
5. Saves current version to _versions/, writes improved version
6. New version is tested on the next task — auto-rollback if score drops further

evo-bmad evolve status

# 🧬 Evolution Status
#
# Agent                Ver    Score    Trend      Status
# ──────────────────────────────────────────────────────────
# dev-frontend         v1     87       →          🟢 healthy
# architect            v1     —        →          ⚪ new
# qa                   v1     —        →          ⚪ new

Configuration

.bmadrc.yaml — created by evo-bmad init:

preset: react-tauri
target: claude-code
evolution: true
project:
  name: my-app
  language: typescript
  framework: null
pipeline:
  gate:
    typecheck: npx turbo typecheck
    lint: npx turbo lint
    test: npx turbo test
agentLanguage: en
agentStyle: balanced
team: solo
git:
  commits: true
  prefix: conventional

Supported Stacks

| Preset | Stack | Agents included | |--------|-------|-----------------| | nextjs | Next.js + Prisma | Frontend, Backend, DB Migration | | react-tauri | React + Tauri (Desktop) | Frontend, Platform (Rust), AI Context | | react-spa | React + Vite | Frontend | | node-api | Express / Fastify | Backend, DB Migration | | python-fastapi | Python + FastAPI | Backend | | landing | Landing page | Marketing, Frontend | | generic | Any stack | Core agents only |

Supported AI Tools

| Target | Entry point | How it works | |--------|------------|--------------| | Claude Code | CLAUDE.md | Auto-detected on claude start | | Cursor | .cursorrules | Auto-detected by Cursor | | Windsurf | .windsurfrules | Auto-detected by Windsurf | | Claude Projects | CLAUDE.md | Upload to Project Knowledge | | Generic | BMAD-SYSTEM-PROMPT.md | Paste as system prompt |

FAQ

Does this require an API key? No. The orchestration is pure prompts — your AI reads .md files and follows instructions. The CLI (evo-bmad gate, learn, etc.) runs locally with no external calls (except optional sync).

Can I customize agents? Yes. Every agent is a .md file — edit directly. Evolved versions are saved in _versions/ so you can always rollback.

Will evo-bmad update overwrite my changes? No. It skips agents that have been evolved (version > 1) or modified since init.

How is this different from just using AI? Structure. Instead of one big prompt doing everything, you get specialized agents with quality gates, a kanban board, evolution metrics, and a knowledge base that grows with your project.

License

MIT