@luanpdd/kit-mcp 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -6,6 +6,107 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-05-06
+
+Patch de integração da Suíte Supabase v1.8.0 — fecha 7 lacunas onde o conteúdo novo não estava "wired" nos pontos de entrada existentes do framework.
+
+### Mudado — integração entre Suíte Supabase e fluxo padrão
+
+- **`/fazer`** (`kit/commands/fazer.md`) — adicionada linha "Tarefa Supabase → `/supabase`" na decision tree + parágrafo "Detecção de intenção Supabase" listando 7 categorias de termos (DB / Auth / Realtime / Edge / Storage / RAG / Background) que devem rotear para `/supabase` em vez de `/discutir-fase` ou `/expresso`.
+- **`planner` agent** (`kit/agents/planner.md`) — nova seção `<specialized_agents>` instrui o planner a delegar para `supabase-*` agents (architect, migration-writer, rls-writer, edge-fn-writer, realtime-implementer, auth-bootstrapper, storage-implementer) em fases Supabase em vez de gerar tasks genéricas para o `executor` resolver inline.
+- **`executor` agent** (`kit/agents/executor.md`) — nova tabela "Delegação para agents especializados" lista 8 patterns de task (migrations, schemas declarative, RLS, Edge Functions, Realtime, Auth bootstrap, Storage, schema-checker) com `Task(subagent_type=...)` correto. Princípio: agent especializado é mais barato + mais correto que o executor genérico em domínios cobertos.
+- **`/depurar`** (`kit/commands/depurar.md`) — `<available_agent_types>` agora inclui `schema-checker`. Nova seção `<supabase_pre_check>` faz triagem de bugs SQL/Supabase e pré-valida via `schema-checker` antes do `debugger` genérico (5 sintomas mapeados: migration falhou, RLS quebrou query, Edge Function quebrou, user_metadata em policy, service_role exposto).
+- **`discuss-phase` workflow** (`kit/framework/workflows/discuss-phase.md`) — nova seção `<supabase_detection>` antes da identificação de áreas cinzentas. Se a fase é Supabase, delega o questionamento para `supabase-architect` (que já tem template de perguntas Supabase-específicas) em vez de gerar gray areas genéricas.
+- **`plan-phase` workflow** (`kit/framework/workflows/plan-phase.md`) — `<available_agent_types>` agora inclui agents Supabase. Nova seção `<supabase_phase_detection>` no Step 1 — se fase é Supabase, usa `supabase-architect` em vez de `phase-researcher` genérico, e instrui o `planner` a marcar tasks com `subagent_type` apontando para o agent especializado correto (tabela com 7 patterns).
+- **CI** (`.github/workflows/ci.yml`) — novo step "Audit — v1.8 Supabase suite gates" que executa os 4 gates blocking (`budget-description`, `no-personal-uuid`, `agent-no-recursive-dispatch`, `skill-must-include`) extraindo o bash check de cada `gates/<name>.md` e rodando. Falha o CI se algum violar. Gate non-blocking `sync-idempotent` defer (exige CLI completo).
+
+### Adicionado — agentes existentes ganham awareness Supabase
+
+Sem novos arquivos. As 6 edições em arquivos de agent/workflow/command existentes integram o conteúdo da v1.8.0 nos pontos de entrada que LLMs usam, fechando o gap "conteúdo entregue mas não chamado".
+
+### Sem mudanças de API runtime
+
+Patch v1.8.1 continua content-only. Zero alterações em `src/core/`, `registry.js`, `sync.js`. Stable API v1.0+ preservada.
+
+### Tests
+
+Todos os 4 gates blocking continuam passing após o patch. CI agora os roda explicitamente — Phase 28 deixou os specs prontos mas sem step de execução.
+
+## [1.8.0] - 2026-05-06
+
+Milestone v1.8 — Suíte Supabase: primeira coleção especializada de skills+agents+command focada em um stack concreto. 31 REQs em 4 fases (Phases 25-28).
+
+### Adicionado — 11 skills Supabase canônicas (Phase 25)
+
+Cada skill é auto-contida (sem `references/` folder), com frontmatter `description ≤ 200 chars`, template fixo de 5 seções (Quando usar / Regras absolutas / Patterns canônicos / Anti-patterns / Ver também), code blocks EN com comentários PT-BR pedagógicos, e cross-refs via Markdown link relativo.
+
+- `supabase-realtime` — broadcast vs postgres_changes, `private: true` obrigatório, naming `scope:entity:id`, `realtime.broadcast_changes` triggers, `removeChannel` cleanup
+- `supabase-auth-ssr` — Next.js v16 + `@supabase/ssr` (NUNCA `auth-helpers-nextjs`), padrão `getAll`/`setAll` exclusivo, middleware com `getUser()` + redirects, single serverClient factory
+- `supabase-edge-functions` — Deno runtime, imports `npm:`/`jsr:` versionados, env vars pre-populadas, `Deno.serve`, `EdgeRuntime.waitUntil`, file writes apenas em `/tmp`, basePath `/<function-name>`
+- `supabase-declarative-schema` — workflow `supabase/schemas/` → `supabase stop` → `db diff -f` → revisar → apply, com caveats sobre views, RLS, partitions
+- `supabase-rls-policies` — REGRA #1 absoluta `(select auth.uid())` wrapper, WARNING `user_metadata` em autorização (privilege escalation), policies granulares por operação, `to authenticated`/`to anon` explícito, indexes obrigatórios, MFA via `aal2`
+- `supabase-database-functions` — `SECURITY INVOKER` por default, `set search_path = ''` SEMPRE (lint advisor 0011), schema-qualified names, `IMMUTABLE`/`STABLE` quando aplicável
+- `supabase-migrations` — naming `YYYYMMDDHHmmss_<name>.sql` UTC, header de metadados, RLS obrigatório em toda nova tabela, granular policies, comentários extensivos em comandos destrutivos
+- `supabase-postgres-style` — lowercase reserved, `snake_case`, plurais para tabelas/singular para colunas, `ISO 8601`, CTEs lineares para queries complexas
+- `supabase-storage` — buckets públicos vs privados, `signed URL` com expiration, RLS sobre `storage.objects` com multi-tenant path isolation, image transforms (Pro+), TUS para uploads > 6 MB, awareness de egress billing
+- `supabase-pgvector-rag` — `create extension vector`, dim consistente por modelo, `HNSW` (default 2026) vs `IVFFlat`, operadores `<=>`/`<#>`/`<->`, RAG with permissions via RLS, chunking 200-500 tokens
+- `supabase-cron-queues` — `pg_cron` + `pgmq` (Postgres 15.6.1.143+) + `pg_net` v0.10.0+, pattern canônico `cron → pgmq → Edge Function`, idempotência obrigatória em consumers
+
+Plus glossário compartilhado em `kit/skills/_shared-supabase/glossary.md` — termos PT-BR↔EN, comandos CLI canônicos, patterns canônicos consolidados (não-skill, arquivo de referência).
+
+### Adicionado — 7 agents Supabase + convenção universal (Phase 26)
+
+Cada agent inclui tabela `## Compatibilidade` por IDE (Full / Partial / Offline-only), preflight detection MCP no Step 0 (declara MODO OFFLINE explícito se MCP indisponível — NUNCA finge sucesso), output em layout canônico do CLI Supabase (`supabase/migrations/`, `supabase/schemas/`, `supabase/functions/<name>/`), e frontmatter `tools:` com nomes canônicos `mcp__supabase__*` (zero UUIDs).
+
+- `supabase-architect` (blue) — projeta schema + RLS + topologia realtime ANTES da implementação. Pergunta tier (Free/Pro/Team/Enterprise) upfront via `AskUserQuestion`. Alerta sobre Free pause + branch billing. NÃO escreve código.
+- `supabase-migration-writer` (yellow) — escreve migrations seguindo declarative schema + RLS obrigatório + style guide. Detecta layout `schemas/` vs `migrations/` no boot. Aplica via `mcp__supabase__apply_migration` se MCP disponível; modo offline gera SQL.
+- `supabase-rls-writer` (red) — gera 4 policies granulares por operação com `(select auth.uid())` wrapper + indexes recomendados. **ABORTA explicitamente** se input menciona `user_metadata` em policy de autorização.
+- `supabase-edge-fn-writer` (cyan) — escreve Edge Functions Deno com `npm:`/`jsr:` versionados, `Deno.serve`, env vars pre-populadas, file writes em `/tmp`, basePath em multi-rota. Alerta cold start em bundles grandes.
+- `supabase-realtime-implementer` (magenta) — configura 3 layers (RLS sobre `realtime.messages` + trigger DB via `realtime.broadcast_changes` + client subscribe com cleanup obrigatório). Migra `postgres_changes` para `broadcast`.
+- `supabase-auth-bootstrapper` (green) — bootstrap Next.js v16 com `@supabase/ssr` (browser client + server client + middleware completo). **Audita `.env*` files** e ABORTA se detectar `NEXT_PUBLIC_*SERVICE*` (service_role leak).
+- `supabase-storage-implementer` (orange) — configura bucket + RLS sobre `storage.objects` com multi-tenant path (`<auth.uid()>/<file>`) + client code (upload + signedURL). Suporta TUS para uploads grandes.
+
+### Adicionado — Command `/supabase` orquestrador único (Phase 27)
+
+`kit/commands/supabase.md` aceita 10 subcomandos com sinônimos PT-BR/EN: `arquiteto|architect`, `migration|migrar`, `rls`, `edge|edge-function|funcao`, `realtime|tempo-real`, `auth|autenticacao`, `storage|armazenamento`, `rag|pgvector|embeddings`, `cron|queues|pgmq|background`, `check|validar` (invoca `schema-checker` existente), `help|ajuda|?`.
+
+Detecta `supabase/config.toml` para extrair `project_id`. Dispatch via `Task(subagent_type=supabase-...)`. **É o único ponto de chain de agents Supabase** — agents permanecem função pura (anti-pitfall A10).
+
+### Adicionado — 5 audit gates novos (Phase 28)
+
+Markdown specs em `gates/` com `## Check` em bash:
+
+- `gates/budget-description.md` — valida `description ≤ 200 chars` em todo agent/command/skill (anti-pitfall A2 — CLAUDE.md inflation)
+- `gates/no-personal-uuid.md` — detecta UUIDs `[0-9a-f]{8}-...` em frontmatter ou body de `kit/{agents,commands,skills}/` (anti-pitfall A12)
+- `gates/agent-no-recursive-dispatch.md` — valida zero `Task(...subagent_type=...supabase-...)` em `kit/agents/supabase-*.md` (anti-pitfall A10)
+- `gates/skill-must-include.md` — valida strings obrigatórias por skill verbatim — `(select auth.uid())`, `set search_path = ''`, `getAll`/`setAll`, `private: true`, `Deno.serve`, etc. (anti-pitfall A7)
+- `gates/sync-idempotent.md` — valida que `kit sync claude-code` rodado 2× produz `.claude/` byte-idêntico (anti-pitfall A1, non-blocking warn)
+
+### Mudado — schema-checker.md UUID migration
+
+`kit/agents/schema-checker.md` migrado de `mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__execute_sql` (UUID do projeto pessoal do mantenedor) para `mcp__supabase__execute_sql`/`__list_tables`/`__apply_migration` (canônico). **Breaking interno:** instaladores de versões anteriores tinham um UUID que não funcionava para eles; com v1.8 funciona com qualquer Supabase MCP server configurado. Mesma funcionalidade — apenas referência canônica.
+
+### Sem mudanças de API runtime
+
+v1.8 é **content-only por design** — zero alterações em `src/core/`, `registry.js`, `sync.js`. Stable API v1.0+ totalmente preservada. CI passa sem mudança em `.github/workflows/`. Deps budget mantido em 6/6 (zero deps novas — todo o conteúdo é markdown).
+
+### Tests
+
+Tests existentes (115 unit + 67 integration de v1.7) continuam verde. Novos gates não têm tests dedicados (são bash em markdown, executados via `runGate` no framework de gates já testado em `test/unit/gates.test.js`).
+
+### Decisões arquiteturais
+
+Validadas em `.planning/research/`:
+- **Naming flat** `kit/skills/supabase-*/SKILL.md` (não subárvore — quebraria `readSkillsDir`)
+- **MCP-first com fallback offline gracioso** — 5 dos 8 IDE targets não têm Supabase MCP; agents funcionam offline gerando SQL/código
+- **Cross-references via Markdown link relativo** (não `@-include` — quebraria lazy-load das skills)
+- **Outputs em layouts canônicos do CLI Supabase** — `supabase/migrations/`, `supabase/schemas/`, `supabase/functions/<name>/`
+- **Glossário compartilhado** em `_shared-supabase/` — não é skill (sem trigger), apenas referência cross-skill
+
+### Detalhes
+
+`.planning/milestones/v1.8.0/` (após `/concluir-marco`).
+
 ## [1.7.0] - 2026-05-06
 
 Milestone v1.7 — perf+lean part 2 + UX naming canonical: 10 REQs em 3 fases.

