# Мультиагентная работа через Herdr ## Файл: SKILL.md --- name: herdr-multiagent description: Координирует параллельную работу нескольких кодовых агентов через Herdr: этапы, отдельные git worktree и окружения, брифы, мониторинг, проверка и слияние результатов. Тип потомков берётся из `herdr pane current` и совпадает с типом оркестратора. Требуется HERDR_ENV=1. --- # Мультиагентная работа через Herdr Плейбук: разложить задачи проекта на независимые этапы, посадить на каждый этап отдельный агент в своём git worktree и herdr-пейне, выдать файловый бриф, мониторить и принять результат. Скилл агент-независим: kind потомков = kind оркестратора. Запустил скилл из opencode — потомки будут opencode; из omp — omp; из claude — claude. Никогда не подставляй kind оркестратора по памяти и не выбирай «популярный» kind. ## 0. Предусловия ```bash test "${HERDR_ENV:-}" = 1 # без этого — стоп, мы не внутри Herdr ``` Если проверка не прошла — сказать пользователю, что сессия не под Herdr, и остановиться. Не управлять чужим Herdr снаружи. Базовые команды пейнов/агентов — в штатном скилле Herdr (`herdr --skill`). Установленный бинарник — авторитет по синтаксису; при сомнении читай `herdr agent`, `herdr pane`, `herdr integration`, а не гадай. ## 1. Определить свой kind — до любых действий ```bash herdr pane current --current ``` Поле `.result.pane.agent` — это и есть kind оркестратора, он же значение для `--kind` у потомков: ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # без jq: KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` Пусто или `unknown` — спросить пользователя, каким kind запускать потомков. Дальше по тексту `$KIND` — это полученное значение, не литерал. Проверить интеграцию Herdr ↔ этот kind (она даёт `agent list/wait/prompt`): ```bash herdr integration status | grep -i "$KIND" ``` - `current` — ок. - `not installed` — `herdr integration install "$KIND"`. Интеграцию подхватывают только **новые** сессии, поэтому ставить её ДО запуска потомков; сам оркестратор останется невидимым для `agent list` — это нормально, его мониторить не нужно. - kind отсутствует в списке `herdr integration install` (например `amp`, `cline`, `kiro`, `maki`) — структурного мониторинга не будет, работаем по fallback §7 (`pane read` + git). Это не блокер. Зафиксировать и объявить пользователю: «kind потомков = $KIND». ## 2. Декомпозиция — главный шаг, не торопись - Прочитай план/спеку проекта и текущее состояние (`git log`, тесты, `git worktree list`). - Разбей оставшуюся работу на этапы с **непересекающимися файловыми областями**. Два агента над одним пакетом — только осознанно и с явным порядком (после, не параллельно). - Аддитивные правки общих файлов (config, lock) допустимы — записать в брифы «только аддитивно, без смены сигнатур»; мерж-конфликты разрулит оркестратор. - Зафиксируй матрицу «этап → файлы, которые МОЖНО / НЕЛЬЗЯ трогать». Перед запуском: всё готовое в main закоммичено, дерево чистое. ## 3. Worktree + изолированное окружение на агента ```bash git worktree add ../-s -b stage-- ``` Ловушка Python-проектов: общий venv импортирует ЧУЖОЙ код (editable install основного репо). Каждому worktree — свой venv: ```bash cd ../-s && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` Несколько venv ставить последовательно одной фоновой командой (pip cache общий). JS-стек: свои `node_modules` в каждом worktree (`npm ci`). Если у оркестратора есть хук-обёртка команд (rtk и подобные): относительный путь к интерпретатору (`../.venv/Scripts/python.exe`) в брифах через такой хук не резолвится («command not found»). В брифах и промптах — только АБСОЛЮТНЫЕ пути к python/npm нужного worktree. ## 4. Брифы — файлами, не в командной строке `/.briefs/stage-.md` (untracked). Структура брифа: - **контекст**: что читать первым (спека, контракт, ключевые файлы), что уже сделано; - **задача**: конкретные требования со ссылками на пункты спеки; - **границы**: файлы можно/нельзя, «не выходи из worktree», «push НЕ делать»; - **приёмка**: точные команды тестов/линтера (с абсолютным путём к интерпретатору worktree), «старые тесты остаются зелёными», коммит в свою ветку, финальный отчёт. Бриф не должен предполагать конкретный kind агента: не пиши в него «запусти omp/skill/...» — пиши цель, границы и команды приёмки. Потомок сам решит, какими своими инструментами это сделать. Промпт агенту короткий: «Прочитай файл <бриф> и выполни до конца». ## 5. Пейны: создать, СРАЗУ назвать Рекомендуемая раскладка — main-left: пейн оркестратора слева на всю высоту, все потомки колонкой справа друг под другом. Если у пользователя стоят плагины раскладок, рассчитанные на main-left, любая другая схема сломает ему обзор. Если пользователь явно просит другую раскладку — выполнять его. Первый потомок — `split --current --direction right`, остальные — `split --pane <предыдущий потомок> --direction down` ВНУТРИ правой колонки. НЕ сплитить пейн оркестратора и не сплитить агентские пейны вправо — только down-цепочка в правой колонке. ```bash herdr pane split --current --direction right --cwd "" --no-focus herdr pane split --pane --direction down --cwd "" --no-focus ``` ID нового пейна — из JSON `.result.pane.pane_id`. Фокус пользователя не трогать (`--no-focus`). Имя потомку даётся на шаге 6 через `agent start`, плюс для наглядности `herdr pane rename "s-"`. ## 6. Запуск потомка своего kind Штатный путь — `agent start`, он же валидирует, что в пейне поднялся именно ожидаемый агент: ```bash herdr agent start s1- --kind "$KIND" --pane -- <флаги-автономности> ``` Имя должно матчить `[a-z][a-z0-9_-]{0,31}` и быть уникальным среди живых агентов. ### Флаги автономности Потомок работает без человека, иначе встанет на аппруве. Флаг зависит от CLI, а не от Herdr. Подтверждённые: | kind | запуск | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions` (или `--permission-mode bypassPermissions`) | | `opencode` | `-- --auto` | Для любого другого kind (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes, qodercli, mastracode, pi, …) — НЕ выдумывать флаг. Определить canonical исполняемый файл и прочитать его справку: ```bash herdr agent start --help # в описании --kind указан canonical 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-пейнах: `agent start` шлёт искажённый `Start-Process` → таймаут. Обход — поднять CLI в пейне напрямую: ```bash herdr pane run " <флаги-автономности>" sleep 3 && herdr pane read --lines 15 # ожидаем промпт CLI herdr agent rename s1- # если herdr распознал агента ``` Если после этого `herdr agent explain ` не даёт распознанного агента — структурный мониторинг для этого пейна недоступен, работаем по fallback §7. ### Выдача брифа НЕ через `pane run`: Enter проглатывается, пока TUI рендерит вставку. В два шага с паузой: ```bash herdr pane send-text "Прочитай файл <абсолютный путь к брифу> — это твой бриф. Выполни полностью до конца (код, тесты, линтер, коммит в свою ветку), затем дай финальный отчёт." sleep 5 && herdr pane send-keys Enter ``` Штатная альтернатива, когда интеграция стоит и `agent start` отработал: ```bash herdr agent prompt s1- "Прочитай файл <бриф> и выполни до конца" --wait --timeout 300000 ``` Проверить по `pane read`, что бриф УШЁЛ: input пустой, агент работает. ## 7. Мониторинг — через интеграцию, НЕ cron ```bash herdr agent list # статусы всех потомков herdr agent wait s1- --until idle --timeout 1800000 herdr agent prompt s1- "<текст>" # докинуть инструкцию работающему herdr agent read s1- --lines 40 ``` Семантика состояний: `idle` — готов к вводу и его таб видели в UI; `done` — тот же idle после невидимой фоновой работы (чтение через CLI не помечает таб увиденным); `blocked` — herdr распознал UI аппрува/вопроса, потомок ЖДЁТ человека; `unknown` — агент есть, но классификации нет, это НЕ признак завершения. Цикл оркестратора: `agent wait` по очереди или по событию → приёмка (§8). `blocked` → `agent read`, понять вопрос, ответить через `agent prompt` или спросить пользователя. Подозрительная тишина → `pane read `. Таймаут `wait` держать умеренным (~30 мин) и перевзводить по срабатыванию: очень большие значения уходят в «timed out». Fallback, когда интеграция для `$KIND` недоступна или `agent explain` не распознал потомка: периодический `herdr pane read --lines 60` + `git log/status` в worktree. Cron — только крайний случай и обязательно удалить по завершении. Обрыв сессии потомка: работа в worktree сохраняется. Перезапуск — тем же CLI с его флагом продолжения (проверить в `--help`): `omp --resume`, `claude --continue`, `opencode --continue`. Затем промпт: «Сессия прервана. Проверь git status, доведи бриф <файл> до конца». ## 8. Приёмка и мерж - Каждая ветка: тесты + линтер в её worktree, ревизия `git diff main... --stat`. - Не принимать на веру финальный отчёт потомка — проверить команды приёмки самому. - Мерж в main — только с подтверждения пользователя; аддитивные пересечения разруливать вручную. - После мержа: `git worktree remove`; ветки — по договорённости с пользователем. - Освободить пейны потомков, не трогая пейн пользователя. ## Файл: README.md # herdr-multiagent Скилл-плейбук для агента: как вести проект **несколькими агентами параллельно** через [Herdr](https://herdr.dev) (терминальный мультиплексер для кодинг-агентов) — по отдельному git worktree и пейну на каждый этап, с файловыми брифами, мониторингом состояний и приёмкой. Скилл **агент-независим**: kind потомков определяется из Herdr и совпадает с kind оркестратора. Запустили из `opencode` — потомки будут `opencode`; из `omp` — `omp`; из `claude` — `claude`. Поддерживается любой kind из `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 определение своего kind и проверка интеграции Herdr ↔ этот kind; - §2 декомпозиция на этапы с непересекающимися файловыми областями; - §3 worktree + изолированное окружение (отдельный venv / node_modules — иначе агенты импортируют чужой код через editable install основного репо); - §4 брифы файлами, а не в командной строке; - §5 раскладка пейнов main-left, `--no-focus` (фокус пользователя не трогается); - §6 запуск потомка, флаги автономности по kind, обход бага `agent start` на Windows, корректная выдача брифа (Enter проглатывается при `pane run`); - §7 мониторинг через `herdr agent list/wait/prompt/read`, семантика `idle/done/blocked/unknown`, fallback на `pane read` + git, восстановление оборванной сессии; - §8 приёмка и мерж только с подтверждения пользователя. ## Требования - Herdr, сессия запущена внутри его пейна (`HERDR_ENV=1`). Вне Herdr скилл останавливается. - Git (worktree). - Один из поддерживаемых агентских CLI в `PATH`. - Для структурного мониторинга: `herdr integration install `. Для kind без интеграции скилл переключается на fallback — это не блокер. - Проверено на Windows (Git Bash + PowerShell-пейны); команды POSIX, пути — с явной оговоркой про Windows-venv. ## Установка Скилл — это папка с `SKILL.md`. Положите её в каталог скиллов вашего агента: | Агент | путь (проверено на машине автора) | |---|---| | omp, pi | `~/.agents/skills/herdr-multiagent/SKILL.md` | | Claude Code | `~/.claude/skills/herdr-multiagent/SKILL.md` | | opencode | `~/.config/opencode/skills/herdr-multiagent/SKILL.md` | | только в проекте | `/.agents/skills/herdr-multiagent/SKILL.md` | Раскладка не рекурсивная: `/<имя-скилла>/SKILL.md`. Вложенность вида `skills/team/herdr-multiagent/SKILL.md` не обнаруживается. Точный путь для вашего CLI сверьте с его документацией — каталоги скиллов у агентов разные, а `SKILL.md` с frontmatter `name` + `description` читается одинаково. ## Использование Явно: попросите агента «работай по скиллу herdr-multiagent» или вызовите `/skill:herdr-multiagent` (в omp, если включены skill-команды). Автоматически: скилл подхватится, когда задача звучит как «разработать это несколькими агентами параллельно» и агент запущен внутри Herdr. Первое, что сделает агент — проверит `HERDR_ENV=1` и определит свой kind, затем предложит декомпозицию и спросит подтверждение перед запуском потомков. ## Структура ``` herdr-multiagent/ ├─ SKILL.md # тело скилла: frontmatter (name, description) + §0–§8 └─ README.md # этот файл, для человека; агенту не нужен ``` Дополнительные ассеты (скрипты, шаблоны брифов, `references/*.md`) кладутся в ту же папку и читаются агентом через `skill://herdr-multiagent/<путь>`. Здесь их нет: плейбук помещается в один файл, а шаблоны брифов описаны текстом в §4. ## Безопасность Потомки запускаются в режиме автономности (`omp --yolo`, `claude --dangerously-skip-permissions`, `opencode --auto`) — без запросов подтверждения. Это означает полный доступ к файловой системе и shell в пределах их worktree. Скилл ограничивает их брифом («не выходи из worktree», «push НЕ делать»), но это инструкция, а не изоляция. Мерж в main — только с явного подтверждения пользователя. ## Лицензия Свободное использование. --- Источник: prompts.chat. Текст: CC0 1.0 Universal. Русская версия: Kvantora.