bx-dev Skill for Codex

bx-dev is a self-contained Codex skill for ad-hoc development sessions on a session branch. It coordinates single-shot Codex subagents for implementation, review, optional QA, git commits, PR creation, merge, and cleanup.

What This Is

bx-dev is a workflow skill for working on a normal git repository with Codex. It starts a temporary development session, keeps the work isolated on a session branch, delegates implementation and review to Codex subagents, and helps you push the result back into dev through a PR.

Use it when you want a structured coding session instead of one direct Codex edit. The skill is especially useful for feature work, bug fixes, refactors, or multi-step changes where you want implementation, review, commits, and optional QA handled in one workflow.

This repository is not an app template and does not modify your project by itself. Installing it only adds the $bx-dev skill to Codex.

How You Use It

After installing and restarting Codex, open Codex in the repository you want to work on and start a session with a message like:

$bx-dev auth-cleanup

Then give tasks in the same Codex chat:

fix password reset validation
add tests for the reset token edge cases
push
exit

Common session commands:

• push — run detected checks, push the session branch, create a PR to dev, and merge it when the push and merge gates pass.
• exit — finish the session: commit leftover work when appropriate, push and merge unpushed commits, switch back to dev, clean session state, and delete the session branch when it is safe. If tests, PR creation, or merge gates fail, exit aborts and leaves the session intact.
• set dev-server — record a running browser URL for QA when using --careful. It does not start the server.

Supported flags:

• $bx-dev --careful — add a QA phase after implementation and review. For web UI work, start your dev server yourself and provide its URL when the skill asks, or later with set dev-server .
• $bx-dev --solo — run without subagents; useful for small changes. Solo mode still uses the session branch and creates its commit on push.
• $bx-dev --no-review — skip review in team mode.
• $bx-dev --plan-approve — ask for your approval after the scout plan before implementation starts.
• $bx-dev --no-sop — use a regular PR merge instead of the default squash merge on push.
• $bx-dev --sop — accepted for backward compatibility only; squash is already the default.

$bx-dev messages are Codex prompts, not terminal commands. Run terminal commands only where the README explicitly shows shell snippets.

What Happens In A Session

At a high level, bx-dev:

1. Checks that the current repo is clean enough to start.
2. Ensures origin/dev exists, then creates a session branch from it.