polyphony

Visão geral do skill polyphony

polyphony é um skill de orquestração multiagente para executar trabalhos paralelos de agentes em workspaces isolados por contêiner. Cada sessão ganha seu próprio container Docker e sua própria branch git, o que o torna útil quando você quer execução concorrente sem colisão de branches, bugs de estado compartilhado ou limpeza bagunçada depois.

Para que o polyphony serve

Use o skill polyphony quando a tarefa for maior do que um único prompt, mas ainda se beneficiar de delegação estruturada: trabalho paralelo de features, validação isolada, triagem de issues ou execução de vários caminhos de agente no mesmo codebase. Ele foi pensado para quem se importa com execução limpa, roteamento de tarefas reproduzível e coordenação multiagente mais segura.

Por que ele se destaca

O principal diferencial do polyphony é um design de fluxo de trabalho orientado à isolamento desde o início. Em vez de pedir para um agente “fazer tudo”, ele separa descoberta da tarefa, roteamento, provisionamento, runtime e verificação, para que cada worker opere em um workspace controlado. Isso torna a abordagem do polyphony para Multi-Agent Systems mais prática quando você precisa de testes independentes e de um comportamento de entrega mais limpo.

Melhor encaixe e trade-offs

O polyphony funciona melhor se o seu ambiente já suporta Docker ou OrbStack e se você quer orquestração ativada por padrão, em vez de um padrão de prompt pontual. Ele é menos útil se você só precisa de uma resposta de chat, não consegue rodar containers ou quer setup mínimo, sem workflow ciente do repositório.

Como usar o skill polyphony

Instale e carregue o polyphony

Instale o skill polyphony no seu diretório de skills e depois use-o no fluxo de trabalho do host que oferece suporte a carregamento de skills. A documentação do repositório informa que ele foi criado para ser carregado automaticamente quando a isolação por contêiner estiver disponível, e que é o padrão para /spawn-team. Se o seu ambiente for diferente, verifique se há acesso ao Docker, criação de branch e montagem de workspaces antes de confiar no skill.

Comece pelos arquivos certos

Para usar o polyphony, comece em skills/polyphony/SKILL.md e depois leia o contexto vinculado ou mencionado na mesma ordem usada internamente pelo skill: ciclo de vida da tarefa, arquitetura, pré-requisitos, configuração e quaisquer referências específicas do repositório embutidas no arquivo. Como este repo não tem scripts auxiliares nem pastas extras de referência, o comportamento central vive no próprio arquivo do skill, então vale a pena lê-lo com atenção.

Transforme um objetivo vago em um prompt útil

Um bom prompt para polyphony deve incluir: o repo-alvo, o número de agentes paralelos desejado, o tipo de trabalho que cada agente deve assumir, a expectativa de branch ou PR e quaisquer restrições de testes, credenciais ou limpeza. Por exemplo, em vez de “corrija este projeto”, peça para “dividir a issue em três tarefas isoladas de agentes: reproduzir, corrigir e verificar, usando workspaces Docker separados e reportando o status de landing por branch”.

O que especificar para obter melhor saída

Dê ao skill sinais concretos de roteamento: prioridade da tarefa, dependências, se o trabalho precisa começar em modo read-only, quais ambientes são seguros para provisionar e o que conta como verificação. Isso ajuda o orquestrador a escolher melhores RunSpecs e reduz spins de container desperdiçados. Para um guia de polyphony, a entrada mais útil não é mais texto; é delimitação mais clara entre as tarefas.

FAQ do skill polyphony

O polyphony é só para setups com Docker?

Sim, na prática. O skill polyphony pressupõe que a isolação por contêiner está disponível, então suporte a Docker ou OrbStack é o principal filtro de adoção. Se você não consegue provisionar containers, o workflow perde boa parte do valor.

O polyphony é diferente de um prompt normal?

Sim. Um prompt normal pede que um agente aja; o polyphony define como várias execuções de agentes são reivindicadas, roteadas, provisionadas, verificadas e entregues. Essa estrutura é justamente o ponto do skill polyphony, especialmente quando branches independentes e execução limpa importam mais do que velocidade pura.

Iniciantes conseguem usar o polyphony?

Sim, desde que já consigam rodar containers e ler um arquivo de skill. A principal curva de aprendizado não é escrever prompt; é entender que o polyphony espera decomposição da tarefa e ambiente pronto. Iniciantes normalmente obtêm melhores resultados quando começam com uma tarefa pequena e um único alvo claro de verificação.

Quando não devo usar o polyphony?

Não use o polyphony para perguntas rápidas, edições leves ou ambientes sem Docker. Ele também é uma escolha ruim quando a tarefa é ambígua e você ainda não definiu o que cada agente deve assumir, porque o overhead de orquestração pode ser maior do que o benefício.

Como melhorar o skill polyphony

Dê limites de tarefa melhores para o roteador

O maior ganho de qualidade no polyphony vem de uma decomposição de tarefas mais clara. Diga o que é exploração, o que altera código e o que serve apenas para verificar. Se quiser paralelismo, defina a divisão explicitamente em vez de esperar que o sistema inferira isso de um objetivo vago.

Inclua restrições que afetam o comportamento do workspace

Mencione regras de nome de branch, limites de rede, expectativas de tempo de execução de testes e se segredos ou identidades montadas são necessários. Como o polyphony usa containers isolados e branches independentes, essas restrições afetam diretamente o provisionamento e se a execução consegue terminar sem intervenção manual.

Peça verificação, não só implementação

Um modo comum de falha é parar em “o código mudou”. Um uso melhor do polyphony pede passos de reprodução, comandos de teste e critérios de entrega para cada caminho de agente. Isso é especialmente importante quando vários workers podem chegar a soluções diferentes e você precisa de uma decisão confiável de merge.

Itere depois da primeira execução

Se a primeira saída vier ampla demais, restrinja a tarefa e rode de novo com um único critério de sucesso. Se o resultado vier fragmentado demais, reduza o número de agentes paralelos e adicione dependências mais fortes entre as etapas. Para polyphony, a melhoria normalmente vem de entradas de orquestração mais precisas, não de prompts mais longos.