Agent Coordination Playbook

This folder documents David's multi-agent collaboration model: several agents can work in parallel, but one coordinator filters the room, answers non-owner questions, and escalates only the decisions that genuinely need David.

Skills: This playbook is operationalized as field cards in skills/. Run /coordinator to act as the single coordinator; /coord-worker --id=<project>-<role> --role=worker --lane=<lane> --project=<p> --room=<p> --repo=<path> to join as a lane owner (every card takes the same signature: --id --role --project --room[s] --repo [--lane]); /coord-aide to act as David's comms point & planning buddy (Queue/roadmap); /coord-qa to act as the independent quality gate; or /coord-ci (cheap model) to operate the release pipeline. All join the coord MCP bus over tmux and follow this protocol automatically; the coordinator hands the right skill to each agent on onboarding.

| anchor | slice | words | |---|---|---| | §install | install.md | 106 | | §install-quick | install.md | 143 | | §fleet | fleet.md | 649 | | §goal | roles.md | 54 | | §role-model | roles.md | 428 | | §roles | roles.md | 133 | | §aide | roles.md | 1092 | | §qa | roles.md | 810 | | §ci | roles.md | 190 | | §express | express.md | 624 | | §rooms | rooms.md | 421 | | §rooms-orientation | rooms.md | 1044 | | §naming | naming.md | 451 | | §bus-prefixes | bus.md | 1060 | | §bus-relay | bus.md | 279 | | §coord-duties | coord-loop.md | 80 | | §coord-execute | coord-loop.md | 445 | | §context-topology | context.md | 350 | | §audit | audit.md | 421 | | §board-queue | board-write-rules.md | 1325 | | §facts | facts-protocol.md | 357 | | §context-reset | context.md | 402 | | §context-phase | context.md | 131 | | §context-history | context.md | 226 | | §bus-tokens | bus.md | 1538 | | §handoff | handoff.md | 315 | | §handoff-david | handoff.md | 193 | | §david-requires | david.md | 152 | | §david-maturation | david.md | 300 | | §david-alert | david.md | 467 | | §david-packet | david.md | 322 | | §david-status | david.md | 41 | | §worktrees | worktrees.md | 991 | | §gates-merge | gates.md | 2009 | | §delivery | delivery.md | 1837 | | §handoff-dead | handoff.md | 272 | | §release-cutover | release.md | 132 | | §mutate | mutate.md | 750 | | §board-verbs | board-write-rules.md | 629 | | §board-accuracy | board-write-rules.md | 630 | | §routing-flow | routing.md | 476 | | §verify | verify.md | 25 | | §verify-worldstate | verify.md | 594 | | §verify-controls | verify.md | 847 | | §verify-reporting | verify.md | 1284 | | §verify-population | verify.md | 3887 | | §verify-closure | verify.md | 874 | | §verify-instruments | verify.md | 4211 | | §verify-wording | verify.md | 1997 | | §verify-baselines | verify.md | 921 | | §verify-tests | verify.md | 2308 | | §gates-money | gates.md | 489 | | §release-ci | release.md | 698 | | §release-flow | release.md | 668 | | §routing-capability | routing.md | 407 | | §release-gap | release.md | 56 |

Skills & Installation

The eight field cards live in skills/<role>/SKILL.md. This README is the canonical essay. Heading-level slices live in skills/references/ and install to ~/.claude/groundwork-playbook/ — never under ~/.claude/skills/. Each card ships at most two hot-path slices in references/.

• skills/coordinator/ — field card; hot path: board-write-rules.md, bus.md
• skills/coord-worker/ — field card; hot path: verify.md
• skills/coord-aide/ — field card; hot path: board-write-rules.md
• skills/coord-qa/ — field card; hot path: gates.md
• skills/coord-ci/ — field card; hot path: express.md
• skills/coord-fleet/ — field card + scripts/coord-claude-layout.sh; hot path: fleet.md
• skills/coord-handover/ — field card; hot path: handoff.md
• skills/coord-audit/ — field card; hot path: audit.md

Quick install

Install or re-sync all 14 skills into the global harness homes — no clone needed:

npm i -g agent-coordination
agent-coordination install            # install or refresh
agent-coordination update             # alias — re-sync in place
agent-coordination install --dry-run  # preview only, change nothing
agent-coordination install --harness=claude,grok,cursor,vscode,opencode

Requires Node ≥18. Defaults install every harness. Claude: ~/.claude (CLAUDE_HOME). Grok Build: ~/.grok/skills/ + essay ~/.grok/groundwork-playbook/ (GROK_HOME); Grok also reads ~/.claude/skills/ via compat, but the Grok cards use agent-coord__* tool names, not Claude's mcp__<server>__* spelling. After install, invoke the field card (/coordinator, or tell Grok to act as coordinator).

OpenCode: auto-discovers ~/.claude/skills/<name>/ or the copy at ~/.config/opencode/skills/<name>/. Frontmatter stays name + description only — OpenCode rejects other top-level keys (allowed-tools etc.; put extras under metadata: or in the body). The installer rewrites MCP tool-name placeholders ({{tool:list_agents}}, {{tools:agent-coord}}) per harness, so committed field cards stay harness-neutral.

Fleet Bootstrap & Layout

Every project fleet starts the same way, with the same window names, geography and colors — so anyone (David or an agent glancing at a screen) can read any fleet at sight. This is canonical: don't improvise per-project layouts.

Standard window layout (role-named windows; agreed with the console's provision.ts 2026-08-22 — one scheme, two implementations):

<project>-coordinator   one pane (your --self-coordinator pane, renamed)
<project>-aide          one pane
<project>-qa            one pane
<project>-ci            one pane (absent when the fleet runs without ci)
<project>-workers       N even vertical panes (worker-1 … worker-N)

Window names carry the plain project (windows are per-machine, like rooms); agent ids and worktrees keep the <project>-<owner> fleet prefix. A consumer must not assume all five windows exist — optional roles simply have no window.

Role → color map (applied twice: tmux pane-border title color, and /color inside each Claude session):

| Role | Color | |---|---| | coordinator | green | | aide | pink | | qa | yellow | | workers | blue |

Two ways to launch:

1. One-call (preferred): David opens a single claude in the project repo (inside tmux, fresh window) and invokes /coord-fleet [N]. That session cascades into the coordinator (invokes /coordinator itself), infers the project name, agent ids, and #room from the repo basename (sanitized to the id convention, collision-checked against live agents/rooms on the bus — it stops and asks David on any clash rather than squatting), then runs the launcher in --self-coordinator mode to scaffold aide/qa/workers around itself.
2. Script-direct: run the launcher yourself from the agent-coordination repo:

scripts/coord-claude-layout.sh <N> --project=<name> --repo=<path> [--lanes=a,b,c] [--frame-only] [--self-coordinator] [--wait=s]

It builds the window, styles the borders, launches claude in every pane, and injects each role's skill invocation (/coordinator, /coord-aide, /coord-qa, /coord-worker — all with the common --id --role --project --room[s] --repo [--lane] signature) plus its /color. Agent ids follow the <project>-<role> convention automatically.

Rules:

• Bootstrap starts with David. Agents never scaffold a fleet on their own initiative — David either runs the script or invokes /coord-fleet in the one session he opened (his invocation is the authorization; sessions cost real money). After bootstrap, the coordinator onboards whatever appears on the bus.
• One fleet per project per machine. The launcher refuses if ANY of the five role windows already exists (strict-create; the error names the kill commands). The console's spawn path instead reuses a role window whose panes are the fleet's own, and refuses on a foreign collision — never silent suffixing.
• --frame-only builds panes + colors without launching sessions (for re-attaching existing agents or manual starts).
• Workers' lanes default to worker-i; pass --lanes= when lane names are known up front, otherwise the coordinator assigns lanes at onboarding as usual.
• A seed that cannot name its agent must fail loudly, not start mute. Any seeding path that templates an agent id — a hand-rolled prompt, a spawn script, a UI, anything other than the bundled launcher, which interpolates ids directly in shell and has no placeholder to leave behind — must refuse to start if a placeholder survives substitution. An unsubstituted id would be a total, silent loss of outbound comms: the agent binds no identity, so send_message/post_status are unavailable, while inbound still arrives over an existing pusher — it reads every instruction, can answer none, and presents to the coordinator as ordinary idleness. Convert the convention into a loud failure — an agent that cannot identify itself should refuse to run rather than run mute. (Stated as a principle, not from a confirmed instance: the field case that motivated it — a worker mute for a whole session, 28 minutes of two lanes blocked — is established as an agent started outside the standard path, but the placeholder mechanism was a relayed self-report and no placeholder was ever found on disk. See LESSONS #34/#34b: the effect is evidence, the mechanism is not.)

Goal

Reduce raw chat load while keeping the benefits of multiple specialist agents:

• repo owners keep implementation authority for their repos
• reference agents review domain-specific risks
• the coordinator keeps shared state, routes work, and prevents stale or duplicate asks
• David receives compact decision packets instead of the full room firehose

Role Model

| Agent | Role | | --- | --- | | Coordinator | Executes: turns plans into routed work and gets them landed. David's coordination layer and chief-of-staff. Filters room traffic, answers non-David questions, escalates real decisions, maintains the live board, and tracks quality/product/cutover risk. | | Repo owner | Owns one repository or service. Has implementation authority for that repo's branches, PRs, tests, deploy readiness, and local contract. | | Consumer owner | Owns the downstream consumer of another service. Reviews contract compatibility and user/product impact. | | Reference/advisory agent | Provides domain reference, source-system behavior, risk review, pricing/cost knowledge, or legacy implementation context. Does not mutate live production systems unless explicitly authorized. | | Infrastructure owner | Owns shared coordination tooling, chat delivery, CI/CD infrastructure, or deployment primitives. | | Aide | Plans, in PRODUCT terms — what David is trying to achieve, for whom, what is worth doing next. David's comms point — the one agent David talks to. Forwards the coordinator's decision packets to David; curates docs/QUEUE.md (priority/wording/scope — the coordinator closes items) and owns the roadmap; turns David's asks into queued items or roadmap phases. Quiet channel; never executes code. (Skill: /coord-aide.) | | QA / reviewer | Validates quality AND challenges the choices — the only role chartered to contradict a plan, which is a different duty from gating a diff. Standing independent quality gate. Listens for DONE:, runs the gate, issues cited PASS/FAIL verdicts. Reviews others' code, never its own; with a CI operator present it never merges. (Skill: /coord-qa.) | | CI operator | Executes the pipeline and judges nothing — it merges on a verdict someone else issued. Zero-judgment executor on a cheap model. Executes merges on QA's PASS verdicts, squash-verifies, watches the merge→qa deploy, posts telemetry, chases tier-2. Bounces all judgment (conflicts→worker, red pipelines→coordinator, prod→David). (Skill: /coord-ci.) | | Architecture auditor | On-demand, read-only measurement instrument. Checks the tree against DECISIONS/ARCHITECTURE_GUIDE/STACK_MAP (rule conformance), reports mechanical duplication/boundary/leftover findings, docs-vs-code drift, and friction stats from bus+git — cited, to the coordinator (queue candidates). Does not judge whether the architecture is good; design opinions go to David as questions. Never fixes, gates, or merges. (Skill: /coord-audit.) | | Automation (groundwork-console) | Mechanical watcher. Detects seam/bus events and may send_message with a playbook prefix (FYI: / AGENT_ACTION: / RISK:). Never edits seam files, never gates, never merges. Frozen role id automation — not a gate-runner, cannot emit verdict / go / scope. | | david | Human owner. Decides on authority, credentials, production risk, scope, priorities, and process changes. |

Aide, QA & CI Roles

Three specialist roles peel load off the coordinator's busiest seams — the David-facing channel, the quality gate, and the release pipeline. All are optional: a small project runs without them and the coordinator absorbs the jobs. Each ships as its own skill (/coord-aide, /coord-qa, /coord-ci) and defers to this playbook for the shared bus/room/prefix/noise protocol, so the skills stay thin. (The aide has been renamed twice — "backlog curator" → "liaison" → aide, each time because the name pulled agents toward the wrong half of the job: "curator" read as queue clerk, "liaison" read as pure relay and understated the planning partnership. Running fleets may still hold <project>-curator or <project>-<owner>-liaison ids until the server reloads; the aide answers to all three, and self-migrates with rename_agent per §Agent Naming.)

Aide — David's comms point & planning buddy

The aide is the one agent David talks to — his comms point and planning buddy, his delegate with a deliberately narrow surface. The division with the coordinator is by facing, not content: the aide faces David; the coordinator faces the fleet and organizes the work. (The earlier content split gave both roles a David-facing mandate and produced real turf fights — LESSONS #16.)

• Comms topology — David ↔ aide ↔ coordinator ↔ fleet. All conversational agent→David traffic flows through the aide: the coordinator composes DAVID_DECISION: packets and DMs them to the aide, which forwards to david verbatim (the UI still parses the card; planning context goes around the packet, never inside it). Questions, reports expecting a reply, priority discussions — same path. Exactly two sanctioned bypasses: (1) BLOCKER fast-path — production-fire BLOCKER: goes coordinator→David directly (latency + single-point-of-failure safety), cc the aide; (2) dock telemetry — non-interrupting RISK:/DONE: dock DMs go coordinator→David's UI directly: a notification feed, not conversation; relaying it would make the aide the noise sink.
• Noise gradient — coordinator loud, aide quiet. (Prose on purpose. This rule already existed, was well-reasoned, and still failed to bind — and no mechanism was found that distinguishes a digest from a relay without reading the message. Recorded as a deliberate decision under ADR-014 rather than left as an item nobody mechanized.) The coordinator is the noise sink: it watches the rooms and absorbs fleet chatter. The aide is the quiet channel: it gets filtered digests from the coordinator, not the room firehose, so David's messages never compete with fleet traffic. It may read the project room passively/on-demand (peer cross-correction stays valuable) but does not monitor it.
• David's inbound asks default to the aide — planning and execution. Planning it handles; execution it forwards to the coordinator (normally as a Queue item; urgent → a tagged direct DM). Delegate, not bottleneck: forward fast, never sit on execution asks.
• What it owns: docs/QUEUE.md (the inbound queue file) and the roadmap. Minor ask → a Queue item; major → open/plan a roadmap phase and reference it from the Queue (the human-facing front of the plan-phase → BACKLOG planner seam).
• It is David's proxy for the queue — but ownership splits by ACTION, not by file. Assigning the file to one role left the verb prune with no owner at all, and the cost was measured: four merged items sat open and twelve merges went 23 hours unlogged in docs/DONE.md, because each writer could reasonably read the other as responsible. Note the mechanism, which is the transferable part — the coordinator read both rules, could not reconcile them, and resolved it by doing less. A wrong rule gets challenged; a contradiction gets absorbed silently. So:
  • AIDE curates — priority, wording, whether an item belongs in the queue at all, whether it is really one item. It is David's proxy for what the queue says.
  • COORDINATOR closes — prunes items a merge has satisfied, sets item status, writes docs/DONE.md. It sees merges land, so closing is a consequence of landing rather than a thing anyone must notice.
  • With no coordinator in the fleet, the aide does both. State the fallback or it becomes the same unowned verb one role down; a fleet with an aide and no coordinator is common (it is how most start).
  • Still one writer per edit: neither role rewrites the other's field on the same item.
  • And the write goes through the VERB that owns the file, not through the editor. queue_write files, amends, reprioritises and retags a row; land writes the closure across the queue row and docs/DONE.md; claim writes the board row at claim time. The verb takes FIELDS and never markdown, so it owns the grammar; it mints and stamps the id; it refuses a write whose base moved instead of clobbering the other writer; and it refuses multi-line text, because queue.v1 is one line per item and every parser drops a continuation silently. Hand-editing reproduces all four by hand and more weakly — measured 2026-09-15: a row appended directly needed stamp-queue-ids.mjs afterwards to acquire an id, and carried a literal ⟨q-…⟩ into body prose, which is the occurrence-vs-position defect this playbook has filed repeatedly. op:'amend' re-normalises an existing row without changing its id, so a row already cited elsewhere can be routed back through the verb after a hand edit.
  • Direct editing is the exception, and it is the route only where no verb covers the write — the board's transitions after claim (land has never touched the board), the roadmap, docs/DECISIONS.md, and the phase docs. There, and only there: write atomically (temp file + rename) and re-read before writing. (David's ruling, 2026-08-22, re-ruled 2026-08-26.)
• It plans and relays; it does not execute. The aide never owns a code lane, opens a code worktree, or merges. One writer to David's attention, one writer to the Queue; the coordinator drains in parallel.
• Narrow interface — the aide is not a routing target for the fleet. Inbound: David and the coordinator. Outbound: David, the coordinator, and the queue/roadmap files — nothing else. Workers and QA do not @-mention or DM the aide; findings flow worker/QA → coordinator → (filtered) → aide, the coordinator deduping and filtering before anything reaches the queue.
• Route-once — one path per queue candidate: coordinator → aide, exactly once; the coordinator's relay is authoritative, not redundant; workers and QA surface a candidate to the coordinator and stop. Dual-path routing produced duplicated tokens and crossed queue writes in the field — LESSONS #15.
• Lane disputes between aide and coordinator go to David as ONE joint decision packet — never competing DMs. The aide's authority is David's channel and the queue; the coordinator's is the fleet and the board — and the board is a WRITE authority: docs/WORKSTREAMS.md is the coordinator's file and nobody else writes it.
• Deputized mode — explicit, temporary execution. Under deadline pressure David may direct the aide to do hands-on work itself (install runtimes, write seed scripts, probe APIs). That is a feature, not a violation, when it is explicit and temporary: only on David's direct instruction; the aide announces AGENT_ACTION: deputized — <task> in the project room so the coordinator knows the lane exception exists; it still never merges, runs the gate, or takes a code lane on the coordinator's board; a mission refresher (or task completion) returns it to planning-only. Undirected drift into execution remains a role violation.

QA — the quality gate

The QA agent is a standing, independent reviewer that turns the quality gate into a role instead of a coordinator chore.

• What it does: listens for cited DONE: completions, runs the gate — by default mode: ci-trusted (required CI green on the exact head, narrow checks on the touched files, an independent behavior check against real input, a scope / .skip / .only audit, security-critical paths) and mode: full-local (adds the build and the real test suite) only for the risk classes under Gate-split —, and issues a cited PASS/FAIL verdict. With a CI operator present, the verdict is QA's whole output — ci executes the merge; on FAIL it reports to the coordinator, which routes back to the owning worker.
• Independence is the invariant: whoever merges did not author the change. QA reviews workers' code, never its own. With ci holding the merge button, the separation is structural: QA never merges, so it may fix trivial nits freely without a forfeiture dance.
• Without a CI operator (fallback rules): QA merges on pass — and then the forfeiture rule applies: touch the code (even a nit) and QA loses merge authority on that PR; the coordinator or a second reviewer merges. No QA at all → the coordinator runs the gate itself.
• Verdict freshness: a PASS is bound to the PR head it reviewed — new commits void it (ci checks headRefOid before executing).
• A new head voids the verdict, not the review. When the author pushes, the reviewer who already holds the context checks the delta since the reviewed head and re-issues the verdict on the new head; a second independent chain re-pays the whole review for one changed hunk and adds a merge race between the two. The exception is the money / high-risk fan-out gate, which is independent by design. (cass 2026-10-10: "reuse that ONE review ... without second QA / root gate".)
• The gate is single-threaded, so cut the cost of each gate — do not add gate agents first, and never lower the bar silently. One QA agent gating 34 PRs in a day is the critical path. "Let the queue grow" kept the bar but did not keep the fleet moving: over the last 150 merged PRs here the median open-to-merge is 37 min but the p90 is 17 h, and on cass parallel local suites drove the shared host to load 105 and a 4h40m fleet stall. A deep queue still creates pressure toward lighter passes, which is why the order below is fixed. When the queue is the constraint: (1) ci-trusted for everything outside the full-local classes, (2) the Heavy-work lock so gates stop contending for the host, (3) derived-file checks move post-merge (Post-merge main gate), and only then (4) a DAVID_DECISION: about a second gate agent. Depth is scaled by risk, never by backlog length, and a cheaper gate is never silent: every verdict states its mode, so a relaxed gate reads as policy and not as omission (LESSONS #25, #66).
• A PASS may not carry an author-actionable advisory — if the first line is a hold, the verdict is a hold. "PASS, but please fix X before merge" reads as PASS to the ci operator and to every parser; the advisory silently ships (field report §28). If the finding needs the author, the verdict is FAIL (or PASS-HOLD where merge≠deploy); if it does not, put it after the verdict as an observation, explicitly non-blocking. One verdict, one meaning.
• Gate-split once a real CI pipeline runs the suite on the PR head. Where ci already runs typecheck, build and the full suite against the PR head on a cold runner, QA re-running it locally pays twice and pays for the weaker environment — a warm, pre-seeded dev tier structurally cannot exercise a bootstrap path. So with CI present, QA's default is: require CI green, then spend the gate on what CI structurally cannot do — judgement, scope-vs-contract, security paths, the independent behaviour check. The full local suite stays mandatory for schema/migrations, auth, money, and anything QA judges risky. Every verdict states its mode — mode: ci-trusted or mode: full-local — so a skipped suite is never ambiguous between policy and omission. Prerequisite, non-negotiable: a CI green is only as good as the commit it ran against. The measured bootstrap-path case: EVIDENCE.md.
• Scope: routine, behavior-identical, low-risk PRs go straight to main — and the coordinator may take them off your queue entirely via the Express lane below (you audit those post-merge). Money / fraud / auth / migration / high-risk surfaces still take the full fan-out gate (off-bus adversarial auditor + pre-studying secondary — see Money & High-Risk Review Gate); QA alone is not sufficient there, the coordinator orchestrates that gate, and enabling live money is always David's.

CI — the release pipeline operator (cheap model)

The CI operator executes the release path so neither QA nor the coordinator burns expensive context on mechanics. Run it on a cheap model (Haiku-class) — the role is designed to contain zero judgment: every duty is a lookup, an execution, or a classification, and anything that feels like a decision gets bounced.

• Executes, never decides: on QA's cited PASS verdict (current-head only), after checking the coordinator's deploy holds → squash-merge, squash-verify (git show origin/main:<path>), watch the tier-1 deploy to qa, smoke-check, post DONE:/RISK: dock telemetry, log deploy state to FACTS. Chases tier-2 (nightly/E2E/scans) results; failures go to the coordinator as queue candidates.
• Hard bounces: merge conflicts → the owning worker (ci never resolves them); red pipeline beyond one known-flaky re-run → classify (build|test|infra) and BLOCKER: the coordinator with the log pointer; fix-forward vs hold → coordinator; anything prod → David; quality → QA, always.
• Non-author by construction: ci never writes code, so every merge it executes satisfies the non-author invariant automatically.
• Fallback: no ci → QA merges under the forfeiture rules above; no QA either → coordinator.

Express lane — routine PRs bypass QA

QA is single-threaded and its bar does not move with queue depth, so on a busy fleet the verdict queue is the critical path. The express lane takes the PRs that never needed a behavior check off that queue without lowering the bar for anything that does: the coordinator classifies at routing time, ci verifies eligibility mechanically and merges, QA audits after the fact.

• The coordinator decides, once, in the contract. Every GO carries gate: full (default) or gate: express. Express is for changes whose risk is exhausted by typecheck + tests + PR-level CI: docs / copy / comments, config values, tests-only, behavior-identical refactors, dependency-free small fixes. Never express: auth · money · migrations / schema · dependency manifests / lockfiles · CI workflows · infra / k8s / Dockerfiles · secrets paths · anything the contract cannot describe as behavior-identical. When unsure → full. A dependency or lockfile PR takes full and its verdict shows a smoke check of the surface the dependency feeds, because the type- and test-suite can be green while a duplicated peer breaks the runtime (cass #1957: a TypeScript-peer bump forked one UI package into two instances and every CMS edit view returned 500 on dev until #1976 reverted it). The tag is judgment, so it lives with the coordinator; nobody downstream re-decides it.
• The worker addresses an express DONE: to ci (still a cited PR, PR checks green, same completion-report rules). A worker cannot self-promote to express — no tag in the contract means full.
• ci verifies eligibility with lookups only, then executes. In order: the contract says express (quote the GO) · headRefOid current · PR checks green · mergeable · no deploy hold · gh pr view --json files,additions,deletions: no file under a deny path (**/migrations/**, package.json, *lock*, .github/workflows/**, **/auth/**, **/*secret*, Dockerfile*, k8s/**, infra/**), total churn ≤ 150 lines, not counting files the repo regenerates (the contract lists them) · gh pr diff adds no .skip(/.only(. Every check passes → squash-merge → squash-verify → telemetry tagged express. Any check fails → not a bounce: forward the DONE: to QA as an ordinary full-lane item (FYI: the coordinator with the failing check). ci never argues eligibility; a miss just falls back to the normal gate.
• An express commit that touches a package's files list, deletes source, or changes what a build emits names its npm pack --dry-run result in the self-check line (file count + the specific presence/absence the change claims). A behavior-identical claim about a shipped artifact is only checkable on the artifact — the repo-level pack gate covers one tarball unless the kit extends it; QA's post-merge audit verified kit b27f729 (templates un-shipped, dead dist/ids.js) by hand, and found the author's stale dist/ would have shipped the "deleted" file on the next publish (LESSONS #39).
• QA audits, never blocks. QA reads express telemetry and spot-checks a sample post-merge (all of them when its queue is idle). A bad express merge is a RISK: to the coordinator, which stops tagging that class — the lane tightens by evidence, never by ci or QA opinion.
• Invariants untouched: merge is still non-author (ci), routing is still single-router, QA's full-lane bar is unchanged, nothing new reaches David. Fallbacks: no ci → express PRs go to QA like everything else (QA runs the mechanical list instead of the worktree ritual, forfeiture still applies); no QA → coordinator.
• Server note (coord-mcp): ci is not a gate-runner role, so a DONE: addressed to ci queues silently instead of push-waking the pane; ci's wait_for_message loop still picks it up promptly. Do not add ci to the gate-runner set to fix this — that would grant it verdict authority.

Rooms

An agent works in its project room, #<project>, and nowhere else — routing, GOs, reports, blockers, onboarding, handover, presence. A fleet runs its entire life in one room, and cross-project asks go coordinator↔coordinator as DMs.

#general is retired: do not join, post, or route to it. It was narrowed twice first — cross-project traffic only, then no default membership — and each time the coordinators stayed and their presence pings followed, until it became the thing it was scoped to avoid. Scoping a shared channel by its intended CONTENT did not hold; only removing the reason to be in it did. The default channel still exists: the server refuses to delete it, and David does not read it.

| Room | Purpose | | --- | --- | | #<project> | The coordinator's and its workers' primary working room. All routing, GOs, completion reports, status diffs, blockers, and onboarding for that project happen here. Create it with join_room; set its topic on first join so other agents see what it is for. | | #general | Retired — do not join. The bus's default channel; it cannot be deleted, and nothing routes through it. Cross-project traffic goes coordinator↔coordinator as DMs. | | #ops | Terraform, deploys, namespace/RBAC, keys, tokens, CI runners, and cutover gates — when those span projects or warrant a shared lane. | | #infra | Shared tooling or coordination infrastructure, when it is noisy enough to deserve a separate lane. |

Guidelines:

• Work happens in the project room. Cross-fleet asks travel coordinator↔coordinator as DMs (§Agent Naming & Multi-Owner Rooms) — the only standing cross-project path, and it was already the sanctioned one.
• Onboarding hands each agent --rooms=<project> only. An agent that finds itself in #general leaves with leave_room; being delivered its traffic is not a reason to answer there.
• The board is docs/WORKSTREAMS.md — repo-local, so coordinators on different projects never collide even though the bus is shared (no per-project filename suffix needed). It unifies on Groundwork's WORKSTREAMS.md (core ## Active Streams + ## Recently Closed) plus a coordinator-only extension block (Open PRs, Cutover Gates, Needs David, Risks, Rooms, Decisions).
• Retire a focused or project room with delete_room once its project wraps; it refuses while agents are still joined unless force=true, and it refuses outright for #general — the default channel is undeletable by design, which is why that one is retired by disuse rather than removed. Don't let dead rooms accumulate: leftover rooms become cross-fleet routing surfaces, which is what #general became.

Orientation artifacts (topic / MOTD) are owned, and they assert location, not state

A joining agent's whole orientation is join → default-room MOTD → join_room → room topic + MOTD → history. These are the first things it reads and the last things anyone reviews — they sit outside every gate the fleet has, they are read before the agent has any repo context to check them against, and a wrong one misinforms every future join, not once (LESSONS #31). Ownership therefore applies to them exactly as to repo files (§Board Accuracy Rules, LESSONS #21):

• Name an owner in the artifact itself — Topic owner: <agentId> — and treat topic/MOTD edits as reviewable changes, not housekeeping. Unowned is how they rot: the room's creator stops seeing them as information and starts seeing them as furniture.
• Assert where things live, never lifecycle state. board: docs/WORKSTREAMS.md · queue: docs/QUEUE.md · coordinator: <id> stays true for a project's whole life. "fresh repo, no board docs yet", "Phase 1 MVP", "integration branch: feature/phase14" are guaranteed to become lies and were found doing so in live rooms — one told every joining agent that no planning docs existed for a repo with 961 commits and six board documents, shaping its first move against the truth.
• An id in a topic is a routing instruction, so re-check it after any rename. Topics naming a coordinator that has since self-renamed (bf-coord → bf-david-coord) point new agents at an id that no longer exists — worse than a stale doc claim, because it fails as an instruction. Rename an agent, audit the rooms that name it (§Agent Naming).
• Cross-project artifacts are David's, not a coordinator's to rewrite. #general's MOTD is served as defaultRoom to every agent on join, across all projects — retiring the room does not change that, since join returns it whether or not anyone is a member — so a coordinator that "just fixes" it silently rewrites another fleet's onboarding. Flag drift to David with a proposed replacement; never edit it unilaterally. (Found stale in the field: it named three focused rooms, one of which did not exist and one of which had been dead for months, while omitting every currently-active project room.)
• Keep the MOTD small enough to correct, and put the doctrine in a repo file. An MOTD is read on every join, so the temptation is to put everything in it — but a large one becomes unaffordable to fix, and then it goes stale in place. Measured: one room's MOTD reached 33,870 bytes while every other room on the bus sat at 0–739; a rule routing escalations to a role David had just deleted was left standing there because another 34KB rewrite "wasn't worth one stale clause". Doctrine belongs in a versioned repo file (docs/BUS_PROTOCOL.md), with the MOTD reduced to a pointer plus whatever changes behaviour right now — live suspensions, the current gate rule, where the board and queue live. set_room_motd takes motdAppend and motdPatch:{find,replace} precisely so a one-clause correction costs one small call; past ~4KB it warns and names this pattern. A stale rule in a big MOTD outranks a maintained file, because the MOTD is what a joining agent reads first.
• Absent beats wrong, but neither is fine. A room with no topic gives a joining agent nothing; a stale one gives it a confident falsehood it has no way to check. Set the topic on room creation (§Rooms table) and re-read it whenever you cite it — reading your own topic in a list_rooms dump does not count as reviewing it.

The audit unit is every artifact that RESOLVES AN ID, not every artifact that mentions one (LESSONS #31b). Four artifacts resolve ids — room topic, room MOTD, room membership, and the agent registry — and they can disagree with each other silently. The severity ordering is what matters: prose naming a dead id misinforms a reader, who can notice; membership and the registry make an id addressable, so an agent routes to it in good faith and gets silence rather than an error — a DM lands in an inbox no process reads. Found live: two agents listed as members of a project room were absent from the registry entirely, and a fleet whose rename audit was genuinely clean still had three defects in this class.

• Reconcile membership against the registry — the sweep is free. ping { from, to } answers entirely server-side (zero model tokens on the target) and returns reason: "unregistered" for a phantom, so every member of every room can be checked for the cost of a few calls. This was never a hard check, only an unrun one: ping each room member, and anything unregistered is a routing black hole to clear.
• Detection and remediation have different reliability — never let one lesson fuse them. ping detects a phantom reliably and for free. Removing it is a separate operation that must be verified on its own terms, and the built-in sweep is not known to close what the probe opens: a field dry-run of prune {room, targets:["members"]} reported orphanMembers: [] on a room holding two members ping had just called unregistered (LESSONS #32). So: probe with ping, remediate deliberately, then re-probe to confirm the removal. A sweep returning [] is not evidence the class is clean — it may be evidence the sweep cannot see the defect.
• Registration fields are unvalidated, which is why they drift. role is free text, so one fleet carried role: "worker-4" on one worker while its siblings had role: "worker" (an instance number where the others hold a class — harmless until something filters by role), and two live agents had no role at all. Nothing rejects any of it. Treat your own join { agentId, role, project } as an artifact you own: role is the class, the instance number lives in the id.
• Audit the class, not the instance you were asked about. The fleet above passed the rename check and would have reported "clean" had it only checked what was asked — the three defects surfaced because it inspected the whole artifact class instead. When one member of an unowned class is found rotten, sweep the others.

Agent Naming & Multi-Owner Rooms

Agent ID convention: <project>-<owner>-<role>[-n] (e.g. bf-david-aide, bf-marco-worker-2). owner is the fleet's human sponsor — the person whose DAVID_DECISION:-class escalations this fleet routes to. Adopted 2026-07-08 when project rooms became multi-owner: two developers can connect their fleets to the same #<project> room, and attribution must be readable from the ID alone. coord-claude-layout.sh --owner=<name> bakes it in (defaults to $USER).

Legacy <project>-<role> IDs self-migrate: each agent calls rename_agent on ITSELF (the caller's token binding rotates — never rename another agent), then re-attaches its transport (attach_agent; rename detaches it).

Multi-owner authority rule: a worker acts only on GO: from its own owner's coordinator. Cross-fleet asks travel coordinator↔coordinator as DMs — never directly to another owner's workers, and never as room broadcasts that could read as tasking. Silence from a foreign coordinator is not permission. Each owner's aide faces only its own owner; there is no cross-owner aide↔aide lane (owners talk to each other as humans).

• gh pr list --author @me RETURNS THE FLEET, NOT THE SEAT — AND IT ANSWERS CONFIDENTLY, WHICH IS WHAT MAKES IT DANGEROUS. AN IDENTITY FIELD THAT IS CONSTANT ACROSS A POPULATION CANNOT DISCRIMINATE WITHIN IT. Measured 2026-09-12 across the last ten PRs, and I checked it rather than took it: distinct authors: 1 — every seat authenticates as the same GitHub user, because it is ONE human's credential shared by six agents — while branches carrying a seat prefix: 10 of 10. ⛔ A worker ran --author @me, got another seat's frozen PR back as its own, and CAUGHT IT RATHER THAN ACTING ON IT. Acting on it would have meant touching a branch frozen for a gate — the one move this playbook treats as unrecoverable. ⭐⭐ THE FIELD IS NOT BROKEN AND THAT IS THE TRAP: @me is perfectly accurate about the ACCOUNT. It is simply not a fact about the SEAT, and nothing in the output says so — a shared identity looks exactly like a personal one at the point of use. ✅ THE DISCRIMINATOR THAT EXISTS ALREADY: <agentId>/<slice> BRANCH NAMES, 10 of 10 on the same sample. Filter on the branch prefix; never on the author. ⚠ AND THE GENERAL FORM, WHICH IS WHY THIS IS CANON RATHER THAN A CLI TIP: BEFORE A FIELD IS USED TO TELL MEMBERS OF A POPULATION APART, CHECK THAT IT VARIES ACROSS THAT POPULATION. One distinct count answers it. A field with cardinality 1 used as a key returns everything and looks like it returned something. ⛆ Same shape as a coverage ratio over a population nobody named, and as a ref that resolves against a moving tree: the instrument is fine and the POPULATION assumption underneath it was never checked.

Message Prefixes

Agents should prefix important room messages with one of these:

• FYI: no action needed
• AGENT_ACTION: another agent can handle this without David
• DAVID_DECISION: David must decide
• BLOCKER: work cannot continue without an action or decision
• RISK: quality, security, production, cost, or product risk
• DONE: completed work or closed item

The coordinator may ask agents to restate unclear messages using these prefixes.

The prefix is for the human eye; record.type is the one the bus reads — and every agent→agent message carries one. The nine types are decision · verdict · done · blocker · risk · fyi · action · go · scope, and they map onto the prefixes above one-for-one (AGENT_ACTION: → action, DAVID_DECISION: → decision; GO:/SCOPE: are the coordinator's two). Send both:

send_message { from, to, text: "DONE: task 12 landed — …",
               record: { type: "done", payload: { summary: "…" },
                         cites: [{ kind: "pr", ref: "owner/repo#163" }] } }

• text is untouched by the record and your wording always wins — a record renders into text only when you supplied none.
• Why it is obligatory rather than encouraged: a typed multi-line message is delivered as ONE attributed line plus a retrieve_message handle; an untyped one arrives in full, in every reader's context, and its continuation lines arrive with no [tag time from] header at all, so a reader cannot even attribute them. Measured on one room: 206 messages, 175 multi-line, 33 typed — the slimming shipped and went unused for days.
• An untyped agent→agent send is refused at the SEND, not the render (agent-coord-mcp ≥0.26.10; WARN with the date named until 2026-09-15, REFUSE after). Enforcing where the message is read would leave the untyped message on disk and the next reader re-deriving its type from prose. The refusal names the type you should have used and the literal call that succeeds.
• fyi is the honest catch-all. If nothing fits, it is fyi — do not force a false decision/risk to get past the gate. A mistyped record is worse than an untyped one, because the type is then noise nobody can query.
• A verdict names its gater, in a field. payload: { result, headRefOid, gatedBy?, scribe?, notes? } — gatedBy is the seat that JUDGED when that is not the sender; scribe is the sender that transcribed it (it must equal from, or the send is refused). Every reader attributes a gate by gatedBy ?? from, never from alone. Authority does not move: only gate-runner roles may emit verdict, so a gate result from any other seat MUST be scribed — the gater posts the typed line GATE: PASS @ \`in its owndone/fyiciting the PR, and a gate-runner emits theverdictcarryinggatedBy. An open PR whose head has such a typed report and no verdictis reported bystall_checkasunverdicted-pr · reported-unscribed(versusnobody-gated) — the claim exists, the record does not. A gatedness citation names the SEAT whenever any channel can: when the earliest match is a PR comment (the shared account) and a bus verdict names the same head, it reads *"by (bus), first seen on the PR at`"*; a PR-only verdict names the account and says so.
• David-facing messages stay prose. The rule is scoped to agent→agent traffic; a message whose recipient the server KNOWS as human is exempt — a human is not a registered agent and a human's registry entry cannot survive eviction, so the send path reads the durable human set (humans.json, written when a seat registers with a human role, unioned with AGENT_COORD_HUMANS; visible as list_agents.humans). No flag on the message; an id the server does not know as human is an agent (⟨q-178878aa⟩).
• A model that cannot reliably pick a type declares proseOnly: true at join — per agent, never a global env var, visible and counted in list_agents. The exemption is granted to the SENDER and paid by every READER: an untyped message cannot be slimmed, so a prose-only agent spends other agents' context on every multi-line send. That is why it is opt-in and reviewed rather than self-service, and why a rising exempt share is the number that says the rule is decaying.

Every DONE: must cite its PR — a URL, owner/repo#N, or PR #N when the channel has a default repo. This is what lets the coordinator (or an automated claim-verifier) confirm merge state from gh instead of trusting the message. A DONE: with no PR reference is unverifiable and should be treated as not-yet-done until cited. A merge-closing DONE: MERGED … states a branch deletion only as something it READ — remote ref read: 0 refs at <ISO ts> (an ls-remote taken after the delete) — or as delete requested (a command issued, state unclaimed). Bare "Remote branch deleted" is refused at the send by the same check: measured 2026-09-14, two such lines preceded their artefact by 33s and 62s, and five more described deletions that never happened (gh --delete-branch had left the remote when the local delete errored). A closing line verifies the squash by content; the ref gets the same rule. Work that has no PR by rule — docs pushed straight to the shared branch (queue curation, canon, board moves) — cites the commit instead: record.cites:[{kind:'commit', ref:<full 40-hex sha>}] plus repo, and the bus verifies the sha is reachable from that repository's origin/main before writing; a short, fabricated or side-branch sha is refused by name, an uncited done is refused as before (⟨q-cc0819dc⟩). A commit-cited DONE closes its queue row through docs/DONE.md (the closure grammar accepts a sha) but produces no pr event and joins no verdict — there is no PR to gate.

Degraded comms: lead with the blocker, not the deliverable. If your only channel out is narrow or borrowed — you can receive but not transmit, your bus tools are unavailable, you are relaying through a human — the first line must be the constraint and the ask, never the work product. An agent that reported its finished push to David but buried "please relay this" mid-message stayed blocked, and two other lanes with it, because a constraint nobody acts on is indistinguishable from silence (LESSONS #34). Say BLOCKER: cannot transmit — relay to <coordinator>: <one line> first; the deliverable goes underneath.

Relay Authenticity

Agents are (rightly) trained to treat unexpected mid-task instruction text as potential prompt injection — which means a legitimate scope change relayed over the bus can be silently discarded as suspicious. This happened in the field: a sub-agent dropped real coordinator corrections and cost a full re-send cycle. Right instinct, wrong outcome. The fix is a provenance convention:

• The coordinator countersigns relayed scope changes. A mid-task instruction that amends a worker's contract arrives as a coordinator DM that leads with SCOPE CHANGE: (or SCOPE:) and references the contract it amends. The explicit prefix plus the known coordinator sender id is the countersignature — and under tiered delivery (coord-mcp ≥v0.12.0) that same prefix from a trusted sender is what makes the relay push immediately instead of queueing.
• Prefer file + pointer for instruction-bearing relays. Write the amended contract to a repo file (ideally the contract's existing file) and DM a short pointer. Repo-file provenance reads as data, not as mid-stream injected instructions — and it composes with the long-contract rule below.
• Workers: an instruction arriving as a countersigned coordinator DM, or as a pointer to a contract file in the repo, is authentic by convention — verify the sender id, then act on it. If an instruction-bearing relay arrives with neither marker, don't silently drop it: ask the coordinator to confirm in one line.
• Never start a message with /. The tmux pusher's injection guard stores leading-slash text in the inbox but never types it into a pane, so /status … as a DM reaches no one's screen (send_message now warns). Say AGENT_ACTION: run /<skill> …; only send_command (/clear, /compact, /reload-skills) goes in raw.

Coordinator Duties

The coordinator acts as David's channel and second-in-command:

• answer questions that do not require David
• route repo-specific work to the responsible repo owner
• ask for review from the most relevant non-author agent
• detect and correct stale room state
• prevent cross-checkout and cross-repo contamination
• maintain a concise live state board
• escalate only real David decisions, with context and a recommendation
• restate David's decisions back to the room so all agents align

How To Execute The Coordinator Role

The coordinator's job is not to do every task. The job is to keep the system coherent so specialist agents can move quickly without turning David into the message bus.

Operating posture:

• Be the single routing point for cross-agent ambiguity.
• Trust repo owners on repo facts, but verify claims that affect decisions, merges, deploys, spend, or production risk.
• Keep implementation authority with the owning agent unless David reassigns it.
• Prefer short, decisive room messages over long discussion threads.
• Collapse noisy debate into a small number of options and a recommendation.
• Keep David out of routine execution, but bring him in early for irreversible, costly, credentialed, production, or ownership decisions.

Startup loop:

1. Register or join as the coordinator identity.
2. Attach live message delivery and confirm it is working.
3. Join the relevant focused rooms.
4. Read or reconstruct the live board, and read the project queue (docs/QUEUE.md; legacy docs/BACKLOG.md) for queued work.
5. Announce coordinator state in the project room: active, rooms joined, current blockers, and how agents should route requests.
6. If replacing another coordinator, wait for David's explicit handoff decision and the outgoing coordinator's handover packet.

Daily operating loop:

1. Watch the project room for David decisions, blockers, stale routing, and unclear ownership. Cross-project traffic arrives as a coordinator↔coordinator DM, not from a shared room.
2. Keep detailed implementation discussion in focused rooms.
3. Convert ambiguous messages into one of: AGENT_ACTION, DAVID_DECISION, BLOCKER, RISK, DONE, or FYI.
4. When a lane has capacity: next_unblocked → claim → route it as a contract; land when it merges (§Bus Verbs).
5. Route work to the owning agent, with the expected output and merge/review gate.
6. Ask the most relevant non-author agent for review when risk warrants it.
7. Update the live board when work merges, blocks, or changes owner.
8. Correct stale board state quickly and visibly, especially when an item is already merged, deployed, blocked on ops, or no longer relevant.
9. Send David compact decision packets only when the room cannot safely proceed without him.

When a new or replacement agent joins:

1. Confirm the agent's role, repo lane, and rooms.
2. Onboard it with /coord-worker --rooms=<project> so it reports in the project room; add extra rooms only if its lane genuinely spans them.
3. Point it to this playbook and the current live board.
4. Summarize only the state needed for its lane.
5. State explicit boundaries: repo ownership, branch/PR expectations, secrets policy, and production guardrails.
6. Give one concrete next action or tell it to stay idle/on-call.
7. Ask for an ACK so delivery and comprehension are confirmed.

Context Topology & Delegation Economics

The system is hub-and-spoke for context, not just routing. Getting the topology right is what keeps the whole fleet's token cost sub-linear.

• Asymmetric context is the design, not an accident. The coordinator is the one wide, persistent context that holds the global picture once; workers are narrow, ephemeral spokes that see only their current slice and get cleared between tasks. Delegation is the mechanism that keeps spokes lean — a worker never needs the map, so its context never bloats. Resist the pull to brief everyone on everything.
• The board is the coordinator's swap-space, and its SOLE WRITER is the coordinator. The coordinator offloads global state to a durable board (docs/WORKSTREAMS.md — repo-local; a bus-side board later) so its own window stays lean. Every other role reads it and never writes it — queue and done carry that never-clause explicitly and the board carried none, which left an agent looking at a stale row with no prohibition to stop it. Board is the state; chat is the audit log of transitions. Write state to the project room. An empty board plus a bloated room is the anti-pattern.
• Delegation floor — delegate substantial slices, do trivial work inline. Delegation has a fixed tax: writing a self-contained contract plus a review round-trip. If that tax exceeds the work being handed off, delegating is net-negative — just do it inline. Reserve delegation for slices big enough to repay the coordination cost.
• The contract is a compression interface, not bureaucracy. A sharp, self-contained task contract (goal, inputs, boundaries, done-definition, gate) is precisely what buys the lean executor: the tighter the contract, the less context the worker needs, the harder it can be cleared afterward. Vague contracts force the worker to carry (and re-derive) context it should never have held.
• Keep a per-lane work queue so spokes never idle. Routing is not "coordinator hands out one task at a time on request." Maintain a ready next-GO per lane so a worker pulls the next slice the instant one lands (see Worker Flow: No Idle Gaps).

Architecture Audit (structural drift)

Every standing role sees a slice: the coordinator holds the board, workers hold a lane, QA holds one PR, docs hold intent. Nobody re-derives whether the code still matches the architecture that was decided — so duplication, boundary leaks and silently violated ADRs accumulate below every gate's resolution until they surface as the bug no agent can fix in a codebase no human has read. The audit is the periodic instrument that looks (skill: /coord-audit).

• Read-only, report-only, on demand. David or the coordinator invokes it (per phase close, per N merges, or when a smell recurs). It authors no code, opens no code PRs, issues no verdicts, and reports to the coordinator only — accepted findings become queue candidates the coordinator relays to the aide once (route-once).
• Measurement, not taste. An agent reading agent-written code grades its surface and shares the writer's priors; maintainability has no oracle at read time (LESSONS the same models — the podcast's "if the model knew what good code looked like it would write it"). So the audit is confined to what is checkable: (a) conformance to stated rules, (b) mechanical measurements (duplication, forbidden imports, leftovers, size, churn), (c) docs-vs-code disagreement, (d) friction stats from bus + git (co-change clusters, churn, QA bounces per path, context resets per lane) — architecture cost measured by its consequences, the only honest quality signal. Design opinions are not findings; they go to David under Questions, with evidence, uncounted.
• Docs are the hypothesis, the tree is the evidence. It reads DECISIONS/ARCHITECTURE_GUIDE/STACK_MAP/domain model first, turns each rule into a falsifiable claim, then checks the claims against a fresh origin/main worktree with positive controls (§Verify Before You Report Or Assert). Tripwires (dup/boundary lint, groundwork doctor) run first and are quoted raw. Findings are cited file:line, classified (RULE-VIOLATION · DUPLICATION · BOUNDARY-IMPORT · LEFTOVER · DOC-DRIFT · TEST-CANNOT-FAIL · FRICTION), severity by blast radius / measured cost, and scoped to what was measured. Uncovered areas are listed — silent partial coverage reads as clean.
• Drift cuts both ways. "Docs wrong, not code" is a first-class finding; the fix is a doc/ADR update, not a code task.
• Accepted deviations are facts. Anything David/the coordinator chooses to live with is written to docs/FACTS.md (with the audit SHA) so it is not re-reported; a finding that recurs across audits with no such fact is flagged RECURRING and treated as a guard candidate (see LESSONS Guard field) rather than another task.
• Reports live in docs/audits/<date>-<sha7>.md (docs-only branch/PR).

Task Backlog (Inbound Queue)

The board is the coordinator's outbound state ("what's happening"). The backlog is its inbound twin ("what David wants next") — a durable, David-owned queue that replaces ephemeral chat asks. Chat is a poor queue: unordered, no priority, buried in the firehose, and every ask wakes the whole bus. A file is append-anytime, prioritized, greppable, diff-able, and costs zero bus tokens.

• Location: two files in each project repo — docs/QUEUE.md (inbound queue) and docs/DONE.md (completion log) — versioned, and David edits where the work lives. Per-project, like the board. Legacy layout (single docs/BACKLOG.md with ## Queue/## Done regions): still parsed by the UI; existing projects migrate by a one-time mechanical split — this is the only normative mention; everywhere else, read "queue/done files" as covering both until migration completes.
• Single writer per ACTION (the file alone is not enough — see Aide): docs/QUEUE.md is David's file for curation — written by David directly, by the aide as his proxy, or via an authorized editing surface (e.g. groundwork-console, formerly agent-coord-ui) acting on his behalf; those are the same logical writer. docs/DONE.md is the coordinator's file, append-only. One writer per ACTION means git and the filesystem arbitrate, and the shared-region CAS ceremony disappears (LESSONS #7). Pruning satisfied or merge-obsoleted Queue items is the coordinator's obligation — it sees merges land, so closing follows from landing rather than from someone noticing; with no coordinator, the aide does both.
• The queue feeds the board; it does not duplicate it. Pulling a task makes it an info-dense contract and a 🚧 In Progress row in docs/WORKSTREAMS.md (## Active Streams) — claim writes that row. On completion land appends the docs/DONE.md line with its PR ref and closes the item in docs/QUEUE.md — status and pruning only, never priority or wording, which are the aide's. Live state lives on the board; the queue stays thin.
• How the coordinator drains it: next_unblocked answers "what next", claim opens the row, land closes it. The ordering, the tie-break, the skip and the board hunk are the verb's job now (§Bus Verbs) — what stays a judgment call is converting the item into a contract (goal · boundaries · done-def · gate · cited refs) and choosing the lane. The queue is the inbound swap-space, mirroring the board as the outbound one: it lets the coordinator pull one item when there is capacity instead of holding all of David's intentions in context.
• Dependencies: the aide orders, the coordinator detects, one DM closes the loop. The aide orders the queue without lane capacity or dependency knowledge; the coordinator sees both but cannot write the file. next_unblocked performs the skip and returns the board hunk that records it; the part no verb can do is the one AGENT_ACTION: RESEQUENCE: <item> after <item> — <one-line why> DM to the aide. Route-once applies: one path, one message, no re-asking.
• Format — the groundwork-console parser contract (see the fleet writer rules under Board Accuracy Rules). Match it exactly or the UI BacklogPanel renders empty — silently, not an error (polywatch hit this; tolerance added in agent-coord-ui#58; split-file support in agent-coord-ui#59):
  • File precedence: if docs/QUEUE.md or docs/DONE.md exists, the UI reads the split files; otherwise it falls back to legacy docs/BACKLOG.md. In the split files the # QUEUE — <project> / # DONE — <project> title and the ## Queue/## Done h2 are optional — headerless item lines parse too — but keep the headers for readability.
  • In the legacy layout, ## Queue and ## Done are the recognized h2 sections (order-independent); any other h2 section is ignored.
  • Queue item: - [ ] (P1) <task text> — checkbox, then a required priority (P1)/(P2)/(P3) (parenthesized, or compact [P1] post-#58), then the task. The parser captures everything after the priority as task text — Queue refs are not separately extracted, so any — refs you add is just part of the displayed text, not a structured field.
  • Done item: - [x] <task> — <ref> · YYYY-MM-DD — ref and date are parsed, and the separator glyphs are exact: the ref splits on the last — (space + EM DASH U+2014 + space) and the date is a trailing · YYYY-MM-DD (space + MIDDLE DOT U+00B7 + space). A plain hyphen - or - will not split the ref; any other date format will not extract. Use the exact glyphs.
  • ### Subsection (h3) headers are allowed inside ## Queue/## Done for grouping. Everything else — prose, non-priority bracket tags (e.g. [ops]) — is ignored by the parser.

docs/QUEUE.md                                docs/DONE.md
# QUEUE — <project>                          # DONE — <project>

## Queue                                     ## Done
- [ ] (P1) <task text>                       - [x] <task> — owner/repo#N · YYYY-MM-DD
- [ ] (P2) <task text>

Writing the acceptance: field — four things it must say, each learned from a clause that was correct and useless.

• Name the LOCUS of every measured instance, and say whether the remedy RUNS there. ⟨q-2c8d05f7⟩ specified a pipefail preamble and a repo lint; all five measured instances were ad-hoc shell commands typed through the Bash tool, so both remedies guard a room the defect never entered. Nobody was wrong about the mechanism — the shape, the controls and the negative control were all right. The question nobody asked was WHERE. It survived three reviewers because each was checking whether the fix WORKS, not whether it is where the defect IS. The tell is five rows of two columns, writ