package/gates/agent-no-recursive-dispatch.md

@@ -0,0 +1,48 @@
+---
+id: agent-no-recursive-dispatch
+stage: pre-verify
+blocking: true
+description: Valida que agents Supabase NÃO contêm Task(subagent_type=supabase-...). Orquestração só via /supabase command (anti-pitfall A10 — recursive dispatch).
+---
+
+# Agent no recursive dispatch gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: agents Supabase não devem invocar outros agents Supabase via Task()
+# Orquestração centralizada no command /supabase (anti-pitfall A10)
+set -e
+
+VIOLATIONS=0
+
+for f in kit/agents/supabase-*.md; do
+  [ -f "$f" ] || continue
+  # PT-BR: busca por Task(...subagent_type=...supabase-... ou Task(... 'supabase-...
+  if grep -nE 'Task\([^)]*subagent_type[^)]*supabase-' "$f"; then
+    echo "FAIL: $f — agent Supabase invocando outro agent Supabase via Task()"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  echo "Agents Supabase devem ser função pura. Orquestração apenas via /supabase command."
+  exit 1
+fi
+
+echo "✓ Zero recursive dispatch entre agents Supabase"
+exit 0
+```
+
+## Verdict
+
+- **passed** — zero `Task(subagent_type=supabase-...)` em `kit/agents/supabase-*.md`
+- **block** — recursive dispatch detectado
+
+## Notes
+
+Anti-pitfall A10 da v1.8: tentação de `supabase-architect` invocar `supabase-migration-writer` que re-invoca architect → stack overflow lógico + custo LLM multiplicado. Solução: agents permanecem função pura; chain via `/supabase` command (Phase 27 — único orquestrador autorizado).

package/gates/budget-description.md

@@ -0,0 +1,68 @@
+---
+id: budget-description
+stage: pre-verify
+blocking: true
+description: Valida que cada agent/command/skill tem `description:` ≤ 200 chars no frontmatter (anti-pitfall A2 — CLAUDE.md inflation).
+---
+
+# Budget description gate
+
+**When to run:** pre-verify, antes de commit final do milestone.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: itera por todos os agent/command/skill, valida frontmatter description ≤ 200 chars
+set -e
+
+VIOLATIONS=0
+
+# function que extrai description do YAML frontmatter
+check_description() {
+  local file="$1"
+  local desc
+  desc=$(awk '/^description:/{sub(/^description: ?/, ""); print; exit}' "$file" 2>/dev/null || true)
+  if [ -z "$desc" ]; then
+    echo "WARN: $file — sem description: no frontmatter"
+    return 0
+  fi
+  local len=${#desc}
+  if [ "$len" -gt 200 ]; then
+    echo "FAIL: $file — description tem $len chars (max 200)"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+}
+
+# itera agents
+for f in kit/agents/*.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+# itera commands
+for f in kit/commands/*.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+# itera skills (SKILL.md em subdirs)
+for f in kit/skills/*/SKILL.md; do
+  [ -f "$f" ] && check_description "$f"
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS (max description length 200 chars)"
+  exit 1
+fi
+
+echo "✓ Todos os agents/commands/skills têm description ≤ 200 chars"
+exit 0
+```
+
+## Verdict
+
+- **passed** — todas as descriptions ≤ 200 chars
+- **block** — pelo menos uma description > 200 chars (CLAUDE.md inflation)
+
+## Notes
+
+Anti-pitfall A2 da v1.8: cluster `supabase-*` adiciona 19+ entradas em CLAUDE.md. Sem este budget, descriptions verbosas inflam CLAUDE.md em ~3-4 KB+ — desfaz otimização de v1.6/v1.7.

