Herdr Multiagent: Parallele Codierungs-Agenten-Workflow

--- name: herdr-multiagent description: 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. --- # Multi-Agent Work via Herdr Playbook: break down project tasks into independent stages, assign each stage to a separate agent in its own git worktree and herdr pane, provide a file brief, monitor, and accept the result. The skill is agent-independent: child kind = orchestrator kind. If you started the skill from opencode, children will be opencode; from omp - omp; from claude - claude. Never guess the orchestrator kind from memory and never pick a "popular" kind. ## 0. Prerequisites ```bash test "${HERDR_ENV:-}" = 1 # without this - stop, we are not inside Herdr ``` If the check fails - tell the user that the session is not under Herdr and stop. Do not manage someone else's Herdr from outside. Basic pane/agent commands are in the standard Herdr skill (`herdr --skill`). The installed binary is authoritative for syntax; when in doubt, read `herdr agent`, `herdr pane`, `herdr integration`, do not guess. ## 1. Determine your kind - before any actions ```bash herdr pane current --current ``` The field `.result.pane.agent` is the orchestrator kind, which is also the value for `--kind` for children: ```bash KIND=$(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 launch children with. From here on, `$KIND` refers to the obtained value, not a literal. Check the Herdr ↔ this kind integration (it provides `agent list/wait/prompt`): ```bash herdr integration status | grep -i "$KIND" ``` - `current` - ok. - `not installed` - `herdr integration install "$KIND"`. Integrations are picked up only by **new** sessions, so install it BEFORE launching children; the orchestrator itself will remain invisible to `agent list` - that is normal, it does not need monitoring. - Kind is missing from the `herdr integration install` list (e.g. `amp`, `cline`, `kiro`, `maki`) - no structural monitoring will be available, we work via fallback §7 (`pane read` + git). This is not a blocker. Record and announce to the user: "child kind = $KIND". ## 2. Decomposition - the main step, take your time - Read the project plan/spec and current state (`git log`, tests, `git worktree list`). - Break the remaining work into stages with **non-overlapping file areas**. Two agents on the same package - only deliberately and with an explicit order (sequential, not parallel). - Additive edits to shared files (config, lock) are allowed - write "additive only, no signature changes" into the briefs; merge conflicts will be resolved by the orchestrator. - Record the matrix "stage → files that CAN / MUST NOT be touched". Before launching: everything ready in main is committed, the tree is clean. ## 3. Worktree + isolated environment per agent ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Python project pitfall: a shared venv imports FOREIGN code (editable install of the main repo). Each worktree gets its own venv: ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` Install multiple venvs sequentially in one background command (pip cache is shared). JS stack: own `node_modules` in each worktree (`npm ci`). If the orchestrator has a command wrapper hook (rtk and similar): a relative path to the interpreter (`../.venv/Scripts/python.exe`) in the brief will not resolve through such a hook ("command not found"). In briefs and prompts, use only ABSOLUTE paths to the python/npm of the relevant 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**: specific requirements with references to spec sections; - **boundaries**: files can/cannot, "do not leave the worktree", "do NOT push"; - **acceptance**: exact test/linter commands (with absolute path to the worktree interpreter), "old tests stay green", commit to your own branch, final report. The brief must not assume a specific agent kind: do not write "run omp/skill/..." in it - write the goal, boundaries, and acceptance commands. The child will decide on its own which of its tools to use. Agent prompt is short: "Read the file <brief> and execute it to completion." ## 5. Panes: create, name IMMEDIATELY Recommended layout - main-left: orchestrator pane on the left at full height, all children in a column on the right, one below the other. If the user has layout plugins designed for main-left, any other scheme will break their view. If the user explicitly requests a different layout - follow their request. 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 - only a down-chain in the right column. ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` The new pane ID is from the JSON `.result.pane.pane_id`. Do not touch user focus (`--no-focus`). The child is named in step 6 via `agent start`, plus for clarity `herdr pane rename <pane_id> "s<N>-<name>"`. ## 6. Launching a child of your kind The standard path is `agent start`, which also validates that the expected agent is up in the pane: ```bash herdr 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 flags The child works without a human, otherwise it will stop for approval. The flag depends on the CLI, not on Herdr. Confirmed: | 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. Determine the canonical executable and read its help: ```bash herdr agent start --help # the --kind description lists the canonical executable <executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` Flag not found → check if there is an autonomy mode in the CLI config (e.g. `~/.omp/agent/config.yml: tools.approvalMode: yolo`, `~/.claude/settings.json: permissions`, `opencode.json: permission`), and warn the user that the child may stop for approvals - these appear as `blocked` state (§7). ### If `agent start` fails with a timeout Known bug on Windows in PowerShell panes: `agent start` sends a corrupted `Start-Process` → timeout. Workaround - launch the CLI directly in the pane: ```bash herdr pane run <pane_id> "<executable> <autonomy-flags>" sleep 3 && herdr pane read <pane_id> --lines 15 # expect the CLI prompt herdr agent rename <pane_id> s1-<name> # if herdr recognized the agent ``` If after this `herdr agent explain <pane_id>` does not yield a recognized agent - structural monitoring is unavailable for this pane, we work via fallback §7. ### Delivering the brief NOT via `pane run`: Enter gets swallowed while the TUI renders the paste. In two steps with a pause: ```bash herdr pane send-text <pane_id> "Read the file <absolute path to brief> - this is your brief. Execute it fully to completion (code, tests, linter, commit to your branch), then give a final report." sleep 5 && herdr pane send-keys <pane_id> Enter ``` Standard alternative, when the integration is installed and `agent start` worked: ```bash herdr agent prompt s1-<name> "Read the file <brief> and execute it to completion" --wait --timeout 300000 ``` Verify via `pane read` that the brief WENT OUT: input is empty, the agent is working. ## 7. Monitoring - via integration, NOT cron ```bash herdr agent list # statuses of all children herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<text>" # push extra instruction to a working agent herdr agent read s1-<name> --lines 40 ``` State semantics: `idle` - ready for input and its tab was seen in the UI; `done` - same as idle after invisible background work (reading via CLI does not mark the tab as seen); `blocked` - herdr recognized an approval/question UI, the child is WAITING for a human; `unknown` - the agent exists but has no classification, this is NOT a sign of completion. Orchestrator loop: `agent wait` sequentially or on event → acceptance (§8). `blocked` → `agent read`, understand the question, answer via `agent prompt` or ask the user. Suspicious silence → `pane read <pane_id>`. Keep the `wait` timeout moderate (~30 min) and re-arm on trigger: very large values go into "timed out". Fallback, when integration for `$KIND` is unavailable or `agent explain` did not recognize the child: periodic `herdr pane read <pane_id> --lines 60` + `git log/status` in the worktree. Cron - only as a last resort and must be removed upon completion. Child session interruption: work in the worktree is preserved. Restart - with the same CLI and its resume flag (check in `--help`): `omp --resume`, `claude --continue`, `opencode --continue`. Then prompt: "Session interrupted. Check git status, finish the brief <file> to completion." ## 8. Acceptance and merge - Each branch: tests + linter in its worktree, review `git diff main...<branch> --stat`. - Do not take the child's final report on faith - verify the acceptance commands yourself. - Merge into main - only with user confirmation; resolve additive overlaps manually. - After merge: `git worktree remove`; branches - by agreement with the user. - Free up child panes without touching the user's pane.