Criar uma extensão do DeskcommCRM

Alguém chega com uma ideia de nicho — comanda de barbearia, comissão de vendedor, um roteiro de pós-atendimento de clínica — e o instinto é abrir um PR no núcleo, acrescentando um campo, uma aba, uma regra. O núcleo precisa continuar útil com zero extensões: é isso que mantém o produto genérico enquanto os nichos ganham espaço. Este guia é para onde a triagem manda quem chegou por ali, e para quem já sabe que quer criar um pacote.

A lei é docs/doctrine/extensoes.md. O contrato em vigor é lib/extensions/manifest.ts e lib/extensions/capacidades.ts. Quando este guia e o código discordarem, o código está certo — e todo número aqui vem com o comando que o revela.

Como você age

• Primeiro classifica, depois ensina. Metade do que chega como "extensão" é núcleo, e a outra metade é uma jornada que o formato atual ainda não constrói. Mandar alguém escrever um pacote que não pode existir custa mais que uma resposta desconfortável.
• Não anuncia o que não existe. Não há SDK, execução de código de terceiro, marketplace público, avaliação nem contador de downloads. A lei proíbe prometer os quatro antes da prova (não-negociável 11), e prometer a alguém que vai investir uma semana é a pior forma de prometer.
• Mede na fonte. Limite, vocabulário e versão do host saem de lib/extensions/, nunca de memória.
• Preserva o trabalho de quem chegou. "Isto não cabe hoje" vem sempre com o que fazer com o que já foi feito.

Passo 1 — isto é núcleo ou extensão?

A pergunta que decide, e ela não é "isto serve a muita gente?":

Se nenhuma organização desta instalação ativar isto, a operação comum continua inteira?

Sim → pode ser extensão. Não, porque identidade, autorização, isolamento, auditoria, contratos ou a cadeia de envio dependem disto → é núcleo.

Núcleo	Extensão
contatos, conversas, funis, agenda	comanda, comissão, fidelidade
papéis, permissão, isolamento entre organizações	tema visual, roteiro de um método de vendas
auditoria, recibos, cadeia de envio, opt-out	integração com um ERP de um segmento só
caixa: contas, formas de pagamento, plano de contas, lançamento avulso (decisão do dono, não dedução)	o que fica em cima do caixa
corrigir comportamento que já foi distribuído	jornada adicional que ninguém precisa ligar

Os dois lados com mais exemplos, o destino "ambos" e o que fazer quando a régua diz extensão mas a ferramenta ainda não existe: references/decidir-nucleo-ou-extensao.md.

Passo 2 — o que uma extensão consegue fazer hoje

O que ela faz: publica até 4 cards de orientação no hub do CRM. Cada card tem título, descrição, blocos de texto e um botão, e esse botão abre uma tela que o CRM já tem. Quem administra a instalação admite o catálogo e instala; quem administra a organização ativa e configura (densidade e mostrar descrição); quem usa lê e clica, dentro do acesso que já tinha. As telas alcançáveis são seis: Tarefas, Conversas, Funil, Contatos, Agenda e Radar.

O que ela não faz — e nenhuma dessas é "ainda não implementei":

Não existe	Por quê
Código. O pacote é JSON. Sem JavaScript, SQL, shell, expressão	não há executor isolado; a escolha dele é por evidência, e ainda não foi feita
Tabela ou qualquer dado próprio (data só aceita {"mode":"none"})	módulo nativo com tabelas é a ADR-0002, aceita em 17/09/2026 e não construída
Tela, rota ou item de menu	mesma ADR-0002
Ferramenta, instrução ou prompt do agente de IA	recusado por escrito na ADR-0003: o motor de instruções caminha pelo conteúdo da sessão, e deixar o pacote escolher o caminho é leitura do que não é dele
Endereço livre (href, prefixo, destino próprio)	alcançaria as telas onde a instalação guarda segredo com todos os testes verdes. Recusado para sempre
Imagem, captura de tela, URL de qualquer tipo	endereço clicável dentro de pacote de terceiro é porta de engano; o ícone sai de uma lista de três
Ler dado do CRM — tarefa, conversa, contato	a capacidade abre uma porta que o núcleo já tem, com a autorização de sempre; ela não concede leitura
Depender de outra extensão	dependencies é []
Marketplace, avaliação, download contado, telemetria	não existem, e a lei proíbe anunciá-los antes da prova

Se a sua ideia precisa de uma linha desta tabela, pare aqui e vá para o Passo 6.

Passo 3 — escreva o pacote

Comece pelo exemplo válido: references/pacote-de-exemplo.json — um roteiro de clínica com dois cards, que usa duas portas (Conversas e Agenda). Copie, troque os textos e os slugs, valide.

O esqueleto, com o que cada campo cobra:

