admin/orchestrator
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity
Files
main
orchestrator/docs/work-items/ORCH-011/01-brd.md

22 KiB
Raw Permalink Blame History

work_item, stage, author_agent, status, created_at, model_used
work_item stage author_agent status created_at model_used
ORCH-011 analysis analyst ready-for-review 2026-06-11 claude-opus-4-8

01 — BRD: ORCH-011 — Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций)

Work Item: ORCH-011 · Repo: orchestrator (self-hosting) · Стадия: analysis Заказчик: Владелец (Слава) Тип: docs+tests (паттерн ORCH-102/103 — golden-source-документ + структурные анти-дрейф тесты; рантайм не трогается)

1. Бизнес-контекст и проблема

1.1. Цель

Описать работу всей мультиагентной системы оркестратора в одном месте — от бизнес-смысла (зачем, какую проблему решает, что умеет) до технического устройства (архитектура, конвейер, агенты, модель объектов, интеграции, качество, наблюдаемость). Документация нужна, чтобы:

  1. другие люди (разработчики, заказчики, менеджеры проектов) могли разобраться, как работает оркестратор, не раскапывая 60+ work-item пакетов и 40 ADR;
  2. на её основе генерировать презентационные материалы по использованию и возможностям (решение Владельца: слайды PowerPoint, стильный тёмный дизайн, точный рендеринг).

1.2. Корневая проблема — документация богатая, но фрагментированная

Установленные факты (проверено по дереву репо, не изобретать):

Что есть Где Ограничение как «единого места»
Паспорт проекта CLAUDE.md для агентов/разработчиков; плотный реестр доработок, не вводный текст
Тех-витрина README.md только технический уровень; обзор без бизнес-слоя
Бизнес-видение docs/PRODUCT_VISION.md (v1.0, 2026-06-04) «концепция развития» (vision), не описание текущего состояния; не покрывает тех-уровень
Детальная архитектура docs/architecture/README.md (~1246 строк), internals.md глубокий справочник для инженеров; нечитаем «с нуля» нетехническим читателем
Решения docs/architecture/adr/ (40 сквозных ADR) + per-work-item ADR точечные решения, не цельная картина
Стандарты docs/_standards/ (PIPELINE_DOCS, HANDOFF_PROTOCOL, TRACEABILITY) нормативы для агентов
Эксплуатация/тираж docs/operations/ (8 runbook'ов), docs/deployment/ (LITE_SETUP, BUNDLED_SETUP) операторские инструкции
История/уроки docs/history/, docs/epics/self-evolution.md сырьё, не витрина

Ни один из этих документов не является единой точкой входа «бизнес + тех» для трёх целевых аудиторий. Новому человеку (заказчику, менеджеру, новому разработчику) сегодня нужно собирать картину из 5–8 разных мест с разной степенью детализации и разным языком. Презентацию о возможностях системы собирать не из чего — нет слайдо-готового источника.

1.3. Почему сейчас

  • Платформа достигла тиражируемости (ORCH-101/102/103: Lite- и Bundled-развёртывание у заказчика) — появился внешний читатель (заказчики-тестеры), которому нужно объяснять систему.
  • Самовоспроизводящийся темп доработок (self-hosting) без единой витрины делает порог входа всё выше с каждой задачей.

1.4. Решения Владельца (из бизнес-запроса) — приняты как требования

# Решение
D-1 Формат презентационных материалов — слайды PowerPoint, стильный тёмный дизайн, точный рендеринг.
D-2 Аудитория документации — разработчики, заказчики, менеджеры проектов (три явных маршрута чтения).
D-3 Единое место — репозиторий orchestrator: docs/ (+ возможно compiled-wiki — как опция, см. §2.2).
D-4 Поддерживать в актуальном состоянии: документация обновляется сразу после изменения функционала (правило CLAUDE.md §2 распространяется на новую витрину).

2. Объём (scope)

2.1. В объёме

  • Единая витрина системы — новый связный раздел в docs/ с одной точкой входа (индексом), покрывающий два уровня:
    • Бизнес-уровень (для нетехнических читателей и презентаций): зачем нужен оркестратор и какую проблему решает; что умеет (автономный конвейер «задача → прод», мультипроектность, самовосстановление, пакетный авто-режим, багфикс-трек, тиражируемость); ценность и возможности простым языком; сценарии использования.
    • Технический уровень (7 блоков, контент-карта — TRZ §3):
      1. архитектура — компоненты и их связи; 2) конвейер/стадии и гейты на переходах;
      2. агенты — 6 ролей, входы/выходы, артефакты, шаблоны; 4) структура объектов — Project/Work-Item, реестр проектов, jobs-очередь, события/дедуп, каноническая модель БД;
      3. интеграции — Plane, Gitea, LLM-модели, Telegram; 6) качество/безопасность;
      4. аналитика/наблюдаемость.
  • Маршруты чтения для трёх аудиторий (D-2): «я заказчик / я менеджер / я разработчик — с чего начать и что читать дальше».
  • Презентационная основа (D-1): слайдо-структурированный источник (последовательность слайдов: заголовок/тезисы/визуальный мотив) + воспроизводимый путь получения .pptx в тёмном дизайне. Выбор инструмента генерации — за архитектором (TRZ §3.4, OQ-2).
  • Норматив сопровождения: правило «изменил функционал → обнови витрину в том же PR» зафиксировано в витрине и в правилах агентов (D-4; ось reviewer'а по обзорным докам уже существует — ORCH-079).
  • Анти-дрейф: структурные pytest-тесты каркаса витрины (по образцу tests/test_lite_setup_doc.py / test_bundled_setup_doc.py): обязательные разделы, сверка карты стадий импортом src/stages.py::STAGE_TRANSITIONS, полнота 6 агентов, валидность внутренних ссылок, запрет секретов/хост-хардкодов.
  • Обновление указателей: README.md, CLAUDE.md (ссылка на витрину), CHANGELOG.md.

2.2. Вне объёма (явно, не делать)

  • Любые изменения рантайма: src/**, STAGE_TRANSITIONS, QG_CHECKS, check_*, machine-verdict ключи, схема БД, compose/Dockerfile — байт-в-байт.
  • Compiled-wiki / внешняя вики-платформа — вне объёма v1: репозиторий остаётся единственным источником истины («канон не форкается», паттерн ORCH-009 BR-2); экспорт в wiki — возможное развитие, фиксируется как открытый вопрос (TRZ §9 OQ-4), не реализуется.
  • Перенос вне-репозиторных источников в репо: tasks/orchestrator/STATUS.md, BACKLOG.md, PROGRESS-журналы, дневники memory/ физически в репозитории отсутствуют — они служат лишь затравками для содержания; сами файлы в гит не переносятся (внутренняя кухня, риск утечки контекста/секретов).
  • Переписывание/замена существующих golden sources (docs/architecture/README.md, internals.md, стандарты docs/_standards/, deployment-доки): витрина ссылается на них, а не дублирует и не подменяет (анти-«второй источник истины», BR-4).
  • Автогенерация документации из кода (doc-from-code, autodoc) — вне объёма.
  • Маркетинговые материалы за пределами PPTX-основы (видео, лендинги, демо-стенды).
  • Новые runtime-зависимости прод-образа (включая библиотеки генерации презентаций) — запрещено (NFR-2).

3. Заинтересованные стороны

  • Владелец/оператор (Слава) — заказчик задачи; принимает витрину и презентационную основу; использует слайды для показа возможностей платформы.
  • Заказчики платформы (внешние, включая тестеров Lite/Bundled-тиража ORCH-102/103) — читают бизнес-уровень и сценарии; смотрят презентацию.
  • Менеджеры проектов — читают бизнес-уровень + конвейер/статусную модель (что видно в Plane, какие человеческие гейты есть).
  • Разработчики (люди и агенты самого оркестратора) — входят через витрину в технический уровень и далее по ссылкам в golden sources.
  • Reviewer-агент конвейера — контролирует соблюдение норматива сопровождения витрины (расширение оси «обзорные доки» ORCH-079).

4. Бизнес-требования (BR)

ID Требование Связь
BR-1 В docs/ существует единая точка входа (индекс витрины), из которой достижимы оба уровня (бизнес/тех) и все 7 тех-блоков; любой из трёх читателей начинает с одного места. D-3, AC-1
BR-2 Бизнес-уровень читается нетехническим человеком: проблема → решение → ценность → возможности → сценарии использования; термины конвейера объяснены по-человечески; без необъяснённого жаргона и кодовых идентификаторов в основном тексте. D-2, AC-2
BR-3 Технический уровень покрывает все 7 заявленных блоков (§2.1) и соответствует фактическому коду/канону репо: карта стадий = STAGE_TRANSITIONS, реестр гейтов = QG_CHECKS + под-гейты, агенты = 6 промптов .openclaw/agents/ + таблица модель/эффорт (ORCH-41), модель данных = фактические таблицы src/db.py. AC-3, AC-4, AC-5
BR-4 Link-first / не форкается канон: витрина даёт цельную картину и ссылается на golden sources за деталями (architecture/README, internals, стандарты, ADR, deployment-доки); не создаёт второй источник истины и не противоречит коду. §2.2, AC-6
BR-5 Презентационная основа: в репо есть слайдо-структурированный источник (бизнес-нарратив → слайды) и воспроизводимый, документированный путь получения .pptx в тёмном дизайне (D-1). Инструмент — выбор архитектора; запуск — вне рантайма конвейера. D-1, AC-7
BR-6 Маршруты аудиторий: витрина содержит явные маршруты чтения для заказчика / менеджера / разработчика (D-2). D-2, AC-8
BR-7 Норматив сопровождения: правило «изменил функционал → обнови витрину в том же PR» зафиксировано в витрине и видимо агентам (CLAUDE.md-указатель); reviewer-ось обзорных доков покрывает витрину. D-4, AC-9
BR-8 Анти-дрейф: каркас витрины и её ключевые машинно-проверяемые факты (стадии, агенты, ссылки, отсутствие секретов) защищены структурными pytest-тестами; их падение ловит расхождение витрины с кодом. AC-10
BR-9 Существующие указатели актуализированы: README.md и CLAUDE.md ссылаются на витрину; CHANGELOG.md несёт запись. AC-11

5. Нефункциональные требования (NFR)

ID Требование
NFR-1 docs+tests only: src/** байт-в-байт; STAGE_TRANSITIONS / QG_CHECKS / check_* / machine-verdict ключи / схема БД / compose / Dockerfile — не тронуты. Kill-switch не нужен: документация не исполняется (паттерн ORCH-102/103).
NFR-2 Прод-образ без новых зависимостей: генерация презентации (если скриптом) исполняется вне рантайма (host/dev-окружение, явный запуск человеком — паттерн ORCH-009); зависимости генерации НЕ попадают в requirements/образ оркестратора.
NFR-3 Без секретов и хост-специфики в новых доках/источниках презентации: токены, внутренние URL/имена хостов — только плейсхолдерами (паттерн tests/test_no_host_hardcodes.py / fenced-скан test_lite_setup_doc.py).
NFR-4 Язык: русский (канон репо; языковое исключение deployer.md не затрагивается). Терминология единая со статусной моделью Plane (ORCH-066) и PIPELINE_DOCS.
NFR-5 Self-hosting safety: задача не рестартит/не роняет прод-контейнер; прод-деплой — только штатным маршрутом конвейера (staging-гейт + Confirm Deploy).
NFR-6 Поддерживаемость: витрина модульная (отдельные файлы по блокам, связанные индексом), чтобы будущие правки были точечными; объём основного текста разумен за счёт link-first (BR-4).

6. Допущения и ограничения

  • Вне-репозиторные затравки (tasks/orchestrator/STATUS.md, BACKLOG.md, PROGRESS-журналы, memory/) в worktree недоступны — содержание витрины строится из внутрирепозиторных golden sources (CLAUDE.md, README, PRODUCT_VISION, architecture/, _standards/, ADR, deployment/, history/). Этого достаточно: репо самодостаточен по фактам (проверено §1.2).
  • docs/PRODUCT_VISION.md остаётся самостоятельным vision-документом; витрина переиспользует его бизнес-нарратив со сверкой с фактическим состоянием (что из vision уже реализовано — например, тираж ORCH-101/102/103) и ссылается на него.
  • Точное имя/структура каталога витрины — решение архитектора (рекомендация TRZ §2: новый каталог в docs/, например docs/overview/); анти-дрейф тесты пишутся под выбранные пути.
  • Бинарный артефакт .pptx: коммит бинаря в git спорен — решает архитектор (OQ-3); требование BR-5 — воспроизводимость пути генерации, не обязательность бинаря в репо.
  • Задача объёмная по контенту: допускается реализация витрины «вглубь по блокам» в одном PR (один прогон developer); если объём не помещается — эскалация на уровне задач (разбиение) по штатному маршруту, не молчаливое сокращение объёма.

7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md)

  • AC-1 единая точка входа существует и связывает оба уровня и маршруты аудиторий.
  • AC-2 бизнес-уровень самодостаточен для нетехнического читателя.
  • AC-3…AC-5 тех-уровень покрывает 7 блоков и сходится с кодом (стадии/гейты/агенты/модель данных).
  • AC-6 link-first: ссылки на golden sources валидны, дублирования-противоречий нет.
  • AC-7 презентационная основа есть; путь к .pptx (тёмный дизайн) воспроизводим и документирован.
  • AC-8 маршруты трёх аудиторий присутствуют.
  • AC-9 норматив сопровождения зафиксирован.
  • AC-10 структурные анти-дрейф тесты существуют и зелёные; полный pytest зелёный.
  • AC-11 README/CLAUDE.md/CHANGELOG обновлены; src/** не тронут.

8. Риски (кратко; детали — 10-tech-risks.md, заполняет архитектор)

  • R-1 — гниение витрины. Self-hosting темп (несколько задач в неделю) быстро устаревает любой снапшот. Митигция: link-first (BR-4) + норматив сопровождения (BR-7) + структурные тесты на машинно-проверяемые факты (BR-8) — дрейф ловится CI, а не глазами.
  • R-2 — второй источник истины. Дублирование деталей architecture/README в витрине приведёт к противоречиям. Митигция: витрина = картина + ссылки; детали живут в существующих golden sources.
  • R-3 — объём одного прогона. Полная витрина + презентация + тесты могут не поместиться в один PR разумного размера. Митигция: модульность (NFR-6), приоритет блоков, при необходимости — эскалация/разбиение (допущение §6).
  • R-4 — зависимость генерации презентации. Библиотека генерации PPTX в прод-образе — лишний attack-surface/вес. Митигция: NFR-2 (вне рантайма), решение по инструменту — ADR архитектора.
  • R-5 — расползание скопа в маркетинг. Слайды → «а давайте ещё видео/лендинг». Митигция: жёсткая граница §2.2.
Reference in New Issue View Git Blame Copy Permalink