1
---
2
name: herdr-multiagent
3
description: "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."
4
---
5
6
# Multi-agent work through Herdr
7
8
Playbook: split the project's remaining work into independent stages, put each stage
9
on its own agent in its own git worktree and Herdr pane, hand it a file-based brief,
10
monitor it, and accept the result.
11
12
This skill is agent-agnostic: the kind of the children equals the kind of the
13
orchestrator. Launched from opencode, the children are opencode; from omp, they are
14
omp; from claude, they are claude. Never hardcode the orchestrator's kind from
15
memory and never pick a "popular" kind.
16
17
## 0. Preconditions
18
19
```bash
20
test "${HERDR_ENV:-}" = 1 # if this fails, stop - we are not inside Herdr
21
```
22
23
If the check fails, tell the user the session is not running under Herdr and stop.
24
Do not drive someone else's Herdr from outside it.
25
26
The basic pane/agent commands live in Herdr's own skill (`herdr --skill`).
27
The installed binary is the authority on syntax; when unsure read
28
`herdr agent`, `herdr pane`, `herdr integration` instead of guessing.
29
30
## 1. Determine your own kind - before anything else
31
32
```bash
33
herdr pane current --current
34
```
35
36
The `.result.pane.agent` field IS the orchestrator's kind, and the same value goes
37
to `--kind` for the children:
38
39
```bash
40
KIND=$(herdr pane current --current | jq -r '.result.pane.agent')
41
# without jq:
42
KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1)
43
echo "$KIND"
44
```
45
46
Empty or `unknown` - ask the user which kind to start the children with.
47
Below, `$KIND` always means this resolved value, never a literal.
48
49
Check the Herdr integration for this kind (it provides `agent list/wait/prompt`):
50
51
```bash
52
herdr integration status | grep -i "$KIND"
53
```
54
55
- `current` - good.
56
- `not installed` - run `herdr integration install "$KIND"`. Only **new** sessions
57
pick the integration up, so install it BEFORE starting children; the orchestrator
58
itself stays invisible to `agent list`, which is fine - it needs no monitoring.
59
- The kind is absent from `herdr integration install` (e.g. `amp`, `cline`, `kiro`,
60
`maki`) - there will be no structural monitoring, use the §7 fallback
61
(`pane read` + git). Not a blocker.
62
63
State it explicitly to the user: "children kind = $KIND".
64
65
## 2. Decomposition - the main step, do not rush
66
67
- Read the project plan/spec and the current state (`git log`, tests,
68
`git worktree list`).
69
- Split the remaining work into stages with **non-overlapping file areas**.
70
Two agents on one package - only deliberately and with an explicit order
71
(afterwards, not in parallel).
72
- Additive edits to shared files (config, lock) are acceptable - record in the briefs
73
"additive only, no signature changes"; the orchestrator resolves merge conflicts.
74
- Write down the matrix "stage -> files it MAY / MUST NOT touch".
75
76
Before launch: everything finished in main is committed, the tree is clean.
77
78
## 3. Worktree + isolated environment per agent
79
80
```bash
81
git worktree add ../<proj>-s<N> -b stage-<N>-<name>
82
```
83
84
Python trap: a shared venv imports SOMEONE ELSE's code (editable install of the main
85
repo). Give each worktree its own venv:
86
87
```bash
88
cd ../<proj>-s<N> && python -m venv .venv \
89
&& ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]"
90
```
91
92
Install several venvs sequentially in one background command (the pip cache is shared).
93
JS stack: its own `node_modules` per worktree (`npm ci`).
94
95
If the orchestrator has a command-wrapper hook (rtk and similar): a relative
96
interpreter path (`../.venv/Scripts/python.exe`) in briefs does not resolve through
97
such a hook ("command not found"). In briefs and prompts use only ABSOLUTE paths to
98
the python/npm of that worktree.
99
100
## 4. Briefs - as files, not on the command line
101
102
`<repo>/.briefs/stage-<N>.md` (untracked). Brief structure:
103
104
- **context**: what to read first (spec, contract, key files), what is already done;
105
- **task**: concrete requirements referencing spec items;
106
- **boundaries**: files allowed/forbidden, "do not leave the worktree", "do NOT push";
107
- **acceptance**: exact test/linter commands (with the absolute interpreter path of
108
the worktree), "pre-existing tests stay green", commit to its own branch, final report.
109
110
A brief must not assume a particular agent kind: do not write "run omp/skill/..."
111
into it - write the goal, the boundaries and the acceptance commands. The child
112
decides which of its own tools to use.
113
114
The prompt to the agent is short: "Read the file <brief> and complete it fully".
115
116
## 5. Panes: create them, name them IMMEDIATELY
117
118
Recommended layout - main-left: the orchestrator pane on the left at full height, all
119
children in a column on the right, one under another. If the user has layout plugins
120
built around main-left, any other scheme breaks their view.
121
If the user explicitly asks for a different layout, follow the user.
122
123
First child - `split --current --direction right`, the rest -
124
`split --pane <previous child> --direction down` INSIDE the right column.
125
Do NOT split the orchestrator pane, and do not split agent panes to the right - only
126
the down-chain inside the right column.
127
128
```bash
129
herdr pane split --current --direction right --cwd "<worktree1>" --no-focus
130
herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus
131
```
132
133
The new pane ID comes from JSON `.result.pane.pane_id`. Do not touch the user's focus
134
(`--no-focus`). The child gets its name in step 6 via `agent start`; additionally
135
`herdr pane rename <pane_id> "s<N>-<name>"` for clarity.
136
137
## 6. Starting a child of your own kind
138
139
The standard path is `agent start`, which also validates that the expected agent
140
actually came up in the pane:
141
142
```bash
143
herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <autonomy-flags>
144
```
145
146
The name must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents.
147
148
### Autonomy flags
149
150
A child works unattended, otherwise it stops at an approval. The flag belongs to the
151
CLI, not to Herdr. Confirmed ones:
152
153
| kind | launch |
154
|---|---|
155
| `omp` | `-- --yolo` |
156
| `claude` | `-- --dangerously-skip-permissions` (or `--permission-mode bypassPermissions`) |
157
| `opencode` | `-- --auto` |
158
159
For any other kind (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes,
160
qodercli, mastracode, pi, ...) do NOT invent a flag. Resolve the canonical executable
161
and read its help:
162
163
```bash
164
herdr agent start --help # the --kind help text names the canonical executable
165
<executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow"
166
```
167
168
No flag found - check whether the CLI has an autonomy mode in its config
169
(e.g. `~/.omp/agent/config.yml: tools.approvalMode: yolo`,
170
`~/.claude/settings.json: permissions`, `opencode.json: permission`), and warn the
171
user that the child may stop at approvals - those surface as the `blocked` state (§7).
172
173
### If `agent start` timed out
174
175
Known bug on Windows in PowerShell panes: `agent start` sends a mangled
176
`Start-Process` -> timeout. Workaround - launch the CLI in the pane directly:
177
178
```bash
179
herdr pane run <pane_id> "<executable> <autonomy-flags>"
180
sleep 3 && herdr pane read <pane_id> --lines 15 # expect the CLI prompt
181
herdr agent rename <pane_id> s1-<name> # if herdr recognized the agent
182
```
183
184
If `herdr agent explain <pane_id>` still reports no recognized agent afterwards,
185
structural monitoring is unavailable for that pane - use the §7 fallback.
186
187
### Handing over the brief
188
189
NOT via `pane run`: Enter gets swallowed while the TUI renders the paste. Two steps
190
with a pause:
191
192
```bash
193
herdr 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."
194
sleep 5 && herdr pane send-keys <pane_id> Enter
195
```
196
197
Standard alternative once the integration is installed and `agent start` succeeded:
198
199
```bash
200
herdr agent prompt s1-<name> "Read the file <brief> and complete it fully" --wait --timeout 300000
201
```
202
203
Verify with `pane read` that the brief actually WENT IN: input empty, agent working.
204
205
## 7. Monitoring - through the integration, NOT cron
206
207
```bash
208
herdr agent list # states of all children
209
herdr agent wait s1-<name> --until idle --timeout 1800000
210
herdr agent prompt s1-<name> "<text>" # push an instruction to a working child
211
herdr agent read s1-<name> --lines 40
212
```
213
214
State semantics: `idle` - ready for input and its tab has been seen in the UI;
215
`done` - the same idle state after unseen background work (reading through the CLI
216
does not mark the tab seen); `blocked` - Herdr recognized an approval/question UI,
217
the child is WAITING for a human; `unknown` - an agent is present but cannot be
218
classified, which is NOT evidence of completion.
219
220
Orchestrator loop: `agent wait` in turn or on an event -> acceptance (§8).
221
`blocked` -> `agent read`, understand the question, answer via `agent prompt` or ask
222
the user. Suspicious silence -> `pane read <pane_id>`.
223
224
Keep the `wait` timeout moderate (~30 min) and re-arm it on each return: very large
225
values end up as "timed out".
226
227
Fallback when the integration for `$KIND` is unavailable or `agent explain` did not
228
recognize the child: periodic `herdr pane read <pane_id> --lines 60` plus
229
`git log/status` in the worktree. Cron only as a last resort, and always remove it
230
when done.
231
232
Child session dropped: the work in the worktree survives. Restart with the same CLI
233
and its continue flag (check `--help`): `omp --resume`, `claude --continue`,
234
`opencode --continue`. Then prompt: "Your session was interrupted. Check git status
235
and finish the brief <file>".
236
237
## 8. Acceptance and merge
238
239
- Each branch: tests + linter in its own worktree, review `git diff main...<branch> --stat`.
240
- Do not take the child's final report on faith - run the acceptance commands yourself.
241
- Merge into main only with the user's confirmation; resolve additive overlaps manually.
242
- After the merge: `git worktree remove`; branches as agreed with the user.
243
- Release the children's panes without touching the user's pane.
244
245