package/gates/no-personal-uuid.md

@@ -0,0 +1,72 @@
+---
+id: no-personal-uuid
+stage: pre-verify
+blocking: true
+description: Detecta UUIDs no formato [0-9a-f]{8}-[0-9a-f]{4}-... em frontmatter `tools:` ou body de skills/agents/commands. UUID pessoal quebra para outros instaladores (anti-pitfall A12).
+---
+
+# No personal UUID gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: detecta UUID em formato [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
+# em frontmatter tools: ou body de kit/{agents,commands,skills}/
+set -e
+
+# allowlist: glossário menciona patterns mas não usa UUID em tools
+ALLOWLIST_FILES=(
+  "kit/skills/_shared-supabase/glossary.md"
+)
+
+VIOLATIONS=0
+
+is_allowlisted() {
+  local file="$1"
+  for af in "${ALLOWLIST_FILES[@]}"; do
+    [ "$file" = "$af" ] && return 0
+  done
+  return 1
+}
+
+check_uuid() {
+  local file="$1"
+  is_allowlisted "$file" && return 0
+
+  # PT-BR: extrair frontmatter (entre --- ... ---)
+  local frontmatter
+  frontmatter=$(awk '/^---$/{i++; next} i==1' "$file" 2>/dev/null || true)
+
+  # PT-BR: buscar UUID em frontmatter (linhas com tools: ou abaixo)
+  if echo "$frontmatter" | grep -qE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'; then
+    echo "FAIL (frontmatter): $file"
+    grep -nE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' "$file" | head -3
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+}
+
+for f in kit/agents/*.md; do [ -f "$f" ] && check_uuid "$f"; done
+for f in kit/commands/*.md; do [ -f "$f" ] && check_uuid "$f"; done
+for f in kit/skills/*/SKILL.md; do [ -f "$f" ] && check_uuid "$f"; done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  echo "UUIDs pessoais quebram para outros instaladores. Use mcp__supabase__* canônico."
+  exit 1
+fi
+
+echo "✓ Zero UUIDs pessoais em kit/{agents,commands,skills}/"
+exit 0
+```
+
+## Verdict
+
+- **passed** — zero UUIDs em frontmatter ou body
+- **block** — pelo menos um UUID pessoal detectado (quebra para outros users)
+
+## Notes
+
+Anti-pitfall A12 da v1.8: `schema-checker.md` originalmente usava `mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__execute_sql` (UUID do projeto pessoal do user). Distribuído via `@luanpdd/kit-mcp`, isso quebra para qualquer outro instalador. Phase 28 migra para `mcp__supabase__*` canônico. Este gate previne regressão.

package/gates/skill-must-include.md

@@ -0,0 +1,69 @@
+---
+id: skill-must-include
+stage: pre-verify
+blocking: true
+description: Valida que skills supabase-* contêm strings obrigatórias verbatim — anti-pattern prevention (RLS (select), search_path, getAll/setAll, etc.).
+---
+
+# Skill must-include gate
+
+**When to run:** pre-verify.
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: cada skill deve incluir strings obrigatórias verbatim para prevenir anti-patterns
+set -e
+
+VIOLATIONS=0
+
+# PT-BR: mapeamento skill → must-include strings (delimitadas por |)
+declare -A MUST_INCLUDE
+MUST_INCLUDE["supabase-rls-policies"]="(select auth.uid())|user_metadata|TO authenticated"
+MUST_INCLUDE["supabase-database-functions"]="set search_path = ''|SECURITY INVOKER"
+MUST_INCLUDE["supabase-auth-ssr"]="getAll|setAll|auth-helpers-nextjs|@supabase/ssr"
+MUST_INCLUDE["supabase-realtime"]="broadcast|private: true|realtime.broadcast_changes|removeChannel"
+MUST_INCLUDE["supabase-edge-functions"]="npm:|jsr:|Deno.serve|EdgeRuntime.waitUntil|/tmp"
+MUST_INCLUDE["supabase-declarative-schema"]="supabase/schemas/|supabase stop|supabase db diff -f"
+MUST_INCLUDE["supabase-migrations"]="YYYYMMDDHHmmss|RLS|granular"
+MUST_INCLUDE["supabase-postgres-style"]="snake_case|ISO 8601|lowercase"
+MUST_INCLUDE["supabase-storage"]="signed URL|storage.objects|multi-tenant"
+MUST_INCLUDE["supabase-pgvector-rag"]="HNSW|IVFFlat|<=>|RAG with permissions"
+MUST_INCLUDE["supabase-cron-queues"]="pg_cron|pgmq|pg_net"
+
+for skill in "${!MUST_INCLUDE[@]}"; do
+  file="kit/skills/$skill/SKILL.md"
+  if [ ! -f "$file" ]; then
+    echo "FAIL: $file — skill ausente"
+    VIOLATIONS=$((VIOLATIONS + 1))
+    continue
+  fi
+
+  # PT-BR: testa cada string (separada por |)
+  IFS='|' read -ra REQUIRED <<< "${MUST_INCLUDE[$skill]}"
+  for str in "${REQUIRED[@]}"; do
+    if ! grep -qF "$str" "$file"; then
+      echo "FAIL: $file — must-include ausente: '$str'"
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done
+done
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "Total violations: $VIOLATIONS"
+  exit 1
+fi
+
+echo "✓ Todas as skills supabase-* contêm must-include strings"
+exit 0
+```
+
+## Verdict
+
+- **passed** — todas as 11 skills têm strings obrigatórias
+- **block** — pelo menos uma skill faltando string crítica (anti-pattern prevention quebrada)
+
+## Notes
+
+Anti-pitfall A7 da v1.8: skills devem prevenir ativamente os anti-patterns Supabase mais críticos. Sem este gate, refator de skill pode acidentalmente remover a regra principal (ex: `(select auth.uid())` wrapper que previne 1000× degradação). Strings como `WARNING user_metadata`, `set search_path = ''`, `NEVER use auth-helpers-nextjs` são as primeiras coisas que LLM lê — devem estar lá.

