cfahed

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)

1. /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.
2. /story-setup-ci — Run once to install the GitHub Actions workflow that auto-syncs issue closures to BMAD files.
3. /story-create — Pick the next story, run the BMAD planning workflow, update GitHub labels.
4. /story-dev — Set up a git worktree, implement the story with granular commits, open a PR.
5. /story-review — Run BMAD code review; the story stays at review status (not done).
6. The user reviews and merges the PR on GitHub (quality gate).
7. /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