Herdr Agent

Herdr Agent

Build and control an AI-agent fleet in the root agent's Herdr tab. Keep the root pane as orchestrator; add each sub-agent as a right-hand split running the main agent's own launch profile; equalize all columns; then start, prompt, wait, read, monitor, steer, or tear down through the herdr CLI.

Use Herdr concepts, not tmux assumptions. Let the server do the work: herdr agent prompt --wait submits and waits in one request, herdr agent wait is event-driven, and herdr api snapshot reports the whole fleet in one call. Relay reply deltas rather than whole panes to protect the context and token budget.

Choose the Workflow

Read only the reference needed by that branch:

• See references/herdr-recipes.md for guarded grid spawning, equalization semantics, multi-line prompts, focus, and troubleshooting.
• See references/launch-profile.md for where a worker's kind, model, thinking level, and flags come from, the kind gate, and what never carries over.
• See references/delivery-and-waiting.md for the one-call prompt contract, error codes, wait semantics, reading replies, and the no-agent fallback.
• See references/fleet-monitoring.md for snapshot status, sidebar badges, notifications, and the run report.
• See references/context-succession.md for the main agent's context gate, HANDOFF procedure, and handoff brief template.
• See references/final-report.md for the closing report's status words, required parts, and examples.

Answer a Help Request

Resolve this branch before Prerequisites. A help request runs no herdr command, touches no pane, and changes nothing, because someone asking how this works may not have Herdr installed yet. Take it on help, --help, /herdr-agent help, or any plain question about what the skill does or how to drive it. Answer, then stop: no fleet work, no completion report.

The full help text is in references/help-request.md. For a narrower question such as how to broadcast, answer from that one phase instead of printing the whole block, and name the phase so the user can ask for it again by name.

Done when: the user has the summary or their specific answer, and no herdr command ran.

Check Prerequisites

1. Run command -v herdr and herdr status. If the server is unavailable, ask the user to start Herdr from a real terminal; never run bare herdr from a non-TTY shell.
2. Confirm HERDR_ENV=1. Outside a Herdr pane, do not inspect or control the focused session. If check 1 or 2 fails, stop: the run ends BLOCKED.
3. Resolve the root pane, tab, and workspace from HERDR_PANE_ID, HERDR_TAB_ID, and HERDR_WORKSPACE_ID, or from herdr pane current --current and list/get commands.
4. Run agents directly in Herdr panes. Do not nest tmux when agent detection is required.
5. Treat the installed CLI as authoritative. Check uncertain commands with herdr <group> rather than inventing flags. Client and server versions can differ after an update; herdr status says whether the server supports what you are about to use.

Follow Non-Negotiable Rules

1. Keep root as a role. Never replace or close the root pane during fleet work. The one exception is a Phase 8 HANDOFF, where the orchestrator role migrates to a ready successor pane; even then the outgoing pane is retired to read-only, never closed without Rule 8 confirmation.
2. Run exactly one orchestrator. Only the current main agent writes to fleet panes. After a HANDOFF ack, the outgoing agent issues no further prompts, splits, or closes.
3. Parse IDs. Read opaque workspace/tab/pane IDs from JSON; never infer them from display order. A pane moved to another workspace gets a new ID.
4. Use one equal-width row. Split the current rightmost pane right, keep every worker in the root tab, then run the equalizer. Create separate tabs only when the user explicitly requests isolation.
5. Fail closed before writes. Herdr refuses a blocked target itself, but not a working one, and its wait tracks lifecycle state rather than one turn. Reject missing, ambiguous, working, or unverifiable targets yourself before dispatching.
6. Wait before follow-ups. Never prompt while an agent is working. Every follow-up is its own agent prompt --wait cycle.
7. Surface blockers. A trust, auth, or permission prompt needs a human. Focus the pane, notify, and never answer the dialog for them.
8. Confirm destruction. Closing panes, tabs, workspaces, or the server can lose work. Obtain explicit approval and preserve the orchestrator pane unless the user says otherwise.
9. Gate your own context. Self-check at every Phase 8 gate point; at or above the threshold, HANDOFF instead of continuing to fill this window.
10. Mirror the main agent. Start every worker, including a HANDOFF successor, on the inherited launch profile: the same harness kind, model, thinking level, and setup flags as the main agent. Change only what the user names for that worker, or what a calling skill's launch contract requires (for example --without flags for a skill that demands bare launches). A field is named only by a concrete value: a kind, a model ID or alias, a thinking level, or a flag. Ask when a request is vague ("something cheaper") or names a model from another harness without a kind. A worker of a different kind inherits nothing else. Never guess a value you cannot read: model or thinking may be reported UNKNOWN, but unreadable same-kind setup flags abort the launch unless --without flags explicitly opts out.