package/gates/sync-idempotent.md

@@ -0,0 +1,62 @@
+---
+id: sync-idempotent
+stage: pre-verify
+blocking: false
+description: Valida que `kit sync claude-code` rodado 2× consecutivos produz `.claude/` byte-idêntico (anti-pitfall A1 — drift kit/ ↔ .claude/).
+---
+
+# Sync idempotent gate
+
+**When to run:** pre-verify (non-blocking — warn em vez de bloquear).
+
+## Check
+
+```bash
+#!/usr/bin/env bash
+# PT-BR: roda sync 2× e compara — output deve ser byte-idêntico
+set -e
+
+TMPDIR=$(mktemp -d -t kit-mcp-sync-test-XXXXXX)
+trap "rm -rf $TMPDIR" EXIT
+
+# PT-BR: copia projeto root para tmpdir (sem node_modules)
+mkdir -p "$TMPDIR/project"
+cp -r kit "$TMPDIR/project/"
+cp package.json "$TMPDIR/project/" 2>/dev/null || true
+
+# PT-BR: 1ª execução
+node bin/cli.js sync install claude-code --project-root "$TMPDIR/project" >/dev/null 2>&1 || {
+  echo "WARN: primeira sync falhou — gate inconclusivo"
+  exit 0
+}
+
+# PT-BR: snapshot do output
+SNAPSHOT1=$(find "$TMPDIR/project/.claude" -type f -exec sha256sum {} \; 2>/dev/null | sort | sha256sum)
+
+# PT-BR: 2ª execução
+node bin/cli.js sync install claude-code --project-root "$TMPDIR/project" >/dev/null 2>&1
+
+# PT-BR: snapshot 2
+SNAPSHOT2=$(find "$TMPDIR/project/.claude" -type f -exec sha256sum {} \; 2>/dev/null | sort | sha256sum)
+
+if [ "$SNAPSHOT1" != "$SNAPSHOT2" ]; then
+  echo "FAIL: sync não-idempotente — output diverge entre execuções"
+  echo "Snapshot 1: $SNAPSHOT1"
+  echo "Snapshot 2: $SNAPSHOT2"
+  exit 1
+fi
+
+echo "✓ Sync idempotente — duas execuções produzem .claude/ byte-idêntico"
+exit 0
+```
+
+## Verdict
+
+- **passed** — `.claude/` byte-idêntico entre 2 execuções
+- **warn** — drift detectado (não-blocking; investigar)
+
+## Notes
+
+Anti-pitfall A1 da v1.8: drift entre `kit/` canonical e `.claude/` stubs após adicionar 19+ items multiplicados por 8 IDE targets. Sync deve ser idempotente — qualquer fonte de não-determinismo (timestamps, ordering aleatório, hash de tempo de geração) precisa ser eliminada. Este gate detecta divergência cedo, antes de chegar em produção.
+
+**Por que non-blocking:** o gate roda CLI completo + I/O — pode falhar por razões ambientais (permissions, espaço em disco) que não são bugs de sync. Falha vira warn para revisão manual.

