Round Flow

The shape of one task round, and what the lead does between the steps of skills/herdr-teamlead/SKILL.md. Read this when a round deviates from the happy path.

The Three Roles

Roles rotate between tasks. The rotation is decided by measured headroom through teamlead.sh plan, never by the lead's impression of who looks fresh. plan breaks a headroom tie on who has held the role fewest times, so nobody owns developer forever.

Step 5 in skills/herdr-teamlead/SKILL.md identifies the source for the default weights and assignment algorithm. Re-weigh from measurements: run measure before and after a round and read what the seat actually cost.

Fewer live workers than roles is an error, not a silent drop — a role nobody holds is work nobody is doing. Either name another agent into the roster or fold two roles onto one worker deliberately, in that worker's brief.

Two Phases

A task runs through the round twice, and only the second pass gates anything.

Phase 1 — pre-development (optional). The architect posts a design note on the issue (reviewer Mode A). The tester writes a plan mapping each acceptance criterion to a test, or delivers those tests as a patch (tester Mode A or B). The developer implements against both, runs the repo's gates, pushes the branch, and stops without opening a PR.

Skip Phase 1 for a change small enough that a design note would say less than the diff. Nothing in Phase 1 is a pass; it is preparation.

Phase 2 — post-push verification (mandatory). The reviewer reviews the pushed branch and posts a COMMENT review (Mode B). The tester runs the gates and the acceptance tests against that same branch (Mode C). Both report against the current tip by SHA.

The release hand-off reads Phase 2 reports and nothing else. A design note is not a review of the code that got written, and a test plan is not a test run.

Phase 2 plans with the author barred from the seats that judge its work: plan --exclude reviewer=<author> --exclude tester=<author>. The author keeps whatever seat is left to it — a bar that would strand another role is refused, naming the role and the exclusions, rather than quietly seating somebody to review their own branch.

One Round, End to End

1. Roster — roster.sh names the live workers. An unnamed pane has no dispatch handle; name it first.
2. Authority — verify-authority.sh <owner/repo> answers whether the operator owns the repo. Ownership is the namespace, never write permission, and the answer becomes the authority line in every brief.
3. Measure — teamlead.sh measure reads each worker's own usage numbers. A worker that is working or blocked is skipped with null windows rather than interrupted.
4. Plan — teamlead.sh plan --roles developer,tester,reviewer assigns the roles, with --exclude <role>=<agent> for every seat a worker must not hold. It contacts nobody and writes nothing.
5. Compose — compose-briefs.sh renders the templates from one values file, refusing to write anything when a placeholder is unfilled or a supplied key matches no template. The lead decides the values; the script decides nothing.
6. Provision — provision-worktree.sh creates every worktree the briefs name, from the shared checkout. A worker never runs git there, so its checkout has to exist before the brief arrives.
7. Dispatch — teamlead.sh apply uses Step 9's explicit context mode, then sends the assignment prompt. Only a same-role fix may retain context. It re-reads live status and refuses to type into a busy worker.
8. Wait — wait-report.sh <agent> <report-path> per worker, in the order the round needs them.
9. Gate — the lead reads every report in full and decides: another round, or the release hand-off.

Reading a Report

A report is the worker's only channel to the lead. Read all of it, every time — a ## BLOCKED section can sit under a report that otherwise reads as finished.

• Blocking findings present — take Step 11's bounded fix path under rules/agent-team-operation.md Fix Loops. Keep a stable task identifier and advance its fix counter; changing worker or scope never restarts it. Name the findings and prior report in each brief. Re-check the findings with scoped briefs, then run full verification before release.
• A ## BLOCKED section — the worker stopped on something it could not decide. Resolve it in the NEXT brief, which reaches it through a fresh dispatch. Never type the answer into the worker that is waiting.
• wait-report.sh exit 3 — the worker is at an approval or question dialog. Read the pane, relay the dialog text to the operator verbatim, and stop the round for that worker. The lead never answers it — an approval dialog is input, and input to a blocked agent is exactly what Dispatch Safety forbids. The operator answers; the wait resumes once herdr agent get <name> reports a state other than blocked.
• wait-report.sh exit 1 — the budget ran out. Read the pane before re-dispatching; a worker that is still working needs more budget, not a second copy of the same brief.

