auto-sync: 2026-05-15 01:30:01

tasks/multi-agent/BRD.md

@@ -154,6 +154,147 @@ related:
 
 Пропущен на пилоте: Дизайн (UI-макеты пока ручные).
 
+## 5.1. Структура репозитория (канон)
+
+```
+enduro-trails/
+├── CLAUDE.md                          # Паспорт проекта для агентов
+├── README.md
+├── CHANGELOG.md
+├── Makefile                           # make dev / test / lint / build
+├── Dockerfile
+├── docker-compose.yml
+├── .env.example
+├── .gitea/workflows/                  # CI (Gitea Actions)
+│   └── ci.yml
+├── .openclaw/agents/                  # system prompts агентов
+│   ├── architect.md
+│   ├── developer.md
+│   ├── reviewer.md
+│   └── tester.md
+├── docs/
+│   ├── architecture/
+│   │   ├── README.md
+│   │   ├── c4-context.mmd
+│   │   ├── c4-component.mmd
+│   │   └── adr/
+│   └── work-items/
+│       └── <plane-id>/
+│           ├── 00-business-request.md
+│           ├── 01-brd.md
+│           ├── 02-trz.md
+│           ├── 03-acceptance-criteria.md
+│           ├── 04-test-plan.yaml
+│           ├── 06-adr/
+│           ├── 12-review.md
+│           └── 13-test-report.md
+├── src/
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── scripts/
+│   ├── lint-spec.sh
+│   ├── lint-adr.sh
+│   └── req-coverage.py
+└── migrations/
+```
+
+Все артефакты имеют YAML frontmatter (type, plane_id, status, version). Линтеры проверяют наличие и валидность.
+
+## 5.2. CLAUDE.md (паспорт проекта)
+
+Файл в корне репо — первое что читает каждый агент при запуске. Содержит:
+- Стек технологий
+- Команды (make dev/test/lint/build)
+- Структура проекта
+- Конвенции (commits, branches, naming)
+- Правила для агентов (что можно, что нельзя)
+
+## 5.3. Формат запуска агентов
+
+Orchestrator запускает Claude Code CLI:
+
+```bash
+cd /home/slin/repos/enduro-trails && \
+claude -p "Прочитай CLAUDE.md. Прочитай docs/work-items/<plane-id>/02-trz.md и все артефакты предыдущих этапов. Реализуй задачу согласно своей роли. Закоммить результат." \
+  --allowedTools read,write,edit,bash \
+  --systemPrompt "$(cat .openclaw/agents/developer.md)"
+```
+
+Параметры:
+- `--systemPrompt` — роль агента (из `.openclaw/agents/<role>.md`)
+- `--allowedTools` — ограниченный набор инструментов
+- Рабочая директория — корень репо (агент видит весь проект)
+- Бюджет: ограничен через Max подписку (5-часовое окно)
+
+## 5.4. Обратная волна (back-to)
+
+Когда агент возвращает задачу на предыдущий этап:
+
+**Reviewer → Developer:**
+1. Reviewer ставит `request-changes` в PR (через Gitea API)
+2. Orchestrator получает webhook → лейбл `back-to:dev`
+3. Orchestrator запускает Developer повторно (читает комментарии review)
+4. Лимит: ≤3 итерации. После 3-й → `escalation:human-needed`, уведомление Славе
+
+**Tester → Developer:**
+1. Tester находит баг → создаёт issue в Plane, пишет в test-report
+2. Orchestrator: лейбл `back-to:dev`, PR возвращается в stage:dev
+3. Developer фиксит → снова QG-4 → QG-5 → QG-6
+
+**Architect → Analyst (Стрим):**
+1. Architect находит противоречие в ТЗ → коммитит комментарий, лейбл `back-to:analysis`
+2. Orchestrator уведомляет Стрим → Стрим правит ТЗ → новый :approved: от Славы
+
+## 5.5. Эскалация
+
+Оркестратор эскалирует к Славе когда:
+- Агент 3 раза вернулся на предыдущий этап
+- Claude Code CLI вернул ошибку (rate limit, timeout, crash)
+- QG красный после 3 попыток
+- Найдена security-уязвимость уровня critical
+
+Формат: уведомление в Plane (комментарий + лейбл `escalation:*`) + сообщение Славе через Стрим.
+
+## 5.6. Идемпотентность и очередь
+
+**Идемпотентность:** webhooks могут дублироваться. Orchestrator проверяет:
+- Не запущен ли уже агент на эту задачу (lock по plane_id + stage)
+- Не обработано ли уже это событие (event_id в журнале)
+
+**Очередь:** задачи выполняются последовательно (один Claude Code CLI одновременно). Orchestrator ведёт FIFO-очередь. Приоритет: urgent > high > medium > low.
+
+## 5.7. Service account в Git
+
+- User: `claude-bot` в Gitea
+- Email: `claude-bot@mva154.local`
+- PAT-токен для push в feature-ветки
+- Не имеет права push в main (только через PR merge)
+- Все коммиты агентов — от этого аккаунта (отличимы от человеческих)
+
+## 5.8. Plane → Orchestrator: события
+
+| Событие Plane | Реакция Orchestrator |
+|---------------|---------------------|
+| `work_item.created` (Feature) | QG-0 → создать ветку + подзадачи + папку docs/ |
+| `:approved:` от Славы на подзадаче «Анализ» | QG-1 → запустить Architect |
+| Подзадача «Архитектура» → done | QG-2 → запустить Developer |
+| CI green на PR | QG-4 → запустить Reviewer |
+| Review approved | QG-5 → запустить Tester |
+| Test report: verdict=pass | QG-6 → merge PR, deploy |
+| `:approved:` от Славы после деплоя | QG-7 → закрыть Work Item |
+
+## 5.9. Tester — scope на пилоте
+
+На пилоте Tester запускает:
+- Unit-тесты (повторно, в чистой среде)
+- Integration-тесты
+- E2e-тесты (Playwright) по Acceptance Criteria из `04-test-plan.yaml`
+- Формирует `13-test-report.md`
+
+Не на пилоте (v2): visual regression, a11y (axe-core), performance, security scan.
+
 ## 6. Quality Gates
 
 | QG | Между | Что проверяет | Как |