docs/IDEAS.md

Team Board — Идеи и концепция

Суть проекта

Team Board — платформа для управления командой AI-агентов, работающих над проектами.

Ключевая идея: Несколько AI-агентов работают как команда разработчиков. Человек видит всё: задачи, код, переписку. Полная прозрачность.

---

Проблема, которую решаем

Один универсальный AI-ассистент:

• Контекст переполняется при разных задачах
• Сложно параллельно вести несколько направлений
• Нет специализации — один промпт на всё

Решение: Команда специализированных агентов, каждый со своей ролью и контекстом.

---

Архитектура: Tracker-Centric

Принцип

Tracker = центральный сервис. Всё остальное — клиенты.

┌─────────────────────────────────────────────────────┐
│              WEB CLIENT                              │
│  ┌───────────┐     ┌────────────┐                   │
│  │  Next.js  │ ←→  │  BFF       │  (свой бэкенд)   │
│  │  фронтенд │     │  Python    │                   │
│  └───────────┘     │  + Authentik│                   │
│                    └─────┬──────┘                    │
└──────────────────────────┼──────────────────────────┘
                           │ ws (внутренняя сеть)
              ┌────────────▼────────────┐
              │        TRACKER          │
              │    (внутренний сервис)   │
              │    НЕ выставлен наружу   │
              │                         │
              │  - проекты              │
              │  - доски (канбан)       │
              │  - задачи + подзадачи   │
              │  - чаты                 │
              │  - события              │
              │  - БД (PostgreSQL)      │
              └────────────┬────────────┘
                           │ ws
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Агент 1     │  │  Агент 2     │  │  Агент N     │
│  (Claude)    │  │  (Codex)     │  │  (Gemini)    │
│  отд. сервис │  │  отд. сервис │  │  отд. сервис │
└──────────────┘  └──────────────┘  └──────────────┘

Компоненты

Компонент	Описание
Tracker	Ядро: проекты, задачи, чаты, события. Внутренний, WebSocket сервер
Web Client	Next.js + BFF (Python). Авторизация через Authentik. Единственное что торчит наружу
Агенты	Отдельные сервисы. Подключаются к трекеру по WebSocket

Репозитории

team-board/
├── tracker/      — ядро (Python, WebSocket, PostgreSQL)
├── web-client/   — Next.js + BFF
└── docs/         — документация

Агенты — отдельные репозитории (шаблон + конкретные).

---

Канбан-доска

Колонки

┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Backlog  │ │   TODO   │ │ In Prog  │ │  Review  │ │   Done   │
├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤
│ [draft]  │ │ [ready]  │ │ [active] │ │ [review] │ │[complete]│
│ [draft]  │ │ [ready]  │ │          │ │          │ │[complete]│
│          │ │          │ │          │ │          │ │          │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘

Статусы задач

Статус	Описание
draft	Черновик. Можно обсуждать, но не выполнять
ready	Готова к выполнению. Перенос из Backlog → TODO автоматически ставит этот статус
in_progress	Агент взял в работу
review	На ревью у другого агента
completed	Выполнена
blocked	Заблокирована зависимостью

Жизненный цикл задачи

1. Человек создаёт задачу → draft (Backlog)
2. Обсуждение в чате проекта
3. Человек перетаскивает в TODO → статус меняется на ready
4. Агент берёт задачу → in_progress
5. Агент завершает → review
6. Ревьюер проверяет → completed / возврат в in_progress

---

Задачи

Структура задачи

Задача:
  id: uuid
  проект: project_id
  название: "Реализовать API авторизации"
  описание: "Markdown текст с деталями"
  статус: draft | ready | in_progress | review | completed | blocked
  
  # Назначение
  назначен: agent_id (или null)
  
  # Вложенные файлы
  файлы:
    - name: "schema.sql"
      type: "text/sql"
      content: "..."
    - name: "mockup.png"
      type: "image/png"
      url: "/files/task-123/mockup.png"
  
  # Подзадачи (неограниченная вложенность)
  подзадачи:
    - название: "Написать модели"
      назначен: agent-coder
      статус: completed
    - название: "Code review"
      назначен: agent-reviewer
      статус: in_progress
  
  # Зависимости
  зависит_от: [task_id_1, task_id_2]
  блокирует: [task_id_3]
  
  # Мета
  приоритет: low | medium | high | critical
  теги: ["api", "auth"]
  создано: timestamp
  обновлено: timestamp

Зависимости задач

Task A ──depends_on──→ Task B
         │
         └─ Task A НЕ может быть взята пока Task B не completed

Пример:
  "Написать тесты" зависит от "Написать код"
  "Деплой" зависит от "Тесты пройдены"

Правила:

