翻译时结构校验未通过（标题数不一致：原文 22，译文 15；结构化行数减少：原文 65，译文 36；标题数不一致：原文 22，译文 16；结构化行数减少：原文 65，译文 43），译文可能有格式偏差，建议对照英文原文使用。

中文译文

通过 Herdr 进行多智能体工作

操作手册：把项目剩余的工作拆分成独立的阶段，将每个阶段交给一个专属的智能体，运行在它自己的 git worktree 和 Herdr 窗格中，递给它一份基于文件的简报，监控其进展，并验收其结果。

本技能与智能体类型无关：子智能体的类型等于编排器的类型。从 opencode 启动时，子智能体就是 opencode；从 omp 启动时，它们就是 omp；从 claude 启动时，它们就是 claude。绝不凭记忆硬编码编排器的类型，也绝不挑选某种“流行”的类型。

0. 前提条件

test "${HERDR_ENV:-}" = 1   # if this fails, stop - we are not inside Herdr

如果检查失败，告诉用户该会话并未运行在 Herdr 之下，然后停止。绝不要从外部操控他人的 Herdr。

基本的 pane/agent 命令位于 Herdr 自身的 skill（herdr --skill）中。已安装的二进制文件是语法的权威；不确定时请阅读 herdr agent、herdr pane、herdr integration，而不是凭空猜测。

1. 确定你自己的类型——在做任何其他事情之前

herdr pane current --current

.result.pane.agent 字段就是编排器的 kind，同一个值会作为子项的 --kind 传入：

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"

为空或 unknown - 询问用户要用哪种 kind 来启动子项。下文中，$KIND 始终表示这个解析后的值，绝不是字面量。

查看此 kind 对应的 Herdr 集成（它提供 agent list/wait/prompt）：

herdr integration status | grep -i "$KIND"

git worktree add ../<proj>-s<N> -b stage-<N>-<name>

Python 陷阱：共享的 venv 会导入别人的代码（主仓库的可编辑安装）。为每个 worktree 配置独立的 venv：

cd ../<proj>-s<N> && python -m venv .venv \
  && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]"

herdr pane split --current --direction right --cwd "<worktree1>" --no-focus
herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus

新的窗格 ID 来自 JSON .result.pane.pane_id。不要触碰用户的焦点（--no-focus）。子代理会在第 6 步通过 agent start 获得名称；此外为了清晰起见，还要执行 herdr pane rename <pane_id> "s<N>-<name>"。

6. 启动与你同类的子代理

标准路径是 agent start，它还会验证预期的代理是否确实已在窗格中启动：

herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <autonomy-flags>

名称必须匹配 [a-z][a-z0-9_-]{0,31}，且在活跃的 agent 中唯一。

自主性标志

子 agent 无人值守地运行，否则它会在需要批准时停下。该标志属于 CLI，而不是 Herdr。已确认的如下：

类型	启动参数
`omp`	`-- --yolo`
`claude`	`-- --dangerously-skip-permissions`（或 `--permission-mode bypassPermissions`）
`opencode`	`-- --auto`

对于其他任何类型（codex、gemini、kimi、cursor、copilot、droid、kilo、grok、hermes、 qodercli、mastracode、pi 等），绝不要凭空编造标志。请解析规范的可执行文件并阅读其帮助信息：

herdr agent start --help        # the --kind help text names the canonical executable
<executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow"

未找到标志 - 检查 CLI 的配置中是否有自主模式（例如 ~/.omp/agent/config.yml: tools.approvalMode: yolo、 ~/.claude/settings.json: permissions、opencode.json: permission），并警告用户子进程可能会在审批处停下 - 这些情况会表现为 blocked 状态（§7）。

如果 `agent start` 超时

Windows 上 PowerShell 面板中的已知 bug：agent start 发送的 Start-Process 格式错乱 -> 超时。解决方法 - 直接在面板中启动 CLI：

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

如果 herdr agent explain <pane_id> 之后仍报告未识别到任何 agent，则该窗格的结构化监控不可用——请使用 §7 的后备方案。

交接简报

绝不通过 pane run：在 TUI 渲染粘贴内容时回车键会被吞掉。分两步进行，中间稍作停顿：

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."
sleep 5 && herdr pane send-keys <pane_id> Enter

集成安装完成且 agent start 成功后的标准替代方案：

herdr agent prompt s1-<name> "Read the file <brief> and complete it fully" --wait --timeout 300000

用 pane read 验证任务简报确实已经写入：输入为空，agent 正在运行。

7. 监控 - 通过集成，而非 cron

herdr agent list                       # states of all children
herdr agent wait s1-<name> --until idle --timeout 1800000
herdr agent prompt s1-<name> "<text>"  # push an instruction to a working child
herdr agent read s1-<name> --lines 40

