Boty Telegram — Przewodnik Użytkownika

Arc OS używa dwupoziomowej architektury botów Telegram: jeden Master Bot zarządza wszystkimi projektami, a każdy projekt otrzymuje własnego Child Bota z workerami AI.

Przegląd Architektury

System zbudowany jest na dwóch poziomach:

Master Bot ("Szef") — orkiestrator, bez AI. Zarządza cyklem życia wszystkich projektów: tworzenie, usuwanie, monitorowanie stanu, deploy, awaryjne zatrzymanie.
Child Bot — jeden na projekt. Proxy między Telegram a Claude CLI. Zawiera workerów AI (Consultant, Developer, niestandardowi), obsługuje wiadomości, przechowuje kontekst dialogu.

Jak to Działa

Kanał Telegram:
  Użytkownik → Telegram → Child Bot → Claude CLI → Odpowiedź → Telegram

CRM Dashboard:
  Użytkownik → CRM → crm_inbox.jsonl → Child Bot (polling 500ms) → Claude CLI → Odpowiedź → Telegram + CRM

Child Bot ciągle polluje plik crm_inbox.jsonl co 500ms, więc wiadomości z CRM Dashboard są przetwarzane niemal natychmiastowo.

Komendy Master Bot

Komenda	Opis
`/start`	Wyświetl listę dostępnych komend
`/status`	Status wszystkich projektów: aktywne wątki, uptime, zużycie zasobów
`/list`	Lista wszystkich Child Botów ze wskaźnikami stanu (🟢/🔴)
`/health`	Macierz stanu: stan Bot, Bridge, sesji tmux dla każdego projektu
`/deploy <name\|all>`	Git pull + restart dla konkretnego projektu lub wszystkich naraz
`/new_project <name>`	Uruchomienie onboardingu nowego projektu (tworzenie Child Bota, tmux, konfiguracji)
`/remove_project <name>`	Usunięcie projektu z potwierdzeniem (przycisk inline "Tak, usuń")
`/emergency_stop`	3-poziomowe kaskadowe zatrzymanie: SIGINT → `/exit` → SIGKILL. Zatrzymuje wszystko.
`/watchdog`	Monitorowanie Child Botów: automatyczny restart jeśli bot nie odpowiada
`/cancel`	Anuluj bieżącą aktywną operację (deploy, onboarding itp.)

Komendy Child Bot

Podstawowe Prefiksy

Prefiks	Worker	Model	Dostęp
`/c <wiadomość>`	Consultant	Sonnet	Tylko odczyt, doradca strategiczny
`/d <wiadomość>`	Developer	Opus	Pełny dostęp do plików i terminala
`/w:<worker_id> <wiadomość>`	Niestandardowy worker	Zależnie od konfiguracji	Definiowany w `workers_registry.json`
(bez prefiksu)	Aktywny worker	—	Domyślnie — Consultant

Przykład:

/c Przeanalizuj architekturę modułu auth
/d Napraw buga w formularzu logowania
/w:sentinel Przeprowadź audyt bezpieczeństwa ostatnich zmian

Komendy Informacyjne

Komenda	Opis
`/ping`	Sprawdzenie stanu bota + uptime
`/thread`	Rozmiar bieżącej historii dialogu (liczba wiadomości)
`/quality`	Metryki jakości: liczba wywołań, feedback (👍/👎), średni czas odpowiedzi
`/learnings`	Lista zakumulowanych reguł korekcji (learnings)
`/specs`	Lista specyfikacji ze statusami (draft / review / approved)
`/approve <id>`	Zatwierdzenie specyfikacji po ID
`/reject <id> [reason]`	Odrzucenie specyfikacji z opcjonalnym powodem

Przyciski Inline

Pod Odpowiedzią Workera

Po każdej odpowiedzi workera AI pojawiają się trzy rzędy przycisków:

Rząd 1 — Sterowanie procesem Claude:

