DenisSergeevitch/repo-task-proof-loop

Repo Task Proof Loop

Use esta skill quando o usuário desejar um fluxo de trabalho de implementação auditável e repetível para uma tarefa de codificação não trivial, especialmente uma funcionalidade, refatoração, migração ou correção de bug que deve deixar prova local no repositório em .agent/tasks/<TASK_ID>/.

Todos os artefatos da tarefa criados por este fluxo de trabalho devem permanecer dentro do repositório.

Quando os exemplos abaixo mencionarem scripts/task_loop.py, esse caminho é relativo à raiz desta skill. Execute-o enquanto seu diretório de trabalho do shell estiver dentro do repositório de destino.

O que esta skill faz

1. Inicializa uma pasta de tarefa estrita local ao repositório sob .agent/tasks/<TASK_ID>/
2. Cria ou atualiza os arquivos de artefato necessários
3. Instala modelos de subagentes Codex e Claude com escopo de projeto em .codex/agents/ e .claude/agents/
4. Atualiza o AGENTS.md base do Codex na raiz do repositório, além do arquivo de guia Claude do repositório (CLAUDE.md ou .claude/CLAUDE.md), com um bloco gerenciado que explica o fluxo de trabalho
5. Guia o agente através de um loop rigoroso:
   • congelamento da especificação
   • implementação pelo construtor
   • empacotamento de evidências
   • verificação fresca
   • correção mínima
   • verificação fresca novamente até PASS

Veja:

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

Comandos que esta skill suporta

Trate as seguintes palavras como comandos quando o usuário invocar esta skill:

• init <TASK_ID>: cria .agent/tasks/<TASK_ID>/, instala ou atualiza modelos de subagentes e atualiza AGENTS.md e o arquivo de guia Claude do repositório
• freeze <TASK_ID>: cria ou refina spec.md a partir da tarefa do usuário, arquivo de tarefa e orientações do repositório
• build <TASK_ID>: implementa a tarefa de acordo com a especificação congelada
• evidence <TASK_ID>: cria ou atualiza evidence.md, evidence.json e artefatos brutos sem alterar o código de produção
• verify <TASK_ID>: executa uma passagem de verificação fresca e escreve verdict.json, além de problems.md quando necessário
• fix <TASK_ID>: aplica o menor conjunto de correções seguras de problems.md e, em seguida, atualiza o pacote de evidências
• run <TASK_ID>: executa o loop completo, do congelamento da especificação à verificação
• status <TASK_ID>: resume o estado atual dos artefatos

Se o usuário não fornecer um comando, infira o próximo passo a partir do estado do repositório:

• Se a pasta da tarefa não existir, execute init primeiro. Se o usuário claramente quiser apenas a inicialização, pare por aí. Caso contrário, após init ser bem-sucedido e .agent/tasks/<TASK_ID>/spec.md existir, continue reavaliando o estado do repositório na mesma rodada. Não sobreponha init com freeze, build, evidence, verify, fix, validate, status ou trabalho de subagente.
• Se spec.md estiver ausente ou for apenas um placeholder, faça freeze
• Se a implementação ainda não estiver completa, faça build
• Se as evidências estiverem desatualizadas ou ausentes, faça evidence
• Se não houver um veredito recente, faça verify
• Se o veredito não for PASS, faça fix

Etapa de inicialização

Execute o inicializador empacotado a partir da raiz do repositório ou do diretório de trabalho atual dentro do repositório:

scripts/task_loop.py init --task-id <TASK_ID>

Semeação opcional de tarefa:

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "Texto da tarefa do usuário"

O inicializador irá:

• resolver a raiz do repositório
• criar .agent/tasks/<TASK_ID>/
• criar todos os artefatos necessários, incluindo placeholders em raw/
• instalar arquivos de subagentes com escopo de projeto
• inserir ou atualizar blocos de fluxo de trabalho gerenciados em AGENTS.md e no arquivo de guia Claude do repositório

