luongnv89/herdr-agent-comms

Herdr Agent Comms

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; equalize all columns; then send, wait, read, steer, or tear down through the herdr CLI.

Use Herdr concepts, not tmux assumptions. Prefer status-aware helpers and relay reply deltas rather than whole panes to protect the context and token budget.

Choose the Workflow

| Request | Follow | |---|---| | 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 | | Broadcast to a fleet | Phases 3 and 6 | | Focus/steer a pane | Phase 3, then Phase 6 | | Close workers | Phase 6 teardown |

Read only the reference needed by that branch:

• See references/herdr-recipes.md for guarded grid spawning, equalization semantics, multi-line sends, focus, and troubleshooting.
• See references/delivery-and-waiting.md for preflight, completion markers, delivery verification, wait outcomes, and concurrent waits.

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. 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.
3. Run agents directly in Herdr panes. Do not nest tmux when agent detection is required.
4. Treat the installed CLI as authoritative. Check uncertain commands with herdr <group> rather than inventing flags.

Follow Non-Negotiable Rules

1. Keep root. Never replace or close the root pane during fleet work.
2. Parse IDs. Read opaque workspace/tab/pane IDs from JSON; never infer them from display order.
3. 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.
4. Fail closed before writes. Reject missing, ambiguous, working, blocked, malformed, or off-enum targets. Only a verified safe status may receive input.
5. Wait before follow-ups. Never send while an agent is working. Every follow-up gets a fresh baseline and completion marker.
6. Surface blockers. A trust, auth, or permission prompt needs a human; do not type a task or recovery Enter into it.
7. Confirm destruction. Closing panes, tabs, workspaces, or the server can lose work. Obtain explicit approval and preserve root unless the user says otherwise.

Phase 1 — Resolve Root Context

command -v herdr >/dev/null || { echo "Error: herdr is not installed" >&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:?}"

Outside Herdr, list workspaces and agents, then choose the user-named or focused root. Resolve project_dir from the root pane's cwd, falling back to the current directory.

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

Phase 2 — Spawn and Ready the Fleet

Before spawning, define each worker's unique name, CLI/model settings, task, and expected deliverable. Launch the interactive CLI first; submit the task only after readiness passes.

Resolve the scripts directory by checking repo-local installs before global ones. Then 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.
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 and agent, then launch the CLI with herdr pane run.
6. After all workers launch, run concurrent wait_for_idle.py --ready checks. Assign no work unless every worker returns 0.

Use pi --model ... --thinking ... --skill ..., or verified flags for Claude Code, Codex, or OpenCode. Do not attach the long task to the initial launcher argv.

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, and all readiness checks pass.

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. Record both the name and pane ID and use that same pane ID for every later mutation.

Done when: one existing target resolves uniquely and its status is valid.

Phase 4 — Send Safely

Follow the canonical baseline → marker → preflight → send → delivery-check sequence in references/delivery-and-waiting.md:

1. Capture recent-unwrapped output to a baseline file before sending.
2. Create a fresh split HERDR_DONE_ completion marker.
3. Run scripts/preflight_send.py immediately before dispatch.
4. Submit with herdr pane run "$pane_id" "$task".
5. Verify working status or transcript activity. Transcript activity may be prompt echo; only the joined marker proves completion.

For multi-line payloads or literal typing, use the guarded recipes in references/herdr-recipes.md. Re-run preflight immediately before any recovery Enter.

Done when: dispatch succeeded and status or transcript activity proves delivery; otherwise return a descriptive error.

Phase 5 — Wait, Read, and Verify

Run scripts/wait_for_idle.py with the pre-send baseline and fresh completion marker. Handle its result: 0 completed, 1 error, 2 timeout, 3 blocked. Propagate non-zero results; do not report them as replies.

Accept idle or done after observed work. Read a capped recent-unwrapped transcript and relay only the relevant delta. On timeout, inspect pane get, pane read, and agent explain; stop after the bounded retry budget.

Done when: the requested reply is captured and verified, or blocked/timeout evidence is reported without further writes.

Phase 6 — Broadcast, Steer, or Tear Down

• Broadcast: run scripts/broadcast.sh "<task>" <targets...>. It resolves targets, preflights, baselines, dispatches safe panes first, waits concurrently, and fails if any target is skipped or unsuccessful.
• Steer: focus with herdr agent focus <name>. For CLI follow-ups, repeat Phases 4–5 with a new baseline and marker.
• Tear down: after explicit confirmation, close only worker panes created by this run. Close the root tab, workspace, or server only when explicitly requested.

Done when: every requested target has a recorded outcome and destructive actions match the user's confirmed scope.

Verify Expected Output

Expected output for a successful fleet operation:

Fleet: PASS
Root kept: w26:p1
Workers: reviewer=done, tests=idle
Layout: 3 equal-width columns
Replies: 2 captured, 0 blocked, 0 timed out

Acceptance criteria:

• herdr status succeeds and every target resolves uniquely.
• Root remains in its original pane and all default workers share its tab.
• Spawned columns are equal within one terminal cell.
• Every send passes preflight and every completed reply has delivery evidence.
• Every agent ends as completed, blocked, timed out, or failed—none disappear from the report.
• Errors and destructive confirmations are surfaced explicitly.

Handle Edge Cases

• blocked: show the dialog and request human action.
• unknown: use the wait helper's stability fallback or install the integration.
• Name collision: suffix the requested name; never reuse an existing agent accidentally.
• More than four panes: warn that columns become cramped; change layout only with user approval.
• Unequal grid: rerun the equalizer and abort worker launch if it still fails.
• Wrong workspace or accidental tab: stop, preserve work, and ask before moving or closing panes.

Emit the Step Completion Report

◆ Herdr Agent Comms ([operation])
··································································
  Server:              √ pass
  Root resolved:       √ pass (pane · tab · workspace)
  Targets:             √ pass (N/N unique)
  Layout/readiness:    √ pass (if spawning; otherwise — n/a)
  Delivery:            √ pass (if sending; otherwise — n/a)
  Replies:             √ pass (done|idle · blocked/timeouts reported)
  Destructive action:  — none (or confirmed scope)
  Result:              PASS | FAIL | PARTIAL