auto-bmad — hands-off BMAD stories, human-in-the-loop where it counts

A BMAD module that runs the full BMAD story implementation workflow end-to-end — one story at a time, or an entire epic in one run, on Claude Code, Codex, or opencode, with human-in-the-loop checkpoints at the decisions that matter.

auto-bmad chains the core BMM skills (create-story → dev-story → code-review) and the optional TEA (Test Architect) skills into a single resumable pipeline. It detects the next story from sprint-status.yaml (or takes one as an argument), runs every step in an isolated git branch with conventional-commit checkpoints, opens a PR, and finishes with a report of the PR link, 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 — the same pipeline looped over the epic's stories, trimmed for wall-clock and capped with one integration review + one PR.

The orchestrator only delegates and reports — every BMAD step runs inside a sub-agent, with model and thinking effort matched to the stakes (Opus/max for high-stakes implementation, a faster model for low-stakes mechanics). On Claude Code, Codex, and opencode those are real, isolated subagents (.claude/agents / .codex/agents / .opencode/agent, generated from a configurable profiles block); elsewhere it falls back to generic subagents (untuned) or runs inline — same pipeline either way. opencode is multi-provider — point any phase (or the second-opinion reviewer) at any provider/model you've configured (Anthropic, DeepSeek, Qwen, local, …); it's model-tuned per phase but, since its reasoning knob is provider-specific, not effort-tuned in the agent files.

Requires the BMAD skills it orchestrates (bmm, plus tea for the test phases) and a _bmad/ config in your project — the installer below can add these in the same run. auto-bmad drives those skills; it does not replace them.

Compatibility: tested against the BMAD-METHOD v6 skill line up to 6.9.0, and the separately versioned TEA test-architecture module v1 line (the testarch skills) up to 1.19.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 code-review loop and human-in-the-loop stops below are guardrails, not guarantees; the real leverage is clear stories and sound design before you press go.

Install

auto-bmad is a BMAD module, so the official way to install it — for any supported tool, Claude Code included — is the BMAD installer. Requires Node.js 20.12+ and Git.

From your project directory, run the installer and add this repo as a custom source:

npx bmad-method install

When the interactive flow asks "Would you like to install from a custom source (Git URL or local path)?", choose Yes and enter:

https://github.com/stefanoginella/auto-bmad

The installer reads this repo's marketplace.json, offers the auto-bmad module, and copies it into your tool's skills dir (.claude/skills/ for Claude Code, .agents/skills/ for Codex, …). In the same run, also select the official modules auto-bmad orchestrates if they aren't already installed — at least bmm, plus tea for the test-architecture phases.

Non-interactive equivalent:

npx bmad-method install \
  --directory . \
  --modules bmm,tea \
  --custom-source https://github.com/stefanoginella/auto-bmad \
  --tools claude-code \
  --yes

Use --tools codex for Codex (npx bmad-method install --list-tools lists every target). Re-run npx bmad-method install anytime to update.

Both the interactive and --custom-source forms install auto-bmad's latest main commit; to pin a specific release instead, append the tag to the URL (…/[email protected]) — see Updating.

Then provision the delegate agents once with /auto-bmad setup — though auto-bmad also self-registers on the first normal /auto-bmad run if you skip it.

/plugin marketplace add stefanoginella/auto-bmad
/plugin install auto-bmad@auto-bmad

Updating

auto-bmad installs as a custom-source BMAD module, so an update has to re-supply its Git source. Re-run the installer in update mode pointing at this repo (requires Node.js 20.12+):

npx bmad-method install \
  --action update \
  --custom-source https://github.com/stefanoginella/auto-bmad \
  --yes

This re-clones the repo into BMAD's module cache and rewrites the install manifest with auto-bmad's source, so the update applies and future bmad update runs resolve it cleanly.

Choosing a version. The bare --custom-source URL above tracks auto-bmad's main HEAD — the latest commit, so each update pulls the newest main. To pin an exact release instead, append the tag to the source: --custom-source https://github.com/stefanoginella/[email protected]. For a custom-source URL the @<ref> suffix is the only version selector — BMAD's --channel/--all-next flags govern registered modules, not custom-source URLs, so they won't move auto-bmad onto a release tag.

⚠️ Don't update with --action quick-update (the interactive default for an existing install). It skips custom-source re-cloning entirely, so auto-bmad is silently skipped and you keep seeing [warn] … could not locate module.yaml for 'abm' on the next bmad update. Always re-supply --custom-source as above (interactively: choose "Modify BMAD Installation" and re-enter the custom source — don't accept the quick-update default).

💡 Delegate agents re-render themselves after an update. A module update (or a profiles edit) would otherwise leave the generated .claude/agents / .codex/agents stale, so the next /auto-bmad run detects this at preflight and reprovisions automatically, noting it in the report. To refresh them yourself (e.g. right after editing profiles), run /auto-bmad reprovision. Nothing else needs reconfiguring — the running tool is auto-detected every run.

