Bots do Telegram — Guia do Usuário

Arc OS usa uma arquitetura de bots Telegram em dois níveis: um Master Bot gerencia todos os projetos, e cada projeto recebe seu próprio Child Bot com workers de IA.

Visão Geral da Arquitetura

O sistema é construído em dois níveis:

Master Bot ("O Chefe") — orquestrador, sem IA. Gerencia o ciclo de vida de todos os projetos: criação, remoção, monitoramento de saúde, deploy, parada de emergência.
Child Bot — um por projeto. Proxy entre Telegram e Claude CLI. Contém workers de IA (Consultant, Developer, customizados), processa mensagens e mantém o contexto do diálogo.

Como Funciona

Telegram-канал:
  Usuário → Telegram → Child Bot → Claude CLI → Resposta → Telegram

CRM Dashboard:
  Usuário → CRM → crm_inbox.jsonl → Child Bot (polling 500ms) → Claude CLI → Resposta → Telegram + CRM

O Child Bot faz polling do arquivo crm_inbox.jsonl a cada 500ms, então mensagens do CRM Dashboard são processadas quase instantaneamente.

Comandos do Master Bot

Comando	Descrição
`/start`	Mostrar lista de comandos disponíveis
`/status`	Status de todos os projetos: threads ativas, uptime, uso de recursos
`/list`	Lista de todos os child bots com indicadores de saúde (🟢/🔴)
`/health`	Matriz de saúde: estado do Bot, bridge, sessões tmux para cada projeto
`/deploy <name\|all>`	Git pull + restart para um projeto específico ou todos de uma vez
`/new_project <name>`	Inicia o onboarding de um novo projeto (cria child bot, tmux, configurações)
`/remove_project <name>`	Remove o projeto com confirmação (botão inline "Sim, remover")
`/emergency_stop`	Parada em cascata de 3 níveis: SIGINT → `/exit` → SIGKILL. Para tudo.
`/watchdog`	Monitoramento de child bots: restart automático se o bot não responder
`/cancel`	Cancela a operação ativa atual (deploy, onboarding etc.)

Comandos do Child Bot

Prefixos Principais

Prefixo	Worker	Modelo	Acesso
`/c <mensagem>`	Consultant	Sonnet	Read-only, consultor estratégico
`/d <mensagem>`	Developer	Opus	Acesso completo a arquivos e terminal
`/w:<worker_id> <mensagem>`	Worker customizado	Depende da configuração	Definido em `workers_registry.json`
(sem prefixo)	Worker ativo	—	Padrão — Consultant

Exemplo:

/c Analise a arquitetura do módulo auth
/d Corrija o bug no formulário de login
/w:sentinel Faça um security audit das últimas mudanças

Comandos de Informação

Comando	Descrição
`/ping`	Verificação de saúde do bot + uptime
`/thread`	Tamanho do histórico atual do diálogo (número de mensagens)
`/quality`	Métricas de qualidade: número de chamadas, feedback (👍/👎), duração média de resposta
`/learnings`	Lista de regras de correção acumuladas (learnings)
`/specs`	Lista de especificações com status (draft / review / approved)
`/approve <id>`	Aprovar especificação por ID
`/reject <id> [reason]`	Rejeitar especificação com motivo opcional

Botões Inline

Sob a Resposta do Worker

Após cada resposta do worker de IA, três linhas de botões aparecem:

Linha 1 — Controle do processo Claude:

Botão	Ação
🛑 STOP	Encerra o processo Claude (SIGKILL). Use se a resposta foi na direção errada ou travou.
⏸️ PAUSE	Pausa o processo Claude (SIGSTOP). Útil para aguardar algo antes de continuar.
▶️ RESUME	Retoma o processo pausado (SIGCONT).

Linha 2 — Contexto e feedback:

Botão	Ação
💡 BTW	Modo de coleta de contexto adicional. Suas próximas mensagens entram na fila e serão injetadas no próximo prompt GSD.
🛠️ Fix It	Reexecuta a tarefa com correções automáticas baseadas na resposta anterior.
👍	Feedback positivo — registrado nas métricas de qualidade.
👎	Feedback negativo — cria automaticamente uma learning rule que será injetada em cada próximo prompt do worker.

Linha 3 — Navegação:

Botão	Ação
🏷️ Skills	Mostrar lista de skills que foram usadas na resposta.
📊 View Log	Abrir o log desta sessão no CRM.

Botões do Master Bot

No card de cada projeto no Master Bot, os seguintes botões estão disponíveis:

Restart — reinicia o child bot
Delete — remove o projeto (com confirmação)
Manifest — mostra a configuração do projeto
Skills — lista as skills do projeto
Quality — métricas de qualidade
CRM — link para o CRM Dashboard

Contexto e Memória

O histórico do diálogo é salvo por worker (máximo de 50 entradas). Cada worker tem sua própria memória.
Reply em uma mensagem específica → o texto será injetado como CONTEXT no prompt do Claude.
O Context Router seleciona automaticamente as top-5 skills relevantes para sua mensagem.
Learnings de 👎 → injetados automaticamente em cada próximo prompt GSD, para que o worker não repita os erros.

Alternando Entre Workers

Cada Child Bot suporta múltiplos workers. O worker ativo é salvo no arquivo active_role.json.

/c — alterna para Consultant (Sonnet, análise read-only)
/d — alterna para Developer (Opus, acesso completo)
/w:<worker_id> — alterna para um worker customizado pelo seu ID

Mensagens sem prefixo vão para o worker ativo no momento. Se você enviou /d Corrija o bug, o Developer fica ativo — as próximas mensagens sem prefixo também irão para o Developer.

Integração com CRM

Telegram e CRM Dashboard são dois canais para o mesmo worker:

O CRM Dashboard escreve mensagens no arquivo crm_inbox.jsonl
O Child Bot faz polling desse arquivo a cada 500ms e processa novas mensagens
As respostas aparecem tanto no Telegram quanto no CRM ao mesmo tempo
Attachments (imagens, PDF) são suportados via CRM Dashboard

Isso significa que você pode iniciar um diálogo no Telegram, continuar no CRM e vice-versa — o contexto é mantido.

Troubleshooting

Problema	Solução
Bot não responde	Verifique `/health` no Master Bot. Se o child bot estiver 🔴 — clique em Restart ou use `/deploy <name>`. Verifique `/watchdog` para monitoramento automático.
Tempo de resposta longo	Alterne para o Consultant (`/c`) — ele usa Sonnet, que é mais rápido que Opus. Para perguntas simples, isso é suficiente.
Mensagem cortada	O Telegram tem limite de 4096 caracteres por mensagem. O bot divide automaticamente respostas longas em partes: `[1/3]`, `[2/3]`, `[3/3]`.
Bot responde lentamente via CRM	Verifique se a sessão tmux do child bot está ativa: `/health` deve mostrar tmux 🟢.
👎 não cria learning	Certifique-se de que você clicou em 👎 diretamente na resposta do worker, e não em uma mensagem do sistema.