Why Phase 2 Runs Before the PR

The registry build's PR #27 went through 12 automated review rounds — policy reviewer plus Copilot — because the code reached the bots before the team's own reviewer and tester had seen it. Each round cost a full CI cycle and a context reload on the developer.

A plain branch push does not trigger the policy reviewer. That gap is the opening: the developer pushes the branch and stops. The tester and the reviewer run against the pushed branch, the developer folds their blocking findings in, and only then does the PR open — so the bots review work the team has already agreed on, and the usual outcome is one round instead of twelve.

The hand-off is therefore split around the bots:

• Developer runs Skill(skill: "release") Steps 1–4 — readiness, PR, version reasoning, and the review request.
• The bots review once.
• Developer runs Steps 5–7 — watch the reviews, act on blocking findings, merge and clean up.

The lead releases nothing until it holds a reviewer Mode B report and a tester Mode C report against the SHA the developer pushed. A newer push invalidates both: re-run Phase 2 against the new tip.

Shared-Account Reviews

The workers share one GitHub account, and GitHub refuses APPROVE and REQUEST_CHANGES on that account's own PR. Internal reviews are posted as COMMENT reviews with each finding labelled blocking or advisory per rules/review-severity.md. The COMMENT state carries no gate, so the LEAD is the gate: a blocking finding in an internal review sends the round back, whatever GitHub's merge box says.

The Judge

A fifth seat, outside the three-role rotation, on the most capable model available. It never holds developer, reviewer, or tester. rules/agent-team-operation.md Judge Seat is the contract; this section is the operational detail for Steps 12–18 of skills/herdr-teamlead/SKILL.md.

Dispatch it on exactly one of four triggers:

• A contested reviewer or tester verdict — one worker's finding, another worker's (or the lead's) disagreement, neither side able to settle it by re-reading the rule.
• A lead override of a blocking finding — the lead about to waive a finding a worker labelled blocking gets a second, independent read first.
• A fix loop exhausted its cap without approval — the judge rules before any further action. If the ruling requires more implementation, Step 18 reports BLOCKED to the operator rather than dispatching another fix.
• A bot finding the team disagrees with — the policy reviewer or Copilot flags something the developer and reviewer both think is wrong.

It is read-only without exception: no file edit, no mutating git or gh command, no GitHub post, no subagent dispatch. It reads both positions and the governing rule, verifies the disputed facts against the tree itself rather than trusting either side's framing, and returns a report opening with three lines — RULING: uphold A | uphold B | amend — <line> | blocked — <question>, ACTION: naming the minimal step, UNVERIFIED: naming anything it could not check — followed by its numbered reasons.

blocked is the judge declining to rule on a dispute it cannot settle from the tree and the rule text alone. The round stops there and the named question goes to the operator. The lead does not dispatch a second judge and does not rule in its place.

The ruling binds the round the moment the lead reads it. Only the operator overrides one; record the override and why in the round log.

The judge worker is declared in the main config.json and is measured and planned like every other seat, but its seat is pinned rather than ranked: the judge block names the agent, model and effort, the planner never chooses who judges, and the pinned worker never holds another seat.

It runs on the same Claude subscription as the claude worker, so both declare the same window_group and the planner charges a seat's cost against every worker sharing that window. When that window is exhausted the round halts: there is no substitute judge, no fallback to another vendor's flagship, and no degraded ruling.

What the Lead Never Does

• Edit the shared checkout. The lead reads it and dispatches; workers write.
• Answer a question by typing into a working worker. Wait for the report.
• Answer a blocked worker's approval dialog. Relay it to the operator and stop.
• Create a worktree for a worker after dispatch. Provision before briefing.
• Write an authority line by hand. It comes from verify-authority.sh.
• Brief a write action on a repo the operator does not own without their explicit per-repo, per-action permission recorded in the brief.
• Release on a Phase 1 report. A plan is not a verification.
• Treat a single idle or done observation as completion.
• Merge on a worker's behalf. The developer runs the release skill.
• Act against a judge's ruling, or seat the judge on developer, reviewer, or tester. Only the operator overrides a ruling.