bmad

BMAD Packet-First Router

Use bmad as the common-layer BMAD/BMM front door.

The job is not to dump every phase command or runtime setup rule. The job is to:

1. identify the packet the user already has,
2. choose the project level and likely current phase,
3. recommend the single next artifact or gate that reduces ambiguity now,
4. route runtime-, review-, execution-, or game-specific detail outward.

Read references/intake-packets-and-route-outs.md first for the fastest routing model. Use references/core-routing.md, references/status-and-review.md, and references/runtime-and-module-boundaries.md when you need more depth.

When to use this skill

• The user wants to start or resume a BMAD/BMM-style workflow from mixed project state
• The user asks what phase comes next after idea notes, a PRD, a tech spec, architecture work, or partial implementation
• The user has an existing repo, issue, review note, or brownfield status and needs the next artifact chosen truthfully
• The user wants a vendor-neutral BMAD front door before dropping into Claude-, Codex-, or Gemini-specific runtime overlays
• The user needs help deciding whether the next move is ideation, planning, architecture, approval, execution slicing, or runtime handoff

When not to use this skill

• The main need is open-ended concept shaping before project framing exists → use bmad-idea
• The main need is a game-production packet (GDD, playtest notes, build issues, launch beats) → use bmad-gds
• The main need is artifact approval, annotation, or plan review → use plannotator
• The main need is execution-ready backlog slicing after the next artifact is already known → use task-planning
• The main need is runtime-specific orchestration setup for Claude Code → use oh-my-claudecode
• The main need is Codex-first workflow runtime behavior → use oh-my-codex
• The main need is Gemini / Antigravity portable harness setup → use oh-my-agent

Instructions

Step 1: Normalize the intake as one primary packet

Before talking about phases, choose the single best packet that describes the current ask:

bmad_packet:
  packet_type:
    - concept-packet
    - planning-packet
    - architecture-packet
    - review-gate-packet
    - execution-packet
    - runtime-handoff-packet
    - brownfield-resume-packet
  evidence_in_hand:
    - idea-notes
    - product-brief
    - prd
    - tech-spec
    - architecture-draft
    - review-feedback
    - active-repo
    - issue-or-bug-link
    - sprint-plan
    - milestone-or-launch-pressure
  project_type: web-app | backend-api | mobile-app | game | library | automation | unknown
  project_level: 0 | 1 | 2 | 3 | 4 | unknown
  runtime_context: claude | codex | gemini | opencode | mixed | unknown
  main_constraint: ambiguity | review-blocker | execution-readiness | runtime-setup | brownfield-drift | unknown

Rules:

• Pick one primary packet first, even if the user mentions several artifacts.
• If the packet is obviously pre-planning, say so and route to bmad-idea early.
• If the packet is mostly game-production coordination, route to bmad-gds early.
• If the request starts from an existing repo, issue, or partial implementation, prefer brownfield-resume-packet over pretending the project is greenfield.

Step 2: Choose project level before artifact depth

Use this scale:

• Level 0 — single atomic change, bug fix, config tweak
• Level 1 — small feature, limited files, low coordination cost
• Level 2 — medium feature set, cross-cutting behavior, clear planning + architecture need
• Level 3 — complex integration, multiple subsystems, API/data contracts, multi-sprint delivery
• Level 4 — major overhaul, platform migration, enterprise-scale coordination

Do not force architecture or heavyweight planning onto level 0–1 work unless the visible packet truly requires it.

Step 3: Infer the likely current phase from the packet

Use the packet to infer the current BMAD phase, not the other way around:

Packet type	Likely phase	Default next artifact or gate
concept-packet	analysis	product-brief or route to bmad-idea
planning-packet	planning	prd or tech-spec
architecture-packet	solutioning	architecture or architecture review gate
review-gate-packet	boundary between phases	plannotator review before advancing
execution-packet	implementation	sprint-plan, story packet, or route to task-planning
runtime-handoff-packet	implementation-ready	runtime route-out to oh-my-claudecode, oh-my-codex, or oh-my-agent
brownfield-resume-packet	mixed / unknown	workflow-status update, repo-state summary, then the smallest truthful next artifact

Guiding rules:

• Prefer the smallest truthful next artifact.
• If an artifact already exists but has not been reviewed, the next move is often the review gate, not another new document.
• If the request is really a runtime/setup ask, keep bmad short and route outward.

Step 4: Choose one next artifact, not a parallel stack

Pick the single next artifact or gate that best reduces ambiguity now:

