herdr-multiagent
Run several coding agents in parallel under Herdr: stage decomposition, one git worktree, isolated env, pane and file brief per agent, state monitoring, review, merge. Child kind is read from `herdr pane current` (.result.pane.agent) and matches the orchestrator (omp, opencode, claude, codex, kimi, ...). Requires HERDR_ENV=1.
Skill files
---name: herdr-multiagentdescription: "Playbook for running several coding agents in parallel under Herdr: stage decomposition, one git worktree + isolated env + pane per agent, file-based briefs, state monitoring, review and merge. Agent-agnostic: the child kind comes from `herdr pane current` (.result.pane.agent) and matches the orchestrator (omp, opencode, claude, codex, kimi, ...). Use for multi-agent parallel work in separate worktrees. Requires HERDR_ENV=1."---# Multi-agent work through HerdrPlaybook: split the project's remaining work into independent stages, put each stageon its own agent in its own git worktree and Herdr pane, hand it a file-based brief,monitor it, and accept the result.This skill is agent-agnostic: the kind of the children equals the kind of theorchestrator. Launched from opencode, the children are opencode; from omp, they areomp; from claude, they are claude. Never hardcode the orchestrator's kind frommemory and never pick a "popular" kind.## 0. Preconditions```bashtest "${HERDR_ENV:-}" = 1 # if this fails, stop - we are not inside Herdr```If the check fails, tell the user the session is not running under Herdr and stop.Do not drive someone else's Herdr from outside it.The basic pane/agent commands live in Herdr's own skill (`herdr --skill`).The installed binary is the authority on syntax; when unsure read`herdr agent`, `herdr pane`, `herdr integration` instead of guessing.## 1. Determine your own kind - before anything else```bashherdr pane current --current```The `.result.pane.agent` field IS the orchestrator's kind, and the same value goesto `--kind` for the children:```bashKIND=$(herdr pane current --current | jq -r '.result.pane.agent')# without jq:KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1)echo "$KIND"```Empty or `unknown` - ask the user which kind to start the children with.Below, `$KIND` always means this resolved value, never a literal.Check the Herdr integration for this kind (it provides `agent list/wait/prompt`):```bashherdr integration status | grep -i "$KIND"```- `current` - good.- `not installed` - run `herdr integration install "$KIND"`. Only **new** sessions pick the integration up, so install it BEFORE starting children; the orchestrator itself stays invisible to `agent list`, which is fine - it needs no monitoring.- The kind is absent from `herdr integration install` (e.g. `amp`, `cline`, `kiro`, `maki`) - there will be no structural monitoring, use the §7 fallback (`pane read` + git). Not a blocker.State it explicitly to the user: "children kind = $KIND".## 2. Decomposition - the main step, do not rush- Read the project plan/spec and the current state (`git log`, tests, `git worktree list`).- Split the remaining work into stages with **non-overlapping file areas**. Two agents on one package - only deliberately and with an explicit order (afterwards, not in parallel).- Additive edits to shared files (config, lock) are acceptable - record in the briefs "additive only, no signature changes"; the orchestrator resolves merge conflicts.- Write down the matrix "stage -> files it MAY / MUST NOT touch".Before launch: everything finished in main is committed, the tree is clean.## 3. Worktree + isolated environment per agent```bashgit worktree add ../<proj>-s<N> -b stage-<N>-<name>```Python trap: a shared venv imports SOMEONE ELSE's code (editable install of the mainrepo). Give each worktree its own venv:```bashcd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]"```Install several venvs sequentially in one background command (the pip cache is shared).JS stack: its own `node_modules` per worktree (`npm ci`).If the orchestrator has a command-wrapper hook (rtk and similar): a relativeinterpreter path (`../.venv/Scripts/python.exe`) in briefs does not resolve throughsuch a hook ("command not found"). In briefs and prompts use only ABSOLUTE paths tothe python/npm of that worktree.## 4. Briefs - as files, not on the command line`<repo>/.briefs/stage-<N>.md` (untracked). Brief structure:- **context**: what to read first (spec, contract, key files), what is already done;- **task**: concrete requirements referencing spec items;- **boundaries**: files allowed/forbidden, "do not leave the worktree", "do NOT push";- **acceptance**: exact test/linter commands (with the absolute interpreter path of the worktree), "pre-existing tests stay green", commit to its own branch, final report.A brief must not assume a particular agent kind: do not write "run omp/skill/..."into it - write the goal, the boundaries and the acceptance commands. The childdecides which of its own tools to use.The prompt to the agent is short: "Read the file <brief> and complete it fully".## 5. Panes: create them, name them IMMEDIATELYRecommended layout - main-left: the orchestrator pane on the left at full height, allchildren in a column on the right, one under another. If the user has layout pluginsbuilt around main-left, any other scheme breaks their view.If the user explicitly asks for a different layout, follow the user.First child - `split --current --direction right`, the rest -`split --pane <previous child> --direction down` INSIDE the right column.Do NOT split the orchestrator pane, and do not split agent panes to the right - onlythe down-chain inside the right column.```bashherdr pane split --current --direction right --cwd "<worktree1>" --no-focusherdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus```The new pane ID comes from JSON `.result.pane.pane_id`. Do not touch the user's focus(`--no-focus`). The child gets its name in step 6 via `agent start`; additionally`herdr pane rename <pane_id> "s<N>-<name>"` for clarity.## 6. Starting a child of your own kindThe standard path is `agent start`, which also validates that the expected agentactually came up in the pane:```bashherdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <autonomy-flags>```The name must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents.### Autonomy flagsA child works unattended, otherwise it stops at an approval. The flag belongs to theCLI, not to Herdr. Confirmed ones:| kind | launch ||---|---|| `omp` | `-- --yolo` || `claude` | `-- --dangerously-skip-permissions` (or `--permission-mode bypassPermissions`) || `opencode` | `-- --auto` |For any other kind (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes,qodercli, mastracode, pi, ...) do NOT invent a flag. Resolve the canonical executableand read its help:```bashherdr agent start --help # the --kind help text names the canonical executable<executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow"```No flag found - check whether the CLI has an autonomy mode in its config(e.g. `~/.omp/agent/config.yml: tools.approvalMode: yolo`,`~/.claude/settings.json: permissions`, `opencode.json: permission`), and warn theuser that the child may stop at approvals - those surface as the `blocked` state (§7).### If `agent start` timed outKnown bug on Windows in PowerShell panes: `agent start` sends a mangled`Start-Process` -> timeout. Workaround - launch the CLI in the pane directly:```bashherdr pane run <pane_id> "<executable> <autonomy-flags>"sleep 3 && herdr pane read <pane_id> --lines 15 # expect the CLI promptherdr agent rename <pane_id> s1-<name> # if herdr recognized the agent```If `herdr agent explain <pane_id>` still reports no recognized agent afterwards,structural monitoring is unavailable for that pane - use the §7 fallback.### Handing over the briefNOT via `pane run`: Enter gets swallowed while the TUI renders the paste. Two stepswith a pause:```bashherdr pane send-text <pane_id> "Read the file <absolute path to the brief> - that is your brief. Complete it fully (code, tests, linter, commit to your own branch), then give a final report."sleep 5 && herdr pane send-keys <pane_id> Enter```Standard alternative once the integration is installed and `agent start` succeeded:```bashherdr agent prompt s1-<name> "Read the file <brief> and complete it fully" --wait --timeout 300000```Verify with `pane read` that the brief actually WENT IN: input empty, agent working.## 7. Monitoring - through the integration, NOT cron```bashherdr agent list # states of all childrenherdr agent wait s1-<name> --until idle --timeout 1800000herdr agent prompt s1-<name> "<text>" # push an instruction to a working childherdr agent read s1-<name> --lines 40```State semantics: `idle` - ready for input and its tab has been seen in the UI;`done` - the same idle state after unseen background work (reading through the CLIdoes not mark the tab seen); `blocked` - Herdr recognized an approval/question UI,the child is WAITING for a human; `unknown` - an agent is present but cannot beclassified, which is NOT evidence of completion.Orchestrator loop: `agent wait` in turn or on an event -> acceptance (§8).`blocked` -> `agent read`, understand the question, answer via `agent prompt` or askthe user. Suspicious silence -> `pane read <pane_id>`.Keep the `wait` timeout moderate (~30 min) and re-arm it on each return: very largevalues end up as "timed out".Fallback when the integration for `$KIND` is unavailable or `agent explain` did notrecognize the child: periodic `herdr pane read <pane_id> --lines 60` plus`git log/status` in the worktree. Cron only as a last resort, and always remove itwhen done.Child session dropped: the work in the worktree survives. Restart with the same CLIand its continue flag (check `--help`): `omp --resume`, `claude --continue`,`opencode --continue`. Then prompt: "Your session was interrupted. Check git statusand finish the brief <file>".## 8. Acceptance and merge- Each branch: tests + linter in its own worktree, review `git diff main...<branch> --stat`.- Do not take the child's final report on faith - run the acceptance commands yourself.- Merge into main only with the user's confirmation; resolve additive overlaps manually.- After the merge: `git worktree remove`; branches as agreed with the user.- Release the children's panes without touching the user's pane.Prompts come from prompts.chat, an open community library dedicated to the public domain (CC0). We refresh our copy every week.