publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/global/skills/plano.executar/SKILL.md

12 KiB
Raw Blame History

name description scope updatedAt
plano.executar Executa planos técnicos de implementação em ./PLANOS/pendente/ com postura /goal e orquestração de multiagentes especialistas (@back, @front, @ux, @refatorar, @testes, @documentacao) global 2026-09-30

Skill: /plano.executar (Execução de Planos Técnicos com /goal e Multiagentes)

Esta skill é responsável pela implementação e execução técnica determinística de planos de trabalho previamente criados pelo Tester / QA em ./PLANOS/pendente/.

O agente atua como Orquestrador Líder, operando sob a postura obstinada do /goal (autonomia completa, auto-correção iterativa e não encerramento até validação total) e coordenando um time de multiagentes especialistas para implementar, refatorar, testar e arquivar as demandas.

🎯 Formas de Invocação e Modos de Operação

# Modo 1: Executar o último plano criado na conversa (ou o pendente mais recente)
/plano.executar
/plano.executar ultimo

# Modo 2: Executar plano específico por identificador (slug, ID ou nome de arquivo)
/plano.executar <identificador>
# Exemplos:
/plano.executar 2026-09-30-10-35-reabrir-licenca-nao-assinada
/plano.executar reabrir-licenca-nao-assinada

# Modo 3: Executar todos os planos da pasta em ordem de chegada (FIFO - Primeiro que chega é o primeiro executado)
/plano.executar todos
/plano.executar --todos

⚡ Postura Operacional /goal (Execução Obstinada)

Ao acionar /plano.executar, o agente adota estritamente o compromisso do /goal:

  1. Autonomia sem Paradas Prematuras: O agente não interrompe a execução para pedir confirmações triviais ou fazer perguntas óbvias. Ele pesquisa o codebase, diagnostica causas raiz e aplica as correções de ponta a ponta.
  2. Loop Iterativo de Auto-Correção: Caso um comando de build, linter (biome) ou verificação estática (typecheck) aponte erros:
    • O agente NÃO desiste nem pede ajuda imediatamente.
    • Ele analisa o stack trace / log de erro, diagnostica a causa raiz, refatora o trecho e roda a validação novamente.
    • Esse loop continua até que todos os critérios de aceite (Definition of Done) estejam 100% verdes.
  3. Comprovação Baseada em Evidências (.evidencias/): Apenas testes reais e verificações executadas contam como conclusão, com todas as evidências geradas pelos testes automatizados salvas obrigatoriamente na pasta .evidencias/. Não há "deve estar funcionando" sem validação com comandos concretos.

👥 Matriz de Multiagentes Especialistas

O Orquestrador Líder decompõe a especificação técnica do plano e distribui a execução entre os especialistas conforme os módulos impactados:

Especialista Papel & Escopo de Atuação Principais Responsabilidades
@back (Backend Specialist) *-back, *-comuns, *-migracao Endpoints Bun/Hono/Express, queries Knex, tabelas PostgreSQL, migrações, schemas Zod e types de contrato em *-comuns.
@front (Frontend Specialist) *-front, *-comuns Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs, CSS co-localizado e despoluição visual (refactoring-ui-hierarquia-despoluicao).
@ux (UX Specialist) *-front (Interface, Heurísticas, Fluxo Funcional & Refactoring UI) Aplicação das Heurísticas de Nielsen, ux-fluxo-funcional e refactoring-ui-hierarquia-despoluicao (livro no Paiol: https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf): navegação exclusiva no MenuLateral.vue ordenada pela jornada, pré-requisitos guiados, revelação progressiva (12 colunas), pirâmide de ações (1 primária sólida; destrutivas discretas fora do modal), zero Card-ception / menos bordas, consolidação de colunas em tabelas, contraste de tokens Vuetify (secondary escuro), zero jargão técnico e feedback imediato.
@refatorar (Clean Code Specialist) Todo o código alterado Governança estrita das 12 regras de Código Limpo: garantia do limite de 250 linhas por arquivo, eliminação de code smells, modularidade e Dispatch Tables.
@testes (QA & Automation) Checagens e Validação E2E Tipagem (bun run typecheck / tsc --noEmit), linter (biome check --write), governança (sh .agent/verificar-linhas.sh) e testes de interface visual via agent-browser --session <modulo>_<contexto?> --headed com evidências salvas em .evidencias/.
@documentacao (Memory & Docs) memorias-ia/, <modulo-wiki>/ Registro de sessão no Pilar 6 (memorias-ia/sessao-*.md), indexação no historico-acoes.md, atualização de regras técnicas na Wiki de Dev (<modulo-wiki>/dev/<modulo-id>/).

