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

implementado graphify.sh

Browse source
This commit is contained in:
Luiz Silva 2026-10-14 17:12:10 -03:00
parent 65a7aeb275
commit cb90e4d858
11 changed files with 261 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored
View file

@ -13,3 +13,8 @@ node_modules/
.vscode/
.idea/
*.swp
# Graphify Knowledge Graph
.graphify/
.engram/
graphify-out/

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

@ -53,6 +53,12 @@ executor: null
- `caminho/do/arquivo1.ts` — <motivo do impacto>
- `caminho/do/arquivo2.vue` — <motivo do impacto>
### Raio de Impacto & Dependências (Graphify)
<!-- Obtido via: bash .agent/scripts/graphify.sh impact <arquivos> (instala automaticamente se ausente, atualiza .gitignore e gera o grafo sob demanda) -->
- **Nós / Símbolos Centrais:** `<funções, rotas ou componentes identificados via graphify.sh query / explain>`
- **Arquivos Dependentes Impactados:** `<arquivos em *-back, *-front, *-comuns afetados em cascata>`
- **Cadeias Críticas / Lacunas de Teste:** `<alertas retornados pelo review-delta do Graphify>`
---
## 3. Critérios de Aceite & Validação (Definition of Done)

17
TOOLS
View file

@ -115,6 +115,17 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
- **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação.
- **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [modulo-override]`
### graphify.sh (`.agent/scripts/graphify.sh`)
- **Descrição:** Utilitário canônico de Grafo de Conhecimento (*Knowledge Graph*) do código-fonte baseado em `@sentropic/graphify`.
- **Por que ajuda as IAs:** Permite que o comando `/plano` e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (*Blast Radius*) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (`bun i -g @sentropic/graphify`) caso não exista na máquina, atualiza o `.gitignore` (`.graphify/`, `.engram/`, `graphify-out/`) e gera o grafo sob demanda (`ensure`).
- **Uso:**
- `bash .agent/scripts/graphify.sh update` (reconstrói/atualiza o grafo AST)
- `bash .agent/scripts/graphify.sh ensure` (garante instalação, `.gitignore` e grafo existente)
- `bash .agent/scripts/graphify.sh query "<termo>" [budget]` (busca nós e arquivos no grafo)
- `bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"` (detalha conexões e imports)
- `bash .agent/scripts/graphify.sh impact <arq1> [arq2...]` (calcula raio de impacto e lacunas de testes via `review-delta`)
- `bash .agent/scripts/graphify.sh summary` (exibe principais hubs e comunidades do projeto)
---
## 8. Instalação Rápida (Copia e Cola)
@ -131,8 +142,8 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh
# 2. Instalar ferramentas em Node
npm install -g @ast-grep/cli @biomejs/biome
# 3. Instalar automação de navegador para IA (visível com --headed)
bun i -g agent-browser && agent-browser install
# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun
bun i -g agent-browser @sentropic/graphify && agent-browser install
# 4. Instalar yq via snap
sudo snap install yq
@ -144,5 +155,5 @@ sudo snap install yq
# Instalar utilitários essenciais
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
npm install -g @biomejs/biome
bun i -g agent-browser && agent-browser install
bun i -g agent-browser @sentropic/graphify && agent-browser install
```

17
TOOLS.md
View file

@ -115,6 +115,17 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
- **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação.
- **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [modulo-override]`
### graphify.sh (`.agent/scripts/graphify.sh`)
- **Descrição:** Utilitário canônico de Grafo de Conhecimento (*Knowledge Graph*) do código-fonte baseado em `@sentropic/graphify`.
- **Por que ajuda as IAs:** Permite que o comando `/plano` e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (*Blast Radius*) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (`bun i -g @sentropic/graphify`) caso não exista na máquina, atualiza o `.gitignore` (`.graphify/`, `.engram/`, `graphify-out/`) e gera o grafo sob demanda (`ensure`).
- **Uso:**
- `bash .agent/scripts/graphify.sh update` (reconstrói/atualiza o grafo AST)
- `bash .agent/scripts/graphify.sh ensure` (garante instalação, `.gitignore` e grafo existente)
- `bash .agent/scripts/graphify.sh query "<termo>" [budget]` (busca nós e arquivos no grafo)
- `bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"` (detalha conexões e imports)
- `bash .agent/scripts/graphify.sh impact <arq1> [arq2...]` (calcula raio de impacto e lacunas de testes via `review-delta`)
- `bash .agent/scripts/graphify.sh summary` (exibe principais hubs e comunidades do projeto)
---
## 8. Instalação Rápida (Copia e Cola)
@ -131,8 +142,8 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh
# 2. Instalar ferramentas em Node
npm install -g @ast-grep/cli @biomejs/biome
# 3. Instalar automação de navegador para IA (visível com --headed)
bun i -g agent-browser && agent-browser install
# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun
bun i -g agent-browser @sentropic/graphify && agent-browser install
# 4. Instalar yq via snap
sudo snap install yq
@ -144,5 +155,5 @@ sudo snap install yq
# Instalar utilitários essenciais
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
npm install -g @biomejs/biome
bun i -g agent-browser && agent-browser install
bun i -g agent-browser @sentropic/graphify && agent-browser install
```

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

@ -123,6 +123,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof
### 1. Leitura e Decomposição
- Lê o plano integralmente com `view_file`.
- Mapeia os critérios de aceite (Definition of Done) na Seção 3 e especificações na Seção 4.
- Caso novos arquivos precisem ser inspecionados além dos previstos no plano, consulta o Grafo de Conhecimento via `bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"` ou `bash .agent/scripts/graphify.sh impact <arquivos>`.
- Orquestrador define os especialistas necessários.
### 2. Implementação Especializada
@ -151,14 +152,16 @@ Ao atingir 100% de conformidade com todos os critérios do plano:
- Seção 6 (*Histórico de Execução*): arquivos modificados, resumo da solução e evidências de validação.
2. **Mover o Plano:**
- Salvar em `./PLANOS/executado/<nome-original>.md` e remover de `./PLANOS/pendente/<nome-original>.md` (preservando o nome original do arquivo).
3. **Memória do Projeto (Pilar 6 - @documentacao):**
3. **Atualizar Grafo de Conhecimento (Graphify):**
- Executar `bash .agent/scripts/graphify.sh update` para atualizar o grafo de código com os novos símbolos, arquivos e relações implementados (garantindo automaticamente a instalação via Bun se ausente e as regras no `.gitignore`).
4. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`.
4. **Staging e Commit Semântico:**
5. **Staging e Commit Semântico:**
- Executar `git add <arquivos>` e `git status`.
- Inspecionar a branch atual com `git branch --show-current`: se estiver em `master` (ou `main`), criar e alternar para uma nova branch semântica (`git checkout -b <tipo>/<slug-plano>`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`).
- Executar o `git commit` semântico na branch de trabalho (`git commit -m "<tipo>(<escopo>): <descrição>"`).
5. **Notificação no Sistema Operacional (Linux & macOS):**
6. **Notificação no Sistema Operacional (Linux & macOS):**
- Disparar notificação sonora e visual no SO via script `.agent/notificar.sh`:
`sh .agent/notificar.sh "Plano Concluído" "<Nome ou Título do Plano>" sucesso`
- O utilitário detecta automaticamente se o host é Linux (KDE `kdialog`, `notify-send`, `gdbus`, PipeWire/PulseAudio) ou macOS (`osascript` banner nativo + `afplay` áudio Glass + terminal bell `\a`), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI.

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

