Brainstorm: agent architecture, roles, MCP/skills, git workflow, file storage, references

BRAINSTORM-AGENTS-2026-02-20.md

@@ -0,0 +1,134 @@
+# Брейншторм: механика подключения агентов к 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)