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.
3. Stores session state under .bx-dev// in the target repo.
4. For each task, asks implementation/review subagents to work on the branch unless --solo is used.
5. Creates conventional commits for completed work. In team mode this happens per completed task; in --solo mode dirty work is committed when you push.
6. On push, runs available checks, pushes the session branch, opens a PR to dev, and merges according to the skill workflow if the gates pass.
7. On exit, tries to finish any pending work, push it through the same gates, switch to dev, and clean up session state. If a gate fails, the session is preserved so you can fix the issue and try again.

The session writes normal git commits and .bx-dev/ session state in the repository where you run it.

When Not To Use It

Use regular Codex editing instead when the change is tiny, purely local, or does not need a branch/review workflow. Do not use bx-dev in a repository that does not have git, origin, and main available unless you are prepared to set those up first.

Contents

skills/bx-dev/                         Installable Codex skill folder
skills/bx-dev/SKILL.md                 Main skill entrypoint
skills/bx-dev/docs/                    Internal docs used by the skill
skills/bx-dev/templates/               Internal subagent prompt templates
skills/bx-dev/skill-library/           Internal reusable support skills

Requirements

• Codex runtime with subagent tools available for team mode. --solo can be used without subagents.
• git
• jq
• A git repository with origin and main
• A clean worktree when starting a session. If the target repo already has uncommitted changes, the skill stops instead of guessing what belongs to the session.
• A dev integration branch. If origin/dev is missing, the skill attempts to create it from main.
• An authenticated GitHub CLI gh for push, PR creation, and PR merge flows. You can install and start local work without gh, but push needs it, and exit needs it when there are unpushed commits.

Optional QA and browser automation paths, such as --careful, may require additional local tooling in the target repository. For web UI QA, you start the dev server yourself; bx-dev only stores the URL for the QA phase.

No external issue tracker, external memory service, messaging bridge, or non-bundled agent template pack is required.

Install

Install bx-dev as one Codex skill. The install target is the whole skills/bx-dev/ folder, not just SKILL.md and not the repository root.

The folder is intentionally self-contained:

bx-dev/
  SKILL.md
  docs/
  templates/
  skill-library/

Those internal folders are part of the skill. SKILL.md reads them through relative paths such as docs/..., templates/..., and skill-library/.... You install this as one skill folder; you do not install the bundled support skills separately.

1. Clone the repository

Pick a stable location for the checkout. These examples use $CODEX_HOME, which defaults to ~/.codex:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
git clone https://github.com/bish-x/bx-dev-skill.git "$CODEX_HOME/bx-dev-skill"
export BX_DEV_BUNDLE="$CODEX_HOME/bx-dev-skill"

If you cloned the repository somewhere else, set BX_DEV_BUNDLE to that path:

export BX_DEV_BUNDLE="/path/to/bx-dev-skill"

2. Install the skill folder

Create the Codex skills directory and link the whole installable skill folder:

mkdir -p "$CODEX_HOME/skills"
ln -sfn "$BX_DEV_BUNDLE/skills/bx-dev" "$CODEX_HOME/skills/bx-dev"

This single link is the install. The docs/, templates/, and skill-library/ folders stay inside $CODEX_HOME/skills/bx-dev/.

If you do not want symlinks, copy the whole folder instead:

mkdir -p "$CODEX_HOME/skills"
cp -R "$BX_DEV_BUNDLE/skills/bx-dev" "$CODEX_HOME/skills/"

3. Verify the install

Run these checks before starting Codex:

test -f "$CODEX_HOME/skills/bx-dev/SKILL.md"
test -f "$CODEX_HOME/skills/bx-dev/docs/CODEX-ORCHESTRATION.md"
test -f "$CODEX_HOME/skills/bx-dev/docs/MERGE-PROTOCOL.md"
test -f "$CODEX_HOME/skills/bx-dev/templates/agents/bx-dev-merger.md"
test -f "$CODEX_HOME/skills/bx-dev/skill-library/INDEX.md"
test -f "$CODEX_HOME/skills/bx-dev/skill-library/architecture/ddd/SKILL.md"

If every command exits successfully, restart Codex. The skill should then be available as $bx-dev.

Run $bx-dev from the repository you want it to work on, not from the bx-dev-skill checkout.

Updating

If you installed with symlinks, update the checkout and restart Codex:

cd "$BX_DEV_BUNDLE"
git pull

If you copied the folder instead of symlinking it, copy the folder contents again after git pull:

rsync -a "$BX_DEV_BUNDLE/skills/bx-dev/" "$CODEX_HOME/skills/bx-dev/"

What not to do

Do not copy only SKILL.md. Do not split docs/, templates/, or skill-library/ into top-level $CODEX_HOME folders. They are internal resources of the bx-dev skill and must stay inside the installed bx-dev/ folder.

Support skills under bx-dev/skill-library/ are bundled references. They are included so bx-dev can point agents at reusable workflows without relying on private local files. They are internal to this public bx-dev bundle unless you intentionally reuse them elsewhere.

Most bx-dev role prompts are inline in skills/bx-dev/SKILL.md. The only extra subagent prompt template is skills/bx-dev/templates/agents/bx-dev-merger.md.

Skill Library

The repository includes 105 unique support skills grouped by purpose:

• skills/bx-dev/skill-library/architecture/ — 1 skill
• skills/bx-dev/skill-library/backend/ — 12 skills
• skills/bx-dev/skill-library/documents/ — 1 skill
• skills/bx-dev/skill-library/engineering/ — 6 skills
• skills/bx-dev/skill-library/frontend/ — 13 skills
• skills/bx-dev/skill-library/general/ — 16 skills
• skills/bx-dev/skill-library/marketing/ — 37 skills
• skills/bx-dev/skill-library/review-qa/ — 12 skills
• skills/bx-dev/skill-library/system/ — 7 skills

skills/bx-dev/skill-library/references/ contains shared public reference docs used by copied skills. It is not a skill category.

See skills/bx-dev/skill-library/INDEX.md for the category router, each category INDEX.md for per-skill descriptions, and skills/bx-dev/skill-library/MANIFEST.md for the flat inventory.