Para Codex, o inicializador mantém seu bloco de fluxo de trabalho gerenciado no AGENTS.md da raiz do repositório. O Codex também suporta AGENTS.override.md e nomes de arquivos de guia alternativos configurados; arquivos aninhados mais próximos ao código ainda têm precedência, e esta skill intencionalmente não os substitui. Se init criar ou reescrever AGENTS.md durante uma sessão Codex em execução, inicie uma nova sessão Codex antes de confiar nas instruções atualizadas. O Codex captura a orientação do documento do projeto no início da sessão.

Para Claude Code, o inicializador mantém seu bloco de fluxo de trabalho gerenciado no CLAUDE.md da raiz do repositório. O Claude Code também suporta .claude/CLAUDE.md, .claude/rules/*.md e CLAUDE.local.md, mas esta skill trata o CLAUDE.md raiz como o guia principal do projeto porque o Claude o exibe diretamente.

No Claude Code, se init acabou de escrever ou atualizar .claude/agents/* durante a sessão atual, não presuma que esses agentes atualizados já estão disponíveis no meio da sessão.

Trate init como um pré-requisito serial. Nunca o sobreponha com freeze, build, evidence, verify, fix, validate, status ou geração de agentes filhos.

Fluxo de trabalho padrão para tarefas pesadas

Para tarefas grandes, mantenha a solicitação voltada ao usuário simples. No Codex, continue serialmente, a menos que o usuário peça explicitamente delegação ou trabalho paralelo de agentes; após essa autorização, a skill pode escolher a configuração interna de filhos automaticamente quando a superfície atual do produto suportar delegação e a forma da tarefa justificar.

Sequência delegada preferida

1. Execute init <TASK_ID> se necessário. Aguarde sua conclusão e confirme se .agent/tasks/<TASK_ID>/spec.md e a estrutura local da tarefa existem antes de continuar.
2. Somente após init ser concluído, crie exatamente um subagente congelador de especificação e aguarde por ele
3. Crie exatamente um subagente construtor e deixe-o implementar
4. Continue com a mesma sessão do construtor para empacotamento de evidências
5. Crie exatamente um subagente verificador fresco e aguarde por ele
6. Se o veredito não for PASS, crie exatamente um subagente reparador
7. Crie novamente um subagente verificador fresco
8. Repita as etapas 6-7 até que o verificador retorne PASS ou o usuário pare o loop

Fan-out adaptativo do Codex

Use isso somente após o usuário ter autorizado explicitamente a delegação do Codex e a tarefa for ampla o suficiente para se beneficiar de trabalho paralelo limitado. Use a sequência serial mais simples acima para tarefas estreitas.

Boas adequações:

• múltiplas perguntas independentes sobre a base de código precisam ser respondidas antes que a especificação esteja estável
• a implementação pode ser dividida em escopos de escrita separados
• a prova requer várias verificações somente leitura independentes em diferentes superfícies

Padrão Codex:

1. init permanece serial.
2. Se a tarefa ainda for ambígua, distribua até 3 filhos explorer internos em paralelo. Dê a cada um uma única pergunta, subsistema ou escopo de caminho. Aguarde por eles e congele a especificação.
3. Crie um filho congelador de especificação e aguarde por ele.
4. Crie um filho task-builder como proprietário da integração.
5. Se a implementação se dividir claramente, o pai também pode criar filhos worker internos limitados em paralelo. Cada trabalhador deve ter propriedade explícita de arquivo ou módulo e não deve escrever evidence.md, evidence.json, verdict.json ou problems.md.
6. Use send_input ou a superfície de acompanhamento equivalente para manter o construtor de integração ativo para empacotamento de evidências. O construtor permanece o único proprietário do pacote de evidências.
7. Se for necessária prova extra, o pai pode distribuir um pequeno conjunto limitado de filhos explorer somente leitura para reexecutar verificações separadas ou inspecionar lacunas de prova distintas em paralelo. Esses filhos podem relatar comandos, saídas e descobertas, mas não escrevem verdict.json.
8. Execute exatamente um filho verificador fresco para cada passagem de verificação.

Comportamento da plataforma

• No Codex, mantenha o caminho normal serial e primeiro modo automático após init. Evite expor detalhes internos de delegação, a menos que afetem materialmente o trabalho.
• No Codex, crie subagentes limitados somente quando o usuário solicitar explicitamente subagentes, delegação ou trabalho paralelo de agentes.
• No Codex, uma vez que a delegação seja autorizada, a skill pode escolher as funções filhas correspondentes e se deve permanecer com um filho de cada vez ou usar fan-out limitado. O usuário não deve precisar nomear funções filhas específicas ou comandos de barra.
• No Codex, a criação de filhos ainda é uma ação explícita do pai/orquestrador. Se a superfície atual do Codex bloquear a delegação, diga isso brevemente apenas quando afetar materialmente o trabalho e continue serialmente.
• No Codex, mantenha a árvore de tarefas rasa. A sessão pai deve criar filhos de pesquisa, construtor, reparador e verificador diretamente, em vez de pedir que um filho de tarefa personalizado orquestre mais filhos.
• No Codex, uma vez que a delegação seja autorizada, escolha entre delegação de um filho de cada vez e fan-out limitado a partir da especificação congelada, forma do repositório e superfície de delegação atual. Mantenha init, propriedade de evidências e cada passagem de verificação serializados em ambos os casos.
• No Codex, mantenha o fan-out de ajuda modesto e baseado em ondas. Prefira até 3 filhos de ajuda paralelos de uma vez, aguarde o fim dessa onda e decida a próxima fase.
• No Codex, o explorer interno é a primeira escolha para descoberta de repositório somente leitura e sondas de prova. O worker interno é apropriado para implementação separada limitada ou reexecuções de verificação quando você pode atribuir propriedade explícita.
• No Codex, reutilize o filho construtor ativo para empacotamento de evidências enviando uma instrução de acompanhamento. As passagens de verificação devem usar um filho novo ou sessão nova; não satisfaça a novidade do verificador retomando um verificador anterior. Os filhos construtor e reparador podem ser reutilizados ou retomados quando você intencionalmente desejar o contexto de volta.
• No Codex, inspecione a lista atual de threads filhas antes de reutilizar ou retomar um filho. Use /agent no Codex CLI ou qualquer superfície de inventário de threads filhas equivalente disponível na superfície atual do produto Codex.
• No Codex, a interface de lista de tarefas/todo do update_plan é apenas orientação de sessão opcional. É útil para exibição de progresso ao vivo, mas não é a fonte da verdade para este fluxo de trabalho.
• No Claude Code, a skill deve decidir se permanece na thread principal ou permite que a sessão principal do Claude delegue automaticamente a fase atual a um subagente interno ou de projeto correspondente após init. O usuário não deve precisar solicitar um subagente Claude específico ou modo de delegação separadamente.
• No Claude Code, o TodoWrite ou a interface visível de tarefa/todo é apenas exibição de progresso opcional com escopo de sessão. Pode ajudar no acompanhamento ao vivo na sessão atual, mas não é a fonte da verdade para este fluxo de trabalho.
• No Claude Code, prefira os subagentes de projeto instalados de .claude/agents/, com descrições escritas como condições de gatilho proativas para a fase correspondente do loop de prova. A sessão principal do Claude roteia pela solicitação de tarefa, descrições dos subagentes e contexto atual, portanto, mantenha o prompt de cada fase claro em linguagem natural. Reutilize o mesmo filho construtor para a etapa de evidência por padrão. Execute um novo construtor apenas no modo somente evidência se a sessão do construtor original não estiver disponível ou se você a descartou intencionalmente. Se init acabou de atualizar .claude/agents/* durante a sessão Claude atual, recorra à thread principal ou a agentes já visíveis em vez de presumir que os atualizados estão disponíveis imediatamente.
• No Claude Code, mantenha a orquestração plana: a auto-delegação da sessão principal é aceitável, mas os agentes do fluxo de trabalho do loop de prova são funções folha. A sessão pai deve possuir as transições de fase do loop de prova em vez de pedir que um agente de tarefa personalizado crie outro.
• No Claude Code, o estado durável canônico é sempre o conjunto de artefatos local ao repositório sob .agent/tasks/<TASK_ID>/, especialmente spec.md, evidence.md, evidence.json, verdict.json e problems.md.
• Se subagentes não estiverem disponíveis, preserve a mesma separação de funções em sessões separadas ou mudanças claras de modo na sessão atual.

Use os prompts de função exatos de references/COMMANDS.md.

Requisitos de congelamento de especificação

spec.md deve conter pelo menos:

• declaração original da tarefa
• critérios de aceitação explícitos rotulados AC1, AC2, ...
• restrições
• não objetivos

Pode incluir também:

• fontes de orientação do repositório
• plano de verificação
• suposições resolvidas de forma restrita a partir da solicitação do usuário

Não edite código de produção durante o congelamento da especificação.

Requisitos de empacotamento de evidências

evidence.md e evidence.json devem julgar cada critério de aceitação independentemente com um de:

• PASS
• FAIL
• UNKNOWN

O empacotamento de evidências pode executar verificações ausentes, mas não deve continuar alterando o código de produção.

Cada PASS deve citar prova concreta, como:

• caminhos de arquivo
• comandos executados
• códigos de saída
• resumos de saída
• caminhos de artefatos em raw/

Não reivindique PASS geral no pacote de evidências a menos que todo critério de aceitação seja PASS.

Requisitos de verificação fresca

O verificador deve ser uma sessão nova ou subagente novo. No Codex, não satisfaça este requisito retomando um filho verificador anterior.

O verificador deve julgar o estado atual do repositório e os resultados atuais de reexecução, não a narrativa do construtor.

O verificador escreve:

• .agent/tasks/<TASK_ID>/verdict.json
• .agent/tasks/<TASK_ID>/problems.md somente quando o veredito geral não for PASS

problems.md deve incluir, para cada critério não PASS:

• id e texto do critério
• status
• por que não está comprovado
• etapas mínimas de reprodução
• esperado vs real
• arquivos afetados
• menor correção segura
• dica corretiva em 1-3 frases

O verificador não deve modificar código de produção ou preencher novamente o pacote de evidências.

Requisitos do reparador

O reparador lê apenas:

• spec.md
• verdict.json
• problems.md

O reparador deve:

• reconfirmar cada problema listado na base de código antes de editar
• fazer o menor conjunto de alterações seguras
• evitar regredir critérios já aprovados
• regenerar evidence.md, evidence.json e artefatos brutos
• parar sem escrever aprovação final

Validação

Antes de afirmar que o fluxo de trabalho foi inicializado corretamente ou que o conjunto de artefatos está completo, execute:

scripts/task_loop.py validate --task-id <TASK_ID>

Execute validate somente após init ter sido totalmente concluído. Se ele relatar que a inicialização está em andamento, aguarde e execute-o novamente, em vez de tratar esse resultado como falha estável da tarefa.

Para um resumo rápido:

scripts/task_loop.py status --task-id <TASK_ID>

Execute status somente após init ter sido totalmente concluído, quando você precisar de um estado de tarefa estável. Se ele relatar init_in_progress: true, trate isso como uma condição de tentar novamente mais tarde.

Salvaguardas

• Mantenha .agent/tasks/<TASK_ID>/ dentro do repositório
• Trate a interface de todo/lista de tarefas do Codex como progresso efêmero apenas; o estado durável são os artefatos no repositório
• Nunca sobreponha comandos
• Verifique sempre o estado estável do repositório antes de avançar