🔄 Protocolo de Invocação e Handoff Multiagente

Método A: Invocação de Subagentes (invoke_subagent)

Quando uma etapa demandar isolamento de contexto ou execução especializada profunda, o Orquestrador invoca subagentes via invoke_subagent:

  • TypeName: "self"
  • Role: "Backend Specialist (@back)" (ou @front, @testes, etc.)
  • Prompt: Descreve a fração específica da Seção 4 do plano a ser implementada, com os critérios de aceite esperados.

Método B: Execução Sequencial de Fases Especializadas (Pipeline)

Em implementações integradas, o Orquestrador segue a ordem canônica de handoff:

1. [@back]        Implementa rotas, serviços e schemas Zod em *-comuns
      ↓
2. [@front]       Implementa componentes e telas consumindo os novos schemas
      ↓
3. [@ux]          Audita fluxo funcional (ux-fluxo-funcional), navegação visível, contraste e estados de UI
      ↓
4. [@refatorar]   Extrai módulos se exceder 250 linhas e aplica Código Limpo
      ↓
5. [@testes]      Roda typecheck, biome e testes E2E com agent-browser --session <modulo>_<contexto?> --headed (evidências em .evidencias/)
      ↓ (Loop /goal de auto-correção se houver falhas)
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano

🛠️ Procedimento Operacional: Resolução do Alvo (Target Resolution)

Modo 1: Sem parâmetros (/plano.executar ou /plano.executar ultimo)

  1. Contexto da Conversa:
    • O agente busca no histórico imediato da sessão se algum plano foi criado recentemente em ./PLANOS/pendente/ (padrão AAAA-MM-DD-HH-mm-<slug>.md ou legado YYYY-MM-DD-<slug>.md).
  2. Fallback para o Mais Recente na Pasta:
    • Se nenhum foi criado na sessão, inspeciona ./PLANOS/pendente/ e seleciona o arquivo mais recente (ordem decrescente de timestamp / data de modificação).
  3. Confirmação:
    • Exibe: 🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"

Modo 2: Por Identificador (/plano.executar <identificador>)

  1. Procura em ./PLANOS/pendente/ por correspondência de ID exato, nome do arquivo ou correspondência parcial de slug (aceita tanto nomes com timestamp AAAA-MM-DD-HH-mm-<slug> quanto nomes legados YYYY-MM-DD-<slug>).
  2. Em caso de ambiguidade, lista as opções para confirmação; se não encontrado, orienta verificar com /plano listar.

Modo 3: Execução Serial de Toda a Fila (/plano.executar todos ou --todos)

  1. Listar Fila: Lista todos os planos .md em ./PLANOS/pendente/ (desconsiderando .gitkeep).
  2. Ordenar em Estrita Ordem de Chegada (FIFO — First In, First Out):
    • Ordena os arquivos em ordem cronológica de chegada (o plano mais antigo criado é executado primeiro).
    • Com a nomenclatura AAAA-MM-DD-HH-mm-<slug>.md, a ordenação alfabética/lexicográfica ascendente padrão (sort ou Array.prototype.sort()) corresponde naturalmente à ordem temporal de criação.
    • Compatibilidade com Planos Legados: Caso existam arquivos legados sem hora no nome (YYYY-MM-DD-<slug>.md), o agente utiliza o horário de modificação/criação do arquivo (mtime) ou o campo data-criacao do frontmatter para intercalá-los na ordem temporal exata.
  3. Execução Sequencial:
    • Executa um por um na ordem da fila, aplicando o ciclo completo /goal para cada plano antes de passar ao seguinte.
    • Exibe o progresso: 🎯 [Orquestrador /goal] [Fila X/N] Executando PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"
  4. Conclusão da Fila ou Circuit Breaker:
    • Ao finalizar com sucesso toda a fila de pendentes: sh .agent/notificar.sh "Fila de Planos Concluída" "Todos os planos foram executados com sucesso!" sucesso
    • Se um plano encontrar um bloqueio técnico insuperável mesmo após auto-correções, o lote é interrompido com relatório claro para não corromper o repositório nem propagar falhas, e o operador é alertado: sh .agent/notificar.sh "Execução Interrompida" "O plano <nome> encontrou um bloqueio técnico." erro

