publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

.

Browse source
This commit is contained in:
Luiz Silva 2026-09-28 22:02:00 -03:00
parent e899107f22
commit f5abcec365
8 changed files with 427 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

19
skills/plano-executar/SKILL.md Normal file
View file

@ -0,0 +1,19 @@
---
name: plano-executar
description: Alias para /plano.executar - Executa planos técnicos em ./PLANOS/pendente/ com postura obstinada /goal e orquestração de multiagentes (@back, @front, @ux, @refatorar, @testes, @documentacao)
scope: global
updatedAt: "2026-09-28"
---
# Skill: /plano-executar (Alias para /plano.executar com /goal e Multiagentes)
Atalho para a skill canônica [`/plano.executar`](../plano.executar/SKILL.md), executando planos técnicos enfileirados em `./PLANOS/pendente/`:
- **Postura `/goal`:** Execução autônoma contínua, profunda e resiliente com loop de auto-correção até 100% de validação verde (DoD).
- **Multiagentes Especialistas:** Coordenação de `@back`, `@front`, `@ux`, `@refatorar`, `@testes` e `@documentacao`.
- **Modos de Invocação:**
- `/plano.executar` ou `/plano.executar ultimo` $\rightarrow$ Executa o último plano criado na conversa (ou o mais recente na pasta).
- `/plano.executar <identificador>` $\rightarrow$ Executa o plano correspondente por slug, ID ou nome de arquivo.
- `/plano.executar todos` $\rightarrow$ Executa todos os planos pendentes na pasta em modo serial sequencialmente.
Para a especificação completa, matriz de papéis e detalhes operacionais, consulte [`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md).

150
skills/plano.executar/SKILL.md Normal file
View file

@ -0,0 +1,150 @@
---
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-28"
---
# 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-28-reabrir-licenca-nao-assinada
/plano.executar reabrir-licenca-nao-assinada
# Modo 3: Executar todos os planos da pasta de forma serial (um a um)
/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 --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`)
1. **Contexto da Conversa:**
- O agente busca no histórico imediato da sessão se algum plano foi criado recentemente em `./PLANOS/pendente/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 data/modificação).
3. **Confirmação:**
- Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/YYYY-MM-DD-<slug>.md — "<Título>"`
### Modo 2: Por Identificador (`/plano.executar <identificador>`)
1. Procura em `./PLANOS/pendente/` por ID exato, nome do arquivo ou correspondência parcial de 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. Lista todos os planos `.md` em `./PLANOS/pendente/` (desconsiderando `.gitkeep`).
2. Ordena por criticidade/data.
3. Executa sequencialmente um por um, aplicando o ciclo completo `/goal` para cada plano antes de passar ao seguinte.
4. **Circuit Breaker:** Se um plano encontrar um bloqueio técnico insuperável mesmo após auto-correções, o lote é interrompido para não corromper o repositório.
---
## 💻 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:
1. **Atualizar Metadados e Histórico do Plano:**
- Frontmatter: `status: "executado"`, `data-execucao: "YYYY-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/YYYY-MM-DD-<slug>.md` e remover de `./PLANOS/pendente/`.
3. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-YYYY-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`.
4. **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.

64
skills/plano/SKILL.md
View file

@ -5,30 +5,32 @@ scope: global
updatedAt: "2026-09-28"
---
# Skill: /plano (Gestão e Execução de Planos Técnicos)
# Skill: /plano (Criação e Gestão de Planos Técnicos)
Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** e o **Desenvolvedor**, formalizando demandas de homologação em planos de implementação completos na pasta `./PLANOS/pendente/` e executando-os deterministamente para posterior arquivamento em `./PLANOS/executado/`.
Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** e o **Desenvolvedor**, formalizando demandas de homologação em planos de implementação completos na pasta `./PLANOS/pendente/` sem interromper a rotina de testes. Para a fase de implementação e codificação, aciona-se a skill dedicada [`/plano.executar`](../plano.executar/SKILL.md).
---
## 🎯 Gatilhos e Comandos
A skill é acionada por comandos iniciando com `/plano`:
```bash
# 1. Criação de novo plano técnico (Fase de Tester / Review)
/plano <instrução ou descrição da melhoria / bug>
# 2. Listagem da fila de planos
# 2. Listagem e panorama da fila de planos
/plano listar
# 3. Execução de um plano existente (Fase de Desenvolvimento)
/plano executar <slug-ou-nome-do-arquivo>
# 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado)
/plano.executar # Executa o último plano da conversa ou mais recente
/plano.executar <slug> # Executa plano específico por slug/ID
/plano.executar todos # Executa todos os pendentes em lote serial
# 4. Arquivamento manual de um plano já concluído
/plano arquivar <slug-ou-nome-do-arquivo>
```
> 💡 **Nota de Compatibilidade:** Caso o operador invoque a sintaxe `/plano executar <slug>`, o agente automaticamente acionará o procedimento canônico de [`/plano.executar`](../plano.executar/SKILL.md).
---
## 🛠️ Procedimento Operacional: Criação de Plano (`/plano <instrução>`)
@ -72,13 +74,13 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
- **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso.
- **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido).
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser`.
- **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão.
- **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor.
- Salve o arquivo em `./PLANOS/pendente/YYYY-MM-DD-<slug>.md` usando `write_to_file`.
### 4. Resposta ao Usuário
- Informe o link do arquivo criado em `./PLANOS/pendente/`.
- Apresente um resumo sucinto dos módulos impactados e critérios de aceite.
- Sinalize que o plano está na fila e que o tester pode continuar a homologação criando novos planos ou solicitar a execução via `/plano executar <slug>`.
- Sinalize que o plano está na fila e que o tester pode continuar a homologação criando novos planos com `/plano` ou solicitar a implementação via `/plano.executar`.
---
@ -87,47 +89,27 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
1. Liste os arquivos existentes em `./PLANOS/pendente/` e `./PLANOS/executado/`.
2. Para cada arquivo, extraia título, data e prioridade do frontmatter.
3. Exiba uma tabela Markdown organizada:
- **Planos Pendentes (Aguardando Dev)**
- **Planos Executados (Concluídos)**
- **Planos Pendentes (Aguardando Dev):** ID, Título, Prioridade, Data de Criação.
- **Planos Executados (Concluídos):** ID, Título, Data de Execução, Executor.
4. Lembre o operador dos atalhos de execução: `/plano.executar` ou `/plano.executar todos`.
---
## 🛠️ Procedimento Operacional: Execução (`/plano executar <slug>`)
## 🛠️ Procedimento Operacional: Execução
Quando invocado para implementar um plano existente:
Para implementar qualquer plano da fila, a operação canônica é delegada para:
### 1. Localização e Leitura
- Localize o arquivo em `./PLANOS/pendente/` correspondente ao slug fornecido.
- Leia o conteúdo integral com `view_file`.
### 2. Implementação Rigorosa
- Execute as mudanças solicitadas nos pacotes apropriados, seguindo:
- `rules/diagnostico-antes-correcao.md`
- `rules/literatura-tecnica-e-usabilidade.md`
- `workflows/codigo-limpo.md` (limite de 250 linhas por arquivo, Dispatch Tables)
- `rules/feedback-visivel.md` (feedback claro na UI e logs no backend)
- `rules/fronteiras-monorepo.md` (não vazar dependências entre back e front)
### 3. Validação e Qualidade
- Execute checagens de integridade:
- `biome check --write <arquivos-alterados>`
- `bun run typecheck` ou `tsc --noEmit` (se aplicável ao pacote)
- `sh .agent/verificar-linhas.sh`
- Valide os critérios de aceite definidos na Seção 3 do plano.
### 4. Transição para Executado
- Atualize o conteúdo do plano:
- Frontmatter: `status: "executado"`, `data-execucao: "YYYY-MM-DD HH:mm"`, `executor: "<nome-ou-agente>"`.
- Seção 6 (`Histórico de Execução`): registre arquivos modificados, resumo da solução e evidências de validação.
- Mova o arquivo de `./PLANOS/pendente/YYYY-MM-DD-<slug>.md` para `./PLANOS/executado/YYYY-MM-DD-<slug>.md` (usando `write_to_file` no destino e removendo da pasta pendente).
- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-<slug>.md` e indexe em `memorias-ia/historico-acoes.md`.
- Lembre-se: **nunca execute git commit na aplicação** (`rules/proibido-commit-ia.md`). Sugira a mensagem de commit para o usuário.
👉 **[`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md)**:
- `/plano.executar` (sem argumentos: último plano criado na conversa ou pendente mais recente)
- `/plano.executar <slug>` (plano específico)
- `/plano.executar todos` (processamento serial com circuit breaker)
---
## 🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar <slug>`)
## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar <slug>`)
Quando um plano foi implementado externamente ou não requer alteração de código:
1. Localize o arquivo em `./PLANOS/pendente/`.
2. Atualize o frontmatter para `status: "executado"` e registre a data.
2. Atualize o frontmatter para `status: "executado"`, registrando `data-execucao` e executor.
3. Mova o arquivo para `./PLANOS/executado/`.
4. Notifique o usuário da conclusão do arquivamento.