herdr-agents

Herdr Agents

The subagents skill decides the scopes. This skill runs each scope in its own checkout.

Guard: test "${HERDR_ENV:-}" = 1. If it fails, say so and dispatch with the Agent tool. Read-only Explore work always uses the Agent tool.

Mail

The bundled herdr-mail plugin holds mail until the recipient is idle. Its hooks mail each child's done, blocked, and exited states to the parent. Check it once per run:

mail="${CLAUDE_SKILL_DIR}/assets/herdr-mail/bin/herdr-mail"
herdr plugin list --json | jq -e --arg r "${CLAUDE_SKILL_DIR}/assets/herdr-mail" \
  '.result.plugins[] | select(.plugin_id == "skrrt.herdr-mail" and .plugin_root == $r)'

No match: ask the user, then run herdr plugin link "${CLAUDE_SKILL_DIR}/assets/herdr-mail". It runs in every Herdr session. Suggest allowing Bash(<$mail path>:*), or each child stops on a permission prompt at its first send.

Dispatch

Once per run, confirm herdr worktree create, herdr agent start, and $mail are allowed. If not, ask the user once for the rules, not per agent.

Once per stage, snapshot the base: base=$(git stash create), or HEAD on a clean tree. It captures the integrated earlier stages without committing or signing.

Per scope. Name the agent after the scope, matching [a-z][a-z0-9_-]{0,31}. Read every ID from JSON.

ws=$(herdr worktree create --cwd "$PWD" --branch "scope/$name" --base "${base:-HEAD}" --label "$name" --no-focus)
pane=$(jq -r .result.root_pane.pane_id <<<"$ws")    # also keep .result.workspace.workspace_id
herdr agent start "$name" --kind claude --pane "$pane" -- --model opus
"$mail" watch "$name"
herdr agent prompt "$name" "$(cat <<'EOF'
<brief, ending with the protocol below>
EOF
)" --wait --until working --timeout 30000

• --until working confirms delivery and returns. Start the whole stage before waiting on any agent.
• Use another kind, model, or permission mode only when the user names one.
• Install dependencies in the checkout before prompting. Get its path from herdr worktree list --cwd "$PWD". Never copy .env files into it.
• Never seed a checkout with a patch or share one checkout between agents.
• New work gets a new agent and worktree. Never re-brief a finished agent.