BMADX

BMADX is a lightweight BMAD-first guardrail for Codex.

It helps agentic builders choose the smallest safe workflow:

• copy tweaks stay tiny,
• normal product changes stay bounded,
• auth, billing, data, and production work escalates,
• messy repos get a rare Rescue Mode (X4/FUBAR).

Use it when plain Codex feels too ad-hoc, but full BMAD ceremony feels too heavy for everyday work. Copy tweak != architecture ceremony. Auth change != vibe-coded one-shot.

If this matches how you use Codex/BMAD, stars and misroute reports help find early testers.

Current public version: v0.3.1

Main development line: v0.3.2-dev, adding criteria-based planning effort and reproducible Sol reasoning comparisons.

GPT-5.6 Sol, Terra, and Luna passed their first subscription-backed healthy canaries on 2026-07-10. They remain candidate profiles until repeated healthy and degraded BMADX benchmarks pass.

Start here

If this is your first time:

1. Read START_HERE.md
2. Run the install wrapper from 5-Minute Quickstart
3. Paste one of the prompts from What to Paste into Codex

Tiny demo

BMADX is easiest to judge on tasks where a coding agent can either stay useful or quietly become too clever.

Task you give Codex	BMADX should do
Fix this typo in the pricing copy.	keep it tiny (X1)
Add Google login without breaking existing auth.	slow down, identify ownership and proof (X3)
This repo is messy and I need a migration recovery plan.	use Rescue Mode only if the entropy is real (X4/FUBAR)

The point is not to add ceremony. The point is to stop treating copy, auth, and unclear migration recovery as the same kind of work.

Visual map

Known limits today

• BMADX requires BMAD for Codex. If BMAD is not installed, start there first.
• BMADX is Codex-first, not Claude Code-native.
• BMADX adds routing and guardrails; it does not prove code quality by itself.
• BMADX can recommend per-task Codex thinking budget, but it does not edit your global Codex config.
• GPT-5.6 requires Codex CLI 0.144.0 or newer.
• Model experiments such as PMAX X are benchmark probes, not support claims.
• Tests, CI, static analysis, and human review still matter for red-zone work.

BMADX can also emit a broad-orchestrator handoff packet for tasks that are too judgment-heavy, long-context, privacy-sensitive, or multi-system for the narrow Codex lane. This is a schema, not a runtime: it can cooperate with broad orchestration models such as Gastown-style workflows without shipping worker dispatch, model lanes, arbiters, hooks, MCP, plugins, subagents, or persistent state. See Broad Orchestrator Handoff.

Who this is for

BMADX is for:

• founders, makers, designers, and PM-ish users who already use Codex
• non-technical builders who understand the problem better than the technology
• engineers who want more discipline than ad-hoc prompting
• people who want BMAD behind the scenes without running full BMAD ceremony on every bounded task
• teams that occasionally need a rescue/scaffold layer for messy repos

BMADX is probably not for you if:

• you already know you want to work directly in BMAD all the time
• you want a durable orchestration runtime with .omx-style state and runtime tooling
• you only need plain Codex for trivial one-off prompts
• you want Claude Code-native hooks, MCP, plugins, subagents, or settings automation

Codex-first stance

BMADX is intentionally Codex-first. The current product is optimized around Codex Skills, CODEX_HOME, codex exec benchmarkability, and a compact gate that separates classification from execution permission.

Claude Code is not a near-term target. Its Skills, CLAUDE.md, hooks, subagents, MCP, plugins, permissions, and interactive/non-interactive behavior make a simple BMADX port misleading. BMADX may watch Claude Code as an execution surface, but the repo does not currently ship or promise a Claude adapter.

Model experiments are welcome inside Codex. The benchmark runner supports the primary OpenAI/Codex path and can also run experimental local-model checks via Codex OSS providers when a local model is installed.

BMADX can also suggest a fit-for-purpose thinking budget for the current run. The mapping is model-aware: Sol can stay at high for X4, while Terra and Luna keep xhigh for Rescue execution until benchmarks say otherwise. See Thinking Budget Advisor and GPT-5.6 Model Compatibility.

For longer Codex threads, BMADX can also say when /goal or a bounded review/repair/validate loop is useful. This does not add a gear and does not turn BMADX into a runtime orchestrator. See Goal and Loop Discipline.

Model lanes

• Validated baseline: Codex on GPT-5.5.
• Canary-passed candidate lanes: GPT-5.6 Sol, Terra, and Luna; no performance or default-model promotion claim yet.
• Experiment lane: PMAX X, currently focused on cheaper Ollama/OpenRouter/local candidates.
• Current best PMAX X experiment: minimax-m2.7:cloud, but it is not safe as the BMADX router yet.
• Not defaults: Claude adapters, local/Ollama/OpenRouter models, and any model that fails red-zone routing.

Rule: no public model claim without the same BMADX benchmark gates for routing, compactness, red-zone escalation, degraded BMAD behavior, and X4 rarity.

Evidence status

The July 16 blinded decision-value study completed 162 Sol generation calls and 325 synthetic panel judgments, but two of five reviewer families failed the preregistered candidate-order stability gate. The run remained blinded and is inconclusive: it does not support a claim that BMADX is better or worse than plain Sol, and it does not establish outcomes for novice builders.

This failure is published because the benchmark is meant to block attractive claims when the evaluation panel is not reliable enough. See the full result and trade-offs and machine-readable gate.

Help test BMADX

