@luanpdd/kit-mcp 1.27.0 → 1.28.0

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

@@ -2,47 +2,81 @@
 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).
+description: Valida que agents Supabase não montam ciclos via Task(). DAGs cooperativos v1.23+ (hardener/implementer pattern) são permitidos.
 ---
 
 # Agent no recursive dispatch gate
 
 **When to run:** pre-verify.
 
+## Context
+
+A v1.8 introduziu este gate para prevenir o anti-pitfall A10: tentação de `supabase-architect` invocar `supabase-migration-writer` que re-invocaria architect → **ciclo** lógico + custo LLM multiplicado.
+
+A v1.23+ introduziu o pattern de **handoff cooperativo** (princípio canônico): agents não-Supabase planejam, agents Supabase materializam/hardenam, ninguém descarta upstream. Isso significa que **dispatches DAG entre agents Supabase são legítimos** (ex: `supabase-rls-writer` → `supabase-rls-hardener`). Apenas **ciclos** são proibidos.
+
+Este gate, portanto, valida o conjunto **proibido** (ciclos) e o conjunto **permitido** (handoffs DAG canônicos da hierarquia hardener/implementer).
+
+## Allowlist canônica de handoffs DAG (downstream-only)
+
+- `supabase-rls-hardener` (v1.23) — canonical handoff target
+- `supabase-rls-writer` (v1.8) — pode invocar hardener; hardener nunca invoca writer de volta
+- `supabase-column-privileges-writer` (v1.24)
+- `supabase-rbac-implementer` (v1.25)
+- `supabase-roles-implementer` (v1.26)
+- `supabase-migration-writer` (cross-suite SQL handoff)
+- `supabase-branching-architect` (v1.27)
+- `supabase-cicd-pipeline-implementer` (v1.27)
+
+Dispatches para esses targets são **permitidos** mesmo quando o caller é também um agent Supabase.
+
 ## 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)
+# PT-BR: agents Supabase podem invocar peers via DAG canônico (hardener/implementer pattern v1.23+).
+# Proibido: ciclos. Permitido: dispatches downstream para a allowlist da hierarquia cooperativa.
 set -e
 
 VIOLATIONS=0
 
+# Allowlist canônica (downstream-only): cada um destes é leaf na DAG cooperativa
+ALLOWLIST='supabase-(rls-hardener|rls-writer|column-privileges-writer|rbac-implementer|roles-implementer|migration-writer|branching-architect|cicd-pipeline-implementer)'
+
 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()"
+  # 1. Match raw: linha contém Task(...subagent_type=...supabase-...)
+  # 2. Excluir allowlist (handoffs DAG legítimos v1.23+)
+  # 3. Excluir linhas de auto-documentação ("Este agent é invocável via Task" / "Cross-suite handoff: invocar via")
+  matches=$(grep -nE 'Task\([^)]*subagent_type[^)]*supabase-' "$f" \
+    | grep -vE "subagent_type[^)]*${ALLOWLIST}" \
+    | grep -vE 'Este agent é invocável via|Cross-suite handoff: invocar via|invocável via .?Task' \
+    || true)
+  if [ -n "$matches" ]; then
+    echo "FAIL: $f — dispatch fora da allowlist canônica (potencial ciclo):"
+    echo "$matches"
     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."
+  echo "Agents Supabase podem invocar a allowlist canônica (hardener/implementer pattern v1.23+)."
+  echo "Dispatches fora dessa lista correm risco de ciclo (anti-pitfall A10)."
   exit 1
 fi
 