package/kit/agents/codebase-mapper.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-mapper
-description: Explora a codebase e escreve documentos de análise estruturados. Invocado pelo mapear-codebase com uma área de foco (tech, arch, quality, concerns). Escreve documentos diretamente para reduzir a carga de contexto do orquestrador.
+description: Explora a codebase e escreve docs de análise estruturados. Invocado por /mapear-codebase com foco (tech, arch, quality, concerns). Reduz carga de contexto do orquestrador.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
 # hooks:

package/kit/agents/executor.md

@@ -42,6 +42,23 @@ Antes de executar, descubra o contexto do projeto:
 Isso garante que padrões, convenções e melhores práticas específicas do projeto sejam aplicados durante a execução.
 
 **Cumprimento do CLAUDE.md:** Se `./CLAUDE.md` existir, trate suas diretivas como restrições rígidas durante a execução. Antes de fazer commit de cada tarefa, verifique se as mudanças de código não violam as regras do CLAUDE.md (padrões proibidos, convenções obrigatórias, ferramentas mandatadas). Se uma ação de tarefa contradizer uma diretiva do CLAUDE.md, aplique a regra do CLAUDE.md — ela tem precedência sobre instruções do plano. Documente quaisquer ajustes motivados pelo CLAUDE.md como desvios (Regra 2: adicione automaticamente funcionalidade crítica ausente).
