kb: Skill for Claude Code

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.