Workflow: Novo Cliente

Playbook executável para criar um novo cliente (tenant) na plataforma Triadeflow. Claude Code deve seguir este workflow passo a passo quando o Alex pedir para criar um novo cliente.

Quando usar este workflow

Use este playbook quando o Alex disser algo como:

“Cria um novo cliente”
“Adiciona o tenant X”
“Onboarding novo do cliente Y”
/novo-cliente NOME

Pré-requisitos

Antes de iniciar, confirme com o Alex que você tem:

Nome do cliente final (ex: “Dra. Camila Borges”)
Tipo de agente (sdr, vendas, suporte, agendamento, recuperacao, cobranca, pos-venda)
Nicho (saude, beleza, educacao, ecommerce, b2b-servicos, saas, infoproduto)
Provider de mensageria (evolution para Kommo, stevo para GHL)
Integrações específicas (calendário, gateway de pagamento, ERP, etc)

Se faltar alguma informação, pergunte UMA por vez. Não dispare 5 perguntas de uma vez.

Passo 1: Validar contexto

Confirme em uma frase curta o que você entendeu:

"Entendi: cliente Dra. Camila Borges, agent-agendamento, nicho saúde,
 provider Evolution (Kommo), integração com Doctoralia. Confirma?"

Aguarde confirmação antes de prosseguir.

Passo 2: Definir tenant_id

Padronização do tenant_id:

Lowercase
Apenas letras, números e hífen
Sem acentos
3-32 caracteres
Inicia com letra

Exemplos corretos:

Dra. Camila Borges → dra-camila-borges
USA Salus → usa-salus
Petisco Alimentos → petisco-alimentos
Reverso Academy → reverso-academy

Confirme o tenant_id proposto com o Alex antes de criar.

Passo 3: Estrutura de pastas

Cria a estrutura padrão dentro do repositório do agente correspondente:

cd ~/triadeflow/agent-{tipo}/
mkdir -p tenants/{tenant_id}/{kb,assets}
touch tenants/{tenant_id}/config.yaml

Estrutura esperada:

agent-{tipo}/
└── tenants/
    └── {tenant_id}/
        ├── config.yaml
        ├── kb/                   # base de conhecimento (será vetorizada)
        │   ├── empresa.md
        │   ├── produtos.md
        │   ├── faq.md
        │   └── politicas.md
        └── assets/
            ├── logo.png
            └── catalogo.pdf

Passo 4: Gerar config.yaml

Use o template em .claude/examples/tenants/_template.yaml e preencha. Estrutura obrigatória:

tenant_id: {tenant_id}
agent_type: {tipo}
created_at: {data ISO}

agente:
  nome: "Assistente {Nome}"
  empresa: "{Nome do Cliente}"
  contexto_negocio: |
    {2-3 parágrafos descrevendo a empresa, o que faz, público-alvo}
  objetivo_principal: |
    {O que o agente deve realizar - 1 frase clara}

modelo:
  principal: claude-sonnet-4-20250514
  fallback: claude-haiku-4-5-20251001
  estruturadas: claude-haiku-4-5-20251001
  temperatura: 0.7
  max_tokens: 1024

messaging:
  provider: {evolution|stevo}
  instance_name: {tenant_id}-prod
  webhook_secret: ${{TENANT_NAME_UPPER}_WEBHOOK_SECRET}

crm:
  type: {kommo|ghl}
  base_url: {url do CRM}
  api_token: ${{TENANT_NAME_UPPER}_CRM_TOKEN}
  pipeline_id: {id_pipeline}
  stage_qualified: {id_stage}
  stage_lost: {id_stage}

rag:
  collection: {tenant_id}
  top_k: 5
  rerank: false
  threshold: 0.7

memory:
  redis_prefix: {tenant_id}
  short_term_size: 10
  summarize_after: 10
  ttl_hours: 168  # 7 dias

tools_enabled:
  - consultar_kb
  - handoff_humano
  # ... específicas do tipo de agente

horario:
  timezone: America/Sao_Paulo
  inicio: "08:00"
  fim: "20:00"
  dias_semana: [MON, TUE, WED, THU, FRI, SAT]

handoff:
  triggers_keywords: ["humano", "atendente", "falar com pessoa"]
  triggers_sentiment: negative_strong
  max_tentativas: 3
  destino: {kommo_user_id|ghl_user_id}

qualificacao:
  metodo: {bant|spin|custom}
  campos_obrigatorios:
    - {campo1}
    - {campo2}

langfuse:
  enabled: true
  tags:
    - {tipo}
    - {nicho}