@ -43,10 +43,22 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
- 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 com Graphify (Sem alterar código)
- **NÃO altere arquivos de código de produção nesta etapa.**
- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`).
- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos.
- **Consultar o Grafo de Conhecimento (`graphify.sh`):**
- O utilitário `.agent/scripts/graphify.sh` verifica e instala automaticamente o `@sentropic/graphify` via Bun caso não esteja instalado na máquina, atualiza de forma idempotente o `.gitignore` do projeto (`.graphify/`, `.engram/`, `graphify-out/`) e inicializa o grafo sob demanda (`ensure`) caso ainda não exista:
```bash
# 1. Localizar nós, rotas, tabelas ou componentes relacionados à demanda
bash .agent/scripts/graphify.sh query "<termo-chave-da-demanda>"
bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"
```
- Inspecione rapidamente os arquivos candidatos com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos.
- **Mapear Raio de Impacto em Cascata (*Blast Radius*):**
- Com os arquivos candidatos identificados, execute a análise de impacto no grafo:
```bash
bash .agent/scripts/graphify.sh impact <caminho/arquivo1> <caminho/arquivo2>
```
- Utilize a saída (`Impacted files`, `High-risk dependency chains`, `Likely test gaps`) para determinar com precisão todos os pacotes em `modulos-impactados` (`*-comuns`, `*-back`, `*-front`, `*-migracao`) e mapear efeitos colaterais entre módulos.
- Identifique o comportamento atual vs comportamento esperado.
### 3. Redigir e Persistir o Arquivo de Plano
@ -71,7 +83,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
---
```
- **1. Objetivo & Contexto:** Descrição concisa da demanda e impacto de negócio.
- **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`.
- **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps, arquivos mapeados com links `[arquivo](file://...)` e subseção **Raio de Impacto & Dependências (Graphify)** extraída via `bash .agent/scripts/graphify.sh impact`.
- **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso.
- **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido).
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo>_<contexto?> --headed`.

13
global/workflows/plano.md
View file

@ -52,9 +52,11 @@ Durante a navegação, testes manuais ou homologação de telas e rotas, o teste
Quando o comando for executado:
1. **Interpretação e Diagnóstico Rápido:**
1. **Interpretação e Diagnóstico Rápido com Graphify:**
- A IA extrai o núcleo da demanda (o que está quebrado ou precisa ser feito).
- Consulta o Grafo de Conhecimento via `bash .agent/scripts/graphify.sh query "<termo>"` e `explain "<no>"` (o script instala automaticamente o `@sentropic/graphify` via Bun caso não exista na máquina, atualiza o `.gitignore` e gera o grafo sob demanda).
- Investiga o código-fonte (sem alterá-lo) para identificar arquivos, componentes Vue, rotas Bun/Hono, schemas Zod ou tabelas impactadas.
- Executa `bash .agent/scripts/graphify.sh impact <arquivos...>` para calcular o raio de impacto em cascata (*Blast Radius*), cadeias críticas e lacunas de testes entre pacotes.
- Identifica a causa raiz ou o ponto exato de intervenção.
2. **Formatação do Nome do Arquivo:**
@ -67,7 +69,7 @@ Quando o comando for executado:
- Preenche:
- 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).
- Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados).
- Diagnóstico Técnico & Evidências (repro steps, arquivos mapeados e **Raio de Impacto & Dependências via Graphify**).
- Critérios de Aceite (Definition of Done).
- Especificação Técnica passo a passo para orientar o desenvolvedor.
- Plano de Verificação & Testes.
@ -126,12 +128,15 @@ Ao confirmar que a implementação está verde e validada:
para:
`PLANOS/executado/<nome-original>.md`
3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):**
3. **Atualização do Grafo de Conhecimento (Graphify):**
- Executa `bash .agent/scripts/graphify.sh update` para sincronizar o grafo do projeto com as alterações recém-implementadas.
4. **Registro na Memória do Projeto (Pilar 6 - @documentacao):**
- Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexa no `memorias-ia/historico-acoes.md`.
- Executa `git add` nos arquivos alterados e realiza o `git commit` semântico (se a branch atual for `master`, cria e seleciona previamente uma nova branch de trabalho — nunca comita em `master`, conforme `rules/proibido-commit-ia.md`).
4. **Notificação no Sistema Operacional (Linux & macOS):**
5. **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.

156
scripts/graphify.sh Executable file
View file

@ -0,0 +1,156 @@
#!/usr/bin/env bash
# ==============================================================================
# Utilitário Canônico do Graphify (.agent/scripts/graphify.sh)
# Gerencia instalação automática via Bun, atualização idempotente do .gitignore,
# geração sob demanda (ensure) e consultas ao Grafo de Conhecimento para /plano.
# ==============================================================================
set -e
export PATH="$HOME/.bun/bin:$PATH"
export ENGRAM_QUIET_DEPRECATION=1
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# Resolver diretório raiz do projeto hospedeiro
resolver_raiz_projeto() {
local super_dir
super_dir=$(git -C "$SCRIPT_DIR" rev-parse --show-superproject-working-tree 2>/dev/null || true)
if [ -n "$super_dir" ]; then
echo "$super_dir"
return
fi
local candidato
candidato="$(cd "$SCRIPT_DIR/../.." && pwd)"
if [ -d "$candidato/.agent" ] || [ -f "$candidato/memorias-ia/modulo.yml" ]; then
echo "$candidato"
return
fi
pwd
}
SUPER_DIR="$(resolver_raiz_projeto)"
# 1. Garantir entradas do Graphify no .gitignore do projeto hospedeiro
garantir_gitignore() {
local gitignore_file="$SUPER_DIR/.gitignore"
if [ ! -f "$gitignore_file" ]; then
touch "$gitignore_file"
fi
local adicionou_cabecalho=0
if grep -qE "^# Graphify Knowledge Graph" "$gitignore_file" 2>/dev/null; then
adicionou_cabecalho=1
fi
for entrada in ".graphify/" ".engram/" "graphify-out/"; do
if ! grep -qxF "$entrada" "$gitignore_file" 2>/dev/null; then
if [ "$adicionou_cabecalho" -eq 0 ]; then
printf "\n# Graphify Knowledge Graph\n" >> "$gitignore_file"
adicionou_cabecalho=1
fi
printf "%s\n" "$entrada" >> "$gitignore_file"
fi
done
}
# 2. Garantir que o Graphify esteja instalado na máquina (via Bun)
garantir_instalacao() {
local forcar="${1:-0}"
if [ "$forcar" = "1" ] || { ! command -v graphify >/dev/null 2>&1 && ! command -v engram >/dev/null 2>&1; }; then
if command -v bun >/dev/null 2>&1; then
echo "📦 Instalando/atualizando Graphify globalmente via Bun (@sentropic/graphify)..." >&2
bun i -g @sentropic/graphify >&2 || true
fi
fi
}
# 3. Executar o binário do Graphify com fallback para bunx / bun x
executar_graphify() {
if command -v graphify >/dev/null 2>&1; then
graphify "$@"
elif command -v engram >/dev/null 2>&1; then
engram "$@"
elif command -v bunx >/dev/null 2>&1; then
bunx @sentropic/graphify "$@"
elif command -v bun >/dev/null 2>&1; then
bun x @sentropic/graphify "$@"
else
echo "Erro: Graphify não encontrado no PATH e Bun (bun/bunx) não está disponível na máquina." >&2
exit 1
fi
}
# 4. Garantir existência do grafo sob demanda (modo ensure)
garantir_grafo() {
garantir_gitignore
garantir_instalacao 0
if [ ! -f "$SUPER_DIR/.engram/graph.json" ] && [ ! -f "$SUPER_DIR/.graphify/graph.json" ]; then
echo "📊 Grafo de conhecimento ainda não existe em $SUPER_DIR. Gerando automaticamente..." >&2
(cd "$SUPER_DIR" && executar_graphify update . --no-description >&2)
fi
}
SUBCOMANDO="${1:-update}"
if [ $# -gt 0 ]; then
shift
fi
case "$SUBCOMANDO" in
install)
garantir_gitignore
garantir_instalacao 1
echo "✅ Graphify instalado e .gitignore atualizado em $SUPER_DIR!"
;;
gitignore)
garantir_gitignore
echo "✅ .gitignore verificado e atualizado em $SUPER_DIR!"
;;
ensure)
garantir_grafo
;;
update)
garantir_gitignore
garantir_instalacao 0
echo "📊 Atualizando o grafo de conhecimento (Graphify) em $SUPER_DIR..."
(cd "$SUPER_DIR" && executar_graphify update . --no-description "$@")
echo "✅ Grafo atualizado com sucesso!"
;;
query)
if [ $# -lt 1 ]; then
echo "Uso: sh .agent/scripts/graphify.sh query \"<termo-ou-pergunta>\" [budget]" >&2
exit 1
fi
TERMO="$1"
BUDGET="${2:-1500}"
garantir_grafo
(cd "$SUPER_DIR" && executar_graphify query "$TERMO" --budget "$BUDGET")
;;
explain)
if [ $# -lt 1 ]; then
echo "Uso: sh .agent/scripts/graphify.sh explain \"<no-ou-arquivo>\"" >&2
exit 1
fi
garantir_grafo
(cd "$SUPER_DIR" && executar_graphify explain "$@")
;;
impact)
garantir_grafo
if [ $# -eq 0 ]; then
(cd "$SUPER_DIR" && executar_graphify review-delta --depth 2)
else
CSV_FILES=$(IFS=,; echo "$*")
(cd "$SUPER_DIR" && executar_graphify review-delta --files "$CSV_FILES" --depth 2)
fi
;;
summary)
garantir_grafo
(cd "$SUPER_DIR" && executar_graphify summary --top-hubs 5 --top-communities 5 "$@")
;;
*)
garantir_grafo
(cd "$SUPER_DIR" && executar_graphify "$SUBCOMANDO" "$@")
;;
esac

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

@ -123,6 +123,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof
### 1. Leitura e Decomposição
- Lê o plano integralmente com `view_file`.
- Mapeia os critérios de aceite (Definition of Done) na Seção 3 e especificações na Seção 4.
- Caso novos arquivos precisem ser inspecionados além dos previstos no plano, consulta o Grafo de Conhecimento via `bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"` ou `bash .agent/scripts/graphify.sh impact <arquivos>`.
- Orquestrador define os especialistas necessários.
### 2. Implementação Especializada
@ -151,14 +152,16 @@ Ao atingir 100% de conformidade com todos os critérios do plano:
- Seção 6 (*Histórico de Execução*): arquivos modificados, resumo da solução e evidências de validação.
2. **Mover o Plano:**
- Salvar em `./PLANOS/executado/<nome-original>.md` e remover de `./PLANOS/pendente/<nome-original>.md` (preservando o nome original do arquivo).
3. **Memória do Projeto (Pilar 6 - @documentacao):**
3. **Atualizar Grafo de Conhecimento (Graphify):**
- Executar `bash .agent/scripts/graphify.sh update` para atualizar o grafo de código com os novos símbolos, arquivos e relações implementados (garantindo automaticamente a instalação via Bun se ausente e as regras no `.gitignore`).
4. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`.
4. **Staging e Commit Semântico:**
5. **Staging e Commit Semântico:**
- Executar `git add <arquivos>` e `git status`.
- Inspecionar a branch atual com `git branch --show-current`: se estiver em `master` (ou `main`), criar e alternar para uma nova branch semântica (`git checkout -b <tipo>/<slug-plano>`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`).
- Executar o `git commit` semântico na branch de trabalho (`git commit -m "<tipo>(<escopo>): <descrição>"`).
5. **Notificação no Sistema Operacional (Linux & macOS):**
6. **Notificação no Sistema Operacional (Linux & macOS):**
- Disparar notificação sonora e visual no SO via script `.agent/notificar.sh`:
`sh .agent/notificar.sh "Plano Concluído" "<Nome ou Título do Plano>" sucesso`
- O utilitário detecta automaticamente se o host é Linux (KDE `kdialog`, `notify-send`, `gdbus`, PipeWire/PulseAudio) ou macOS (`osascript` banner nativo + `afplay` áudio Glass + terminal bell `\a`), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI.