{
  "format_version": 1, "profile": "declarative",
  "publisher": "slug-minusculo", "name": "slug-minusculo", "version": "1.0.0", "license": "MIT",
  "host_api": { "min": 2, "max": 2 },
  "permissions": ["navigation.inbox", "navigation.agenda"],
  "dependencies": [], "data": { "mode": "none" },
  "display": { "title": {…}, "summary": {…}, "category": "service", "icon": "ListChecks" },
  "configuration": { "density": "comfortable", "show_description": true },
  "contributions": { "crm_cards": [ { "id": "…", "action": { "capability": "inbox.open" } } ] }
}

As três regras que mais recusam pacote:

1. Chave desconhecida recusa o pacote inteiro. Autoria, site, etiqueta e imagem não moram no manifesto — são metadado de catálogo, o artefato que passa por revisão (ADR-0003, D3).
2. Toda capacidade usada tem de estar coberta por uma permissão declarada. Usar inbox.open sem declarar navigation.inbox é recusado na instalação, na ativação e na leitura: a lista de permissões é o que a tela mostra antes de alguém aceitar a extensão.
3. host_api é a janela que você garante. Um pacote que usa as portas novas declara min 2. Confira o host: grep -n "HOST_API_VERSION =" lib/extensions/manifest.ts.

Campo a campo, com os limites e o formato do texto localizado: references/contrato-do-pacote.md. O exemplo explicado, com o que é decisão sua e o que é obrigação: references/exemplo-comentado.md. Quando o parser recusar e não disser por quê: references/erros-do-pacote.md.

Passo 4 — valide antes de enviar

bash .agents/skills/deskcomm-extensao/scripts/validar-pacote.sh caminho/do/pacote.json

Roda parseManifest() e checkCompatibility() do host — não uma cópia das regras — e, quando passa, imprime a entrada de catálogo com sha256 e byte_length calculados dos seus bytes. Sai 1 quando recusa.

Passar aqui é o piso: o schema não julga se o card vale uma instalação. Os degraus seguintes — o catálogo de ensaio local e a prova pela tela — estão em references/testar-local.md, com a ressalva medida sobre o laboratório, que carrega a própria cópia das regras e pode estar atrás do contrato.

Passo 5 — envie

Por pull request, com revisão humana. Merge não publica: validação automática e revisão proporcional ao perfil antecedem a publicação, e teste verde não é selo.

No corpo do PR: o que a extensão faz em duas frases, para qual nicho, quais portas abre e por quê, a saída do validador (o comando e o resultado, não a conclusão), o destino declarado — "extensão", com a razão medida pela pergunta-raiz, que é o item 18 do Definition of Done — e o que você não mediu. A mecânica de PR deste repositório (branch, identidade, fragmento em .changes/) está na skill deskcomm-contribuir; carregue-a antes de abrir.

O que a revisão olha, em ordem, e o que acontece depois de publicado (nenhuma origem desliga uma extensão numa VPS em silêncio): references/enviar-e-revisao.md.

Usar na sua própria instalação não pede permissão de ninguém — pacote seu, catálogo seu, admitido pela tela. O PR é só para entrar no catálogo oficial.

Passo 6 — o meu caso não cabe no formato

Acontece com a maioria das boas ideias, e a resposta honesta vale mais que um encaminhamento simpático. Na ordem:

1. Precisa guardar dado, ter tela própria ou entrar no menu? O caminho é o módulo nativo da ADR-0002 — tabelas criadas por uma função provisionadora quando o módulo é instalado na instância. Ela foi aceita em 17/09/2026 e ainda não foi construída. Não há data, e este guia não inventa uma.
2. Parte do seu trabalho é genérica e o núcleo já usa hoje? Essa parte entra pelo caminho normal de PR, separada do resto.
3. O que sobra é conteúdo — orientação, roteiro, sequência de passos? Isso é empacotável hoje. Volte ao Passo 3.
4. Nada disso? Abra uma issue descrevendo a jornada inteira e o que ela precisa guardar. A doutrina é explícita: enquanto a plataforma está em construção, "extensão" é destino, não exigência de usar uma ferramenta que ainda não existe — o trabalho se preserva e a dependência se registra.

O que você nunca faz

• Prometer SDK, execução de código, marketplace público, avaliações ou downloads — nem "em breve".
• Inventar um caminho de pasta para o pacote no repositório: onde a loja mora ainda não está decidido (ADR-0003, "o que esta ADR não decide").
• Sugerir que o contribuidor amplie o perfil declarativo por dentro para caber o caso dele. Quem propõe um item da coluna "ainda não existe" segue a coluna "o que pede antes", que é prova.
• Recomendar que alguém extraia do núcleo um recurso já distribuído porque "seria extensão": isso exige equivalência demonstrada e migração explícita.
• Aceitar publisher que se parece com marca alheia, ou texto que descreve uma extensão que o pacote não é.