@seedgrid/ai-toolkit 0.3.1 → 0.3.3

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-crud
+name: sg-crud-front
 description: Create or refactor SeedGrid CRUD flows in a Next.js app built on the SeedGrid boilerplate, using the project standard of separate `*_list` and `*_edit` pages, `publicId` routing, Next API proxy routes, and SeedGrid components. Use when you need to build or standardize an entity CRUD (users, roles, plans, API keys, audit screens, etc.) with `SgDatatable`, `SgInputTextSearch`, permissions, user-facing copy, and menu/breadcrumb integration.
 ---
 
@@ -13,7 +13,7 @@ Read the existing screens of the project before writing a new one and copy their
 hooks, helpers). The names below (`Shell`, `useSavedToast`, `ListLoadError`, `adminProxyClient`, ...)
 are the boilerplate's own; if the project names them differently, use the project's equivalents.
 
-To register the menu item, icon and permission of a new screen, use the `seedgrid-new-screen` skill.
+To register the menu item, icon and permission of a new screen, use the `sg-new-screen` skill.
 
 ## Workflow
 
@@ -31,10 +31,10 @@ To register the menu item, icon and permission of a new screen, use the `seedgri
 
 ## Required Patterns
 
-- Use the list/edit split described in `references/patterns.md`.
-- Use `publicId` routing and proxy conventions from `references/routing.md`.
+- Use the list/edit split described in `references/crud-front-patterns.md`.
+- Use `publicId` routing and proxy conventions from `references/crud-front-routing.md`.
 - Use `SgInputTextSearch` as the standard remote-search input.
-- Use the checklist in `references/checklist.md` before closing the task.
+- Use the checklist in `references/crud-front-checklist.md` before closing the task.
 
 ## Required UI Components
 

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SeedGrid CRUD"
   short_description: "Padrao CRUD SeedGrid"
-  default_prompt: "Use $seedgrid-crud to create a SeedGrid CRUD with list/edit pages, publicId routing, and SgInputTextSearch."
+  default_prompt: "Use $sg-crud-front to create a SeedGrid CRUD with list/edit pages, publicId routing, and SgInputTextSearch."

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud/references/routing.md → sg-crud-front/references/crud-front-routing.md}

@@ -63,4 +63,4 @@ Resources behind a CRUD should:
 - Menu item should point to the real list route
 - Breadcrumb items must use valid `href` values
 - Parent sections like `/security` must resolve to a real child route if there is no standalone page
-- Registering the menu item, icon and permission is covered by the `seedgrid-new-screen` skill
+- Registering the menu item, icon and permission is covered by the `sg-new-screen` skill

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-new-screen → sg-new-screen}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-new-screen
+name: sg-new-screen
 description: Registrar uma tela, menu ou permissao nova no boilerplate SeedGrid (app do cliente `frontend/` ou admin da plataforma `admin/`) sem esquecer nenhum dos lugares que precisam ficar sincronizados - migration da permissao, item de menu, icone, item ativo, catalogo do editor de perfis e, se for vendavel por plano, o treeview de features do admin e o `@RequiresPlanFeature`. Use ao criar tela nova, acao nova numa tela existente, permissao nova, ou ao mover/renomear item de menu.
 ---
 
@@ -19,7 +19,7 @@ Nao executar sem o usuario pedir.)
 
 ## Passo a passo
 
-Detalhes e exemplos de codigo de cada passo em `references/steps.md`.
+Detalhes e exemplos de codigo de cada passo em `references/new-screen-steps.md`.
 
 1. **Permissao (backend)** - migration nova em `backend/src/main/resources/db/migration/app/`
    (`V3xxx__<assunto>.sql`, nunca editar uma ja aplicada): `insert into permissions` com o `audience` certo,
@@ -43,7 +43,7 @@ Detalhes e exemplos de codigo de cada passo em `references/steps.md`.
 
 ## Verificacao
 
-Rodar o checklist de `references/checklist.md` antes de encerrar. No minimo:
+Rodar o checklist de `references/new-screen-checklist.md` antes de encerrar. No minimo:
 
 ```bash
 # os dois catalogos do cliente iguais (ignorando fim de linha)

package/seedgridKB/SeedGrid/Toolkit/skills/sg-new-screen/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SeedGrid tela nova"
+  short_description: "Tela, menu e permissoes sincronizados"
+  default_prompt: "Use $sg-new-screen to add a new screen with its permissions, menu item, icon, profile-editor catalog and, if sellable, the plan feature tree."

