Communitygithub.com

AgentPilotLab/loop-goal-runner

Skill de Modo de Meta com estado para Codex, Claude Code e agentes de IA usando memória STATE.md, portões e regras de parada.

O que é loop-goal-runner?

O Loop Goal Runner é um skill projetado para transformar tarefas abertas do Codex em loops pequenos e stateful, garantindo que cada iteração tenha um objetivo claro, estado durável, um portão objetivo e uma regra de parada. Ele suporta plataformas como Codex, Claude Code e outros agentes de IA, e é ideal para tarefas que se repetem semanalmente ou que exigem persistência de estado, como desenvolvimento de software, automação de testes ou revisão de código. O skill define um contrato central com quatro artefatos obrigatórios: Meta (objetivo e critérios de conclusão), Estado (arquivo `STATE.md` ou sistema externo), Gate (comando de prova objetiva como testes ou lint) e Regra de Parada (sucesso, bloqueador, tentativas máximas, orçamento, etc.). O fluxo de trabalho inclui uma verificação de adequação do loop, localização ou criação de estado com precedência de caminho, modelagem da meta para o modo Goal do Codex, execução de uma iteração com leitura de estado, ação, gate e revisão, e decisões sobre uso de subagentes ou worktrees apenas quando necessário. O skill enfatiza que a conclusão só deve ser reivindicada com evidências de verificação frescas, e inclui regras de escalonamento para parar quando o gate passa, limites são atingidos ou bloqueadores persistem. A confiabilidade do acionamento é baseada em descrição, e um snippet opcional em `references/agents-snippet.md` pode ser adicionado ao `AGENTS.md` para invocação automática.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add AgentPilotLab/loop-goal-runner

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Loop Goal Runner

Use este skill para transformar uma tarefa aberta do Codex em um loop pequeno e stateful. O loop deve ter um objetivo claro, estado durável, um portão objetivo e uma regra de parada. Mantenha o caminho padrão leve; adicione subagentes ou worktrees apenas quando a tarefa justificar o custo extra.

Contrato Central

Cada execução de loop deve manter estes quatro artefatos ou decisões:

  1. Meta: o objetivo atual do usuário e os critérios de conclusão.
  2. Estado: um arquivo STATE.md durável ou um sistema de estado externo explicitamente nomeado.
  3. Gate: testes, lint, verificações de tipo, build, validação de dados, verificações de screenshot ou outro comando de prova objetivo.
  4. Regra de parada: sucesso, bloqueador, tentativas máximas, tempo de execução máximo, limite de orçamento ou limite de aprovação humana.

Não reivindique conclusão sem evidências de verificação recentes. Se não houver um portão objetivo, mantenha o trabalho em modo consultivo/manual e diga que não é um bom candidato a loop.

Fluxo de Trabalho

1. Execute a Verificação de Adequação do Loop

Antes de construir ou continuar um loop, verifique se a tarefa é adequada:

  • Repete-se pelo menos semanalmente, ou é longa o suficiente para que o estado persistente importe.
  • Tem um portão objetivo que pode rejeitar saída ruim.
  • Pode ser executada no ambiente disponível.
  • Tem uma condição de parada rígida.
  • Não requer julgamento não supervisionado para arquitetura, autenticação, pagamentos, deploys de produção ou ações irreversíveis.

Se uma dessas falhar, explique a condição que falhou e use um fluxo de trabalho único normal, a menos que o usuário peça explicitamente para prosseguir.

2. Localize ou Crie o Estado

Trate o estado como escopo da meta por padrão. Cada meta distinta deve ter seu próprio arquivo de estado durável, a menos que o usuário peça explicitamente para reutilizar um arquivo de estado existente ou o arquivo existente claramente pertença à mesma meta ativa.

Precedência de caminho de estado:

  1. Use o caminho exato do arquivo de estado nomeado pelo usuário, se houver.
  2. Se estiver continuando uma meta existente e seu caminho de estado anterior for conhecido, reutilize esse mesmo arquivo.
  3. Se a meta criar ou modificar principalmente um repositório de tarefas ou diretório de artefatos, use o STATE.md da raiz dessa tarefa.
  4. Caso contrário, crie um arquivo específico da meta em .codex/goals/<goal-slug>/STATE.md no espaço de trabalho atual.
  5. Use o STATE.md da raiz do espaço de trabalho apenas quando o próprio espaço de trabalho for a meta, ou quando o usuário o selecionar explicitamente.

Antes de reutilizar qualquer STATE.md existente, inspecione suas seções de Meta e Status Atual. Se descreverem um objetivo diferente, não sobrescreva ou reaproveite. Crie um novo arquivo de estado com escopo de meta e mencione brevemente a separação.

