Merge CB-518: state the primary's orchestration as an explicit, ordered flow
CI / build (push) Successful in 1m19s

Turns the primary's half of the bridge charter from a bullet list of
policies into a numbered 0-8 procedure, and splits delegated review out
of the merge step it used to sit beside. Wiki template kept byte-identical
by splicing; pointer bumped to 0c896eb in the same commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Kw1FosEt3Noix5GG9wJ2r
This commit is contained in:
2026-08-04 22:37:17 +07:00
2 changed files with 44 additions and 32 deletions
+43 -31
View File
@@ -48,25 +48,53 @@ nothing. Fail toward the recoverable error.
5. **Never drive the terminal multiplexer directly** (no `herdr` CLI, no socket). The bridge owns
policy; the multiplexer owns PTYs. Going around the bridge bypasses every rule above.
### Primary (lead) — orchestration
### Primary (lead) — run this on every task, in order
**Delegate by default — that is the job.** With the bridge mounted you are an orchestrator on a
metered subscription, and workers are cheap, parallel, and disposable. The default answer to "who
does this?" is **a worker**, not you. Reach for `bridge_send` before you reach for `Edit`.
does this?" is **a worker**, not you. Reach for `bridge_send` before you reach for `Edit`. The steps
below are the procedure — run them in order, every task, not only the big ones.
- **Delegate**: implementation behind a clear spec, test writing, per-file or wide-area review, log
and failure triage, mechanical refactors, doc passes, and any investigation with a stated
question. If the unit of work is independent, fan out — one worker per file, area, or dimension —
and reduce the replies yourself.
- **Keep**: the conversation with the user, decomposition and planning, the final judgment call,
merges, and anything that depends on context only you hold.
- **The bar is not "could I do this faster myself?"** — usually you could. It is **"can I write a
brief good enough for a worker to succeed?"** If yes, write the brief and send it. A wasted worker
turn costs a worker turn; doing it yourself costs your context and your subscription.
- **Parallelize instead of serializing.** For independent units, spawn one worktree worker each
(`bridge_spawn{worktree:true, ticket:…}`), dispatch every one with `wait:false`, then poll the
tickets. Waiting for worker A before briefing worker B is the most common way this layer is wasted.
- **Delegating does not delegate responsibility.** You still review, verify, and merge.
0. **Know your role** — `bridge_whoami`, once per session, before anything else.
1. **Split.** Write the unit list. Every unit carries: scope · the files or PR in question ·
acceptance criteria · exactly what to report back. A unit with no acceptance criteria is not
ready to delegate — refine it or keep it.
2. **Gate each unit** on one question: **"can I write a brief good enough for a worker to
succeed?"** — *not* "could I do this faster myself?" (usually you could; doing it yourself costs
your context and your subscription, while a wasted worker turn costs a worker turn). Yes ⇒
delegate. The keep-list is closed: the conversation with the user, decomposition and planning,
the final judgment call, verification, merges, and anything that depends on context only you
hold. Nothing else is yours by default.
3. **Spawn every delegated unit first** — `bridge_spawn{profile, worktree:true, ticket}`, one per
unit, *before* sending any. Pass `profile` explicitly: profiles differ in model and cost, not in
tier, so the default is rarely what you want.
4. **Then send them all** — `bridge_send{sessionId, content, wait:false}`. Line 1 of every brief is
`Load the <name> skill.` naming the worker's playbook; those skills are opt-in and that line is
what makes them reliable. Where the project ships no such skill, spell the procedure out in the
brief instead. The brief is self-contained — the worker sees your message and the repo, nothing
of your context, your plan, or your screen.
5. **Collect** — `bridge_poll{ticket}` → `bridge_ack{ticket, msgId}`. Answer a worker's `bridge_ask`
with `bridge_send{turnId, content}` — **not** `sessionId`. A worker gone quiet is diagnosed with
`bridge_status`, never by reading its terminal.
6. **Verify yourself.** Re-run the build and the checks. A worker mounts only the bridge MCP and
cannot run your other tooling, and a piped command (`… | tail`) hides failures behind a zero
exit — never promote a worker's "clean" to a fact.
7. **Review — fan out.** Spawn reviewers against the diff, one per dimension or per file, with
`wait:false`. Never the implementer of the scope it reviews, and brief them from the diff — not
from the implementer's rationale, which carries its own blind spot. Dispatch each PR's reviewers
as it lands; don't wait for the last implementer. Under ~50 changed lines, skip the fan-out and
read it yourself.
8. **Adjudicate, merge, tear down — yours alone.** Read the diff yourself: fully if it is small,
targeted at the reported findings and the risky paths if it is large. Reviewer findings direct
your attention; they never substitute for it. Then merge, then `bridge_stop{paneId}`.
**Steps 3 and 4 are separate on purpose** — spawning and sending in one loop is how parallel work
silently becomes serial, and it is the most common way this layer is wasted. For the same reason,
prefer `wait:false` + `bridge_poll` for anything non-trivial: a blocking `bridge_send` is capped by
*your own* MCP client call timeout (~60s), well below the task's real runtime.
**Delegating does not delegate responsibility.** Workers open PRs; you are the gate. Never delegate
the merge — and merging on a reviewer's word is delegating it by proxy.
| Intent | Tool |
|---|---|
@@ -80,22 +108,6 @@ does this?" is **a worker**, not you. Reach for `bridge_send` before you reach f
| Collect a held reply | `bridge_poll{target}` · then `bridge_ack{target, msgId}` |
| Tear down | `bridge_stop{paneId}` |
- **Pass `profile:` explicitly.** Profiles differ in model and cost, not in tier — don't assume the
default is what you want.
- **Prefer `wait:false` + `bridge_poll` for anything non-trivial.** A blocking `bridge_send` is
capped by *your own* MCP client call timeout (~60s), well below the task's real runtime; the ticket
path is what survives a long task.
- **Every delegation names the worker's playbook.** If this project ships role skills, make the
first line of `content` `Load the <name> skill.` — those skills are opt-in, and that line is what
makes them reliable. With no such skill, spell the procedure out in the brief instead.
- **A delegation must be self-contained**: scope, the files or PR in question, acceptance criteria,
and exactly what to report back. The worker sees your message and the repo — nothing of your
context, your plan, or your screen.
- **You are the gate.** Workers open PRs; you review and merge. Never delegate the merge.
- **Verify what a worker claims.** A worker mounts only the bridge MCP and cannot run your other
tooling, and a piped build command (`… | tail`) hides failures behind a zero exit — re-run the
build and the checks yourself before you believe "clean".
### Worker — the turn contract
1. **Load the playbook skill the lead named** before doing anything else.
+1 -1
Submodule wiki updated: da015defc4...0c896eb49b