@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-crud/references/patterns.md

@@ -0,0 +1,185 @@
+# CRUD Page Pattern
+
+Use this structure for every entity CRUD.
+
+## 1. List Page
+
+File pattern:
+
+- `app/<module>/<entity>/<entity>_list/page.tsx`
+
+Responsibilities:
+
+- Load paginated server-side data through `/api/<module>/<entity>`
+- Render `SgDatatable`
+- Render `SgInputTextSearch`
+- Show `ListLoadError` (with retry) instead of the table when the load fails
+- Support sort, page, and empty states
+- Navigate to `<entity>_edit`
+- Gate actions by permission
+
+Expected behavior:
+
+- `Novo` button opens `<entity>_edit`
+- edit action opens `<entity>_edit?publicId=...`
+- delete action opens an `SgConfirmationDialog` (never `window.confirm`); only on
+  confirm does it call `/api/<module>/<entity>/{publicId}`
+- success returns to the list with a query flag such as `?saved=created`
+
+Toolbar layout:
+
+- Use `SgStack direction="row" align="end" gap={12} wrap`, not a 50/50 `SgGrid`
+- `SgInputTextSearch` grows inside `<div style={{ flex: 1, minWidth: 240 }}>`
+- `Novo` button stays compact (`label="Novo"`, `size="md"`) and is height-matched
+  to the input with `style={{ height: 44 }}` (input is `h-11`, button `md` is
+  `h-10`)
+
+Recommended state shape:
+
+```ts
+type QueryState = {
+  page: number;
+  rows: number;
+  search: string;
+  sortField: string;
+  sortOrder: "asc" | "desc";
+};
+```
+
+## 2. Edit Page
+
+File pattern:
+
+- `app/<module>/<entity>/<entity>_edit/page.tsx`
+
+Responsibilities:
+
+- Read `publicId` from `searchParams`
+- If `publicId` exists, load the entity through `/api/<module>/<entity>/{publicId}`
+- If absent, open in create mode
+- Save through `POST` or `PUT`
+- Redirect back to `<entity>_list`
+
+Expected behavior:
+
+- Dedicated page only, never inline edit inside the list
+- Use SeedGrid form controls
+- Show skeleton while loading existing data
+- Show user-facing save errors (`extractApiErrorMessage` with a generic fallback)
+- On success, go back to the list with `?saved=created` / `?saved=updated`; the list shows the toast (`useSavedToast`)
+
+### Input type by data type
+
+Match the input to the field's data type. Do **not** use `SgInputText` for
+numbers or money: it accepts letters and only fails at submit.
+
+| Field kind | Component | Key props | Parse on submit |
+| --- | --- | --- | --- |
+| Money (price, fee, overage, balance) | `SgInputCurrency` | `currency="BRL"`, `decimals={2}`, `minValue={0}` | `parseDecimalInput` |
+| Integer count (requests, users, qty, billing day) | `SgInputNumber` | `decimals={0}`, `minValue={...}` | `Number.parseInt(v, 10)` |
+| Decimal non-money (rate, factor) | `SgInputNumber` | `decimals={2}` | `parseDecimalInput` |
+| Date | `SgInputDate` | — | ISO on submit |
+| Free text | `SgInputText` | — | trim |
+
+Both numeric inputs are controlled via `inputProps={{ value }}` and emit a string
+through `onChange`. Keep form state as the raw string; convert only on submit.
+
+```tsx
+// money
+<SgInputCurrency
+  id="<entity>-price"
+  label="Preco mensal"
+  currency="BRL"
+  decimals={2}
+  minValue={0}
+  inputProps={{ value: form.price }}
+  onChange={(price) => setForm((f) => ({ ...f, price }))}
+/>
+
+// integer count
+<SgInputNumber
+  id="<entity>-requests"
+  label="Requests/mes"
+  decimals={0}
+  minValue={1}
+  inputProps={{ value: form.requests }}
+  onChange={(requests) => setForm((f) => ({ ...f, requests }))}
+/>
+```
+
+## 3. Shell Copy
+
+Use business language, not implementation language.
+
+Good:
+
+- `Consulte os planos disponiveis`
+- `Atualize as informacoes do usuario`
+
+Bad:
+
+- `listagem administrativa paginada no servidor`
+- `debounce, distinct e cancelamento`
+- `pagina dedicada`
+
+## 4. Skeleton Pattern
+
+The table loading state must read as a table, not a single grey rectangle. Use a
+table-shaped skeleton: one header row plus several body rows of `shape="text"`
+skeletons, so the placeholder suggests multiple columns and fields.
+
+Prefer the shared `DatatableSkeleton` helper (in `app/components`) and match the
+real column count and page size:
+
+```tsx
+{loading ? (
+  <DatatableSkeleton columns={columns.length} rows={Math.min(queryState.rows, 8)} />
+) : (
+  <SgDatatable ... />
+)}
+```
+
+Underlying structure the helper renders (replicate if a shared helper is not
+available):
+
+```tsx
+<div className="overflow-hidden rounded-lg border border-border">
+  <div className="grid gap-3 border-b border-border p-3" style={{ gridTemplateColumns }}>
+    {/* one text skeleton per column = header */}
+  </div>
+  {/* N rows, each with one text skeleton per column, last:border-b-0 */}
+</div>
+```
+
+Do not use a single `<SgSkeleton shape="rectangle" />` for table loading. Cap the
+row count (e.g. `Math.min(pageSize, 8)`) so large page sizes do not render dozens
+of skeleton rows.
+
+Form/edit pages may still use a single rectangular `SgSkeleton` while loading the
+entity.
+
+## 5. Status Badge Colors (boolean columns)
+
+Boolean state columns (active, 2FA, integration, etc.) must read at a glance with
+strong semantic colors — never a washed-out `secondary` grey for the "off" state.
+Use `StatusBadge` with an explicit `severity`:
+
+- The neutral/desirable state is `success` (green).
+- The opposite state is `danger` (red).
+- Do not use `secondary` or `info` for these two-state columns.
+
+```tsx
+// active / enabled
+<StatusBadge severity={row.active ? "success" : "danger"} value={row.active ? "ATIVO" : "INATIVO"} />
+
+// 2FA
+<StatusBadge severity={row.twoFactorEnabled ? "success" : "danger"} value={row.twoFactorEnabled ? "ATIVO" : "DESATIVADO"} />
+```
+
+Pick which boolean value is green by meaning, not by `true`/`false`. For example a
+role's "for integration" flag is the exception: a non-integration role is the safe
+default (`success`/green) and an integration role is flagged (`danger`/red):
+
+```tsx
+<StatusBadge severity={row.forIntegration ? "danger" : "success"} value={row.forIntegration ? "SIM" : "NAO"} />
+```

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-crud/references/routing.md

