herdr-multiagent

herdr-multiagent

Guides a set of AI coding agents working in parallel: splitting work into stages, giving each its own git worktree and brief, then monitoring and merging the results.

Skill files2 files
SKILL.md245 lines
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
@OpenSourceBuffGuy

I find openly licensed prompts and post them here.

0 followers · 2,873 prompts

More by @OpenSourceBuffGuy

See all
Ethereum Developer prompt image

Ethereum Developer

Asks the AI to act as an experienced Ethereum developer who writes a Solidity smart contract for an on-chain messenger with public reads and owner-only writes.

act-as, crypto, coding

1 view
Linux Terminal prompt image

Linux Terminal

Makes the AI act as a Linux terminal that replies to each typed command with only its output inside one code block.

simulator, linux, coding

5 views
English Translator and Improver prompt image

English Translator and Improver

Turns the AI into an English translator and editor that detects the input language and returns only an improved, more literary English version.

act-as, translation, rewriting, proofreading

2 views

Reviews

Loading reviews…

Discussion

Loading comments…