168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
---
|
|
name: plano.executar
|
|
description: 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)
|
|
scope: global
|
|
updatedAt: "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
|
|
|
|
```bash
|
|
# 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:** 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 --session <modulo>_<contexto?> --headed`. |
|
|
| **`@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 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 --session <modulo>_<contexto?> --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`)
|
|
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.
|
|
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.
|