Herdr voice dispatcher

Translate conversational requests into bounded Herdr CLI actions. This skill is an external controller for Codex Voice or chat, so it intentionally works without HERDR_ENV=1.

Connect

1. Run the concise inventory without native session references:

   python3 ~/.agents/skills/herdr-voice-dispatcher/scripts/list_agents.py
   

2. If Herdr is unavailable, report the exact error.

   • For Operation not permitted, ask the user to run the Codex task with Full Access; a skill cannot bypass the sandbox.

3. Do not dump raw herdr agent list output. It includes noisy native session references.

Resolve the target

• Use an exact live agent name or pane ID.

• If the user names a project, title, or directory, filter the inventory:

  python3 ~/.agents/skills/herdr-voice-dispatcher/scripts/list_agents.py --query dotfiles
  

• Treat labels such as omp or codex as agent kinds, not unique targets, when several matches exist.

• If more than one candidate remains, ask one concise clarification. Never guess a pane.

Act

List or check status: use the inventory helper. Use herdr agent get "$target" only when more detail about one resolved agent is necessary.

Dispatch work: preserve the user's requested outcome and constraints, then submit without waiting:

herdr agent prompt "$target" "$prompt"

Report only that Herdr accepted the prompt. If the target was already working, explain that Herdr lifecycle state does not correlate completion to an individual queued turn.

Read a result: check status, then read bounded output:

herdr agent read "$target" --source recent-unwrapped --lines 80

If recent output is incomplete because the agent uses an alternate screen, use --source visible. Do not claim success from unknown state or truncated output.

Wait when explicitly requested: keep Voice responsive with a bounded wait:

herdr agent wait "$target" \
  --until idle --until done --until blocked \
  --timeout 60000

If the agent becomes blocked, read and relay its question. Do not answer it for the user.

Guardrails

1. Prompt only the target and intent the user authorized.
2. Never start, stop, focus, interrupt, send keys, or answer an approval unless the user explicitly requests that exact action.
3. Treat dispatch as an external state change; a zero exit status proves submission, not task completion.
4. Do not expose agent session paths or unrelated terminal content.
5. Never wait indefinitely. Return control after 60 seconds and offer a fresh status check.

Spoken examples

• “Which Herdr agents need attention?” → list and summarize blocked, working, and done.
• “Tell the dotfiles reviewer to inspect the current diff without editing.” → resolve one target, dispatch once, and return immediately.
• “What did the reviewer say?” → check its state, then read bounded output.
• “The reviewer is blocked—what does it need?” → read and relay the question without answering it.