# xmm/codex-bmad-skills architecture

> Architecture diagram of the GitHub repository xmm/codex-bmad-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xmm/codex-bmad-skills
- Repository: https://github.com/xmm/codex-bmad-skills

## Overview

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: [`skills/bmad-orchestrator`](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-orchestrator) (Orchestrator), [`skills/bmad-shared`](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-shared) (Shared core), [`skills/bmad-builder`](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-builder) (Builder), [`skills/bmad-analyst`](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-analyst) (Analyst)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_codex["Codex runtime"]
  node_codex(("Codex<br/>runtime"))
  node_bmad_intents["bmad:* intents<br/>command surface"]
  node_skills_dir[("Skills dir<br/>install target")]
end

subgraph group_group_skills["Skill pack"]
  node_orchestrator["Orchestrator<br/>coordination skill"]
  node_analyst["Analyst<br/>discovery skill"]
  node_pm["Product manager<br/>product skill"]
  node_architect["Architect"]
  node_scrum["Scrum master<br/>planning skill"]
  node_developer["Developer<br/>delivery skill"]
  node_ux["UX designer<br/>design skill"]
  node_creative["Creative intelligence<br/>ideation skill"]
  node_builder["Builder<br/>meta skill"]
end

subgraph group_group_shared["Shared workflow core"]
  node_shared["Shared core<br/>shared utilities"]
end

subgraph group_group_install["Installers"]
  node_install_sh["install-codex.sh<br/>installer<br/>[install-codex.sh]"]
  node_install_ps1["install-codex.ps1<br/>installer<br/>[install-codex.ps1]"]
end

subgraph group_group_docs["Documentation"]
  node_outputs["Artifacts"]
  node_docs_site["Docs site<br/>documentation site"]
  node_docs_config["Site config<br/>[_config.yml]"]
end

subgraph group_group_project["Project state"]
  node_proj_yaml["project.yaml<br/>project config"]
  node_workflow_yaml["workflow-status.yaml<br/>workflow state"]
  node_sprint_yaml["sprint-status.yaml<br/>sprint state"]
end

node_codex -->|"receives"| node_bmad_intents
node_bmad_intents -->|"dispatches to"| node_orchestrator
node_orchestrator -->|"uses"| node_shared
node_shared -->|"reads/writes"| node_proj_yaml
node_shared -->|"reads/writes"| node_workflow_yaml
node_shared -->|"reads/writes"| node_sprint_yaml
node_orchestrator -->|"routes to"| node_analyst
node_orchestrator -->|"routes to"| node_pm
node_orchestrator -->|"routes to"| node_architect
node_orchestrator -->|"routes to"| node_scrum
node_orchestrator -->|"routes to"| node_developer
node_orchestrator -->|"routes to"| node_ux
node_orchestrator -->|"routes to"| node_creative
node_orchestrator -->|"routes to"| node_builder
node_install_sh -->|"copies to"| node_skills_dir
node_install_ps1 -->|"copies to"| node_skills_dir
node_builder -->|"installs into"| node_skills_dir
node_docs_site -->|"configured by"| node_docs_config
node_analyst -->|"produces"| node_outputs
node_pm -->|"produces"| node_outputs
node_architect -->|"produces"| node_outputs
node_scrum -->|"produces"| node_outputs
node_developer -->|"produces"| node_outputs
node_ux -->|"produces"| node_outputs
node_creative -->|"produces"| node_outputs
node_builder -->|"produces"| node_outputs
node_outputs -->|"published in"| node_docs_site
node_outputs -.->|"references"| node_proj_yaml
node_outputs -.->|"advances"| node_workflow_yaml
node_outputs -.->|"updates"| node_sprint_yaml

click node_orchestrator "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-orchestrator"
click node_shared "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-shared"
click node_analyst "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-analyst"
click node_pm "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-product-manager"
click node_architect "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-architect"
click node_scrum "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-scrum-master"
click node_developer "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-developer"
click node_ux "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-ux-designer"
click node_creative "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-creative-intelligence"
click node_builder "https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-builder"
click node_docs_site "https://github.com/xmm/codex-bmad-skills/tree/main/docs"
click node_docs_config "https://github.com/xmm/codex-bmad-skills/blob/main/docs/_config.yml"
click node_install_sh "https://github.com/xmm/codex-bmad-skills/blob/main/installers/install-codex.sh"
click node_install_ps1 "https://github.com/xmm/codex-bmad-skills/blob/main/installers/install-codex.ps1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_codex,node_bmad_intents,node_skills_dir toneBlue
class node_orchestrator,node_analyst,node_pm,node_architect,node_scrum,node_developer,node_ux,node_creative,node_builder toneAmber
class node_shared toneMint
class node_install_sh,node_install_ps1 toneRose
class node_outputs,node_docs_site,node_docs_config toneIndigo
class node_proj_yaml,node_workflow_yaml,node_sprint_yaml toneTeal
```

## Components

### Codex runtime

Execution environment that receives BMAD intents and runs installed skills.

- **Codex**: runtime · Host environment that receives BMAD intents and runs installed skills.
- **bmad:* intents**: command surface · Intent namespace used to trigger BMAD workflow actions.
- **Skills dir**: install target · Destination directory where Codex discovers installed skills.

### Skill pack

Reusable BMAD role and workflow skills.

- [Orchestrator](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-orchestrator): coordination skill · Central workflow coordinator for setup, phase tracking, next-step guidance, and config validation. · `skills/bmad-orchestrator`
- [Analyst](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-analyst): discovery skill · Research and briefing skill for discovery work. · `skills/bmad-analyst`
- [Product manager](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-product-manager): product skill · PRD, prioritization, and product specification skill. · `skills/bmad-product-manager`
- [Architect](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-architect): architecture skill · Architecture design and gate-check skill. · `skills/bmad-architect`
- [Scrum master](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-scrum-master): planning skill · Sprint planning, story sizing, and burndown skill. · `skills/bmad-scrum-master`
- [Developer](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-developer): delivery skill · Linting, coverage, and code-review support skill. · `skills/bmad-developer`
- [UX designer](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-ux-designer): design skill · Accessibility, responsive design, and user-flow skill. · `skills/bmad-ux-designer`
- [Creative intelligence](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-creative-intelligence): ideation skill · Brainstorming and research-technique skill. · `skills/bmad-creative-intelligence`
- [Builder](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-builder): meta skill · 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](https://github.com/xmm/codex-bmad-skills/tree/main/skills/bmad-shared): shared utilities · 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](https://github.com/xmm/codex-bmad-skills/blob/main/installers/install-codex.sh): installer · Shell installer that validates tooling and copies skills into a destination. · `installers/install-codex.sh`
- [install-codex.ps1](https://github.com/xmm/codex-bmad-skills/blob/main/installers/install-codex.ps1): installer · PowerShell installer for placing the skill pack into a Codex skills directory. · `installers/install-codex.ps1`

### Documentation

Published guidance, examples, and site assets.

- **Artifacts**: generated artifacts · Workflow outputs such as briefs, PRDs, architectures, stories, and reviews.
- [Docs site](https://github.com/xmm/codex-bmad-skills/tree/main/docs): documentation site · Published onboarding, workflow, examples, and troubleshooting documentation. · `docs`
- [Site config](https://github.com/xmm/codex-bmad-skills/blob/main/docs/_config.yml): 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 config · Project-local workflow configuration and setup state.
- **workflow-status.yaml**: workflow state · Project-local workflow phase and progress state.
- **sprint-status.yaml**: sprint state · Sprint tracking state written by planning workflows.

## Connections

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