Przycisk	Akcja
🛑 STOP	Zabija proces Claude (SIGKILL). Używaj gdy odpowiedź poszła nie tak lub się zawiesiła.
⏸️ PAUSE	Wstrzymuje proces Claude (SIGSTOP). Przydatne gdy chcesz poczekać na coś przed kontynuacją.
▶️ RESUME	Wznawia wstrzymany proces (SIGCONT).

Rząd 2 — Kontekst i feedback:

Przycisk	Akcja
💡 BTW	Tryb zbierania dodatkowego kontekstu. Twoje kolejne wiadomości trafiają do kolejki i będą wstrzyknięte do następnego promptu GSD.
🛠️ Fix It	Ponowne uruchomienie zadania z automatycznymi poprawkami na podstawie poprzedniej odpowiedzi.
👍	Pozytywny feedback — zapisywany w metrykach jakości.
👎	Negatywny feedback — automatycznie tworzy regułę learning, która będzie wstrzykiwana do każdego kolejnego promptu workera.

Rząd 3 — Nawigacja:

Przycisk	Akcja
🏷️ Skills	Pokaż listę skilów, które zostały użyte do odpowiedzi.
📊 View Log	Otwórz log CRM tej sesji.

Przyciski Master Bot

Na karcie każdego projektu w Master Bot dostępne są przyciski:

Restart — restart Child Bota
Delete — usunięcie projektu (z potwierdzeniem)
Manifest — pokaż konfigurację projektu
Skills — lista skilów projektu
Quality — metryki jakości
CRM — link do CRM Dashboard

Kontekst i Pamięć

Historia dialogu przechowywana jest per-worker (maksymalnie 50 wpisów). Każdy worker ma oddzielną pamięć.
Reply na konkretną wiadomość → jej tekst zostanie wstrzyknięty jako CONTEXT do promptu Claude.
Context Router automatycznie dobiera top-5 skilów relewantnych dla twojej wiadomości.
Learnings z 👎 → automatycznie wstrzykiwane do każdego kolejnego promptu GSD, żeby worker nie powtarzał błędów.

Przełączanie Workerów

Każdy Child Bot obsługuje kilku workerów. Aktywny worker przechowywany jest w pliku active_role.json.

/c — przełącza na Consultant (Sonnet, analiza tylko do odczytu)
/d — przełącza na Developer (Opus, pełny dostęp)
/w:<worker_id> — przełącza na niestandardowego workera po jego ID

Wiadomość bez prefiksu trafia do bieżącego aktywnego workera. Jeśli wysłałeś /d Napraw buga, Developer staje się aktywny — kolejne wiadomości bez prefiksu też trafią do Developer.

Połączenie z CRM

Telegram i CRM Dashboard to dwa kanały do tego samego workera:

CRM Dashboard zapisuje wiadomości do pliku crm_inbox.jsonl
Child Bot polluje ten plik co 500ms i przetwarza nowe wiadomości
Odpowiedzi pojawiają się zarówno w Telegram, jak i w CRM jednocześnie
Załączniki (obrazy, PDF) obsługiwane są przez CRM Dashboard

Oznacza to, że możesz zacząć dialog w Telegram, kontynuować w CRM i odwrotnie — kontekst jest zachowany.

Rozwiązywanie Problemów

Problem	Rozwiązanie
Bot nie odpowiada	Sprawdź `/health` w Master Bot. Jeśli Child Bot 🔴 — kliknij Restart lub użyj `/deploy <name>`. Sprawdź `/watchdog` dla automatycznego monitorowania.
Długi czas odpowiedzi	Przełącz się na Consultant (`/c`) — używa Sonnet, który jest szybszy od Opus. Do prostych pytań to wystarczy.
Wiadomość jest obcięta	Telegram ma limit 4096 znaków na wiadomość. Bot automatycznie dzieli długie odpowiedzi na części: `[1/3]`, `[2/3]`, `[3/3]`.
Bot odpowiada wolno przez CRM	Sprawdź, czy sesja tmux Child Bota jest aktywna: `/health` powinien pokazywać tmux 🟢.
👎 nie tworzy learningu	Upewnij się, że klikasz 👎 bezpośrednio pod odpowiedzią workera, a nie pod wiadomością systemową.