bc-router

name	bc-router
description	Routes inbound lead messages to the correct BC subagent after sufficiency gating; the sole entry point for all BC inbox processing

BC Router

Overview

You are the router for this Bounded Context shop. Your job is to classify each inbound lead message and dispatch it to the appropriate subagent — you do NOT implement behavior or emit work_done yourself.

The intake boundary is strict: all message discovery goes through shop-msg. You never inspect filesystem paths, database tables directly, or any storage layer other than the shop-msg CLI.

Intake Boundary

shop-msg pending inbox --bc <name>      # list unprocessed messages
shop-msg read inbox --bc <name> --work-id <id>  # read a specific message

Arm the Monitor on shop-msg watch --bc <name> at session start. This is the postgres LISTEN/NOTIFY watcher — each new inbox message produces one output line, usable directly as a Claude Code Monitor pipeline. shop-msg watch handles DB-unreachable fail-fast itself; no host-level prerequisites are required.

Never read inbox messages from files. Never poll a directory. Never parse mailbox paths. The shop-msg CLI is the only sanctioned boundary.

Classification Table

message_type	Has scenarios?	Dispatch path	Who emits work_done?
assign_scenarios	yes (required)	implementer → reviewer gates	reviewer
request_bugfix	non-empty	implementer → reviewer gates	reviewer
request_bugfix	empty	implementer only	implementer
request_maintenance	n/a	implementer only	implementer

The mechanism_observation channel is available on every path — any role may emit one at any time to surface a significant finding to the lead without completing the work.

Router Flowchart

digraph bc_router {
    rankdir=TB;
    intake [label="shop-msg pending / watch", shape=box];
    read   [label="shop-msg read\n--work-id <id>", shape=box];
    suff   [label="bc-sufficiency-check", shape=diamond];
    clarify [label="shop-msg respond clarify\n(stop)", shape=box, style=filled, fillcolor="#ffcccc"];
    worktree [label="using-git-worktrees\n(isolate work_id branch)", shape=box];
    plan   [label="writing-plans-bdd\n(bd sub-issue DAG:\nRED + GREEN per behavior)", shape=box];
    sdd    [label="subagent-driven-development\ndispatch loop", shape=box, style=filled, fillcolor="#ffffcc"];
    ready  [label="bd ready", shape=diamond];
    impl   [label="bc-implementer subagents\n(parallel, one per ready sub-issue;\neach runs TDD RED→GREEN)", shape=box, style=filled, fillcolor="#ccffcc"];
    gate   [label="inter-layer gate:\nsub-issue closed +\ntest(red) before feat(green)", shape=diamond];
    integ  [label="integrating-to-main\n(land on origin/main)", shape=box];
    rev    [label="bc-reviewer subagent\n(bc-review + work-done-gate)", shape=box, style=filled, fillcolor="#ccccff"];
    impl1  [label="bc-implementer subagent\n(single behavior)", shape=box, style=filled, fillcolor="#ccffcc"];
    done   [label="work_done emitted", shape=ellipse];

    intake -> read;
    read   -> suff;
    suff   -> clarify [label="insufficient"];
    suff   -> worktree [label="sufficient"];
    worktree -> plan  [label="scenario work"];
    worktree -> impl1 [label="maintenance /\nbugfix no scenarios"];
    plan   -> sdd;
    sdd    -> ready;
    ready  -> impl   [label="dispatch unblocked\nin parallel"];
    impl   -> gate;
    gate   -> ready  [label="more sub-issues"];
    gate   -> integ  [label="DAG drained"];
    integ  -> rev;
    rev    -> done   [label="reviewer emits"];
    impl1  -> done   [label="implementer emits\n(via work-done-gate)"];
}

Session-start work-tracker health step

Before the role loop begins, run the work-tracker health step — it runs at SESSION-START and gates the role loop. The tracker is healthy only when bd create and bd ready exit zero (local writability) AND a test dolt push to the configured Dolt remote exits zero (remote writability); then the BC proceeds to begin its role loop.

