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-30 10:50:44 -03:00
parent e7adba8fd8
commit 1f79b0c403
10 changed files with 221 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

12
DOCUMENTACAO/templates/plano.md.template
View file

@ -2,23 +2,23 @@
type: template type: template
name: plano name: plano
description: Template canônico para Planos Técnicos de Implementação (fila PLANOS/pendente/ e PLANOS/executado/) 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"
--- ---
<!-- <!--
DESTINO CANÔNICO NO PROJETO: DESTINO CANÔNICO NO PROJETO:
- Criação pelo Tester: <base_projeto>/PLANOS/pendente/YYYY-MM-DD-<slug>.md - Criação pelo Tester: <base_projeto>/PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md
- Arquivamento pelo Dev: <base_projeto>/PLANOS/executado/YYYY-MM-DD-<slug>.md - Arquivamento pelo Dev: <base_projeto>/PLANOS/executado/AAAA-MM-DD-HH-mm-<slug>.md
EXEMPLO: EXEMPLO:
PLANOS/pendente/2026-09-28-ajuste-filtro-denuncia-anonima.md PLANOS/pendente/2026-09-30-10-35-ajuste-filtro-denuncia-anonima.md
--> -->
--- ---
id: YYYY-MM-DD-<slug-do-plano> id: AAAA-MM-DD-HH-mm-<slug-do-plano>
titulo: "<Título claro e descritivo da demanda>" titulo: "<Título claro e descritivo da demanda>"
origem: "Revisão Tester / QA" origem: "Revisão Tester / QA"
data-criacao: "YYYY-MM-DD" data-criacao: "AAAA-MM-DD HH:mm"
data-execucao: null data-execucao: null
status: "pendente" # pendente | executado | cancelado status: "pendente" # pendente | executado | cancelado
prioridade: "media" # critica | alta | media | baixa prioridade: "media" # critica | alta | media | baixa

11
TOOLS
View file

@ -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 "<Título>" "<Mensagem>" [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). 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).

5
global/skills/plano-executar/SKILL.md
View file

@ -2,7 +2,7 @@
name: plano-executar 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) 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 scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Skill: /plano-executar (Alias para /plano.executar com /goal e Multiagentes) # 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:** - **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` 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 <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. - `/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). Para a especificação completa, matriz de papéis e detalhes operacionais, consulte [`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md).

47
global/skills/plano.executar/SKILL.md
View file