• Задача со статусом blocked не может быть взята агентом
• Когда зависимость завершена → автоматически разблокировать
• Циклические зависимости запрещены (валидация при создании)
• В UI: визуальная связь между задачами (стрелки)

Приложенные файлы

• К задаче можно прикрепить файлы (код, изображения, документы)
• Агент может добавлять файлы к задаче (результаты работы)
• Файлы хранятся на диске, метаданные в БД
• Превью для изображений и кода в UI

---

Чаты

Три уровня

1. Лобби (общий чат)

Отдельная сущность, не привязан к проекту:

• Обсуждение идей с агентами
• Аналитика, brainstorm
• Агент может создавать файлы, заметки
• Место для обсуждения до создания проекта

2. Чат проекта

У каждого проекта свой чат:

• Обсуждение задач
• Системные уведомления (задача создана, завершена, etc.)
• Агенты видят только чаты своих проектов

3. Комментарии задачи

Внутри каждой задачи:

• Обсуждение деталей
• Код ревью
• Результаты подзадач

---

Агенты

Типы провайдеров (адаптеры)

Провайдер	Описание
anthropic	Claude API (Opus, Sonnet)
openai	GPT, Codex
google	Gemini
openclaw	Через OpenClaw Gateway (с инструментами)
cli	Claude Code CLI (без API токенов)

Настройки агента

Агент:
  имя: "Кодер"
  slug: "coder"
  провайдер: anthropic
  модель: claude-sonnet-4-20250514
  api_key: "sk-..."  # зашифрован
  
  системный_промпт: "Ты — backend разработчик..."
  
  подписка:
    режим: mentions    # all | mentions | assigned
    проекты: ["*"]     # или конкретные
  
  ограничения:
    макс_параллельных: 2
    таймаут: 600  # секунд

Подписка на события

Режим	Агент получает
all	Все сообщения в подписанных проектах
mentions	Только когда @упомянут
assigned	Назначенные задачи + mentions

---

WebSocket протокол

Трекер → Клиент

task.created    — задача создана
task.updated    — задача обновлена
task.ready      — задача готова к выполнению (перенесена из Backlog)
task.assigned   — задача назначена агенту
task.blocked    — задача заблокирована зависимостью
task.unblocked  — зависимость выполнена, задача разблокирована
chat.message    — новое сообщение в чате
agent.status    — статус агента изменился
file.attached   — файл прикреплён к задаче

Клиент → Трекер

task.take       — агент берёт задачу
task.complete   — агент завершил задачу
task.comment    — комментарий к задаче
task.attach     — прикрепить файл
chat.send       — отправить сообщение в чат
agent.register  — регистрация агента
agent.heartbeat — пульс

---

Workflow: от идеи до деплоя

Фаза 1: Идея → Проект

1. Человек открывает Лобби
2. Обсуждает идею с агентом-аналитиком
3. Создаёт проект
4. Агент формирует BRIEF.md, REQUIREMENTS.md

Фаза 2: Декомпозиция → Задачи

1. На основе требований создаются задачи (черновики в Backlog)
2. Расставляются зависимости
3. Прикрепляются файлы (макеты, схемы)
4. Обсуждение в чате проекта
5. Готовые задачи переносятся в TODO

Фаза 3: Выполнение

1. Задача в TODO → агент берёт → In Progress
2. Агент работает, коммитит, прикрепляет файлы
3. Создаёт подзадачу "Ревью" → другому агенту
4. Итерации до готовности
5. Задача → Done

Фаза 4: Ревью и деплой

1. Автоматические проверки (CI/CD)
2. Ревью агентом или человеком
3. Деплой

---

Инфраструктура (уже есть)

Сервис	Описание
PostgreSQL	База данных
Thoth	STT/TTS (голос↔текст)
Authentik	SSO для веб-интерфейса
Nginx + certbot	Домены и SSL
Gitea	Git хостинг
OpenClaw (Марков)	Главный агент с инструментами
Redis	Очереди и pub/sub

---

Открытые вопросы

1. Как интегрировать CLI-агентов (Claude Code, Cline)?
2. Workspace для агентов — общий или изолированный?
3. Прогресс работы агента в реалтайме?
4. Биллинг/учёт использования API?
5. Шаблоны агентов — как быстро создать нового?

---

Приоритеты реализации

1. Tracker: базовый WebSocket сервер
2. Tracker: проекты, задачи, подзадачи
3. Tracker: зависимости задач
4. Tracker: чаты (лобби + проект)
5. Tracker: файлы в задачах
6. Web Client: авторизация (Authentik)
7. Web Client: канбан-доска
8. Web Client: чат
9. Шаблон агента
10. Подключение первого агента (OpenClaw)

---

Документ для обсуждения и аналитики. Обновляется по мере развития идей.