[BUG] Codex integration audit log: root resolution, review coverage, and command drift

Description

This is an audit log for the Codex integration generated by BMad Method v6.12.0. The install is structurally healthy—Codex discovers the skills, the skill validator passes, and the shipped tests pass—but several runtime instructions fail or become inaccurate in normal Codex use.

I also checked the same source areas on current main (6.13.0-next, commit 94b6727b). This report distinguishes defects still present there from v6.12 findings that have already been corrected. I am filing one audit log to preserve the shared integration context; please split it for implementation if that is easier to triage.

Environment and provenance

• BMad: v6.12.0 / commit 05bfbd46
• Install: project-local Core + BMM, Codex target, installShims: false
• Codex CLI: 0.154.0
• OS: Linux under WSL2
• Git: 2.53.0
• Python: 3.14.7
• uv: 0.12.13
• Node: 24.21.0
• All 29 installed skill directories were byte-identical to their v6.12.0 upstream source directories (excluding runtime caches)

The issue form has no Codex CLI choice, so the applicable IDE value is Other.

Summary

Priority	Finding	v6.12.0	Current main
High	Nested Codex working directories produce the wrong {project-root}	Reproduced	Still present
High	Code Review fails before the first commit and omits untracked files	Reproduced	Still present
Medium	Deep Recon invokes its installed helper using a CWD-relative path	Reproduced	Still present
Medium	Personal override files are promised as ignored but fresh setup does not create the ignore rule	Related v6.12 gap	Still present in the new layout
Medium	Routes point to absent or optional Builder skills without a consistent installed-module guard	Reproduced	Partly present
Medium	Codex is described as lacking subagents / agent teams	Reproduced	Still present
Medium	“Headless JSON schemas” are prompt examples, not CLI-enforced output schemas	Reproduced	Still present
Low	Customization exposes settings that their workflows never consume	Reproduced	Still present
Low	bmad-help / bmad naming is inconsistent	N/A	Present on main

1. Nested working directory breaks {project-root} commands

Codex loads repository skills by scanning .agents/skills from the current directory up to the repository root. BMad's skill convention instead defines {project-root} as the current project working directory and builds absolute helper paths from it.

Representative source:

• v6.12.0 PRD skill
• current PRD skill
• current root convention
• Codex local-skill discovery behavior

Steps to reproduce

mkdir -p <project>/some/nested/directory
cd <project>/some/nested/directory
codex
# Invoke $bmad-prd (or another BMad skill that calls an _bmad helper).

Codex still discovers <project>/.agents/skills/bmad-prd, but BMad constructs paths such as:

<project>/some/nested/directory/_bmad/scripts/resolve_customization.py

That file does not exist. The actual helper remains under <project>/_bmad/scripts/.

Expected: repository-local BMad skills resolve one stable repository/workspace root regardless of which descendant directory launched Codex.

This is related to root-resolution work in #2796 / #2802 and path hardening in #2624, but those do not cover the nested-CWD case.

2. Code Review misses fresh and untracked work

The “Uncommitted changes” route runs only git diff HEAD:

• v6.12.0 source
• current source

Steps to reproduce

mkdir review-repro && cd review-repro
git init
printf 'print("hello")\n' > app.py
git diff HEAD

Actual result:

fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree

The command exits 128 and yields no review input. After the repository has a commit, git diff HEAD still excludes untracked files. In the audited fresh install, that meant the review route could see none of 234 untracked generated files.

Expected: “Uncommitted changes” handles an unborn HEAD and includes staged, unstaged, and untracked files.

I found no existing issue for this behavior.

3. Deep Recon runs an installed script relative to the caller's CWD

Deep Recon emits eight commands in the form:

uv run scripts/recon_kit.py ...

Examples: draft reference and skill workflow.

From a repository working directory this resolves to <project>/scripts/recon_kit.py, while the installed script is under the skill directory. The command fails unless the caller happens to change into that skill first.

Expected: commands address the helper through the skill's resolved installation directory (or an installed wrapper), not an assumed CWD.

I found no existing issue for this exact path defect; #2724 covers different recon_kit data/citation behavior.

4. Fresh setup does not ignore promised personal overrides

