long-task-coordinator

Visão geral da skill long-task-coordinator

O que a long-task-coordinator faz

long-task-coordinator é uma skill de coordenação para trabalhos que precisam sobreviver a interrupções, repasses e longos intervalos entre interações. A função central dela é simples: tirar tarefas de longa duração da memória frágil do chat e colocá-las em um arquivo de estado durável, com transições de status explícitas, verificações de recuperação e rastreamento dos próximos passos.

Quem deve instalar

Esta skill é mais indicada para quem faz orquestração de agentes, pesquisa delegada, migrações, jobs em lote ou qualquer tarefa que possa ser pausada, retomada depois ou ficar aguardando outro worker. Se o seu fluxo inclui “retoma isso amanhã” ou “dispara agora e confere depois”, a skill long-task-coordinator tende a encaixar muito bem.

O problema real que ela resolve

Os usuários não instalam long-task-coordinator só para “planejar melhor”. Eles instalam para tornar trabalhos longos recuperáveis e honestos:

• recuperar estado após perda de contexto
• rastrear responsabilidade entre coordinator e workers
• representar estados de espera de forma explícita
• evitar declarações falsas de conclusão
• retomar a partir de uma fonte de verdade salva, em vez de adivinhar com base no chat anterior

O que diferencia de um prompt comum de planejamento

O diferencial não é conhecimento de domínio. É disciplina de workflow:

• um único arquivo de estado durável
• um loop fixo: READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• status explícitos como running, awaiting-result, paused, blocked e complete
• preferência por persistir antes de reportar, para que a sessão seguinte consiga se recuperar com confiabilidade

Casos ideais e casos em que não faz sentido

Use long-task-coordinator quando a tarefa atravessa várias sessões, envolve subagentes ou jobs em background, ou precisa de checkpoints e tentativas de recuperação. Evite para tarefas pequenas, de uma única interação. O repositório direciona explicitamente casos mais leves de planejamento para planning-with-files, em vez de adicionar a sobrecarga de trabalho longo quando recuperação não é necessária.

Como usar a skill long-task-coordinator

Opções de instalação da long-task-coordinator

O README do repositório mostra a instalação manual via symlink da skill para o diretório de skills do seu cliente, por exemplo:

ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.claude/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.codex/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.gemini/skills/long-task-coordinator

Se você usa um gerenciador de skills, garanta que o caminho final instalado ainda exponha o conteúdo real da pasta skills/long-task-coordinator, e não apenas a raiz do repositório.

Leia estes arquivos primeiro

Para uma adoção rápida, mas confiável, leia nesta ordem:

1. skills/long-task-coordinator/SKILL.md
2. skills/long-task-coordinator/references/workflow.md
3. skills/long-task-coordinator/evals/prompts.md
4. skills/long-task-coordinator/README.md

Por que essa ordem funciona:

• SKILL.md define quando a skill deve ser acionada e quais são as regras centrais
• references/workflow.md mostra o padrão utilizável de arquivo de estado
• evals/prompts.md deixa claro como é um “comportamento correto”
• README.md confirma a instalação e o loop principal

Que entrada a skill precisa

A skill long-task-coordinator funciona melhor quando você fornece:

• o objetivo da tarefa
• critérios concretos de sucesso
• se o trabalho já está em andamento
• onde o arquivo de estado durável deve ficar
• quaisquer atribuições ativas de worker ou subagente
• o próximo gatilho de checkpoint, como tempo ou condição
• bloqueios ou dependências já conhecidos

Sem isso, o modelo ainda consegue começar, mas vai assumir mais coisas e produzir um registro de coordenação mais fraco.

Como transformar um pedido vago em uma boa invocação

Pedido fraco:

Me ajuda a acompanhar essa migração.

Pedido melhor:

Use long-task-coordinator para esta migração. Crie ou recupere um arquivo de estado durável em docs/migration-state.md. Objetivo: migrar a autenticação do serviço para OAuth2. Critérios de sucesso: testes passando, notas de rollout escritas, caminho antigo de autenticação desativado. Podemos delegar trabalho para subagentes e retomar em várias sessões. Se houver trabalho em andamento, use um estado de espera explícito em vez de sugerir falha.