Se o arquivo de estado selecionado não existir e edições de arquivo forem permitidas, crie-o a partir de references/state-template.md. Se edições não forem permitidas, elabore o estado inicial na resposta e peça ao usuário para colocá-lo.

No início de cada execução de loop:

  • Leia o arquivo de estado selecionado com escopo de meta antes de planejar.
  • Leia o AGENTS.md aplicável mais próximo ou instruções de projeto equivalentes quando disponíveis.
  • Extraia a última execução, status atual, bloqueadores abertos, próximas ações, histórico de verificação, lições aprendidas e o caminho do arquivo de estado.

Ao final de cada execução de loop:

  • Atualize apenas o arquivo de estado selecionado com escopo de meta com as ações reais tomadas.
  • Registre comandos de verificação e resultados.
  • Registre a próxima ação ou motivo de parada.
  • Preserve lições que devem sobreviver à compactação ou execuções futuras.
  • Não mova, arquive ou reescreva o estado de uma meta não relacionada, a menos que o usuário peça explicitamente.

3. Modele a Meta

Para o modo Goal do Codex, escreva a meta de forma que seja mensurável:

/goal <objetivo>. Concluído quando: <portão objetivo passa>. Restrições: atualizar o arquivo de estado selecionado com escopo de meta a cada execução; parar após <N> tentativas falhas ou quando julgamento humano for necessário.

Se uma meta já estiver ativa, use a meta atual como fonte da verdade, a menos que o usuário a altere. Se nenhuma meta estiver ativa, infira uma meta de trabalho a partir da solicitação do usuário e declare-a brevemente.

4. Execute Uma Iteração do Loop

Use esta forma de iteração:

  1. Leia o estado e as instruções.
  2. Escolha a próxima ação útil mais pequena.
  3. Execute a ação.
  4. Execute o portão relevante ou explique por que não pode executá-lo.
  5. Revise o diff ou a saída.
  6. Atualize o arquivo de estado selecionado com escopo de meta.
  7. Decida continuar, parar ou escalar.

Mantenha as alterações com escopo. Prefira uma execução manual confiável antes de agendar automação.

5. Decida se Deve Usar Subagentes

Padrão: um único agente. Use subagentes apenas quando pelo menos um se aplicar:

  • Investigações independentes podem ser executadas em paralelo.
  • Uma divisão criador/verificador reduziria materialmente o risco.
  • A tarefa tem várias falhas, subsistemas ou documentos não relacionados.
  • O usuário pede explicitamente agentes paralelos ou subagentes.

Ao usar subagentes, aplique estes padrões:

  • Criador/verificador: um agente implementa ou investiga, outro revisa conformidade com especificações e qualidade do código.
  • Despacho paralelo: um agente por domínio de problema independente.
  • Verificador: um agente novo revisa evidências, não raciocínio oculto.

Não trate a opinião de um subagente como um portão rígido. A verificação objetiva ainda vence.

6. Decida se Deve Usar Worktrees

Use worktrees para alterações de código quando vários agentes ou branches de longa duração possam escrever concorrentemente. Pule worktrees para pesquisa somente leitura, análise de documentos, pequenas edições de um arquivo ou espaços de trabalho que não sejam repositórios.

Se worktrees forem necessários, prefira suporte nativo a worktrees do Codex quando disponível. Caso contrário, use worktrees do Git apenas após confirmar o repositório alvo e garantir que o diretório worktree não será acidentalmente commitado.

7. Conclusão e Escalonamento

Pare e relate claramente quando:

  • O portão passa e os critérios da meta são atendidos.
  • O máximo de tentativas, tempo de execução ou limite de orçamento é atingido.
  • Permissões necessárias, credenciais, serviços externos ou julgamento humano são necessários.
  • O mesmo bloqueador se repete em três voltas consecutivas do loop.
  • O loop precisaria tocar em arquitetura, autenticação, pagamentos, deploys de produção, segredos ou permissões amplas sem aprovação humana explícita.

A resposta final deve incluir o estado atual, evidências de verificação e a próxima ação recomendada.

Confiabilidade do Acionamento

O acionamento do skill é baseado em descrição. Para fazer este skill ser executado automaticamente com uso futuro do modo Goal, adicione o snippet em references/agents-snippet.md a um AGENTS.md global ou de projeto.

Referências

  • references/state-template.md: modelo para novos arquivos STATE.md.
  • references/agents-snippet.md: instrução durável opcional para fazer o Codex invocar este skill sempre que o usuário iniciar ou discutir uma meta.

Habilidades Relacionadas