onboard2orch/checklists/ONBOARDING_CHECKLIST.md

Чеклист онбординга проекта в оркестратор

Пошаговое подключение нового проекта «под ключ». Каждый пункт — в репо ПОДКЛЮЧАЕМОГО проекта, не здесь.

Шаг 1. Регистрация проекта в орке

• Создать проект в Plane, получить plane_project_id и префикс work-item (напр. ET, ORCH).
• Создать git-репо проекта в Gitea.
• Добавить запись в реестр орка ORCH_PROJECTS_JSON (env орка): plane_project_id → repo + work_item_prefix + name. См. orchestrator src/projects.py (ADR-0001).
• Настроить вебхуки: Plane → /webhook/plane, Gitea → /webhook/gitea (HMAC-секрет в env орка).

⚠️ Шаг 1a. Статусная модель Plane (ОБЯЗАТЕЛЬНО — иначе стадии не отобразятся)

• Создать в новом Plane-проекте все 14 статусов, как в эталонном (enduro): Backlog, Todo, In Progress, Architecture, Development, Review, Testing, Approved, Rejected, Done, Cancelled, Needs Input, In Review, Blocked. Новый проект по умолчанию имеет только 5 базовых — недостающие 9 добавить через Plane API (POST /projects/<id>/states/, поля name/color/group).
• Убедиться, что орк резолвит статусы per-project (ORCH-10): get_project_states(project_id) читает UUID статусов из Plane API по project_id. UUID у каждого проекта СВОИ — НЕ хардкодить. Проверка: get_project_states(<новый pid>) возвращает 14 ключей с UUID этого проекта.
• ⚠️ Грабля (05.06.2026): без стадийных статусов webhook НЕ распознаёт «старт конвейера» (In Progress) → задача не запустится.

⚠️ Шаг 1b. Боты-агенты — члены Plane-проекта (ОБЯЗАТЕЛЬНО — иначе 403 на комменты)

• Добавить все 7 ботов-агентов (Analyst, Architect, Developer, Reviewer, Tester, Deployer, Stream) в новый Plane-проект как членов (POST /projects/<id>/members/, поле {"member": <user_id>, "role": 15}). user_id ботов можно взять из эталонного проекта (GET /projects/<et-id>/members/).
• ⚠️ Грабля (05.06.2026): каждый агент постит коммент-артефакт под СВОИМ ботом (PLANE_BOT_<ROLE>). Если бот не член проекта → Plane отдаёт 403 Forbidden на коммент, и ссылки на артефакты (BRD/ADR/review/…) не лягут в задачу. Конвейер продолжит работу, но без видимых комментов. admin-токен работает (он овнер), поэтому баг легко просмотреть при ручном тесте.

Шаг 2. Паспорт проекта — CLAUDE.md в корне репо

• TL;DR, стек, команды (тесты/запуск/деплой), среды (prod/staging), структура.
• Раздел «Артефакты задачи» — точные имена (00-business-request..15-staging-log, 04-test-plan.YAML).
• Раздел «Конвенции» (commits, ветки, ADR-формат).
• Раздел «Правила для агентов» (golden source, не править чужие артефакты, не закрывать задачу, машинные вердикты — YAML).
• Если есть инфра-риски (self-hosting/shared resources) — отдельный раздел + docs/operations/INFRA.md.

Шаг 3. Структура документации (канон)

• docs/architecture/README.md — обзор + конвейер + QG-таблица.
• docs/architecture/adr/ — сквозные ADR (adr-NNNN-slug.md) + README.md индекс.
• docs/work-items/ — артефакты задач (по <plane-id>).
• docs/operations/ — runbook/инфра (если нужно).
• docs/history/ — архив (bugfixes, lessons, incidents).
• CHANGELOG.md (Keep a Changelog).

Шаг 4. Промпты агентов — .openclaw/agents/*.md

• Все 6 ролей: analyst, architect, developer, reviewer, tester, deployer.
• По каркасу из principles/PROMPT_PRINCIPLES.md, содержимое — СВОЁ под проект.
• Каждый ссылается на CLAUDE.md + docs/architecture/README.md.
• Модели сверены с орк src/agents/launcher.py AGENT_CONFIGS.
• reviewer содержит reviewer-gate на документацию (REQUEST_CHANGES при необновлённой доке).

Шаг 5. Проверка готовности

• Тестовая задача в Plane → проходит весь конвейер до done.
• Название задачи ≤80 символов (иначе QG-0 завернёт в Blocked на старте).
• Комменты-артефакты реально ложатся в Plane на каждой стадии (нет 403) — проверка Шага 1b.
• Стадии отображаются на доске (Architecture/Development/…) — проверка Шага 1a.
• Вебхук фильтрует чужие проекты (unknown → ignored).
• Артефакты пишутся в docs/work-items/<id>/ с правильными именами.
• Quality Gates читают машинные вердикты (verdict:/deploy_status:/staging_status:).

---

Образец готового набора — examples/enduro-trails/. Принципы промптов — principles/PROMPT_PRINCIPLES.md.