@ -2,7 +2,7 @@
name: plano.executar 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) 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 scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Skill: /plano.executar (Execução de Planos Técnicos com /goal e Multiagentes) # 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) # Modo 2: Executar plano específico por identificador (slug, ID ou nome de arquivo)
/plano.executar <identificador> /plano.executar <identificador>
# Exemplos: # 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 /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
/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. 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: 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. - 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. - 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. - 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. 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`) ### Modo 1: Sem parâmetros (`/plano.executar` ou `/plano.executar ultimo`)
1. **Contexto da Conversa:** 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`. - O agente busca no histórico imediato da sessão se algum plano foi criado recentemente em `./PLANOS/pendente/` (padrão `AAAA-MM-DD-HH-mm-<slug>.md` ou legado `YYYY-MM-DD-<slug>.md`).
2. **Fallback para o Mais Recente na Pasta:** 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:** 3. **Confirmação:**
- Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/YYYY-MM-DD-<slug>.md — "<Título>"` - Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"`
### Modo 2: Por Identificador (`/plano.executar <identificador>`) ### Modo 2: Por Identificador (`/plano.executar <identificador>`)
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-<slug>` quanto nomes legados `YYYY-MM-DD-<slug>`).
2. Em caso de ambiguidade, lista as opções para confirmação; se não encontrado, orienta verificar com `/plano listar`. 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`) ### 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`). 1. **Listar Fila:** Lista todos os planos `.md` em `./PLANOS/pendente/` (desconsiderando `.gitkeep`).
2. Ordena por criticidade/data. 2. **Ordenar em Estrita Ordem de Chegada (FIFO — First In, First Out):**
3. Executa sequencialmente um por um, aplicando o ciclo completo `/goal` para cada plano antes de passar ao seguinte. - Ordena os arquivos em ordem cronológica de chegada (o plano mais antigo criado é executado primeiro).
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. - Com a nomenclatura `AAAA-MM-DD-HH-mm-<slug>.md`, a ordenação alfabética/lexicográfica ascendente padrão (`sort` ou `Array.prototype.sort()`) corresponde naturalmente à ordem temporal de criação.
- **Compatibilidade com Planos Legados:** Caso existam arquivos legados sem hora no nome (`YYYY-MM-DD-<slug>.md`), o agente utiliza o horário de modificação/criação do arquivo (`mtime`) ou o campo `data-criacao` do frontmatter para intercalá-los na ordem temporal exata.
3. **Execução Sequencial:**
- Executa um por um na ordem da fila, aplicando o ciclo completo `/goal` para cada plano antes de passar ao seguinte.
- Exibe o progresso: `🎯 [Orquestrador /goal] [Fila X/N] Executando PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"`
4. **Conclusão da Fila ou Circuit Breaker:**
- Ao finalizar com sucesso toda a fila de pendentes:
`sh .agent/notificar.sh "Fila de Planos Concluída" "Todos os planos foram executados com sucesso!" sucesso`
- Se um plano encontrar um bloqueio técnico insuperável mesmo após auto-correções, o lote é interrompido com relatório claro para não corromper o repositório nem propagar falhas, e o operador é alertado:
`sh .agent/notificar.sh "Execução Interrompida" "O plano <nome> encontrou um bloqueio técnico." erro`
--- ---
@ -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: Ao atingir 100% de conformidade com todos os critérios do plano:
1. **Atualizar Metadados e Histórico 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. - Seção 6 (*Histórico de Execução*): arquivos modificados, resumo da solução e evidências de validação.
2. **Mover o Plano:** 2. **Mover o Plano:**
- Salvar em `./PLANOS/executado/YYYY-MM-DD-<slug>.md` e remover de `./PLANOS/pendente/`. - Salvar em `./PLANOS/executado/<nome-original>.md` e remover de `./PLANOS/pendente/<nome-original>.md` (preservando o nome original do arquivo).
3. **Memória do Projeto (Pilar 6 - @documentacao):** 3. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-YYYY-MM-DD-<slug>.md`. - Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`. - Indexar no `memorias-ia/historico-acoes.md`.
4. **Staging de Segurança:** 4. **Staging de Segurança:**
- Executar `git add <arquivos>` e `git status`. - 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. - 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" "<Nome ou Título do Plano>" sucesso`
- O utilitário detecta automaticamente se o host é Linux (KDE `kdialog`, `notify-send`, `gdbus`, PipeWire/PulseAudio) ou macOS (`osascript` banner nativo + `afplay` áudio Glass + terminal bell `\a`), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI.

29
global/skills/plano/SKILL.md
View file