compliance:
  lgpd: true
  retention_days: 90
  consent_required: true

features:
  voice_messages: false
  media_attachments: true
  group_messaging: false

limites:
  max_messages_por_dia: 1000
  max_custo_usd_por_dia: 50
  alert_threshold_pct: 80

triadeflow:
  partner: {parceira_id|null}
  white_label: false
  contract_start: {data ISO}
  monthly_fee_brl: {valor}
  tier: {1|2|3|4}

Sempre aplicar o playbook do nicho (.claude/playbooks/{nicho}.md) sobre o template — ele já vem com tom, qualificação e compliance específicos do setor.

Passo 5: Configurar variáveis de ambiente

Para cada ${VAR} no config, adicione ao .env do agente:

# Padrão: TENANT_UPPERCASE_PROPOSITO
DRA_CAMILA_BORGES_WEBHOOK_SECRET=...
DRA_CAMILA_BORGES_CRM_TOKEN=...
DRA_CAMILA_BORGES_DOCTORALIA_API=...

Nunca comite .env. Use .env.example como template versionado.

Passo 6: Criar knowledge base

Estrutura mínima de KB em tenants/{tenant_id}/kb/:

`empresa.md`

Nome, fundação, fundadores
Missão, visão, valores
Diferenciais
História resumida

`produtos.md` (ou `servicos.md`)

Cada produto/serviço com nome, descrição, preço, público-alvo
Casos de uso
Diferenciais vs concorrência

`faq.md`

20-50 perguntas mais comuns
Respostas em primeira pessoa do agente
Linguagem do público-alvo

`politicas.md`

Política de cancelamento
Política de reembolso
Política de troca
Termos relevantes

`casos.md` (opcional, alta conversão)

5-10 casos de sucesso reais (com permissão)
Antes/depois
Métricas concretas

Passo 7: Vetorizar a KB

Rode o script de ingestão:

cd ~/triadeflow/agent-{tipo}/
python scripts/ingest_kb.py --tenant {tenant_id}

O script:

Lê todos .md em tenants/{tenant_id}/kb/
Chunking por seção (500-800 tokens por chunk)
Gera embeddings com OpenAI text-embedding-3-small
Sobe para Qdrant na collection {tenant_id}
Loga no Langfuse o resultado da ingestão

Validar: query de teste deve retornar resultados relevantes.

python scripts/test_rag.py --tenant {tenant_id} --query "qual o horário de atendimento"

Passo 8: Adaptar system prompt

System prompt herda do template do agente + playbook do nicho + dados do tenant. Não escreva do zero.

# O renderer compila automaticamente:
python scripts/render_prompt.py --tenant {tenant_id}

Saída: tenants/{tenant_id}/_compiled/system_prompt.md — para revisão antes de promover.

Sempre revise o prompt compilado com o Alex antes de subir. 5 minutos de revisão evitam horas de iteração depois.

Passo 9: Configurar mensageria

Para Evolution API (Kommo)

# Cria instância na Evolution
curl -X POST https://evolution.triadeflow.com/instance/create \
  -H "apikey: ${EVOLUTION_API_KEY}" \
  -d '{
    "instanceName": "{tenant_id}-prod",
    "qrcode": true,
    "webhook": {
      "url": "https://{tipo}.triadeflow.com/webhook/{tenant_id}",
      "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"]
    }
  }'

QR code é enviado para o cliente conectar o WhatsApp.

Para Stevo (GHL)

# Configurar webhook no GHL apontando para:
# https://{tipo}.triadeflow.com/webhook/{tenant_id}
# Provider: stevo (já abstraído no código)

Passo 10: Configurar CRM

Kommo

Criar pipeline (se não existir)
Criar stages: Inbound, Qualificado, Agendado, Convertido, Perdido
Anotar IDs e adicionar ao config.yaml
Criar custom fields se necessário (e.g. convenio, urgencia)
Adicionar webhook do agente para eventos relevantes

GHL (GoHighLevel)

Criar funil correspondente
Mapear stages no config.yaml
Criar custom values e contact fields
Configurar workflow de notificação humana

Detalhes em .claude/integrations/{kommo|ghl}.md.

Passo 11: Integrações específicas

Para cada integração externa, ver .claude/integrations/:

Doctoralia: .claude/integrations/doctoralia.md
Google Calendar: .claude/integrations/google-calendar.md
Stripe/Asaas: .claude/integrations/stripe-asaas.md
Bling/Tiny: .claude/integrations/erps.md

