diff --git a/DOCUMENTACAO/templates/plano.md.template b/DOCUMENTACAO/templates/plano.md.template index 02dc11d..151aa32 100644 --- a/DOCUMENTACAO/templates/plano.md.template +++ b/DOCUMENTACAO/templates/plano.md.template @@ -2,23 +2,23 @@ type: template name: plano description: Template canônico para Planos Técnicos de Implementação (fila PLANOS/pendente/ e PLANOS/executado/) -updatedAt: "2026-09-28" +updatedAt: "2026-09-30" --- --- -id: YYYY-MM-DD- +id: AAAA-MM-DD-HH-mm- titulo: "" origem: "Revisão Tester / QA" -data-criacao: "YYYY-MM-DD" +data-criacao: "AAAA-MM-DD HH:mm" data-execucao: null status: "pendente" # pendente | executado | cancelado prioridade: "media" # critica | alta | media | baixa diff --git a/TOOLS b/TOOLS index fd21b8e..2cb09be 100644 --- a/TOOLS +++ b/TOOLS @@ -102,7 +102,16 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot --- -## 7. Instalação Rápida (Copia e Cola) +## 7. Utilitários Nativos do Framework .agent + +### notificar.sh (`.agent/notificar.sh`) +- **Descrição:** Utilitário unificado de notificação para o Sistema Operacional, compatível nativamente com **Linux** e **macOS**. +- **Por que ajuda as IAs e Operadores:** Permite que comandos de longa duração (como `/plano.executar todos` e loops `/goal`) avisem o operador imediatamente no momento da conclusão, emitindo popup no desktop (KDE `kdialog`, FreeDesktop `notify-send` / `gdbus`, macOS Notification Center via `osascript`), som de alerta discreto (PipeWire, PulseAudio ou macOS `afplay`) e campainha no terminal (`\a`). Totalmente assíncrono, não-bloqueante e seguro para ambientes headless. +- **Uso:** `sh .agent/notificar.sh "" "" [sucesso|aviso|erro]` + +--- + +## 8. Instalação Rápida (Copia e Cola) Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados). diff --git a/global/skills/plano-executar/SKILL.md b/global/skills/plano-executar/SKILL.md index f0f048e..51aaa70 100644 --- a/global/skills/plano-executar/SKILL.md +++ b/global/skills/plano-executar/SKILL.md @@ -2,7 +2,7 @@ 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" +updatedAt: "2026-09-30" --- # Skill: /plano-executar (Alias para /plano.executar com /goal e Multiagentes) @@ -14,6 +14,7 @@ Atalho para a skill canônica [`/plano.executar`](../plano.executar/SKILL.md), e - **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. + - `/plano.executar todos` $\rightarrow$ Executa todos os planos pendentes na pasta em modo serial sequencialmente por ordem de chegada (FIFO). +- **Notificação Nativa no SO:** Ao concluir cada plano ou finalizar toda a fila, emite alerta sonoro e visual no Sistema Operacional (Linux & macOS) via `.agent/notificar.sh`, ideal para acompanhamento em sessões CLI em segundo plano. 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 index 2aeb320..02a94cc 100644 --- a/global/skills/plano.executar/SKILL.md +++ b/global/skills/plano.executar/SKILL.md @@ -2,7 +2,7 @@ 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" +updatedAt: "2026-09-30" --- # Skill: /plano.executar (Execução de Planos Técnicos com /goal e Multiagentes) @@ -23,10 +23,10 @@ O agente atua como **Orquestrador Líder**, operando sob a postura obstinada do # 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 2026-09-30-10-35-reabrir-licenca-nao-assinada /plano.executar reabrir-licenca-nao-assinada -# Modo 3: Executar todos os planos da pasta de forma serial (um a um) +# 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 ``` @@ -39,9 +39,9 @@ Ao acionar `/plano.executar`, o agente adota estritamente o compromisso do **/go 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. + - 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. --- @@ -91,21 +91,30 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ### 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`. + - 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-.md` ou legado `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). + - 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/YYYY-MM-DD-.md — ""` + - Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/.md — ""` ### Modo 2: Por Identificador (`/plano.executar `) -1. Procura em `./PLANOS/pendente/` por ID exato, nome do arquivo ou correspondência parcial de slug. +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-` quanto nomes legados `YYYY-MM-DD-`). 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. +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-.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-.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/.md — ""` +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 encontrou um bloqueio técnico." erro` --- @@ -138,13 +147,17 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof 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)"`. + - 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/YYYY-MM-DD-.md` e remover de `./PLANOS/pendente/`. + - Salvar em `./PLANOS/executado/.md` e remover de `./PLANOS/pendente/.md` (preservando o nome original do arquivo). 3. **Memória do Projeto (Pilar 6 - @documentacao):** - - Criar `memorias-ia/sessao-YYYY-MM-DD-.md`. + - Criar `memorias-ia/sessao-AAAA-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. +5. **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" "" 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. diff --git a/global/skills/plano/SKILL.md b/global/skills/plano/SKILL.md index 918ffd5..4cb3a09 100644 --- a/global/skills/plano/SKILL.md +++ b/global/skills/plano/SKILL.md @@ -2,7 +2,7 @@ name: plano description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs scope: global -updatedAt: "2026-09-28" +updatedAt: "2026-09-30" --- # Skill: /plano (Criação e Gestão de Planos Técnicos) @@ -23,7 +23,7 @@ Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** # 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 +/plano.executar todos # Executa todos os pendentes em lote serial (ordem de chegada - FIFO) # 4. Arquivamento manual de um plano já concluído /plano arquivar @@ -37,10 +37,11 @@ Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** Quando invocado com uma instrução (ex.: `/plano corrigir validação do número do processo no formulário de denúncia`): -### 1. Obter Data e Gerar Slug -- Obtenha a data local atual no formato `YYYY-MM-DD`. +### 1. Obter Data, Hora e Gerar Slug +- Obtenha a data e hora locais atuais da máquina no formato `AAAA-MM-DD-HH-mm` (ano com 4 dígitos, mês, dia, hora 24h e minuto com 2 dígitos, ex.: `2026-09-30-10-35`). - Converta o tema principal da instrução em um slug sucinto em kebab-case (letras minúsculas e hífens, sem acentos ou caracteres especiais). -- Caminho alvo: `./PLANOS/pendente/YYYY-MM-DD-.md`. +- Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md`. +- **Propósito da Nomenclatura:** A inclusão de hora (`HH`) e minuto (`mm`) no prefixo temporal viabiliza a ordenação lexicográfica determinística da fila (FIFO — First In, First Out), permitindo que `/plano.executar todos` processe os planos estritamente na ordem em que foram criados. ### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) - **NÃO altere arquivos de código de produção nesta etapa.** @@ -55,10 +56,10 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - **Frontmatter YAML:** ```yaml --- - id: YYYY-MM-DD- + id: AAAA-MM-DD-HH-mm- titulo: "" origem: "Revisão Tester / QA" - data-criacao: "YYYY-MM-DD" + data-criacao: "AAAA-MM-DD HH:mm" data-execucao: null status: "pendente" prioridade: "media" # ou critica/alta/baixa @@ -75,7 +76,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - **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 pelo executor. -- Salve o arquivo em `./PLANOS/pendente/YYYY-MM-DD-.md` usando `write_to_file`. +- Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md` usando `write_to_file`. ### 4. Resposta ao Usuário - Informe o link do arquivo criado em `./PLANOS/pendente/`. @@ -89,7 +90,7 @@ 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):** ID, Título, Prioridade, Data de Criação. + - **Planos Pendentes (Aguardando Dev — Fila FIFO):** ID, Título, Prioridade, Data de Criação. Listados em ordem cronológica de chegada (mais antigo primeiro). - **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`. @@ -102,14 +103,14 @@ Para implementar qualquer plano da fila, a operação canônica é delegada para 👉 **[`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) +- `/plano.executar todos` (processamento serial em ordem de chegada FIFO com circuit breaker) --- -## 🛠️ Procedimento Operacional: Arquivamento Manual (`/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"`, registrando `data-execucao` e executor. -3. Mova o arquivo para `./PLANOS/executado/`. +1. Localize o arquivo em `./PLANOS/pendente/` (aceita slug puro, ID completo ou nome de arquivo). +2. Atualize o frontmatter para `status: "executado"`, registrando `data-execucao: "AAAA-MM-DD HH:mm"` e executor. +3. Mova o arquivo para `./PLANOS/executado/` preservando o nome original do arquivo. 4. Notifique o usuário da conclusão do arquivamento. diff --git a/global/workflows/plano.md b/global/workflows/plano.md index 23aad74..95f7b56 100644 --- a/global/workflows/plano.md +++ b/global/workflows/plano.md @@ -3,7 +3,7 @@ type: workflow name: plano 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" +updatedAt: "2026-09-30" --- # Workflow: /plano e /plano.executar (Gestão e Execução de Planos Técnicos) @@ -11,11 +11,11 @@ updatedAt: "2026-09-28" 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 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 ` $\rightarrow$ Diagnostica a demanda sem mexer em código e gera um plano técnico em `PLANOS/pendente/AAAA-MM-DD-HH-mm-.md`. +> - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes (FIFO) e executados. > - `/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.executar todos` $\rightarrow$ Executa sequencialmente todos os planos pendentes em ordem de chegada (FIFO - com circuit breaker). > - `/plano arquivar ` $\rightarrow$ Move manualmente um plano para `PLANOS/executado/`. --- @@ -35,7 +35,7 @@ Durante a navegação, testes manuais ou homologação de telas e rotas, o teste ┌─────────────────────────────────┐ ┌─────────────────────────────┐ │ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │ │ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │ -│ /plano │ │ │ +│ /plano │ │ Ordem de Chegada (FIFO) │ └─────────────────────────────────┘ └──────────────┬──────────────┘ │ ▼ @@ -58,13 +58,14 @@ Quando o comando for executado: - Identifica a causa raiz ou o ponto exato de intervenção. 2. **Formatação do Nome do Arquivo:** - - Formato: `PLANOS/pendente/YYYY-MM-DD-.md` - - Onde `YYYY-MM-DD` é a data atual da máquina e `` reflete a essência do plano. + - Formato: `PLANOS/pendente/AAAA-MM-DD-HH-mm-.md` + - Onde `AAAA-MM-DD-HH-mm` é a data e hora locais atuais da máquina (com dois dígitos para dia, mês, hora 24h e minuto). + - **Propósito:** A inclusão de hora e minuto viabiliza que a ordenação alfabética/lexicográfica coincida nativamente com a ordem de chegada (FIFO), orientando a fila de execução serial do desenvolvedor. 3. **Escrita do Documento:** - Utiliza a estrutura do template canônico `.agent/DOCUMENTACAO/templates/plano.md.template`. - Preenche: - - Frontmatter com `status: pendente` e tags do domínio. + - Frontmatter com `id: AAAA-MM-DD-HH-mm-`, `data-criacao: "AAAA-MM-DD HH:mm"`, `status: pendente` e tags do domínio. - Objetivo & Contexto (visão funcional). - Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados). - Critérios de Aceite (Definition of Done). @@ -79,7 +80,7 @@ Quando o comando for executado: ## 📋 Fase 2: Gestão da Fila (`/plano listar`) Para visualizar o status atual de todos os planos: -- Lista arquivos em `PLANOS/pendente/` (status, título, prioridade, data). +- Lista arquivos em `PLANOS/pendente/` ordenados por ordem de chegada FIFO (status, título, prioridade, data). - Lista arquivos em `PLANOS/executado/` (data de execução, executor). --- @@ -103,8 +104,8 @@ O Orquestrador divide as tarefas entre os especialistas: ### 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. +- **Modo 2: Por identificador (`/plano.executar `)** $\rightarrow$ Localiza por slug, ID ou nome de arquivo (suportando formatos novo e legado). +- **Modo 3: Fila serial em ordem de chegada (`/plano.executar todos`)** $\rightarrow$ Ordena os pendentes em estrita ordem cronológica de chegada (FIFO: o mais antigo criado é executado primeiro; arquivos com prefixo temporal `AAAA-MM-DD-HH-mm-` ordenam-se alfabeticamente; legados usam data de criação/mtime) e processa sequencialmente um a um com circuit breaker caso ocorra erro irrecuperável. --- @@ -115,17 +116,22 @@ Ao confirmar que a implementação está verde e validada: 1. **Atualização do Plano:** - Atualiza o frontmatter do arquivo: - `status: executado` - - `data-execucao: "YYYY-MM-DD HH:mm"` + - `data-execucao: "AAAA-MM-DD HH:mm"` - `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:** - - Move o arquivo de: - `PLANOS/pendente/YYYY-MM-DD-.md` + - Move o arquivo preservando o nome original: + `PLANOS/pendente/.md` para: - `PLANOS/executado/YYYY-MM-DD-.md` + `PLANOS/executado/.md` 3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** - - Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-.md`. + - Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-.md`. - Indexa no `memorias-ia/historico-acoes.md`. - Executa `git add` nos arquivos alterados e sugere o comando de commit semântico ao operador (seguindo `rules/proibido-commit-ia.md`). + +4. **Notificação no Sistema Operacional (Linux & macOS):** + - Dispara alerta sonoro e notificação visual de desktop via `.agent/notificar.sh`: + `sh .agent/notificar.sh "Plano Concluído" "" sucesso` + - Na conclusão de toda a fila serial de `/plano.executar todos`, emite a notificação consolidada de encerramento do lote para avisar o operador no CLI. diff --git a/notificar.sh b/notificar.sh new file mode 100755 index 0000000..11c671f --- /dev/null +++ b/notificar.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +# ============================================================================== +# Script de Notificação do Sistema Operacional (Compatível com Linux & macOS) +# Uso: sh .agent/notificar.sh "" "" [sucesso|aviso|erro] +# ============================================================================== + +TITULO="${1:-Antigravity /goal}" +MENSAGEM="${2:-Trabalho concluído com sucesso!}" +TIPO="${3:-sucesso}" + +# 1. Sinal sonoro universal do terminal (CLI) +printf '\a' 2>/dev/null || true + +OS_NAME="$(uname -s 2>/dev/null || echo "Desconhecido")" + +# 2. Execução assíncrona por Sistema Operacional (não bloqueia o terminal) +( + case "$OS_NAME" in + Darwin*) + # --- macOS --- + # Som nativo do macOS + case "$TIPO" in + erro) SOM_MAC="/System/Library/Sounds/Basso.aiff" ;; + aviso) SOM_MAC="/System/Library/Sounds/Sosumi.aiff" ;; + *) SOM_MAC="/System/Library/Sounds/Glass.aiff" ;; + esac + [ -f "$SOM_MAC" ] && afplay "$SOM_MAC" >/dev/null 2>&1 & + + # Notificação Desktop via AppleScript + if command -v osascript >/dev/null 2>&1; then + osascript -e "display notification \"$MENSAGEM\" with title \"$TITULO\" subtitle \"Antigravity\"" >/dev/null 2>&1 + elif command -v terminal-notifier >/dev/null 2>&1; then + terminal-notifier -title "$TITULO" -message "$MENSAGEM" >/dev/null 2>&1 + fi + ;; + + Linux*) + # --- Linux --- + # Som nativo via PipeWire, PulseAudio ou Canberra + case "$TIPO" in + erro) + SOM_LINUX="/usr/share/sounds/freedesktop/stereo/dialog-error.oga" + [ ! -f "$SOM_LINUX" ] && SOM_LINUX="/usr/share/sounds/Oxygen-Sys-App-Error.ogg" + ;; + aviso) + SOM_LINUX="/usr/share/sounds/freedesktop/stereo/dialog-warning.oga" + [ ! -f "$SOM_LINUX" ] && SOM_LINUX="/usr/share/sounds/Oxygen-Sys-Warning.ogg" + ;; + *) + SOM_LINUX="/usr/share/sounds/Oxygen-Sys-App-Positive.ogg" + [ ! -f "$SOM_LINUX" ] && SOM_LINUX="/usr/share/sounds/freedesktop/stereo/complete.oga" + [ ! -f "$SOM_LINUX" ] && SOM_LINUX="/usr/share/sounds/ocean/stereo/dialog-information.oga" + ;; + esac + + if [ -f "$SOM_LINUX" ]; then + if command -v pw-play >/dev/null 2>&1; then + pw-play "$SOM_LINUX" >/dev/null 2>&1 & + elif command -v paplay >/dev/null 2>&1; then + paplay "$SOM_LINUX" >/dev/null 2>&1 & + elif command -v aplay >/dev/null 2>&1; then + aplay "$SOM_LINUX" >/dev/null 2>&1 & + fi + elif command -v canberra-gtk-play >/dev/null 2>&1; then + canberra-gtk-play -i complete >/dev/null 2>&1 & + fi + + # Notificação Desktop (KDE / GNOME / XFCE / DBus) + if [ -n "$DISPLAY$WAYLAND_DISPLAY" ]; then + if command -v kdialog >/dev/null 2>&1; then + kdialog --title "$TITULO" --passivepopup "$MENSAGEM" 5 >/dev/null 2>&1 + elif command -v notify-send >/dev/null 2>&1; then + notify-send -u normal -a "Antigravity" "$TITULO" "$MENSAGEM" >/dev/null 2>&1 + elif command -v gdbus >/dev/null 2>&1; then + gdbus call --session --dest org.freedesktop.Notifications \ + --object-path /org/freedesktop/Notifications \ + --method org.freedesktop.Notifications.Notify \ + "Antigravity" 0 "" "$TITULO" "$MENSAGEM" "[]" "{}" 5000 >/dev/null 2>&1 + elif command -v zenity >/dev/null 2>&1; then + zenity --notification --text="$TITULO: $MENSAGEM" >/dev/null 2>&1 + fi + fi + ;; + esac +) >/dev/null 2>&1 & + +exit 0 diff --git a/skills/plano-executar/SKILL.md b/skills/plano-executar/SKILL.md index f0f048e..51aaa70 100644 --- a/skills/plano-executar/SKILL.md +++ b/skills/plano-executar/SKILL.md @@ -2,7 +2,7 @@ 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" +updatedAt: "2026-09-30" --- # Skill: /plano-executar (Alias para /plano.executar com /goal e Multiagentes) @@ -14,6 +14,7 @@ Atalho para a skill canônica [`/plano.executar`](../plano.executar/SKILL.md), e - **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. + - `/plano.executar todos` $\rightarrow$ Executa todos os planos pendentes na pasta em modo serial sequencialmente por ordem de chegada (FIFO). +- **Notificação Nativa no SO:** Ao concluir cada plano ou finalizar toda a fila, emite alerta sonoro e visual no Sistema Operacional (Linux & macOS) via `.agent/notificar.sh`, ideal para acompanhamento em sessões CLI em segundo plano. 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 index 2aeb320..02a94cc 100644 --- a/skills/plano.executar/SKILL.md +++ b/skills/plano.executar/SKILL.md @@ -2,7 +2,7 @@ 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" +updatedAt: "2026-09-30" --- # Skill: /plano.executar (Execução de Planos Técnicos com /goal e Multiagentes) @@ -23,10 +23,10 @@ O agente atua como **Orquestrador Líder**, operando sob a postura obstinada do # 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 2026-09-30-10-35-reabrir-licenca-nao-assinada /plano.executar reabrir-licenca-nao-assinada -# Modo 3: Executar todos os planos da pasta de forma serial (um a um) +# 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 ``` @@ -39,9 +39,9 @@ Ao acionar `/plano.executar`, o agente adota estritamente o compromisso do **/go 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. + - 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. --- @@ -91,21 +91,30 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ### 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`. + - 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-.md` ou legado `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). + - 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/YYYY-MM-DD-.md — ""` + - Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/.md — ""` ### Modo 2: Por Identificador (`/plano.executar `) -1. Procura em `./PLANOS/pendente/` por ID exato, nome do arquivo ou correspondência parcial de slug. +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-` quanto nomes legados `YYYY-MM-DD-`). 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. +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-.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-.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/.md — ""` +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 encontrou um bloqueio técnico." erro` --- @@ -138,13 +147,17 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof 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)"`. + - 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/YYYY-MM-DD-.md` e remover de `./PLANOS/pendente/`. + - Salvar em `./PLANOS/executado/.md` e remover de `./PLANOS/pendente/.md` (preservando o nome original do arquivo). 3. **Memória do Projeto (Pilar 6 - @documentacao):** - - Criar `memorias-ia/sessao-YYYY-MM-DD-.md`. + - Criar `memorias-ia/sessao-AAAA-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. +5. **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" "" 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. diff --git a/skills/plano/SKILL.md b/skills/plano/SKILL.md index 918ffd5..4cb3a09 100644 --- a/skills/plano/SKILL.md +++ b/skills/plano/SKILL.md @@ -2,7 +2,7 @@ name: plano description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs scope: global -updatedAt: "2026-09-28" +updatedAt: "2026-09-30" --- # Skill: /plano (Criação e Gestão de Planos Técnicos) @@ -23,7 +23,7 @@ Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** # 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 +/plano.executar todos # Executa todos os pendentes em lote serial (ordem de chegada - FIFO) # 4. Arquivamento manual de um plano já concluído /plano arquivar @@ -37,10 +37,11 @@ Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** Quando invocado com uma instrução (ex.: `/plano corrigir validação do número do processo no formulário de denúncia`): -### 1. Obter Data e Gerar Slug -- Obtenha a data local atual no formato `YYYY-MM-DD`. +### 1. Obter Data, Hora e Gerar Slug +- Obtenha a data e hora locais atuais da máquina no formato `AAAA-MM-DD-HH-mm` (ano com 4 dígitos, mês, dia, hora 24h e minuto com 2 dígitos, ex.: `2026-09-30-10-35`). - Converta o tema principal da instrução em um slug sucinto em kebab-case (letras minúsculas e hífens, sem acentos ou caracteres especiais). -- Caminho alvo: `./PLANOS/pendente/YYYY-MM-DD-.md`. +- Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md`. +- **Propósito da Nomenclatura:** A inclusão de hora (`HH`) e minuto (`mm`) no prefixo temporal viabiliza a ordenação lexicográfica determinística da fila (FIFO — First In, First Out), permitindo que `/plano.executar todos` processe os planos estritamente na ordem em que foram criados. ### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) - **NÃO altere arquivos de código de produção nesta etapa.** @@ -55,10 +56,10 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - **Frontmatter YAML:** ```yaml --- - id: YYYY-MM-DD- + id: AAAA-MM-DD-HH-mm- titulo: "" origem: "Revisão Tester / QA" - data-criacao: "YYYY-MM-DD" + data-criacao: "AAAA-MM-DD HH:mm" data-execucao: null status: "pendente" prioridade: "media" # ou critica/alta/baixa @@ -75,7 +76,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - **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 pelo executor. -- Salve o arquivo em `./PLANOS/pendente/YYYY-MM-DD-.md` usando `write_to_file`. +- Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md` usando `write_to_file`. ### 4. Resposta ao Usuário - Informe o link do arquivo criado em `./PLANOS/pendente/`. @@ -89,7 +90,7 @@ 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):** ID, Título, Prioridade, Data de Criação. + - **Planos Pendentes (Aguardando Dev — Fila FIFO):** ID, Título, Prioridade, Data de Criação. Listados em ordem cronológica de chegada (mais antigo primeiro). - **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`. @@ -102,14 +103,14 @@ Para implementar qualquer plano da fila, a operação canônica é delegada para 👉 **[`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) +- `/plano.executar todos` (processamento serial em ordem de chegada FIFO com circuit breaker) --- -## 🛠️ Procedimento Operacional: Arquivamento Manual (`/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"`, registrando `data-execucao` e executor. -3. Mova o arquivo para `./PLANOS/executado/`. +1. Localize o arquivo em `./PLANOS/pendente/` (aceita slug puro, ID completo ou nome de arquivo). +2. Atualize o frontmatter para `status: "executado"`, registrando `data-execucao: "AAAA-MM-DD HH:mm"` e executor. +3. Mova o arquivo para `./PLANOS/executado/` preservando o nome original do arquivo. 4. Notifique o usuário da conclusão do arquivamento.