该技能是 agent-agnostic（与具体代理无关）的：子代理的类型从 Herdr 解析得出，并与编排器的类型一致。从 opencode 启动时，子代理就是 opencode；从 omp 启动时，它们就是 omp；从 claude 启动时，它们就是 claude。任何由 herdr agent start --help 列出的类型都可用（pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, maki）。

涵盖内容

§1 解析自身的类型，并验证其对应的 Herdr 集成；
§2 分解为多个阶段，各阶段的文件区域互不重叠；
§3 worktree + 隔离环境（各自的 venv / node_modules —— 否则代理会通过主仓库的可编辑安装导入他人的代码）；
§4 简报以文件形式传递，而非放在命令行上；
§5 主窗格居左的布局，--no-focus（绝不抢占用户的焦点）；
§6 启动子代理，各类型对应的自主性标志，Windows 下 agent start 超时的解决办法，正确的简报交接（回车键会被 pane run 吞掉）；
§7 通过 herdr agent list/wait/prompt/read 进行监控，idle/done/blocked/unknown 的语义，回退到 pane read + git，恢复掉线的子代理会话；
§8 仅在用户确认后才进行验收与合并。

要求

Herdr，且会话运行在其某个窗格内（HERDR_ENV=1）。在 Herdr 之外，该技能即停止。
Git（worktree）。
PATH 中有一个受支持的代理 CLI。
若需结构化监控：herdr integration install <kind>。没有集成的类型会回退到 pane read + git —— 这并非阻碍。
已在 Windows 上验证（Git Bash + PowerShell 窗格）；命令均为 POSIX 风格，并在 Windows venv 路径存在差异之处给出明确说明。

安装

技能是一个包含 SKILL.md 的目录。请将其放入你的代理的技能根目录：

Agent	路径（已在作者机器上验证）
omp, pi	`~/.agents/skills/herdr-multiagent/SKILL.md`
Claude Code	`~/.claude/skills/herdr-multiagent/SKILL.md`
opencode	`~/.config/opencode/skills/herdr-multiagent/SKILL.md`
项目本地	`<repo>/.agents/skills/herdr-multiagent/SKILL.md`

目录结构不是递归的：<skills-root>/<skill-name>/SKILL.md。嵌套路径如 skills/team/herdr-multiagent/SKILL.md 不会被识别。

请查阅你自己 CLI 的文档以确认确切的 skills 根目录——各 agent 的目录有所不同，而带 name + description frontmatter 的 SKILL.md 则以相同方式被读取。

用法

显式方式：要求 agent “按照 herdr-multiagent 技能工作”，或者调用 /skill:herdr-multiagent（在 omp 中，当 skill 命令已启用时）。

自动方式：当任务描述类似于“用多个 agent 并行构建这个”且 agent 运行在 Herdr 中时，该技能会被自动选用。

agent 做的第一件事是检查 HERDR_ENV=1 并确定自身的类型；然后它会提出一种任务分解方案，并在启动任何子 agent 之前请求确认。

目录结构

herdr-multiagent/
├─ SKILL.md      # the skill body: frontmatter (name, description) + §0–§8
└─ README.md     # this file, for humans; the agent does not need it

