BMAD Loop module (bmad-loop)

A BMAD module pairing the automation skills with the bmad-loop orchestrator tool (the Python program that drives the loop). The skills can be installed by the BMAD installer, or laid down by bmad-loop init (the orchestrator's wheel bundles them); either way bmad-loop-setup installs the bmad-loop package from its Git repository, so installing this module gives you a working system — skills plus the orchestrator that invokes them. Standard BMAD installs are never modified; the skills are bmad-loop-owned, standalone or bmad-loop-native (see the table below).

Component	Forked from	Role
bmad-loop	— (this repo, Git)	the orchestrator: ralph-loop, hooks, tmux adapters, TUI. CLI bmad-loop. Installed by bmad-loop-setup from Git.
bmad-loop-resolve	— (bmad-loop-native)	interactive CRITICAL-escalation resolution: a human disambiguates a frozen spec so a paused story can be re-driven (/bmad-loop-resolve <story>)
bmad-loop-sweep	— (bmad-loop-native)	read-only deferred-work ledger triage; owns the canonical deferred-work-format.md
bmad-loop-setup	— (scaffolded)	installs the orchestrator tool from Git, runs bmad-loop init + validate, refreshes _bmad/bmad-loop/module-help.csv

The inner dev primitive is the upstream bmad-build-auto skill (BMAD-METHOD's generic unattended dev session; bmad-dev-auto on pre-rename releases, resolved from disk and invoked under whichever name is there). It is not owned or bundled here — the orchestrator drives it as an external skill that must already be installed (by the BMad installer / bmm-core). The bmad-loop orchestrator synthesizes its result.json from the spec the session leaves on disk (see bmad_loop.devcontract). The skill self-reviews inline (its step-04 review layers) and commits its own work each iteration; the orchestrator's follow-up review is just a re-invocation of the primitive on the done spec (BMAD-METHOD #2508 routes a done spec to a fresh review pass), so there is no separate review skill.

Install into a project

The orchestrator tool now bundles these skills, so bmad-loop init lays them down for you:

uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git"
bmad-loop init --project /path/to/project --cli claude   # add --cli codex/gemini as needed
claude "/bmad-loop-setup accept all defaults"            # installs the tool + wires the project

bmad-loop init installs the bmad-loop-* skills into .claude/skills/ (claude) and/or .agents/skills/ (codex/gemini), registers hooks, writes .bmad-loop/policy.toml, and gitignores the runs dir. Existing skill dirs are left untouched (--force-skills to overwrite, --no-skills to skip). bmad-loop-setup is one-shot for the bootstrap the BMAD installer cannot do: it ensures the orchestrator tool is installed, then runs bmad-loop init and bmad-loop validate (preflight). Module registration — _bmad/bmad-loop/, the central config.toml, the /bmad-help catalog — belongs to the BMAD installer, which regenerates it on every run; the only file the skill writes there is _bmad/bmad-loop/module-help.csv.

The skills must be installed together: bmad-loop-sweep owns the canonical deferred-work-format.md that the ledger normalizes to, and the upstream dev primitive must also be present (since BMAD-METHOD 6.10.1-next.33 it records deferred findings in its spec's frontmatter for the orchestrator to harvest into the ledger; pre-rename copies append flat entries the sweep normalizes instead). Requires the BMad Method (bmm) module (_bmad/bmm/config.yaml) and a sprint-status.yaml from bmad-sprint-planning.

_bmad/custom/<skill-name>.toml customization overrides are keyed by skill directory name.

Maintaining the skills

• This directory (src/bmad_loop/data/skills/) is canonical for the skills and is bundled into the wheel as package data, so bmad-loop init can install them. The repo's .claude/skills/ and .agents/skills/ hold dev-workspace copies; tests/test_module_skills_sync.py fails if they drift. After editing here, re-copy the skill dirs into both trees.
• The orchestrator tool is not bundled in the skill dirs — the BMAD installer copies only the skill directories, so a sibling tool/ would never reach an installed project. bmad-loop-setup installs the bmad-loop package from https://github.com/bmad-code-org/bmad-loop (src/bmad_loop, pyproject.toml are canonical at the repo root). (The skills, by contrast, ride along inside the package wheel.)
• The inner dev primitive (bmad-build-auto, or bmad-dev-auto pre-rename) is not maintained here — it is the upstream bmm-core skill, driven unmodified. Nothing in this directory mirrors it; the orchestrator adapts to it via bmad_loop.devcontract.
• Do not rename the result.json workflow values — they are machine contracts the orchestrator validates, not skill names:
  • dev → "auto-dev" (checked by verify.DEV_WORKFLOW in verify_dev / verify_dev_bundle; the orchestrator forges this value in devcontract when synthesizing the dev result from the spec).
  • sweep triage / migrate → "deferred-sweep-triage" / "deferred-sweep-migrate" (checked in sweep.py).

Validate after changes (from the repo root):

python3 .claude/skills/bmad-module-builder/scripts/validate-module.py src/bmad_loop/data/skills