@ -2,7 +2,7 @@
name: plano name: plano
description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs
scope: global scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Skill: /plano (Criação e Gestão de Planos Técnicos) # 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) # 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado)
/plano.executar # Executa o último plano da conversa ou mais recente /plano.executar # Executa o último plano da conversa ou mais recente
/plano.executar <slug> # Executa plano específico por slug/ID /plano.executar <slug> # 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 # 4. Arquivamento manual de um plano já concluído
/plano arquivar <slug-ou-nome-do-arquivo> /plano arquivar <slug-ou-nome-do-arquivo>
@ -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`): 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 ### 1. Obter Data, Hora e Gerar Slug
- Obtenha a data local atual no formato `YYYY-MM-DD`. - 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). - 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-<slug>.md`. - Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.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) ### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código)
- **NÃO altere arquivos de código de produção nesta etapa.** - **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:** - **Frontmatter YAML:**
```yaml ```yaml
--- ---
id: YYYY-MM-DD-<slug> id: AAAA-MM-DD-HH-mm-<slug>
titulo: "<Título claro e direto>" titulo: "<Título claro e direto>"
origem: "Revisão Tester / QA" origem: "Revisão Tester / QA"
data-criacao: "YYYY-MM-DD" data-criacao: "AAAA-MM-DD HH:mm"
data-execucao: null data-execucao: null
status: "pendente" status: "pendente"
prioridade: "media" # ou critica/alta/baixa 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). - **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`. - **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. - **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`. - Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md` usando `write_to_file`.
### 4. Resposta ao Usuário ### 4. Resposta ao Usuário
- Informe o link do arquivo criado em `./PLANOS/pendente/`. - 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/`. 1. Liste os arquivos existentes em `./PLANOS/pendente/` e `./PLANOS/executado/`.
2. Para cada arquivo, extraia título, data e prioridade do frontmatter. 2. Para cada arquivo, extraia título, data e prioridade do frontmatter.
3. Exiba uma tabela Markdown organizada: 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. - **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`. 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)**: 👉 **[`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md)**:
- `/plano.executar` (sem argumentos: último plano criado na conversa ou pendente mais recente) - `/plano.executar` (sem argumentos: último plano criado na conversa ou pendente mais recente)
- `/plano.executar <slug>` (plano específico) - `/plano.executar <slug>` (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 <slug>`) ## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar <slug-ou-id>`)
Quando um plano foi implementado externamente ou não requer alteração de código: Quando um plano foi implementado externamente ou não requer alteração de código:
1. Localize o arquivo em `./PLANOS/pendente/`. 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` e executor. 2. Atualize o frontmatter para `status: "executado"`, registrando `data-execucao: "AAAA-MM-DD HH:mm"` e executor.
3. Mova o arquivo para `./PLANOS/executado/`. 3. Mova o arquivo para `./PLANOS/executado/` preservando o nome original do arquivo.
4. Notifique o usuário da conclusão do arquivamento. 4. Notifique o usuário da conclusão do arquivamento.

38
global/workflows/plano.md
View file

@ -3,7 +3,7 @@ type: workflow
name: plano 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 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 scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Workflow: /plano e /plano.executar (Gestão e Execução de Planos Técnicos) # 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. 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:** > 💡 **Comandos Rápidos:**
> - `/plano <instrução>` $\rightarrow$ Diagnostica a demanda sem mexer em código e gera um plano técnico em `PLANOS/pendente/YYYY-MM-DD-<slug>.md`. > - `/plano <instrução>` $\rightarrow$ Diagnostica a demanda sem mexer em código e gera um plano técnico em `PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md`.
> - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes e executados. > - `/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 o último plano da conversa (ou pendente mais recente) sob a postura autônoma `/goal`.
> - `/plano.executar <slug>` $\rightarrow$ Executa plano específico coordenando a equipe de especialistas (`@back`, `@front`, `@ux`, `@refatorar`, `@testes`, `@documentacao`). > - `/plano.executar <slug>` $\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 <slug>` $\rightarrow$ Move manualmente um plano para `PLANOS/executado/`. > - `/plano arquivar <slug>` $\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 │ │ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │
│ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │ │ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │
│ /plano <instrução> │ │ │ │ /plano <instrução> │ │ Ordem de Chegada (FIFO) │
└─────────────────────────────────┘ └──────────────┬──────────────┘ └─────────────────────────────────┘ └──────────────┬──────────────┘
│ │
▼ ▼
@ -58,13 +58,14 @@ Quando o comando for executado:
- Identifica a causa raiz ou o ponto exato de intervenção. - Identifica a causa raiz ou o ponto exato de intervenção.
2. **Formatação do Nome do Arquivo:** 2. **Formatação do Nome do Arquivo:**
- Formato: `PLANOS/pendente/YYYY-MM-DD-<slug-em-kebab-case>.md` - Formato: `PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug-em-kebab-case>.md`
- Onde `YYYY-MM-DD` é a data atual da máquina e `<slug>` reflete a essência do plano. - 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:** 3. **Escrita do Documento:**
- Utiliza a estrutura do template canônico `.agent/DOCUMENTACAO/templates/plano.md.template`. - Utiliza a estrutura do template canônico `.agent/DOCUMENTACAO/templates/plano.md.template`.
- Preenche: - Preenche:
- Frontmatter com `status: pendente` e tags do domínio. - Frontmatter com `id: AAAA-MM-DD-HH-mm-<slug>`, `data-criacao: "AAAA-MM-DD HH:mm"`, `status: pendente` e tags do domínio.
- Objetivo & Contexto (visão funcional). - Objetivo & Contexto (visão funcional).
- Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados). - Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados).
- Critérios de Aceite (Definition of Done). - Critérios de Aceite (Definition of Done).
@ -79,7 +80,7 @@ Quando o comando for executado:
## 📋 Fase 2: Gestão da Fila (`/plano listar`) ## 📋 Fase 2: Gestão da Fila (`/plano listar`)
Para visualizar o status atual de todos os planos: 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). - 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 ### 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 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 <slug-ou-id>`)** $\rightarrow$ Localiza por slug, ID ou nome de arquivo. - **Modo 2: Por identificador (`/plano.executar <slug-ou-id>`)** $\rightarrow$ Localiza por slug, ID ou nome de arquivo (suportando formatos novo e legado).
- **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 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:** 1. **Atualização do Plano:**
- Atualiza o frontmatter do arquivo: - Atualiza o frontmatter do arquivo:
- `status: executado` - `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)"` - `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. - 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:** 2. **Movimentação do Arquivo:**
- Move o arquivo de: - Move o arquivo preservando o nome original:
`PLANOS/pendente/YYYY-MM-DD-<slug>.md` `PLANOS/pendente/<nome-original>.md`
para: para:
`PLANOS/executado/YYYY-MM-DD-<slug>.md` `PLANOS/executado/<nome-original>.md`
3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** 3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):**
- Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-<slug>.md`. - Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexa no `memorias-ia/historico-acoes.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`). - 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" "<Nome ou Título do Plano>" 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.

