stefanoginella/auto-bmad
30 stars · Last commit 2026-08-24
BMAD module that runs the full BMAD story workflow end-to-end — one story at a time, hands-off between human-in-the-loop checkpoints — on Claude Code or Codex, delegating each step to model/effort-tuned subagents.
README preview
# auto-bmad — hands-off BMAD stories, human-in-the-loop where it counts
[](./LICENSE) [](https://github.com/stefanoginella/auto-bmad) [](https://github.com/bmad-code-org/BMAD-METHOD) [](https://github.com/bmad-code-org/BMAD-METHOD) [](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) [](#install) [](./CONTRIBUTING.md)
A **BMAD module** that runs the **[BMAD](https://github.com/bmad-code-org/BMAD-METHOD) build lane end-to-end — one story at a time, or an [entire epic in one run](#run-a-whole-epic)**, on **Claude Code, Codex, or opencode**, with **[human-in-the-loop checkpoints](#human-in-the-loop-stops)** at the decisions that matter.
`auto-bmad` wraps BMAD's own unattended story primitive, **`bmad-build-auto`** (plan → build → review), in a resumable pipeline: it picks the next story from your story source — `sprint-status.yaml`, or a `bmad-spec` spec folder's `stories.yaml` (see [Two story sources](#two-story-sources)) — or takes one as an argument, runs `bmad-build-auto` to **plan** the story into a spec, then to **build** it (implement → review → finalize, with build-auto's own review layers *plus* auto-bmad's security and cross-model layers), then runs a **follow-up review pass on a second model**, adds the optional TEA (Test Architect) skills by risk, keeps the sprint status in sync, and finishes with a branch, a PR, and a report of open questions, deferred work, and anything that needs your attention — then stops so **you** decide when to start the next story. Or run a **whole epic at once** with [`/auto-bmad epic`](#run-a-whole-epic) — the same lane looped over the epic's stories, no per-story halts, one branch, one PR, one epic-end retrospective.
The orchestrator **only delegates and reports** — it never reads or edits story code, and never edits the spec. Every step runs in **your host's native subagents with per-phase models** (Claude Code, Codex, opencode): the heavy plan/build steps on your strongest model, the follow-up review on a *different* model, triage and the retrospective on a faster one. Nothing is rendered into your repo — the models live in a `profiles` block in auto-bmad's config, and the same project runs unchanged under any of the three tools (the host is re-detected every run). Where a host has no subagents at all, the pipeline runs inline — same phases, same stops.
> **Prerequisites**
> - **BMAD ≥ 6.11.0** installed in the project (`_bmad/config.toml` present) with the **`bmm`** module — that is where `bmad-build-auto`, `bmad-sprint-planning` and `bmad-retrospective` come from — plus **`tea`** for the test-architecture phases (optional). The installer below can add these in the same run.
> - **`uv`** on PATH (BMAD's build lane renders through `uv run`) and a **`python3` ≥ 3.11 on PATH** (auto-bmad reads BMAD's TOML config with the standard library; `uv python install 3.11` if you need one).
> - **Nested subagents** enabled for your host — auto-bmad's delegate must be able to spawn `bmad-build-auto`'s own subagents. **Claude Code:** the default (depth 3) is fine; only an explicit `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1` breaks it. **Codex:** add `[agents]` `max_depth = 2` to `~/.codex/config.toml` (or the project's `.codex/config.toml`), or run `codex features enable multi_agent_v2`. **opencode:** set `"subagent_depth": 2` in `opencode.json` and grant the Task tool to the subagent (`"agent": {"general": {"permission": {"task": "allow"}}}`). Preflight checks this and prints the exact fix.
> - **`gh`** (GitHub CLI, authenticated) for the push/PR/CI/merge steps — without it, or without a GitHub remote, auto-bmad runs in **local mode** (branch + commits, no PR).
> - Recommended: an `AGENTS.md` with BMAD's `<!-- bmad:context -->` block (`/bmad-project-context setup`) so build-auto's implementers inherit your repo conventions — preflight only warns when it is missing.
> **Compatibility:** tested against the **[BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) 6.11 line** — floor **6.11.0**, tested up to **6.11.0** (and prerelease **6.11.1-next.27**) — and the separately versioned **[TEA test-architecture module](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) v1 line** (the `testarch` skills) — floor **1.23.0**, tested up to **1.23.2** (and prerelease **1.23.3-next.0**) — auto-bmad couples to those skills' contracts rather than pinned versions.
> ⚠️ **It can't save you from bad inputs.** auto-bmad automates the *workflow*, not judgment — vague epics, thin acceptance criteria, or a shaky architecture produce vague, untrustworthy code, just faster. The review passes and human-in-the-loop stops below are guardrails, not guarantees; the real leverage is clear stories and sound design *before* you press go.