Herdr Multiagent: Fluxo de Trabalho com Agentes de Codificação em Paralelo

--- name: herdr-multiagent description: Executa vários agentes de codificação em paralelo sob Herdr: decomposição em etapas, um git worktree, ambiente isolado, pane e brief de arquivo por agente, monitoramento de estado, revisão, merge. O kind do filho é lido de `herdr pane current` (.result.pane.agent) e corresponde ao orquestrador (omp, opencode, claude, codex, kimi, ...). Requiere HERDR_ENV=1. --- # Trabalho multiagente via Herdr Playbook: decomponha as tarefas do projeto em etapas independentes, coloque um agente separado em cada etapa em seu próprio git worktree e pane do herdr, forneça um brief de arquivo, monitore e aceite o resultado. Skill agnóstico de agente: kind dos filhos = kind do orquestrador. Se você iniciou o skill a partir de opencode - os filhos serão opencode; de omp - omp; de claude - claude. Nunca substitua o kind do orquestrador de memória e não escolja um kind "popular". ## 0. Pré-requisitos ```bash test "${HERDR_ENV:-}" = 1 # sem isso - pare, não estamos dentro do Herdr ``` Se a verificação falhar - diga ao usuário que a sessão não está sob Herdr e pare. Não gerencie o Herdr de outra pessoa externamente. Comandos básicos de panes/agentes - no skill padrão do Herdr (`herdr --skill`). O binário instalado é a autoridade em sintaxe; em caso de dúbida, leia `herdr agent`, `herdr pane`, `herdr integration`, não adivine. ## 1. Determine seu kind - antes de qualquer ação ```bash herdr pane current --current ``` O campo `.result.pane.agent` - este é o kind do orquestrador, que também é o valor para `--kind` nos filhos: ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # sem jq: KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` Vazio ou `unknown` - pergunte ao usuário com qual kind iniciar os filhos. De agora em adiante, `$KIND` - este é o valor obtido, não um literal. Verifique a integração Herdr ↔ este kind (ela fornece `agent list/wait/prompt`): ```bash herdr integration status | grep -i "$KIND" ``` - `current` - ok. - `not installed` - `herdr integration install "$KIND"`. A integração é captada apenas por **novas** sessões, portanto instale ANTES de iniciar os filhos; o próprio orquestrador permanecerá invisível para `agent list` - isso é normal, não precisa ser monitorado. - kind ausente na lista `herdr integration install` (por exemplo `amp`, `cline`, `kiro`, `maki`) - não haverá monitoramento estrutural, trabalhamos com fallback §7 (`pane read` + git). Isso não é um bloqueador. Registre e anuncie ao usuário: "kind dos filhos = $KIND". ## 2. Decomposição - passo principal, não tenha pressa - Leia o plano/especificação do projeto e o estado atual (`git log`, testes, `git worktree list`). - Divida o trabalho restante em etapas com **áreas de arquivos que não se superpõem**. Dois agentes sobre o mesmo pacote - apenas conscientemente e com ordem explícita (depois, não em paralelo). - Edições aditivas de arquivos comuns (config, lock) são permitidas - anote nos briefs "só aditivamente, sem mudar assinaturas"; os conflitos de merge serão resolvidos pelo orquestrador. - Registre a matriz "etapa → arquivos que PODE / NÃO PODE tocar". Antes de iniciar: tudo pronto em main está commitado, árvore limpa. ## 3. Worktree + ambiente isolado por agente ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Armadilla de projetos Python: o venv compartilhado importa código de OUTRO (editable install do repo principal). Para cada worktree - seu próprio venv: ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` Instale vários venvs sequencialmente com um único comando em segundo plano (cache pip compartilhado). Stack JS: seus próprios `node_modules` em cada worktree (`npm ci`). Se o orquestrador tem um wrapper de hook para comandos (rtk e similares): o caminho relativo ao interpretador (`../.venv/Scripts/python.exe`) no brief não será resolvido através desse hook ("command not found"). No brief e prompts - apenas caminhos ABSOLUTOS para python/npm do worktree correspondente. ## 4. Briefs - por arquivos, não na linha de comando `<repo>/.briefs/stage-<N>.md` (untracked). Estrutura do brief: - **contexto**: o que ler primeiro (especificação, contrato, arquivos chave), o que já foi feito; - **tarea**: requisitos concretos com referências a pontos da especificação; - **limites**: arquivos pode/não pode, "não saia do worktree", "NÃO fazer push"; - **aceitação**: comandos exatos de testes/linter (com caminho absoluto ao interpretador do worktree), "testes antigos permanecem verdes", commit na sua própria branch, reporte final. O brief não deve assumir um kind específico de agente: não escreva "inicie omp/skill/..." - escreva o objetivo, limites e comandos de aceitação. O filho decidirá por si mesmo com quais suas próprias ferramentas fazer isso. Prompt ao agente, curto: "Leia o arquivo <brief> e execute até o final". ## 5. Panes: criar e, IMEDIATAMENTE, nomear Layout recomendado - main-left: pane do orquestrador à esquerda em toda a altura, todos os filhos em columna à direita, um debajo do outro. Se o usuário tem plugins de layout calculados para main-left, qualquer outro esquema quebrará sua visão. Se o usuário pedir explicitamente outro layout - execute o dele. Primer filho - `split --current --direction right`, os demais - `split --pane <filho anterior> --direction down` DENTRO da columna direita. NÃO dividir o pane do orquestrador nem dividir panes de agentes à direita - apenas uma cadena down na columna direita. ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` ID do novo pane - do JSON `.result.pane.pane_id`. Não tocar o foco do usuário (`--no-focus`). O nome do filho é dado no passo 6 via `agent start`, além de, para maior clareza, `herdr pane rename <pane_id> "s<N>-<name>"`. ## 6. Iniciar filho do seu kind Caminho padrão - `agent start`, que também valida que o agente esperado subiu no pane: ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <flags-de-autonomia> ``` O nome deve corresponder a `[a-z][a-z0-9_-]{0,31}` e ser único entre agentes vivos. ### Flags de autonomia O filho trabalha sem humano, de lo contrario ficará em aprobación. A flag depende do CLI, não do Herdr. Confirmadas: | kind | inicio | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions` (ou `--permission-mode bypassPermissions`) | | `opencode` | `-- --auto` | Para qualquer outro kind (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes, qodercli, mastracode, pi, ...) - NÃO inventar a flag. Determinar o executável canónico e ler sua ajuda: ```bash herdr agent start --help # na descrição de --kind está indicado o executable canónico <executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` Flag não encontrada → verificar se há modo de autonomia na config do CLI (por exemplo `~/.omp/agent/config.yml: tools.approvalMode: yolo`, `~/.claude/settings.json: permissions`, `opencode.json: permission`), e avisar ao usuário que o filho pode ficar em aprobaciones - visibles como estado `blocked` (§7). ### Se `agent start` falhou por timeout Bug conhecido no Windows em panes PowerShell: `agent start` envia um `Start-Process` distorsionado → timeout. Solución - levantar o CLI no pane diretamente: ```bash herdr pane run <pane_id> "<executable> <flags-de-autonomia>" sleep 3 && herdr pane read <pane_id> --lines 15 # esperamos prompt do CLI herdr agent rename <pane_id> s1-<name> # se herdr reconheceu o agente ``` Se depois disso `herdr agent explain <pane_id>` não dá um agente reconhecido - monitoramento estrutural para este pane indisponible, trabalhamos com fallback §7. ### Entrega do brief NÃO via `pane run`: Enter é engullido enquanto o TUI renderiza a inserção. Em dois passos com pausa: ```bash herdr pane send-text <pane_id> "Leia o arquivo <caminho absoluto ao brief> - este é seu brief. Execute completamente até o final (código, testes, linter, commit na sua branch), depois dê um reporte final." sleep 5 && herdr pane send-keys <pane_id> Enter ``` Alternativa padrão, quando a integração está instalada e `agent start` funcionou: ```bash herdr agent prompt s1-<name> "Leia o arquivo <brief> e execute até o final" --wait --timeout 300000 ``` Verifique com `pane read` que o brief FOI: input vazio, agente trabalhando. ## 7. Monitoramento - via integração, NÃO cron ```bash herdr agent list # status de todos os filhos herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<texto>" # adicionar instrução a um agente em execução herdr agent read s1-<name> --lines 40 ``` Semántica dos estados: `idle` - pronto para input e sua tab foi vista no UI; `done` - mesmo idle após trabalho em segundo plano invisível (leitura via CLI não marca a tab como vista); `blocked` - herdr reconheceu UI de aprobación/pregunta, o filho ESPERA um humano; `unknown` - agente existe, mas sem classificação, isso NÃO é signo de finalização. Ciclo do orquestrador: `agent wait` por turno ou por evento → aceitação (§8). `blocked` → `agent read`, entender a pregunta, responder via `agent prompt` ou perguntar ao usuário. Silêncio sospechoso → `pane read <pane_id>`. Timeout de `wait` manter moderado (~30 min) e rearmar ao disparar: valores muito grandes caem em "timed out". Fallback, quando a integração para `$KIND` não está disponível ou `agent explain` não reconheceu o filho: `herdr pane read <pane_id> --lines 60` periódico + `git log/status` no worktree. Cron - só em último caso e obrigatoriamente eliminar ao finalizar. Corte de sessão do filho: o trabalho no worktree se conserva. Reinicio - com o mesmo CLI e sua flag de continuación (verificar em `--help`): `omp --resume`, `claude --continue`, `opencode --continue`. Depois prompt: "Sessão interrumpida. Verifica git status, lleva el brief <archivo> hasta el final". ## 8. Aceptación y merge - Cada branch: tests + linter en su worktree, revisión `git diff main...<branch> --stat`. - No aceptar el reporte final del hijo al pie de la letra - verificar los comandos de aceptación uno mismo. - Merge en main - solo con confirmación del usuario; superposiciones aditivas resolver manualmente. - Después del merge: `git worktree remove`; branches - según acuerdo con el usuario. - Liberar los panes de los hijos, sin tocar el pane del usuario.