/bmad-help

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](${CLAUDE_PLUGIN_ROOT}/skills/bmad-help/REFERENCE.md).

How it works

1. **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.

2. **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.

3. **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.

1. No `project-context.md` → establish project context (run `bmad-init`, or `bmad-product-brief` if the user opts into Analysis). Confirm the track. 2. No `prd.md` and no `tech-spec.md` →

• Quick Flow → `bmad-tech-spec` (tech-spec).
• BMad Method / Enterprise → `bmad-prd` (PRD).

3. Project has a UI and no `ux-design.md` (BMad/Enterprise) → `bmad-ux`. 4. Track needs architecture and no `architecture.md` (BMad/Enterprise) → `bmad-architecture`. (Quick Flow skips architecture.) 5. Enterprise and no security/devops planning → `bmad-architecture` (security + devops sections / handoff). 6. No `epics.md` (BMad/Enterprise) → `bmad-epics-and-stories` (epic breakdown). 7. No story files under `stories/` → `bmad-epics-and-stories` (create ready-for-dev stories). 8. 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. 9. 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](${CLAUDE_PLUGIN_ROOT}/skills/bmad-help/REFERENCE.md).

Notes for Claude

• This is the entry point. Always detec