The most useful feedback is not "nice project." It is where BMADX over-escalated, under-escalated, or explained itself badly.

Try one real Codex task and report:

• what BMADX chose,
• what you expected,
• whether the result was too light or too heavy,
• what proof would convince a non-technical owner it is safe.

Feedback templates: Community Feedback

5 minute quickstart

Prerequisite: BMAD must already be installed in your Codex skills. BMADX depends on bmad-method-codex.

BMADX checks that dependency locally and read-only. It does not require BMAD synchronization before normal tasks; release drift is advisory, and only a missing or structurally unusable BMAD installation blocks X3/X4.

git clone https://github.com/pdurlej/BMADX.git
cd BMADX
python3 scripts/install_and_verify_bmadx.py --force

Then open Codex in your project and paste:

Use BMADX for this repo. Pick the lightest safe mode. Keep it lightweight unless BMAD is truly needed.
Use the Architecture Guardrail Card silently unless a risk changes the safe mode.
Suggest the thinking budget only if it matters for this task.

My task:
<describe the change in plain English>

What I care about:
<speed / clarity / safety / cleanup / shipping>

More onboarding:

• 5-Minute Quickstart
• Install for Vibe Coders
• What to Paste into Codex

What happens after install

Most users should not choose X1/X2/X3/X4 manually.

The intended model is:

1. describe the task in plain language
2. let BMADX classify it
3. let BMADX stay compact for normal work
4. escalate to BMAD-heavy work only when the task genuinely needs it

The internal gear model is:

• X1 for tiny local fixes
• X2 for normal bounded changes
• X3 for BMAD-heavy work
• X4 for Rescue Mode (X4/FUBAR) when the repo or rollout needs extra structure

X4 is intentionally rare. It is the ace in the sleeve, not the default.

BMAD vs BMADX vs OMX vs plain Codex

Use this when...	Best fit	Why
you just need a trivial one-off answer	plain Codex	lowest setup and lowest ceremony
you want full process ownership and BMAD artifacts should drive the work	BMAD	BMAD remains the upstream source of truth
you want lighter day-to-day Codex usage with BMAD-compatible guardrails	BMADX	compact routing, verify discipline, rare rescue mode
you want a heavier runtime layer and broader orchestration	OMX	closer to that product category than BMADX

More detail:

• Architecture Guardrail Card
• Why BMAD is required
• Choose BMAD vs BMADX vs OMX
• Ecosystem and strategic stance
• Broad orchestrator handoff
• Model experiments
• FAQ

Recommended companion stack

BMADX works best as part of a small, explicit stack:

• BMAD for process and architecture source of truth
• BMADX for lightest-safe-mode routing in Codex
• Oracle for second-opinion reviews with the right files and stronger models when the builder does not know what to ask
• pyfallow for Python codebase intelligence when available
• Guardrails.md for repo-local safety constraints and repeated failure lessons
• CI, tests, static analysis, and secret scans for hard technical facts

More detail: Ecosystem and strategic stance

In plain language: Oracle helps ask the expert second opinion, BMADX decides the safe work mode, BMAD owns the process, Guardrails.md remembers hard mistakes, pyfallow checks Python code structure, and CI/tests prove the result.

What BMADX proves well today

BMADX has a real public wedge:

• it is much lighter than OMX in the repo’s benchmarked runs
• it keeps BMAD as the source of truth instead of competing with it
• it reduces day-to-day process selection friction inside Codex
• it keeps a rare but useful Rescue Mode for messy repos

What it does not prove:

• that BMADX is categorically better than BMAD
• that token counts alone capture user value
• that every task should use BMADX instead of plain Codex

Benchmark reading:

• Benchmark Overview
• Historical benchmark summary
• Current mixed-metric summary
• GPT-5.5 benchmark summary

Human-readable proof:

• Plain Codex vs BMADX transcript
• BMAD vs BMADX vs OMX transcript

Latest benchmark snapshot:

• BMADX GPT-5.5 healthy (2026-04-24): 6302.0 average tokens
• BMADX GPT-5.5 degraded (2026-04-24): 8918.5 average tokens, with X3/X4 hard-gate semantics preserved
• BMADX GPT-5.4 healthy (2026-04-24 comparison): 12370.75 average tokens
• GPT-5.5 healthy passed core format, token, reference_budget, routing, and overreach validation
• historical OMX baseline remains 25540.5 average tokens

Rescue Mode (X4/FUBAR)

Rescue Mode exists for cases where BMAD alone is not enough as a tactical operating surface inside Codex.

Typical triggers:

• the repo is messy or high-entropy
• scope is diffuse or multi-threaded
• rollout and ownership need to be made explicit
• the team needs a scaffold bundle, not just a short answer

What it generates:

• AGENTS.md
• .customize.yaml snippets
• trigger and verify matrices
• rollout checklist
• subagent policy

More detail:

• Rescue Mode guide
• Sample bundle

Repository map

• START_HERE.md
• docs/index.md
• skill/bmadx
• scripts/install_and_verify_bmadx.py
• scripts/install_bmadx.py
• benchmark/scripts/run_bmadx_benchmark.py
• benchmark/scripts/run_sol_bmadx_ab.py
• Plain Sol vs BMADX A/B
• samples/fubar-bundle

Contributing

Public onboarding comes first. Contributor and internal guidance lives here:

• CONTRIBUTING.md
• CHANGELOG.md
• docs/architecture.md
• _bmad-output/project-context.md