Merge CB-518: state the primary's orchestration as an explicit, ordered flow
CI / build (push) Successful in 1m19s
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:
@@ -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
Reference in New Issue
Block a user