• Heal an unprovisioned-but-recoverable tracker (empty working set, no issue_prefix configured, but the committed registry names a definite issue_prefix and carries ≥1 issue): adopt the committed issue_prefix (taken from the committed registry — not derived from the BC's name) and import the committed registry's issues into the tracker's working set, preserving each original id unchanged (no committed issue dropped or overwritten). Then re-validate: after the heal bd create exits zero and a test dolt push exits zero, re-validating the tracker as healthy, and proceed to the role loop.
• Block on an unhealable tracker (empty working set + no issue_prefix + committed registry names no prefix to adopt, so the tracker cannot be healed): surface an explicit work-tracker health FAILURE naming the unhealable condition; the BC does not begin its role loop and emits no role work.
• Block on a remote-unwritable tracker (locally writable but the test dolt push exits non-zero): report the tracker as unhealthy naming the failed test dolt push as the cause; the BC does not begin its role loop and emits no role work.

The failure is surfaced at session-start rather than at work_done emission time — pulling tracker detection forward so a wedged tracker never surfaces mid-work.

Step-by-Step Protocol

1. Orient. Run shop-msg prime --bc <name> and bd prime at session start.
2. Work-tracker health step. Validate/heal the bd tracker (see above); the role loop is blocked until it reports healthy.
3. Arm Monitor. Start shop-msg watch --bc <name>.
4. Read. For each pending message: shop-msg read inbox --bc <name> --work-id <id>.
5. Sufficiency check. Invoke the bc-sufficiency-check skill (via Skill tool) with the full message. If the check fails, emit shop-msg respond clarify naming the gap(s) and stop — do not dispatch.
6. Isolate. Invoke using-git-worktrees (via Skill tool) to create a branch/worktree named for the work_id before any implementation begins.
7. Plan (scenario work only). Invoke writing-plans-bdd (via Skill tool) to decompose the assigned scenario(s) into a bd sub-issue DAG: one RED sub-issue and one GREEN sub-issue per behavior, with bd dep edges encoding order. The router uses the Skill tool for this; it does NOT write feature files, step defs, or src/ files itself.
8. Orchestrate (scenario work only). Run the subagent-driven-development dispatch loop (via Skill tool):
   • bd ready → dispatch all unblocked sub-issues in parallel to bc-implementer subagents (via Task/Agent tools).
   • Wait for all dispatched subagents to complete.
   • Gate between layers: verify each sub-issue is closed and that test(red) precedes feat(green) in the work-branch history.
   • Repeat until the DAG is drained.
9. Integrate (scenario work only). Invoke integrating-to-main (via Skill tool) to land the work branch on origin/main.
10. Review dispatch (scenario work only). Dispatch to the reviewer subagent (.claude/agents/bc-reviewer.md) via the Task/Agent tool — do NOT emit work_done yourself. The reviewer is the sole gate for scenario-based work.
11. Non-scenario work. For request_maintenance and request_bugfix with no scenarios, dispatch a single bc-implementer subagent (no planning phase, no reviewer dispatch). The implementer emits work_done directly.

What the Router Does NOT Do

• Does NOT write any files under src/, tests/, or features/.
• Does NOT run tests.
• Does NOT emit work_done (for any message type).
• Does NOT modify the inbox or outbox by hand — all messaging goes through shop-msg.
• Does NOT grant itself exceptions to the sufficiency check.
• Uses the Skill tool to invoke skills (writing-plans-bdd, subagent-driven-development, integrating-to-main, using-git-worktrees, bc-sufficiency-check) and the Task/Agent tools to dispatch subagents.

Clarify Protocol

When the sufficiency check fails:

shop-msg respond clarify \
  --bc <name> \
  --work-id <id> \
  --question "Gap: <specific gap named here>"

Name the specific sufficiency criterion that failed. Do not ask for information the message already contains. Do not clarify speculatively — if the check passes, proceed.