+
+**Delegação para agents especializados:** se uma task do plan toca em domínios que têm agents especializados no kit, **DELEGUE em vez de executar inline**. Exemplos:
+
+| Task toca em | Delegue para | Por quê |
+|---|---|---|
+| `supabase/migrations/<*>.sql` (criar/editar) | `Task(subagent_type=supabase-migration-writer, prompt=<task description>)` | Aplica RLS obrigatório, granular policies, `(select auth.uid())` wrapper, naming UTC |
+| `supabase/schemas/<*>.sql` | `Task(subagent_type=supabase-migration-writer)` | Idem + workflow declarative (`supabase stop` → `db diff -f`) |
+| RLS policies em qualquer tabela | `Task(subagent_type=supabase-rls-writer)` | ABORTA em `user_metadata`, gera 4 policies granulares + indexes |
+| `supabase/functions/<name>/*.ts` | `Task(subagent_type=supabase-edge-fn-writer)` | Aplica `npm:`/`jsr:` versionados, `Deno.serve`, env vars canônicas |
+| Realtime channels (client + trigger + RLS) | `Task(subagent_type=supabase-realtime-implementer)` | Garante `private: true`, cleanup, RLS sobre `realtime.messages` |
+| Bootstrap Next.js + `@supabase/ssr` | `Task(subagent_type=supabase-auth-bootstrapper)` | Audita `.env*` para service_role leak, single serverClient factory |
+| Storage buckets + RLS `storage.objects` | `Task(subagent_type=supabase-storage-implementer)` | Multi-tenant path isolation, signed URLs, image transforms |
+| Validar SQL antes de aplicar | `Task(subagent_type=schema-checker)` | Valida FKs/colunas/tabelas via Supabase MCP |
+
+**Quando NÃO delegar:** tasks que só leem, fazem grep, ou aplicam mudança trivial em arquivo Supabase (ex: corrigir typo em comment de migration existente). Use seu próprio Edit nesses casos.
+
+**Princípio:** o agent especializado é mais barato + mais correto que o executor genérico para esses domínios — ele já tem as regras embutidas. Delegação não é overhead; é correção.
 </project_context>
 
 <execution_flow>

