orchestrator/docs/overview/presentation.md

Презентация системы: слайдо-источник

Источник истины презентации. Каждый слайд — блок ## Слайд N: Заголовок с тезисами (3–6 на слайд) и опциональной подписью визуала. Из этого файла собирается редактируемый PowerPoint в тёмном дизайне — процедура в конце файла («Как собрать .pptx»). Собранный бинарь в git не коммитится: меняешь рассказ — правишь этот файл и пересобираешь.

Слайд 1: Orchestrator — автономная фабрика разработки

• Конвейер из ИИ-агентов: от постановки задачи до выкладки на прод
• Человек ставит задачу и принимает результат — всё между автономно
• Платформа уже работает: ведёт несколько проектов и дорабатывает сама себя

Визуал: тёмный титул, логотип-конвейер из шести звеньев

Слайд 2: Проблема

• Классическая разработка — люди-бутылочное-горлышко на каждом шаге
• Каждая передача между ролями — потеря времени, контекста и денег
• Мелкая фича или баг едут до прода днями — из-за очередей, не сложности

Визуал: цепочка из шести человек с песочными часами между ними

Слайд 3: Решение

• Шесть ИИ-агентов проводят задачу через все стадии разработки сами
• Аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер
• Человек принимает два решения: одобрить постановку и подтвердить прод
• Честность держат машинные гейты качества — их нельзя «уговорить»

Визуал: та же цепочка, но из агентов; человек над ней с двумя кнопками

Слайд 4: Как это работает — конвейер

• Задача из трекера едет по стадиям: анализ → проектирование → код → ревью → тесты → репетиция → прод
• На каждом переходе — гейт: машинная проверка честности стадии
• Не прошёл гейт — задача возвращается на доработку с замечаниями
• Каждая задача — своя ветка и изолированная рабочая копия кода

Визуал: горизонтальная схема стадий со шлагбаумами-гейтами

Слайд 5: Гейты качества

• Вердикты машинные: зелёный CI, одобрение ревью, отчёт тестов — только структурированные ключи
• Перед продом — четыре дополнительных проверки: безопасность, слияние, покрытие тестами, свежесть сборки
• Покрытие тестами не может деградировать: базовая линия растёт только вверх
• Слияние в основную ветку — только через PR; прямой push запрещён всем

Визуал: четыре шлагбаума подряд перед воротами «прод»

Слайд 6: Роли агентов

• Аналитик: требования, критерии приёмки, тест-план
• Архитектор: проектные решения с фиксацией в ADR
• Разработчик: код + тесты + документация одним PR
• Ревьюер и тестировщик: независимые машинные вердикты
• Деплойер: репетиция на песочнице, затем прод

Визуал: шесть карточек-ролей с артефактами на выходе

Слайд 7: Человек в контуре

• Постановщик и приёмщик, а не оператор: ноль ручных пинков в штатном прогоне
• Решение 1: одобрить постановку после аналитики
• Решение 2: подтвердить выкладку на прод отдельным статусом
• Живая карточка задачи в Telegram показывает, когда конвейер ждёт вас

Визуал: человек с двумя кнопками и карточка задачи в телефоне

Слайд 8: Запуск и ведение задачи через Plane

• Запуск: перевод задачи в статус «To Analyse» — единственная точка входа в конвейер
• Статусы Plane — индикация, а не управление: платформа выставляет их сама (Backlog → … → Done)
• Управляющих статусов ровно три: запуск, человеческие гейты и отмена
• Ход задачи виден сразу: статусы доски, живая карточка в Telegram, комментарии в задаче со ссылками на ветку и PR

Визуал: доска Plane с движущейся карточкой и зеркальное уведомление в Telegram

Слайд 9: Что решает человек: гейты, авто-режим, отмена

• Гейт 1 — статус «Approved» на анализе: одобрить постановку задачи
• Гейт 2 — статус «Confirm Deploy» на деплое: подтвердить прод отдельным статусом, чтобы привычный approve не выкатил прод случайным кликом
• Лейблы «autoApprove» / «autoDeploy» снимают эти два решения для пакетного авто-режима
• Авто-режим убирает только ожидание человека — ни одна техническая проверка не пропускается
• Лейбл «Bug» — короткий багфикс-маршрут; статус «STOP» — безопасная отмена с уборкой ветки и worktree, не трогает прод

Визуал: две кнопки человека, переключатели авто-лейблов и стоп-кран STOP

Слайд 10: Пакетный автономный режим

• Задачи одного проекта едут строго друг за другом — без столкновений
• Каждая следующая стартует от свежего кода с результатом предыдущей
• Метки авто-одобрения снимают оба человеческих гейта — пакет уезжает «за ночь»
• Технические проверки при этом не ослабляются ни на одну

Визуал: ночная очередь задач, утром — стопка готовых

Слайд 11: Багфикс за полцены

• Метка «баг» — и задача едет коротким маршрутом
• Пропускаются тяжёлая аналитика и отдельное проектирование
• Обязателен регресс-тест, фиксирующий дефект
• Все гейты качества — без исключений

