53 lines
6.0 KiB
Markdown
53 lines
6.0 KiB
Markdown
# Чеклист онбординга проекта в оркестратор
|
||
|
||
Пошаговое подключение нового проекта «под ключ». Каждый пункт — в репо ПОДКЛЮЧАЕМОГО проекта, не здесь.
|
||
|
||
## Шаг 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`.*
|