bmad-help

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.

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

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

1. No prd.md and no tech-spec.md →

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

1. Project has a UI and no ux-design.md (BMad/Enterprise) → bmad-ux.
2. Track needs architecture and no architecture.md (BMad/Enterprise) →

bmad-architecture. (Quick Flow skips architecture.)

1. Enterprise and no security/devops planning → bmad-architecture (security + devops

sections / handoff).

1. No epics.md (BMad/Enterprise) → bmad-epics-and-stories (epic breakdown).
2. No story files under stories/ → bmad-epics-and-stories (create ready-for-dev stories).
3. 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.

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