A versão mais forte melhora a saída porque define persistência, escopo, lógica de conclusão e estilo de coordenação logo no início.

Crie um arquivo de estado durável cedo

O hábito operacional mais importante é criar o arquivo de estado antes de o trabalho ficar confuso. A referência recomenda caminhos como:

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

No mínimo, persista:

• Objetivo
• Critérios de sucesso
• Status
• Etapa atual
• Trabalho concluído
• Próxima ação
• Próximo checkpoint
• Bloqueios
• Responsáveis

Este é o ponto-chave de adoção: se você pular o arquivo de estado, perde a maior parte do valor da skill long-task-coordinator.

Use o loop de recuperação da long-task-coordinator em toda rodada

O loop central do repositório é o coração prático do uso de long-task-coordinator:

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

Na prática, isso significa:

1. ler primeiro o estado salvo
2. verificar se o status ainda continua válido
3. checar se o trabalho delegado já retornou
4. decidir se deve continuar, esperar, tentar de novo, pausar ou encerrar
5. escrever o estado atualizado
6. só então reportar ao usuário

Essa ordem é o que mantém a próxima sessão recuperável.

Use estados explícitos, especialmente awaiting-result, na long-task-coordinator

Um recurso sutil, mas muito valioso, desta skill é o uso de awaiting-result. Muitos agentes simulam progresso agindo como se uma tarefa delegada tivesse falhado ou terminado, quando na verdade ela ainda está em andamento. Esta skill oferece um modelo mais limpo:

• running para trabalho ativo do coordinator
• awaiting-result quando um worker ou job ainda está executando
• paused quando foi interrompido intencionalmente
• blocked quando restrições externas impedem o progresso
• complete apenas quando os critérios de sucesso foram realmente cumpridos

Para Agent Orchestration, essa é uma das distinções mais úteis de toda a skill.

Workflow sugerido para trabalho delegado

Um bom padrão operacional é:

1. definir a tarefa e os critérios de sucesso
2. criar o arquivo de estado
3. atribuir trabalho delimitado a um worker
4. registrar o responsável e a condição esperada de retorno
5. definir o status como awaiting-result se estiver aguardando
6. retomar com recuperação, não com memória
7. atualizar os itens concluídos e a próxima ação
8. marcar complete só depois de verificar os critérios

Esse padrão é mais seguro do que prompts abertos do tipo “continue”, porque os repasses passam a ser auditáveis.

Padrões de prompt práticos que funcionam bem

Bons prompts de uso da long-task-coordinator costumam incluir linguagem de recuperação. Exemplos:

• “Use long-task-coordinator e recupere a partir de qualquer estado existente antes de propor próximos passos.”
• “Persista o status atualizado antes de reportar.”
• “Se um worker ainda estiver em andamento, marque awaiting-result e defina o próximo checkpoint.”
• “Não marque como complete a menos que o estado salvo e os critérios de sucesso estejam de acordo.”

Esses padrões se alinham diretamente aos prompts de avaliação do repositório e reduzem a falsa sensação de certeza.

Erros comuns na adoção

A maioria dos usos malsucedidos vem de falhas de processo, não de falta de recursos:

• depender do histórico do chat em vez de um arquivo
• usar texto de status vago em vez dos estados definidos
• reportar progresso antes de atualizar o estado salvo
• não registrar responsáveis em trabalho delegado
• marcar como concluído sem checar os critérios de aceitação
• usar a skill para tarefas curtas em que a sobrecarga de coordenação não se justifica

FAQ da skill long-task-coordinator

Vale a pena instalar long-task-coordinator para tarefas simples?

Em geral, não. Se a tarefa é curta, cabe em uma única sessão e não exige recuperação, long-task-coordinator adiciona overhead. O repositório a posiciona explicitamente para trabalhos que sobrevivem a uma interação ou dependem de estado durável.

Em que ela difere de planning-with-files

