bish-x/bx-dev-skill/bx-dev

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:

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:

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

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

1. Single-shot subagents only (when not --solo). Every teammate is a fresh spawn via natural language ("Spawn the <name> subagent with the following input: ..."). There is no team registration, no team_name, no long-running session.
2. 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.

1. 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.
2. 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".
3. 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.
4. 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.
5. Reviewers are fresh per task. Spawn, review, results returned in the spawn response.
6. `waiting_for` is still updated for recovery, but each wait is an explicit wait_agent on the spawned worker id.

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

1. 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>.

1. 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:

1. Do NOT immediately re-spawn the role.
2. Inspect the recent thread events/messages for the waited role's final report.
3. 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"

1. Resume the next workflow step from that final report.
2. 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:

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