Bots Telegram — Guide utilisateur

Arc OS utilise une architecture de bots Telegram à deux niveaux : un Master Bot gère tous les projets, et chaque projet obtient son propre Child Bot avec des workers AI.

Vue d'ensemble de l'architecture

Le système repose sur deux niveaux :

Master Bot ("Le Boss") — orchestrateur, sans AI. Gère le cycle de vie de tous les projets : création, suppression, monitoring de santé, déploiement, arrêt d'urgence.
Child Bot — un par projet. Proxy entre Telegram et le CLI Claude. Contient des workers AI (Consultant, Developer, personnalisés), traite les messages, conserve le contexte de la conversation.

Comment ça fonctionne

Canal Telegram :
  Utilisateur → Telegram → Child Bot → Claude CLI → Réponse → Telegram

CRM Dashboard :
  Utilisateur → CRM → crm_inbox.jsonl → Child Bot (polling 500ms) → Claude CLI → Réponse → Telegram + CRM

Le Child Bot interroge en permanence le fichier crm_inbox.jsonl toutes les 500ms, donc les messages du CRM Dashboard sont traités presque instantanément.

Commandes du Master Bot

Commande	Description
`/start`	Afficher la liste des commandes disponibles
`/status`	Statut de tous les projets : threads actifs, uptime, utilisation des ressources
`/list`	Liste de tous les child bots avec indicateurs de santé (🟢/🔴)
`/health`	Matrice de santé : état Bot, Bridge, session tmux pour chaque projet
`/deploy <name\|all>`	Git pull + redémarrage pour un projet spécifique ou tous à la fois
`/new_project <name>`	Lancer l'onboarding d'un nouveau projet (création du child bot, tmux, configuration)
`/remove_project <name>`	Supprimer un projet avec confirmation (bouton inline "Oui, supprimer")
`/emergency_stop`	Arrêt en cascade à 3 niveaux : SIGINT → `/exit` → SIGKILL. Arrête tout.
`/watchdog`	Monitoring des child bots : redémarrage automatique si le bot ne répond pas
`/cancel`	Annuler l'opération active en cours (déploiement, onboarding, etc.)

Commandes du Child Bot

Préfixes principaux

Préfixe	Worker	Modèle	Accès
`/c <message>`	Consultant	Sonnet	Read-only, conseiller stratégique
`/d <message>`	Developer	Opus	Accès complet aux fichiers et au terminal
`/w:<worker_id> <message>`	Worker personnalisé	Selon la configuration	Défini dans `workers_registry.json`
(sans préfixe)	Worker actif	—	Par défaut — Consultant

Exemple :

/c Analyse l'architecture du module auth
/d Corrige le bug dans le formulaire de login
/w:sentinel Effectue un audit de sécurité des derniers changements

Commandes d'information

Commande	Description
`/ping`	Vérification de santé du bot + uptime
`/thread`	Taille de l'historique de conversation actuel (nombre de messages)
`/quality`	Métriques de qualité : nombre d'appels, feedback (👍/👎), durée moyenne de réponse
`/learnings`	Liste des règles de correction accumulées (learnings)
`/specs`	Liste des spécifications avec statuts (draft / review / approved)
`/approve <id>`	Approuver une spécification par ID
`/reject <id> [reason]`	Rejeter une spécification avec une raison optionnelle

Boutons inline

Sous la réponse du worker

Après chaque réponse du worker AI, trois rangées de boutons apparaissent :

Rangée 1 — Contrôle du processus Claude :

Bouton	Action
🛑 STOP	Tue le processus Claude (SIGKILL). Utilise ça si la réponse part dans la mauvaise direction ou est bloquée.
⏸️ PAUSE	Met en pause le processus Claude (SIGSTOP). Utile pour attendre quelque chose avant de continuer.
▶️ RESUME	Reprend le processus mis en pause (SIGCONT).

Rangée 2 — Contexte et feedback :

Bouton	Action
💡 BTW	Mode collecte de contexte supplémentaire. Tes prochains messages rejoignent la file d'attente et seront injectés dans le prochain prompt GSD.
🛠️ Fix It	Relance la tâche avec des corrections automatiques basées sur la réponse précédente.
👍	Feedback positif — enregistré dans les métriques de qualité.
👎	Feedback négatif — crée automatiquement une règle de learning qui sera injectée dans chaque prochain prompt du worker.

Rangée 3 — Navigation :

Bouton	Action
🏷️ Skills	Afficher la liste des skills utilisées pour cette réponse.
📊 View Log	Ouvrir le log CRM de cette session.

Boutons du Master Bot

Sur la fiche de chaque projet dans le Master Bot, des boutons sont disponibles :

Restart — redémarrage du child bot
Delete — suppression du projet (avec confirmation)
Manifest — afficher la configuration du projet
Skills — liste des skills du projet
Quality — métriques de qualité
CRM — lien vers le CRM Dashboard

Contexte et mémoire

L'historique de conversation est conservé par worker (maximum 50 entrées). Chaque worker a sa propre mémoire.
Répondre à un message spécifique → son texte sera injecté comme CONTEXT dans le prompt Claude.
Le Context Router sélectionne automatiquement les 5 skills les plus pertinentes pour ton message.
Les Learnings issus de 👎 → injectés automatiquement dans chaque prochain prompt GSD, pour que le worker ne répète pas ses erreurs.

Changement de worker

Chaque Child Bot supporte plusieurs workers. Le worker actif est sauvegardé dans le fichier active_role.json.

/c — bascule vers Consultant (Sonnet, analyse read-only)
/d — bascule vers Developer (Opus, accès complet)
/w:<worker_id> — bascule vers un worker personnalisé par son ID

Les messages sans préfixe vont au worker actif courant. Si tu as envoyé /d Corrige le bug, Developer devient actif — les prochains messages sans préfixe iront aussi à Developer.

Lien avec le CRM

Telegram et le CRM Dashboard sont deux canaux vers le même worker :

Le CRM Dashboard écrit les messages dans le fichier crm_inbox.jsonl
Le Child Bot interroge ce fichier toutes les 500ms et traite les nouveaux messages
Les réponses apparaissent à la fois dans Telegram et dans le CRM simultanément
Les pièces jointes (images, PDF) sont supportées via le CRM Dashboard

Cela signifie que tu peux démarrer une conversation dans Telegram, la continuer dans le CRM, et inversement — le contexte est conservé.

Dépannage

Problème	Solution
Le bot ne répond pas	Vérifie `/health` dans le Master Bot. Si le child bot est 🔴 — clique sur Restart ou utilise `/deploy <name>`. Vérifie `/watchdog` pour le monitoring automatique.
Temps de réponse long	Bascule vers Consultant (`/c`) — il utilise Sonnet, plus rapide qu'Opus. Pour les questions simples, c'est suffisant.
Message tronqué	Telegram a une limite de 4 096 caractères par message. Le bot divise automatiquement les longues réponses en parties : `[1/3]`, `[2/3]`, `[3/3]`.
Le bot répond lentement via le CRM	Vérifie que la session tmux du child bot est active : `/health` doit afficher tmux 🟢.
👎 ne crée pas de learning	Assure-toi d'avoir appuyé sur 👎 directement sous la réponse du worker, pas sous un message système.