Cada integração tem seu próprio handler em src/integrations/ que é instanciado se ativado no config.yaml.

Passo 12: Validação local

Antes de subir para produção, rodar testes locais:

# Testar config
python scripts/validate_config.py --tenant {tenant_id}

# Rodar agente em modo dev
TENANT_ID={tenant_id} make dev

# Em outro terminal, simular webhook
python scripts/simulate_message.py \
  --tenant {tenant_id} \
  --message "Olá, gostaria de saber mais sobre o serviço"

Esperado: agente responde em < 3s, com tom adequado ao playbook do nicho.

Passo 13: Eval do tenant

Rodar dataset de eval específico ou genérico:

python scripts/run_eval.py \
  --tenant {tenant_id} \
  --dataset eval/datasets/golden.json \
  --max-cases 20

Critério de aprovação:

Score médio LLM-as-judge > 0.85
Zero hallucinations em casos críticos (preço, política, agendamento)
Latência p95 < 4s
Custo médio por conversa < limite definido no playbook

Se reprovar, ajustar prompt/RAG e re-rodar.

Passo 14: Deploy

# Deploy do agente para Hetzner
make deploy ENV=prod TENANT={tenant_id}

# Validar saúde
curl https://{tipo}.triadeflow.com/health/{tenant_id}

Ver .claude/workflows/deploy.md para detalhes.

Passo 15: Documentação

Criar documentação de operação no Notion:

# Via MCP Notion
"Cria página no Notion 'Cliente: {Nome}' em /Triadeflow/Clientes/
 com: tenant_id, agente, integrações ativas, contatos do cliente,
 link do dashboard, link do Langfuse"

Estrutura sugerida da página:

Identificação: tenant_id, agent_type, nicho, parceira
Contatos: cliente final + contato técnico
Integrações: lista com status de cada uma
Acessos: link Langfuse, link CRM, link dashboard cliente
SLA: horário, tempo de resposta acordado
Comercial: mensalidade, contrato, vigência
Histórico: log de mudanças significativas

Passo 16: Asana — projeto de implantação

Criar projeto no Asana via MCP para acompanhar implantação:

"Cria projeto Asana 'Implantação: {Nome}' no time TDI com:
 - Seção 'Discovery' (tarefas: confirmar escopo, coletar materiais, validar integrações)
 - Seção 'Implementação' (tarefas: setup tenant, ingerir KB, deploy)
 - Seção 'Homologação' (tarefas: testes, ajustes, aprovação cliente)
 - Seção 'Go-live' (tarefas: ativação, monitoramento 7 dias)
 - Owner: Alex Campos
 - Due dates: baseado no cronograma TDI"

Passo 17: Comunicação ao cliente

Gerar e enviar para o Alex:

Email de boas-vindas com link do dashboard, primeiros passos
Cronograma de implantação com datas
Lista de materiais que precisamos do cliente (se ainda não tem tudo)

Templates em .claude/examples/comunicacao/.

Passo 18: Monitoramento das primeiras 72h

Nos primeiros 3 dias após go-live, monitorar de perto:

Custo real vs estimado
CSAT inicial
Taxa de erro
Casos que viraram handoff humano (proporção)
Mensagens onde o agente não soube responder

Ajustes finos no prompt e RAG nessa janela são esperados e bem-vindos.

Checklist final

Ao concluir, confirme:

Saída para o Alex

Ao concluir, retorne resumo neste formato:

✓ Cliente {Nome} criado e em produção

Tenant ID: {tenant_id}
Agente: {tipo}
Nicho: {nicho}
Provider: {evolution|stevo}

Arquivos criados:
- {caminho1}
- {caminho2}
...

Documentação:
- Notion: {link}
- Asana: {link}
- Langfuse: {link}

Próximos passos recomendados:
1. {passo1}
2. {passo2}
3. {passo3}

Pontos de atenção identificados:
- {ponto1, se houver}
- {ponto2, se houver}

Sem emojis, exceto o ✓ inicial se concluído com sucesso.

Erros comuns a evitar

Tenant_id mal formatado — só lowercase, hífen, sem acento
Esquecer de adicionar ao .env — config aponta para variável que não existe
KB rasa — menos de 4 documentos compromete qualidade
System prompt sem revisão — sempre revisar com Alex antes de promover
Pular eval — promover sem testar é receita pra cliente insatisfeito
Não documentar no Notion — knowledge fica só na sua cabeça e some

Versão: 1.0 Workflow relacionado: .claude/workflows/deploy.md, .claude/workflows/otimizar-custo.md