feat(skills): acionamento automático nos cinco CLIs — portas, regras e hook de sessão

- AGENTS.md (Codex, OpenCode, Cursor) e CLAUDE.md (Claude Code) ganham a tabela "situação → guia"; `.cursor/rules/deskcomm-guias.mdc` (alwaysApply) e `.agents/rules/deskcomm-guias.md` (Antigravity, trigger always_on) com o mesmo corpo — gate que reprova divergência entre os dois e guia ausente em qualquer porta - hook de início de sessão (`sessao.sh`): fala UMA vez e só em clone de contribuidor (quem-sou.sh); silêncio para o mantenedor. Ligado em `.claude/settings.json` (versionado; o .gitignore passa a liberá-lo) e `.codex/hooks.json` (o Codex exige aprovação em /hooks) - portas para o leigo: docs/index.md, README ("Prefere que uma IA instale"), CONTRIBUTING (passo 0), hostgator-setup-kit/README ("Caminho fácil" para os cinco CLIs); fragmento `.changes/guias-do-assistente.md` (capacidade_nova) - gates: 91 casos verdes (skills, ponteiros, roteiro×guia, AGENTS.md×package, acolhida); shell 34/34; typecheck 0 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N4qXpr9LCmXoG2KR4TBrL3
2026-10-02 01:28:34 +08:00 · 2026-09-10 07:51:56 -03:00
parent 31ea4f1c83
commit 6d89914985
16 changed files with 214 additions and 3 deletions
@@ -0,0 +1,20 @@
+---
+trigger: always_on
+description: Guias do assistente do DeskcommCRM — quando usar cada um
+---
+
+Este repositório embute guias (skills em `.agents/skills/`) para cinco situações. Quando o pedido
+casar, carregue o guia antes de agir — a pessoa pode não saber que ele existe:
+
+- instalar, subir, atualizar, consertar a instalação numa VPS, domínio, Supabase, WhatsApp
+  que não conecta → `deskcomm-instalar`
+- configurar o CRM para um cliente ou nicho (clínica, imobiliária, serviços, curso, loja):
+  agentes, roteadores, follow-ups, base de conhecimento → `deskcomm-cliente-novo`
+- desempenho, conversão, custo de IA, funil, relatório, "o agente está vendendo?" → `deskcomm-metricas`
+- o agente responde errado, passa tudo para humano, não usa a agenda, melhorar o prompt → `deskcomm-prompt`
+- contribuir, corrigir um bug, abrir ou atualizar um PR, migration, conflito com a main → `deskcomm-contribuir`
+  (rode `bash .agents/skills/deskcomm-contribuir/scripts/quem-sou.sh` primeiro: se disser
+  `mantenedor`, este guia fica quieto)
+
+Escrevendo código aqui: `deskcomm-doutrina` (as regras que mais custam) e `sistema-vivo` (o gate
+de arquitetura). A doutrina completa é o `CLAUDE.md` da raiz; o contrato portável é o `AGENTS.md`.
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# sessao.sh — o lembrete de início de sessão para quem CONTRIBUI.
+#
+# Ligado como hook de SessionStart (Claude Code: .claude/settings.json; Codex:
+# .codex/hooks.json, depois de a pessoa aprovar em /hooks). Imprime UMA vez, e só
+# quando o clone é de contribuidor: para o mantenedor, silêncio total — ele tem o
+# próprio ritual. O texto vai para o contexto do assistente, não para a pessoa.
+# Sai sempre com 0: um hook que falha derruba a sessão de quem só queria ler.
+set -uo pipefail
+
+aqui="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+quem="$(bash "$aqui/../quem-sou.sh" --curto 2>/dev/null || echo contribuidor)"
+[ "$quem" = "contribuidor" ] || exit 0
+
+raiz="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+hooks="$(git -C "$raiz" config --get core.hooksPath 2>/dev/null || true)"
+estado_hooks="hooks de git do contribuidor NÃO armados (bash .agents/skills/deskcomm-contribuir/scripts/armar-hooks.sh)"
+case "$hooks" in *deskcomm-contribuir*) estado_hooks="hooks de git do contribuidor armados" ;; esac
+
+cat <<TXT
+[DeskcommCRM] Este clone é de um contribuidor (não do mantenedor). Antes de codar ou commitar,
+carregue a skill deskcomm-contribuir: ela mede o que a triagem mede (branch atrasada, tripla de
+migration, marca do fork no diff, fragmento de release) e evita retrabalho. $estado_hooks.
+Guias para outras situações: deskcomm-instalar, deskcomm-cliente-novo, deskcomm-metricas, deskcomm-prompt.
+TXT
+exit 0
@@ -0,0 +1,6 @@
+---
+impacto: capacidade_nova
+secao: adicionado
+titulo: Guias do assistente para quem instala, opera e contribui com um CLI de IA
+---
+Com o repositório aberto no Claude Code, Codex, Cursor, OpenCode ou Antigravity, cinco guias carregam sozinhos na hora certa: instalar e consertar a instalação, montar um cliente por nicho (agentes, roteadores, follow-ups, base de conhecimento), analisar as métricas sem expor dado pessoal, afinar o prompt de um agente com dados, e contribuir com um PR que passa na triagem de primeira. O roteiro do kit de instalação foi corrigido (a verificação em duas etapas é opcional; três provedores de IA; token do Supabase) e o banner final do instalador passa a refletir a escolha de telemetria.
@@ -0,0 +1,16 @@
+{
+  "$comment": "Hook de início de sessão do Claude Code: fala UMA vez, e só quando o clone é de contribuidor (ver .agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh). Para o mantenedor, silêncio.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# sessao.sh — o lembrete de início de sessão para quem CONTRIBUI.
+#
+# Ligado como hook de SessionStart (Claude Code: .claude/settings.json; Codex:
+# .codex/hooks.json, depois de a pessoa aprovar em /hooks). Imprime UMA vez, e só
+# quando o clone é de contribuidor: para o mantenedor, silêncio total — ele tem o
+# próprio ritual. O texto vai para o contexto do assistente, não para a pessoa.
+# Sai sempre com 0: um hook que falha derruba a sessão de quem só queria ler.
+set -uo pipefail
+
+aqui="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+quem="$(bash "$aqui/../quem-sou.sh" --curto 2>/dev/null || echo contribuidor)"
+[ "$quem" = "contribuidor" ] || exit 0
+
+raiz="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+hooks="$(git -C "$raiz" config --get core.hooksPath 2>/dev/null || true)"
+estado_hooks="hooks de git do contribuidor NÃO armados (bash .agents/skills/deskcomm-contribuir/scripts/armar-hooks.sh)"
+case "$hooks" in *deskcomm-contribuir*) estado_hooks="hooks de git do contribuidor armados" ;; esac
+
+cat <<TXT
+[DeskcommCRM] Este clone é de um contribuidor (não do mantenedor). Antes de codar ou commitar,
+carregue a skill deskcomm-contribuir: ela mede o que a triagem mede (branch atrasada, tripla de
+migration, marca do fork no diff, fragmento de release) e evita retrabalho. $estado_hooks.
+Guias para outras situações: deskcomm-instalar, deskcomm-cliente-novo, deskcomm-metricas, deskcomm-prompt.
+TXT
+exit 0
@@ -0,0 +1,16 @@
+{
+  "$comment": "Codex só roda hooks do repositório depois que a pessoa os aprova em /hooks (trust por hash). Este imprime um lembrete de início de sessão apenas em clone de contribuidor — ver .agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -0,0 +1,20 @@
+---
+description: Guias do assistente do DeskcommCRM — quando usar cada um
+alwaysApply: true
+---
+
+Este repositório embute guias (skills em `.agents/skills/`) para cinco situações. Quando o pedido
+casar, carregue o guia antes de agir — a pessoa pode não saber que ele existe:
+
+- instalar, subir, atualizar, consertar a instalação numa VPS, domínio, Supabase, WhatsApp
+  que não conecta → `deskcomm-instalar`
+- configurar o CRM para um cliente ou nicho (clínica, imobiliária, serviços, curso, loja):
+  agentes, roteadores, follow-ups, base de conhecimento → `deskcomm-cliente-novo`
+- desempenho, conversão, custo de IA, funil, relatório, "o agente está vendendo?" → `deskcomm-metricas`
+- o agente responde errado, passa tudo para humano, não usa a agenda, melhorar o prompt → `deskcomm-prompt`
+- contribuir, corrigir um bug, abrir ou atualizar um PR, migration, conflito com a main → `deskcomm-contribuir`
+  (rode `bash .agents/skills/deskcomm-contribuir/scripts/quem-sou.sh` primeiro: se disser
+  `mantenedor`, este guia fica quieto)
+
+Escrevendo código aqui: `deskcomm-doutrina` (as regras que mais custam) e `sistema-vivo` (o gate
+de arquitetura). A doutrina completa é o `CLAUDE.md` da raiz; o contrato portável é o `AGENTS.md`.
@@ -63,6 +63,8 @@ supabase/.branches/
 .claude/*
 !.claude/agents/
 !.claude/commands/
+# settings.json: só o hook de início de sessão dos guias (fala apenas em clone de contribuidor)
+!.claude/settings.json
 # skills/: allowlist por PREFIXO — só as deste repo. Liberar a pasta inteira
 # arrastaria skills locais de outros apps (Lina etc.) para o versionamento.
 # `.claude/skills/` é ESPELHO gerado de `.agents/skills/` (fonte única, lida
@@ -252,6 +252,22 @@ sem: typecheck/lint zerados, testes relevantes verdes, RLS testada se tocou tabe
 tenant-aware, migration + baseline + MANIFEST se mudou schema, prova visual se mudou UI, e a
 regra de packaging acima se mudou o artefato que o self-hoster instala.

+## Guias do assistente (skills embutidas)
+
+O repositório embute guias em `.agents/skills/` — lidos por Codex, Cursor, OpenCode e
+Antigravity; o Claude Code lê o espelho em `.claude/skills/` (`pnpm skills:sync` regrava, e
+`tests/unit/skills-embutidas.test.ts` reprova divergência). Carregue o guia quando o pedido
+casar, mesmo que a pessoa não saiba que ele existe:
+
+| situação | guia |
+|---|---|
+| instalar, atualizar ou consertar a instalação numa VPS; domínio, Supabase, WhatsApp que não conecta | `deskcomm-instalar` |
+| configurar o CRM para um cliente ou nicho: agentes, roteadores, follow-ups, base de conhecimento | `deskcomm-cliente-novo` |
+| desempenho, conversão, custo de IA, funil, relatório | `deskcomm-metricas` |
+| o agente responde errado, passa tudo para humano, não usa a agenda; melhorar o prompt | `deskcomm-prompt` |
+| contribuir: corrigir bug, abrir ou atualizar PR, migration, conflito com a `main` | `deskcomm-contribuir` — que fica quieto quando `bash .agents/skills/deskcomm-contribuir/scripts/quem-sou.sh` responde `mantenedor` |
+| escrever ou revisar código aqui | `deskcomm-doutrina` (as três regras que mais custam) e `sistema-vivo` (o gate de arquitetura) |
+
 ## Regra final — não invente

 Este repositório tem PRDs, specs, regras de negócio e doutrina escritos
@@ -445,6 +445,16 @@ Processo padrão (siga sempre):

 ## Skills relevantes a usar (Claude Code)

+**Guias embutidos neste repositório** (`.claude/skills/`, espelho gerado de `.agents/skills/` — a
+mesma tabela vale para Codex, Cursor, OpenCode e Antigravity; ver `AGENTS.md`):
+
+- `deskcomm-instalar` — instalar, atualizar ou consertar a instalação numa VPS
+- `deskcomm-cliente-novo` — configurar o CRM para um cliente ou nicho (agentes, roteadores, follow-ups, conhecimento)
+- `deskcomm-metricas` — desempenho, conversão, custo de IA, funil, relatório
+- `deskcomm-prompt` — afinar o prompt de um agente que não performa
+- `deskcomm-contribuir` — o espelho da triagem, antes do PR; fica quieto para o mantenedor
+- `deskcomm-doutrina` — as três regras que mais custam, antes de escrever código
+
 - `superpowers:brainstorming` — antes de implementar feature não-trivial
 - `superpowers:writing-plans` — pra task com mais de 1 etapa de DB/API
 - `superpowers:test-driven-development` — feature crítica (LGPD, RLS, anti-banimento)
@@ -2,6 +2,10 @@

 ## Antes de começar

+0. Abra o repositório no seu assistente de código (Claude Code, Codex, Cursor, OpenCode ou
+   Antigravity): o guia `deskcomm-contribuir` (`.agents/skills/deskcomm-contribuir/SKILL.md`) mede
+   antes do PR o que a triagem mede depois — branch atrasada, tripla de migration, marca do fork no
+   diff, fragmento de release — e arma os hooks de git com `bash .agents/skills/deskcomm-contribuir/scripts/armar-hooks.sh`.
 1. Leia [`CLAUDE.md`](CLAUDE.md) — convenções não-negociáveis.
 2. Leia [`ARCHITECTURE.md`](ARCHITECTURE.md) — visão de 1 página.
 3. Identifique o epic de origem em [`docs/stories/epics/MASTER.md`](docs/stories/epics/MASTER.md).
@@ -133,6 +133,11 @@ Jogue a pasta `hostgator-setup-kit/` no chat do **Claude Code** rodando dentro d

 Saiu versão nova? Há dois caminhos, e o primeiro **não exige terminal**.

+Com o repositório clonado, o **guia de instalação** já vem dentro — `.agents/skills/deskcomm-instalar/` —
+e carrega sozinho no Claude Code, Codex, Cursor, OpenCode ou Antigravity aberto na pasta. Diga só
+*"quero instalar o CRM na minha VPS"*. Há guias também para montar um cliente por nicho, analisar
+métricas, afinar o prompt do agente e contribuir (`AGENTS.md`, seção "Guias do assistente").
+
 ### Pela tela (recomendado)

 Quando existe versão nova, o rodapé do menu lateral acende **"Nova versão"** — só pro dono do
@@ -38,6 +38,7 @@ de menor precedência e registre.
 | [`CONTRIBUTING.md`](../CONTRIBUTING.md) | Como contribuir |
 | [`CHANGELOG.md`](../CHANGELOG.md) | Mudanças por versão (SemVer). **Quem roda VPS lê antes de `update.sh`** — mudança que exige ação manual aparece sob "⚠️ Requer atenção" |
 | [`docs/current-state.md`](current-state.md) | **O que está pronto, incompleto e quebrado hoje** |
+| [`.agents/skills/`](../.agents/skills/deskcomm-instalar/SKILL.md) | **Guias do assistente** — instalar, montar cliente por nicho, métricas, prompt, contribuir. Skills lidas por Claude Code, Codex, Cursor, OpenCode e Antigravity (não confundir com as *Skills* do agente de IA, na tela IA › Skills) |

 ## 2. Produto e intenção

@@ -19,11 +19,13 @@ Este kit sobe o **DeskcommCRM** no seu servidor VPS da HostGator. Você tem dois
 > de tentar subir um Caddy que não caberia. Ver
 > [VPS que já vem com proxy próprio](#vps-que-já-vem-com-proxy-próprio-hostinger-coolify-dokploy).

-## 🤖 Caminho fácil: deixe o Claude Code fazer
+## 🤖 Caminho fácil: deixe o assistente de código fazer

 1. Contrate um **VPS na HostGator** e acesse-o por SSH.
-2. Jogue esta pasta (ou o `.zip`) no chat do **Claude Code** rodando dentro do VPS.
-3. Diga: *"instala o DeskcommCRM pra mim"*. Ele lê o `CLAUDE.md` e conduz tudo —
+2. Clone o repositório (`git clone --depth 1 https://github.com/melgarafael/DeskcommCRM.git deskcommcrm`)
+   e abra a pasta no **Claude Code, Codex, Cursor, OpenCode ou Antigravity** dentro do VPS —
+   ou jogue só esta pasta no chat: o `CLAUDE.md` daqui manda clonar e abre o guia.
+3. Diga: *"instala o DeskcommCRM pra mim"*. O guia `deskcomm-instalar` conduz tudo —
   cria o banco, gera as senhas, sobe o CRM e te ajuda a conectar o WhatsApp.

 ## ⚙️ Caminho manual: um comando
@@ -134,6 +134,20 @@ git switch -q main 2>/dev/null
 saida="$(bash .agents/skills/deskcomm-contribuir/scripts/pre-voo.sh 2>&1)"
 assert_contains "$saida" "você está na 'main'" "na main, manda abrir branch"

+echo "6. sessao.sh (hook de início de sessão)"
+clone="$TMP/c6"; clonar "$clone" "alguem@fork.dev"; git -C "$clone" config --unset core.hooksPath
+saida="$(cd "$clone" && bash .agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh)"; code=$?
+assert_exit "$code" 0 "sai com 0"
+assert_contains "$saida" "clone é de um contribuidor" "contribuidor recebe o lembrete"
+assert_contains "$saida" "NÃO armados" "diz que os hooks não estão armados"
+git -C "$clone" config core.hooksPath ".agents/skills/deskcomm-contribuir/scripts/hooks"
+saida="$(cd "$clone" && bash .agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh)"
+assert_contains "$saida" "contribuidor armados" "com hooks armados, diz que estão"
+git -C "$clone" config user.email "rafael@maudibrasil.com.br"
+saida="$(cd "$clone" && bash .agents/skills/deskcomm-contribuir/scripts/hooks/sessao.sh)"; code=$?
+assert_exit "$code" 0 "mantenedor: sai com 0"
+if [ -z "$saida" ]; then ok "mantenedor: silêncio total"; else falha "mantenedor: silêncio total" "saída: $saida"; fi
+
 echo
 if [ "$falhas" = 0 ]; then echo "deskcomm-contribuir: $casos casos, todos verdes"; exit 0
 else echo "deskcomm-contribuir: $falhas de $casos casos vermelhos"; exit 1; fi
@@ -148,6 +148,33 @@ describe("skills embutidas — o espelho de Claude é fiel à fonte", () => {
  });
 });

+describe("skills embutidas — as portas de acionamento conhecem todas as skills", () => {
+  // O acionamento automático depende de a descrição estar no contexto (os cinco
+  // CLIs fazem isso) E de a doutrina que cada CLI lê apontar para a skill certa:
+  // AGENTS.md (Codex, OpenCode, Cursor), CLAUDE.md (Claude Code), a rule
+  // sempre-ativa do Cursor e a do Antigravity. Uma skill nova que entre só na
+  // pasta fica invisível para quem não sabe que ela existe — que é o leigo.
+  const PORTAS = ["AGENTS.md", "CLAUDE.md", ".cursor/rules/deskcomm-guias.mdc", ".agents/rules/deskcomm-guias.md"];
+  const guias = SKILLS.filter((n) => n.startsWith("deskcomm-"));
+
+  it.each(PORTAS)("%s cita cada guia deskcomm-*", (porta) => {
+    const texto = readFileSync(join(RAIZ, porta), "utf8");
+    const ausentes = guias.filter((n) => !texto.includes(n));
+    expect(ausentes, `${porta} não menciona: ${ausentes.join(", ")}`).toEqual([]);
+  });
+
+  it("a regra do Cursor e a do Antigravity têm o mesmo corpo (só o cabeçalho muda)", () => {
+    const corpo = (p: string) => readFileSync(join(RAIZ, p), "utf8").split("\n---\n").slice(1).join("\n---\n").trim();
+    expect(corpo(".cursor/rules/deskcomm-guias.mdc")).toBe(corpo(".agents/rules/deskcomm-guias.md"));
+  });
+
+  it.each([".claude/settings.json", ".codex/hooks.json"])("%s é JSON válido e aponta para o hook de sessão", (arquivo) => {
+    const json = JSON.parse(readFileSync(join(RAIZ, arquivo), "utf8")) as { hooks?: { SessionStart?: unknown[] } };
+    expect(json.hooks?.SessionStart?.length ?? 0).toBeGreaterThan(0);
+    expect(JSON.stringify(json)).toContain("deskcomm-contribuir/scripts/hooks/sessao.sh");
+  });
+});
+
 describe("skills embutidas — fora da imagem Docker", () => {
  it(".dockerignore exclui as pastas de harness", () => {
    const linhas = readFileSync(join(RAIZ, ".dockerignore"), "utf8")