# Surfaces team — Lambda Lab 3.0

Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.

## Правило №1: не быть ждуном

Платформа (SDK от Азамата) ещё не готова. Это **не блокер**.

- Все вызовы платформы — через `platform/interface.py` (Protocol)
- Реализация сейчас — `platform/mock.py` (MockPlatformClient)
- При подключении реального SDK — меняем только `platform/mock.py`
- Архитектурные решения принимаем сами, фиксируем в `docs/api-contract.md`

---

## Архитектура

```
surfaces-bot/
  core/
    protocol.py      — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
    handler.py       — ядро: IncomingEvent → OutgoingEvent (общее для всех ботов)
    session.py       — управление сессиями и чатами
    auth.py          — AuthFlow
    settings.py      — SettingsAction

  adapter/
    telegram/        — aiogram адаптер
      converter.py   — aiogram Event → IncomingEvent и обратно
      bot.py         — точка входа
      handlers/      — aiogram роутеры
      keyboards/     — инлайн-клавиатуры
      states.py      — FSM состояния
    matrix/          — matrix-nio адаптер
      converter.py   — matrix-nio Event → IncomingEvent и обратно
      bot.py         — точка входа
      handlers/      — обработчики событий

  platform/
    interface.py     — Protocol: PlatformClient (контракт к SDK)
    mock.py          — MockPlatformClient (заглушка)

  docs/              — вся документация
  tests/             — pytest тесты
  .claude/agents/    — конфиги агентов
```

Подробно об унификации: `docs/surface-protocol.md`
Telegram функционал: `docs/telegram-prototype.md`
Matrix функционал: `docs/matrix-prototype.md`

---

## Агенты

| Агент | Когда запускать | Модель | Токены |
|-------|----------------|--------|--------|
| `@researcher` | Изучить API, найти примеры | Haiku | ~дёшево |
| `@architect` | Спроектировать решение | Sonnet | ~средне |
| `@tg-developer` | Писать код Telegram-адаптера | Sonnet | ~средне |
| `@matrix-developer` | Писать код Matrix-адаптера | Sonnet | ~средне |
| `@core-developer` | Писать core/ и platform/ | Sonnet | ~средне |
| `@reviewer` | Проверить код перед PR | Sonnet | ~средне |

**Важно (Pro-лимиты):** не запускай больше двух Sonnet-агентов одновременно.
Haiku можно запускать параллельно сколько угодно.

---

## Стратегия параллельной разработки

Два бота разрабатываются параллельно, но через общее ядро.

### Порядок работы

```
1. core/ — сначала (однократно, все ждут)
   @core-developer пишет protocol.py, handler.py, session.py, auth.py, settings.py

2. platform/ — сразу после core/
   @core-developer пишет interface.py и mock.py

3. adapter/telegram/ и adapter/matrix/ — параллельно
   @tg-developer  →  adapter/telegram/
   @matrix-developer  →  adapter/matrix/
   Не пересекаются по файлам — можно одновременно в разных терминалах.
```

### Что можно делать одновременно (разные терминалы)

```bash
# Терминал 1 — Telegram адаптер
claude "Use @tg-developer to implement adapter/telegram/handlers/start.py"

# Терминал 2 — Matrix адаптер (параллельно)
claude "Use @matrix-developer to implement adapter/matrix/handlers/start.py"
```

### Что нельзя делать одновременно

- Два агента в одном файле
- @core-developer параллельно с @tg-developer или @matrix-developer
  (core/ должен быть готов до адаптеров)
- Больше двух Sonnet-агентов одновременно (Pro-лимит)

---

## Git worktree workflow

Каждая фича в отдельном worktree — адаптеры не мешают друг другу:

```bash
# Создать worktrees для параллельной работы
git worktree add .worktrees/telegram -b feat/telegram-adapter
git worktree add .worktrees/matrix   -b feat/matrix-adapter

# Работать в каждом независимо
cd .worktrees/telegram && claude "Use @tg-developer to ..."
cd .worktrees/matrix   && claude "Use @matrix-developer to ..."

# Смержить когда готово
git checkout main
git merge feat/telegram-adapter
git merge feat/matrix-adapter
```

---

## Команды запуска

```bash
# Установить зависимости
uv sync

# Запустить тесты
pytest tests/ -v

# Запустить только тесты Telegram
pytest tests/adapter/telegram/ -v

# Запустить только тесты Matrix
pytest tests/adapter/matrix/ -v

# Запустить только тесты ядра
pytest tests/core/ -v

# Запустить Telegram бота
python -m adapter.telegram.bot

# Запустить Matrix бота
python -m adapter.matrix.bot
```

---

## Переменные окружения

```bash
cp .env.example .env
```

Никогда не коммить `.env`.

---

## Экономия токенов (Pro-лимиты)

- Исследования → всегда `@researcher` (Haiku), не Sonnet
- Точечные правки в одном файле → напрямую без агента
- Ревью → только перед PR, не после каждого коммита
- Длинный контекст → дай агенту конкретный файл, не весь проект
- Если агент "завис" в рассуждениях → прерви, переформулируй задачу точнее