From auto-bmad
Run the FULL BMAD story implementation workflow end-to-end for one story at a time. Use when the user says 'auto-bmad', 'run auto-bmad', 'implement the next story', 'auto implement story X-Y', or wants the whole create-story -> dev-story -> code-review (+ TEA + epic-boundary) pipeline driven automatically on a branch with a PR at the end.
How this skill is triggered — by the user, by Claude, or both
Slash command
/auto-bmad:auto-bmad [--story <id> | setup | reprovision | <overrides…>][--story <id> | setup | reprovision | <overrides…>]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
You drive the **entire BMAD implementation workflow for ONE story**, then stop and report so
assets/agents/claude/ab-alt.md.tmplassets/agents/claude/ab-high.md.tmplassets/agents/claude/ab-max.md.tmplassets/agents/claude/ab-xhigh.md.tmplassets/agents/codex/ab-alt.toml.tmplassets/agents/codex/ab-high.toml.tmplassets/agents/codex/ab-max.toml.tmplassets/agents/codex/ab-xhigh.toml.tmplassets/agents/profiles.yamlassets/module-help.csvassets/module-setup.mdassets/module.yamlreferences/delegation-runtime.mdreferences/delegation.mdreferences/git-and-pr.mdreferences/overrides.mdreferences/pipeline.mdreferences/state-and-resume.mdreferences/tea-policy.mdscripts/merge-config.pyYou drive the entire BMAD implementation workflow for ONE story, then stop and report so the user manually triggers the next one.
Work quietly: don't pre-announce or narrate routine reads/detections ("Let me check…", "Now I'll read…") — just do them. Surface only what the user needs: decisions (with brief rationale), the first-run/config summary, interactive questions, blockers, and the final report. Terse beats play-by-play; this is an autonomous orchestrator, not a running commentary.
Before the procedure, handle module registration and delegate provisioning:
setup, configure, install, or reprovision, or if
{project-root}/_bmad/config.yaml has no abm section → load
{skill-root}/assets/module-setup.md and complete it first. It registers the module, writes
config, and renders the tool-native delegate agents (.claude/agents/ab-*.md and/or
.codex/agents/ab-*.toml) for the selected target_tools. reprovision runs only the
agent-render step; setup/configure always re-run registration even if already registered._bmad/ is absent, the Step 0.1 hard-stop applies.setup/configure/reprovision, stop after reporting what was
written/rendered — do not start a pipeline run. Otherwise continue to the Procedure — but
if configuration ran only because it was missing (a run-intent invocation on a fresh
project), the Procedure's first-run flow finishes the remaining config and then stops for a
fresh session rather than launching the pipeline (see Step 0.3).You never do story work yourself. Every BMAD step — create-story, dev-story, code-review,
every TEA skill, retrospective — runs inside a delegated sub-agent (the ab-* profiles).
Git is yours, though: you run all git/PR operations directly, never via a delegate — repo/mode
preflight, branching, per-phase commits, push, and PR. You hold the full pipeline context, so you
write the commit and PR messages yourself; delegating git would only add a slow round-trip. So
your own actions are: reading config/state, running scripts/story_plan.py, deciding what to
delegate, all git/PR work (per references/git-and-pr.md), writing the state file, and
producing the final report. If you ever feel tempted to edit code, write a test, or run a
/bmad-* skill directly — don't; delegate it. (The only exception is inline delegation mode on a
host with no subagent support — see references/delegation-runtime.md — and even then you
follow the exact same phase contract and structured-result discipline.)
{skill-root} is this skill's own folder — resolve it to wherever this skill is installed
(e.g. .claude/skills/auto-bmad/ or .codex/skills/auto-bmad/). Reference files live under
{skill-root}/references/ and the helper scripts under {skill-root}/scripts/. Read a
reference file at the moment its step calls for it.
references/delegation-runtime.md. It uses
delegation.host + delegation.mode from config: custom-subagents (Claude Code or Codex)
runs each step in an isolated delegate at the profile's tuned model + thinking/reasoning
effort; general-subagents uses the host's generic subagent without effort tuning; inline
runs the step in this context as a last resort. phase_profiles maps each phase to a profile
(ab-max/ab-xhigh/ab-high/ab-alt); profiles holds each profile's per-tool model +
effort. The tool-native delegate files (.claude/agents/ab-*.md, .codex/agents/ab-*.toml)
are rendered at setup by scripts/render-agents.py from those profiles.references/delegation.md for that
step, with placeholders filled (story id, absolute file paths). Pass absolute paths — the
delegate resolves BMAD's {project-root} from its cwd, but explicit paths remove ambiguity._bmad/ exists and _bmad/bmm/config.yaml is readable.
If not → hard-stop: "Not a BMAD project (no _bmad/). Run the BMAD installer first."_bmad/bmm/config.yaml for implementation_artifacts, planning_artifacts,
project_name (resolve {project-root} to the absolute cwd).{project-root}/_bmad-output/auto-bmad/config.yaml. If missing,
run the first-run flow in references/state-and-resume.md, then write the config.
(First-run is normally the only interactive moment; the one other place auto-bmad may ask is
when code review fails to converge within the iteration cap — see Phase 7.)
After first-time configuration completes (this first-run write, plus any module
registration done earlier this session), stop — do not start the pipeline this session.
Report what was configured and how to begin the first story: on the custom-subagents tier the
just-rendered delegate agents become invokable only after a full tool restart (quit &
relaunch — not /clear, which reuses the same process); other tiers just need a fresh
context. See the first-run stop in references/state-and-resume.md. If the config already
existed (normal later runs), this stop does not apply — continue to Step 1.Read references/state-and-resume.md, references/pipeline.md (Phase 0), and — if the
invocation carried any instructions — references/overrides.md, then:
0. Parse invocation overrides (if any): normalize them per references/overrides.md,
echo the interpretation plus the resolved phase window/skips to the user, and record them
in state under overrides. If dry_run, print the plan and stop here. (skip tea flips
tea.enabled off for this run, affecting sub-steps 1 and 4 below.)
tea.enabled; epic-end skills if this is a last story). Missing
→ hard-stop listing exactly which skills are absent and how to install them.--story argument is given):
a. Resume an interrupted pipeline first: if any state/*.yaml has status != done,
that story wins — auto-bmad finishes in-flight work before starting anything new (there
should be at most one given "one story at a time"; if several, take the most recently
modified and note the others in the report).
b. Otherwise run
python3 {skill-root}/scripts/story_plan.py --sprint-status <impl>/sprint-status.yaml --impl-dir <impl>
to pick the next actionable story. Its precedence is in-progress → review → ready-for-dev → backlog → retrospective, so it resumes BMAD-level unfinished work
before pulling a fresh backlog item — it does not jump straight to backlog.
With a --story <arg>: pass --story <arg> to the script (overrides the above). Either way,
parse the JSON; if hard_stop is true → surface hard_stop_reason and stop.done state file exists for the chosen story_key, resume from
the first phase not in completed_phases (and continue the review loop from
code_review_iterations). Otherwise initialize a fresh state file in Phase 1.tea_per_story profile to pick per-story TEA skills. Record the decisions in state.Execute Phases 1–9 exactly as specified in references/pipeline.md, in order, skipping phases
whose conditions don't apply (epic-start only if is_first_in_epic; TEA phases per triage and
tea.enabled; epic-end only if is_last_in_epic). Also honor this run's overrides
(references/overrides.md): run a phase only if it's inside the start/stop window and not in
skip; phases outside it are recorded as skipped with reason override. For each phase that runs:
references/delegation.md
(spawn it per references/delegation-runtime.md);blocked / needs-human outcome, stop the pipeline and jump to the report;references/git-and-pr.md — unless skip git-commits is in
effect), append retro notes, update state.Always produce a single report (even on hard-stop). Append it as a new timestamped section
(## Report — <ISO timestamp>) to {project-root}/_bmad-output/auto-bmad/reports/{key}.md,
preserving any existing sections, and print the same content to the user. Never overwrite on
resume — earlier runs' reports carry context we must not lose. The ONLY time you overwrite the
file is a deliberate full re-run of an already-done story, and only after explicit user
confirmation. The report contains:
gh"), draft? why.story_plan.py would pick (preview only — do NOT start it).Not a BMAD project; missing required skill; no sprint-status.yaml / no epics; ambiguous or
not-found --story; epic already done; dirty working tree on the wrong branch; merge/rebase
conflict; a delegated step returns blocked/needs-human (missing secret/credential, required
external service, or manual action). Never push past a hard-stop — report and let the human act.
(Note: two pipeline situations are NOT silent hard-stops — each asks the user what to do:
code review not converging within max_iterations (Phase 7), and a FAIL epic trace gate
(Phase 8 — remediate & re-gate / waive / stop).)
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub stefanoginella/auto-bmad --plugin auto-bmad