If you installed via the Claude plugin marketplace (the alternative above) rather than the BMAD installer, update through Claude Code instead:

/plugin marketplace update auto-bmad
/plugin install auto-bmad@auto-bmad

Usage

Run from the root of a BMAD-enabled project:

/auto-bmad              # implement the next story from sprint-status.yaml
/auto-bmad 1-3          # implement a specific story (epic 1, story 3)
/auto-bmad 1-3-user-auth
/auto-bmad epic         # implement an ENTIRE epic in one run (see "Run a whole epic")
/auto-bmad epic --epic 2  # implement a specific epic
/auto-bmad stop before code-review        # steer a single run (see Overrides)
/auto-bmad --story 1-3 skip git commits
/auto-bmad reprovision                    # re-render delegate agents after editing profiles
/auto-bmad reset-defaults                 # discard profile retunes, restore shipped defaults

💡 Run it in an auto-approve / "YOLO" mode. auto-bmad is built to run autonomously between the human-in-the-loop stops below, so it works best when the host tool isn't prompting for permission on every tool call — Claude Code's or opencode's --dangerously-skip-permissions (aka YOLO mode), or Codex's --dangerously-bypass-approvals-and-sandbox. Because that hands the agent broad access, run it inside a sandbox: see aicontainer for a containerized environment that lets you skip permission prompts safely — and because Codex's normal sandbox (bubblewrap) can't initialize inside a nested container, that bypass flag is also what lets Codex run within aicontainer.

• No-argument /auto-bmad resumes unfinished work first — an interrupted pipeline if one exists, otherwise the next actionable story by status (in-progress → review → ready-for-dev → backlog); it doesn't jump straight to a fresh backlog item. Pass a story id to target one explicitly. The pipeline is resumable (re-run to continue from the last completed phase), and a clean run marks the story done (story file + sprint-status.yaml) so the next run advances instead of re-picking it.
• A per-story report log is saved to _bmad-output/auto-bmad/reports/<story>.md — each run appends a timestamped section (never overwritten on resume), and a clean run commits it before push so it ships in the PR diff. It holds the story-level outputs: overrides, TEA outcomes, timing (total elapsed plus an AI-run vs human-wait split), open questions, deferred work, epic-end planning drift, blockers, next-story preview, and the one-line pipeline disposition (clean / caveated / draft + reason). PR/CI links, merge method, and the final status-flip are printed to chat only — already retrievable from GitHub and the BMAD status files.
• Everything auto-bmad does per phase, and every point where it stops for you, is in the two tables below — the phase playbook and the human-in-the-loop stops.

What it does per story

Each phase ends with a conventional commit, so progress survives interruptions and is easy to review.

Run a whole epic

/auto-bmad epic (or /auto-bmad epic --epic N) drives an entire epic — every actionable story — in one run, then one PR. It exists for epics that are too slow story-by-story: it keeps the autonomous create-story → dev-story core (with tests) for each story but trims the heavy per-story code-review loop to a single thin review + fix, and batches the heavy adversarial review into one epic-wide integration pass at the end. The result is one epic/N-slug branch, per-story commits on it, one CI wait, and one merge prompt.

• It warns and asks you to confirm up front — an epic runs fully unattended through the review: no per-story checkpoints, and no review stop at all (not even at the end). Review findings that need a decision are auto-resolved with the reviewer's recommended fix/defer/dismiss (surfaced in the epic report's Auto-decided section), and a review that can't converge cleanly ships a draft PR with the findings flagged. The only stops left are the E0 preflight safety asks (adopting a half-done epic / a base-branch readiness check) and the final merge prompt.
• A best-guess on a high-severity finding still gets your eyes: any Critical/High the run auto-decided forces the PR to a draft (epic stays at review) and lands in the report's Needs human — so you review it before merge.
• Per-story safety stays: every story must pass its own tests (the hard gate) and gets a quick review whose findings flow into the final integration review, so later stories don't build on unreviewed code.
• It completes a half-done epic: stories already finished — by the normal per-story /auto-bmad flow or by hand — are skipped (assumed merged into your base branch); epic mode runs only what's left. If a finished story's work is on an un-merged branch, it asks before proceeding.
• One report, one status flip: a single reports/epic-N.md rolls up every story; on a clean run all the epic's stories flip to done together. If anything is caveated (an open Critical/High, a Critical/High the run auto-decided, a waived gate, red CI), the whole epic stays at review — a single PR is either mergeable or not.

