hive.worker-delegation

## Operational Protocol: Worker Delegation

**Applies when** you're in COLONY mode and considering whether (and how) to fan out work to parallel workers via `run_playbook`. Read this before fan-out, not during.

### Mental model: the tracker is the spine, the playbook is the controller

You don't coordinate workers by reading their reports and deciding what's next each turn. You model the goal as a **tracker table** where every unit of work is a row, and you write a **playbook** — a deterministic Python script — that drives that table to completion:

> The playbook queries the rows that aren't done yet, dispatches one worker per undone row, and re-queries until none are left. Workers advance their own rows. Re-running the playbook resumes — done rows simply aren't in the work-list anymore.

This is a reconciliation loop. The tracker is the state; the playbook is the controller that converges it. Three artifacts, three jobs:

- **Tracker table** — the durable work-list and its state. The row's status column *is* the progress.
- **Skill** (`write_skill`) — the worker's operating procedure: schema, tool sequence, output format, quality bar. The risky part.
- **Playbook** (`run_playbook`) — the deterministic orchestration: which rows are undone, who runs them, rate limits, retry/convergence policy. The cheap part.

The worker's task string carries only the per-row slice; everything reusable lives in the skill, everything deterministic lives in the playbook.

### The decision: should you fan out at all?

Fan-out helps when:
- The work has **N independent units** (rows, person on linkedin, files, accounts, segments) and each unit takes meaningful tool time (browser, API, file read, LLM call).
- The units are **disjoint** — no two workers need to write the same row at the same time.
- You can describe one unit's work in <100 words once shared playbook is in the skill.

Fan-out HURTS when:
- N=1 or N=2 with cheap units. Spawning has overhead (fresh AgentLoop, separate conversation, no shared context). Below ~3 units of meaningful work, do it yourself.
- The work is exploratory ("figure out X"). Workers are bad at open-ended scope. Decompose first, then fan out the bounded parts.

When the user explicitly asks for fan-out, do not reject the request from an untested architecture guess. If you are unsure whether a browser session, API cursor, login, or other shared resource can be used by workers, ask the user. Workers you spawn get their own separate Chrome tab groups within the SAME Chrome profile — their tabs won't interfere with yours or each other's, and they share cookies / logged-in sessions with you.

### Pilot before fan-out (do the first one yourself)

You wrote the skill from your own walkthrough — but a walkthrough is not an execution. Selectors that worked when exploring can break under the exact tool sequence the skill prescribes; a page may paginate differently when fetched fresh; a field you eyeballed once might be intermittently null. Validate the skill yourself before paying N× to discover the bug.

**The queen runs the pilot, not a worker.** Pick ONE row from the tracker and execute the skill's protocol end-to-end with your own tools — the same `hive-browser` commands, `tracker_*`, `web_scrape`, etc. the workers would use. You see every tool result directly, with no `[WORKER_REPORT]` round-trip, and you can patch the skill mid-pilot as you discover gaps.

When to pilot (always, even when the user asks for "parallel"):
- You just wrote the skill from your own walkthrough, or you're recycling a skill across a UI/API you haven't driven this session.
- The work touches a UI surface that virtualizes, paginates, or has dynamic selectors (LinkedIn, Twitter, Notion, anything with virtual scroll or Shadow DOM).
- The per-unit work spans more than 2–3 tool calls.

How to pilot:
1. Pick ONE row — the most representative one, not the easiest.
2. Execute the skill yourself: run each tool in the prescribed order, advance the row to "done."
3. **If you hit a snag** — fix the skill in place before continuing. Capturing these patches is the whole point.
4. **If the row finishes cleanly:** the skill is validated. Run the playbook for the rest.
5. **If you can't finish the row at all:** the protocol is wrong (not one selector). Redesign before any worker touches it.

Skip the pilot only when the protocol is one you've already validated this session AND nothing about the target surface has changed.

### The loop (always, in order)

1. **Model the goal as a table** — `tracker_sql('CREATE TABLE …')`. Every unit is a row. **Include a done-predicate column** (a status enum, or a `*_at` timestamp that is NULL until complete). The playbook's "what's left" query depends on it. Register the columns workers write with `tracker_register_writable(...)`.
2. **Write the worker protocol as a skill** — `write_skill(skill_name='<protocol>', skill_body='…')`. Or `write_skill(source_path='<root>')` to lift an existing skill into this colony to pilot-patch it. The worker's last act is to **advance its own row** to done.
3. **Pilot the first row yourself** — execute the skill end-to-end against one row. Patch the skill in place. Don't run the playbook until this row finishes cleanly.
4. **Author the playbook** — a Python script (`meta` + `async def run(args)`) that calls `converge(...)` over the table. Set `meta["concurrency"]` to how many workers run at once (you own that number; the framework honors it, rejecting only if it's too high). The script runs in the colony's full Python env — `import json` / `datetime` etc. just work. This is the deterministic orchestration (next section).
5. **Run it** — `run_playbook({playbook: '<script>'})`. It saves the script to the colony library (`playbooks/<meta-name>.play.py`), returns immediately, and notifies you on completion. The convergence loop dispatches undone rows, retries the gap, and dead-letters terminal failures — without bouncing every worker report back to you. *(If