planning-with-files é a opção mais leve quando você precisa principalmente de planejamento estruturado. long-task-coordinator é para retomada, estados de espera explícitos e recuperação após interrupções. Escolha esta quando a integridade do estado importa mais do que apenas organizar etapas.

A long-task-coordinator é boa para Agent Orchestration?

Sim. Esse é um dos encaixes mais claros. A skill foi pensada para configurações coordinator-worker, execução delegada, jobs em background e repasses entre múltiplas sessões. O rastreamento de responsáveis e o estado awaiting-result são especialmente úteis para Agent Orchestration.

Ela exige um runtime ou framework específico?

Não. O README a descreve como intencionalmente abstrata e portável. Ela não parte de um domínio nem de um runtime específico. O principal requisito é que seu agente consiga ler e gravar um arquivo durável no workspace.

Iniciantes podem usar esta skill long-task-coordinator?

Sim, desde que já entendam a tarefa que estão coordenando. A skill em si é conceitualmente simples, mas iniciantes podem exagerar no uso. Se você não está lidando com interrupções, delegação ou retomada, comece por uma skill de planejamento mais simples.

Quando eu não devo usar long-task-coordinator?

Evite quando:

• a tarefa vai terminar em uma única passada
• não há necessidade de retomar depois
• não existe worker delegado nem processo em background envolvido
• você não quer a etapa extra de manter um arquivo de estado

Nesses casos, prompts comuns podem ser mais rápidos.

Como melhorar a skill long-task-coordinator

Comece com critérios de sucesso mais fortes

A maior alavanca de qualidade está em uma lógica de conclusão mais precisa. Em vez de “finalizar a migração”, escreva critérios como:

• testes de autenticação passando
• configuração de produção atualizada
• nota de rollback adicionada
• caminho legado desativado

Critérios melhores tornam muito mais difícil para o modelo encerrar a tarefa antes da hora.

Torne o arquivo de estado concreto e fácil de reencontrar

Não esconda o estado em um arquivo temporário qualquer. Coloque-o em um caminho previsível, como docs/oauth-migration-state.md. Uma boa recuperação depende de um arquivo que a próxima sessão realmente consiga encontrar sem precisar adivinhar.

Registre responsabilidade explicitamente

Para usar melhor a long-task-coordinator, sempre registre quem é responsável por quê:

• Origin: define a tarefa
• Coordinator: mantém o estado e o sequenciamento
• Worker: executa trabalho delimitado

Esse pequeno hábito reduz duplicação, trabalho parado e confusão quando vários agentes participam.

Melhore os prompts com condições de checkpoint

Um checkpoint fraco diz: “confere depois”. Um checkpoint forte diz: “retome quando o worker devolver os resultados dos testes ou às 15:00 UTC, o que acontecer primeiro”. Quanto mais explícito for o gatilho, menor a chance de o coordinator se perder.

Evite relatórios de progresso enganosos

Um modo de falha comum é gerar relatórios que soam bem, mas não são confiáveis. Corrija isso instruindo a skill a:

• ler primeiro o estado salvo
• verificar se ele ainda está correto
• persistir atualizações antes de resumir
• distinguir espera de bloqueio
• justificar complete com base nos critérios de sucesso

Isso mantém as saídas da long-task-coordinator confiáveis ao longo das sessões.

Use os prompts de avaliação como testes de aceitação

evals/prompts.md é útil para mais do que um smoke test. Trate esses prompts como um checklist local para suas próprias adaptações:

• ela consegue retomar trabalho interrompido com segurança?
• representa espera de forma honesta?
• comprova a conclusão com o estado salvo?

Se o seu uso customizado falha nesses testes, seu padrão de orquestração ainda está solto demais.

Faça uma iteração depois da primeira rodada

Depois da primeira rodada de coordenação, inspecione o arquivo de estado e refine tudo que ainda estiver ambíguo:

• substitua status vagos
• adicione responsáveis que faltam
• esclareça bloqueios
• quebre próximas ações grandes demais
• adicione uma condição real de checkpoint

A skill long-task-coordinator melhora rapidamente quando o estado persistido fica mais específico, porque toda recuperação futura depende desse arquivo, e não da memória.