micooz/planejar-executar-em-lote

Execução de Plano em Lote

Use esta habilidade quando a tarefa é criar, revisar, retirar, executar ou inspecionar planos de módulo e o checklist.md derivado, com base em uma fonte de requisitos e no estado atual do diretório plans/.

Esta habilidade atualmente possui estes modos explícitos:

• plan: gerar ou revisar planos prontos para implementação e atualizar checklist.md
• execute: implementar planos já revisados

Esta habilidade pode fazer as seguintes coisas:

• Aceita texto de requisito do chat, um arquivo de requisito como requirements.md, ou um arquivo de plano existente ou diretório plans/.
• Reconstrói o estado de planejamento atual a partir da fonte de requisitos mais recente, arquivos de plano existentes e um arquivo de estado oculto.
• Detecta mudanças mistas por módulo: novos requisitos, requisitos alterados, requisitos removidos e notas de revisão.
• Constrói planos de módulo ou fluxo de trabalho cientes de dependências que refletem trabalho paralelizável e serial.
• Gera um checklist.md consolidado a partir da fonte de requisitos mais recente mais notas de revisão autoritativas.
• Executa planos aprovados com subagentes de implementação somente após um comando de execução explícito do usuário.

Tratamento de Entrada

Escolha a entrada primária nesta ordem:

1. Um caminho de arquivo de plano explícito ou caminho de diretório plans/ mencionado pelo usuário.
2. Um caminho de arquivo de requisito explícito mencionado pelo usuário.
3. Um arquivo ou documento já anexado no contexto da tarefa.
4. O texto do requisito escrito diretamente no chat.

Use estas regras:

• Se um caminho de arquivo de plano for fornecido, trate essa linhagem de plano como o ponto de partida primário e inspecione o diretório plans/ irmão.
• Se um caminho de diretório plans/ for fornecido, inspecione apenas arquivos de plano e o arquivo de estado dentro desse diretório.
• Se um caminho de arquivo de requisito for fornecido, leia-o diretamente e trate-o como a fonte de requisitos mais recente.
• Se a entrada for texto bruto do chat, trate o texto completo do usuário como a fonte de requisitos mais recente.
• Se tanto uma fonte de requisitos quanto um diretório plans/ estiverem disponíveis, use sempre ambos.

Falhe imediatamente se qualquer arquivo ou diretório referenciado não existir ou não for legível.

Idioma de Saída

Use estas regras:

• Corresponda todo o idioma da saída visível ao usuário ao idioma dominante da fonte de requisitos mais recente.
• Se não existir fonte de requisitos, corresponda ao idioma dominante da entrada do usuário na rodada atual.
• Se o usuário pedir explicitamente tradução ou um idioma de saída específico, siga isso.

Seleção de Modo

Padrão para modo plan.

Mude para o modo execute somente quando o usuário emitir explicitamente um comando de execução na rodada atual.

Exemplos que RESOLVEM para o modo execute:

• 开始执行
• 按这个方案实现
• 去改代码
• 直接落地
• implement now
• apply the plan

Exemplos que NÃO mudam o modo do comportamento padrão plan:

• LGTM
• OK
• 继续
• 按这个方向
• review 过了
• qualquer aprovação que confirme o plano, mas não peça explicitamente para iniciar a implementação

Use estas regras:

• Aprovação de revisão não é aprovação de execução.
• Se o usuário for ambíguo, permaneça no modo plan e refine o plano de execução ou peça um comando de execução mais claro.
• Nunca infira intenção de execução a partir de momentum, otimismo ou falta de objeções.

Localização e Nomenclatura de Saída

Escreva arquivos de plano em um diretório plans/:

• Se a fonte for um arquivo de requisito, use uma pasta plans/ ao lado desse arquivo.
• Se a fonte for um arquivo de plano ou diretório plans/, continue escrevendo nesse mesmo diretório plans/.
• Se a fonte for texto bruto do chat, use <cwd>/plans/.

Crie o diretório plans/ se ele não existir.

Arquivos de plano base usam este formato:

• <module-slug>.md

Arquivos de plano de revisão usam este formato:

• <module-slug>.rev-<n>.md

O arquivo de checklist derivado deve ser:

• checklist.md

O arquivo de estado oculto deve ser:

• .state.json

Use estas regras de nomenclatura:

• new-plan pode criar um arquivo base se o módulo não tiver linhagem anterior.
• revise-plan e obsolete-plan devem sempre escrever um novo arquivo rev.
• no-op não deve escrever um novo arquivo de plano.
• Não sobrescreva um arquivo existente silenciosamente.
• Slugs de plano devem seguir a propriedade de implementação, não o texto do cabeçalho do requisito, quando os dois diferirem.
• Se a fonte de requisitos mais recente for um arquivo legível, escreva checklist.md ao lado desse arquivo de requisito, em vez de dentro de plans/.
• Se nenhum arquivo de requisito legível existir, volte a escrever checklist.md dentro do diretório plans/ ativo.
• Sempre sobrescreva o caminho resolvido de checklist.md no local quando puder ser atualizado com segurança.
• checklist.md é um snapshot derivado, não um artefato de linhagem de plano e não um alvo de execução.

