/herdr-agent

name: herdr-agent
description: "Manage AI agent fleets in Herdr: tile root + sub-agents in one tab, start/prompt/wait/read/monitor via the herdr agent CLI, steer any pane; `help` lists every operation. Use for Herdr fleets. Don't use for tmux, screen, or non-Herdr terminals."
license: MIT
compatibility: "Requires herdr 0.9.0 or later on PATH and a running Herdr server (`herdr status`) for every operation except `help`, which runs no herdr command. Default same-kind launches also require `pane process-info` to return full argv; `--without flags` explicitly opts out."
effort: medium
metadata:
  version: 3.2.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

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

| Request | Follow | |---|---| | `help`, or what this does and how to drive it | Help in `references/help-request.md` — answer and stop | | Spawn sub-agents beside root | Phases 1–2, then 4–5 if assigning work | | Message an existing agent | Phases 3–5 | | Read without sending | Phase 3, then Phase 5 read only | | Check what the fleet is doing | Phase 6 | | Broadcast to a fleet | Phases 3 and 7 | | Focus/steer a pane | Phase 3, then Phase 7 | | Close workers | Phase 7 teardown | | Main agent's own context is filling up | Phase 8 HANDOFF |

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.** Sta