/herdr-orchestration

name: herdr-orchestration
description: Orchestrate Claude and Codex worker TUIs from a controller agent — one worker per named herdr tab, driven over the herdr socket CLI.
disable-model-invocation: true
metadata:
  author: Pedro Nauck
  github: https://github.com/pedronauck
  repository: https://github.com/pedronauck/skills

herdr Orchestration

The top-level agent is the **controller** (Codex, Claude, Fable, or another); it delegates to **worker** TUIs that gather evidence, draft bounded patches, run tests, and report. The controller owns assignment, state, conflict control, verification, integration, and the final user-facing answer. herdr is the substrate: each worker TUI owns a named tab, and the socket CLI (`herdr …`) gives the controller placement, input, screen reads, and native agent-status waits.

One worker, one named tab

Every worker gets its own tab, labeled at creation with `tab create --label`. The tab bar is the controller's dashboard: a labeled tab says which model is running which slice, and stays readable no matter how many workers are live.

Tabs also cost no screen area. A split pane divides the caller's screen with every worker, and on a laptop the third worker leaves every pane too narrow to read. Split a pane only when the user explicitly asks to watch a worker beside the caller.

Two names per worker, both required at launch:

• **tab label** — `<model>: <slice>`, e.g. `opus: fix loops`,

`codex: audit auth`. Free text; keep it short, tab bars truncate.

• **agent name** — the slice as a slug, e.g. `fix-loops`. Must match

`[a-z][a-z0-9_-]{0,31}` and be unique among live agents. Every `agent …` verb accepts it in place of a pane id.

Workers are TUIs — no headless runners

A worker is an interactive TUI — `claude` or `codex` — started with `herdr agent start`, which validates the agent's identity and returns only once herdr sees it ready for input. herdr's agent-state integrations hook those TUIs, so `agent wait`, `agent list`, and blocked/done detection exist only while a real TUI is on screen.

Headless runners — `claude -p`, `codex exec`, anything that streams JSON events into a pane — never report state, so waits never fire and the delegation dies silently. A worker tab filling with raw JSON event lines is a broken delegation: interrupt it (`rtk herdr pane send-keys <pane_id> ctrl+c`) and relaunch through `agent start`.

Invariants

• Scope every action to the caller workspace unless the user names another

target.

• Resolve caller context from `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and

`HERDR_PANE_ID` (injected into every herdr pane) before any focused-window fallback.

• Address workers by ids parsed from command JSON — agent name for `agent …`

verbs, `w2:t3` / `w2:p4` for tab and pane verbs — never by guessed position.

• Pass `--no-focus` on every creating verb (`tab create`, `workspace create`,

`worktree create`, `pane split`); use focus verbs only when the user asks.

• Retire every worker you launch when its assignment and planned integration

follow-ups are finished (see Retire workers).

Preflight

Inspect the daemon, integrations, and caller context:

rtk herdr status                 # server running + socket path
rtk herdr integration status     # selected worker runtime must show `current`
rtk herdr pane current --current # caller pane / tab / workspace ids
rtk herdr agent list             # agents already running

Check/install only the integration for each selected runtime. Reuse this preflight in the same workspace while the daemon and integrations are unchanged; a new packet alone does not require repeating it.

Launch workers

Use each worker runtime's configured model unless the user requests an override. Launch is two commands: create the named tab, then start the TUI in that tab's root pane.

# 1. named tab — returns .result.tab.tab_id and .result.root_pane.pane_id
rtk herdr tab create --workspace "$HERDR_WORKSPACE_ID" --cwd "$PWD" \
  --label "opus: fix loops" --no-focus

# 2. worker TUI in that tab's root pane; native flags follow `--`
rtk herdr agent start fix-loops --kind claude --pane <root_pane_id> -- \
  --dangerously-skip-permissions "<packet>"

rtk herdr agent start audit-auth --kind codex --pane <root_pane_id> -- \
  --yolo

Capture `tab_id`, `pane_id`, and the agent name in the registry — retiring and screen reads need all three.

Claude always launches with `--dangerously-skip-permissions` and Codex with `--yolo` — workers run unattended and must not stall on permission prompts. Plan-first runs add Claude's `--permission-mode plan`; the flags compose (see Plan-first delegation).

`agent start` returns success only after herdr detects the agent ready, so a non-zero exit is the launch failure — read the tab's root pane (`rtk herdr pane read <pane_id> --source visible`) before retrying. Confirm the label stuck with `rtk herdr tab list --workspace "$HERDR_WORKSPACE_ID"`; if the tab shows a default label, restore it:

rtk herdr tab rename <tab_id> "opus: fix loops"

Sending prompts to running TUIs

Prefer passing the initial packet as launch argv (shown above) — the session starts working immediately and skips the TUI-ready race. Exception: Codex plan-first launches bare (see Plan-first delegation).

For any follow-up, use `agent prompt` — it submits text plus Enter atomically, honoring the pane's live bracketed-paste mode, and `--wait` blocks until the worker settles:

rtk herdr agent prompt fix-loops "<follow-up prompt>" --wait --timeout 300000

A trailing `\n` in `pane send-text` does not submit — a TUI renders it as a soft newline and the prompt sits unsubmitted. An unconfirmed send is not delivered: if `--wait` returns `agent_prompt_stalled`, the worker never changed state — read the screen and resend.

Plan-first delegation (opt-in)

Plan-first runs only when the user activates it — an explicit ask ("plan first", "plan mode") or a `--plan-m