bx-dev

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

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

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.

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

4. 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".

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

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

7. Reviewers are fresh per task. Spawn, review, results returned in the spawn response.

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

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

10. 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"
4. Resume the next workflow step from that final report.
5. 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

1. Scope is always dev — no Story IDs in this mode.
2. Description language must match existing commits. Run git log --oneline -10 and detect the language. Use the same.
3. Description is lowercase, imperative mood, no period at end.
4. BREAKING CHANGE: add ! before : — feat(dev)!: redesign auth API.
5. Team mode: one commit per task after review passes. If many unrelated changes, still ONE commit — this is ad-hoc mode.
6. 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}"

# Refs collision check: cannot have both ref `dev` (leaf) and ref `dev/<slug>` (under dir).
# Git stores refs as files: `.git/refs/heads/dev` is either a file OR a directory, not both.
if git show-ref --verify --quiet refs/heads/dev; then
  # `dev` exists as a leaf ref → can't create `dev/<slug>` under it.
  # Fallback: use `adhoc/` prefix (no collision risk).
  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:

# Python
.venv/bin/pytest <test_files> -v --tb=short 2>/dev/null
# Node
npx jest <test_files> 2>/dev/null
# Go
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:

# Relies on the Scout Report template in Section 0g of the Dev Spawn Prompt,
# specifically the `### Complexity` heading followed by `TRIVIAL/MODERATE/COMPLEX`
# on the next line. If you edit that template, keep this grep in sync.
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:

• Inspect the dirty path list and the diff. Treat non-ignored worktree changes made during the solo session as relevant session changes.
• If any dirty path is clearly unrelated to the session, generated/local-only, or unsafe to include, STOP and ask the user which paths to include. Do not push until the commit boundary is explicit.
• Stage the relevant session paths. Use git add -A only when every dirty path is relevant to the session; otherwise stage explicit paths.
• Create exactly one conventional commit before checking commits to push:

  git commit -m "<type>(dev): <description>"
  

  Pick type from the Commit Convention section (feat for feature work, fix for bug fixes, docs, test, refactor, or chore as appropriate). Use feat(dev): ... only when the accumulated solo work is feature-like.
• Record the commit SHA and continue with the normal push checks.

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)
# merge_op: "pr-merge-squash" if squash==true else "pr-merge-merge"
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.

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

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

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

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

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

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

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

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

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

3. Set waiting_for="merger". Wait for Merger's final verdict via wait_agent on codex_agents.merger.agent_id.

4. Persist the Merger report, call close_agent(target=<agent_id>), set codex_agents.merger.status="closed", clear teammates.merger, and clear waiting_for.

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

# Check for uncommitted changes
dirty=$(git status --porcelain)
# Check waiting_for in state
waiting=$(jq -r '.waiting_for' .bx-dev/<session-id>/state.json)
# Check last completed task count
task_count=$(jq -r '.task_count' .bx-dev/<session-id>/state.json)
# Check if brief exists (Scout was done)
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:

1. Implement what the user asks. No over-engineering, no unsolicited refactoring.
2. Read before edit. Understand existing code before changing it.
3. Run checks after changes — if the project has tests/linter, run them.
4. Stay on the session branch.
5. 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"**.