# 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 (если поддерживается)
```bash
claude --message "prompt" --output result.txt
```

### 2. PTY Automation
```python
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 готов

---

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

```yaml
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. [ ] Подключение реальных агентов

---

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