On current main, Customize says _bmad/custom/*.user.toml is gitignored and safe for personal overrides: documented behavior. Fresh setup creates _bmad/custom/ but does not create its .gitignore: setup path.

After fresh setup, git check-ignore _bmad/custom/example.user.toml reports no match. This is a privacy and team-portability footgun because the filename is explicitly presented as the personal layer.

Expected: setup creates the promised ignore rule, or the docs stop promising that these files are ignored.

The v6.12 installer created _bmad/custom/.gitignore, but its separate root _bmad/config.user.toml was not covered and user values were mirrored into generated YAML. #2456 and #2533 reported the older root-config behavior and were closed during backlog cleanup rather than as fixed; the current reproduction above is for the replacement layout.

5. Routes can target unavailable or nonexistent Builder skills

With Core + BMM installed and shims disabled:

• v6.12 Code Review recommended dev-story, which was not installed. This is fixed on main, which now recommends bmad-build: current route.
• PRD and UX still suggest optional bmad-workflow-builder without consistently checking whether BMad Builder is installed. Architecture already demonstrates an installed-module guard.
• Customize recommends bmad-builder, but the external Builder module exposes bmad-workflow-builder and bmad-agent-builder, not a bmad-builder skill: current references.

Expected: every route names a real installed skill, or clearly gates the route and explains how to install the optional module. Open #2841 appears related to Builder documentation; this report adds the generated-skill routing behavior.

6. Current Codex capability guidance is stale

Current BMad source explicitly lists Codex among runtimes without subagents (Build) and describes agent teams as Claude-only (Party Mode). Current Codex supports subagent orchestration and reusable role configuration: official Codex subagent documentation.

The stale checks unnecessarily force sequential/fallback behavior in Codex.

Expected: prefer capability detection or current Codex behavior over a hard-coded product-name exclusion. Closed #2451 covered older authorization ambiguity, not the current false capability statement.

7. Headless contracts are not Codex output schemas

The PRD integration calls Markdown examples “JSON Schemas,” but they are instruction text rather than JSON Schema documents: current headless contracts.

Codex --json emits lifecycle events as JSONL; --output-schema is the CLI mechanism for enforcing a stable final response shape: official non-interactive-mode documentation.

This does not mean prompt-directed JSON cannot work. It means the advertised contract is best-effort unless a caller supplies a real schema and invocation contract.

Expected: either ship actual JSON Schema files plus a documented codex exec --output-schema integration, or describe the current examples as prompt-level output shapes.

8. Inert customization settings

• Project Context exposes workflow.on_complete, but its workflow never reads or runs it: customization.
• Spec exposes spec_filename = "SPEC.md", while the workflow fixes the name as SPEC.md throughout: customization.

Expected: honor these settings or remove them so users do not configure behavior that cannot occur.

9. bmad / bmad-help naming drift on current main

The source skill is now named bmad: current frontmatter. Current docs and several skills still tell users to invoke bmad-help: documentation example.

Expected: one canonical skill name across source, generated guidance, and docs.

v6.12 findings already corrected or already tracked

These were confirmed in the released install but should not be opened again as current-main bugs:

• Sixteen installed skills bypassed the four-layer TOML resolver and read generated YAML directly. This was corrected after v6.12 by 30cec3a7 and 8f09e6a6.
• The obsolete Code Review dev-story route is corrected on main.
• Forced minimum review findings / inability to return zero clean findings is already tracked in open #2772; #2805 proposed a fix but was closed unmerged.
• Bytecode included in the v6.12 package/manifest is already known as #2694.
• Review-layer duplication is already tracked in #2760.

Validation performed

This does not appear to be a corrupt or partial installation:

• 29/29 skills were discovered from both repository-root and nested working directories.
• 29/29 SKILL.md files passed the OpenAI skill validator.
• 300/300 shipped Python tests passed.
• Python compilation, resource-link validation, and both bmad-build render paths passed.
• A temporary four-layer config override proved that the resolver returned the override while v6.12 direct-YAML readers could not observe it.
• The Git, Deep Recon, ignore-rule, and helper-path cases above were reproduced directly.

Expected integration invariant

A project-local BMad install for Codex should work from any descendant working directory; every generated command should resolve to an installed file or gated optional capability; configuration should have one authoritative resolution path; reviews should see all selected work; and Codex-specific guidance should match current supported invocation and orchestration behavior.

I am happy to provide smaller reproductions or split confirmed fixes into focused PRs/issues according to maintainer preference.