bx-dev-skill

KO | EN

gitlite — search

#hacktoberfest #golang #go #android #machine-learning #rust #deep-learning #java #cli #kubernetes #awesome-list #vue #mcp #open-source

(★ 24)

Self-contained Codex skill for ad-hoc development sessions on session branches.

bx-dev-skill Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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:

```text
$bx-dev auth-cleanup
```

Then give tasks in the same Codex chat:

```text
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 <url>` — record a running browser URL for QA when using
  `--careful`. It does not start the server.

Supported flags:

- `$bx-dev <topic> --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 <url>`.
- `$bx-dev <topic> --solo` — run without subagents; useful for small changes.
  Solo mode still uses the session branch and creates its commit on `push`.
- `$bx-dev <topic> --no-review` — skip review in team mode.
- `$bx-dev <topic> --plan-approve` — ask for your approval after the scout plan
  before implementation starts.
- `$bx-dev <topic> --no-sop` — use a regular PR merge instead of the default
  squash merge on `push`.
- `$bx-dev <topic> --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/<session-id>/` 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

```text
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:

```text
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
cd "$BX_DEV_BUNDLE"
git pull
```

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

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

bx-dev-skill

bx-dev-skill Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

bx-dev-skill

bx-dev-skill Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README