---
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-секций в нормативном порядке `<context>` → `<task>` → `<deliverables>` →
  `<constraints>` → `<output_format>`; `<success_criteria>`; `<escalation>` у
  developer/reviewer/tester (после `</success_criteria>`); `<thinking>` у решающих ролей —
  как в эталоне `.openclaw/agents/` (ORCH-077/092).
- Запреты в формате «❌ X → ✅ Y».
- Директивы доки (жёстко): читай `CLAUDE.md`(паспорт)/`AGENTS.md`/`docs/ARCHITECTURE.md`/ADR
  ПЕРЕД работой; пиши артефакты в `docs/work-items/<id>/` по `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:`); копируемые
  примеры — с плейсхолдерами `<YYYY-MM-DD>`/`<resolve по конфигу>` (анти-паттерн 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/<id>/` по канону. Контур песочницы
  (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).
