docs/IDEAS.md

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

Суть проекта

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

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

---

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

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

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

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

---

Архитектура

Микросервисы (Python + FastAPI)

Сервис	Описание
Gateway	API Gateway, аутентификация
Projects	Проекты, Git интеграция
Tasks	Задачи, канбан, подзадачи
Agents	Управление AI агентами
Chat	Чаты проектов

Frontend (Next.js)

Web UI для управления всем.

Database

PostgreSQL (существующий на сервере).

---

UI Layout

┌────────────────────────────────────────────────────────────────────┐
│  [Logo] Team Board          [User Avatar] ▼                        │
├──────────────┬─────────────────────────────────────────────────────┤
│              │  Project Alpha                          [Settings]  │
│  PROJECTS    │─────────────────────────────────────────────────────│
│              │  💬 Chat ▼ (сворачиваемый)                          │
│  ○ Alpha     │  ┌──────────────────────────────────────────────┐   │
│  ● Beta      │  │ Agent-1: Закоммитил фикс для issue #42       │   │
│  ○ Gamma     │  │ Agent-2: Проверил, всё ок                    │   │
│              │  │ You: Мержите                                  │   │
│  [+ New]     │  └──────────────────────────────────────────────┘   │
│              │─────────────────────────────────────────────────────│
│──────────────│  KANBAN                                             │
│              │                                                     │
│  AGENTS      │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│              │  │ Backlog │ │ In Prog │ │ Review  │ │  Done   │   │
│  ● Claude    │  ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤   │
│  ○ Codex     │  │ [Task3] │ │ [Task1] │ │ [Task2] │ │ [Task0] │   │
│  ○ Gemini    │  │         │ │  └─sub  │ │         │ │         │   │
│              │  │         │ │  └─sub  │ │         │ │         │   │
│  [+ Add]     │  └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
│              │                                                     │
└──────────────┴─────────────────────────────────────────────────────┘

---

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

Фаза 1: Инициация проекта

Точки входа:

• Через главного агента (Марков) в Telegram
• Через Web UI — кнопка "New Project"
• Через любого агента

Результат: Создаётся черновик проекта, открывается Discovery Chat.

---

Фаза 2: Discovery (Обсуждение)

Участники: Человек + Lead Agent

Цель: Превратить размытую идею в чёткое ТЗ

Что делает Lead Agent:

1. Задаёт уточняющие вопросы
2. Предлагает варианты реализации
3. Указывает на риски
4. Формирует структуру

Артефакты:

• BRIEF.md — краткое описание проекта
• REQUIREMENTS.md — функциональные требования
• ARCHITECTURE.md — техническое решение

Выход из фазы: Человек подтверждает "Да, делаем так"

---

Фаза 3: Planning (Декомпозиция)

Кто делает: Lead Agent (или человек вручную)

Процесс:

REQUIREMENTS.md → Декомпозиция → Epic → Tasks → Subtasks

Пример:

Epic: "Модуль авторизации"
├── Task: "Модель пользователя"
│   ├── Subtask: "Схема БД"
│   ├── Subtask: "SQLAlchemy модель"
│   └── Subtask: "Миграция"
├── Task: "API эндпоинты"
│   ├── Subtask: "POST /auth/register"
│   ├── Subtask: "POST /auth/login"
│   └── Subtask: "Tests"
└── Task: "Интеграция с frontend"

---

Фаза 4: Execution (Разработка)

Как агенты берут задачи:

Модель	Описание
Pull	Агент сам выбирает задачу по специализации
Push	Lead Agent назначает задачи
Гибрид	Критичные — назначаются, остальные — свободный выбор

Процесс работы агента:

1. Взял задачу → "In Progress"
2. Читает контекст (Brief, Requirements, связанные задачи)
3. Работает (код, тесты, документация)
4. Коммитит в feature branch
5. Создаёт подзадачу "Review" → другому агенту
6. Ревью и итерации
7. Merge в main

---

Фаза 5: Review & QA

Принцип: Никакой код не идёт в main без ревью.

Кто ревьюит:

• Другой агент (не автор)
• Специальный "Reviewer" агент
• Человек (для критичного)

Автоматизация:

• CI/CD запускает тесты
• Линтеры
• Security checks

Escalation: 3 итерации ревью без согласия → эскалация к Lead/Human.

---

Фаза 6: Deploy

1. Integration тесты
2. Staging deploy
3. Human approval (опционально)
4. Production deploy

---

Задачи и подзадачи

Ключевой принцип: Подзадачи внутри задачи — контекст НЕ теряется.

Task: "Реализовать API авторизации"
├── Subtask: "Написать модели" → Agent-1 ✓
├── Subtask: "Code review" → Agent-2 ✓
├── Subtask: "Написать тесты" → Agent-1 (in progress)
└── Subtask: "Final review" → Agent-2 (waiting)

Когда агент работает над подзадачей — видит всё дерево + историю.

---

Роли агентов

Роль	Обязанности
Lead/Analyst	Discovery, Planning, Coordination
Developer	Код, тесты
Reviewer	Code review, QA
DevOps	CI/CD, Deploy
Documenter	Документация

---

Типы агентов

Тип	Описание
OpenClaw	Полноценный агент с инструментами
Claude API	Прямой вызов API
Claude Code CLI	Через CLI (без траты API токенов)
Codex	OpenAI
Gemini	Google
Custom	Любой через API

---

Проблема: CLI Integration

Задача: Использовать Claude Code CLI (авторизован через Max подписку) без траты API токенов.

Варианты решения:

1. Headless Mode (если поддерживается)

claude --message "prompt" --output result.txt

2. PTY Automation

import pexpect
child = pexpect.spawn('claude')
child.sendline('Write a function...')
response = child.before

3. Session Bridge

Team Board → Agent Service → PTY Bridge → Claude CLI в tmux

4. MCP Integration

Если CLI поддерживает Model Context Protocol.

5. Гибридный подход

• Простые задачи → API (дёшево)
• Кодинг → CLI
• Роутинг по типу задачи

Требуется исследование: Проверить возможности claude CLI.

---

Прозрачность

Всё видно в Web UI:

• Статус задач
• Кто над чем работает
• Коммиты
• Переписка в задачах
• Метрики

Уведомления:

• Задача застряла
• Нужно решение человека
• Deploy готов

---

Настройки проекта

Project:
  name: "My Project"
  git_enabled: true          # default: true
  git_url: "https://..."
  lead_agent_id: "markov"    # можно переназначить
  agents: ["claude", "codex"]

---

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

• PostgreSQL — БД
• Thoth — STT/TTS сервис
• Authentik — SSO
• Nginx + certbot — домены
• Gitea — Git хостинг
• OpenClaw (Марков) — главный агент

---

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

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

---

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

1. Базовый UI: проекты, доска
2. Tasks Service: CRUD, подзадачи
3. Agents Service: регистрация
4. Chat Service
5. Git интеграция
6. CLI Bridge для Claude Code
7. Подключение реальных агентов

---

Документ для обсуждения. Финальная архитектура — отдельно.