# Брейншторм: механика подключения агентов к Team Board
Дата: 2026-02-20

## Архитектура

```
Хозяин ──голос──→ Марков ──HTTP API──→ Team Board (Tracker)
Хозяин ──веб────→ team.uix.su ──────→       ↑
Хозяин ──tg─────→ Telegram Bridge ──WS──→    │
                                              │
Агент-Архитектор ──────────────────WS/HTTP──→ │
Агент-Кодер #1 ────────────────────WS/HTTP──→ │
Агент-Кодер #2 ────────────────────WS/HTTP──→ │
```

Все входы равноправны. Team Board — центральный хаб. Система работает без Маркова.

## Роли

| Роль | Кто | Что делает |
|------|-----|-----------|
| Хозяин | Eugene | Ставит задачи, контролирует, одобряет MR |
| Марков | OpenClaw | Голосовой интерфейс хозяина, менеджер (необязателен) |
| Архитектор | Агент (Opus) | Декомпозиция фич → задачи, координация |
| Кодер | Агент (Sonnet) | Кодинг, MR, исправление конфликтов |
| Bridge | Telegram бот | Дублирует чат в Telegram и обратно |

## Один Runner — разные роли
- Один и тот же binary/процесс
- Роль определяется конфигом: модель, prompt, capabilities
- Скилл для Runner'ов описывает взаимодействие с Tracker

## Транспорт
- **WebSocket** — основной (persistent connection, события в реальном времени)
- **HTTP Callback** — альтернативный (Tracker POST'ит события на URL агента)
- **HTTP API** — для файлов, задач, регистрации

## Агент = чёрный ящик
- Получает сообщения / задачи
- Имеет LLM + tools (Read, Write, Edit, Bash, WebSearch...)
- Отвечает в чат, создаёт подзадачи, открывает MR
- Настройки (prompt, роль) на стороне агента

## Задачи

### Жизненный цикл
```
backlog → todo → in_progress → in_review → done
                     ↑              ↓
                     └── rejected ──┘
```
- `backlog → todo` = назначение (человек или архитектор)
- `todo` = готова к работе, агент может взять
- `task.take` — атомарная операция (кто первый — того и тапки)
- Большая задача → агент сам разбивает на подзадачи

### Назначение
1. Человек назначает вручную
2. Архитектор создаёт и назначает
3. Агент сам берёт из `todo` по capabilities
4. Через чат: "ребята, новая задача"

## Git workflow
- Агент клонит repo в свою рабочую директорию
- Работает в отдельной ветке
- По завершении → **Merge Request**
- Ревью (агент/человек) → approve/reject
- **Конфликты**: решает тот, чей MR. После — повторный review.
- Автомерж после approve

## Файлы проекта — гибрид
- **Git repo** — опционально (привязывается если проект кодовый)
- **File storage** — всегда (docs, картинки, видео, attachments)
- Доступ через HTTP API (агент может быть на другом сервере)
- Чат и задачи поддерживают прикрепление файлов

## Проекты ≠ только код
- Кодовый проект: repo + files
- Документационный: только files
- Медийный: только files

## Контекст проекта
- Документация в `docs/` проекта или в file storage
- Все агенты в чате = все в контексте
- НЕ привязываемся к конкретному LLM (никаких CLAUDE.md)
- Скилл для Runner'ов описывает где что искать

## Проблема "глухого агента"
- LLM `query()` блокирующий — агент не слышит новых сообщений
- Решения: **короткие задачи** + **checkpoint pattern** (чекать между шагами)

## Чат = лента событий
- Сообщения людей + агентов + системные уведомления
- MR создан/approved/rejected → в чат
- Статус задачи изменился → в чат
- Можно фильтровать по типу

## Уведомления
- Всё в чат Team Board
- Telegram Bridge дублирует в Telegram группу
- Типы: task_created, task_updated, mr_created, mr_approved, agent_connected

## Безопасность
- Аутентификация через **токены** (прописываются заранее при регистрации агента)
- Каждый агент = уникальный токен
- Пока без OAuth/сложной авторизации

## Мониторинг
- **Heartbeat** — Tracker пингует агентов периодически
- Если агент не отвечает → статус `offline`
- Уведомление в чат: "Агент X перестал отвечать"

## Тестирование / Ревью
- Другие агенты проверяют результат (агент-ревьюер)
- CI/CD на MR (Gitea Actions) — автотесты

## Интеграция агентов с Tracker
- **MCP-сервер** для Tracker — нативные tools (create_task, send_message и т.д.)
- **Скилл (fallback)** — для моделей без MCP, инструкции с curl
- **Скилл для правил** — роль, стиль работы, когда что делать
- MCP = tools (ЧТО делать), Скилл = правила (КАК делать)
- Скилл можно автогенерировать из MCP-описания

## Открытые вопросы
- Формат скилла для Runner'ов (взаимодействие с Tracker)
- Как агент определяет релевантность задачи для себя?
- Автоматическое назначение по capabilities (будущее)
- Интеграция с Gitea API для MR
- UX веб-клиента (отдельная тема)

## Референсы
- **MetaGPT** (github.com/FoundationAgents/MetaGPT) — промпты ролей (PM, Architect, Engineer, QA), pub/sub между ролями, SOP. Забрать промпты для назначения ролей агентам.
- **Claude Flow / Ruflo** — claims, swarm топологии, multi-provider
- **BMAD Method** — brainstorming workflow, party mode (мульти-ролевой prompt)