@@ -0,0 +1,66 @@
+# Routing And Proxy Standard
+
+## Public URLs
+
+Always prefer `publicId` in URLs:
+
+- list action to edit:
+  - `/<module>/<entity>/<entity>_edit?publicId=<uuid>`
+- proxy detail route:
+  - `/api/<module>/<entity>/{publicId}`
+
+Do not expose the numeric database `id` in the route when a `publicId` exists.
+
+## Pages
+
+- `app/<module>/<entity>/page.tsx`: only `redirect("/<module>/<entity>/<entity>_list")`
+- `app/<module>/<entity>/<entity>_list/page.tsx`
+- `app/<module>/<entity>/<entity>_edit/page.tsx`
+
+## Next Route Convention
+
+Use Next API routes as server-side proxies:
+
+- `app/api/<module>/<entity>/route.ts` (`GET` list, `POST` create)
+- `app/api/<module>/<entity>/[id]/route.ts` (`GET`, `PUT`, `DELETE`; the `[id]` segment carries the
+  `publicId`)
+
+What they do:
+
+- forward the session to the backend through the project's session-aware fetch helper
+- keep the backend paths in one place (a `*Paths` helper in `lib/`), not scattered as strings
+- return the backend response untouched on writes (passthrough helper)
+- on reads, turn failures into `problem+json` with the **real status** (`problemResponse`); a session
+  that expired or a backend that is down must never become an empty `200` page
+
+```ts
+export async function GET(request: Request) {
+  const params = new URLSearchParams(new URL(request.url).searchParams);
+  const suffix = params.toString() ? `?${params.toString()}` : "";
+  try {
+    return NextResponse.json(await apiFetch<PaginatedResult<Entity>>(`${Paths.entity.base}${suffix}`));
+  } catch (error) {
+    return problemResponse(error);
+  }
+}
+```
+
+The client calls these routes with the project's HTTP client (`adminProxyClient` in the boilerplate)
+and reads errors with `extractApiErrorMessage`.
+
+## Backend Convention
+
+Resources behind a CRUD should:
+
+- return both `id` and `publicId` in payloads when useful
+- resolve detail/update/delete by `publicId`
+- keep numeric `id` only for internal persistence and joins
+- paginate server-side (`page` 0-based, `size`, `sortField`, `sortOrder`) and answer
+  `{ items, totalRecords, page, size, sortField, sortOrder, query }`
+
+## Breadcrumb And Menu
+
+- 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

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-new-screen/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: seedgrid-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.
+---
+
+# Tela nova no SeedGrid (menu + permissoes)
+
+Hoje menu e catalogo de permissoes sao mantidos **a mao, em varios lugares**. Esta skill existe para nenhum ser
+esquecido. (Plano futuro para centralizar: `seedgrid-quarkus-ext-security/docs/refactor-permission-catalog.md`.
+Nao executar sem o usuario pedir.)
+
+## Antes de comecar, responda
+
+1. **Qual app?** `frontend/` (cliente final, audience `client`) ou `admin/` (plataforma, audience `platform`).
+2. **Quais permissoes?** A de abrir a tela (`XXX_READ`) e uma por acao relevante (`XXX_CREATE`, `XXX_DELETE`...).
+   Uma tela pode ter varias.
+3. **Onde no menu?** Grupo (pai) e posicao. Ou "nao aparece no menu" (permissao sem tela).
+4. **So' no app do cliente: e' vendavel por plano?** Se o plano pode ligar/desligar a funcionalidade.
+
+## Passo a passo
+
+Detalhes e exemplos de codigo de cada passo em `references/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,
+   vinculo ao perfil `ADMIN`, e - se vendavel - vinculo aos terms dos planos que a liberam.
+2. **Endpoint (backend)** - `@PermissionsAllowed("XXX_READ")` (e por acao). Se vendavel:
+   `@RequiresPlanFeature("XXX_READ")`.
+3. **Menu** - item em `<app>/app/data.ts` (`navItems`) com `href`, `label` e `permission`.
+4. **Icone** - entrada no `iconByHref` de `<app>/app/components/Shell.tsx` (sem ela o item fica sem icone).
+5. **Item ativo** - se a tela tem sub-rotas (ex.: `_edit`), regra em `normalizeMenuPath` do mesmo `Shell.tsx`.
+6. **Editor de perfis** - a tela e as acoes no catalogo do app:
+   - cliente: `frontend/lib/client-permission-tree.ts`;
+   - admin: `admin/lib/permission-tree.ts`.
+   Permissao fora do catalogo **nao aparece** no editor de perfis do cliente (some em silencio).
+7. **Se vendavel (so' cliente)** - copiar a mesma entrada para `admin/lib/client-permission-tree.ts` (os dois
+   `client-permission-tree.ts` sao **identicos**). Se o grupo novo NAO for vendavel, incluir o id dele em
+   `NOT_SELLABLE_GROUPS` (`admin/app/plans/plan_terms/page.tsx`).
+8. **Na pagina** - botoes de acao checam a propria permissao (`hasPermission("XXX_DELETE")`). O catalogo so'
+   declara a acao para o editor de perfis; nao esconde botao.
+9. **Os dois boilerplates** - `login-tenancy` e `subdomain-tenancy` tem os mesmos arquivos. Se a tela e' do
+   boilerplate (nao de um produto derivado), repetir nos dois.
+
+## Verificacao
+
+Rodar o checklist de `references/checklist.md` antes de encerrar. No minimo:
+
+```bash
+# os dois catalogos do cliente iguais (ignorando fim de linha)
+diff <(tr -d '\r' < frontend/lib/client-permission-tree.ts) <(tr -d '\r' < admin/lib/client-permission-tree.ts)
+# typecheck dos dois apps
+(cd frontend && npx tsc --noEmit -p .) && (cd admin && npx tsc --noEmit -p .)
+```
+
+E na tela: o item aparece no menu para quem tem a permissao e some para quem nao tem; o editor de perfis mostra
+a tela com as acoes; se vendavel, o treeview "features liberadas neste plano" mostra a tela.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-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 $seedgrid-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/seedgrid-new-screen/references/checklist.md

@@ -0,0 +1,32 @@
+# Checklist - tela nova
+
+## Backend
+
+- [ ] Migration NOVA (nao editar uma aplicada) com as permissoes, `audience` certo (`client` | `platform`), nome
+      com ate 30 caracteres.
+- [ ] Permissoes vinculadas ao perfil `ADMIN`.
+- [ ] Endpoints com `@PermissionsAllowed` por acao.
+- [ ] Vendavel: `@RequiresPlanFeature` no endpoint + vinculo aos terms (trial e planos) na migration.
+
+## Front (`frontend/` ou `admin/`)
+
+- [ ] Item em `app/data.ts` com `permission`.
+- [ ] Icone em `iconByHref` (`app/components/Shell.tsx`).
+- [ ] Sub-rotas em `normalizeMenuPath` (mesmo arquivo), se houver.
+- [ ] Tela e acoes no catalogo: `frontend/lib/client-permission-tree.ts` ou `admin/lib/permission-tree.ts`.
+- [ ] Botoes da pagina checam a propria permissao.
+- [ ] Vendavel: `admin/lib/client-permission-tree.ts` identico ao do frontend; grupo nao vendavel em
+      `NOT_SELLABLE_GROUPS`.
+
+## Boilerplates
+
+- [ ] Repetido em `login-tenancy` e `subdomain-tenancy` (se a tela for do boilerplate).
+
+## Verificacao
+
+- [ ] `diff` dos dois `client-permission-tree.ts` vazio (ignorando `\r`).
+- [ ] `npx tsc --noEmit -p .` no `frontend/` e no `admin/`.
+- [ ] Banco recriado (ou migration aplicada) e backend reiniciado.
+- [ ] Usuario COM a permissao ve o item; usuario SEM nao ve.
+- [ ] Editor de perfis mostra a tela e as acoes; o "olhinho" da lista de perfis lista as permissoes da tela.
+- [ ] Vendavel: o treeview do plano mostra a tela; plano sem a feature -> 402 `FEATURE_NOT_IN_PLAN`.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-new-screen/references/steps.md

@@ -0,0 +1,114 @@
+# Passos detalhados
+
+Exemplo usado em todos os passos: tela **Relatorios** no app do cliente, com abrir, gerar e excluir, vendavel
+por plano.
+
+## 1. Permissao (migration)
+
+`backend/src/main/resources/db/migration/app/V3010__reports_permissions.sql`:
+
+```sql
+-- Audience: 'client' = app do cliente (frontend/); 'platform' = admin da plataforma (admin/).
+insert into permissions (name, description, public_id, audience) values
+    ('REPORT_READ',     'Relatorios',         gen_random_uuid()::text, 'client'),
+    ('REPORT_GENERATE', 'Gerar relatorio',    gen_random_uuid()::text, 'client'),
+    ('REPORT_DELETE',   'Excluir relatorio',  gen_random_uuid()::text, 'client')
+on conflict (name) do update
+set description = excluded.description,
+    audience    = excluded.audience;
+
+-- O ADMIN tem todas as permissoes (o responsavel pela conta entra com ADMIN no cadastro).
+insert into role_permissions (role_id, permission_id)
+select r.id, p.id from roles r cross join permissions p
+where r.name = 'ADMIN' and p.name in ('REPORT_READ', 'REPORT_GENERATE', 'REPORT_DELETE')
+on conflict do nothing;
+
+-- SO' SE VENDAVEL: os planos que liberam a feature (o trial tem public_id fixo ...0000a2).
+-- Sem billing (modulo desligado) as tabelas de plano nao existem: o bloco so' pula.
+do $$
+begin
+    if to_regclass('plan_term_permissions') is null then
+        return;
+    end if;
+    insert into plan_term_permissions (plan_term_id, permission_id)
+    select t.id, p.id
+    from plan_terms t join plans pl on pl.id = t.plan_id cross join permissions p
+    where p.name = 'REPORT_READ'
+      and (t.public_id = '00000000-0000-0000-0000-0000000000a2' or pl.code in ('PRO'))
+    on conflict do nothing;
+end $$;
+```
+
+- `name` tem no maximo 30 caracteres.
+- No subdomain-tenancy as migrations de `db/migration/app` rodam no banco **master**.
+- Referencia viva: `V3002__usage_demo_permission.sql`.
+
+## 2. Endpoint
+
+```java
+@POST
+@Path("/reports")
+@PermissionsAllowed("REPORT_GENERATE")
+@RequiresPlanFeature("REPORT_READ")         // so' se vendavel: 402 FEATURE_NOT_IN_PLAN quando o plano nao libera
+public Report generate(...) { ... }
+```
+
+## 3. Menu (`<app>/app/data.ts`)
+
+```ts
+{ href: "/reports/report_list", label: "Relatorios", permission: "REPORT_READ" },
+```
+
+- Grupo = item com `children`; aparece se tiver ao menos um filho visivel.
+- Regra implicita do `Shell`: folha **sem** `permission` aparece **so' para ADMIN**. Prefira sempre declarar a
+  permissao.
+
+## 4. Icone (`<app>/app/components/Shell.tsx`)
+
+```ts
+const iconByHref = {
+  ...
+  "/reports/report_list": <FileText size={16} />,   // import { FileText } from "lucide-react"
+} as const;
+```
+
+## 5. Item ativo nas sub-rotas (`normalizeMenuPath`, mesmo arquivo)
+
+```ts
+if (pathname.startsWith("/reports/")) {
+  return "/reports/report_list";
+}
+```
+
+## 6. Editor de perfis
+
+Cliente - `frontend/lib/client-permission-tree.ts` (admin: `admin/lib/permission-tree.ts`, mesmo formato):
+
+```ts
+{
+  id: "relatorios",                       // id do grupo (usado em NOT_SELLABLE_GROUPS)
+  label: "Relatorios",
+  screens: [
+    {
+      id: "relatorios/relatorios",
+      label: "Relatorios",
+      actions: [
+        { permission: "REPORT_READ", label: "Abrir a tela" },      // a PRIMEIRA e' sempre a de abrir
+        { permission: "REPORT_GENERATE", label: "Gerar relatorio" },
+        { permission: "REPORT_DELETE", label: "Excluir relatorio" },
+      ],
+    },
+  ],
+},
+```
+
+- A ordem dos grupos segue o menu.
+- Cada permissao aparece **uma vez** no catalogo (a arvore usa o publicId como id da folha).
+
+## 7. Vendavel (so' cliente)
+
+- Copiar o arquivo inteiro: `frontend/lib/client-permission-tree.ts` -> `admin/lib/client-permission-tree.ts`.
+- O treeview "features liberadas neste plano" mostra todos os grupos do catalogo **menos** os de
+  `NOT_SELLABLE_GROUPS` (`admin/app/plans/plan_terms/page.tsx`): hoje `seguranca`, `menu-usuario`.
+  Grupo novo nao vendavel -> acrescentar o id ali.
+- Sem o `@RequiresPlanFeature` no endpoint, liberar ou nao no plano nao muda nada.

package/seedgridKB/SeedGrid/Toolkit/skills/seedgrid-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: seedgrid-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
+---
+
+# Revisar o padrão SeedGrid
+
+Confere o código contra as regras do toolkit e devolve uma lista objetiva de violações. **Somente leitura**: não edite arquivos, a menos que o usuário peça as correções depois.
+
+## Escopo
+
+- `front`: revisa só o front-end (regras `FE-nn`, arquivo `.ai/rules/frontend-seedgrid.md`).
+- `back`: revisa só o back-end Java (regras `BE-nn`, arquivo `.ai/rules/backend-java-seedgrid.md`).
+- Sem argumento: revisa os dois. Se o projeto só tiver um lado (sem `pom.xml`/`*.java` ou sem `package.json`/`*.tsx`), diga isso e revise apenas o que existe.
+
+Alvo: por padrão, os arquivos alterados (`git diff --name-only <base>...HEAD` mais os não commitados). Se o usuário pedir "o projeto inteiro" ou não houver diff, varra `src/` (back) e `app/`, `components/` (front).
+
+## Passos
+
+1. Leia **apenas** a rule do escopo (`.ai/rules/frontend-seedgrid.md` e/ou `.ai/rules/backend-java-seedgrid.md`). Para dúvida sobre um componente ou extension, abra pelo índice da KB (`.ai/brain/SeedGrid/SeedGrid-components/Indice.md`, `.ai/brain/SeedGrid/Extensions/Indice.md`) e só a nota do grupo; nunca varra `.ai/brain/` inteira.
+2. Faça primeiro as buscas mecânicas, sem abrir arquivo por arquivo. Exemplos:
+   - Front: `<input`, `<button`, `<select`, `<textarea`, `<table` em `*.tsx`; `window.confirm`, `alert(`; `SgInputText` em campo cujo nome/label indique telefone, whatsapp, cpf, cnpj, e-mail, cep, senha, valor, data (FE-10 a FE-19).
+   - Back: `@Inject` em atributo; `throw new RuntimeException`; `Resource` no nome de classe; `UPDATE ` em JPQL/SQL de código; Panache em módulo de lib; endpoint que devolve `id` em vez de `publicId`; `"%" +` em `LIKE`; pacote no singular.
+3. Abra só os arquivos com suspeita e confirme no contexto. Descarte falsos positivos (por exemplo, `<input>` dentro do próprio pacote de componentes, ou comentário que justifica a exceção da FE-01).
+4. Para regras que exigem julgamento (FE-02, BE-05, BE-11, BE-40), reporte só o que você consegue sustentar com o trecho de código. Diga o que **não** conseguiu verificar.
+
+## Saída
+
+```markdown
+## Padrão SeedGrid: <front|back|front e back>
+Escopo revisado: <arquivos ou pastas>
+
+### Violações
+| Regra | Local | Problema | Correção |
+| --- | --- | --- | --- |
+| FE-10 | app/clientes/cliente_edit/page.tsx:84 | telefone com SgInputText | trocar por SgInputPhone |
+
+### Não verificado
+- itens que dependem de execução ou de contexto que você não tinha
+
+### Resumo
+N violações (X bloqueantes). Conformes: <regras checadas sem achados>.
+```
+
+Classifique como **bloqueante** o que afeta segurança ou contrato (BE-10, BE-25, BE-30, FE-32) e como **ajuste** o resto. Sem violações, diga isso e liste o que foi checado, sem inventar achados.
+
+## Bloco final para automação
+
+O `seedgrid-ai review` lê o resultado desta skill. Por isso, **termine sempre a resposta** com exatamente um bloco assim (JSON válido, sem comentários), depois do relatório:
+
+````markdown
+```seedgrid-review-json
+{"scope": "front", "violations": 1, "blocking": 0, "notVerified": 0}
+```
+````
+
+- `scope`: `front`, `back` ou `both`.
+- `violations`: total de violações do relatório; `blocking`: quantas são bloqueantes.
+- `notVerified`: quantos itens ficaram em "Não verificado".

package/seedgridKB/SeedGrid/Toolkit/skills/validar-mudanca/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: validar-mudanca
+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
+---
+
+# Validar mudança
+
+Comprove com evidências executadas que a mudança funciona; não declare sucesso sem verificar.
+
+## Passos
+
+1. **Critérios.** Liste os critérios de aceite. Se não existirem, derive-os do objetivo e informe isso.
+2. **Comandos do projeto.** Descubra como compilar, testar e executar: consulte `.ai/local/` (se existir), README, scripts de build (`package.json`, `pom.xml`, `build.gradle`, `Makefile` etc.). Não invente comandos.
+3. **Mapeamento.** Associe cada critério a uma verificação concreta (teste automatizado, comando, inspeção do comportamento).
+4. **Execução.** Rode, nesta ordem quando aplicável: verificação de tipos/compilação, lint, testes afetados, suíte relevante, build. Exercite o comportamento alterado quando possível.
+5. **Registro.** Preencha o modelo [assets/relatorio-validacao.md](assets/relatorio-validacao.md) com comandos, resultados e evidências resumidas.
+
+## Regras
+
+- Diferencie "passou", "falhou" e "não executado (motivo)". Nunca converta um "não executado" em "passou".
+- Não execute ações que publiquem ou alterem serviços externos (deploy, envio de e-mail, pagamentos, push) sem autorização explícita.
+- Se uma verificação falhar, devolva a evidência ao implementador em vez de corrigir por conta própria, salvo instrução contrária.
+- Testes instáveis: repita uma vez e relate a instabilidade, sem ocultá-la.
+
+## Saída
+
+O relatório de validação preenchido, com conclusão "Aprovado", "Reprovado" ou "Aprovado com ressalvas".

package/seedgridKB/SeedGrid/Toolkit/templates/decisao-arquitetura.md

@@ -0,0 +1,29 @@
+---
+description: "Modelo de registro de decisão de arquitetura (ADR): contexto, alternativas, decisão e consequências."
+---
+# Decisão de arquitetura: <título>
+
+> Modelo do SeedGrid AI Toolkit. Copie para o local de documentação do projeto antes de preencher; não edite o modelo.
+
+- **Status:** proposta | aceita | substituída por <link>
+- **Data:** AAAA-MM-DD
+- **Responsáveis:** <pessoas ou papéis>
+
+## Contexto
+Problema, forças em jogo e restrições.
+
+## Decisão
+O que foi decidido, em termos objetivos.
+
+## Alternativas consideradas
+| Alternativa | Prós | Contras | Motivo da rejeição |
+| --- | --- | --- | --- |
+| | | | |
+
+## Consequências
+- Positivas:
+- Negativas e riscos:
+- Trabalho decorrente:
+
+## Validação
+Como saberemos que a decisão funcionou (métricas, testes, critérios).

package/seedgridKB/SeedGrid/Toolkit/templates/especificacao-tarefa.md

@@ -0,0 +1,32 @@
+---
+description: "Modelo de especificação de tarefa: objetivo, escopo, critérios de aceite e riscos, para planejar antes de implementar."
+---
+# Especificação de tarefa: <título curto>
+
+> Modelo do SeedGrid AI Toolkit. Copie para o local de documentação do projeto antes de preencher; não edite o modelo.
+
+## Objetivo
+O que deve estar verdadeiro quando a tarefa terminar.
+
+## Contexto
+Por que a mudança é necessária; decisões e entregas anteriores relevantes.
+
+## Papel responsável
+`<id do papel>` (ver catálogo de papéis).
+
+## Arquivos e áreas envolvidos
+- caminho/ou/módulo — motivo
+
+## Limites
+- O que não deve ser alterado.
+- Arquivos que outro papel está alterando em paralelo.
+
+## Critérios de aceite
+- [ ] Critério verificável 1
+- [ ] Critério verificável 2
+
+## Verificações esperadas
+Comandos ou inspeções que comprovam os critérios.
+
+## Resultado esperado
+Entrega no formato padrão (resultado, arquivos alterados, verificações, pendências, contexto para a próxima etapa).

package/seedgridKB/SeedGrid/Toolkit/templates/relatorio-validacao.md

@@ -0,0 +1,30 @@
+---
+description: "Modelo de relatório de validação: o que foi verificado, como, resultado e pendências."
+---
+# Relatório de validação: <tarefa>
+
+> Modelo do SeedGrid AI Toolkit. Copie para o local de documentação do projeto antes de preencher; não edite o modelo.
+
+- **Data:** AAAA-MM-DD
+- **Versão/commit avaliado:** <identificador>
+- **Ambiente:** <SO, runtime, banco etc.>
+
+## Critérios de aceite
+| Critério | Verificação | Resultado | Evidência |
+| --- | --- | --- | --- |
+| | comando ou inspeção | passou / falhou / não executado | saída resumida ou caminho do log |
+
+## Comandos executados
+```text
+<comando>
+<resultado resumido>
+```
+
+## Regressões verificadas
+- Área — como foi verificada — resultado
+
+## Não verificado
+- Item — motivo
+
+## Conclusão
+Aprovado | Reprovado | Aprovado com ressalvas — justificativa em uma frase.