bmad-automator

Story Automator

Portable BMAD bmad-story-automator skill/plugin bundle. This repo packages:

• skills/bmad-story-automator
• skills/bmad-story-automator-review
• the Python helper runtime inside skills/bmad-story-automator

This is the Python port of bma-d/bmad-story-automator-go. The Go README is the stylistic and operator-facing reference; this repo now documents the Python implementation in the same spirit, but with Python-specific behavior and Codex child-session support.

The root skills/ folder follows the Claude skill convention: each skill is a directory with its own SKILL.md. You can copy either skill folder directly into .claude/skills/. The repo also includes .claude-plugin/plugin.json, so the same root layout can be loaded as a Claude Code plugin with claude --plugin-dir ..

Claude Plugin Layout

This repo follows the Anthropic Claude Code plugin layout:

.
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── skills/
│   ├── bmad-story-automator/
│   │   └── SKILL.md
│   └── bmad-story-automator-review/
│       └── SKILL.md
├── bin/
└── README.md

• .claude-plugin/plugin.json is the plugin manifest.
• .claude-plugin/marketplace.json is the marketplace catalog entry.
• skills/ stays at the plugin root, not inside .claude-plugin/.
• bin/ stays at the plugin root so plugin executables can be added to Claude Code's Bash path.

Local plugin test:

claude --plugin-dir .

Local marketplace test:

/plugin marketplace add .
/plugin install bmad-automator@bmad-plugins

Quickstart

Install into the target BMAD project:

cd /absolute/path/to/your-bmad-project
npx bmad-story-automator

Or install from anywhere:

npx bmad-story-automator /absolute/path/to/your-bmad-project

Then run the installed skill from your supported entrypoint session:

Use the bmad-story-automator skill.

Manual skill copy:

cp -a skills/bmad-story-automator /absolute/path/to/project/.claude/skills/
cp -a skills/bmad-story-automator-review /absolute/path/to/project/.claude/skills/

BMAD Method Install Channels

If you install Automator through the BMAD Method official module code automator, choose the channel explicitly. Run these from the target BMAD project root, or add --directory /absolute/path/to/your-bmad-project.

Stable install, using the latest pure-semver tag:

npx bmad-method install --modules automator --all-stable --tools claude-code --yes

Stable pin to the first Codex-capable stable tag:

npx bmad-method install --modules automator --pin automator=v1.15.0 --tools codex --yes

Rollback to the pre-Codex stable tag if needed:

npx bmad-method install --modules automator --pin automator=v1.14.2 --tools claude-code --yes

Codex preview branch, only for testing unpublished follow-up fixes:

npx bmad-method install --custom-source https://github.com/bmad-code-org/bmad-automator@next/codex-runtime-support --tools codex --yes

Current caveat: the official registry sets automator to default_channel: next, so unqualified --modules automator and --next automator resolve to main HEAD. After this stable release lands on main, those commands include Codex support, but use --all-stable or --pin when you need reproducible stable behavior. For custom-source branch testing, verify the custom-source cache HEAD and installed runtime files instead of trusting installer exit status, summary text, or manifest channel fields alone.

Expectations

• This is an orchestrator, not a correctness guarantee. Bad planning artifacts still produce bad implementation runs.
• The npm installer writes the skill into every supported dependency skill root that is complete: .agents/skills, .claude/skills, and/or .codex/skills.
• Child sessions can use Claude or Codex depending on agent configuration.
• Retrospectives inherit the configured primary agent by default, and can be overridden explicitly via agentConfig.
• The automator expects sprint planning to be complete before it starts.
• Review completion is gated by verification, not by child-session exit alone.
• If the optional QA automate skill is missing, install still succeeds, but runs should use Skip Automate = true.

What This Is

Story Automator automates the BMAD implementation loop for one or more stories:

1. create story
2. implement story
3. optionally run automate/test generation
4. run adversarial code review with retries
5. commit verified work
6. trigger retrospective when an epic is fully complete

The core runtime model is:

• one orchestrator session
• one markdown state document
• many short-lived tmux child sessions
• one marker file guarding against accidental stop
• sprint-status.yaml plus story files as the source of workflow truth

How It Works