Bots de Telegram — Guía de usuario

Arc OS utiliza una arquitectura de bots de Telegram de dos niveles: un Master Bot gestiona todos los proyectos, y cada proyecto tiene su propio Child Bot con workers de IA.

Visión general de la arquitectura

El sistema se estructura en dos niveles:

Master Bot ("El Jefe") — orquestador, sin IA. Gestiona el ciclo de vida de todos los proyectos: creación, eliminación, monitoreo de estado, deploy, parada de emergencia.
Child Bot — uno por proyecto. Proxy entre Telegram y Claude CLI. Contiene workers de IA (Consultant, Developer, personalizados), procesa mensajes y mantiene el contexto del diálogo.

Cómo funciona

Canal de Telegram:
  Usuario → Telegram → Child Bot → Claude CLI → Respuesta → Telegram

CRM Dashboard:
  Usuario → CRM → crm_inbox.jsonl → Child Bot (polling 500ms) → Claude CLI → Respuesta → Telegram + CRM

El Child Bot consulta constantemente el archivo crm_inbox.jsonl cada 500 ms, por lo que los mensajes del CRM Dashboard se procesan casi de inmediato.

Comandos del Master Bot

Comando	Descripción
`/start`	Muestra la lista de comandos disponibles
`/status`	Estado de todos los proyectos: hilos activos, uptime, uso de recursos
`/list`	Lista de todos los child bots con indicadores de estado (🟢/🔴)
`/health`	Matriz de estado: condición del Bot, Bridge, sesión tmux para cada proyecto
`/deploy <name\|all>`	Git pull + reinicio para un proyecto concreto o todos a la vez
`/new_project <name>`	Inicia el onboarding de un nuevo proyecto (crea child bot, tmux, configuración)
`/remove_project <name>`	Elimina un proyecto con confirmación (botón inline "Sí, eliminar")
`/emergency_stop`	Parada en cascada de 3 niveles: SIGINT → `/exit` → SIGKILL. Para todo.
`/watchdog`	Monitoreo de child bots: reinicio automático si el bot no responde
`/cancel`	Cancela la operación activa actual (deploy, onboarding, etc.)

Comandos del Child Bot

Prefijos principales

Prefijo	Worker	Modelo	Acceso
`/c <mensaje>`	Consultant	Sonnet	Solo lectura, asesor estratégico
`/d <mensaje>`	Developer	Opus	Acceso completo a archivos y terminal
`/w:<worker_id> <mensaje>`	Worker personalizado	Según configuración	Definido en `workers_registry.json`
(sin prefijo)	Worker activo	—	Por defecto — Consultant

Ejemplo:

/c Analiza la arquitectura del módulo auth
/d Corrige el bug en el formulario de login
/w:sentinel Realiza una auditoría de seguridad de los últimos cambios

Comandos de información

Comando	Descripción
`/ping`	Comprueba el estado del bot + uptime
`/thread`	Tamaño del historial de diálogo actual (número de mensajes)
`/quality`	Métricas de calidad: número de llamadas, feedback (👍/👎), duración media de respuesta
`/learnings`	Lista de reglas de corrección acumuladas (learnings)
`/specs`	Lista de especificaciones con estados (draft / review / approved)
`/approve <id>`	Aprobar una especificación por ID
`/reject <id> [reason]`	Rechazar una especificación con motivo opcional

Botones inline

Bajo la respuesta del worker

Después de cada respuesta de un worker de IA aparecen tres filas de botones:

Fila 1 — Control del proceso Claude:

Botón	Acción
🛑 STOP	Termina el proceso Claude (SIGKILL). Úsalo si la respuesta se desvía o se congela.
⏸️ PAUSE	Pausa el proceso Claude (SIGSTOP). Útil para esperar algo antes de continuar.
▶️ RESUME	Reanuda el proceso pausado (SIGCONT).

Fila 2 — Contexto y feedback:

Botón	Acción
💡 BTW	Modo de recopilación de contexto adicional. Tus siguientes mensajes van a la cola y se inyectarán en el próximo prompt GSD.
🛠️ Fix It	Vuelve a ejecutar la tarea con correcciones automáticas basadas en la respuesta anterior.
👍	Feedback positivo — se registra en las métricas de calidad.
👎	Feedback negativo — crea automáticamente una regla de learning que se inyectará en cada prompt futuro del worker.

Fila 3 — Navegación:

Botón	Acción
🏷️ Skills	Muestra la lista de skills que se usaron para generar la respuesta.
📊 View Log	Abre el log del CRM de esta sesión.

Botones del Master Bot

En la tarjeta de cada proyecto del Master Bot hay botones disponibles:

Restart — reinicia el child bot
Delete — elimina el proyecto (con confirmación)
Manifest — muestra la configuración del proyecto
Skills — lista de skills del proyecto
Quality — métricas de calidad
CRM — enlace al CRM Dashboard

Contexto y memoria

El historial del diálogo se guarda por worker (máximo 50 entradas). Cada worker tiene su propia memoria.
Reply a un mensaje concreto → su texto se inyecta como CONTEXT en el prompt de Claude.
El Context Router selecciona automáticamente las 5 skills más relevantes para tu mensaje.
Los Learnings de 👎 → se inyectan automáticamente en cada prompt GSD posterior, para que el worker no repita errores.

Cambio de workers

Cada Child Bot admite varios workers. El worker activo se guarda en el archivo active_role.json.

/c — cambia al Consultant (Sonnet, análisis de solo lectura)
/d — cambia al Developer (Opus, acceso completo)
/w:<worker_id> — cambia a un worker personalizado por su ID

Los mensajes sin prefijo van al worker activo en ese momento. Si enviaste /d Corrige el bug, Developer se vuelve activo — los mensajes siguientes sin prefijo también irán al Developer.

Conexión con el CRM

Telegram y el CRM Dashboard son dos canales hacia el mismo worker:

El CRM Dashboard escribe los mensajes en el archivo crm_inbox.jsonl
El Child Bot consulta ese archivo cada 500ms y procesa los mensajes nuevos
Las respuestas aparecen tanto en Telegram como en el CRM simultáneamente
Los archivos adjuntos (imágenes, PDF) se admiten a través del CRM Dashboard

Esto significa que puedes iniciar un diálogo en Telegram, continuarlo en el CRM y viceversa — el contexto se conserva.

Troubleshooting

Problema	Solución
El bot no responde	Comprueba `/health` en el Master Bot. Si el child bot está 🔴 — haz clic en Restart o usa `/deploy <name>`. Revisa `/watchdog` para el monitoreo automático.
Tiempo de respuesta largo	Cambia al Consultant (`/c`) — usa Sonnet, que es más rápido que Opus. Para preguntas simples es suficiente.
El mensaje se trunca	Telegram tiene un límite de 4.096 caracteres por mensaje. El bot divide automáticamente las respuestas largas en partes: `[1/3]`, `[2/3]`, `[3/3]`.
El bot responde lento desde el CRM	Verifica que la sesión tmux del child bot esté activa: `/health` debe mostrar tmux 🟢.
👎 no crea un learning	Asegúrate de haber pulsado 👎 justo bajo la respuesta del worker, no bajo un mensaje del sistema.