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
  
  # Тип задачи (флаги/теги)
  теги: ["кодинг", "api", "auth"]
  тип: coding | analytics | design | testing | docs | other
  
  # PR (только для задач с кодом)
  требует_pr: true | false  # автоматически по типу задачи
  
  # Назначение
  назначен: 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. Комментарии задачи

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

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

---

Агенты и адаптеры

Адаптер (провайдер)

Адаптер — это подключение к конкретной нейросети. Один адаптер может использоваться несколькими агентами.

Адаптер:
  id: uuid
  название: "Claude Opus"
  провайдер: anthropic | openai | google | openclaw | cli
  
  # Конфиг — JSON поле, разное для каждого провайдера
  config:
    # Anthropic
    api_key: "sk-ant-..."
    model: "claude-opus-4-5"
    max_tokens: 8192
    
    # Или OpenAI
    api_key: "sk-..."
    model: "gpt-4"
    organization: "org-..."
    
    # Или OpenClaw
    gateway_url: "http://localhost:18789"
    gateway_token: "..."
    agent_id: "main"
    
    # Или CLI
    command: "claude"
    working_dir: "/workspace"
  
  # Возможности адаптера (что умеет эта нейросеть)
  capabilities: ["coding", "analytics", "review", "design", "docs", "testing"]

Важно: Capabilities привязаны к адаптеру, не к агенту. Потому что возможности определяются нейросетью.

Агент

Агент — это "личность" с ролью, которая использует адаптер.

Агент:
  id: uuid
  имя: "Кодер"
  slug: "coder"
  
  # Привязка к адаптеру
  адаптер_id: uuid
  
  # Роль
  системный_промпт: "Ты — backend разработчик..."
  
  # Подписка
  подписка:
    режим: mentions    # all | mentions | assigned
    проекты: ["*"]     # или конкретные
  
  # Ограничения
  макс_параллельных: 2
  таймаут: 600  # секунд

Связка: типы задач ↔ адаптеры

Задача с тегом "coding" → только агенты с адаптером, у которого capability "coding"
Задача с тегом "design" → только агенты с адаптером, у которого capability "design"
Задача с тегом "analytics" → только агенты с адаптером, у которого capability "analytics"

Агент-дизайнер НЕ возьмёт задачу на кодинг — у его адаптера нет такой возможности.

Типы провайдеров

Провайдер	Описание	Конфиг
anthropic	Claude API	api_key, model, max_tokens
openai	GPT, Codex	api_key, model, organization
google	Gemini	api_key, model
openclaw	OpenClaw Gateway	gateway_url, gateway_token, agent_id
cli	Claude Code CLI	command, working_dir

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

Режим	Агент получает
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 — пульс

---

Ревью и PR

Не каждая задача = PR

Тип задачи	Нужен PR?
coding	Да
testing	Да
analytics	Нет — результат в виде файла/отчёта
design	Нет — результат в виде файла
docs	Возможно — зависит от проекта

Поле требует_pr определяется автоматически по типу, но можно переопределить вручную.

Флоу ревью (для задач с PR)

1. Агент работает → коммитит в feature branch
2. Создаёт PR в Gitea
3. Сдвигает задачу в Review
4. Трекер назначает ревьюера (другой агент, НЕ автор)
5. Ревьюер смотрит PR, пишет комментарии В ЗАДАЧЕ
6. Ок → Approve → Done, PR мержится
7. Не ок → замечания → обратно In Progress → автор исправляет

Флоу ревью (для задач без PR)

1. Агент работает → прикрепляет результат (файл/отчёт) к задаче
2. Сдвигает в Review
3. Ревьюер проверяет результат
4. Ок → Done
5. Не ок → замечания → обратно In Progress

Правила ревью

• Автор ≠ ревьюер (всегда)
• Максимум 3 итерации — потом эскалация к человеку
• Все комментарии в задаче (единый контекст)
• Чат проекта = лог событий (всё видно)

Итерации ревью

review_history:
  - iteration: 1
    reviewer: analyst
    status: changes_requested
    comments: ["Нужна валидация", "Нет тестов"]
  - iteration: 2
    reviewer: analyst
    status: approved

---

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

---

База данных (ключевые таблицы)

-- Адаптеры (подключения к нейросетям)
CREATE TABLE adapters (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    provider TEXT NOT NULL,       -- anthropic, openai, google, openclaw, cli
    config JSONB NOT NULL,        -- всё специфичное для провайдера
    capabilities TEXT[] NOT NULL, -- ["coding", "analytics", "review", ...]
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Агенты (личности с ролями)
CREATE TABLE agents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    slug TEXT UNIQUE NOT NULL,
    adapter_id UUID REFERENCES adapters(id),
    system_prompt TEXT,
    subscription_mode TEXT DEFAULT 'mentions',  -- all, mentions, assigned
    max_concurrent INT DEFAULT 1,
    timeout_seconds INT DEFAULT 600,
    status TEXT DEFAULT 'idle',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Задачи
CREATE TABLE tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    project_id UUID REFERENCES projects(id),
    parent_id UUID REFERENCES tasks(id),  -- подзадачи
    title TEXT NOT NULL,
    description TEXT,
    status TEXT DEFAULT 'draft',
    task_type TEXT DEFAULT 'other',  -- coding, analytics, design, testing, docs
    tags TEXT[],
    requires_pr BOOLEAN DEFAULT FALSE,
    assigned_agent_id UUID REFERENCES agents(id),
    priority TEXT DEFAULT 'medium',
    pr_url TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Зависимости задач
CREATE TABLE task_dependencies (
    task_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
    depends_on_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
    PRIMARY KEY (task_id, depends_on_id)
);

-- Файлы задач
CREATE TABLE task_files (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    task_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
    filename TEXT NOT NULL,
    mime_type TEXT,
    file_path TEXT NOT NULL,
    uploaded_by UUID,  -- agent_id или null (человек)
    created_at TIMESTAMPTZ DEFAULT NOW()
);

---

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

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)

---

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