Agent Plugins
A Claude Code plugin marketplace for agent-driven development workflows.
bmad-github
BMAD + GitHub story workflow orchestration with git worktrees for parallel agent development.
This plugin bridges BMAD Method workflows with GitHub project management.
It orchestrates BMAD's create-story, dev-story, and code-review workflows while adding GitHub issue sync, git worktree
management, auto-commits per task, and PR creation.
Why a Claude Code plugin?
BMAD modules are conversational guides — they tell the AI what to do step by step. This plugin operates at the
runtime/DevOps layer, orchestrating those same BMAD workflows while managing gh, git worktree, branches, labels,
milestones and PRs. These are concerns that BMAD's module system isn't designed to handle.
Prerequisites
- Claude Code installed
gh CLI installed and authenticated (gh auth login)- Node.js (for the batch sync script)
- A project using the BMAD Method with
_bmad/ directory (output folder is read from
_bmad/bmm/config.yaml, defaults to _bmad-output/)
Installation
/plugin marketplace add choucrifahed/agent-plugins
/plugin install bmad-github@cfahed
Commands
The plugin provides six slash commands that form a story lifecycle. These commands orchestrate BMAD's own
workflows (create-story, dev-story, code-review) under the hood — if you update your BMAD modules, the
plugin automatically picks up the changes.
| Command | Description |
|---|
/story-init | Batch sync BMAD epics to GitHub — creates milestones, labels, and issues from epics.md |
/story-setup-ci | Install the BMAD Story Sync GitHub Actions workflow into the current project |
/story-create | Sync GitHub state, then run BMAD create-story workflow to plan a story, marks the GitHub issue in ready |
/story-dev | Create a git worktree, run BMAD dev-story workflow with auto-commits per task, then create a PR |
/story-review | Run BMAD adversarial code review and push fixes (does NOT mark story as done) |
/story-sync | Reconcile GitHub state with BMAD files — detects merged PRs, marks stories done, cleans up worktrees |
Workflow
story-init ──► story-create ──► story-dev ──► story-review
│ │
│ ◄── (fix issues) ◄───┘
│
└──────── story-sync ◄── (user merges PR on GitHub)
/story-init — Run once to create GitHub milestones and issues from your BMAD epics.
You can also run it everytime you change your roadmap in BMAD to add new issues and milestones
in GitHub./story-setup-ci — Run once to install the GitHub Actions workflow that auto-syncs issue closures to BMAD files./story-create — Pick the next story, run the BMAD planning workflow, update GitHub labels./story-dev — Set up a git worktree, implement the story with granular commits, open a PR./story-review — Run BMAD code review; the story stays at review status (not done).- The user reviews and merges the PR on GitHub (quality gate).
/story-sync — Detects the merged PR, marks the story as done in BMAD, cleans up the worktree and branch.
The user is always the quality gate — no story is marked done without human review and merge. If an issue is closed
manually (without a merged PR), /story-sync will warn and ask the user for feedback rather than marking it done and
cleaning up the worktree.
Configuration
The plugin stores per-project configuration in .claude/bmad-github.local.md:
---
worktree-root: ../my-project-worktrees/
---
| Field | Default | Description |
|---|
worktree-root | ../<repo-name>-worktrees/ | Directory where git worktrees are created |
This file is auto-created on first run of /story-dev or /story-sync.
BMAD Output Folder
The plugin reads the BMAD output folder from _bmad/bmm/config.yaml or _bmad/bmb/config.yaml (output_folder key).
If no config is found, it defaults to _bmad-output. This makes the plugin portable across different BMAD setups.
Epics → Milestones
Each BMAD epic from <output_folder>/planning-artifacts/epics.md becomes a GitHub milestone titled Epic <N>: <Title>
(e.g., Epic 1: Core Infrastructure). Creation is idempotent — existing milestones are skipped. Every story issue is
assigned to the milestone matching its epic number.
Labels
The plugin manages two categories of labels, all created automatically by /story-init.
Type Labels