87
notificar.sh Executable file
View file

@ -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 "<Título>" "<Mensagem>" [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

5
skills/plano-executar/SKILL.md
View file

@ -2,7 +2,7 @@
name: plano-executar 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) 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 scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Skill: /plano-executar (Alias para /plano.executar com /goal e Multiagentes) # 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:** - **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` 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 <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. - `/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). Para a especificação completa, matriz de papéis e detalhes operacionais, consulte [`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md).

47
skills/plano.executar/SKILL.md
View file

@ -2,7 +2,7 @@
name: plano.executar 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) 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 scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Skill: /plano.executar (Execução de Planos Técnicos com /goal e Multiagentes) # 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) # Modo 2: Executar plano específico por identificador (slug, ID ou nome de arquivo)
/plano.executar <identificador> /plano.executar <identificador>
# Exemplos: # 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 /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
/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. 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: 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. - 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. - 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. - 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. 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`) ### Modo 1: Sem parâmetros (`/plano.executar` ou `/plano.executar ultimo`)
1. **Contexto da Conversa:** 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`. - O agente busca no histórico imediato da sessão se algum plano foi criado recentemente em `./PLANOS/pendente/` (padrão `AAAA-MM-DD-HH-mm-<slug>.md` ou legado `YYYY-MM-DD-<slug>.md`).
2. **Fallback para o Mais Recente na Pasta:** 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:** 3. **Confirmação:**
- Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/YYYY-MM-DD-<slug>.md — "<Título>"` - Exibe: `🎯 [Orquestrador /goal] Plano selecionado: PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"`
### Modo 2: Por Identificador (`/plano.executar <identificador>`) ### Modo 2: Por Identificador (`/plano.executar <identificador>`)
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-<slug>` quanto nomes legados `YYYY-MM-DD-<slug>`).
2. Em caso de ambiguidade, lista as opções para confirmação; se não encontrado, orienta verificar com `/plano listar`. 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`) ### 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`). 1. **Listar Fila:** Lista todos os planos `.md` em `./PLANOS/pendente/` (desconsiderando `.gitkeep`).
2. Ordena por criticidade/data. 2. **Ordenar em Estrita Ordem de Chegada (FIFO — First In, First Out):**
3. Executa sequencialmente um por um, aplicando o ciclo completo `/goal` para cada plano antes de passar ao seguinte. - Ordena os arquivos em ordem cronológica de chegada (o plano mais antigo criado é executado primeiro).
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. - Com a nomenclatura `AAAA-MM-DD-HH-mm-<slug>.md`, a ordenação alfabética/lexicográfica ascendente padrão (`sort` ou `Array.prototype.sort()`) corresponde naturalmente à ordem temporal de criação.
- **Compatibilidade com Planos Legados:** Caso existam arquivos legados sem hora no nome (`YYYY-MM-DD-<slug>.md`), o agente utiliza o horário de modificação/criação do arquivo (`mtime`) ou o campo `data-criacao` do frontmatter para intercalá-los na ordem temporal exata.
3. **Execução Sequencial:**
- Executa um por um na ordem da fila, aplicando o ciclo completo `/goal` para cada plano antes de passar ao seguinte.
- Exibe o progresso: `🎯 [Orquestrador /goal] [Fila X/N] Executando PLANOS/pendente/<nome-do-arquivo>.md — "<Título>"`
4. **Conclusão da Fila ou Circuit Breaker:**
- Ao finalizar com sucesso toda a fila de pendentes:
`sh .agent/notificar.sh "Fila de Planos Concluída" "Todos os planos foram executados com sucesso!" sucesso`
- Se um plano encontrar um bloqueio técnico insuperável mesmo após auto-correções, o lote é interrompido com relatório claro para não corromper o repositório nem propagar falhas, e o operador é alertado:
`sh .agent/notificar.sh "Execução Interrompida" "O plano <nome> encontrou um bloqueio técnico." erro`
--- ---
@ -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: Ao atingir 100% de conformidade com todos os critérios do plano:
1. **Atualizar Metadados e Histórico 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. - Seção 6 (*Histórico de Execução*): arquivos modificados, resumo da solução e evidências de validação.
2. **Mover o Plano:** 2. **Mover o Plano:**
- Salvar em `./PLANOS/executado/YYYY-MM-DD-<slug>.md` e remover de `./PLANOS/pendente/`. - Salvar em `./PLANOS/executado/<nome-original>.md` e remover de `./PLANOS/pendente/<nome-original>.md` (preservando o nome original do arquivo).
3. **Memória do Projeto (Pilar 6 - @documentacao):** 3. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-YYYY-MM-DD-<slug>.md`. - Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`. - Indexar no `memorias-ia/historico-acoes.md`.
4. **Staging de Segurança:** 4. **Staging de Segurança:**
- Executar `git add <arquivos>` e `git status`. - 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. - 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" "<Nome ou Título do Plano>" sucesso`
- O utilitário detecta automaticamente se o host é Linux (KDE `kdialog`, `notify-send`, `gdbus`, PipeWire/PulseAudio) ou macOS (`osascript` banner nativo + `afplay` áudio Glass + terminal bell `\a`), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI.