package/seedgridKB/SeedGrid/Toolkit/skills/sg-new-skill/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sg-new-skill
+description: Cria ou altera uma skill do projeto - pergunta nome, descrição, quando usar e passos, grava o SKILL.md em .ai/skills e sincroniza as pastas nativas do Claude Code e do Codex, atualizando o índice. Use SEMPRE que pedirem para criar, adicionar, escrever, editar, ajustar, renomear ou remover uma skill, ou para transformar um procedimento repetido em skill.
+metadata:
+  toolkit: seedgrid-ai
+---
+
+# Criar ou alterar uma skill
+
+Toda skill nova do projeto nasce por aqui, e toda alteração passa por aqui, para ficar completa e nos lugares certos. Não crie nem edite skill escrevendo arquivos soltos. Para **alterar** uma skill existente, vá direto à seção [Alterar uma skill existente](#alterar-uma-skill-existente); os passos abaixo são de **criação**.
+
+## Passos (criar)
+
+1. **Levantar os dados.** Pergunte o que faltar (junte as perguntas numa só mensagem e não pergunte o que o pedido já respondeu):
+   - **Nome:** minúsculas, números e hífens (`^[a-z0-9]+(-[a-z0-9]+)*$`), curto e específico (`gerar-relatorio-mensal`). Verbo ou tarefa, não "ajuda".
+   - **Objetivo:** o que a skill faz e o resultado esperado.
+   - **Quando usar:** os pedidos e situações que devem acioná-la (e, se houver, quando **não** usar).
+   - **Passos:** o procedimento, as regras e os cuidados. Se o usuário não tiver, proponha um rascunho e peça confirmação.
+   - **Arquivos de apoio:** checklists, exemplos ou scripts que valham um arquivo à parte (opcional).
+2. **Conferir duplicidade.** Veja `.ai/skills/`, `.claude/skills/` e `.agents/skills/`. Se já existir skill com o nome, ou outra que cubra o mesmo caso, mostre e pergunte se estende a existente. Nunca sobrescreva sem pedido explícito. Nomes que começam com `sg-` são reservados às skills do toolkit: o `update` as gerencia e uma skill do projeto com esse prefixo pode ser substituída. Não use `sg-` nas skills do projeto; se o usuário pedir esse prefixo, avise do risco e sugira outro.
+3. **Escrever o `SKILL.md`** em `.ai/skills/<nome>/SKILL.md`:
+   - Frontmatter só com `name` (igual ao nome da pasta) e `description`. Não use campos específicos de uma ferramenta (`context`, `allowed-tools`, `model` etc.).
+   - `description` em uma ou duas frases: o que faz **e quando usar**, com as palavras que o usuário diria. Se tiver `:`, ponha entre aspas. É por ela que o modelo decide chamar a skill, então seja específico.
+   - Corpo curto e direto: passos numerados, regras e saída esperada. Detalhes longos vão em `references/<assunto>.md`, citados no `SKILL.md` com link relativo. Nada de segredos, nem caminhos absolutos da sua máquina.
+4. **Copiar para as pastas nativas**, com o mesmo conteúdo (inclusive `references/` e demais arquivos), apenas nos destinos que o projeto usa: `.claude/skills/<nome>/` se a pasta `.claude/skills/` existir, `.agents/skills/<nome>/` se `.agents/skills/` existir. Sem nenhuma das duas, fique só com `.ai/skills/` e avise que a skill só será usada se o modelo ler o índice.
+5. **Registrar no índice do projeto.** Acrescente a skill em `.ai/skills/projeto.md` (crie se não existir, com o título `# Skills do projeto`), uma linha por skill: `- [nome](nome/SKILL.md): descrição`. **Não edite `.ai/skills/index.md`**: ele é gerado pelo toolkit e o `update` o reescreve (ele já cita o `projeto.md`).
+6. **Conferir.** Releia o `SKILL.md` gravado, confirme que as cópias são idênticas à de `.ai/skills/`, que nenhum link relativo está quebrado e que o `name` bate com a pasta.
+7. **Entregar.** Liste os arquivos criados e diga como usar: pelo nome (`/<nome>` no Claude Code, `$<nome>` no Codex) ou pedindo a tarefa com as palavras da descrição. Avise que uma sessão nova da ferramenta é necessária para listar a skill no menu.
+
+## Alterar uma skill existente
+
+Vale para editar o conteúdo, ajustar a descrição, renomear ou remover.
+
+1. **Localizar.** Confirme o nome em `.ai/skills/`. Se não existir, ofereça criar (passos acima). Leia a `.ai/skills/<nome>/` inteira (`SKILL.md` e `references/`).
+2. **Verificar o dono.** Se o nome começa com `sg-`, ela é do toolkit: o `seedgrid-ai update` a sobrescreve e a edição local se perde. Avise e ofereça duas saídas: (a) alterar no conteúdo do `seedgrid-ai` (fonte e manifesto) para valer para todos; (b) criar uma skill do projeto com outro nome, sem `sg-`, que estenda ou substitua o comportamento. Só edite a cópia local de uma `sg-*` se o usuário insistir, e deixe claro que é temporário.
+3. **Comparar as cópias.** Veja se `.claude/skills/<nome>/` e `.agents/skills/<nome>/` (as que existirem) estão iguais a `.ai/skills/<nome>/`. Se divergirem, mostre a diferença e pergunte qual vale antes de editar.
+4. **Combinar a mudança.** Resuma o que vai mudar (antes e depois) e confirme se for uma mudança grande. Respeite as regras do passo 3 de criação: frontmatter só com `name` e `description`, corpo curto, detalhes em `references/`.
+5. **Editar em `.ai/skills/<nome>/`** e só depois replicar o resultado, com o mesmo conteúdo, nas pastas nativas que o projeto usa.
+   - **Renomear:** mude a pasta e o `name` do frontmatter, nas três pastas e nos links relativos. Procure referências ao nome antigo em outras skills, em `.ai/rules/` e no `projeto.md`.
+   - **Remover:** só com pedido explícito. Apague a pasta nas três e a linha do `projeto.md`.
+6. **Atualizar o índice.** Se a descrição, o nome ou a existência mudou, ajuste a linha em `.ai/skills/projeto.md`. Não edite `.ai/skills/index.md`.
+7. **Conferir.** Releia o `SKILL.md` gravado, confirme que as cópias são idênticas, que nenhum link relativo está quebrado e que o `name` bate com a pasta.
+8. **Entregar.** Liste os arquivos alterados, resuma a mudança e avise que uma sessão nova da ferramenta é necessária para o menu refletir nome ou descrição novos.
+
+## Cuidados
+
+- Skills do projeto (inclusive o `projeto.md`) não entram no lock do toolkit: o `seedgrid-ai update` atualiza o conteúdo do toolkit e não as altera nem as remove. Para virarem parte do toolkit, precisam ser adicionadas ao conteúdo do `seedgrid-ai` (fonte e manifesto).
+- Uma skill, uma finalidade. Se a descrição precisa de "e também", provavelmente são duas skills.
+- Não duplique regras que já estão em `.ai/rules/`: cite o arquivo.
+- Nunca deixe as cópias divergirem: toda edição termina com as três pastas idênticas.

package/seedgridKB/SeedGrid/Toolkit/skills/{planejar-mudanca → sg-plan-change}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: planejar-mudanca
+name: sg-plan-change
 description: Planeja uma mudança de código antes de implementar - entende o objetivo, lê o código afetado, define critérios de aceite, divide em tarefas e identifica riscos. Use quando a tarefa atravessa vários arquivos ou camadas, é ambígua ou envolve decisão de arquitetura.
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-review → sg-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-review
+name: sg-review
 description: Verifica se o código-fonte de um projeto segue os padrões SeedGrid (front React com @seedgrid/fe-components e back Java), citando cada violação por id de regra, arquivo e linha. Use quando pedirem para revisar, auditar ou conferir o padrão SeedGrid, depois de implementar uma tela ou serviço, ou antes de abrir um PR. Aceita o escopo "front", "back" ou nenhum (os dois).
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/SeedGrid/Toolkit/skills/{validar-mudanca → sg-validate-change}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: validar-mudanca
+name: sg-validate-change
 description: Valida uma mudança de código executando build, testes e verificações ligadas aos critérios de aceite, e registra evidências em um relatório. Use antes de declarar uma tarefa concluída ou após correções de revisão.
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/SeedGrid/Visao-geral.md

@@ -16,10 +16,17 @@ Base de documentação técnica do ecossistema SeedGrid, gerada a partir do cód
 | Crates Rust | `rust/` | Portes 1:1 das extensions para servidores Axum (Java é a fonte da verdade), mais `broker` (mensageria) e `runtime`/`macros` (auto-wiring estilo CDI). |
 | Front-end | `front/seedgrid-fe-components` | Biblioteca React `@seedgrid/fe-components` (componentes `Sg*`), tema, core de módulos, playground e módulos de tela `@seedgrid/fe-*` que consomem as APIs das extensions. |
 
+## Produtos
+
+| Produto | O que é | Documentação |
+|---|---|---|
+| **SeedGrid Pulse** | Hub realtime (REST + WebSocket, replay, retry, DLQ, presença) com SDKs publisher/subscriber em várias linguagens. Pode ser usado por qualquer sistema SeedGrid. | [[SeedGrid/Produtos/Pulse/Visao-geral\|Pulse]] · [[SeedGrid/Produtos/Pulse/Servidor/Instalacao\|servidor]] · [[SeedGrid/Produtos/Pulse/UI/Visao-geral\|UI]] · [[SeedGrid/Produtos/Pulse/SDKs\|SDKs]] |
+
 ## Por onde começar
 
 - **Esqueci o nome de uma propriedade** → [[SeedGrid/Extensions/Catalogo-de-propriedades|Catálogo de propriedades]] (busque com `Ctrl+F` ou pela busca do Obsidian).
 - **Quais valores um enum aceita / o que cada valor faz** → [[SeedGrid/Extensions/Catalogo-de-enums|Catálogo de enums]].
+- **Quero usar o Pulse (realtime, notificações, WebSocket)** → [[SeedGrid/Produtos/Pulse/Visao-geral|Pulse]].
 - **Quero entender uma extension** → [[SeedGrid/Extensions/Indice|Índice das extensions]].
 - **Quero usar um componente React** → [[SeedGrid/SeedGrid-components/Indice|Índice dos componentes]].
 - **Quero saber o que depende do quê** → [[SeedGrid/Mapa-dos-repositorios|Mapa dos repositórios]].

package/seedgridKB/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "contentVersion": "0.3.1",
+  "contentVersion": "0.3.3",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     {
@@ -21,6 +21,7 @@
       "files": [
         "rules/coordenacao.md",
         "rules/formato-entrega.md",
+        "rules/documentos.md",
         "rules/personalizacao-local.md",
         "rules/frontend-seedgrid.md",
         "rules/backend-java-seedgrid.md"
@@ -45,9 +46,9 @@
       ]
     },
     {
-      "id": "skill:planejar-mudanca",
+      "id": "skill:sg-plan-change",
       "type": "skill",
-      "name": "planejar-mudanca",
+      "name": "sg-plan-change",
       "files": [
         "SKILL.md",
         {
@@ -57,18 +58,18 @@
       ]
     },
     {
-      "id": "skill:revisar-codigo",
+      "id": "skill:sg-code-review",
       "type": "skill",
-      "name": "revisar-codigo",
+      "name": "sg-code-review",
       "files": [
         "SKILL.md",
-        "references/checklist.md"
+        "references/code-review-checklist.md"
       ]
     },
     {
-      "id": "skill:validar-mudanca",
+      "id": "skill:sg-validate-change",
       "type": "skill",
-      "name": "validar-mudanca",
+      "name": "sg-validate-change",
       "files": [
         "SKILL.md",
         {
@@ -78,48 +79,56 @@
       ]
     },
     {
-      "id": "skill:seedgrid-backend-crud",
+      "id": "skill:sg-crud-back",
       "type": "skill",
-      "name": "seedgrid-backend-crud",
+      "name": "sg-crud-back",
       "files": [
         "SKILL.md"
       ]
     },
     {
-      "id": "skill:seedgrid-crud",
+      "id": "skill:sg-crud-front",
       "type": "skill",
-      "name": "seedgrid-crud",
+      "name": "sg-crud-front",
       "files": [
         "SKILL.md",
-        "references/patterns.md",
-        "references/routing.md",
-        "references/checklist.md",
+        "references/crud-front-patterns.md",
+        "references/crud-front-routing.md",
+        "references/crud-front-checklist.md",
         "agents/openai.yaml"
       ]
     },
     {
-      "id": "skill:seedgrid-new-screen",
+      "id": "skill:sg-new-screen",
       "type": "skill",
-      "name": "seedgrid-new-screen",
+      "name": "sg-new-screen",
       "files": [
         "SKILL.md",
-        "references/steps.md",
-        "references/checklist.md",
+        "references/new-screen-steps.md",
+        "references/new-screen-checklist.md",
         "agents/openai.yaml"
       ]
     },
     {
-      "id": "skill:seedgrid-bump",
+      "id": "skill:sg-bump",
       "type": "skill",
-      "name": "seedgrid-bump",
+      "name": "sg-bump",
       "files": [
         "SKILL.md"
       ]
     },
     {
-      "id": "skill:seedgrid-review",
+      "id": "skill:sg-new-skill",
       "type": "skill",
-      "name": "seedgrid-review",
+      "name": "sg-new-skill",
+      "files": [
+        "SKILL.md"
+      ]
+    },
+    {
+      "id": "skill:sg-review",
+      "type": "skill",
+      "name": "sg-review",
       "files": [
         "SKILL.md"
       ]

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-new-screen/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SeedGrid tela nova"
-  short_description: "Tela, menu e permissoes sincronizados"
-  default_prompt: "Use $seedgrid-new-screen to add a new screen with its permissions, menu item, icon, profile-editor catalog and, if sellable, the plan feature tree."