20
skills/plano/SKILL.md
View file

@ -43,10 +43,22 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
- 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 com Graphify (Sem alterar código)
- **NÃO altere arquivos de código de produção nesta etapa.**
- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`).
- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos.
- **Consultar o Grafo de Conhecimento (`graphify.sh`):**
- O utilitário `.agent/scripts/graphify.sh` verifica e instala automaticamente o `@sentropic/graphify` via Bun caso não esteja instalado na máquina, atualiza de forma idempotente o `.gitignore` do projeto (`.graphify/`, `.engram/`, `graphify-out/`) e inicializa o grafo sob demanda (`ensure`) caso ainda não exista:
```bash
# 1. Localizar nós, rotas, tabelas ou componentes relacionados à demanda
bash .agent/scripts/graphify.sh query "<termo-chave-da-demanda>"
bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"
```
- Inspecione rapidamente os arquivos candidatos com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos.
- **Mapear Raio de Impacto em Cascata (*Blast Radius*):**
- Com os arquivos candidatos identificados, execute a análise de impacto no grafo:
```bash
bash .agent/scripts/graphify.sh impact <caminho/arquivo1> <caminho/arquivo2>
```
- Utilize a saída (`Impacted files`, `High-risk dependency chains`, `Likely test gaps`) para determinar com precisão todos os pacotes em `modulos-impactados` (`*-comuns`, `*-back`, `*-front`, `*-migracao`) e mapear efeitos colaterais entre módulos.
- Identifique o comportamento atual vs comportamento esperado.
### 3. Redigir e Persistir o Arquivo de Plano
@ -71,7 +83,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
---
```
- **1. Objetivo & Contexto:** Descrição concisa da demanda e impacto de negócio.
- **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`.
- **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps, arquivos mapeados com links `[arquivo](file://...)` e subseção **Raio de Impacto & Dependências (Graphify)** extraída via `bash .agent/scripts/graphify.sh impact`.
- **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso.
- **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido).
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo>_<contexto?> --headed`.

15
validar-setup.sh
View file

@ -182,14 +182,25 @@ else
echo -e " ${AZUL}ℹ${RESET} .agent-local/ ausente (usando 100% regras e skills globais)."
fi
# 6. Validar Limite de Linhas (Governança de Código)
echo -e "\n${NEGRITO}[6/6] Governança de Código (verificar-linhas.sh)${RESET}"
# 6. Validar Limite de Linhas e Grafo de Conhecimento (Governança de Código)
echo -e "\n${NEGRITO}[6/6] Governança de Código & Graphify (verificar-linhas.sh / graphify.sh)${RESET}"
if [ -f "$ROOT_DIR/.agent/verificar-linhas.sh" ]; then
sh "$ROOT_DIR/.agent/verificar-linhas.sh" > /dev/null 2>&1 && \
echo -e " ${VERDE}✓${RESET} 100% dos arquivos dentro do limite de 250 linhas." || \
echo -e " ${AMARELO}⚠${RESET} Há arquivos excedendo 250 linhas (execute sh .agent/verificar-linhas.sh)."
fi
if [ -f "$ROOT_DIR/.agent/scripts/graphify.sh" ]; then
bash "$ROOT_DIR/.agent/scripts/graphify.sh" gitignore > /dev/null 2>&1 || true
echo -e " ${VERDE}✓${RESET} .gitignore configurado para Graphify (.graphify/, .engram/, graphify-out/)."
export PATH="$HOME/.bun/bin:$PATH"
if command -v graphify >/dev/null 2>&1 || command -v engram >/dev/null 2>&1; then
echo -e " ${VERDE}✓${RESET} CLI Graphify instalado na máquina."
else
echo -e " ${AZUL}ℹ${RESET} CLI Graphify será instalado automaticamente via Bun no primeiro uso de graphify.sh."
fi
fi
# Resumo Final
echo -e "\n${AZUL}${NEGRITO}======================================================${RESET}"
if [ "$TOTAL_ERROS" -eq 0 ]; then