额外资源（脚本、简报模板、references/*.md）放入同一目录，由智能体通过 skill://herdr-multiagent/<path> 读取。这里没有此类资源：操作手册可容纳在单个文件中，简报模板则在 §4 中以文字形式描述。

安全

子智能体以自主模式运行（omp --yolo、claude --dangerously-skip-permissions、opencode --auto）——没有审批提示。这意味着在其工作树内拥有完整的文件系统和 shell 访问权限。该技能通过简报约束它们（“不要离开工作树”、“绝不推送”），但这只是一条指令，而非隔离。合并到 main 仅在用户明确确认后才会进行。

许可证

可自由使用。

English original

Multi-agent work through Herdr

Playbook: split the project's remaining work into independent stages, put each stage on 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 the orchestrator. Launched from opencode, the children are opencode; from omp, they are omp; from claude, they are claude. Never hardcode the orchestrator's kind from memory and never pick a "popular" kind.

0. Preconditions

test "${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

herdr pane current --current

The .result.pane.agent field IS the orchestrator's kind, and the same value goes to --kind for the children:

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 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):

herdr 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

git worktree add ../<proj>-s<N> -b stage-<N>-<name>

Python trap: a shared venv imports SOMEONE ELSE's code (editable install of the main repo). Give each worktree its own venv:

cd ../<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 relative interpreter path (../.venv/Scripts/python.exe) in briefs does not resolve through such a hook ("command not found"). In briefs and prompts use only ABSOLUTE paths to the 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 child decides which of its own tools to use.

The prompt to the agent is short: "Read the file and complete it fully".

5. Panes: create them, name them IMMEDIATELY

Recommended layout - main-left: the orchestrator pane on the left at full height, all children in a column on the right, one under another. If the user has layout plugins built 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 - only the down-chain inside the right column.

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 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 kind

The standard path is agent start, which also validates that the expected agent actually came up in the pane:

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

A child works unattended, otherwise it stops at an approval. The flag belongs to the CLI, 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 executable and read its help:

herdr 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 the user that the child may stop at approvals - those surface as the blocked state (§7).

If `agent start` timed out

Known bug on Windows in PowerShell panes: agent start sends a mangled Start-Process -> timeout. Workaround - launch the CLI in the pane directly:

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 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 brief

NOT via pane run: Enter gets swallowed while the TUI renders the paste. Two steps with a pause:

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."
sleep 5 && herdr pane send-keys <pane_id> Enter

Standard alternative once the integration is installed and agent start succeeded:

herdr 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

herdr agent list                       # states of all children
herdr agent wait s1-<name> --until idle --timeout 1800000
herdr agent prompt s1-<name> "<text>"  # push an instruction to a working child
herdr 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 CLI does 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 be classified, 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 ask the user. Suspicious silence -> pane read <pane_id>.

Keep the wait timeout moderate (~30 min) and re-arm it on each return: very large values end up as "timed out".

Fallback when the integration for $KIND is unavailable or agent explain did not recognize 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 it when done.

Child session dropped: the work in the worktree survives. Restart with the same CLI and its continue flag (check --help): omp --resume, claude --continue, opencode --continue. Then prompt: "Your session was interrupted. Check git status and finish the brief ".

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.

FILE:README.md

herdr-multiagent

An agent skill (playbook) for driving a project with several coding agents in parallel through Herdr, a terminal multiplexer for coding agents — one git worktree and one pane per stage, file-based briefs, state monitoring and acceptance.

The skill is agent-agnostic: the kind of the children is resolved from Herdr and matches the kind of the orchestrator. Launched from opencode, the children are opencode; from omp, they are omp; from claude, they are claude. Any kind listed by herdr agent start --help works (pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, maki).

What it covers

§1 resolve your own kind, verify the Herdr integration for it;
§2 decompose into stages with non-overlapping file areas;
§3 worktree + isolated environment (own venv / node_modules — otherwise agents import someone else's code through the main repo's editable install);
§4 briefs as files, not on the command line;
§5 main-left pane layout, --no-focus (the user's focus is never taken);
§6 starting a child, autonomy flags per kind, the Windows agent start timeout workaround, correct brief hand-over (Enter gets swallowed by pane run);
§7 monitoring via herdr agent list/wait/prompt/read, the semantics of idle/done/blocked/unknown, fallback to pane read + git, recovering a dropped child session;
§8 acceptance and merge only with the user's confirmation.

Requirements

Herdr, with the session running inside one of its panes (HERDR_ENV=1). Outside Herdr the skill stops.
Git (worktrees).
One supported agent CLI on PATH.
For structural monitoring: herdr integration install <kind>. Kinds without an integration fall back to pane read + git — not a blocker.
Verified on Windows (Git Bash + PowerShell panes); the commands are POSIX, with an explicit note where Windows venv paths differ.

Installation

A skill is a directory containing SKILL.md. Put it into your agent's skills root:

Agent	path (verified on the author's machine)
omp, pi	`~/.agents/skills/herdr-multiagent/SKILL.md`
Claude Code	`~/.claude/skills/herdr-multiagent/SKILL.md`
opencode	`~/.config/opencode/skills/herdr-multiagent/SKILL.md`
project-local	`<repo>/.agents/skills/herdr-multiagent/SKILL.md`

The layout is non-recursive: <skills-root>/<skill-name>/SKILL.md. A nested path like skills/team/herdr-multiagent/SKILL.md is not discovered.

Check your own CLI's docs for the exact skills root — the directories differ per agent, while SKILL.md with name + description frontmatter is read the same way.

Usage

Explicitly: ask the agent to "work according to the herdr-multiagent skill", or invoke /skill:herdr-multiagent (in omp, when skill commands are enabled).

Automatically: the skill is picked up when the task reads like "build this with several agents in parallel" and the agent runs inside Herdr.

The first thing the agent does is check HERDR_ENV=1 and resolve its own kind; then it proposes a decomposition and asks for confirmation before starting any child.

Layout

herdr-multiagent/
├─ SKILL.md      # the skill body: frontmatter (name, description) + §0–§8
└─ README.md     # this file, for humans; the agent does not need it

Extra assets (scripts, brief templates, references/*.md) go into the same directory and are read by the agent via skill://herdr-multiagent/<path>. There are none here: the playbook fits in a single file, and the brief template is described in prose in §4.

Safety

Children run in an autonomy mode (omp --yolo, claude --dangerously-skip-permissions, opencode --auto) — without approval prompts. That means full filesystem and shell access inside their worktree. The skill constrains them through the brief ("do not leave the worktree", "do NOT push"), but that is an instruction, not isolation. Merging into main happens only on the user's explicit confirmation.

License

Free to use.