Arquivo de Estado

Mantenha plans/.state.json como a linha de base do planejamento.

O arquivo de estado deve conter no mínimo:

• requirement_source
• requirement_hash
• run_at
• modules

Cada objeto de estado do módulo deve conter no mínimo:

• slug
• title
• status
• source_excerpt_hash
• body_hash_without_heading
• latest_plan_file
• latest_rev
• last_action

Os valores de status devem ser explícitos:

• active
• obsolete

Use estas regras:

• O arquivo de estado descreve apenas a linhagem do planejamento.
• Não trate o arquivo de estado como permissão para executar.
• Se o arquivo de estado estiver faltando, inicialize a partir da fonte de requisitos mais recente e dos arquivos de plano existentes, em vez de falhar.

Modo de Plano

Use docs/plan.md como o contrato detalhado de escrita do plano.

Extração de Módulo

Padrão para dividir por unidades de implementação e limites de dependência, não pela estrutura de pacotes do repositório e não mecanicamente por cabeçalhos de requisito.

Antes de extrair módulos ou computar qualquer hash de requisito, pré-processe a fonte de requisitos mais recente removendo comentários HTML fora de blocos de código cercados.

Use estas regras:

• Trate conteúdo de requisito comentado como inexistente.
• Comece apenas a partir de seções de requisito como um auxílio de extração, não como o limite final do módulo.
• Trate seções meta, como antecedentes, objetivos, escopo, não-objetivos, premissas, rollout, critérios de aceitação e requisitos não funcionais, como restrições globais, não módulos independentes.
• Mescle fatias de requisito que recaem no mesmo caminho de implementação, superfície de código compartilhada ou entrega no mesmo nível de proprietário.
• Divida uma seção apenas quando ela descrever claramente entregas independentes ou uma sequência de implementação estrita, como trabalho de fundação antes do trabalho de funcionalidade.
• Prefira limites de módulo que correspondam à propriedade funcional, propriedade de interface compartilhada, limites de migração ou limites de implantação.
• Não crie módulos sobrepostos que ambos possuam a mesma mudança compartilhada.
• Falhe ruidosamente se nenhum módulo com carga de implementação puder ser extraído ou se a propriedade compartilhada não puder ser atribuída claramente.

Se a fonte for texto simples sem cabeçalhos confiáveis:

• derive uma lista concisa de módulos do conteúdo do requisito
• use limites de funcionalidade, fluxos de trabalho, entregas e relações de pré-requisito como nomes de módulo
• evite nomes de módulo genéricos como misc, other ou supporting-work

Modelagem de Dependência e Paralelismo

Após extrair módulos candidatos, derive um grafo de dependência explícito antes da classificação ou criação de subagentes.

Use estas regras:

• Classifique cada módulo como foundation, feature ou follow-on.
• Registre depends_on, blocks, parallelizable_with e shared_change_owner.
• Prefira módulos paralelos apenas quando eles não exigirem a mesma propriedade de código compartilhada na mesma fase.
• Prefira sequenciamento serial quando um módulo alterar contratos, esquemas, migrações ou utilitários compartilhados que outro módulo consome.
• Se a implementação for A então B, modele isso diretamente em vez de forçar ambos em uma lista de pares.
• Não infira paralelismo falso. Sequencie conservadoramente se a ordenação segura não estiver clara.

Detecção de Revisão e Linhagem