Phase 1 — Resolve Root Context

command -v herdr >/dev/null || { echo "Error: herdr is not installed" >&2; exit 1; }
test "${HERDR_ENV:-}" = 1 || { echo "Error: not running inside a Herdr pane" >&2; exit 1; }
herdr status || { echo "Error: Herdr server is unavailable" >&2; exit 1; }
root_pane="${HERDR_PANE_ID:?}"; root_tab="${HERDR_TAB_ID:?}"; ws="${HERDR_WORKSPACE_ID:?}"

Resolve project_dir from the root pane's cwd, falling back to the current directory. Set here to the skill's scripts/ directory with the resolver in references/herdr-recipes.md, which probes repo-local installs before global ones. Every later script call uses "$here/…".

Done when: server status passes and concrete root_pane, root_tab, ws, project_dir, and here values are recorded.

Phase 2 — Spawn and Ready the Fleet

Before spawning, define each worker's unique name, task, and expected deliverable. Placement and launch are two steps: herdr agent start never creates or moves layout, and requires a pane already sitting at its shell prompt.

Resolve the inherited launch profile once per spawn wave, as its own tool call before the call that splits, so the user sees it before any agent starts:

python3 "$here/launch_profile.py" --root-pane "$root_pane" \
  --main-model "$main_model" --main-thinking "$main_thinking" >/dev/null

Set main_model and main_thinking to your own model ID and thinking level, and leave either one empty rather than guess. On Claude Code, leave main_thinking empty, because the script reads CLAUDE_EFFORT. Relay the summary line to the user before the first split, including any ⚠ or warning: line. A worker with an UNKNOWN model or thinking level still starts on its config default. Missing or malformed root argv aborts a same-kind launch before the split; --without flags is the explicit reduced-inheritance opt-out. If the user already declined bypass for this run, pass --without bypass on every worker. references/launch-profile.md has the source order, per-kind flags, and what never carries over.

Use the canonical spawn_sub workflow in references/herdr-recipes.md:

1. Run next_grid_split.py --root-pane "$root_pane" to plan the rightmost split.
2. Split with --direction right --no-focus in project_dir, passing --env "HERDR_ROLE=<name>" so the worker can read its own role instead of being told it in every prompt.
3. Parse the new pane ID from JSON.
4. Run next_grid_split.py --equalize --root-pane "$root_pane"; abort on any error or non-convergence.
5. Rename the pane, then start it by running the same command plus --start <name> --pane <id> --timeout 60000. Add only what the user named: --kind, --model, --thinking, --without bypass|flags, or native flags after --. The command runs herdr agent start on the profile.
6. Badge the worker with its job: python3 "$here/badge.py" <name> --title "<job>" --token role=<role>.

agent start is the readiness gate: it returns only once Herdr detects the expected agent and considers it interactive-ready, and returns agent_not_ready immediately if the agent booted into a dialog. There is no separate readiness pass. Names must match [a-z][a-z0-9_-]{0,31} and be unique among live agents. Never fold the task into argv.

Confirm the fleet with python3 "$here/fleet_status.py" --tab "$root_tab" --fail-on-blocked before assigning any work.

Done when: every worker has a unique name and pane ID in root_tab, the layout widths differ by at most one cell, root remains active, the launch-profile summary reached the user, and every start returned success.

Phase 3 — Resolve One Exact Target

Run herdr agent get <name> or herdr pane get <pane-id>. If a name is missing or ambiguous, list agents and ask; never silently retarget. agent_not_found means the pane hosts no detected agent — start one, or take the pane-surface fallback in references/delivery-and-waiting.md. Record both the name and pane ID and use that same ID for every later mutation.

Done when: one existing target resolves uniquely, and its name, pane ID, and current status are recorded.