Визуал: развилка маршрутов — длинный и короткий путь к одному финишу

Слайд 12: Самовосстановление

• Упавший агент перезапускается, осиротевшая задача возвращается в очередь
• Зависшие состояния находит и чинит фоновый сверщик
• Независимый сторож следит за платформой снаружи и шлёт алерты отдельным каналом
• Деградация прода после выкладки замораживает проект до разбора человеком

Визуал: платформа с автоподзаводом и внешним сторожем

Слайд 13: Наблюдаемость

• Одна задача — одна живая карточка: стадия, агент, стоимость, время
• Служебные страницы: снимок очереди и машинные метрики для мониторинга
• Журнал уроков копит отклонения конвейера — фундамент самообучения
• Стоимость каждой задачи и каждой роли видна по фактам

Визуал: дашборд из карточки, очереди и графика стоимости

Слайд 14: Одна платформа — много проектов

• Несколько репозиториев из одного инстанса с общей очередью
• Внутри проекта — строгий порядок, между проектами — параллельность
• Платформа дорабатывает сама себя тем же конвейером (self-hosting)
• Своя доработка репетируется на песочнице и требует явного подтверждения

Визуал: один конвейер, несколько лент с разными проектами

Слайд 15: Сценарии использования

• Фича за вечер: постановка → прод с двумя кликами человека
• Пакет задач на ночь: метки авто-одобрения, утром всё на проде
• Багфикс по короткому маршруту с обязательным регресс-тестом
• Остановить задачу: статус STOP — безопасная отмена с уборкой
• Несколько проектов параллельно без пересечений

Визуал: пять пиктограмм-сценариев

Слайд 16: Тираж платформы

• Разворачивается на новой инфраструктуре без правки кода — только конфиг
• Lite: у заказчика свои трекер и git — ставятся только оркестратор и сторож
• Bundled: весь стек одним комплектом (~14 контейнеров) и бутстрап-скрипт
• Свежие секреты, пошаговые инструкции с проверкой каждого шага

Визуал: коробка-дистрибутив в двух размерах

Слайд 17: Lite-установка скриптами

• Lite — два контейнера платформы: оркестратор и сторож (watchdog) на инфраструктуре заказчика
• Свои Plane, Gitea, Telegram и LLM заказчик подключает — в Lite они не входят
• Разворачивается без правки кода — только конфигом (принцип «дефолт = боевое значение»)
• Скрипты-помощники: gen_secrets.py (свежие секреты), onboard_project.py (регистрация проекта: plan / apply / verify); подъём — docker compose up -d
• Маршрут — пошаговый runbook LITE_SETUP.md с проверкой каждого шага (PASS/FAIL)
• Весь стек одним комплектом и одношаговым бутстрапом — это смежный вариант Bundled, не Lite

Визуал: два контейнера-кубика и чек-лист шагов с галочками

Слайд 18: Статус платформы сегодня

• В проде: автономный конвейер, мультипроектность, самовосстановление
• В проде: пакетный авто-режим, багфикс-маршрут, отмена задач, журнал уроков
• Тираж Lite и Bundled — готовые инструкции и инструменты
• Платформа развивает сама себя: документация и гейты растут с каждой задачей

Визуал: чек-лист способностей с отметками «в проде»

Слайд 19: Итог

• Разработка без очередей между ролями: задача → прод за один проход
• Человек принимает решения — конвейер делает работу
• Качество держат машинные гейты, прозрачность — живая карточка и метрики
• Следующий шаг: поставить первую задачу или развернуть платформу у себя

Визуал: тёмный финальный слайд с одной фразой-приглашением

---

Как собрать .pptx

Сборка выполняется вне рантайма платформы — в одноразовом dev-окружении на хосте разработчика (зависимость генерации не входит в прод-образ). Скрипт — scripts/build_presentation.py; формат слайдов выше парсится им же (один парсер — один источник истины).

Шаг 1. Создать venv и поставить python-pptx:

python3 -m venv .venv-pptx
.venv-pptx/bin/pip install python-pptx

Проверка: .venv-pptx/bin/pip show python-pptx печатает версию пакета — PASS; ошибка установки — FAIL (проверьте доступ к PyPI).

Шаг 2. Собрать презентацию (из корня репозитория):

.venv-pptx/bin/python scripts/build_presentation.py

Проверка: скрипт печатает Собрано слайдов: <N> → build/orchestrator-overview.pptx, где <N> равно числу слайдов в этом файле — PASS; ОШИБКА: … — FAIL (текст подскажет причину).

Шаг 3. Открыть и проверить результат:

Откройте build/orchestrator-overview.pptx в PowerPoint/LibreOffice. Проверка: тема тёмная (тёмный фон, светлый текст, акцентные заголовки), кириллица отображается точно, текст слайдов выделяется и редактируется — PASS. Каталог build/ в .gitignore: собранный бинарь в git не попадает.

---

Нарратив слайдов опирается на business.md; технические утверждения — на тех-блоки витрины (конвейер, агенты).