From 3b0ea4443a7844f39779108ea04740118300263a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D1=80=D0=B8=D0=BC?= Date: Fri, 5 Jun 2026 13:20:11 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20onboarding=20methodology=20=E2=80=94=20?= =?UTF-8?q?principles,=20checklist,=20enduro=20reference=20(ORCH-9)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 36 +++++++++++- checklists/ONBOARDING_CHECKLIST.md | 40 +++++++++++++ examples/enduro-trails/README.md | 35 +++++++++++ principles/PROMPT_PRINCIPLES.md | 94 ++++++++++++++++++++++++++++++ 4 files changed, 203 insertions(+), 2 deletions(-) create mode 100644 checklists/ONBOARDING_CHECKLIST.md create mode 100644 examples/enduro-trails/README.md create mode 100644 principles/PROMPT_PRINCIPLES.md diff --git a/README.md b/README.md index e380273..45b2731 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,35 @@ -# onboard2orch +# onboard2orch — Онбординг проектов в оркестратор -Онбординг проектов в оркестратор (ORCH-9): принципы, методички, примеры-референсы. НЕ код орка. \ No newline at end of file +Репозиторий **методологии онбординга** нового проекта под управление мульти-агентного оркестратора (задача ORCH-9). +Здесь — **принципы, инструкции и примеры-референсы**. Это НЕ код орка и НЕ дока конкретного проекта. + +> Изоляция — основной принцип. Каждый проект живёт в своём репо со своим паспортом `CLAUDE.md` и своими промптами агентов. Этот репо НЕ содержит промпты под конкретные проекты — только КАК их готовить. + +## Зачем +Чтобы подключить новый проект к оркестратору «под ключ» (turnkey), нужно подготовить в репо проекта канонический набор: паспорт, структуру документации, промпты 6 ролей агентов. Этот репозиторий описывает, как это сделать правильно и единообразно. + +## Структура +``` +onboard2orch/ +├── README.md # этот файл +├── principles/ +│ └── PROMPT_PRINCIPLES.md # принципы подготовки промптов агентов +├── checklists/ +│ └── ONBOARDING_CHECKLIST.md # пошаговый чеклист онбординга проекта +└── examples/ + └── enduro-trails/ # пример-референс (обкатанный в бою набор) + └── README.md # что смотреть и почему (ссылки на эталонный репо) +``` + +## С чего начать +1. Прочесть `principles/PROMPT_PRINCIPLES.md` — каркас промпта и инварианты канона. +2. Пройти `checklists/ONBOARDING_CHECKLIST.md` — шаги подключения проекта. +3. Изучить `examples/enduro-trails/` — живой образец (структура, не для копирования содержимого). + +## Что НЕ делать +- НЕ копировать промпты enduro дословно в другой проект — копировать СТРУКТУРУ и ПРИНЦИПЫ, содержимое писать под свой проект. +- НЕ класть сюда промпты/паспорта конкретных проектов — они живут в репо своих проектов. +- НЕ дублировать сюда код орка — за это отвечает репо `orchestrator`. + +--- +*ORCH-9. Источник правды по онбордингу. Изоляция проектов — фича, не баг.* diff --git a/checklists/ONBOARDING_CHECKLIST.md b/checklists/ONBOARDING_CHECKLIST.md new file mode 100644 index 0000000..e521320 --- /dev/null +++ b/checklists/ONBOARDING_CHECKLIST.md @@ -0,0 +1,40 @@ +# Чеклист онбординга проекта в оркестратор + +Пошаговое подключение нового проекта «под ключ». Каждый пункт — в репо ПОДКЛЮЧАЕМОГО проекта, не здесь. + +## Шаг 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 орка). + +## Шаг 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/` — артефакты задач (по ``). +- [ ] `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`. +- [ ] Вебхук фильтрует чужие проекты (unknown → ignored). +- [ ] Артефакты пишутся в `docs/work-items//` с правильными именами. +- [ ] Quality Gates читают машинные вердикты (verdict:/deploy_status:/staging_status:). + +--- +*Образец готового набора — `examples/enduro-trails/`. Принципы промптов — `principles/PROMPT_PRINCIPLES.md`.* diff --git a/examples/enduro-trails/README.md b/examples/enduro-trails/README.md new file mode 100644 index 0000000..5f6791b --- /dev/null +++ b/examples/enduro-trails/README.md @@ -0,0 +1,35 @@ +# Пример-референс: enduro-trails + +**enduro-trails** — первый проект, обкатанный под оркестратором в бою. Его репо — живой образец канона. +Используй как **референс структуры и тона**, НЕ копируй содержимое (оно специфично для enduro: карты/terrain/OSRM). + +> Файлы здесь НЕ дублируются — это указатели на эталонный репо, чтобы он оставался единственным источником и не расходился с копией. + +## Что смотреть в эталонном репо enduro-trails + +### Паспорт проекта +- `CLAUDE.md` — образец паспорта: TL;DR, стек, команды, среды, конвенции, правила для агентов. + +### Документация +- `docs/architecture/README.md` + `docs/architecture/adr/` — обзор архитектуры + сквозные ADR. +- `docs/work-items//` — реальные артефакты задач: `00-business-request.md`, `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`, `06-adr/ADR-NNN-slug.md`, `12-review.md`, `13-test-report.md`, `14-deploy-log.md`. +- `docs/phases/PH-N.*/` — фазовая разбивка (опционально, не каждый проект). + +### Промпты агентов (★ эталон каркаса) +- `.openclaw/agents/architect.md` — образцовый каркас промпта: + `frontmatter (name/description/model/tools) → "Кто ты" → "Контекст проекта" → "Что прочесть в начале" → "Что произвести" → "Принципы" → "Запрещено" → "Эскалация"`. +- `.openclaw/agents/{analyst,developer,reviewer,tester,deployer}.md` — остальные роли. +- Обрати внимание: доменная специфика (MapLibre/OSRM/terrain, «всё в Docker», «vanilla JS > React») зашита в «Принципы» и «Запрещено» — **именно это меняешь под свой проект**. + +## Как использовать +1. Открой `architect.md` enduro → пойми каркас. +2. Скопируй СТРУКТУРУ разделов в свой `.openclaw/agents/architect.md`. +3. Замени ВСЁ доменное содержимое на специфику своего проекта. +4. Повтори для 6 ролей. +5. Сверься с `../../principles/PROMPT_PRINCIPLES.md` (инварианты канона + чеклист). + +## ⚠️ Антипаттерн +Скопировать enduro-промпт целиком и оставить «MapLibre/OSRM/terrain» в проекте, который к картам отношения не имеет. Каркас — да, содержимое — своё. + +--- +*Эталонный репо: enduro-trails (в той же Gitea-инстанции). Здесь только указатели — не копии.* diff --git a/principles/PROMPT_PRINCIPLES.md b/principles/PROMPT_PRINCIPLES.md new file mode 100644 index 0000000..beaf792 --- /dev/null +++ b/principles/PROMPT_PRINCIPLES.md @@ -0,0 +1,94 @@ +# ORCH-9 — Принципы подготовки промптов агентов (методичка онбординга) + +> Репозиторий onboard2orch — методология онбординга (ORCH-9). +> Это **принципы и инструкции**, КАК готовить промпты агентов для ЛЮБОГО проекта. +> **enduro-trails (ET) используется как пример-референс** — НЕ как шаблон для копирования. Каждый проект пишет СВОИ промпты под свою специфику. + +--- + +## 1. Базовый принцип: изоляция +- Промпты живут в репо проекта: `.openclaw/agents/.md`. Launcher читает их в рабочем дереве задачи (`cat {system_prompt}` внутри work_path). +- **Промпты СПЕЦИФИЧНЫ для проекта.** Стек, домен, ограничения — свои у каждого. НЕ копировать чужие промпты дословно — копировать СТРУКТУРУ и ПРИНЦИПЫ. +- Полный набор ролей: `analyst`, `architect`, `developer`, `reviewer`, `tester`, `deployer`. + +## 2. Обязательная структура промпта (каркас) +Каждый промпт роли строится по единому каркасу (референс — `enduro-trails/.openclaw/agents/architect.md`): + +``` +--- +name: +description: <одна строка — роль и зона ответственности> +model: <модель — сверить с src/agents/launcher.py AGENT_CONFIGS> +tools: + - <разрешённые инструменты, напр. Filesystem Read везде / Write только docs|src> +--- + +# System prompt: +<кто ты в этом проекте, твоя задача> + +## Контекст проекта +<стек, среды, ключевая специфика — КОРОТКО, детали в CLAUDE.md> + +## Что прочесть в начале +1. CLAUDE.md (паспорт проекта) +2. docs/architecture/README.md +3. <релевантные артефакты задачи: docs/work-items//...> +4. <глобальные ADR: docs/architecture/adr/ — для architect/developer> + +## Что произвести +<точные имена артефактов, которые роль ПИШЕТ — по канону проекта> + +## Принципы +<доменные принципы проекта — из BRD/архитектуры> + +## Запрещено +<анти-паттерны для этого проекта> + +## Эскалация +<когда возврат на предыдущую стадию / нужен approve Owner> +``` + +## 3. Что ОБЯЗАНО быть в КАЖДОМ промпте (инварианты канона) +Независимо от проекта: +1. **«Прочти `CLAUDE.md` и `docs/architecture/README.md` перед работой»** — в разделе «Что прочесть в начале». +2. **Точные имена артефактов проекта** в «Что произвести» (берутся из CLAUDE.md проекта; у каждого проекта свой набор — см. п.5). +3. **Golden source:** «изменил функционал → обнови документацию В ТОМ ЖЕ изменении». +4. **Не править артефакты других стадий.** +5. **Не закрывать задачу самостоятельно** — это делает CI / финальная стадия. +6. **Машинные вердикты** — только YAML-frontmatter (`verdict:`, `deploy_status:`, `staging_status:`), никогда проза. Это читают Quality Gates. + +## 4. Роль-специфичные инварианты +- **analyst** → производит BRD/ТЗ/AC/Test-Plan; НЕ проектирует решения. +- **architect** → заводит ADR (per-work-item + сквозные в `docs/architecture/adr/`); обновляет `docs/architecture/README.md` при изменении состава компонентов; эскалирует крупные изменения (лейбл `arch:major-change`, approve Owner). +- **developer** → код+тесты+PR; обновляет CHANGELOG и релевантную доку; не закрывает задачу. +- **reviewer** → пишет `12-review.md` с `verdict:`. **Reviewer-gate:** если PR меняет функционал, а документация (docs/, CHANGELOG, ADR) НЕ обновлена → `verdict: REQUEST_CHANGES` с указанием, что обновить. Это держит канон автоматически. +- **tester** → прогон по test-plan → `13-test-report.md` с машинным PASS/FAIL. +- **deployer** → деплой/проверка; пишет `14-deploy-log.md` (+ `15-staging-log.md` если у проекта есть staging-гейт). Знает инфра-риски проекта (см. `docs/operations/INFRA.md` если есть). + +## 5. Откуда брать значения для конкретного проекта +| Что | Источник | +|-----|----------| +| Имена артефактов | `CLAUDE.md` проекта (раздел «Артефакты задачи») | +| Модель роли | `src/agents/launcher.py` → `AGENT_CONFIGS` (НЕ выдумывать) | +| Стек / домен / ограничения | `CLAUDE.md` + `docs/architecture/README.md` проекта | +| Цепочка стадий и QG | `src/stages.py` / `docs/architecture/README.md` | +| Инфра-риски (для deployer) | `docs/operations/INFRA.md` проекта (если есть) | + +## 6. Пример-референс: enduro-trails +Готовый, обкатанный в бою набор: `enduro-trails (эталонный репо) .openclaw/agents/*.md`. +Изучать как ОБРАЗЕЦ структуры и тона: +- `architect.md` — эталон каркаса (frontmatter → контекст → что прочесть → что произвести → принципы → запрещено → эскалация). +- Видно, как доменная специфика (MapLibre/OSRM/terrain, «всё в Docker», «vanilla JS > React») зашита в «Принципы» и «Запрещено». +- **При онбординге нового проекта:** взять этот каркас, заменить ВСЁ доменное содержимое на специфику нового проекта. Не тащить enduro-специфику в чужой проект. + +## 7. Чеклист готовности набора промптов проекта +- [ ] Все 6 ролей заведены в `.openclaw/agents/` +- [ ] Каждый ссылается на CLAUDE.md + docs/architecture/README.md +- [ ] Имена артефактов совпадают с CLAUDE.md проекта +- [ ] Модели сверены с launcher.py +- [ ] reviewer содержит reviewer-gate на документацию +- [ ] Доменные «Принципы» и «Запрещено» — под этот проект, не скопированы у другого +- [ ] deployer знает инфра-специфику/риски проекта + +--- +*Методичка ORCH-9. enduro-trails — пример-референс, не шаблон. Каждый проект изолирован и пишет свои промпты по этим принципам.*