A detecção de revisão só é significativa dentro de plans/*.md.

Use estas regras:

• Trate qualquer comentário HTML fora de blocos de código cercados como uma nota de revisão.
• Se o conteúdo de revisão nos comentários do usuário conflitar com o documento de requisito original, trate o conteúdo de revisão como a instrução autoritativa mais recente.
• Não preserve comentários HTML na saída final do plano.
• Resolva o artefato de linhagem mais recente pelo rev mais alto, caso contrário, pelo arquivo base mais recente.
• Prefira correspondências de slug primeiro.
• Permita correspondência de renomeação apenas para correspondências seguras de um para um em body_hash_without_heading.
• Se a correspondência de renomeação for ambígua, não adivinhe.

Geração de Checklist

Gere ou atualize checklist.md durante toda execução bem-sucedida do modo plan.

Use estas regras:

• Construa o checklist a partir da fonte de requisitos mais recente mais notas de revisão autoritativas da linhagem de plano mais recente.
• Aplique o mesmo pré-processamento de requisito usado para extração de módulo antes de derivar itens do checklist.
• Trate comentários de revisão como autoritativos quando eles conflitarem com o documento de requisito original.
• Nunca preserve comentários HTML brutos em checklist.md; preserve apenas sua intenção resolvida.
• Organize seções do checklist por camada de dependência e ordem do módulo, não pela ordem bruta do cabeçalho do requisito.
• Use cabeçalhos Markdown mais itens acionáveis não marcados, como - [ ] ....
• Prefira resultados de implementação ou aceitação verificáveis, não resumos narrativos.
• Se a fonte de requisitos mais recente for um arquivo legível, escreva checklist.md ao lado desse arquivo de requisito.
• Se nenhum arquivo de requisito legível existir, escreva checklist.md dentro do diretório plans/ ativo.
• Se a fonte for um arquivo de plano ou diretório plans/, resolva a fonte de requisitos legível mais recente de plans/.state.json antes de atualizar o checklist.
• Se uma fonte de requisitos não puder ser reconstruída com segurança, permita que revisões de plano orientadas por revisão prossigam, mas relate que checklist.md não pôde ser atualizado.

Classificação de Modo Misto

Determine a ação por módulo, não uma vez para toda a execução.

Classifique cada módulo em exatamente uma ação:

• new-plan
• revise-plan
• obsolete-plan
• no-op

Use estes padrões:

• Mescle mudanças de requisito e notas de revisão em um revise-plan.
• Gere uma revisão obsolete-plan em vez de descartar silenciosamente módulos removidos.
• Quando nenhuma fonte de requisitos estiver disponível, permita apenas revisões orientadas por revisão.
• Edições somente de comentário na fonte de requisitos não devem acionar revise-plan.

Subagentes de Plano

Gere um subagente de planejamento por módulo afetado após travar a lista de módulos, grafo de dependência e ação.

Use estas regras:

• Prefira subagentes de análise somente leitura para o trabalho de planejamento.
• Use um subagente de propósito geral apenas se uma função de análise somente leitura dedicada não estiver disponível e o subagente ainda puder permanecer somente leitura.
• Subagentes de planejamento não devem editar arquivos.
• Execute subagentes de planejamento em paralelo apenas dentro da mesma camada de dependência.
• Peça a cada subagente de planejamento para retornar áreas de código afetadas, interfaces, dependências, notas de paralelismo, riscos, testes e premissas explícitas.

Montagem do Plano

O agente principal é o proprietário da qualidade final do plano, saída do arquivo de plano e atualizações do arquivo de estado.

Use estas regras:

• Resolva dependências entre módulos para que a terminologia e as mudanças compartilhadas permaneçam consistentes.
• Confirme um proprietário claro para cada interface compartilhada, esquema, migração ou mudança de infraestrutura.
• Ordene a saída final do módulo de acordo com as camadas de dependência, em vez da ordem do cabeçalho do requisito.
• Afirme explicitamente quando um módulo está bloqueado por outro módulo ou pode ser executado em paralelo após pré-requisitos.
• Atualize checklist.md após os planos do módulo serem montados e antes de atualizar o arquivo de estado.
• Atualize plans/.state.json somente após todos os módulos afetados serem processados.

Modo de Execução

Use docs/execute.md como o contrato detalhado de execução.

Pré-condições de Execução

Falhe imediatamente se qualquer um destes for verdadeiro:

• nenhum arquivo de plano alvo ou diretório plans/ pode ser resolvido
• o artefato de plano alvo mais recente ainda contém comentários de revisão não resolvidos
• o repositório não pode ser fundamentado o suficiente para atribuir propriedade de escrita com segurança
• a propriedade de mudança compartilhada é ambígua
• ciclos de dependência não podem ser justificados como um módulo mesclado

Regras de Execução

Após a porta e as pré-condições serem satisfeitas:

• use docs/execute.md para resolução de alvo, fundamentação, despacho de worker, integração, verificação e conclusão
• execute o artefato revisado mais recente para cada linhagem de módulo selecionada
• respeite o grafo de dependência produzido no modo de plano ou reconstrua-o a partir do conjunto de planos mais recente antes do despacho

Regras de Falha

Pare e relate o problema em vez de gerar saída fraca quando:

• o arquivo de requisito, arquivo de plano ou diretório de planos está faltando ou ilegível
• a extração de módulo falha para uma fonte de requisitos necessária
• um plano seria principalmente especulação sem uma amarra significativa com a base de código
• múltiplos candidatos de linhagem mais recente existem para um módulo e a ordenação não pode ser resolvida com segurança
• a correspondência de renomeação é ambígua e não pode ser reduzida a um mapeamento seguro de um para um
• mudanças compartilhadas ou propriedade de dependência não podem ser atribuídas a um módulo ou fluxo de trabalho claro
• o grafo de dependência contém ciclos que não podem ser justificados como um único módulo mesclado
• o arquivo de estado existe, mas está malformado e não pode ser reconstruído com segurança a partir de artefatos visíveis

Não emita arquivos de plano vazios, arquivos somente de resumo ou um único plano agregado quando a tarefa exigir saídas por módulo.