| name | bmad-help |
| description | Orchestration spine and "what do I do next?" router for the BMAD Planning & Orchestrator plugin. Detects current planning state by scanning the output folder for which artifacts exist (project-context.md, decision-log.md, product-brief, prd/tech-spec, architecture, ux, epics, stories), infers the current phase and track, then recommends the next BMAD skill to run — skipping optional phases (Analysis is always optional; UX only when there is a UI). Use when the user asks "what's next", "what do I do next", "where am I", "what's my status", "continue", "resume planning", "which skill should I run", "what BMAD step is next", or types "/bmad-help" / "/status". Auto-invoke at the start of any BMAD planning session to orient. This skill ROUTES only — it never writes planning documents itself.
|
| allowed-tools | Read, Bash, Glob, Grep, TodoWrite |
BMAD Help — Orchestration Spine
A lean router. It answers one question: what do I run next? It detects planning
state, infers the phase and track, and points to the next skill. It is auto-invoked to
orient a session and replaces a heavyweight master/orchestrator agent.
This skill produces NO planning documents. It reads state and recommends. All
artifacts are produced by the specialized planning skills it routes to.
When to use
- User asks "what's next", "where am I", "what's my status", "continue", "resume".
- Start of any BMAD session, to orient before doing planning work.
- User is unsure which skill to invoke.
Phase Map
Analysis ──► Planning ──► Solutioning ──► Implementation-handoff
(optional) (required) (conditional) (required: ready-for-dev stories)
| Phase | Artifact(s) | Skill |
|---|
| Analysis (optional) | product-brief, research, brainstorm | bmad-product-brief / bmad-research / bmad-brainstorm |
| Planning (required) | prd.md OR tech-spec.md, epics.md | bmad-prd / bmad-tech-spec / bmad-epics-and-stories |
| Planning — UX (only if UI) | ux-design.md | bmad-ux |
| Solutioning (track-dependent) | architecture.md | bmad-architecture |
| Implementation-handoff (required) | {epic}.{story}.{slug}.story.md (ready-for-dev) | bmad-epics-and-stories → bmad-sprint-planning |
Threaded across every phase: project-context.md (the project "constitution") and
decision-log.md (decisions carried between workflows). If these are missing, the
first recommendation is always to establish them.
Implementation itself (writing code, running tests) is OUT OF SCOPE. The last artifact
this plugin produces is a ready-for-dev story file or handoff manifest, passed to an
external dev tool.
Tracks (scale-adaptive — never numbered levels)
A heuristic may suggest a track from story count; the user confirms.
| Track | Scope | Required planning | Optional |
|---|
| Quick Flow | 1–15 stories | tech-spec + stories | analysis, ux |
| BMad Method | 10–50+ stories | prd + architecture + epics + stories | analysis; ux (if UI) |
| Enterprise | 30+ stories | prd + architecture + security + devops + epics + stories | analysis |
Per-track required vs optional steps in detail: see
REFERENCE.md.
How it works
-
Detect state. Run the detector to list which artifacts exist and the inferred
phase:
bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-help/scripts/detect-state.sh [output-folder]
Default output folder is bmad-output/. It prints a checklist of artifacts (present
or missing), the detected track (from decision-log if recorded), and the inferred
phase.
-
Recommend next. Map the detected state to the next skill:
bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-help/scripts/recommend-next.sh [output-folder]
It prints the single next skill to run, plus why, plus any skipped optional phases.
-
Present the recommendation to the user in plain prose. Offer to invoke the
recommended skill. Do not auto-run planning skills without confirmation when the
track is still ambiguous.
If project-context.md does not exist yet, treat the project as un-initialized: the
recommendation is to start with bmad-init (or bmad-product-brief if the user wants the
optional Analysis phase first) to establish project context and choose a track.
Routing logic (summary)
Evaluate in order; recommend the first unmet step for the active track.
- No
project-context.md → establish project context (run bmad-init, or
bmad-product-brief if the user opts into Analysis). Confirm the track.
- No
prd.md and no tech-spec.md →
- Quick Flow →
bmad-tech-spec (tech-spec).
- BMad Method / Enterprise →
bmad-prd (PRD).
- Project has a UI and no
ux-design.md (BMad/Enterprise) → bmad-ux.
- Track needs architecture and no
architecture.md (BMad/Enterprise) →
bmad-architecture. (Quick Flow skips architecture.)
- Enterprise and no security/devops planning →
bmad-architecture (security + devops
sections / handoff).
- No
epics.md (BMad/Enterprise) → bmad-epics-and-stories (epic breakdown).
- No story files under
stories/ → bmad-epics-and-stories (create ready-for-dev stories).
- Stories exist but some are still
backlog/not ready-for-dev → bmad-epics-and-stories
(finish compiling story context objects); then bmad-sprint-planning to sequence waves.
- All required artifacts present and stories are
ready-for-dev → handoff
complete. Recommend handing the stories to the external dev tool. Nothing left to
plan.
Skipping rules: Analysis is always optional — never block on it. UX is recommended
only when the project has a UI. Architecture is skipped for Quick Flow.
Full decision table with edge cases: REFERENCE.md.
Notes for Claude
- This is the entry point. Always detect state before recommending.
- Recommend exactly ONE next skill. Keep it actionable.
- Never produce planning documents here — route to the owning skill.
- Never recommend running tests, builds, linters, or writing code — that is out of
scope for this plugin entirely.
- Respect locked sections: Acceptance Criteria, Dev Notes, and Testing in story files
are owned by planning skills and must not be edited downstream.
- Use
decision-log.md to read the confirmed track; if absent, ask the user to confirm
the track before recommending track-specific steps.
Part of the BMAD Planning & Orchestrator plugin — a Claude Code harness for the BMAD Method by the BMAD Code Organization (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of bmad-help. All methodology credit belongs to the BMAD Code Organization.
