# 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>`. Для 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` |
| только в проекте | `<repo>/.agents/skills/herdr-multiagent/SKILL.md` |

Раскладка не рекурсивная: `<skills-root>/<имя-скилла>/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 — только с явного подтверждения пользователя.

## Лицензия

Свободное использование.