Delegation, profiles, TEA, resume, and the overrides that still apply all work as in per-story mode; epic mode uses the highest-effort delegate profiles throughout, so expect it to be slower and pricier per run than a single story (it's doing the whole epic). Full mechanics: references/epic-pipeline.md.

Human-in-the-loop stops

auto-bmad runs autonomously between the points below — delegated sub-agents answer BMAD's interactive prompts with sensible defaults. It pauses for you only here:

Use overrides (below) if you want to add your own stops — e.g. stop before code-review.

Overrides

Steer a single run by adding instructions to the invocation (natural language or flags) — e.g. stop before code-review, start at phase 5, skip git commits, skip TEA, skip merge-prompt, max 5 review iterations, git mode local, dry run. The orchestrator echoes how it interpreted them and which phases will run before executing. See references/overrides.md.

Split a story across tools

The cleanest way to mix tools is delegation.cli_phases (see Configuration): it routes chosen phases to another tool's CLI (claude -p / codex exec / opencode run) — at that phase's model + effort — so a single, autonomous /auto-bmad run mixes tools with no hand-off. Set it once and every run honours it — e.g. cli_phases: { code_review_review_secondary: opencode } to implement in your host tool but run the second-opinion review on a different vendor's model for diversity. The orchestrator builds the command and parses the result; the routed tool just needs its auto-bmad/bmm skills installed and (when it isn't the host) to be authenticated — the preflight hard-stops if not.

You can also hand a story off by hand, mid-pipeline — handy when you'd rather drive each tool interactively, or haven't set the other tool up as a headless CLI. The running tool is auto-detected every run and the pipeline is resumable, so stopping at a phase boundary in one tool and resuming in another just works — e.g. implement in Claude Code, review in Codex:

# In Claude Code — runs phases 0–6 (create-story → dev-story), committing each phase
/auto-bmad stop before code-review

# In Codex, same project directory — resumes at phase 7 (code-review) through the PR
/auto-bmad

Swap the tools for the reverse (implement in Codex, review in Claude Code). A plain no-arg /auto-bmad resumes the interrupted pipeline at the next unfinished phase; start at phase 7 is the explicit equivalent (it first validates the story is implemented). The same pattern works at any phase boundary — e.g. stop after phase 5, then resume — so you can route any slice of the pipeline to whichever tool you prefer for it.

Prerequisites for the manual hand-off: install the auto-bmad skill in both tools and provision delegates for both — delegation.target_tools must list claude-code and codex (confirm at /auto-bmad setup). Keep git commits on (the default): the per-phase checkpoint commits and the shared _bmad-output/auto-bmad/state/ file are exactly what let the other tool pick up where the first left off.

Configuration

_bmad-output/auto-bmad/config.yaml (created on first run) controls:

• TEA on/off — including the non-blocking long-epic per-story trace advisory (tea.story_trace_advisory: toggle + epic-length & distance-to-gate thresholds).
• Git — mode (PR vs local-only) and branch prefix.
• Code review — iteration cap (code_review.max_iterations); the optional second/third parallel review models (code_review_review_secondary / code_review_review_tertiary in phase_profiles; blank disables); and the dedicated security review (code_review.security_review, default on — its model is code_review_security in phase_profiles, blank ⇒ the primary reviewer's profile).
• Delegation — the per-phase profile mapping (phase_profiles) and the per-tool model + effort for each delegate (profiles). You can also add custom profiles (e.g. an ab-ultradeep for one phase): same field set as the shipped ones, name starting with ab-, then point phase_profiles entries at it and run /auto-bmad reprovision.
• delegation.target_tools — the tools agents are provisioned for. Setup defaults this to whichever AIs your BMAD install already targets (detected from .claude/skills for Claude Code, .agents/skills for Codex, .opencode/skills for opencode) and lets you confirm or adjust. Provision more than one and the same project runs in any of them — the running tool is auto-detected each run, so you never reconfigure when you switch. opencode's opencode.model ships blank (delegates inherit your opencode default model); set it per profile for per-phase model tiering and cross-vendor review diversity.
• delegation.cli_phases — opt-in per-phase external-CLI routing (a phase→tool map, empty by default): delegates chosen phases to claude -p / codex exec / opencode run instead of an in-tool sub-agent, for cross-tool (and, via opencode, cross-vendor) diversity (e.g. { code_review_review_secondary: opencode }); model + effort still come from that phase's profiles block.

After editing profiles (e.g. to set your Codex model names or opencode provider/model), run /auto-bmad reprovision; to undo your edits and restore the shipped defaults, run /auto-bmad reset-defaults (scope it to one profile, all profiles, or the phase mapping — your git/TEA/delegation settings are never touched; an all-profiles reset also removes custom profiles, after confirming). See references/delegation-runtime.md and references/state-and-resume.md for the full schema.

Contributing

See CONTRIBUTING.md and our Code of Conduct.

License

MIT © 2026 Stefano Ginella