package/kit/agents/planner.md

@@ -37,8 +37,43 @@ Se o prompt contiver um bloco `<files_to_read>`, você DEVE usar a ferramenta `R
 - Lidar com planejamento padrão e modo de fechamento de lacunas
 - Revisar planos existentes com base no feedback do verificador (modo de revisão)
 - Retornar resultados estruturados ao orquestrador
+- **Detectar domínios especializados e delegar para agents apropriados** (ver seção `<specialized_agents>` abaixo)
 </role>
 
+<specialized_agents>
+## Delegação para agents especializados
+
+Antes de gerar PLAN.md, **detecte o domínio da fase** lendo o CONTEXT.md e o objetivo do ROADMAP.md. Se a fase mexe em domínios que têm agents especializados no kit, **prefira delegar** em vez de escrever tasks genéricas que o `executor` faria sem expertise específica.
+
+### Suíte Supabase (v1.8+)
+
+Se a fase menciona qualquer destes patterns, considere delegação:
+
+| Pattern detectado | Agent especializado | Skill relacionada |
+|---|---|---|
+| Schema/DB design "antes" da implementação (escolha de tabelas, RLS strategy, multi-tenant) | `supabase-architect` | `supabase-rls-policies`, `supabase-postgres-style` |
+| Criar/editar arquivo em `supabase/migrations/` ou `supabase/schemas/` | `supabase-migration-writer` | `supabase-migrations`, `supabase-declarative-schema` |
+| Gerar/auditar policies RLS | `supabase-rls-writer` | `supabase-rls-policies` |
+| Edge Function em `supabase/functions/<name>/` | `supabase-edge-fn-writer` | `supabase-edge-functions` |
+| Realtime channels (client + DB triggers + RLS sobre `realtime.messages`) | `supabase-realtime-implementer` | `supabase-realtime` |
+| Bootstrap Next.js v16 + `@supabase/ssr` | `supabase-auth-bootstrapper` | `supabase-auth-ssr` |
+| Storage buckets + RLS multi-tenant em `storage.objects` | `supabase-storage-implementer` | `supabase-storage` |
+| Validar SQL antes de aplicar em produção | `schema-checker` | — |
+
+**Como delegar no PLAN.md:** uma task pode ter `subagent_type: supabase-migration-writer` no frontmatter da task, ou o `executor` lê do plan e dispatcha. Para fases inteiramente Supabase, considere `supabase-architect` no Step 1 do plano para projetar antes do `executor` codar.
+
+**Regra crítica:** agents `supabase-*` NÃO devem se chamar uns aos outros (anti-pitfall A10). Toda chain de agents Supabase deve passar pelo command `/supabase` ou pelo plan que o `executor` lê.
+
+### Outros agents especializados existentes
+
+- `schema-checker` — validação pré-migration de SQL (FK, JOIN, INSERT) contra schema real
+- `ui-researcher` / `ui-checker` / `ui-auditor` — fases frontend com contrato de design
+- `debugger` — investigação de bug com método científico (já invocado por `/depurar`)
+- `nyquist-auditor` — preenchimento de gaps de validação retroativa
+
+Em todos os casos: prefira o especialista quando o domínio bate; degrade para `executor` genérico apenas quando não há especialista.
+</specialized_agents>
+
 <project_context>
 Antes de planejar, descubra o contexto do projeto:
 

package/kit/agents/project-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: project-researcher
-description: Pesquisa o ecossistema do domínio antes da criação do roadmap. Produz arquivos em .planning/research/ consumidos durante a criação do roadmap. Invocado pelos orquestradores /novo-projeto ou /novo-milestone.
+description: Pesquisa ecossistema do domínio antes do roadmap. Produz arquivos em .planning/research/ consumidos pelo roadmapper. Invocado por /novo-projeto ou /novo-marco.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
 color: cyan
 # hooks:

package/kit/agents/schema-checker.md

@@ -1,7 +1,7 @@
 ---
 name: schema-checker
-description: Valida foreign keys, colunas e tabelas referenciadas em uma migration SQL ANTES de aplicá-la em produção. Lê a SQL, extrai refs (FK, JOIN, INSERT INTO ... SELECT), consulta o schema real via Supabase MCP, e devolve um veredito GO/NO-GO com diff entre o que a migration assume e o que existe. Invocar antes de qualquer `apply_migration` que toque dados existentes.
-tools: Read, Bash, Grep, Glob, mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__execute_sql, mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__list_tables
+description: Valida FKs/colunas/tabelas referenciadas em migration SQL ANTES de aplicar em prod. Lê SQL, consulta schema via Supabase MCP, devolve veredito GO/NO-GO/NEEDS-REVIEW.
+tools: Read, Bash, Grep, Glob, mcp__supabase__execute_sql, mcp__supabase__list_tables
 color: red
 ---
 
@@ -61,7 +61,7 @@ SELECT
   EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = '{table}' AND column_name = '{col}') AS col_exists;
 ```
 
-Use `mcp__0a712001-...__execute_sql` com o `project_id`.
+Use `mcp__supabase__execute_sql` com o `project_id`.
 
 #### 3.2 — Tipo da coluna referenciada (FK target)
 
@@ -149,7 +149,7 @@ Apenas o relatório. Sem preâmbulo. Sem "vou analisar agora". Sem "espero ter a
 
 ## Quando o caller deve invocar
 
-- Antes de chamar `mcp__0a712001-...__apply_migration` em qualquer migration que toque dados existentes.
+- Antes de chamar `mcp__supabase__apply_migration` em qualquer migration que toque dados existentes.
 - Antes de mergear PR que contém migration que vai pra produção.
 - Manualmente, quando o dev pediu uma sanity check ("essa migration tá OK?").