2026-09-30 10:50:44 -03:00

11 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:

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.
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.
Comprovação Baseada em Evidências: Apenas testes reais e verificações executadas contam como conclusão. 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 e CSS co-localizado.
`@ux` (UX Specialist)	`*-front` (Interface & Heurísticas)	Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário.
`@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 --headed`.
`@documentacao` (Memory & Docs)	`memorias-ia/`, `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 (`wiki/dev/<modulo>/`).

🔄 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 feedback visual, loading e estados de erro na tela
      ↓
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 --headed
      ↓ (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`)

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).
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).
Confirmação:
- Exibe: 🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"

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

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>).
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`)

Listar Fila: Lista todos os planos .md em ./PLANOS/pendente/ (desconsiderando .gitkeep).
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.
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>"
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.
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:

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.
Mover o Plano:
- Salvar em ./PLANOS/executado/<nome-original>.md e remover de ./PLANOS/pendente/<nome-original>.md (preservando o nome original do arquivo).
Memória do Projeto (Pilar 6 - @documentacao):
- Criar memorias-ia/sessao-AAAA-MM-DD-<slug>.md.
- Indexar no memorias-ia/historico-acoes.md.
Staging de Segurança:
- Executar git add <arquivos> e git status.
- Relembrar a regra rules/proibido-commit-ia.md: nunca executar git commit na aplicação. Sugerir o comando semântico para o operador.
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.

11 KiB Raw Blame History