auto-bmad

auto-bmad

Русский

auto-bmad implements stories and whole epics from a BMad v6 plan. It coordinates coding, independent review, checks and fixes, then saves commits and reports. Works in Codex and Claude Code.

Features

• Run one story, the next planned task or a whole epic.
• Split work across subagents and run independent stories in parallel git worktrees.
• Choose review depth with fast, normal and deep levels.
• Run project tests and configured Android or web checks; fix findings up to a set limit.
• Save progress, update sprint-status.yaml and produce reports with questions that need a human decision.

How it works

plan ──► story in a subagent ──► review layers ──► checks + fix loop ──► commit, sync, report
 │        (bmad-build-auto)       (by level)        (tests, emulator)          │
 └──────────────────────────── next story or next wave ◄───────────────────────┘

1. Plan — reads sprint-status.yaml and the epics file, builds the queue, runs preflight.
2. Story in a subagent — auto-bmad:bmad-story-runner runs the engine: spec → code → commit.
3. Review — 2, 3 or 4 review layers on different models, depending on the level.
4. Checks and fix loop — project tests and other checks; a problem goes back to the engine, up to a limit.
5. Commit and report — tracking is synced, open questions are written, hooks fire.

The work on a story — spec, code, review, fixes, commit — is done by BMad's engine. auto-bmad tunes it for runs without a person through a level profile of rules; what each rule changes is in Under the hood.

New native sessions support bounded local repair checks, role-specific review inputs and a shared content-addressed epic context. Independent verification and the final integration gate remain mandatory. Existing sessions keep their pinned contract. Protocol.

Quick start

Codex

Connect the skills using the installation guide. In your project folder, run $auto-bmad-setup, then $auto-bmad epic-1 for an epic or $auto-bmad 1-3 for one story. Details — Running in Codex.

Claude Code

1. Install the plugin. It lives in the sp-tools marketplace with my other plugins. Tell Claude Code "install the auto-bmad plugin from the StasPotapov/sp-tools marketplace", or run:

   claude plugin marketplace add StasPotapov/sp-tools
   claude plugin install auto-bmad@sp-tools
   

2. Restart Claude Code.

3. In your project folder run /auto-bmad:setup. It checks the environment, helps install BMad 6.12+ (npx bmad-method install, module bmm, tool Claude Code), walks you to a BMad plan (PRD → architecture → epics → sprint planning) and writes .auto-bmad.toml. Run it again after each step it sends you to.

Requirements: git, uv, Python 3.11+, BMad 6.12+. Android checks need the adbm plugin, web checks the mockmatch plugin. Details — Install.

Running

The commands below are for Claude Code. Codex commands are in the quick start.

/auto-bmad:auto-bmad epic-1            # a whole epic
/auto-bmad:auto-bmad 1-3               # one story
/auto-bmad:auto-bmad                   # the next story by sprint status
/auto-bmad:auto-bmad epic-1 --deep     # level for this run: --fast | --normal | --deep
/auto-bmad:auto-bmad epic-1 --no-parallel
/auto-bmad:auto-bmad epic-1 --width 2  # at most 2 stories per wave
/auto-bmad:auto-bmad epic-1 --worktree # the run in its own worktree, merge later: auto-bmad land bmad/epic-1

At the end you get commits in your current branch (nothing is pushed; with --worktree — in the branch bmad/<target>, see Running), sprint-status.yaml up to date, a report per story ("what was done", "how to check", "needs attention"), an epic report, and _bmad-output/implementation-artifacts/epic-<N>-open-questions.md with the open questions. Statistics: auto-bmad stats show.

The run talks to you and writes its reports in your language: BMad's communication_language, or the language you write in. Commit messages and machine markers stay in English.

Configuration

The config is optional: without it a run works on the built-in defaults. /auto-bmad:setup writes the project file .auto-bmad.toml; your personal settings go to ~/.config/auto-bmad/config.toml, and settings of one project on this machine only — to .auto-bmad.local.toml (out of git). The config sets:

• run defaults — the level, parallel waves, the wave width, triage of review findings in a subagent;
• models — model and effort for each actual subagent, including each review layer separately;
• checks after a story — project tests, an Android emulator, a browser, your own commands, and how many fixes they may cause;
• hooks — your scripts on run events: a chat message, a task board update.

[run]
level = "deep"

[executors.codex.roles.blind-hunter]
model = "gpt-6-astra"
effort = "high"

[executors.codex.roles.edge-case-hunter]
model = "gpt-6-astra"
effort = "xhigh"

[executors.claude.roles.edge-case-hunter]
model = "sonnet"
effort = "high"

Each layer is its own subagent. Levels choose active checks and depth; optional explicit per-level overrides change a subagent's model/effort without replacing its identity.

How to set it up and what each key means — Configuration.

Unattended

Example for Claude Code:

auto-bmad setup headless --repo . --write    # once: .claude/auto-bmad-headless.json
mkdir -p .auto-bmad/runs
claude -p "/auto-bmad:auto-bmad epic-1" \
  --permission-mode acceptEdits --permission-prompts none \
  --settings .claude/auto-bmad-headless.json \
  --output-format stream-json --verbose > .auto-bmad/runs/epic-1.jsonl

For cron, launchd or CI use examples/run-epic.sh — see Unattended runs.

Documentation

License

MIT