bmad-loop documentation

August 12, 2026 · View on GitHub

Start with the project README for the overview and quick start. The guides below go deeper, roughly in the order you'll need them.

Using bmad-loop

  • Setup guide — install the tools, pick a CLI, initialize a project, pass preflight, and uninstall.
  • TUI guide — the dashboard: layout, key bindings, the settings editor, and troubleshooting.
  • Features & functionality — the full capability matrix and policy reference.
  • Terminal multiplexer backends — which backend drives your agent sessions (tmux bundled; externals like the herdr adapter install as packages), how selection works, and how external backends arrive.

Extending bmad-loop

  • Authoring CLI adapters & profiles — using bmad-loop probe-adapter to collect + sanitize the hook payload shape, transcript location, and token schema a new CLI profile needs, plus the CodingCLIAdapter ABC and how an adapter class (and the profile selecting it) ships out-of-tree.
  • Writing a bmad-loop plugin — the plugin system: plugin.toml manifest, hooks, lifecycle stages, settings, the trust model, and workflow injection, with a worked walkthrough.
  • Writing a Game Engine plugin — the game-engine layer (built on the plugin system): driving a live engine Editor, the editor_mode ↔ [scm] isolation coupling, a minimal Godot example.
  • Writing a plugin for a specific Editor MCP — Editor-MCP specifics for the bundled Unity plugin: IvanMurzak vs CoplayDev, readiness probes, per_worktree isolation, and the full BMAD_LOOP_* env-var reference.
  • Porting bmad-loop to a new OS — the four OS seams (terminal multiplexer, process lifecycle, hook interpreter, validate preflight), their registries and override env vars, and what a native-Windows port costs end to end.
  • The Test Architect (TEA) plugin — the bundled tea plugin: installing TEA, the six advisory test-architecture steps it injects across runs and sweeps, the enable/blocking settings, and the escalate-on-gate behavior.

Project direction

  • Roadmap — planned and intentionally-deferred work.

For released changes, see the CHANGELOG.

Contributing & community

  • Contributing guide — dev setup (uv + trunk), PR guidelines, and conventional commits.
  • Testing strategy — the layer model, fixture and ablation doctrines, quality guards, the zero-token invariant, and the CI/flake policy behind the suite.
  • Code of Conduct — the Contributor Covenant we follow.
  • Security policy — how to report a vulnerability and what's in scope.
  • Trademark guidelines — proper use of the BMad name and brand.