BMAD Skills for OpenAI Codex

BMAD Skills for OpenAI Codex adds a structured, intent-driven workflow to Codex for product discovery, planning, architecture, and implementation.

It installs reusable BMAD skills, introduces bmad:* intents, and keeps project workflow state in explicit YAML files inside your repository.

Original GitHub project: xmm/codex-bmad-skills

What This Project Does

This repository provides:

• BMAD skills that can be installed into Codex
• intent-based workflow routing via bmad:*
• project-local workflow state in bmad/*.yaml
• a repeatable path from idea to implementation

Use it when you want Codex to guide work through defined phases instead of relying on ad-hoc prompts.

Who This Is For

This project is for:

• developers using OpenAI Codex as a primary coding assistant
• teams that want a consistent AI-assisted delivery workflow
• projects that need explicit planning and traceable workflow state

Quick Start

Requirements

• yq v4+
• python3 (or python)

The installers validate both dependencies before install.

Install

Install to the default global path

./installers/install-codex.sh

Install to a custom path (example: project-local)

./installers/install-codex.sh --dest "/.agents/skills"

Windows PowerShell

./installers/install-codex.ps1
./installers/install-codex.ps1 -Dest "\.agents\skills"

Notes:

• --dest and -Dest are optional
• the default destination is $HOME/.agents/skills
• restart Codex after installation so it reloads newly installed skills

Start Codex

codex

Initialize BMAD in a Project

bmad:init name "My Project" communication language is English documentation language is English

Check Current Status

bmad:status
bmad:next

For a guided walkthrough, see Getting Started.

What Gets Created

After initialization, the project contains:

• bmad/project.yaml - project settings and language preferences
• bmad/workflow-status.yaml - current workflow phase and progress
• bmad/sprint-status.yaml - sprint and delivery tracking
• docs/bmad/ - generated BMAD documents
• docs/stories/ - implementation stories

How The Workflow Works

BMAD in Codex is organized into four main phases.

1. Analysis

Use this phase to explore the problem space and define direction.

Typical intents:

• bmad:product-brief
• bmad:research
• bmad:brainstorm

Typical outputs:

• docs/bmad/product-brief.md
• docs/bmad/research-report.md
• docs/bmad/brainstorm.md

2. Planning

Use this phase to turn discovery into scoped plans and product documentation.

Typical intents:

• bmad:prd
• bmad:tech-spec
• bmad:prioritize
• bmad:ux-design

Typical outputs:

• docs/bmad/prd.md
• docs/bmad/tech-spec.md
• docs/bmad/prioritization.md
• docs/bmad/ux-design.md

Planning rules:

• level 0-1 projects require tech-spec
• level 2-4 projects require prd and architecture

3. Solutioning

Use this phase to define architecture and validate readiness before implementation.

Typical intents:

• bmad:architecture
• bmad:gate-check

Typical outputs:

• docs/bmad/architecture.md
• docs/bmad/gate-check.md

4. Implementation

Use this phase to plan delivery, create stories, build, and review.

Typical intents: