# 🗺️ Antigravity Swarm Master Roadmap & Reference

Центральный справочник и дорожная карта **Antigravity Swarm (v4.0)**. Консолидирует философию, архитектуру, структуру каталогов и план развития мультиагентного роя.

> **v4.0 Migration Note:** Рой полностью мигрирован с Gemini CLI (`.gemini/agents/`) на Antigravity CLI (agy) с динамическими субагентами (`define_subagent` / `invoke_subagent`). Статических `.md` файлов агентов больше нет.

---

## 1. Философия и принципы (Swarm Identity)

Рой построен по топологии **Hub-and-Spoke**, где центральный диспетчер (**CEO / Orchestrator**) координирует специализированных субагентов. Разработка ведётся по методологии **Spec-Driven Development (SDD)**.

### Ключевые контракты:
- **Surgical Precision:** Минимальный объём изменений. Никакого «на всякий случай» кода и несанкционированных рефакторингов.
- **Parameters Guard:** Перед запуском опасных инструментов (запись файлов, shell-команды) — обязательная проверка безопасности аргументов.
- **Workspace Isolation:** Файлы целевых репозиториев анализируются строго на месте. Никакие артефакты других проектов не копируются в управляющий репозиторий.
- **OAuth Only:** VPS использует личную OAuth-подписку. `GOOGLE_API_KEY` отсутствует. ADK и google-genai SDK запрещены.

---

## 2. Архитектура субагентов (agy Dynamic Subagents)

> **КРИТИЧНО:** В Antigravity CLI (agy) нет статических файлов агентов. Субагенты создаются динамически через `define_subagent` и вызываются через `invoke_subagent`.

### Встроенные субагенты (не требуют define):
| Агент | Назначение |
|:---|:---|
| `research` | Поиск по кодовой базе и навигация |
| `browser` | Управляемый браузер (`/browser`) |
| `self` | Клон текущего агента |

### Кастомные субагенты (определяются CEO в GEMINI.md):
| Агент | Роль | Типичные задачи |
|:---|:---|:---|
| **oracle** | Исследователь и спек-райтер | `constitution.md`, `spec.md`, веб-поиск |
| **prometheus** | Архитектор | `plan.md`, `tasks.md` |
| **librarian** | Картограф кодовой базы | list_dir, grep, symbol discovery |
| **junior** | Хирургический имплементор | Правки ≤3 файлов, TDD, чеклисты |
| **frontend** | UI-специалист | HTML/CSS/JS, мобильная адаптация |
| **jules** | Тяжёлый рефакторинг | Сложные multi-file задачи → GitHub PR |
| **stitch** | Design-to-Code компилятор | Stitch MCP canvas → компоненты |
| **quality-validator** | Финальный QA гейт | Аудит против spec/plan/tasks |

### Паттерн использования:
```
# Шаг 1: CEO определяет субагента (один раз за сессию)
define_subagent(name="oracle", system_prompt="...", tools=["search_web", ...])

# Шаг 2: CEO вызывает
invoke_subagent("oracle", task="Исследуй лучшие практики...")
```

Полные системные промпты всех агентов — в [`Gemini_Swarm_Core/GEMINI.md`](GEMINI.md) раздел **Subagent Definitions**.

---

## 3. SDD Pipeline (Spec-Driven Development)

```
oracle (spec) → prometheus (plan/tasks) → [USER APPROVAL Checkpoint] → junior/jules/frontend/stitch (code/TDD) → quality-validator (QA)
```

Мультиагентный рой функционирует строго по методологии **Spec-Driven Development (SDD)**, регламентированной глобальным навыком **`spec-kit`** (`.agents/skills/spec-kit/SKILL.md`):

| Фаза | Агент / Навык | Артефакт | Роль фазы |
|:---|:---|:---|:---|
| **1. Research & Spec** | `oracle` / `spec-kit` | `specs/<feature>/spec.md` | Сбор контекста, выявление требований, разработка API-контрактов и схемы БД. |
| **2. Design & Tasks** | `prometheus` / `spec-kit` | `specs/<feature>/plan.md`<br>`specs/<feature>/tasks.md` | Декомпозиция архитектуры на чек-лист атомарных задач с TDD-тестами. |
| **3. Approval Block** | **USER (Mikhail)** | - | **Критический гейт:** Запрет любых изменений кода до ручного утверждения спецификации и плана пользователем. |
| **4. Implementation** | `junior`/`jules`/`frontend`/`stitch` | Исходный код, unit-тесты | Пошаговое выполнение чек-листа в цикле TDD (красный тест -> зеленый код -> рефакторинг). |
| **5. Validation** | `quality-validator` | Логи тестов, вердикт | Финальное тестирование, аудит безопасности и соответствия плану. |

**Bug fix flow:** `research` (поиск багов) → `junior` (исправление) → `quality-validator` (тесты и приемка)

---

## 4. Карта каталогов (Directory Map)

> **Золотое правило:** `.agents/` и `.specify/` живут в **корне репо** (`Gemini CLI/`) — это читает agy локально.
> `Gemini_Swarm_Core/` — это то что **деплоится на VPS** и там становится `/opt/Gemini_Swarm_Core/`.
> На VPS agy запускается с `CWD=/opt/Gemini_Swarm_Core` — он видит только то что внутри этой папки.

### Локальный репо (git: `Gemini CLI/`)

```
Gemini CLI/                              ← git repo root / локальный workspace agy
│
├── .agents/                             ← [ТОЛЬКО ЛОКАЛЬНО] agy читает при локальном запуске
│   ├── settings.json                    ← telemetry config
│   ├── skills/                          ← 20 навыков (прогрессивная загрузка: сначала только description)
│   │   ├── junior/SKILL.md              ← хирургическая имплементация ≤3 файлов
│   │   ├── prometheus/SKILL.md          ← архитектура и планирование
│   │   ├── quality-validator/SKILL.md   ← QA финальный гейт
│   │   ├── librarian/SKILL.md           ← картографирование кодовой базы
│   │   ├── cognitive-router/SKILL.md    ← маршрутизация задач по агентам/моделям
│   │   ├── context-manager/SKILL.md     ← управление контекстом между субагентами
│   │   ├── code-commentator/SKILL.md    ← документирование кода
│   │   └── stitch-*/SKILL.md            ← 8 навыков дизайна через Stitch MCP
│   └── plugins/
│       └── antigravity-swarm/
│           ├── mcp_config.json          ← Stitch MCP (⚠️ содержит API ключ)
│           └── rules/                   ← правила роя (sdd-pipeline, isolation, retry)
│
├── .specify/                            ← [ТОЛЬКО ЛОКАЛЬНО] persistent memory роя
│   └── memory/
│       ├── constitution.md              ← oracle пишет сюда глобальные стандарты проекта
│       ├── dynamic_agent_decision_logic.md  ← матрица: когда Junior vs Jules
│       └── swarm_memory_architecture.md    ← архитектура SQLite изоляции
│
├── .geminiignore                        ← что agy никогда не читает (секреты, node_modules)
├── .gitignore                           ← VPS.md (чтобы не деплоить локальные заметки)
│
└── Gemini_Swarm_Core/                   ← [ДЕПЛОИТСЯ НА VPS] → /opt/Gemini_Swarm_Core/
    ├── GEMINI.md                        ← системный промпт CEO (agy читает при CWD=/opt/...)
    ├── AGENTS.md                        ← pointer → GEMINI.md (для совместимости)
    ├── MISSION_CONTROL.md               ← Kanban доска (CEO обновляет)
    ├── SWARM_STATUS.md                  ← live лог миссий (CEO обновляет)
    ├── SWARM_ROADMAP.md                 ← этот файл — единый справочник
    ├── specs/                           ← SDD артефакты (spec.md, plan.md, tasks.md)
    ├── docs/archive/                    ← архив исторических планов
    ├── src/web/                         ← Telegram Mini App (статика)
    ├── requirements.txt                 ← Python зависимости (pip install на VPS через CI/CD)
    └── scripts/
        ├── tg_bridge.py                 ← Telegram → agy subprocess мост (⚠️ только через PR)
        ├── deploy_vps.py                ← деплой на VPS (85.155.190.233:50022)
        └── _ssh.py                      ← SSH хелпер (локальный, не деплоится)
```

### VPS файловая система (`/opt/Gemini_Swarm_Core/` = SWARM_ROOT)

```
/opt/Gemini_Swarm_Core/              ← CWD при каждом вызове agy -p "..."
│                                       agy ищет GEMINI.md здесь → загружает как system prompt
│
├── GEMINI.md                        ← ✅ agy читает ПОЛНОСТЬЮ при каждом запросе
├── sessions.db                      ← SQLite (WAL mode) — история чатов, изоляция задач
├── .env                             ← секреты (TELEGRAM_BOT_TOKEN, STITCH_API_KEY, ...)
│                                       ⚠️ не в git, кладёт вручную Mikhail
└── scripts/tg_bridge.py             ← запущен как systemd tg-bridge.service

/root/.gemini/
├── antigravity-cli/
│   ├── antigravity-oauth-token      ← OAuth токен подписки (⚠️ не трогать)
│   └── settings.json                ← 24 allow + 19 deny правил для headless режима
└── antigravity/
    └── mcp_config.json              ← копируется из .agents/plugins/.../mcp_config.json при деплое
```

### Правило: что где редактировать

| Хочу изменить | Редактирую | Как применяется |
|:---|:---|:---|
| Навык агента (инструкции) | `.agents/skills/<name>/SKILL.md` | agy загружает при локальном запуске; на VPS деплоится через CI/CD |
| Системный промпт CEO | `Gemini_Swarm_Core/GEMINI.md` | Деплоится на VPS → agy читает из CWD |
| Глобальные стандарты проекта | `.specify/memory/constitution.md` | oracle пишет, prometheus/validator читают |
| SDD артефакты фичи | `Gemini_Swarm_Core/specs/<feature>/` | Пишут oracle/prometheus, читают junior/validator |
| MCP серверы | `.agents/plugins/antigravity-swarm/mcp_config.json` | CI/CD копирует → `/root/.gemini/antigravity/mcp_config.json` |
| Telegram Bridge | `Gemini_Swarm_Core/scripts/tg_bridge.py` | ⚠️ только через ветку + PR + quality-validator |
| Права доступа субагентов | `/root/.gemini/antigravity-cli/settings.json` | Напрямую через _ssh.py (не через git) |

---

## 5. VPS Architecture (Telegram Bridge with Isolation)

```
Telegram → tg_bridge.py → sessions.db (Isolation Key: session_db_id)
                                  │
                                  ├──► subprocess: agy -p "prompt" --conversation <task-uuid>
                                                   CWD=/opt/Gemini_Swarm_Core (для роя)
                                                   CWD=/root/workspaces/<repo> (для внешних задач)
                                                   HOME=/root
                                                   ↓
                                       /root/.gemini/antigravity-cli/antigravity-oauth-token → Gemini API
```

**VPS:** HostHatch `85.155.190.233:50022`, `User=root`
**База данных:** `/opt/Gemini_Swarm_Core/sessions.db` (режим WAL, изоляция задач)
**Сервис:** `/etc/systemd/system/tg-bridge.service` (graceful shutdown mixed mode)
**Деплой:** `python Gemini_Swarm_Core/scripts/deploy_vps.py`

### Файлы которые НЕЛЬЗЯ трогать без понимания:
- `/etc/systemd/system/tg-bridge.service`
- `/root/.gemini/antigravity-cli/antigravity-oauth-token`  ← OAuth токен (не oauth_creds.json!)
- `Gemini_Swarm_Core/scripts/tg_bridge.py`

---

## 6. MCP серверы

| Сервер | Где настроен | Назначение |
|:---|:---|:---|
| `stitch` | `.agents/plugins/antigravity-swarm/mcp_config.json` | Google Stitch design canvas |
| `julesServer` | `~/.gemini/extensions/gemini-cli-jules/` | Jules remote VM tasks |
| `exa-mcp` | `~/.gemini/settings.json` | Семантический поиск, B2B лиды |
| `tavily-mcp` | `~/.gemini/settings.json` | Веб-поиск и ресёрч |
| `firecrawl` | `~/.gemini/settings.json` | Скрейпинг JS-heavy страниц |

