Herdr Multiagent: Parallel Coding Agents 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. --- # Мультиагентная работа через 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 ../<proj>-s<N> -b stage-<N>-<name> ``` Ловушка Python-проектов: общий venv импортирует ЧУЖОЙ код (editable install основного репо). Каждому worktree - свой venv: ```bash cd ../<proj>-s<N> && 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. Брифы - файлами, не в командной строке `<repo>/.briefs/stage-<N>.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 "<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. Запуск потомка своего kind Штатный путь - `agent start`, он же валидирует, что в пейне поднялся именно ожидаемый агент: ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <флаги-автономности> ``` Имя должно матчить `[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 <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 <pane_id> "<executable> <флаги-автономности>" sleep 3 && herdr pane read <pane_id> --lines 15 # ожидаем промпт CLI herdr agent rename <pane_id> s1-<name> # если herdr распознал агента ``` Если после этого `herdr agent explain <pane_id>` не даёт распознанного агента - структурный мониторинг для этого пейна недоступен, работаем по fallback §7. ### Выдача брифа НЕ через `pane run`: Enter проглатывается, пока TUI рендерит вставку. В два шага с паузой: ```bash herdr pane send-text <pane_id> "Прочитай файл <абсолютный путь к брифу> - это твой бриф. Выполни полностью до конца (код, тесты, линтер, коммит в свою ветку), затем дай финальный отчёт." sleep 5 && herdr pane send-keys <pane_id> Enter ``` Штатная альтернатива, когда интеграция стоит и `agent start` отработал: ```bash herdr agent prompt s1-<name> "Прочитай файл <бриф> и выполни до конца" --wait --timeout 300000 ``` Проверить по `pane read`, что бриф УШЁЛ: input пустой, агент работает. ## 7. Мониторинг - через интеграцию, НЕ cron ```bash herdr agent list # статусы всех потомков herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<текст>" # докинуть инструкцию работающему herdr agent read s1-<name> --lines 40 ``` Семантика состояний: `idle` - готов к вводу и его таб видели в UI; `done` - тот же idle после невидимой фоновой работы (чтение через CLI не помечает таб увиденным); `blocked` - herdr распознал UI аппрува/вопроса, потомок ЖДЁТ человека; `unknown` - агент есть, но классификации нет, это НЕ признак завершения. Цикл оркестратора: `agent wait` по очереди или по событию → приёмка (§8). `blocked` → `agent read`, понять вопрос, ответить через `agent prompt` или спросить пользователя. Подозрительная тишина → `pane read <pane_id>`. Таймаут `wait` держать умеренным (~30 мин) и перевзводить по срабатыванию: очень большие значения уходят в «timed out». Fallback, когда интеграция для `$KIND` недоступна или `agent explain` не распознал потомка: периодический `herdr pane read <pane_id> --lines 60` + `git log/status` в worktree. Cron - только крайний случай и обязательно удалить по завершении. Обрыв сессии потомка: работа в worktree сохраняется. Перезапуск - тем же CLI с его флагом продолжения (проверить в `--help`): `omp --resume`, `claude --continue`, `opencode --continue`. Затем промпт: «Сессия прервана. Проверь git status, доведи бриф <файл> до конца». ## 8. Приёмка и мерж - Каждая ветка: тесты + линтер в её worktree, ревизия `git diff main...<branch> --stat`. - Не принимать на веру финальный отчёт потомка - проверить команды приёмки самому. - Мерж в main - только с подтверждения пользователя; аддитивные пересечения разруливать вручную. - После мержа: `git worktree remove`; ветки - по договорённости с пользователем. - Освободить пейны потомков, не трогая пейн пользователя.