--- work_item: ORCH-009 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-10 model_used: claude-opus-4-8 --- # 02 — ТЗ (TRZ): ORCH-009 — Онбординг проектов в оркестратор (turnkey) Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: analysis > ТЗ описывает **что** должно измениться и **где** (модули/контракты/артефакты). **Как** (точная > раскладка kit, механизм подстановки, формат CLI) — решает архитектор в `06-adr/`. Имена путей > ниже — рабочее предложение; архитектор вправе скорректировать, сохранив требования и AC. > ⚠️ Скоуп по актуализации 10.06: эталон = репо orchestrator; deliverables — в этом репо. > `src/**` НЕ меняется (NFR-1) — задача docs/templates/scripts/tests-only. --- ## 1. Сводка изменения Создать **способность turnkey-онбординга** нового проекта: (1) параметризуемый **onboarding-kit** (каркас нового репо: 6 промптов агентов по канону 52d/92, паспорт, AGENTS/CONTRIBUTING, скелет `docs/` с INFRA.md, копии живых канонов `_templates/`+`_standards/`); (2) операторский **onboarding-скрипт** (Gitea-репо + per-repo webhook; Plane-проект + статусы + лейблы; материализация kit + initial push; генерация записи реестра; dry-run/apply/verify; идемпотентно); (3) **runbook** `docs/operations/ONBOARDING.md` (полный чеклист, ручные шаги, верификация); (4) **структурные тесты** анти-дрейфа. Конвейер/движок не трогаются. --- ## 2. Задействованные модули / пути | Путь | Действие | Роль | |------|----------|------| | `onboarding/repo-skeleton/**` | создать | параметризуемый kit нового репо (дерево зеркалит целевой репо: `.openclaw/agents/*.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, `docs/**`) | | `onboarding/README.md` | создать | устройство kit: словарь плейсхолдеров, правило «канон не форкается» (что копируется live, что шаблонизируется) | | `scripts/onboard_project.py` | создать | операторский turnkey-CLI: `plan` (dry-run, дефолт) / `apply` / `verify`; идемпотентность; отчёт | | `docs/operations/ONBOARDING.md` | создать | runbook: последовательность, ручные шаги (env+рестарт, UI-only Plane), верификация, откат | | `docs/operations/SETUP_WEBHOOKS.md` | обновить | обобщить per-repo Gitea-webhook секцию (сейчас примеры захардкожены на enduro-trails); сослаться на ONBOARDING.md | | `tests/test_onboarding_kit.py` | создать | структура kit, канон промптов, reviewer-gate, INFRA/AGENTS/CONTRIBUTING | | `tests/test_onboarding_script.py` | создать | рендер/плейсхолдеры, registry round-trip, dry-run/идемпотентность, план Plane/Gitea (моки) | | `tests/test_onboarding_invariants.py` | создать | `src/**` не тронут логикой онбординга; снапшот `STAGE_TRANSITIONS`/`QG_CHECKS` | | `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md` | обновить | golden source: раздел «Онбординг проектов (ORCH-009)», запись changelog | | `src/**` | **не менять** | NFR-1; скрипту разрешён **read-only import** `src.projects._parse_projects_json` / констант `src.plane_sync._PLANE_NAME_TO_KEY` для round-trip и точных имён (не дублировать литералы) — допустимость импорта vs снапшот-фикстура решает архитектор | Справочные источники kit (read-only): `.openclaw/agents/*.md`, `docs/_templates/` (16 скелетов), `docs/_standards/` (3 стандарта), `docs/operations/INFRA.md` (образец структуры RUNBOOK). --- ## 3. Функциональные требования ### FR-1 — Onboarding-kit: состав каркаса нового репо (BR-3/BR-5/BR-6) `onboarding/repo-skeleton/` содержит (минимум): ``` .openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md ← шаблоны промптов CLAUDE.md ← паспорт проекта (per-repo канон, Ф-8) AGENTS.md ← точка входа агентов: карта доков + правила ведения CONTRIBUTING.md ← канон процесса: где что лежит, как вести README.md ← entrypoint: что это, quickstart, ссылки CHANGELOG.md ← пустой каркас docs/ARCHITECTURE.md ← код-карта/потоки/БД (заполняется по мере жизни) docs/PIPELINE.md ← стадии, QG, агенты (ссылается на _standards) docs/PRODUCT_VISION.md ← зачем проект (BRD-свод) docs/operations/INFRA.md ← обязательный RUNBOOK (см. FR-3) docs/architecture/adr/ ← реестр сквозных ADR (канон орка, §1.4 BRD) docs/work-items/.gitkeep docs/history/.gitkeep docs/_templates/ ← live-копия канона орка в момент онбординга (BR-2) docs/_standards/ ← live-копия канона орка в момент онбординга (BR-2) .env.example ← заготовка карты env (без секретов) ``` - **Параметризация** — единый словарь плейсхолдеров (минимум): `{{PROJECT_NAME}}`, `{{REPO}}`, `{{WORK_ITEM_PREFIX}}`, `{{PLANE_PROJECT_ID}}`, `{{STACK}}`, `{{TEST_CMD}}`, `{{PROD_PORT}}`/`{{STAGING_PORT}}` (расширяемо; единый синтаксис, фиксирует архитектор). - **Ссылочная целостность:** каждый путь, на который ссылаются kit-промпты/AGENTS.md, существует в каркасе (проверяемо тестом). - **Правило «канон не форкается» (BR-2):** `docs/_templates/` и `docs/_standards/` НЕ хранятся второй редактируемой копией в kit — копируются скриптом из живого канона репо орка в момент материализации. В kit хранятся только параметризуемые дельты (промпты, паспорт, AGENTS, CONTRIBUTING, README, INFRA и пр.). ### FR-2 — Шаблоны промптов 6 ролей по канону 52d/92 (BR-3/BR-4) Каждый из 6 шаблонов промптов: - 5 обязательных XML-секций в нормативном порядке `` → `` → `` → `` → ``; ``; `` у developer/reviewer/tester (после ``); `` у решающих ролей — как в эталоне `.openclaw/agents/` (ORCH-077/092). - Запреты в формате «❌ X → ✅ Y». - Директивы доки (жёстко): читай `CLAUDE.md`(паспорт)/`AGENTS.md`/`docs/ARCHITECTURE.md`/ADR ПЕРЕД работой; пиши артефакты в `docs/work-items//` по `docs/_standards/PIPELINE_DOCS.md` (скелеты из `docs/_templates/`); архитектор фиксирует решения в `06-adr/` + сквозные в `docs/architecture/adr/adr-NNNN-slug.md`; каждый обновляет `CHANGELOG.md`/релевантную доку. - **Reviewer:** содержит gate «документация обновлена? нет → `verdict: REQUEST_CHANGES`». - Эмиссия 6-польной frontmatter-схемы 52c (`work_item`/`stage`/`author_agent`/`status`/ `created_at`/`model_used`) — аддитивно; machine-verdict ключи и значения байт-в-байт (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`); копируемые примеры — с плейсхолдерами ``/`` (анти-паттерн ORCH-092 учтён). - Стек-специфика (язык/тесты/команды) — только через плейсхолдеры; никаких унаследованных орк-литералов (порты 8500/8501, «ORCH-», self-hosting-правила орка) в материализованном виде. - Языковая политика: по канону орка (5 ru + deployer en, нормативно ADR-001 D2 ORCH-092); отступление — только решением архитектора в ADR. ### FR-3 — INFRA.md шаблон: обязательные секции (BR-6) Шаблон `docs/operations/INFRA.md` нового проекта содержит секции: топология (контейнеры, порты прод/staging, сеть, тома, БД); карта env-переменных (дескрипторы в репо; секреты ТОЛЬКО в `.env` на хосте; `.env.example` — канон; `docker-compose.yml`/`Dockerfile` трекаются в гите); границы доступа; эксплуатационные предупреждения, включая **риски общего хоста** (соседние контейнеры, общие ресурсы; факт: хост впритык — см. `docs/epics/self-evolution.md` С-3). Существующий `docs/operations/INFRA.md` орка с self-hosting-предупреждениями (общая БД/очередь/групповой риск рестарта) — не модифицируется этой задачей (read-only образец). ### FR-4 — Onboarding-скрипт: провижининг (BR-1/BR-7/BR-9/BR-11) `scripts/onboard_project.py` (вход: имя проекта, repo, префикс work-item, параметры стека): - **Gitea:** создать репо (API), создать per-repo webhook (`push`/`pull_request`/`status`, HMAC-secret из/для `.env` — формат `SETUP_WEBHOOKS.md`); материализовать kit → **initial push в свежесозданный пустой репо** (единственный разрешённый push; в существующие репо — никогда). - **Plane:** создать проект (или принять существующий `--plane-project-id`); создать статусы со **точными** именами из `_PLANE_NAME_TO_KEY` (22 имени; `STOP` — группа `cancelled`, `Confirm Deploy` — отдельный статус; группы фиксирует архитектор по `plane_sync`) и лейблы `autoApprove`/`autoDeploy`/`Bug`. Недоступное через API CE → пункт отчёта «ручной шаг» со ссылкой на runbook (fail-safe, не падение). - **Реестр:** сгенерировать запись `ORCH_PROJECTS_JSON` (полный новый массив или диф — фиксирует архитектор), **валидную через фактический `projects._parse_projects_json`**; вывести оператору инструкцию «добавь в `.env` + управляемый рестарт». Скрипт сам `.env` прода не правит и контейнер не рестартит (NFR-2). - **Режимы:** `plan` (дефолт; полный план без единой мутации), `apply` (исполнение), `verify` (см. FR-5). Идемпотентность: повторный `apply` обнаруживает существующее (репо/webhook/статусы/лейблы/файлы) и пропускает с пометкой; ничего не удаляет и не перезаписывает существующий контент без явного флага. - **Прозрачность:** лог каждого шага + итоговый отчёт: `created / skipped(exists) / manual-step`. - **Webhook Plane:** не создаётся (workspace-level уже существует, Ф-6) — только проверка в verify. ### FR-5 — Верификация (BR-10) - `verify`-режим скрипта: запись реестра парсится (`_parse_projects_json` round-trip → поля совпадают); статусы проекта резолвятся (все логические ключи, включая `confirm_deploy`/`stop`); лейблы присутствуют; Gitea-webhook существует и активен; kit-файлы в репо (включая 6 промптов, AGENTS.md, INFRA.md, `_templates`/`_standards`); нет неразрешённых плейсхолдеров. - **Smoke на песочнице** (runbook, операторский): онбордить sandbox-проект → создать тестовую задачу → стадия analysis в песочнице → убедиться: агент прочитал доку проекта (следы в выводе/артефактах) и записал артефакты в `docs/work-items//` по канону. Контур песочницы (staging 8501 / одноразовый sandbox) фиксирует архитектор в ADR + runbook. ### FR-6 — Runbook ONBOARDING.md (BR-1/BR-8) Полный чеклист онбординга: предусловия (токены, доступы) → шаги скрипта → **операторские шаги** (env+рестарт — с предупреждением self-hosting: рестарт прода = групповое окно, выполнять осознанно; UI-only шаги Plane, напр. drag-and-drop порядок статусов) → верификация (verify + smoke) → откат (удаление созданного — вручную, скрипт не удаляет). Каждый ручной шаг — с командой проверки результата. --- ## 4. Изменения API **Нет.** Новые/изменённые HTTP-эндпоинты оркестратора не вводятся; вебхук-контракты не меняются. (Onboarding-CLI — операторский инструмент вне FastAPI-приложения.) ## 5. Изменения схемы БД **Нет.** Общая БД не читается и не пишется скриптом (NFR-2). ## 6. Требования к новым/изменённым QG checks **Нет.** Реестр `QG_CHECKS`/`check_*`/`STAGE_TRANSITIONS` — байт-в-байт (контроль — снапшот-тест, TC-18). Онбординг — операторская способность, не гейт конвейера. --- ## 7. Совместимость / регресс - **Нулевая регрессия кода:** `src/**` не меняется → поведение конвейера для enduro/orchestrator идентично; полный регресс `tests/` остаётся зелёным. - **Kill-switch не требуется:** способность активируется только явным запуском операторского CLI; в горячих путях конвейера нового кода нет. - **Обратимость:** удаление `onboarding/`/`scripts/onboard_project.py`/runbook возвращает репо в исходное состояние; созданные онбордингом внешние сущности сносятся вручную по разделу «Откат» runbook. - **Совместимость канонов:** kit-промпты проходят те же структурные требования, что эталонные (анти-дрейф NFR-4); обновление канона орка автоматически подхватывается live-copy частью kit (BR-2), шаблонные дельты — через обычные PR с reviewer-gate. --- ## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR) - `docs/work-items/ORCH-009/06-adr/ADR-001-…` — решения архитектора (раскладка kit, синтаксис плейсхолдеров, copy-vs-template split по файлам, импорт `src` из скрипта vs снапшот, контур песочницы, языковая политика kit-deployer). - `docs/architecture/README.md` — раздел «Онбординг проектов (ORCH-009)». - `CLAUDE.md` — краткий абзац о способности онбординга. - `CHANGELOG.md` — запись `feat:`. - `docs/operations/ONBOARDING.md` (новый), `docs/operations/SETUP_WEBHOOKS.md` (обобщение). - `07-infra-requirements.md` — предусловия онбординга (токены/доступы), заполняет архитектор. --- ## 9. Инварианты (не нарушать) - `src/**` без изменений; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict ключи/схема БД — байт-в-байт (NFR-1). - Скрипт: не рестартит/не останавливает прод-контейнер; не пушит в `main` существующих репо (INV-4 — мерж только через PR-merge API — не затрагивается: initial push идёт в свежесозданный пустой репо, не являющийся участником конвейера до регистрации); не удаляет внешние сущности; секреты в гит не попадают (NFR-2/NFR-3). - Никаких сетевых вызовов в тестах (NFR-5); никаких новых обязательных pip-зависимостей без обоснования в ADR. - Эталонные промпты орка `.openclaw/agents/*.md` этой задачей не модифицируются (они — read-only образец; их правка = отдельные задачи канона). --- ## 10. Открытые вопросы для архитектора (не блокируют анализ) - OQ-1: Раскладка kit — `onboarding/repo-skeleton/` (предложение) vs `docs/_onboarding/` vs `scripts/onboarding/`; где словарь плейсхолдеров. - OQ-2: Механизм подстановки — stdlib (`str.replace`/`string.Template`) без новых зависимостей (рекомендация) vs шаблонизатор (новая зависимость — потребует обоснования). - OQ-3: Copy-vs-template split: какие файлы kit — live-copy канона, какие — параметризуемые шаблоны (минимум по BR-2: `_templates`/`_standards` — live-copy). - OQ-4: Скрипту импортировать `src.projects`/`src.plane_sync` (точные имена/парсер, нет дублирования) vs автономный снапшот констант с тестом синхронизации. - OQ-5: Plane API CE: фактическая доступность создания проекта/статусов/лейблов — что уходит в ручные шаги runbook. - OQ-6: Контур песочницы для smoke (staging 8501 vs одноразовый sandbox-проект) и судьба sandbox-артефактов после прогона. - OQ-7: Языковая политика kit-промптов для не-self-hosting проектов (рекомендация: канон орка, deployer — en). - OQ-8: Защита `main` нового репо в Gitea (branch protection): не должна ломать PR-merge API конвейера — включать ли вообще (рекомендация: не включать, зафиксировать в runbook).