-echo "✓ Zero recursive dispatch entre agents Supabase"
+echo "✓ Zero recursive dispatch fora da allowlist canônica"
 exit 0
 ```
 
 ## Verdict
 
-- **passed** — zero `Task(subagent_type=supabase-...)` em `kit/agents/supabase-*.md`
-- **block** — recursive dispatch detectado
+- **passed** — zero dispatches fora da allowlist DAG canônica
+- **block** — dispatch para target não-allowlist detectado (potencial ciclo)
 
 ## 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).
+- Anti-pitfall A10 (v1.8) ainda válido para targets **não-allowlist** (ex: architect → migration-writer fora do flow cooperativo)
+- Allowlist v1.23-v1.27 reflete o princípio canônico: agents Supabase materializam/hardenam via DAG; ciclos continuam proibidos
+- Para adicionar novo handoff target: incluir em `ALLOWLIST` acima e documentar a justificativa cross-suite

package/kit/COMANDOS.md

@@ -1,138 +1,138 @@
-# Comandos do framework — Referência Rápida
-
-## Fluxo Principal
-
-| Comando | O que faz |
-|---------|-----------|
-| `/novo-projeto` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md |
-| `/novo-marco` | Inicia um novo ciclo de milestone — atualiza PROJECT.md e encaminha para requisitos |
-| `/discutir-fase` | Reúne contexto da fase por questionamento adaptativo antes do planejamento (`--auto` para pular perguntas) |
-| `/planejar-fase` | Cria plano detalhado da fase (PLAN.md) com loop de verificação |
-| `/executar-fase` | Executa todos os planos de uma fase com paralelização por ondas |
-| `/proximo` | Avança automaticamente para o próximo passo lógico no workflow framework |
-| `/autonomo` | Executa todas as fases restantes de forma autônoma — discutir→planejar→executar por fase |
-
-## Tarefas Rápidas
-
-| Comando | O que faz |
-|---------|-----------|
-| `/fazer` | Roteia texto livre para o comando do framework correto automaticamente |
-| `/rapido` | Executa tarefa trivial inline — sem subagentes, sem overhead de planejamento |
-| `/expresso` | Executa tarefa rápida com garantias framework (commits atômicos, rastreamento de estado), pula agentes opcionais |
-
-## Gerenciamento de Fases
-
-| Comando | O que faz |
-|---------|-----------|
-| `/adicionar-fase` | Adiciona fase ao final do milestone atual no roadmap |
-| `/inserir-fase` | Insere trabalho urgente como fase decimal (ex: 72.1) entre fases existentes |
-| `/remover-fase` | Remove uma fase futura do roadmap e renumera as subsequentes |
-| `/pesquisar-fase` | Pesquisa como implementar uma fase (standalone — normalmente use `/planejar-fase`) |
-| `/listar-hipoteses-fase` | Mostra as hipóteses do Claude sobre a abordagem de uma fase antes do planejamento |
-
-## Milestones e Progresso
-
-| Comando | O que faz |
-|---------|-----------|
-| `/progresso` | Verifica o progresso do projeto, mostra contexto e roteia para próxima ação |
-| `/auditar-marco` | Audita a conclusão do milestone contra a intenção original antes de arquivar |
-| `/concluir-marco` | Arquiva milestone concluído e prepara para próxima versão |
-| `/resumo-marco` | Gera resumo abrangente do projeto para onboarding e revisão da equipe |
-| `/planejar-lacunas` | Cria fases para fechar todas as lacunas identificadas pela auditoria de milestone |
-
-## Verificação e Qualidade
-
-| Comando | O que faz |
-|---------|-----------|
-| `/verificar-trabalho` | Valida funcionalidades construídas através de UAT conversacional |
-| `/validar-fase` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída |
-| `/auditar-uat` | Auditoria multi-fase de todos os itens de UAT e verificação pendentes |
-| `/adicionar-testes` | Gera testes para uma fase concluída com base nos critérios de UAT e implementação |
-| `/verificar-tarefas` | Lista todos os todos pendentes e seleciona um para trabalhar |
-
-## UI / Frontend
-
-| Comando | O que faz |
-|---------|-----------|
-| `/fase-ui` | Gera contrato de design UI (UI-SPEC.md) para fases de frontend |
-| `/revisar-ui` | Auditoria visual retroativa de 6 pilares do código frontend implementado |
-
-## Sessão e Contexto
-
-| Comando | O que faz |
-|---------|-----------|
-| `/pausar-trabalho` | Cria handoff de contexto ao pausar trabalho no meio de uma fase |
-| `/retomar-trabalho` | Retoma o trabalho da sessão anterior com restauração completa de contexto |
-| `/relatorio-sessao` | Gera relatório da sessão com estimativas de uso de tokens, resumo de trabalho e resultados |
-| `/fio` | Gerencia threads de contexto persistentes para trabalho entre sessões |
-
-## Análise e Diagnóstico
-
-| Comando | O que faz |
-|---------|-----------|
-| `/mapear-codebase` | Analisa a base de código com agentes paralelos, produz documentos em `.planning/codebase/` |
-| `/depurar` | Depuração sistemática com estado persistente entre resets de contexto |
-| `/forense` | Investigação post-mortem de workflows framework com falha — analisa git, artefatos e estado |
-| `/saude` | Diagnostica a integridade do diretório de planejamento e opcionalmente repara problemas |
-| `/estatisticas` | Exibe estatísticas do projeto — fases, planos, requisitos, métricas git e linha do tempo |
-
-## Publicação e Colaboração
-
-| Comando | O que faz |
-|---------|-----------|
-| `/publicar` | Cria PR, executa revisão e prepara para merge após a verificação passar |
-| `/branch-pr` | Cria branch limpo para PR filtrando commits de `.planning/` — pronto para revisão de código |
-| `/revisar` | Solicita revisão entre IAs de planos de fase a partir de CLIs externas |
-
-## Backlog e Ideias
-
-| Comando | O que faz |
-|---------|-----------|
-| `/nota` | Captura de ideias sem fricção — adicionar, listar ou promover notas |
-| `/adicionar-tarefa` | Captura ideia ou tarefa como todo a partir do contexto da conversa atual |
-| `/adicionar-backlog` | Adiciona uma ideia ao estacionamento de backlog (numeração 999.x) |
-| `/revisar-backlog` | Revisa e promove itens do backlog para o milestone ativo |
-| `/plantar-ideia` | Captura ideia prospectiva com condições de gatilho — surge automaticamente no milestone certo |
-
-## Workspaces
-
-| Comando | O que faz |
-|---------|-----------|
-| `/novo-workspace` | Cria workspace isolado com cópias de repos e `.planning/` independente |
-| `/listar-workspaces` | Lista os workspaces framework ativos e seu status |
-| `/remover-workspace` | Remove um workspace framework e limpa as worktrees |
-| `/fluxos-trabalho` | Gerencia fluxos de trabalho paralelos — listar, criar, alternar, status, concluir e retomar |
-| `/gerenciador` | Central de comando interativa para gerenciar múltiplas fases em um terminal |
-
-## Perfil e Configurações
-
-| Comando | O que faz |
-|---------|-----------|
-| `/perfil-usuario` | Gera perfil comportamental do desenvolvedor e cria artefatos descobríveis pelo Claude |
-| `/definir-perfil` | Altera o perfil de modelo para os agentes framework (quality/balanced/budget/inherit) |
-| `/configuracoes` | Configura os toggles de workflow framework e perfil de modelo |
-
-## Suíte Legacy Code (Feathers + modernizações IA/Supabase 2026)
-
-| Comando | O que faz |
-|---------|-----------|
-| `/legacy <subcomando>` | Orquestrador único — dispatch para agents da suíte (10 subcomandos com sinônimos PT/EN) |
-| `/caracterizar` | Gera characterization tests (cap 13) — golden snapshots cobrindo 7 grupos de equivalência |
-| `/encontrar-seams` | Identifica seams (cap 25) e recomenda técnica de dependency-breaking |
-| `/auditar-refactor` | Gate canônico — coleta evidências e retorna veredito GO/BLOCK/WARN/GO-OVERRIDE |
-| `/refactor-seguro` | Chain canônico — seams → caracterizar → auditar → executar; modos full/sprout/safe-extract/override |
-| `/capturar-payloads` | Instrumenta Edge Function Supabase para captura de payloads reais via mcp__supabase__get_logs (modernização) |
-| `/caracterizar-prompt` | Characterization de prompts/tools LLM com temperature=0 + seed fixo (modernização IA) |
-| `/storytelling` | IA gera mental model + naked CRC + extract candidates (cap 16-17 + modernização IA) |
-| `/detectar-duplicacao` | Shotgun surgery cross-codebase via embeddings + jscpd (cap 21 + modernização IA) |
-| `/auditar-observabilidade-cobertura` | Audit X/N Edge Functions com signals + SLO + burn alert + char (cross-suite) |
-
-## Utilitários
-
-| Comando | O que faz |
-|---------|-----------|
-| `/ajuda` | Mostra os comandos do framework disponíveis e o guia de uso |
-| `/atualizar` | Atualiza o framework para a versão mais recente com exibição de changelog |
-| `/reaplicar-patches` | Reaplicar modificações locais após uma atualização do framework |
-| `/limpeza` | Arquiva diretórios de fase acumulados de milestones concluídos |
-| `/entrar-discord` | Link para entrar na comunidade framework no Discord |
+# Comandos do framework — Referência Rápida
+
+## Fluxo Principal
+
+| Comando | O que faz |
+|---------|-----------|
+| `/novo-projeto` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md |
+| `/novo-marco` | Inicia um novo ciclo de milestone — atualiza PROJECT.md e encaminha para requisitos |
+| `/discutir-fase` | Reúne contexto da fase por questionamento adaptativo antes do planejamento (`--auto` para pular perguntas) |
+| `/planejar-fase` | Cria plano detalhado da fase (PLAN.md) com loop de verificação |
+| `/executar-fase` | Executa todos os planos de uma fase com paralelização por ondas |
+| `/proximo` | Avança automaticamente para o próximo passo lógico no workflow framework |
+| `/autonomo` | Executa todas as fases restantes de forma autônoma — discutir→planejar→executar por fase |
+
+## Tarefas Rápidas
+
+| Comando | O que faz |
+|---------|-----------|
+| `/fazer` | Roteia texto livre para o comando do framework correto automaticamente |
+| `/rapido` | Executa tarefa trivial inline — sem subagentes, sem overhead de planejamento |
+| `/expresso` | Executa tarefa rápida com garantias framework (commits atômicos, rastreamento de estado), pula agentes opcionais |
+
+## Gerenciamento de Fases
+
+| Comando | O que faz |
+|---------|-----------|
+| `/adicionar-fase` | Adiciona fase ao final do milestone atual no roadmap |
+| `/inserir-fase` | Insere trabalho urgente como fase decimal (ex: 72.1) entre fases existentes |
+| `/remover-fase` | Remove uma fase futura do roadmap e renumera as subsequentes |
+| `/pesquisar-fase` | Pesquisa como implementar uma fase (standalone — normalmente use `/planejar-fase`) |
+| `/listar-hipoteses-fase` | Mostra as hipóteses do Claude sobre a abordagem de uma fase antes do planejamento |
+
+## Milestones e Progresso
+
+| Comando | O que faz |
+|---------|-----------|
+| `/progresso` | Verifica o progresso do projeto, mostra contexto e roteia para próxima ação |
+| `/auditar-marco` | Audita a conclusão do milestone contra a intenção original antes de arquivar |
+| `/concluir-marco` | Arquiva milestone concluído e prepara para próxima versão |
+| `/resumo-marco` | Gera resumo abrangente do projeto para onboarding e revisão da equipe |
+| `/planejar-lacunas` | Cria fases para fechar todas as lacunas identificadas pela auditoria de milestone |
+
+## Verificação e Qualidade
+
+| Comando | O que faz |
+|---------|-----------|
+| `/verificar-trabalho` | Valida funcionalidades construídas através de UAT conversacional |
+| `/validar-fase` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída |
+| `/auditar-uat` | Auditoria multi-fase de todos os itens de UAT e verificação pendentes |
+| `/adicionar-testes` | Gera testes para uma fase concluída com base nos critérios de UAT e implementação |
+| `/verificar-tarefas` | Lista todos os todos pendentes e seleciona um para trabalhar |
+
+## UI / Frontend
+
+| Comando | O que faz |
+|---------|-----------|
+| `/fase-ui` | Gera contrato de design UI (UI-SPEC.md) para fases de frontend |
+| `/revisar-ui` | Auditoria visual retroativa de 6 pilares do código frontend implementado |
+
+## Sessão e Contexto
+
+| Comando | O que faz |
+|---------|-----------|
+| `/pausar-trabalho` | Cria handoff de contexto ao pausar trabalho no meio de uma fase |
+| `/retomar-trabalho` | Retoma o trabalho da sessão anterior com restauração completa de contexto |
+| `/relatorio-sessao` | Gera relatório da sessão com estimativas de uso de tokens, resumo de trabalho e resultados |
+| `/fio` | Gerencia threads de contexto persistentes para trabalho entre sessões |
+
+## Análise e Diagnóstico
+
+| Comando | O que faz |
+|---------|-----------|
+| `/mapear-codebase` | Analisa a base de código com agentes paralelos, produz documentos em `.planning/codebase/` |
+| `/depurar` | Depuração sistemática com estado persistente entre resets de contexto |
+| `/forense` | Investigação post-mortem de workflows framework com falha — analisa git, artefatos e estado |
+| `/saude` | Diagnostica a integridade do diretório de planejamento e opcionalmente repara problemas |
+| `/estatisticas` | Exibe estatísticas do projeto — fases, planos, requisitos, métricas git e linha do tempo |
+
+## Publicação e Colaboração
+
+| Comando | O que faz |
+|---------|-----------|
+| `/publicar` | Cria PR, executa revisão e prepara para merge após a verificação passar |
+| `/branch-pr` | Cria branch limpo para PR filtrando commits de `.planning/` — pronto para revisão de código |
+| `/revisar` | Solicita revisão entre IAs de planos de fase a partir de CLIs externas |
+
+## Backlog e Ideias
+
+| Comando | O que faz |
+|---------|-----------|
+| `/nota` | Captura de ideias sem fricção — adicionar, listar ou promover notas |
+| `/adicionar-tarefa` | Captura ideia ou tarefa como todo a partir do contexto da conversa atual |
+| `/adicionar-backlog` | Adiciona uma ideia ao estacionamento de backlog (numeração 999.x) |
+| `/revisar-backlog` | Revisa e promove itens do backlog para o milestone ativo |
+| `/plantar-ideia` | Captura ideia prospectiva com condições de gatilho — surge automaticamente no milestone certo |
+
+## Workspaces
+
+| Comando | O que faz |
+|---------|-----------|
+| `/novo-workspace` | Cria workspace isolado com cópias de repos e `.planning/` independente |
+| `/listar-workspaces` | Lista os workspaces framework ativos e seu status |
+| `/remover-workspace` | Remove um workspace framework e limpa as worktrees |
+| `/fluxos-trabalho` | Gerencia fluxos de trabalho paralelos — listar, criar, alternar, status, concluir e retomar |
+| `/gerenciador` | Central de comando interativa para gerenciar múltiplas fases em um terminal |
+
+## Perfil e Configurações
+
+| Comando | O que faz |
+|---------|-----------|
+| `/perfil-usuario` | Gera perfil comportamental do desenvolvedor e cria artefatos descobríveis pelo Claude |
+| `/definir-perfil` | Altera o perfil de modelo para os agentes framework (quality/balanced/budget/inherit) |
+| `/configuracoes` | Configura os toggles de workflow framework e perfil de modelo |
+
+## Suíte Legacy Code (Feathers + modernizações IA/Supabase 2026)
+
+| Comando | O que faz |
+|---------|-----------|
+| `/legacy <subcomando>` | Orquestrador único — dispatch para agents da suíte (10 subcomandos com sinônimos PT/EN) |
+| `/caracterizar` | Gera characterization tests (cap 13) — golden snapshots cobrindo 7 grupos de equivalência |
+| `/encontrar-seams` | Identifica seams (cap 25) e recomenda técnica de dependency-breaking |
+| `/auditar-refactor` | Gate canônico — coleta evidências e retorna veredito GO/BLOCK/WARN/GO-OVERRIDE |
+| `/refactor-seguro` | Chain canônico — seams → caracterizar → auditar → executar; modos full/sprout/safe-extract/override |
+| `/capturar-payloads` | Instrumenta Edge Function Supabase para captura de payloads reais via mcp__supabase__get_logs (modernização) |
+| `/caracterizar-prompt` | Characterization de prompts/tools LLM com temperature=0 + seed fixo (modernização IA) |
+| `/storytelling` | IA gera mental model + naked CRC + extract candidates (cap 16-17 + modernização IA) |
+| `/detectar-duplicacao` | Shotgun surgery cross-codebase via embeddings + jscpd (cap 21 + modernização IA) |
+| `/auditar-observabilidade-cobertura` | Audit X/N Edge Functions com signals + SLO + burn alert + char (cross-suite) |
+
+## Utilitários
+
+| Comando | O que faz |
+|---------|-----------|
+| `/ajuda` | Mostra os comandos do framework disponíveis e o guia de uso |
+| `/atualizar` | Atualiza o framework para a versão mais recente com exibição de changelog |
+| `/reaplicar-patches` | Reaplicar modificações locais após uma atualização do framework |
+| `/limpeza` | Arquiva diretórios de fase acumulados de milestones concluídos |
+| `/entrar-discord` | Link para entrar na comunidade framework no Discord |

package/kit/README.md

@@ -1,76 +1,76 @@
-# Your kit lives here
-
-This `kit/` folder is the canonical source of your personal collection of
-agents, slash-commands and skills. `kit-mcp` reads from here and projects
-into every supported IDE.
-
-## Layout
-
-```
-kit/
-├── agents/                 one .md per sub-agent
-│   └── <name>.md
-├── commands/               one .md per slash-command
-│   └── <name>.md
-└── skills/                 one folder per skill, containing SKILL.md
-    └── <name>/
-        ├── SKILL.md
-        └── references/     optional reference docs
-```
-
-## File format
-
-Every file uses YAML frontmatter for metadata + Markdown body for the prompt:
-
-```markdown
----
-name: my-agent
-description: One-sentence description of what this agent does and when to use it.
-tools: Read, Write, Bash    # optional, agents only
-color: blue                 # optional, agents only
----
-
-The body of the agent prompt goes here. This is what the LLM sees when
-the agent is spawned. Keep it focused, give clear instructions, list
-constraints.
-```
-
-## Three example items ship in this folder
-
-- `agents/example-reviewer.md` — minimal sub-agent template
-- `commands/example-greeting.md` — minimal slash-command template
-- `skills/example-skill/SKILL.md` — minimal skill template
-
-Replace them with your own. Or, if you keep your kit elsewhere, point
-kit-mcp at it:
-
-```bash
-kit kit list-agents --kit-root /path/to/your/kit
-kit sync install claude-code --kit-root /path/to/your/kit --project-root .
-```
-
-Or set `KIT_MCP_KIT_ROOT` env var to make it the default for the session.
-
-## Suíte DDIA Foundations (v1.22)
-
-8ª suíte do kit, derivada de *Designing Data-Intensive Applications* (Martin Kleppmann, O'Reilly 2017). Cobre capítulos 4, 5, 6, 7, 8, 9, 11.
-
-**Convenção nova:** A partir de v1.22, todos os artefatos novos (skills, agents, commands) usam **PT-BR descritivo** para nome de arquivo/identificador. Termos técnicos canônicos (CDC, RLS, MVCC, write skew, fencing token) preservados em descrições/conteúdo.
-
-**Skills (7):**
-- `evolucao-schema-compativel` (Ch 4) — backward/forward compat, padrão 3-passos
-- `consistencia-leitura-replica` (Ch 5) — read-after-write, monotonic reads, prefix
-- `tenant-quente-mitigacao` (Ch 6) — Justin Bieber problem + 5 estratégias
-- `postgres-isolamento-concorrencia` (Ch 7) — 6 race conditions, isolation levels
-- `armadilhas-sistemas-distribuidos` (Ch 8) — clock skew, fencing tokens, GC pause
-- `escolha-modelo-consistencia` (Ch 9) — linearizable vs causal vs eventual
-- `streams-eventos-cdc` (Ch 11) — CDC, event sourcing, exactly-once
-
-**Agents (3):**
-- `auditor-consistencia-isolamento` — detecta 6 anti-patterns de race condition
-- `detector-tenant-quente` — detecta hot tenants via Supabase logs
-- `validador-evolucao-schema` — pré-validação de migration arriscada
-
-**Comando:** `/dados-distribuidos [auditar-consistencia | auditar-tenant-quente | validar-evolucao-schema | implementar-cdc]`
-
-**Glossário compartilhado:** `_shared-dados-distribuidos/glossary.md` (PT-BR↔EN, 60+ termos)
+# Your kit lives here
+
+This `kit/` folder is the canonical source of your personal collection of
+agents, slash-commands and skills. `kit-mcp` reads from here and projects
+into every supported IDE.
+
+## Layout
+
+```
+kit/
+├── agents/                 one .md per sub-agent
+│   └── <name>.md
+├── commands/               one .md per slash-command
+│   └── <name>.md
+└── skills/                 one folder per skill, containing SKILL.md
+    └── <name>/
+        ├── SKILL.md
+        └── references/     optional reference docs
+```
+
+## File format
+
+Every file uses YAML frontmatter for metadata + Markdown body for the prompt:
+
+```markdown
+---
+name: my-agent
+description: One-sentence description of what this agent does and when to use it.
+tools: Read, Write, Bash    # optional, agents only
+color: blue                 # optional, agents only
+---
+
+The body of the agent prompt goes here. This is what the LLM sees when
+the agent is spawned. Keep it focused, give clear instructions, list
+constraints.
+```
+
+## Three example items ship in this folder
+
+- `agents/example-reviewer.md` — minimal sub-agent template
+- `commands/example-greeting.md` — minimal slash-command template
+- `skills/example-skill/SKILL.md` — minimal skill template
+
+Replace them with your own. Or, if you keep your kit elsewhere, point
+kit-mcp at it:
+
+```bash
+kit kit list-agents --kit-root /path/to/your/kit
+kit sync install claude-code --kit-root /path/to/your/kit --project-root .
+```
+
+Or set `KIT_MCP_KIT_ROOT` env var to make it the default for the session.
+
+## Suíte DDIA Foundations (v1.22)
+
+8ª suíte do kit, derivada de *Designing Data-Intensive Applications* (Martin Kleppmann, O'Reilly 2017). Cobre capítulos 4, 5, 6, 7, 8, 9, 11.
+
+**Convenção nova:** A partir de v1.22, todos os artefatos novos (skills, agents, commands) usam **PT-BR descritivo** para nome de arquivo/identificador. Termos técnicos canônicos (CDC, RLS, MVCC, write skew, fencing token) preservados em descrições/conteúdo.
+
+**Skills (7):**
+- `evolucao-schema-compativel` (Ch 4) — backward/forward compat, padrão 3-passos
+- `consistencia-leitura-replica` (Ch 5) — read-after-write, monotonic reads, prefix
+- `tenant-quente-mitigacao` (Ch 6) — Justin Bieber problem + 5 estratégias
+- `postgres-isolamento-concorrencia` (Ch 7) — 6 race conditions, isolation levels
+- `armadilhas-sistemas-distribuidos` (Ch 8) — clock skew, fencing tokens, GC pause
+- `escolha-modelo-consistencia` (Ch 9) — linearizable vs causal vs eventual
+- `streams-eventos-cdc` (Ch 11) — CDC, event sourcing, exactly-once
+
+**Agents (3):**
+- `auditor-consistencia-isolamento` — detecta 6 anti-patterns de race condition
+- `detector-tenant-quente` — detecta hot tenants via Supabase logs
+- `validador-evolucao-schema` — pré-validação de migration arriscada
+
+**Comando:** `/dados-distribuidos [auditar-consistencia | auditar-tenant-quente | validar-evolucao-schema | implementar-cdc]`
+
+**Glossário compartilhado:** `_shared-dados-distribuidos/glossary.md` (PT-BR↔EN, 60+ termos)