💻 Ciclo de Execução Obstinada /goal (Para cada plano)

1. Leitura e Decomposição

  • Lê o plano integralmente com view_file.
  • Mapeia os critérios de aceite (Definition of Done) na Seção 3 e especificações na Seção 4.
  • Caso novos arquivos precisem ser inspecionados além dos previstos no plano, consulta o Grafo de Conhecimento via bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>" ou bash .agent/scripts/graphify.sh impact <arquivos>.
  • Orquestrador define os especialistas necessários.

2. Implementação Especializada

  • Os especialistas aplicam as mudanças no código de acordo com suas responsabilidades:
    • @back: rotas, queries, schemas Zod, tratamentos defensivos.
    • @front: telas Vue 3, composables, formulários com eli-vue e Vuetify 3.
    • @ux: visibilidade de estados, linguagem do domínio e feedbacks compreensíveis.
    • @refatorar: garantia estrita de máximo 250 linhas por arquivo e Dispatch Tables.

3. Loop /goal de Validação e Auto-Correção

  • Executar verificações estáticas:
    • Formatação e linter: biome check --write <arquivos>
    • Tipagem estrita: bun run typecheck ou tsc --noEmit
    • Governança de arquivos: sh .agent/verificar-linhas.sh
    • Validação de critérios de aceite (DoD) e testes de interface se especificado.
  • Se houver erro: o especialista correspondente atua imediatamente corrigindo a causa raiz até compilação 100% verde.

📦 Arquivamento, Memória e Conclusão

Ao atingir 100% de conformidade com todos os critérios do plano:

  1. Atualizar Metadados e Histórico do Plano:
    • Frontmatter: status: "executado", data-execucao: "AAAA-MM-DD HH:mm", executor: "Orquestrador /goal + Multiagentes (@back, @front, @ux, @refatorar, @testes, @documentacao)".
    • Seção 6 (Histórico de Execução): arquivos modificados, resumo da solução e evidências de validação salvas em .evidencias/.
  2. Mover o Plano:
    • Salvar em ./PLANOS/executado/<nome-original>.md e remover de ./PLANOS/pendente/<nome-original>.md (preservando o nome original do arquivo).
  3. Atualizar Grafo de Conhecimento (Graphify):
    • Executar bash .agent/scripts/graphify.sh update para atualizar o grafo de código com os novos símbolos, arquivos e relações implementados (garantindo automaticamente a instalação via Bun se ausente e as regras no .gitignore).
  4. Memória do Projeto (Pilar 6 - @documentacao):
    • Criar memorias-ia/sessao-AAAA-MM-DD-<slug>.md.
    • Indexar no memorias-ia/historico-acoes.md.
  5. Sugestão de Mensagem de Commit (Sem Executar Commit):
    • Inspecionar os arquivos modificados com git status --short.
    • NUNCA executar git commit ou git push no projeto ou na Wiki — o commit é exclusivo do operador humano (ver rules/proibido-commit-ia.md).
    • Apresentar ao operador humano a sugestão de mensagem de commit no padrão Conventional Commits pronta para copiar: 💬 Sugestão de Commit: <tipo>(<escopo>): <descrição>
  6. Notificação no Sistema Operacional (Linux & macOS):
    • Disparar notificação sonora e visual no SO via script .agent/notificar.sh: sh .agent/notificar.sh "Plano Concluído" "<Nome ou Título do Plano>" sucesso
    • O utilitário detecta automaticamente se o host é Linux (KDE kdialog, notify-send, gdbus, PipeWire/PulseAudio) ou macOS (osascript banner nativo + afplay áudio Glass + terminal bell \a), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI.