How xmm/codex-bmad-skills works
1. Repository purpose
This is not an application runtime repo; it is a Codex skill pack for the BMAD workflow. The core architecture is a set of reusable skills plus installers and documentation that let OpenAI Codex respond to bmad:* intents in a structured delivery process.
2. Top-level system boundaries
The repo splits into three major areas:
- skills/ — the actual BMAD skills and workflow logic
- installers/ — platform-specific installation entrypoints
- docs/ — the published documentation and examples for users
3. Skill-pack subsystem
Each skill directory is a self-contained module with the same shape:
- SKILL.md and REFERENCE.md define the behavior and guidance
- agents/openai.yaml configures Codex agent behavior for that skill
- resources/ contains domain knowledge and checklists
- scripts/ contains validation/generation utilities
- templates/ contains the documents and artifacts the skill produces
4. Workflow orchestration layer
skills/bmad-orchestrator is the central coordination subsystem. It owns project setup, workflow state checking, next-step recommendations, and config validation. This is the layer that turns the BMAD method into a multi-phase process rather than a loose set of prompts.
5. Shared infrastructure
skills/bmad-shared provides cross-cutting utilities used by multiple skills:
- config loading
- phase/workflow checks
- status updates
- workflow registry data
This is the repo’s shared foundation for keeping skills consistent and for reading/writing project-local state.
6. Domain-specific skill modules
The remaining skill packages map to BMAD roles and phases:
- analyst: discovery and research
- product manager: PRD and prioritization
- architect: architecture and gate checks
- scrum master: sprint planning and burndown
- developer: linting, coverage, code review support
- UX designer: accessibility, responsive design, user flows
- creative intelligence: ideation and research techniques
- builder: scaffolding and skill creation
These are boundaries between responsibilities rather than runtime services.
7. Data flow: intent to artifact
The main flow is:
- user invokes a bmad:* intent in Codex
- orchestrator and shared helpers resolve the current workflow phase
- the appropriate skill processes the request
- outputs are written as repository artifacts, usually under docs/bmad/ or docs/stories/
This repo is therefore artifact-driven: the important outputs are markdown and YAML files, not persistent application state in a database.
8. Project-local state model
BMAD keeps workflow state inside the target project, typically in:
- bmad/project.yaml
- bmad/workflow-status.yaml
- bmad/sprint-status.yaml
This state boundary is important: the skills operate against repository-local YAML so progress is explicit, portable, and versionable.
9. Installation and deployment boundary
installers/install-codex.sh and installers/install-codex.ps1 are the only entrypoints that place these skills into a Codex-readable skills directory. The install path is either a default global location or a custom destination such as a project-local .agents/skills folder. The install scripts validate required tooling before copying files.
10. Validation/tooling pattern
The repo uses lightweight validation scripts inside skills to enforce consistency:
- shell scripts for template/config checks
- Python helpers for calculations like velocity or burndown
- yq and python3 as notable runtime dependencies
This keeps the workflow deterministic and machine-checkable without requiring a larger application stack.
11. Documentation site
docs/ is a generated/manual documentation subsystem, with Jekyll-style configuration in docs/_config.yml and styling in docs/assets/main.scss. It supports onboarding, workflow explanations, examples, and troubleshooting rather than product runtime behavior.
12. How the architecture should be drawn
A good diagram would show:
- Codex as the execution environment
- bmad:* intents entering the orchestrator
- shared helpers and the relevant skill package behind each phase
- project-local bmad/*.yaml state as the control plane
- generated docs/stories as the primary outputs
- installers as a separate deployment path that places the skill pack into Codex’s skills directory
Main entry points: bmad-orchestrator Orchestrator · bmad-shared Shared core · bmad-builder Builder · bmad-analyst Analyst
Components 21
Codex runtime
Execution environment that receives BMAD intents and runs installed skills.
- Codex · Host environment that receives BMAD intents and runs installed skills.
- bmad:* intents · Intent namespace used to trigger BMAD workflow actions.
- Skills dir · Destination directory where Codex discovers installed skills.
Skill pack
Reusable BMAD role and workflow skills.
- Orchestrator · Central workflow coordinator for setup, phase tracking, next-step guidance, and config validation.
skills/bmad-orchestrator - Analyst · Research and briefing skill for discovery work.
skills/bmad-analyst - Product manager · PRD, prioritization, and product specification skill.
skills/bmad-product-manager - Architect · Architecture design and gate-check skill.
skills/bmad-architect - Scrum master · Sprint planning, story sizing, and burndown skill.
skills/bmad-scrum-master - Developer · Linting, coverage, and code-review support skill.
skills/bmad-developer - UX designer · Accessibility, responsive design, and user-flow skill.
skills/bmad-ux-designer - Creative intelligence · Brainstorming and research-technique skill.
skills/bmad-creative-intelligence - Builder · Scaffolding and skill-creation skill for extending the pack.
skills/bmad-builder
Shared workflow core
Cross-cutting orchestration and state utilities used by multiple skills.
- Shared core · Common config, phase, status, and registry helpers shared across skills.
skills/bmad-shared
Installers
Platform-specific entrypoints that copy the skill pack into a Codex-readable location.
- install-codex.sh · Shell installer that validates tooling and copies skills into a destination.
installers/install-codex.sh - install-codex.ps1 · PowerShell installer for placing the skill pack into a Codex skills directory.
installers/install-codex.ps1
Documentation
Published guidance, examples, and site assets.
- Artifacts · Workflow outputs such as briefs, PRDs, architectures, stories, and reviews.
- Docs site · Published onboarding, workflow, examples, and troubleshooting documentation.
docs - Site config · Jekyll-style documentation configuration and styling inputs.
docs/_config.yml
Project state
Repository-local YAML state written by workflows in target projects.
- project.yaml · Project-local workflow configuration and setup state.
- workflow-status.yaml · Project-local workflow phase and progress state.
- sprint-status.yaml · Sprint tracking state written by planning workflows.
Connections 30
- Codex → bmad:* intents: receives · Codex accepts BMAD intent commands.
- bmad:* intents → Orchestrator: dispatches to · Intent routing begins with the orchestrator for workflow coordination.
- Orchestrator → Shared core: uses · Orchestrator relies on shared config and phase utilities.
- Shared core → project.yaml: reads/writes · Shared helpers load and update project-local configuration.
- Shared core → workflow-status.yaml: reads/writes · Shared helpers maintain workflow progress state.
- Shared core → sprint-status.yaml: reads/writes · Shared helpers update sprint state when relevant.
- Orchestrator → Analyst: routes to · Discovery work is delegated to the analyst skill.
- Orchestrator → Product manager: routes to · Product definition work is delegated to the product manager skill.
- Orchestrator → Architect: routes to · Architecture and gate checks are delegated to the architect skill.
- Orchestrator → Scrum master: routes to · Sprint planning and burndown work is delegated to scrum master.
- Orchestrator → Developer: routes to · Implementation support tasks are delegated to developer skill.
- Orchestrator → UX designer: routes to · UX and accessibility work is delegated to the UX designer skill.
- Orchestrator → Creative intelligence: routes to · Ideation and research-technique work is delegated to creative intelligence.
- Orchestrator → Builder: routes to · Skill-pack extension and scaffolding work is delegated to builder.
- install-codex.sh → Skills dir: copies to · Shell installer validates tooling and installs the skill pack.
- install-codex.ps1 → Skills dir: copies to · PowerShell installer validates tooling and installs the skill pack.
- Builder → Skills dir: installs into · Builder-oriented workflows place skills into Codex's skills directory.
- Docs site → Site config: configured by · Documentation site behavior and styling are driven by config assets.
- Analyst → Artifacts: produces · Discovery workflows emit briefs and research reports.
- Product manager → Artifacts: produces · Product workflows emit PRDs and technical specs.
- Architect → Artifacts: produces · Architecture workflows emit architecture and gate-check artifacts.
- Scrum master → Artifacts: produces · Planning workflows emit sprint plans, stories, and sprint status.
- Developer → Artifacts: produces · Developer workflows emit review and quality artifacts.
- UX designer → Artifacts: produces · UX workflows emit design and user-flow artifacts.
- Creative intelligence → Artifacts: produces · Creative workflows emit brainstorm and research artifacts.
- Builder → Artifacts: produces · Builder workflows emit skill and workflow templates.
- Artifacts → Docs site: published in · Generated artifacts are documented and surfaced through the docs area.
- Artifacts → project.yaml: references · Artifacts are driven by project-local BMAD configuration.
- Artifacts → workflow-status.yaml: advances · Workflow artifacts are tracked against repository-local progress state.
- Artifacts → sprint-status.yaml: updates · Planning outputs may update sprint tracking state.