From f5abcec365186c15f35e91b3fa2d0c93e5e7c97d Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Mon, 28 Sep 2026 22:02:00 -0300 Subject: [PATCH] . --- global/skills/plano-executar/SKILL.md | 19 ++++ global/skills/plano.executar/SKILL.md | 150 ++++++++++++++++++++++++++ global/skills/plano/SKILL.md | 64 ++++------- global/workflows/plano.md | 83 +++++++------- manifesto.json | 1 + skills/plano-executar/SKILL.md | 19 ++++ skills/plano.executar/SKILL.md | 150 ++++++++++++++++++++++++++ skills/plano/SKILL.md | 64 ++++------- 8 files changed, 427 insertions(+), 123 deletions(-) create mode 100644 global/skills/plano-executar/SKILL.md create mode 100644 global/skills/plano.executar/SKILL.md create mode 100644 skills/plano-executar/SKILL.md create mode 100644 skills/plano.executar/SKILL.md diff --git a/global/skills/plano-executar/SKILL.md b/global/skills/plano-executar/SKILL.md new file mode 100644 index 0000000..f0f048e --- /dev/null +++ b/global/skills/plano-executar/SKILL.md @@ -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 ` $\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). diff --git a/global/skills/plano.executar/SKILL.md b/global/skills/plano.executar/SKILL.md new file mode 100644 index 0000000..2aeb320 --- /dev/null +++ b/global/skills/plano.executar/SKILL.md @@ -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 +# 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//`). | + +--- + +## 🔄 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-.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-.md — ""` + +### Modo 2: Por Identificador (`/plano.executar `) +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 ` + - 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-.md` e remover de `./PLANOS/pendente/`. +3. **Memória do Projeto (Pilar 6 - @documentacao):** + - Criar `memorias-ia/sessao-YYYY-MM-DD-.md`. + - Indexar no `memorias-ia/historico-acoes.md`. +4. **Staging de Segurança:** + - Executar `git add ` 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. diff --git a/global/skills/plano/SKILL.md b/global/skills/plano/SKILL.md index 49638f5..918ffd5 100644 --- a/global/skills/plano/SKILL.md +++ b/global/skills/plano/SKILL.md @@ -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 -# 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 +# 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado) +/plano.executar # Executa o último plano da conversa ou mais recente +/plano.executar # 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 ``` +> 💡 **Nota de Compatibilidade:** Caso o operador invoque a sintaxe `/plano executar `, o agente automaticamente acionará o procedimento canônico de [`/plano.executar`](../plano.executar/SKILL.md). + --- ## 🛠️ Procedimento Operacional: Criação de Plano (`/plano `) @@ -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-.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 `. +- 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 `) +## 🛠️ 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 ` - - `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: ""`. - - 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-.md` para `./PLANOS/executado/YYYY-MM-DD-.md` (usando `write_to_file` no destino e removendo da pasta pendente). -- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-.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 ` (plano específico) +- `/plano.executar todos` (processamento serial com circuit breaker) --- -## 🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar `) +## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar `) +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. diff --git a/global/workflows/plano.md b/global/workflows/plano.md index 6fe0f30..23aad74 100644 --- a/global/workflows/plano.md +++ b/global/workflows/plano.md @@ -1,19 +1,21 @@ --- type: workflow name: plano -description: Workflow oficial de Gestão, Criação e Execução de Planos Técnicos (fila PLANOS/pendente/ e PLANOS/executado/) +description: Workflow oficial de Gestão, Criação (/plano) e Execução (/plano.executar) de Planos Técnicos com postura /goal e multiagentes scope: global updatedAt: "2026-09-28" --- -# Workflow: /plano (Gestão de Planos Técnicos Tester ➔ Dev) +# Workflow: /plano e /plano.executar (Gestão e Execução de Planos Técnicos) -Workflow oficial para captura estruturada de demandas pelo **Tester / QA** durante homologações e execução determinística pelo **Desenvolvedor** no ecossistema Azteca. +Workflow oficial para captura estruturada de demandas pelo **Tester / QA** durante homologações e execução determinística pelo time de desenvolvimento com postura obstinada **/goal** e orquestração de **multiagentes especialistas** no ecossistema Azteca. > 💡 **Comandos Rápidos:** -> - `/plano ` $\rightarrow$ Diagnostica a demanda e gera um plano em `PLANOS/pendente/YYYY-MM-DD-.md`. +> - `/plano ` $\rightarrow$ Diagnostica a demanda sem mexer em código e gera um plano técnico em `PLANOS/pendente/YYYY-MM-DD-.md`. > - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes e executados. -> - `/plano executar ` $\rightarrow$ Carrega o plano pendente, implementa o código, valida e arquiva em `PLANOS/executado/`. +> - `/plano.executar` $\rightarrow$ Executa o último plano da conversa (ou pendente mais recente) sob a postura autônoma `/goal`. +> - `/plano.executar ` $\rightarrow$ Executa plano específico coordenando a equipe de especialistas (`@back`, `@front`, `@ux`, `@refatorar`, `@testes`, `@documentacao`). +> - `/plano.executar todos` $\rightarrow$ Executa sequencialmente todos os planos pendentes em lote serial (com circuit breaker). > - `/plano arquivar ` $\rightarrow$ Move manualmente um plano para `PLANOS/executado/`. --- @@ -22,26 +24,26 @@ Workflow oficial para captura estruturada de demandas pelo **Tester / QA** duran Durante a navegação, testes manuais ou homologação de telas e rotas, o tester frequentemente encontra inconsistências, comportamentos inesperados, melhorias visuais ou lacunas de negócio. -- **Problema anterior:** O tester precisava parar os testes para tentar implementar na hora, ou anotava observações soltas no chat que se perdiam ao final da conversa. -- **Solução com `/plano`:** O tester invoca `/plano `. A IA analisa tecnicamente o código e materializa a demanda em um arquivo padronizado em `PLANOS/pendente/`. O tester pode criar múltiplos planos em sequência na mesma sessão de review. Mais tarde, o desenvolvedor implementa cada um deles com foco total. +- **Fase de Homologação com `/plano`:** O tester invoca `/plano `. A IA analisa tecnicamente o código e materializa a demanda em um arquivo padronizado em `PLANOS/pendente/`. O tester pode criar múltiplos planos em sequência na mesma sessão de review sem parar os testes. +- **Fase de Execução com `/plano.executar`:** O desenvolvedor aciona `/plano.executar`. O agente assume o papel de **Orquestrador Líder sob postura `/goal`**, acionando subagentes especialistas (`@back`, `@front`, `@ux`, `@refatorar`, `@testes`, `@documentacao`) para implementar as demandas de forma autônoma e completa. --- ## 🔄 Fluxo de Operação em 4 Fases ``` -┌───────────────────────────┐ ┌───────────────────────────┐ -│ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │ -│ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │ -│ /plano │ │ │ -└───────────────────────────┘ └─────────────┬─────────────┘ - │ - ▼ -┌───────────────────────────┐ ┌───────────────────────────┐ -│ 4. ARQUIVAMENTO │ │ 3. IMPLEMENTAÇÃO DEV │ -│ (./PLANOS/executado/) │ ◀─── │ (Desenvolvedor / IA) │ -│ Metadados & Histórico │ │ /plano executar │ -└───────────────────────────┘ └───────────────────────────┘ +┌─────────────────────────────────┐ ┌─────────────────────────────┐ +│ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │ +│ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │ +│ /plano │ │ │ +└─────────────────────────────────┘ └──────────────┬──────────────┘ + │ + ▼ +┌─────────────────────────────────┐ ┌─────────────────────────────┐ +│ 4. ARQUIVAMENTO │ │ 3. ORQUESTRADOR DEV /goal │ +│ (./PLANOS/executado/) │ ◀─── │ Multiagentes Especialistas│ +│ Metadados & Histórico │ │ /plano.executar [...] │ +└─────────────────────────────────┘ └─────────────────────────────┘ ``` --- @@ -70,7 +72,7 @@ Quando o comando for executado: - Plano de Verificação & Testes. 4. **Feedback Imediato ao Tester:** - - Informa o caminho do plano gerado e confirma que o review pode prosseguir. + - Informa o caminho do plano gerado e confirma que o review pode prosseguir com novos testes ou acionar a execução via `/plano.executar`. --- @@ -82,28 +84,27 @@ Para visualizar o status atual de todos os planos: --- -## 💻 Fase 3: Execução pelo Desenvolvedor (`/plano executar `) +## 💻 Fase 3: Execução com /goal e Multiagentes (`/plano.executar`) -Quando o desenvolvedor (ou operador) ordenar a implementação de um plano: +A execução é conduzida pela skill canônica [`/plano.executar`](../skills/plano.executar/SKILL.md) atuando como **Orquestrador Líder**: -1. **Carregamento do Plano:** - - A IA lê o arquivo correspondente em `PLANOS/pendente/.md`. - - Se o usuário passou apenas parte do nome (ex.: `filtro-denuncia`), localiza o arquivo correspondente. +### 1. Postura Operacional /goal +- **Autonomia Contínua:** Não interrompe o fluxo para perguntas triviais; executa de ponta a ponta. +- **Loop de Auto-Correção:** Caso linter ou typecheck apresente falhas, diagnostica a causa raiz, refatora e retesta iterativamente até atingir validação 100% verde. -2. **Planejamento & Execução Cirúrgica:** - - Respeita as regras fundamentais: - - `rules/diagnostico-antes-correcao.md` - - `rules/literatura-tecnica-e-usabilidade.md` - - `workflows/codigo-limpo.md` (limite de 250 linhas, Dispatch Tables) - - `rules/feedback-visivel.md` (visibilidade de erros) - - `rules/fronteiras-monorepo.md` (respeitar fronteiras dos pacotes) - - Executa as alterações passo a passo nos pacotes afetados (`*-comuns`, `*-back`, `*-front`, etc.). +### 2. Ativação da Equipe de Especialistas +O Orquestrador divide as tarefas entre os especialistas: +- **`@back`**: Implementa endpoints, queries Knex e schemas Zod em `*-comuns`. +- **`@front`**: Implementa telas Vue 3, composables e formulários consumindo `*-comuns`. +- **`@ux`**: Aplica as Heurísticas de Nielsen (visibilidade de loading/erro, feedback imediato). +- **`@refatorar`**: Governança de Código Limpo (limite estrito de 250 linhas, Dispatch Tables). +- **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --headed`. +- **`@documentacao`**: Documenta a memória da sessão (Pilar 6) e regras de negócio. -3. **Verificação & Testes:** - - Roda checagem de tipos (`tsc --noEmit` / `bun run typecheck`). - - Roda formatação (`biome check --write `). - - Roda governança de linhas (`sh .agent/verificar-linhas.sh`). - - Valida os critérios de aceite definidos na seção 3 do plano. +### 3. Modos de Invocação +- **Modo 1: Sem parâmetros (`/plano.executar` ou `ultimo`)** $\rightarrow$ Localiza o último plano gerado no contexto da sessão ou mais recente na pasta. +- **Modo 2: Por identificador (`/plano.executar `)** $\rightarrow$ Localiza por slug, ID ou nome de arquivo. +- **Modo 3: Fila serial (`/plano.executar todos`)** $\rightarrow$ Processa todos os pendentes sequencialmente, um a um, com circuit breaker caso ocorra erro irrecuperável. --- @@ -115,7 +116,7 @@ Ao confirmar que a implementação está verde e validada: - Atualiza o frontmatter do arquivo: - `status: executado` - `data-execucao: "YYYY-MM-DD HH:mm"` - - `executor: ""` + - `executor: "Orquestrador /goal + Multiagentes (@back, @front, @ux, @refatorar, @testes, @documentacao)"` - Preenche a Seção 6 (`Histórico de Execução`) com o resumo das modificações feitas e evidências de validação. 2. **Movimentação do Arquivo:** @@ -124,7 +125,7 @@ Ao confirmar que a implementação está verde e validada: para: `PLANOS/executado/YYYY-MM-DD-.md` -3. **Registro na Memória do Projeto (Pilar 6):** +3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** - Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-.md`. - Indexa no `memorias-ia/historico-acoes.md`. - - Sugere o comando de commit staged para a aplicação (lembrando que commit automatizado na aplicação é proibido por `rules/proibido-commit-ia.md`). + - Executa `git add` nos arquivos alterados e sugere o comando de commit semântico ao operador (seguindo `rules/proibido-commit-ia.md`). diff --git a/manifesto.json b/manifesto.json index c9556ee..4ddd2f7 100644 --- a/manifesto.json +++ b/manifesto.json @@ -55,6 +55,7 @@ "global/skills/onboarding-projeto/SKILL.md", "global/skills/orquestrar-agentes/SKILL.md", "global/skills/plano/SKILL.md", + "global/skills/plano.executar/SKILL.md", "global/skills/testar-interface-agent-browser/SKILL.md" ] }, diff --git a/skills/plano-executar/SKILL.md b/skills/plano-executar/SKILL.md new file mode 100644 index 0000000..f0f048e --- /dev/null +++ b/skills/plano-executar/SKILL.md @@ -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 ` $\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). diff --git a/skills/plano.executar/SKILL.md b/skills/plano.executar/SKILL.md new file mode 100644 index 0000000..2aeb320 --- /dev/null +++ b/skills/plano.executar/SKILL.md @@ -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 +# 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//`). | + +--- + +## 🔄 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-.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-.md — ""` + +### Modo 2: Por Identificador (`/plano.executar `) +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 ` + - 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-.md` e remover de `./PLANOS/pendente/`. +3. **Memória do Projeto (Pilar 6 - @documentacao):** + - Criar `memorias-ia/sessao-YYYY-MM-DD-.md`. + - Indexar no `memorias-ia/historico-acoes.md`. +4. **Staging de Segurança:** + - Executar `git add ` 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. diff --git a/skills/plano/SKILL.md b/skills/plano/SKILL.md index 49638f5..918ffd5 100644 --- a/skills/plano/SKILL.md +++ b/skills/plano/SKILL.md @@ -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 -# 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 +# 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado) +/plano.executar # Executa o último plano da conversa ou mais recente +/plano.executar # 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 ``` +> 💡 **Nota de Compatibilidade:** Caso o operador invoque a sintaxe `/plano executar `, o agente automaticamente acionará o procedimento canônico de [`/plano.executar`](../plano.executar/SKILL.md). + --- ## 🛠️ Procedimento Operacional: Criação de Plano (`/plano `) @@ -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-.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 `. +- 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 `) +## 🛠️ 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 ` - - `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: ""`. - - 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-.md` para `./PLANOS/executado/YYYY-MM-DD-.md` (usando `write_to_file` no destino e removendo da pasta pendente). -- Registre a ação em `memorias-ia/sessao-YYYY-MM-DD-.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 ` (plano específico) +- `/plano.executar todos` (processamento serial com circuit breaker) --- -## 🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar `) +## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar `) +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.