---

## 7. Поэтапный план развития (Evolution Roadmap)

### ✅ Фаза 1: Фундамент (Завершено)
- Workspace isolation, telemetry, `.gitignore` guard
- Parameters Guard для Junior shell-команд
- `.agents/` структура и базовые навыки

### ✅ Фаза 2: Telegram Bridge (Завершено)
- VPS headless режим, `tg_bridge.py` subprocess архитектура
- OAuth-only (без API ключа), CWD=/opt/Gemini_Swarm_Core
- Anti-loop (retry limit 3), rolling session history
- ANSI + CLI warning фильтрация, typing indicator

### ✅ Фаза 2.5: agy Migration + Full Audit (Завершено — 2026-05-26)
- Удалены все статические `.agents/agents/*.md` файлы (8 штук)
- CEO использует `define_subagent` + `invoke_subagent` из GEMINI.md
- Исправлены `@`-пути инструкций для VPS CWD
- Удалены legacy скрипты (`intercept_gemini_fetch.py`, `debug_cli_network.py`)
- Skills обновлены: убраны `thinking_level`, `Caching API`, `customtools`
- Plugin структура: `.agents/plugins/antigravity-swarm/` с rules и Stitch MCP
- **agy v1.0.2 audit:** убраны `--model`, `--allowed-mcp-server-names`, `agy run` (не существуют)
- `tg_bridge.py`: все вызовы CLI → `agy -p "<prompt>"` без флагов
- VPS: `/root/.gemini/settings.json` исправлен (Linux npx вместо Windows путей)
- VPS: `/root/.gemini/agents/` очищена от legacy статических агентов
- `deploy_vps.py`: локальные скрипты (`_ssh.py`, `setup_*.py`, `test_*.py`) добавлены в IGNORED_FILES

### ✅ Фаза 3: Изоляция задач, Оптимизация квот и Правка прав (Завершено — 2026-06-03)
- Внедрен SQLite WAL mode, синхронизация NORMAL и таймаут 10 секунд.
- Graceful shutdown systemd сервиса и SIGTERM обработчики в Python.
- Очистка дерева фоновых процессов по PGID лидера при отмене задач.
- Логическая изоляция историй в `chat_history` по `session_db_id`.
- Динамический CWD и передача `--conversation <uuid>` в `agy` для изоляции проектов.
- Telegram-команды управления сессиями: `/repos`, `/repo`, `/sessions`, `/new`, `/switch`, `/where`, `/task`.
- Оптимизация квот Gemini: пакетное извлечение памяти (раз в 20 сообщений) и ручной режим `/remember [факт]`.
- Ротация истории (TRIM до 200 записей на сессию) и `PRAGMA optimize` при выходе.
- **Оптимизация моделей:** поагентные переопределения в `settings.json` (Librarian/Frontend на `gemini-3.1-flash`, Research на `gemini-3-flash`, CEO/Junior на `gemini-3.5-flash`) для экономии квот.
- **Безопасность песочницы:** нормализованы права доступа под действия `write_file`/`read_file` движка Antigravity.
- **Пути и Глобальный контекст:** рабочая папка проекта надежно изолируется на уровне OS CWD процесса в Python, и настроено копирование `GEMINI.md` в `/root/.gemini/GEMINI.md` для поддержки глобальных правил.
- **База данных планировщика задач:** Внедрена SQLite-очередь задач (`swarm_tasks`, `swarm_run_sessions`) с генерацией уникальных ID сессий для отслеживания истории выполнения.

### 🟪 Фаза 4: Динамическая адаптация (Планируется)
- Oracle распознаёт стек входящего репозитория и создаёт специализированных субагентов
- Mem0 MCP для долгосрочной памяти между сессиями (фильтрация по `project_id`)

---

## 8. Как запускать

```bash
# Интерактивный режим CEO
agy

# Фоновая задача
agy -p "твоя задача"

# Деплой на VPS
python Gemini_Swarm_Core/scripts/deploy_vps.py

# Проверка MCP и конфигурации
agy inspect
```