| name | bx-dev |
| description | Use only when the user invokes $bx-dev or explicitly asks to start/resume an ad-hoc bx-dev development session. Orchestrates Codex subagents for implementation/review on a session branch without an external issue tracker. Do not use for ordinary direct edits. |
bx-dev - Ad-hoc Development Session (public edition)
Codex Runtime Contract
This workflow was originally written for long-running Agent Teams. In bx-codex,
public instructions use natural-language Codex subagent spawns. Most bx-dev
teammates are single-shot: Lead spawns a role with a full brief, waits for one
final response, consumes the report, then calls close_agent for that agent id.
If a subagent is still live/running before its final response, Lead may use
send_input for a correction. If the subagent is completed, closed, missing, or
stale, Lead must spawn a fresh role with the full relevant context. The
authoritative runtime contract is
docs/CODEX-ORCHESTRATION.md.
When this skill is invoked, treat it as explicit user consent to use Codex
subagents unless --solo is set. The legacy primitives TeamCreate,
Task(team_name=...), SendMessage, WaitNextSendMessage, TaskList,
TaskUpdate, TeamDelete, and shutdown_request do NOT exist in Codex —
ignore any inline references to them as historical wording.
Runtime mapping:
| Legacy term in this file | Codex action |
|---|
Task(... team_name=..., prompt=...) / TeamCreate | Spawn a fresh subagent via natural language: "Spawn the subagent with the following input: ...". |
SendMessage(recipient=teammate, content=...) | If that exact Codex agent is still live/running, use send_input with <content>. If it has completed, is closed, or no live id exists, spawn a fresh subagent of that role with updated full context including <content>. |
Wait for SendMessage / WaitNextSendMessage | wait_agent against the spawned worker id recorded in codex_agents. |
TaskList / TaskUpdate | Use the /plan slash command (or skip — Codex tracks state itself). |
shutdown / shutdown_request / TeamDelete | close_agent(target=<agent_id>), then clear state.teammates.{role} and mark state.codex_agents.{role}.status = "closed". |
Keep teammates as logical role labels if existing state uses it, but store
real Codex ids under codex_agents.{role}.agent_id.
You are Lead. Orchestrator. In team mode, you do NOT implement code,
perform semantic code review, or conduct acceptance QA. You MAY run
deterministic orchestration commands and gates: git status, git diff --stat,
branch/PR probes, configured test commands, lint/build commands, and smoke
commands needed to route the workflow. You coordinate teammates.
Exception: --solo flag — Lead works directly, no subagents. See "Solo Mode" section.
Global AGENTS.md rules (executor, delegation matrix) are DISABLED during bx-dev.
State Files
.bx-dev/<session-id>/state.json — session state (one active session at a time)
.bx-dev/<session-id>/brief.md — latest Scout brief (overwritten per task)
.bx-dev/<session-id>/context.md — session progress log (Lead appends after each major event)
State JSON shape:
{
"active": true,
"branch": "dev/auth-fixes",
"topic": "auth fixes",
"team_name": "bx-dev-super-test",
"mode": "team",
"teammates": {
"dev": "dev-1",
"bug_reviewer": null,
"security_reviewer": null,
"compliance_reviewer": null,
"qa": null,
"merger": null
},
"codex_agents": {
"dev": {
"agent_id": "agent_...",
"role": "dev",
"status": "running"
}
},
"waiting_for": "",
"lead_session_id": "",
"task_count": 0,
"push_count": 0,
"flags": {
"solo": false,
"careful": false,
"no_review": false,
"plan_approve": false,
"squash_on_push": true
},
"dev_server_url": "",
"completed_tasks": []
}
STATE FILE RULE: NEVER use apply_patch for .bx-dev/<session-id>/ state files. Use shell commands instead:
- state.json: all updates via
jq:
jq '.field = "value"' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
For initial creation: echo '{"active":true, ...}' > .bx-dev/<session-id>/state.json
- brief.md: overwrite via heredoc:
cat > .bx-dev/<session-id>/brief.md <<'BRIEF'
...scout report...
BRIEF
Delegation rule (team mode)
Lead works ONLY through Codex subagents for implementation, semantic review,
and QA (when not --solo). Each role —
Dev, Bug Reviewer, Security Reviewer, Compliance Reviewer, QA, Merger — is
spawned as a fresh single-shot subagent via natural language: "Spawn the
subagent with the following input: ...". Dev, Bug Reviewer, Security
Reviewer, Compliance Reviewer, and QA prompts are inline in this file. Merger
uses the bundled templates/agents/bx-dev-merger.md template. Most follow-up
work happens by spawning a fresh role with the new full context. The only
exception is a live/running agent that has not produced a final response yet;
Lead may send that agent a correction via send_input.
Lead does NOT do: write code, semantic review, code-quality assessment, or
acceptance QA. Lead may run deterministic gates and git/runtime probes to route
the workflow, but teammate judgement remains with subagents.
Exception: --solo mode — Lead does everything directly.
Rules
-
Single-shot subagents only (when not --solo). Every teammate is a fresh spawn via natural language ("Spawn the subagent with the following input: ..."). There is no team registration, no team_name, no long-running session.
-
Lead does not implement or judge teammate work. Lead may do file reads,
subagent orchestration (natural-language spawn), git status/log/add/commit/push,
deterministic test/lint/build/smoke gates, branch/PR probes, and shell
commands for .bx-dev/<session-id>/ state files. Lead never uses
apply_patch on state files.
-
Dev does not commit/push — Lead does. Dev implements and returns the diff summary in its final response. Lead commits, pushes, and manages the session branch.
-
Track and close teammates in state. Always keep teammates object in state.json up to date. Update on every spawn. Immediately after consuming a subagent final response, call close_agent(target=<agent_id>), then clear that role and mark codex_agents.<role>.status = "closed".
-
Wait for real subagent completion. Spawn first, persist the returned agent id in codex_agents, then wait via wait_agent. Do not treat the spawn itself as the worker result.
-
No persistent Dev across tasks. Each task spawns a fresh Dev subagent with full briefing — single-shot model has no implicit context carryover. Lead must re-state the relevant prior context in each new spawn input.
-
Reviewers are fresh per task. Spawn, review, results returned in the spawn response.
-
waiting_for is still updated for recovery, but each wait is an explicit wait_agent on the spawned worker id.
jq '.waiting_for = "<role>"' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Where <role> is "dev", "reviewers", "qa", "merger" (waiting on Merger subagent during Push Step 5 or Step 6 — team mode only), "exit-finalize" (waiting on Dev's finalize file/report pass in Exit Step 2), or "exit-kill" (waiting on Dev's background-kill report in Exit Step 4). Clear it with "" when the spawn result arrives.
-
Close every subagent after final response. This applies to Dev, QA,
reviewers, Merger, and any exit/finalize helper. The sequence is always:
consume final response → persist report/state → close_agent(target=<agent_id>)
→ set codex_agents.<role>.status = "closed" → clear teammates.<role>.
-
Spawn lifecycle transaction. Every spawn step for Dev, reviewers, QA,
Merger, and helper roles MUST follow this transaction before any wait:
natural-language spawn → capture returned agent_id → persist
codex_agents.<role> = {agent_id, role, status:"running"} and
teammates.<role> = "<logical-name>" → set waiting_for → call
wait_agent. After consuming the final report, close the agent and mark it
closed before routing to the next step.
Liveness Doctrine (simplified)
Two invariants, NON-NEGOTIABLE.
Invariant 1 — Waiting protocol
Before waiting for any subagent result, set state.waiting_for to the role name. Then call wait_agent with the current codex_agents.<role>.agent_id. Clear waiting_for to "" when the final worker report is received. One atomic jq per set; batch co-updates into the same jq when they belong to the same logical step. The user can always interrupt.
KEY: "Idle · subagent running" in the HUD means the MAIN THREAD is idle in wait_agent, but the subagent is ACTIVELY WORKING. This is the NORMAL state during a subagent's task. Do NOT report this to user as "subagent went idle / dropped" — that misrepresents reality.
Invariant 1a — Interrupted waits and late notifications
If the user interrupts while Lead is in wait_agent, or if wait_agent is aborted and a subagent_notification lands afterward, Lead MUST treat the notification path as first-class completion:
- Do NOT immediately re-spawn the role.
- Inspect the recent thread events/messages for the waited role's final report.
- If a final report exists, consume it as the authoritative completion event:
- persist any payload into
.bx-dev/<session-id>/brief.md / context.md as appropriate
- call
close_agent(target=<agent_id>)
- set
.waiting_for = ""
- set
.teammates.<role> = null
- set
.codex_agents.<role>.status = "closed"
- Resume the next workflow step from that final report.
- Only if no final report exists should Lead resume
wait_agent or enter Recovery.
Never tell the user "still waiting on Dev" after a final subagent_notification has already arrived.
Invariant 2 — Close is explicit
Single-shot subagents return one final response, but their Codex panels may
remain open until Lead closes them. There is no shutdown_request, no
handshake, no TeamDelete. After consuming the spawn result, Lead calls
close_agent(target=<agent_id>), then clears state.teammates.{role} and marks
state.codex_agents.{role}.status = "closed".
Doctrine precedence
If any per-step procedure elsewhere in this skill describes a shutdown that waits for approval or any indefinite block — this doctrine OVERRIDES that procedure.
Flags
Parse from $ARGUMENTS:
| Flag | Effect |
|---|
--solo | No team, no agents. Lead works directly. Old bx:dev behavior. |
--careful | Adds QA phase after review passes. |
--no-review | Skip reviewers entirely for the whole session. |
--plan-approve | Dev waits for user OK before coding (default: show plan, proceed immediately). |
--sop | DEPRECATED no-op. Squash-on-push is now the default; this flag is accepted for backward compatibility and silently ignored. Use --no-sop to opt out. |
--no-sop | Disable default squash. Push uses --merge (preserves all per-task commits in dev log) instead of --squash. |
Public Spawn Syntax
Use natural-language spawn requests in public instructions:
Spawn a worker subagent named `<role-name>` with the following input:
<substituted role prompt + task brief + write/read ownership>
If an implementation exposes an internal primitive named spawn_agent(...),
treat examples of that shape as pseudocode for the runtime, not callable public
syntax. Regardless of the surface, record the returned agent_id in
state.codex_agents.<role> = {agent_id, role, status:"running"} before waiting,
and keep state.teammates.<role> as the human-readable logical role label.
Role priority
| Role | Priority | When spawned |
|---|
| Dev | High-capability coding worker | Fresh per task or fix cycle |
| Bug Reviewer | Fast correctness reviewer | Every non-trivial task |
| Security Reviewer | High-capability security reviewer | When diff touches auth/input/db/secrets patterns |
| Compliance Reviewer | Fast rules reviewer | When project has AGENTS.md (or legacy CLAUDE.md) with substantive rules |
| QA | High-capability acceptance tester | Only with --careful flag |
Commit Convention
All commits follow Conventional Commits with scope dev:
<type>(dev): <description>
Types
| Type | When | Example |
|---|
feat | New feature (default) | feat(dev): add user authentication flow |
fix | Bug fix | fix(dev): restore validation for empty input |
test | Test-only changes | test(dev): add pytest coverage for auth module |
docs | Documentation only | docs(dev): add API usage examples |
refactor | Restructuring without behavior change | refactor(dev): extract style logic into lookup table |
chore | Tooling, config, non-functional | chore(dev): update pyproject.toml dependencies |
Rules
- Scope is always
dev — no Story IDs in this mode.
- Description language must match existing commits. Run
git log --oneline -10 and detect the language. Use the same.
- Description is lowercase, imperative mood, no period at end.
- BREAKING CHANGE: add
! before : — feat(dev)!: redesign auth API.
- Team mode: one commit per task after review passes. If many unrelated changes, still ONE commit — this is ad-hoc mode.
- Solo mode: changes accumulate without commits during the Working Phase, then Push Step 1 creates one conventional commit for all relevant dirty session changes before pushing.
Session Lifecycle
/bx:dev [topic] [flags] <-- enter session, create branch, spawn team
user: do X <-- Scout + implement + review + commit
user: now do Y <-- Scout + implement + review + commit
user: push <-- tests, push, PR -> dev, merge
user: do Z <-- more work
user: push <-- another push cycle
user: exit <-- end session, cleanup
Phase 0: Enter Session
{project} = basename $(pwd). Used for session names throughout the session.
{lead_name} = "lead" (the orchestrator label). Use this as {lead_name} in all spawn prompts so subagents know who they are reporting to.
Step 1: Check for conflicts
git status --porcelain
If dirty -> tell user, STOP. Don't auto-commit someone else's work.
Check for active /bx:dev session (recovery):
active_state="$(
find .bx-dev -mindepth 2 -maxdepth 2 -name state.json -print 2>/dev/null |
while IFS= read -r state_file; do
if jq -e '.active == true' "$state_file" >/dev/null 2>&1; then
printf '%s\n' "$state_file"
break
fi
done
)"
if [ -n "$active_state" ]; then
SESSION_ID="$(basename "$(dirname "$active_state")")"
echo "EXISTING_SESSION ${SESSION_ID}"
fi
If found -> go to Recovery section.
Step 2: Ensure dev branch exists
git fetch origin
if ! git show-ref --verify --quiet refs/remotes/origin/dev; then
git checkout -b dev main && git push -u origin dev
fi
Step 3: Create session branch
- If user passed a topic (
/bx:dev auth fixes): slug = kebab-case of topic, max 30 chars.
- If no topic:
slug = adhoc-{YYYYMMDD-HHmm}
Naming convention: dev/${slug} by default. If a leaf ref dev exists locally (refs collision), fallback to adhoc/${slug}. Both prefixes are still branched from origin/dev — only the name differs. Never invent a new prefix on the fly; use exactly these two.
session_branch="dev/${slug}"
if git show-ref --verify --quiet refs/heads/dev; then
session_branch="adhoc/${slug}"
echo "⚠ Refs collision: leaf branch 'dev' exists locally → using fallback prefix 'adhoc/' for session branch."
fi
git checkout -b "$session_branch" origin/dev
git push -u origin "$session_branch"
Step 4: Detect commit language
git log --oneline -10
Detect language of existing commits (Russian / English). Use the same for all commits this session.
Step 5: Parse flags
⛔ STRICT PARSING — NO INFERENCE. Lead parses ONLY the literal flag tokens listed below. Lead does NOT infer flags from context ("this is just tests, let's skip review"), does NOT alias unknown flags to known ones, does NOT silently drop or substitute flags. If a flag is not explicitly in $ARGUMENTS, its value is the default below — period.
Extract from $ARGUMENTS:
--solo -> flags.solo = true, mode = "solo"
--careful -> flags.careful = true
--no-review -> flags.no_review = true
--plan-approve -> flags.plan_approve = true
--sop -> (no-op, DEPRECATED — squash is now the default; accepted for backward compatibility, silently ignored)
--no-sop -> flags.squash_on_push = false # disable default squash; use regular merge commit on push (preserves per-task commits in dev log)
Default: solo=false, careful=false, no_review=false, plan_approve=false, squash_on_push=true (squash is the default; --no-sop opts out). mode = "team".
Unknown flag handling: any token starting with -- that is NOT in the list above → STOP, surface to user: "Unknown flag: '{flag}'. Recognized flags: --solo, --careful, --no-review, --plan-approve, --sop (deprecated no-op), --no-sop. Did you mean one of these? Drop or correct the flag and re-run.". Do NOT guess. Do NOT proceed with default behavior. Do NOT alias.
Flag echo (MANDATORY): immediately after parsing, BEFORE creating team or spawning Dev, Lead MUST echo the resolved flag set to user in one line:
Flags resolved: solo={true|false}, careful={true|false}, no_review={true|false}, plan_approve={true|false}, squash_on_push={true|false}, mode="{team|solo}".
This makes silent flag-misinterpretation impossible — user sees what Lead understood and can stop the session if wrong before any work happens.
Flag compatibility (explicit):
--solo forces mode = "solo". Solo has no agents, no SCOUT, no review — so flags that presuppose those CANNOT coexist:
--solo + --careful -> ERROR, STOP: "--solo and --careful are incompatible: --solo has no agents, --careful needs a QA agent. Drop one flag and re-run."--solo + --plan-approve -> ERROR, STOP: "--solo and --plan-approve are incompatible: --plan-approve waits for your OK on a Scout Report, but --solo skips SCOUT entirely. Drop one flag and re-run."--solo + --no-review -> INFO, proceed: "--no-review is redundant with --solo (solo already skips review). Continuing." (keep flags.no_review=true for state completeness)
--sop is DEPRECATED and now a no-op — squash is the default for push. Passing --sop is accepted (no error) but changes nothing; Lead may optionally print "--sop is deprecated: squash-on-push is now the default. Ignoring.". Use --no-sop to opt out of the default squash.--no-sop is compatible with every other flag (including --solo). It only affects Push Step 5 (PR merge strategy): when set, Push uses --merge instead of --squash. It does NOT affect review, QA, or any other phase.
Rationale: silent flag-dropping or silent flag-inference leaves users confused when a promised agent (QA, reviewers, user-approval gate) never appears, OR a promised flag (squash) is silently swapped for an unrelated one (skip-review). Prefer a clear error / mandatory echo at Phase 0 over a mysterious missing/extra behavior mid-session.
Step 5.5: Collect dev-server URL (if --careful with web interface)
If flags.careful == true:
- Ask user once: "
--careful spawns a QA subagent that opens a browser MCP. What dev-server URL should QA use? (e.g., http://localhost:3000, or none if this is a CLI/API project, or later to set it via set dev-server <url> once the server is up)"
- Record answer as
dev_server_url in state:
- Valid URL (
http://... or https://...) -> store as-is.
none -> store empty string; QA will skip browser checks and only run CLI/API tests.later or empty -> store empty string; remind user: "You can set it anytime during the session with set dev-server <url>. Until then, QA will block on browser tasks."
- This skill does NOT start the server. If user hasn't started it yet, tell them to do so before the first
--careful task, or use later and set the URL after starting it.
Step 6: Spawn Dev (if not --solo)
{lead_name} is the literal string "lead" — used inside spawn prompts so the Dev subagent knows who to address its result to.
Spawn Dev for the FIRST task only when there is a real first task to brief — bx:dev does NOT pre-spawn a Dev that sits idle. The first Dev spawn happens at the start of Main Loop iteration 1 (see "Spawn Dev" inside the Main Loop), with the actual task brief.
For now (Phase 0 Step 6) record no live Dev:
state.teammates.dev = null and state.codex_agents.dev = null. The spawn
happens when the user provides their first task in the Main Loop.
Step 7: Save session state
SESSION_ID="${session_id:-$(date +%Y%m%d-%H%M%S)}"
mkdir -p ".bx-dev/${SESSION_ID}"
cat > ".bx-dev/${SESSION_ID}/state.json" <<EOF
{
"active": true,
"branch": "${session_branch}",
"topic": "${topic}",
"team_name": "bx-dev-${project}",
"mode": "${mode}",
"teammates": {"dev": null, "bug_reviewer": null, "security_reviewer": null, "compliance_reviewer": null, "qa": null, "merger": null},
"codex_agents": {"dev": null, "bug_reviewer": null, "security_reviewer": null, "compliance_reviewer": null, "qa": null, "merger": null},
"waiting_for": "",
"task_count": 0,
"push_count": 0,
"flags": {"solo": ${solo}, "careful": ${careful}, "no_review": ${no_review}, "plan_approve": ${plan_approve}, "squash_on_push": ${squash_on_push:-true}},
"dev_server_url": "${dev_server_url:-}",
"completed_tasks": []
}
EOF
Step 8: Tell user
"Session started on {session_branch}. [team mode / solo mode]. Tell me what to do. Say push when ready to merge into dev, exit to end."
Task Loop
When user says something that is not push/exit/done:
Step 1: Lead formats task brief
Extract the user's request. Compose a task message:
## Task
{user's request, verbatim}
## Project context
Read CLAUDE.md and AGENTS.md for project rules and conventions.
## Session context
Branch: {session_branch}
Previous tasks this session:
{for each completed task: "- {description} (files: {file list})"}
Step 2: Spawn Dev
There is no live Dev to message — single-shot subagents do not persist between tasks. For every iteration, spawn a fresh Dev with the FULL brief (task + any session context the new Dev needs).
Choose the Dev mode before spawning:
MODE: IMPLEMENT when flags.plan_approve == false. Dev performs SCOUT internally, implements, verifies, and returns one final implementation report containing the Scout Report plus changed files.MODE: SCOUT_ONLY when flags.plan_approve == true. Dev performs SCOUT only, returns the Scout Report as its final response, and stops. Lead must close that scout agent before asking the user for approval.
Spawn Dev:
Spawn a worker subagent named bx-dev-dev with the following input: <DEV PROMPT (Spawn Prompts section) with MODE plus task brief and session context appended>.
After the spawn returns an agent id, persist the lifecycle state before waiting:
jq --arg id "<agent_id>" --arg name "dev-{N}" \
'.teammates.dev = $name
| .codex_agents.dev = {"agent_id": $id, "role": "dev", "status": "running"}
| .waiting_for = "dev"' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Step 3: Wait for Dev final response
WAIT for Dev's final response via wait_agent on codex_agents.dev.agent_id. If interrupted, first check for a late subagent_notification before deciding Dev is still pending.
If Dev returns STATUS: BLOCKED_QUESTION, persist the question, call close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear Dev state, ask the user, then spawn a fresh Dev with the user's answer included using the Dev spawn lifecycle transaction. Do not keep the blocked Dev panel open.
When the final response is received, persist the Scout Report section to .bx-dev/<session-id>/brief.md. For MODE: IMPLEMENT, also persist the implementation report to .bx-dev/<session-id>/dev-report.md. Then call close_agent(target=<agent_id>), clear waiting_for, clear teammates.dev, and mark codex_agents.dev.status = "closed":
jq '.waiting_for = "" | .teammates.dev = null | .codex_agents.dev.status = "closed"' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Step 4: Lead handles Scout Report
If --plan-approve:
Show plan to user only after the SCOUT_ONLY Dev final response has been persisted and the scout agent has been closed.
- User says OK/go/proceed -> spawn a fresh Dev in
MODE: IMPLEMENT with the approved Scout Report and original task included, using the Dev spawn lifecycle transaction. Go back to Step 3.
- User says "no, do it differently" / provides corrections -> spawn a fresh Dev in
MODE: SCOUT_ONLY with the corrections included, using the Dev spawn lifecycle transaction. Go back to Step 3.
Default (no --plan-approve):
There is no second message to Dev. The same MODE: IMPLEMENT spawn already performed SCOUT, implemented, verified, returned final response, and was closed.
If user intervenes before Dev finishes ("wait, do it differently") -> send
input only if the agent is still running. If a final response already arrived,
close that agent first, mark it closed, then spawn a fresh Dev with the new
constraints using the Dev spawn lifecycle transaction.
Step 5: Lead receives Dev implementation report
Dev has already written tests where appropriate, implemented the approach from the Scout Report, run tests/linter, self-verified, returned "Done, files: [...]", and been closed by Lead.
Step 6: Lead receives Dev's "Done"
If --no-review flag -> skip to Step 9 (Commit).
Otherwise -> proceed to Step 7 (Smart Reviewer Selection).
Step 6.5: Smoke tests (Lead runs BEFORE review)
Find tests related to Dev's changed files:
changed_src=$(git diff --name-only HEAD | grep -E '\.(py|ts|js|go|rs)$' | grep -v test | grep -v spec\.)
For each source file, find matching test file (heuristic: test_{name}, {name}_test, {name}.test, {name}.spec):
for src in $changed_src; do
base=$(basename "$src" | sed 's/\.[^.]*$//')
find . -name "test_${base}*" -o -name "${base}_test*" -o -name "${base}.test.*" -o -name "${base}.spec.*" 2>/dev/null
done
Run found tests. Detect framework:
.venv/bin/pytest <test_files> -v --tb=short 2>/dev/null
npx jest <test_files> 2>/dev/null
go test <packages> -v 2>/dev/null
-
Tests pass — proceed to Step 7.
-
Tests fail — spawn a fresh Dev in MODE: IMPLEMENT with input: "Tests fail on your changes. Fix before review: {failed test output}". Follow the Dev spawn lifecycle transaction: persist teammates.dev, codex_agents.dev = {agent_id, role:"dev", status:"running"}, and waiting_for="dev" before waiting. Wait for Dev's final response, persist the fix report, then close the Dev agent with close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear teammates.dev, and clear waiting_for.
Re-run tests. Max 2 rounds. After 2 — show failures to user, ask "Proceed to review anyway?"
-
No test files found — proceed to Step 7 (no blocking).
Step 7: Smart Reviewer Selection
Lead analyzes what changed:
changed_files=$(git diff --name-only HEAD)
diff_stat=$(git diff --stat HEAD)
Pre-step — TRIVIAL fast path:
Read the Scout Report complexity line from .bx-dev/<session-id>/brief.md:
complexity=$(grep -iE '^### Complexity' -A 1 .bx-dev/<session-id>/brief.md | tail -1 | grep -oE 'TRIVIAL|MODERATE|COMPLEX' | head -1)
If complexity extraction fails (empty output) -> safe fallback: treat as non-TRIVIAL and continue with normal reviewer selection below. Do NOT skip review on ambiguity.
If complexity == "TRIVIAL" AND diff_stat is small (<20 lines changed, ≤2 files) AND no security-regex match below AND no Compliance trigger below:
-> Skip ALL reviewers. Tell user: "TRIVIAL task — skipping review. Proceed to commit."
-> Jump to Step 9 (Commit).
This preserves review for MODERATE/COMPLEX tasks and for TRIVIAL tasks that happen to touch a security-regex file or a Compliance-gated repo. Rationale: a Bug Reviewer round-trip per one-line CSS tweak is pure overhead; the SCOUT already classified the task as safe.
Decision logic for which reviewers to spawn (non-TRIVIAL path):
ALWAYS: Bug Reviewer
IF any changed file matches security-sensitive patterns -> + Security Reviewer:
echo "$changed_files" | grep -iE '(auth|login|session|cookie|token|password|secret|credential|jwt|oauth|csrf|sanitiz|encrypt|decrypt|sql.?injection|migration|\.env|deserializ|exec|eval|child_process|webhook)'
If any match -> spawn Security Reviewer.
Rationale: the pattern deliberately omits everyday tokens like api, url, config, role, redirect, callback, admin, cors, tls, ssl, helmet, rate-limit, cert, upload, download, input, valid, db, database, query, hash, spawn, permission, middleware, acl. Those matched too many neutral filenames (e.g. url-helper.ts, webpack.config.js, RoleSelect.vue, useCallback.ts) and produced security-review false-positive spawns. Keep the list narrow; add tokens back only with a concrete false-negative.
IF CLAUDE.md or AGENTS.md exists with substantive content (>10 lines) -> + Compliance Reviewer:
[ -f CLAUDE.md ] && [ $(wc -l < CLAUDE.md) -gt 10 ] && echo "COMPLIANCE"
[ -f AGENTS.md ] && [ $(wc -l < AGENTS.md) -gt 10 ] && echo "COMPLIANCE"
If either matches -> spawn Compliance Reviewer.
Show user which reviewers are being spawned:
"Spawning reviewers: Bug Reviewer [+ Security Reviewer] [+ Compliance Reviewer]"
Step 8: Review cycle
Initialize review_round = 0.
8a: Compose review brief
## Review Brief
**User request:** {what user asked}
**Scout analysis:** {approach and risks from .bx-dev/<session-id>/brief.md}
**Dev's report:** {Done message with file list}
**Changed files:**
{git diff --stat output}
8b: Spawn selected reviewers in parallel
- Bug Reviewer: spawn a fresh reviewer subagent with
<BUG REVIEWER PROMPT with review brief>.
- Security Reviewer, if selected: spawn a fresh reviewer subagent with
<SECURITY REVIEWER PROMPT with review brief>.
- Compliance Reviewer, if selected: spawn a fresh reviewer subagent with
<COMPLIANCE REVIEWER PROMPT with review brief>.
For each spawned reviewer, capture the returned agent id and persist it before
waiting:
jq --arg id "<agent_id>" --arg name "<logical-reviewer-name>" --arg role "<bug_reviewer|security_reviewer|compliance_reviewer>" \
'.teammates[$role] = $name
| .codex_agents[$role] = {"agent_id": $id, "role": $role, "status": "running"}' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
8c: Wait for all reviewers
jq '.waiting_for = "reviewers"' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
WAIT for ALL spawned reviewers to report via wait_agent on their recorded codex_agents ids. If interrupted mid-wait, first reconcile any late subagent_notification results before re-waiting or re-spawning.
Once ALL replied, persist the review reports, close every reviewer agent, mark
each closed, clear the logical teammate slots, and clear waiting_for:
jq '.waiting_for = ""
| .teammates.bug_reviewer = null
| .teammates.security_reviewer = null
| .teammates.compliance_reviewer = null
| if .codex_agents.bug_reviewer then .codex_agents.bug_reviewer.status = "closed" else . end
| if .codex_agents.security_reviewer then .codex_agents.security_reviewer.status = "closed" else . end
| if .codex_agents.compliance_reviewer then .codex_agents.compliance_reviewer.status = "closed" else . end' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
8d: Merge findings
Combine issues from all reviewers. Deduplicate (same file:line AND same root cause = one issue; keep both if they describe different problems).
8e: Decide
CASE A — CLEAN:
Zero issues across all reviewers.
-> Reviewers were already closed and state was cleared in Step 8c.
-> Proceed to Step 9 (Commit).
CASE B — MINOR/INFO ONLY:
Zero [CRITICAL] + zero [MAJOR], but [MINOR] or [INFO] issues exist.
-> Show summary to user (informational).
-> Spawn fresh Dev in MODE: IMPLEMENT with input: "Review passed. Fix these items: {merged list}"
-> Follow the Dev spawn lifecycle transaction: persist codex_agents.dev = {agent_id, role:"dev", status:"running"} and waiting_for="dev" before waiting. Wait for Dev's final response, persist the fix report, then close the Dev agent with close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear teammates.dev, and clear waiting_for.
-> Re-run smoke tests (Dev's MINOR fixes may have broken something):
Same targeted tests as Step 6.5. If fail — spawn fresh Dev with the smoke
failure using the Dev spawn lifecycle transaction, fix, retest (max 2
rounds).
-> Reviewer agents were already closed and state was cleared in Step 8c.
-> Proceed to Step 9 (Commit).
CASE C — CRITICAL/MAJOR FOUND:
Any [CRITICAL] or [MAJOR] survived.
-> Spawn fresh Dev in MODE: IMPLEMENT with input: "Review found issues. Fix these: {merged list with all severities}"
-> Follow the Dev spawn lifecycle transaction: persist codex_agents.dev = {agent_id, role:"dev", status:"running"} and waiting_for="dev" before waiting. Wait for Dev's final response, persist the fix report, then close the Dev agent with close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear teammates.dev, and clear waiting_for.
-> Increment review_round.
If review_round >= 2:
-> Reviewer state is already clear for the completed review round.
-> Show remaining issues to user: "Review didn't converge after 2 rounds. Remaining: {issues}. Commit anyway? [y/n]"
- User says yes -> proceed to Step 9 (Commit).
- User says no -> spawn fresh Dev in
MODE: IMPLEMENT with the specific
issues using the Dev spawn lifecycle transaction. User drives manually, but
every Dev final response is still closed with close_agent.
Otherwise (review_round < 2):
-> Old reviewer state is already clear for the completed review round.
-> Spawn fresh reviewers (Step 8b) with updated review brief including Dev's "Fixed" report.
-> Repeat from Step 8c.
Step 9: Commit (local, on session branch)
After review passes (or user overrides, or --no-review):
git add <all changed project files from git status>
git commit -m "<type>(dev): <description>"
Type: feat / fix / refactor / chore / docs / test — pick based on what was done.
Description: concise summary in the detected language.
Update state:
jq --arg desc "<description>" '.task_count += 1 | .completed_tasks += [$desc]' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Step 10: QA (--careful only)
If --careful flag is NOT set -> skip to Step 11.
Before spawning, read dev_server_url from state:
dev_server_url=$(jq -r '.dev_server_url // ""' .bx-dev/<session-id>/state.json)
Spawn QA:
Spawn a worker subagent named bx-dev-qa with the following input: <QA PROMPT with task context + all changed files + Scout brief + dev_server_url inlined into the dev_server_url: field>. Empty string for dev_server_url means QA will skip browser checks and report the blocker.
After the spawn returns an agent id, persist QA lifecycle state before waiting:
jq --arg id "<agent_id>" --arg name "qa-{task_count}" \
'.teammates.qa = $name
| .codex_agents.qa = {"agent_id": $id, "role": "qa", "status": "running"}
| .waiting_for = "qa"' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
WAIT for QA result via wait_agent on codex_agents.qa.agent_id. If
interrupted, first reconcile any late subagent_notification from QA.
After consuming the QA report, close QA and clear state before routing:
jq '.waiting_for = "" | .teammates.qa = null | .codex_agents.qa.status = "closed"' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
QA passed: proceed to Step 11.
QA failed: Spawn fresh Dev in MODE: IMPLEMENT with input:
"QA found issues: {QA's report}. Fix these."
Follow the Dev spawn lifecycle transaction before waiting. WAIT for Dev's final
response, persist the fix report, then close Dev with
close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear
teammates.dev, and clear waiting_for.
Amend the commit:
git add <fixed files>
git commit --amend --no-edit
Spawn fresh QA with the same QA lifecycle transaction. Re-test. Max 2 QA
rounds. After 2 -> show failures to user, ask "Proceed anyway?"
Step 11: Task complete
Close any remaining reviewer/QA agent ids with close_agent(target=<agent_id>) and clear their state slots.
Update context file:
cat >> .bx-dev/<session-id>/context.md <<CTX
## Task ${task_count}: ${description}
- Scout: ${complexity}
- Review: ${N} reviewers, ${M} issues found
- Files: ${file_list}
- Status: committed
CTX
Tell user: "Task done. [{N} reviewers, {M} issues found/fixed]. {task_count} tasks this session. Continue or push."
Set Dev-Server Command
When user says set dev-server <url>, dev-server <url>, set server <url>, or similar:
Extract the URL (first http://... or https://... token after the trigger phrase). If no valid URL found, ask: "What URL? e.g. http://localhost:3000" and STOP.
Validate shape only (no network call):
echo "$url" | grep -qE '^https?://'
If invalid -> "Not a valid URL (needs http:// or https:// prefix)." STOP.
Update state:
jq --arg u "$url" '.dev_server_url = $u' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Tell user: "Dev-server URL set to {url}. QA (--careful) will use this for browser MCP checks."
Use case: user started /bx:dev feat-x --careful but answered none in Phase 0 Step 5.5 (or forgot to start the server), then later started the dev-server and wants QA to actually check the browser. This command updates state without restarting the session.
Note: this command ONLY sets the URL. It does NOT start a dev-server — that is your responsibility. See Step 5.5 for the initial collection flow.
Push Command
When user says push, go, ship, merge, push, or similar:
Step 1: Check changes to push
First normalize solo-mode dirty changes into a commit, because solo mode
intentionally accumulates work until push.
Read mode and dirty state:
mode=$(jq -r '.mode' .bx-dev/<session-id>/state.json)
dirty=$(git status --porcelain --untracked-files=all)
If mode == "solo" and dirty is non-empty:
Now check committed changes:
git log origin/dev..HEAD --oneline
If nothing -> "Nothing to push." Continue session.
Step 2: Run tests
Detect test framework (pyproject.toml / package.json / go.mod).
If found:
.venv/bin/pytest tests/ -v --tb=short 2>/dev/null
npm test 2>/dev/null
go test ./... -v 2>/dev/null
- Tests pass -> proceed.
- Tests fail -> show failures. Ask user: "Tests fail. Push anyway? [y/n]"
User decides.
- No test framework detected -> skip.
Step 3: Push session branch
Lead pushes directly in both team and solo mode:
git push origin ${session_branch}
Step 4: Create PR
Lead creates the PR directly in both team and solo mode (Lead already has the full context for the title/body):
pr_url=$(gh pr create \
--base dev \
--head "${session_branch}" \
--title "<summary of all tasks since last push>" \
--body "$(cat <<'PR_BODY'
Ad-hoc changes from /bx:dev session.
Tasks:
$(git log origin/dev..HEAD --oneline)
PR_BODY
)")
If gh pr create fails (e.g., PR already exists) — check for existing PR:
pr_url=$(gh pr list --head "${session_branch}" --base dev --json url -q '.[0].url')
If still no PR — tell user the error, STOP.
Capture pr_url — it is passed to Merger in Step 5 (team mode) or used by Lead directly (solo mode).
Step 5: Merge PR
Read merge-strategy flag from state:
squash=$(jq -r '.flags.squash_on_push' .bx-dev/<session-id>/state.json)
if [ "$squash" = "true" ]; then merge_op="pr-merge-squash"; else merge_op="pr-merge-merge"; fi
Merge strategy: default is --squash (clean linear log in dev, one commit per push). Use session flag --no-sop to fall back to --merge (all per-task commits preserved on dev as a merge commit).
Step 5 — Team mode (state.mode == "team")
Lead does NOT run gh pr merge directly. Lead spawns a Merger teammate to execute the PR merge.
-
Assemble MERGE_BRIEF. Capture read-only git context first:
commits_summary=$(git log origin/dev..${session_branch} --oneline)
diff_stat=$(git diff --stat origin/dev..${session_branch})
recent_target=$(git log --oneline -10 origin/dev)
N=$(echo "$commits_summary" | wc -l | tr -d ' ')
one_line_summary=$(echo "$commits_summary" | head -1)
-
Read Merger template and merge protocol + append the merge brief:
- Read
templates/agents/bx-dev-merger.md.
- Read
docs/MERGE-PROTOCOL.md.
- Append the full merge protocol first so the Merger input is
self-contained:
## MERGE_PROTOCOL
<contents of docs/MERGE-PROTOCOL.md>
- Append the following
MERGE_BRIEF block after the protocol:
Operation: ${merge_op}
Source branch: ${session_branch}
Target branch: dev
PR URL: ${pr_url}
Scope / intent: Ad-hoc /bx:dev session push — ${N} commits since last push: ${one_line_summary}
What changed (diff summary):
${commits_summary}
${diff_stat}
Recent commits on target:
${recent_target}
Expected post-merge state: dev tip contains session's changes (as a single squashed commit if Operation is pr-merge-squash, as a merge commit preserving per-task history if Operation is pr-merge-merge); session branch ${session_branch} preserved (delete_branch=false) for continued work.
Delete branch: false
-
Spawn Merger as a fresh single-shot subagent:
Spawn a worker subagent named bx-dev-merger with the following input: <Merger template with substitutions above>.
After the spawn returns an agent id, persist it before waiting:
jq --arg id "<agent_id>" --arg name "merger-push-{push_count}" \
'.teammates.merger = $name
| .codex_agents.merger = {"agent_id": $id, "role": "merger", "status": "running"}' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
-
Set waiting_for:
jq '.waiting_for = "merger"' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
-
Wait for Merger's verdict via wait_agent. If interrupted, first reconcile any late subagent_notification from Merger before deciding the merge is still pending.
-
Persist, close, and clear Merger state after consuming the verdict,
before routing on the status:
- Persist Merger's full report to the session context or push log.
- Call
close_agent(target=<codex_agents.merger.agent_id>).
jq '.teammates.merger = null | .codex_agents.merger.status = "closed" | .waiting_for = ""' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
-
Route on Merger verdict status:
CLEAN (or CONFLICT_RESOLVED — same success semantics): proceed.- Any other exact template status (
ESCALATION_CC, ESCALATION_PROTOCOL,
ROLLBACK_SMOKE_FAIL, ROLLBACK_TEST_REGRESSION,
ROLLBACK_COVERAGE_DEGRADATION, ROLLBACK_SEMANTIC_FAIL,
ROLLBACK_CONTINUE_FAIL, ROLLBACK_COMMITS_MISSING, STALE_BASELINE,
BASELINE_UNUSABLE, TEST_INFRA_FAIL,
UNRECOVERABLE_AFTER_PR_MERGE, OTHER_GIT_FAIL,
BRANCH_PROTECTION_BLOCKED): show Merger's verbatim verdict text to user.
STOP Push. Keep session intact (same spirit as Exit Command 3b —
session branch + Dev + state all preserved; user can fix the underlying
issue and re-run push). Do NOT proceed to Step 6 (sync).
Proceed to Step 6 (sync).
Step 5 — Solo mode (state.mode == "solo")
Lead runs gh pr merge directly (no Merger spawn — solo has no agents):
if [ "$squash" = "true" ]; then
gh pr merge "$pr_url" --squash --delete-branch=false
else
gh pr merge "$pr_url" --merge --delete-branch=false
fi
--delete-branch=false — keep the session branch alive for more work.
If gh pr merge fails → show the error to user, STOP. Do NOT proceed to Step 6.
Step 6: Sync session branch with dev
After PR merge lands on dev, pull it back into the session branch so the next task starts from the merged tip:
git pull origin dev --ff-only
If ff-only succeeds → proceed to Step 7.
If ff-only fails (divergent — e.g., a concurrent push to dev from elsewhere landed between Step 5 and now):
Team mode:
Lead does NOT run git merge directly. Lead spawns a Merger teammate (operation merge) for the local sync.
-
Assemble brief:
Operation: merge
Source branch: origin/dev
Target branch: ${session_branch} (already checked out)
PR URL: N/A (local merge, not pr-merge)
Scope / intent: Post-push sync — pull concurrent origin/dev changes back into session branch ${session_branch} after our own push merged.
What changed (diff summary): <git log --oneline ${session_branch}..origin/dev> + <git diff --stat ${session_branch}..origin/dev>
Recent commits on target: <git log --oneline -10 ${session_branch}>
Expected post-merge state: session branch tip contains origin/dev's latest commits merged in.
(Delete branch is omitted — N/A for local merge.)
-
Spawn Merger with name merger-sync-{push_count}, same spawn lifecycle as
Step 5 team-mode. Persist
codex_agents.merger = {agent_id, role:"merger", status:"running"} and
teammates.merger = "merger-sync-{push_count}" before waiting.
-
Set waiting_for="merger". Wait for Merger's final verdict via wait_agent on codex_agents.merger.agent_id.
-
Persist the Merger report, call close_agent(target=<agent_id>), set
codex_agents.merger.status="closed", clear teammates.merger, and clear
waiting_for.
-
Route on verdict:
CLEAN / CONFLICT_RESOLVED: proceed to Step 7.- Any other exact template status: show Merger's verdict to user. STOP Push. Session intact. Do NOT proceed to Step 7 (push_count is NOT incremented on sync failure — the main PR-merge already landed on
dev, but the session branch is now out of sync with dev and needs user attention).
Solo mode:
Lead resolves directly:
git merge origin/dev --no-edit
If merge conflicts → apply Merge Protocol (docs/MERGE-PROTOCOL.md), Steps 0 through 6:
- Step 0 — DETECT
operation="merge" via .git/MERGE_HEAD (NOT REBASE_HEAD); record for later --abort / --continue.
- Step 1 — SETUP
diff3 + rerere.
- Step 2 — CLASSIFY each conflicted file:
T / SEM / S / DR / B / SM / CC / E / L. Most files here will be T (textual) or L (lock-file).
- Step 3- — RESOLVE per type.
Type CC + -s resolve is the one unconditional NEVER.
- Step 4 — SEMANTIC-CHECK (import chain, API shape, test alignment).
- Step 5 — SMOKE-TEST (detect stack via
pyproject.toml / package.json / go.mod / Cargo.toml / build.gradle; run the corresponding compile + test commands).
- Step 6 — VERIFY: no markers, diff sane, merge commit message conventions.
Step 7 (ROLLBACK) applies only if a broken merge is discovered AFTER commit — use git reset --hard ORIG_HEAD (pre-push CASE A) or git revert -m 1 <merge-sha> (post-push CASE B/C).
On unresolvable conflict (Type CC or protocol escalation) → show to user, STOP.
Step 7: Update state + tell user
jq '.push_count += 1' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Tell user (include "via Merger" only in team mode):
- Team mode:
"Pushed ({squash ? "squash" : "merge"}) into dev via Merger. Continue or exit."
- Solo mode:
"Pushed ({squash ? "squash" : "merge"}) into dev. Continue or exit."
Exit Command
When user says exit, done, end, or similar.
Philosophy: exit is a full teardown. It auto-commits leftover work, auto-pushes unpushed commits, kills background processes, then cleans up team + state + branch. No confirmations for obvious cleanup — user already said exit.
Ordering rule: reversible actions first (commit), then the make-or-break gate (push), then irreversible cleanup (kill background, shutdown, delete branch, rm state). If the push gate fails, STOP and leave the session fully workable — do NOT proceed to shutdown.
Abort semantics: any failure in Steps 2 or 3 aborts the exit. Steps 4+ are never reached. If Step 2 created a finalize commit, that commit remains on the session branch; abort does not automatically roll it back. Tell the user they can undo only that finalize commit with git reset --soft HEAD~1 if they want the changes staged again before the next push.
Step 1: Plan (read-only)
Collect facts without mutating anything:
dirty=$(git status --porcelain)
unpushed=$(git log origin/dev..HEAD --oneline 2>/dev/null | wc -l)
Record the initial dirty state and pre-exit HEAD (in-memory) for reporting
and explicit user-requested discard options. Do not automatically roll back a
finalize commit on abort.
Step 2: Auto-commit dirty changes (reversible)
If dirty is non-empty:
-
In team mode: Spawn a fresh worker subagent named bx-dev-dev only when the
pending changes need a final file/report pass before committing. Input:
"Before exit: inspect pending changes, finish any incomplete file edits only if
required, do not run git add, do not commit, do not push, then report Done with
changed files and a one-line commit summary." After the spawn returns an agent
id, persist teammates.dev = "dev-exit-finalize" and
codex_agents.dev = {agent_id, role:"dev", status:"running"} with
waiting_for="exit-finalize" before waiting. Wait for the final response,
persist the one-line commit summary (if useful), call
close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear
teammates.dev, and clear waiting_for.
-
Lead commits directly in both team and solo mode:
summary=$(git diff --stat | tail -1)
git add -A
git commit -m "chore(dev): finalize session — ${summary}"
-
Record the Lead-created commit SHA as finalize_sha (in-memory).
-
Tell user: "Auto-committed {N} uncommitted file(s) as finalize commit {SHA short}."
If dirty was empty, set finalize_sha="" and skip.
Recompute unpushed (it may have grown by 1 after the finalize commit).
Step 3: Auto-push if anything unpushed — THE GATE
If unpushed == 0: nothing to push, proceed to Step 4.
If unpushed > 0: run Push Command (all 7 steps: 1 check changes, 2 run tests, 3 push branch, 4 create PR, 5 merge PR, 6 sync session with dev, 7 state + tell user). Uses --squash if flags.squash_on_push == true (default), otherwise --merge (--no-sop). Intercept failures and abort exit:
3a. Tests fail (Push Step 2)
ABORT exit. Tell user:
Exit aborted: test suite failed on {N} test(s).
Session is intact. Dev, team, branch, state — all preserved.
{if finalize_sha set:} Your finalize commit {SHA} is on the branch. Run `git reset --soft HEAD~1` to unstage it if you want to keep editing before next push.
Failing tests:
{list}
Options:
1. Fix the failures, then say `exit` again.
2. `push anyway` → re-run push with tests skipped, then exit.
3. `discard` → `git reset --hard {pre-exit SHA}` to drop finalize commit and exit without pushing (keeps uncommitted dev-server etc. alive).
STOP. Do NOT touch teammates, background processes, branch, or state.
3b. PR creation or merge fails (Push Step 4 — gh pr create, OR Push Step 5 solo-mode gh pr merge)
ABORT exit with the same "session intact" preservation logic as 3a. Show the exact gh error to the user. Common causes: no dev branch on remote, auth expired, PR permission denied. Options shown:
1. Fix the remote issue, then `exit` again.
2. `discard` → keep everything local, exit without push.
STOP.
3c. Merge conflict during sync (Push Step 6)
Apply MERGE-PROTOCOL.md (solo mode) or Merger teammate resolves per CONFLICT_RESOLVED (team mode). Most types (T, L, SEM) resolve automatically — exit continues as if nothing happened. For CC (concurrent change on same line), protocol escalates:
Exit paused: concurrent conflict in {file}:{line}.
Your change: {diff}
Origin/dev change: {diff}
Resolution? (your / theirs / custom)
Wait for user. After resolution → continue Push. If the user types abort instead of a resolution → treat as 3b abort (session intact, push reverted via git merge --abort).
In team mode: if Merger returns any verdict other than CLEAN or
CONFLICT_RESOLVED on the sync merge (for example ROLLBACK_SMOKE_FAIL,
ROLLBACK_TEST_REGRESSION, ESCALATION_CC, ESCALATION_PROTOCOL,
STALE_BASELINE, OTHER_GIT_FAIL) → ABORT exit with the same session-intact
preservation as 3a. Show Merger's verbatim verdict text to user. Note that the
PR merge in Push Step 5 has already landed on dev at this point — only the
session branch is out of sync. push_count is NOT incremented (Push Step 7 was
not reached).
3d. Push succeeded (Push Steps 5 + 6 both CLEAN)
Increment push_count (done by Push Step 7). Tell user briefly: "Pushed ({squash ? "squash" : "merge"}) into dev{ via Merger if team mode}." Proceed to Step 4.
3e. Merger failure during PR merge (Push Step 5 — team mode only)
Team mode only. Merger returned a non-CLEAN / non-CONFLICT_RESOLVED verdict on the PR merge itself (examples: ROLLBACK_TEST_REGRESSION, ROLLBACK_COVERAGE_DEGRADATION, ROLLBACK_SMOKE_FAIL, ROLLBACK_SEMANTIC_FAIL, ROLLBACK_COMMITS_MISSING, ROLLBACK_CONTINUE_FAIL, ESCALATION_CC, ESCALATION_PROTOCOL, STALE_BASELINE, BASELINE_UNUSABLE, TEST_INFRA_FAIL, UNRECOVERABLE_AFTER_PR_MERGE, OTHER_GIT_FAIL, BRANCH_PROTECTION_BLOCKED).
ABORT exit with the same "session intact" preservation logic as 3b. Show Merger's verbatim verdict text (including the full report body — routing hints, rollback details, stage-C findings, etc.) to user so they can decide how to remediate. Options shown:
1. Address the Merger's finding (fix code, adjust branch protection, retry network, etc.), then `exit` again.
2. `discard` → keep everything local, exit without push.
STOP. Do NOT touch background processes, branch, or state, except closing any
completed Merger agent with close_agent if a final verdict was received,
marking codex_agents.merger.status="closed", and clearing
teammates.merger. push_count is NOT incremented (Push Step 7 was not
reached).
Step 4: Kill background processes started by Dev (irreversible)
Reached only if Step 3 succeeded.
If mode == "team" AND background processes were tracked during this session:
spawn a fresh worker subagent named bx-dev-dev with input: "Push succeeded.
Now stop every background process started during this session (dev-server,
watchers, and similar). The list of tracked process/session ids is: . Report the stopped list and any failures." After the spawn
returns an agent id, persist teammates.dev = "dev-exit-kill" and
codex_agents.dev = {agent_id, role:"dev", status:"running"} with
waiting_for="exit-kill" before waiting. Wait for the final response, append
the cleanup report to .bx-dev/<session-id>/context.md, call
close_agent(target=<agent_id>), set codex_agents.dev.status="closed", clear
teammates.dev, and clear waiting_for.
If no tracked background shells / --solo: skip. Inform user: "Note: no tracked background processes — if you manually started any during this session, kill them yourself."
Step 5: Close and clear teammate slots
For every non-null codex_agents.<role>.agent_id, call
close_agent(target=<agent_id>). Ignore "already closed" results. Mark every
non-null Codex agent closed, then clear logical state:
jq '.codex_agents |= with_entries(if (.value | type) == "object" then .value.status = "closed" else . end)
| .teammates = {"dev": null, "bug_reviewer": null, "security_reviewer": null, "compliance_reviewer": null, "qa": null, "merger": null}
| .waiting_for = ""
| .lead_session_id = ""' \
.bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && \
mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Proceed to Step 6 without delay.
Step 6: (no-op — no team to delete)
Codex single-shot subagents leave nothing to tear down. This step exists only as a numbering anchor for downstream Step 7.
Step 7: Switch to dev
git checkout dev && git pull origin dev
Step 8: Delete session branch
unpushed=$(git log origin/dev..HEAD --oneline 2>/dev/null | wc -l)
Since Step 3 succeeded and synced, this should be 0.
If unpushed == 0 AND push_count > 0:
git branch -d "${session_branch}" 2>/dev/null
git push origin --delete "${session_branch}" 2>/dev/null
Edge case: push_count == 0 means the user never pushed anything and had nothing to push at exit (empty session). In that case leave the branch alone silently.
Step 9: Remove state files
rm -f .bx-dev/<session-id>/state.json
rm -f .bx-dev/<session-id>/brief.md
rm -f .bx-dev/<session-id>/context.md
Step 10: Tell user
Session ended.
Tasks completed: {task_count}
Pushes: {push_count} (+{1 if auto-pushed this exit else 0})
Background processes killed: {N}
Branch {session_branch}: deleted
You are on dev.
Abort Reference — what survives an aborted exit
When Exit aborts in Step 2 or 3, EVERYTHING below is preserved:
state.active = true, state.waiting_for = "" (reset from "exit-finalize" if we were waiting on Dev's finalize file/report pass)- Dev agent alive, team alive, reviewers/QA as they were
- Session branch unchanged (or contains finalize commit if user wants to keep it)
- Background processes (dev-server etc.) untouched
- State files untouched
- User can immediately continue with next task, another
push, another exit, or any session command
Reset waiting_for to empty on any abort path:
jq '.waiting_for = ""' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Force-exit escape hatch
If the user really wants to abandon everything without pushing (e.g., experimental session they want to throw away), they say exit! or force exit:
- Skip Steps 2 and 3 entirely.
- Run Steps 4-9 directly.
- Tell user:
"Force exit: {unpushed} unpushed commit(s) and {dirty count} uncommitted change(s) were DISCARDED. Session branch {session_branch} deleted."
- Before Step 7, if dirty or unpushed:
git reset --hard origin/dev && git clean -fd to strip local work. This is destructive — only on explicit exit! / force exit.
Recovery
If /bx:dev is invoked, scan for the active state file:
active_state="$(
find .bx-dev -mindepth 2 -maxdepth 2 -name state.json -print 2>/dev/null |
while IFS= read -r state_file; do
if jq -e '.active == true' "$state_file" >/dev/null 2>&1; then
printf '%s\n' "$state_file"
break
fi
done
)"
if [ -n "$active_state" ]; then
SESSION_ID="$(basename "$(dirname "$active_state")")"
else
SESSION_ID=""
fi
Use .bx-dev/${SESSION_ID}/state.json as the recovered state path. If no
active state exists, start a fresh session.
After restart, logical teammates are not trustworthy. Do not overwrite
codex_agents before late-notification reconciliation because those ids may be
needed for close_agent.
Step 1: Read state
cat .bx-dev/<session-id>/state.json
Read branch, mode, flags, teammates, task_count, push_count, completed_tasks.
Also read .bx-dev/<session-id>/context.md if it exists — this contains the session progress log with details of each completed task.
Reset logical teammates only after reading state:
jq '.teammates = {"dev": null, "bug_reviewer": null, "security_reviewer": null, "compliance_reviewer": null, "qa": null, "merger": null} | .lead_session_id = ""' .bx-dev/<session-id>/state.json > .bx-dev/<session-id>/state.json.tmp && mv .bx-dev/<session-id>/state.json.tmp .bx-dev/<session-id>/state.json
Step 2: Check branch exists
git show-ref --verify refs/heads/${branch}
- Branch exists ->
git checkout ${branch}.
- Branch gone -> clean up state files, start fresh.
Step 3: (no-op — no team to recreate)
Codex single-shot subagents have no persistent team registration. Skip.
Step 4: (no idle Dev to spawn)
Single-shot model: Dev is spawned per task with the task brief, not pre-spawned. Just clear state.teammates.dev = null and proceed to Step 5 — the next user task will spawn Dev with a recovery-aware brief.
Step 5: Determine resume point
Check ground truth to figure out where the session was interrupted:
dirty=$(git status --porcelain)
waiting=$(jq -r '.waiting_for' .bx-dev/<session-id>/state.json)
task_count=$(jq -r '.task_count' .bx-dev/<session-id>/state.json)
has_brief=$([ -f .bx-dev/<session-id>/brief.md ] && echo "yes" || echo "no")
Before applying the matrix below, if waiting is non-empty, inspect the recent
thread for a final subagent_notification from that role. If one exists, treat
it as the authoritative completion event: persist the payload, call
close_agent(target=<codex_agents.<role>.agent_id>), update
state.waiting_for = "", clear the logical teammate slot, mark
codex_agents.<role>.status = "closed", and continue from the next workflow
step that payload implies. Do NOT re-spawn the role in that case.
Decision matrix:
-
waiting_for == "dev" + dirty is empty + has_brief == "yes" — Dev was implementing. Spawn a fresh worker subagent named bx-dev-dev with input: "Resumed session. Your last task context is in the brief below. Continue from where you left off. {brief content}". Persist codex_agents.dev = {agent_id, role:"dev", status:"running"} and teammates.dev = "dev-recovery" before setting waiting_for="dev".
-
waiting_for == "dev" + dirty is not empty — Dev made changes but didn't report Done. Spawn a fresh worker subagent named bx-dev-dev with input: "Resumed. You have uncommitted changes. Review them, finish up, and report Done." Persist codex_agents.dev = {agent_id, role:"dev", status:"running"} and teammates.dev = "dev-recovery" before setting waiting_for="dev".
-
waiting_for == "reviewers" — Reviewer subagents already closed via close_agent (single-shot). Uncommitted changes exist from Dev. Re-run review: go to Task Loop Step 7 (Smart Reviewer Selection).
-
waiting_for == "qa" — QA spawn died before returning. Spawn fresh QA with last task context. Persist codex_agents.qa = {agent_id, role:"qa", status:"running"} and teammates.qa = "qa-recovery" before setting waiting_for="qa".
-
waiting_for == "merger" — Merger subagent died mid-Push (Step 5 PR merge OR Step 6 sync-merge fallback). The crash may have happened before, during, or after the actual git operation. Do NOT auto-respawn Merger — a stage-c-only recovery requires knowing the merge landed, which Lead cannot determine reliably here. Safe recovery: check ground truth.
- Read the latest
gh pr view <session_branch> --json state,mergeCommit -q '.state,.mergeCommit.oid' — if PR is MERGED → the PR merge from Push Step 5 already landed; session branch may still be out of sync with dev. Tell user: "Resumed: the last push's PR merge already landed on dev (sha {merge_sha}), but Merger crashed before reporting. Run 'push' again to re-attempt the session-branch sync, or just continue with new tasks (session branch will drift until the next successful push)." Clear state.teammates.merger + state.waiting_for atomically. Do NOT increment push_count (Push Step 7 was never reached — out of caution).
- If PR is still
OPEN → the PR merge did NOT land. Tell user: "Resumed: last push did not complete (Merger crashed before PR merged). Session is intact. Run 'push' again to retry." Clear state.teammates.merger + state.waiting_for atomically.
- In either branch: do NOT try to reconstruct Merger's mid-flight Stage A/B/C state; the user drives the next action.
-
waiting_for == "shutdown" (legacy from old sessions) — Exit got past the push gate. Single-shot subagents from a prior process may be gone, but any live current-session ids must be closed, so just resume Exit Command from Step 7 (checkout dev + pull), Step 8 (branch cleanup if unpushed==0 && push_count>0), Step 9 (rm state), Step 10 (tell user). Tell user: "Exit was interrupted after push. Resuming teardown."
-
waiting_for == "exit-finalize" — Exit Step 2 was waiting on Dev's finalize file/report pass when the session stopped. First inspect the recent thread for a completed Dev report and close the Dev agent if present. Then check git status --porcelain and last commit message. If the worktree is still dirty, Lead performs the deterministic finalize commit from Exit Step 2. If the worktree is clean and the last commit is chore(dev): finalize session ..., treat it as an already-created finalize commit (legacy sessions may have reached this state), record its SHA, and continue exit from Step 3 (push gate). Tell user: "Resumed exit from finalize step." Then fall through to Step 3.
-
waiting_for == "exit-kill" — Exit Step 4 was waiting on Dev to stop background processes when the session stopped. Some processes may already be stopped. Safe recovery: re-issue the cleanup request with the exit-kill spawn lifecycle transaction. After Dev reports, continue from Step 5 (close teammates with close_agent). Tell user: "Resumed exit from background-process cleanup."
-
waiting_for == "" + dirty is empty — Clean state between tasks. Tell user: "Resumed session on {branch}. {task_count} tasks completed. Tell me what to do."
-
waiting_for == "" + dirty is not empty — Changes exist but no active task. Tell user: "Resumed session. Found uncommitted changes: {file list}. Commit these or discard?"
Step 6: Tell user
Report resume status based on the decision above.
Solo Mode (--solo)
If --solo flag: NO subagents. Lead works directly. The old bx:dev behavior.
Enter Session
Same as Phase 0, but skip Step 6 (no Dev spawn). Set mode = "solo".
Working Phase
User tells you what to implement. You do it directly — apply_patch, shell commands, whatever is needed. No SCOUT, no review, no subagents.
Rules:
- Implement what the user asks. No over-engineering, no unsolicited refactoring.
- Read before edit. Understand existing code before changing it.
- Run checks after changes — if the project has tests/linter, run them.
- Stay on the session branch.
- Do not create commits during the Working Phase. Changes accumulate until user says
push; Push Step 1 creates the solo commit boundary.
Push/Exit
Same as team mode Push Command and Exit Command, minus the teammate close_agent cleanup. Push Step 1 is the solo commit boundary: dirty solo changes are committed once at push, then the branch is pushed and merged.
Spawn Prompts
Dev
You are "{dev_name}" in a bx-dev team.
## Language (overrides global settings)
All reasoning, analysis, and communication: English only.
Code comments: follow project conventions.
## Team
- Lead ({lead_name}) — your boss. He commits, pushes, and manages review.
Return your final report as the structured payload that addresses {lead_name} (Lead reads it as the spawn result).
Lead MUST fill {dev_name}, {lead_name} with actual subagent names when spawning.
## Project context
Read AGENTS.md (and CLAUDE.md if present) for project rules and conventions.
## Session context
Topic: {session topic}
Branch: {session_branch}
Previous tasks this session:
{for each completed_task: "- {description}"}
Use this context to understand what has already been done and avoid conflicts with previous work.
## Python projects
If .venv/ or venv/ exists, ALWAYS use .venv/bin/python (or venv/bin/python) instead of python/python3.
For running tools: .venv/bin/pytest, .venv/bin/ruff, etc.
## Lifecycle
You are a single-shot subagent: one task per spawn, one final response, then you end. Lead spawns a fresh you for the next task — do not assume any in-memory continuity between tasks. All shared state lives in the session files Lead maintains.
## Mode
Lead includes exactly one mode in the spawn input:
- `MODE: IMPLEMENT` — perform SCOUT, implement, verify, and return one final report. Include the Scout Report first and the implementation report after it.
- `MODE: SCOUT_ONLY` — perform SCOUT only, return the Scout Report as your final response, and stop. Do not wait for a follow-up "Go"; Lead will close this agent and spawn a fresh implementation agent after approval.
## Background processes
If a task asks you to start a long-running process (dev-server, watcher, daemon):
- Launch it with the available shell/background-process mechanism for the current Codex runtime.
- **Record the process/session id** in your final report to Lead (e.g., `"Started dev-server as process/session abc123 at http://localhost:5173"`). Lead persists this in `.bx-dev/<session-id>/context.md` so the next spawn can stop it.
- If a task explicitly asks you to stop a process: stop the listed process/session ids with the available runtime mechanism. Report the stopped list and any failures back to Lead in your final response.
## Architecture Awareness (DDD-aware, opt-in, self-triggered)
There is no Lead in `/bx:dev` handing you a skills list; DDD activation is YOUR call, made per task before writing code.
**DDD activation heuristic (self-triggered).** DDD track activates if ANY of:
- The user's task prompt mentions domain vocabulary (aggregate, entity, value object, domain event, repository, bounded context, use case, invariant).
- Scout-style codebase inspection reveals folders named `domain/`, `application/`, `usecases/`, `adapters/`, `ports/`, `infrastructure/`, `core/`, or language-specific equivalents (`internal/domain` in Go, etc.).
- The user explicitly asks for DDD.
Otherwise DDD track stays dormant; proceed with the standard ad-hoc workflow against the project's existing conventions.
If DDD track activates, read `skill-library/architecture/ddd/SKILL.md` from this repository if it is available. **Do NOT read the whole skill upfront.** Read specific numbered sections only when this file instructs you to — Section 2 first (classification), then conditional sections per the classification.
DDD references appear in two places: this top-of-prompt block (activation heuristic + classification gate) and inline at each workflow step (Step 0a, Step 1 Implement). When this top-of-prompt guidance conflicts with an inline step instruction, the more specific inline step wins — you are, at that moment, closer to the decision being made.
**Backward compatibility is a hard invariant.** Legacy ≡ any code that existed in the repository before THIS task started. You MUST NOT refactor legacy code toward DDD, even if it's obviously anemic, procedural, or "wrong" — the cost of breaking backward compatibility exceeds the gain of cleanup. See DDD skill Section 3 "Strangler Fig — Legacy Preservation Rules" for the enumerated non-goals.
**Reporting target.** There is no peer-to-peer message channel for the classification verdict. You announce the classification to the user in your first substantive output of the task: a one-line block — `"Architecture classification for this task: <tag>. Rationale: <1 line>."` — at the top of your Scout Report (see Step 0g), BEFORE the `## Scout Report` header, so the user sees it even if they only skim the top of the panel.
## Workflow
When Lead sends you a task:
### Step 0 — SCOUT (MANDATORY — before ANY code)
Perform deep analysis. Do NOT skip any substep.
**Scaling rule:** If the task is clearly TRIVIAL (single file, obvious change like fix typo/rename/add import), compress SCOUT:
- Do 0a (parse intent) + 0b Layer 1 only (find files) + 0c (confirm TRIVIAL)
- Skip 0d, 0e, 0f
- Prepare compressed Scout Report in 0g: just task summary, complexity=TRIVIAL, files, approach in 1 line
- This keeps SCOUT under 30 seconds for simple tasks
#### 0a. PARSE INTENT
- What is the literal request?
- What is the TRUE intent (what problem does the user actually want solved)?
- Implicit constraints (performance, compatibility, style consistency)
- What is explicitly out of scope?
- Ambiguities:
- [BLOCKING] — cannot proceed without clarification. Ask Lead.
- [ASSUMABLE] — reasonable default exists. State assumption, proceed.
For [BLOCKING] ambiguities: return a final response with `STATUS: BLOCKED_QUESTION` and the exact question. Do NOT continue SCOUT with unresolved blocking ambiguities. Lead will close this agent and spawn a fresh one with the answer.
#### 0b. SCAN CODEBASE (systematic, not quick grep)
**Layer 1 — Find the neighborhood:**
- Keyword search for relevant terms
- Glob for file patterns (*.py, *.ts, etc.)
- Identify entry points and module boundaries
**Layer 2 — Understand current behavior:**
- Read the files you will modify
- Trace the data flow through the affected code
- Capture invariants: what does the current code guarantee?
**Layer 3 — Map blast radius:**
- Reverse dependencies: who imports/calls the code you'll change?
- Downstream consumers: APIs, CLI, UI that depend on this
- Data layer: schemas, migrations, stored data contracts
- Config: environment variables, feature flags, settings
**Layer 4 — Test landscape:**
- Existing test files and their coverage
- Test patterns used (pytest fixtures, jest mocks, etc.)
- Which tests will break if you change X?
#### 0c. ASSESS COMPLEXITY (4 axes)
| Axis | TRIVIAL | MODERATE | COMPLEX |
|------|---------|----------|---------|
| Scope | 1 file, <20 lines | 2-5 files | 5+ files |
| Risk | No breakage possible | Known risks, mitigable | Unknown unknowns |
| Ambiguity | Crystal clear | 1-2 assumptions | Multiple interpretations |
| Dependencies | Isolated | 2-3 dependents | Widely consumed |
Overall complexity = highest axis.
#### 0d. MULTI-PERSPECTIVE ANALYSIS
- **Correctness:** edge cases, error handling, boundary conditions
- **Maintainability:** follows existing patterns, easy to extend later
- **Security:** attack surface changes, input handling, auth implications
- **Performance:** hot paths, N+1 queries, memory allocation
#### 0e. APPROACH DESIGN
- List 1-3 candidate approaches with pros/cons
- Select the best one, justify why
- Decompose into ordered implementation steps
- Identify what test to write first (if applicable)
#### 0f. RISK REGISTER
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {risk 1} | Low/Med/High | Low/Med/High | {how to prevent or detect} |
#### 0g. REPORT TO LEAD
Prepare the structured Scout Report:
Scout Report
Task
{one-line summary}
Complexity
{TRIVIAL / MODERATE / COMPLEX} — {justification}
Approach
{selected approach with ordered steps}
Files to modify
{list of files}
Files to create
{list of new files, if any}
Risks
{risk register table}
Tests
{what tests to write}
Estimated scope
{number of files, approximate lines changed}
If mode is `MODE: SCOUT_ONLY`, return this Scout Report as your final response and stop.
If mode is `MODE: IMPLEMENT`, keep the Scout Report as the first section of your eventual final response, then proceed directly to Step 0a (if DDD track is active) and Step 1. Do not wait for a "Go" message.
### Step 0a — Architecture Classification (only if DDD track activated)
Skip entirely if the DDD activation heuristic (see "Architecture Awareness" above) did NOT fire for this task.
a. Read DDD skill Section 2 **"Architecture Classification — Decision Tree"**.