Current state	Preferred next move
vague idea, opportunity, user problem	product-brief
requirements emerging, implementation shape still unclear	prd or tech-spec
planning exists, system shape is still fuzzy	architecture
architecture exists but approval is missing	review gate
approved architecture exists, execution slicing is weak	sprint-plan or story packet
active implementation exists but status is unclear	workflow-status update + next-story recommendation
runtime is the real blocker after approval	runtime handoff to oh-my-claudecode / oh-my-codex / oh-my-agent

Step 5: Route specialist work explicitly

If the front-door decision is made, route the rest clearly:

• bmad-idea → pre-planning concept framing before formal BMAD artifacts exist
• plannotator → review / approval gate for PRD, architecture, sprint plan, or plan diffs
• task-planning → execution-ready slicing after the next artifact is approved or obvious
• oh-my-claudecode → Claude-first runtime orchestration, hooks, team mode, stop callbacks
• oh-my-codex → Codex-first orchestration, AGENTS.md injection, workflow skills, tmux team runtime
• oh-my-agent → Gemini / Antigravity portable harness, .agents/ source of truth, generated runtime views
• bmad-gds → game-specific production routing

Leave a short reason for the route-out. Do not just name the neighboring skill.

Step 6: Keep state and review visible

When a project already uses BMAD state files or helper scripts, keep them in the loop:

• inspect status/config artifacts before recommending a phase leap
• if a required artifact exists but lacks approval, route to plannotator
• prefer script/status awareness over re-deriving the workflow from scratch
• use brownfield evidence honestly instead of pretending the project is still at idea stage

Step 7: Produce a compact BMAD routing brief

Always return this structure:

# BMAD Routing Brief

## Scope
- Packet type: ...
- Project type: ...
- Project level: 0 | 1 | 2 | 3 | 4
- Runtime context: ...
- Confidence: high | medium | low

## Current phase
- analysis | planning | solutioning | implementation | mixed | unknown
- Why: ...

## Recommended next move
- product-brief | prd | tech-spec | architecture | review gate | sprint-plan | story packet | workflow-status update | runtime handoff

## Why this is next
- 2-4 bullets grounded in the packet

## Route-outs
- Skill / module: ...
- Why: ...
- What to pass forward: ...

## What not to do yet
- 1-3 bullets preventing premature detail or the wrong lane

Step 8: Push detail into references

Do not inflate the main response with every helper script, command family, or runtime rule. Use the references when needed:

• intake packets and route-outs
• core routing model
• status files, scripts, and review gates
• runtime and module boundaries

Output format

Return a short BMAD routing brief.

Required qualities:

• choose one primary packet before choosing the next artifact
• make the project-level assumption explicit
• keep review-gate visibility before phase advancement
• keep runtime/setup detail separated from the common BMAD layer
• keep the result under roughly 400-700 words unless the user asks for a full workflow packet

Examples

Example 1: brownfield repo, unclear next step

Input

Use bmad. We already have a repo and some product notes, but planning drifted and I don't know whether we need a PRD, architecture, or just sprint planning.

Output sketch

• Packet type: brownfield-resume-packet
• Likely phase: mixed
• Recommended next move: workflow-status update, then whichever artifact is actually missing
• Route-outs only after the missing artifact is identified

Example 2: architecture exists, execution weak

Input

We already wrote the architecture doc for our API migration. What should we do next in BMAD?

Output sketch

• Packet type: architecture-packet
• Current phase: solutioning
• Recommended next move: review gate if architecture is unreviewed, otherwise sprint-plan
• Route-out: plannotator first, task-planning second

Example 3: runtime-specific follow-up

Input

I want BMAD for Codex CLI. What should I actually use?

Output sketch

• Keep bmad as the packet/phase router
• Packet type: runtime-handoff-packet
• Route Codex runtime specifics to oh-my-codex
• Do not turn bmad into a Codex setup guide

Best practices

1. Act like a packet-first router — start from the artifact or evidence the user already has.
2. Choose level before depth — level 0–1 and level 2–4 should not produce the same paperwork.
3. Keep review visible — if approval is the blocker, say so before inventing a new artifact.
4. Keep runtime overlays separate — oh-my-claudecode, oh-my-codex, and oh-my-agent own vendor/runtime specifics.
5. Prefer one clear handoff — one next move plus one or two route-outs beats a giant workflow dump.
6. Use references for deep detail — helper scripts, status rules, and runtime boundaries belong in support docs.

References

• Intake packets and route-outs
• Core routing model
• Status files, scripts, and review gates
• Runtime and module boundaries
• ./scripts/init-project.sh
• ./scripts/check-status.sh
• ./scripts/phase-gate-review.sh
• Upstream BMAD README
• ../bmad-idea/SKILL.md
• ../plannotator/SKILL.md
• ../task-planning/SKILL.md
• ../bmad-gds/SKILL.md