bmad-orchestrator

Drop a complete BMAD orchestration layer into an existing repository — the story-ready → dev-story → code-review workflow, an enforced pre-implementation gate, and a documentation skeleton — with a single command. Fully additive: it never overwrites a file you already have.

npx bmad-orchestrator

Run it at the root of your project, answer a few questions, and you're set up.

What it does

Running the command adds, alongside your existing code:

• _bmad/ — the BMAD Method framework (v6.9.0) plus the enforcement scripts (gate_hook.py, verify_story_gate.py).
• .claude/skills/ — the BMAD skill set plus five workflow wrappers: story-ready, dev-story, code-review, review-pr, ship-pr.
• A PreToolUse gate hook in .claude/settings.json that blocks a story from being marked implemented until it has passed hardening.
• docs/ — starter templates: repo-risks.md (project invariants), CONTEXT.md, and one development-guide-<app>.md per app you name.
• _bmad-output/ — the planning/implementation artifact tree and a sprint-status.yaml starter.

Safety

The installer is strictly additive and idempotent:

• Never overwrites. Any file that already exists is left untouched.
• CLAUDE.md — appends a marker-guarded BMAD section; your content is preserved.
• .claude/settings.json — merges the gate hook into your existing hooks, keeping everything else intact.
• .gitignore — appends only the entries that are missing.
• Re-runnable. A second run changes nothing.

The workflow

/story-ready <id>   →   ⏸ approve cases   →   /dev-story <id>   →   /code-review

Each gate (Hardened → Implemented → Reviewed) is enforced by the hook, not by convention. Bypass intentionally with SKIP_GATE=1.

After installation

Open _bmad-output/BMAD-NEXT-STEPS.md. In short:

1. Fill docs/repo-risks.md with at least one invariant (Rn) row — until then, story-ready runs in light mode only.
2. Fill the Verify section of each docs/development-guide-<app>.md with your real lint/format/test commands.
3. Review the changes and commit.

Requirements

• Node.js ≥ 18 (to run the installer).
• Python ≥ 3.11 (the gate and config scripts use the standard library only).
• Claude Code — the skills and hook target it.

How it works

It runs the official BMAD installer (pinned to a tested version, shipped as a dependency) to lay down a fresh framework, then overlays a thin custom layer: the five workflow wrappers, the enforcement scripts, a documentation skeleton, and the gate hook. Nothing is vendored or frozen — the framework comes straight from BMAD, so upgrading is a version bump rather than a re-bundle.

The workflow skills are generic: they read your project's docs/repo-risks.md and docs/development-guide-<app>.md, so the same tooling adapts to any codebase.

License

MIT © phamgiang-bhdn

Built on the BMAD Method.