29
skills/plano/SKILL.md
View file

@ -2,7 +2,7 @@
name: plano name: plano
description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs
scope: global scope: global
updatedAt: "2026-09-28" updatedAt: "2026-09-30"
--- ---
# Skill: /plano (Criação e Gestão de Planos Técnicos) # 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) # 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado)
/plano.executar # Executa o último plano da conversa ou mais recente /plano.executar # Executa o último plano da conversa ou mais recente
/plano.executar <slug> # Executa plano específico por slug/ID /plano.executar <slug> # 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 # 4. Arquivamento manual de um plano já concluído
/plano arquivar <slug-ou-nome-do-arquivo> /plano arquivar <slug-ou-nome-do-arquivo>
@ -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`): 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 ### 1. Obter Data, Hora e Gerar Slug
- Obtenha a data local atual no formato `YYYY-MM-DD`. - 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). - 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-<slug>.md`. - Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.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) ### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código)
- **NÃO altere arquivos de código de produção nesta etapa.** - **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:** - **Frontmatter YAML:**
```yaml ```yaml
--- ---
id: YYYY-MM-DD-<slug> id: AAAA-MM-DD-HH-mm-<slug>
titulo: "<Título claro e direto>" titulo: "<Título claro e direto>"
origem: "Revisão Tester / QA" origem: "Revisão Tester / QA"
data-criacao: "YYYY-MM-DD" data-criacao: "AAAA-MM-DD HH:mm"
data-execucao: null data-execucao: null
status: "pendente" status: "pendente"
prioridade: "media" # ou critica/alta/baixa 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). - **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`. - **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. - **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`. - Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md` usando `write_to_file`.
### 4. Resposta ao Usuário ### 4. Resposta ao Usuário
- Informe o link do arquivo criado em `./PLANOS/pendente/`. - 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/`. 1. Liste os arquivos existentes em `./PLANOS/pendente/` e `./PLANOS/executado/`.
2. Para cada arquivo, extraia título, data e prioridade do frontmatter. 2. Para cada arquivo, extraia título, data e prioridade do frontmatter.
3. Exiba uma tabela Markdown organizada: 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. - **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`. 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)**: 👉 **[`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md)**:
- `/plano.executar` (sem argumentos: último plano criado na conversa ou pendente mais recente) - `/plano.executar` (sem argumentos: último plano criado na conversa ou pendente mais recente)
- `/plano.executar <slug>` (plano específico) - `/plano.executar <slug>` (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 <slug>`) ## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar <slug-ou-id>`)
Quando um plano foi implementado externamente ou não requer alteração de código: Quando um plano foi implementado externamente ou não requer alteração de código:
1. Localize o arquivo em `./PLANOS/pendente/`. 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` e executor. 2. Atualize o frontmatter para `status: "executado"`, registrando `data-execucao: "AAAA-MM-DD HH:mm"` e executor.
3. Mova o arquivo para `./PLANOS/executado/`. 3. Mova o arquivo para `./PLANOS/executado/` preservando o nome original do arquivo.
4. Notifique o usuário da conclusão do arquivamento. 4. Notifique o usuário da conclusão do arquivamento.