wiki/tasks/multi-agent/DEV_TASK_ANALYST_IN_ORCHESTRATOR.md

DEV TASK: Analyst в Orchestrator (полноценная стадия Analysis)

Статус: ✅ Done (31.05.2026)
Связанная задача: DEV_TASK_ANALYST_PLANE_SYNC.md (расширение — Plane sync)
Проект: multi-agent
Приоритет: High
Зависит от: DEV_TASK_ORCHESTRATOR_MVP, DEV_TASK_ORCHESTRATOR_FIXES, DEV_TASK_PLANE_SYNC

---

Контекст

Analyst agent уже существует как самостоятельный агент OpenClaw (/home/node/.openclaw/agents/analyst/, модель vibecode/claude-sonnet-4.6, отдельный Telegram binding).

Однако в текущем Orchestrator пайплайне (Plane → webhook → stage machine → Claude CLI) Analyst не участвует. Стадия analysis отсутствует.

Первый прогон ET-002 начался сразу со стадии architecture, потому что BRD/ТЗ были подготовлены вручную Стримом.

Цель: Сделать Analyst полноценной первой стадией конвейера:

• При создании тикета в Plane (или переводе в Analysis) → Orchestrator автоматически запускает Analyst
• Analyst получает 00-business-request.md (или формирует его из описания тикета)
• Analyst пишет BRD, ТЗ, AC, Test Plan в docs/work-items/<id>/
• Analyst задаёт вопросы через Plane comments, ждёт :approved:
• После approve → stage автоматически переходит в architecture, запускается Architect

---

Задачи

1. Добавить стадию analysis в stage machine

Файл: src/stages.py

Что сделать:

• Добавить analysis как первую после created
• Обновить маппинг STAGES и STAGE_TRANSITIONS
• Добавить Quality Gate qg_analysis_approved (проверка наличия BRD + AC + :approved: от стейкхолдера)

Ожидаемый переход:

created → analysis (launch Analyst) → architecture (после :approved:)

2. Роутинг webhook'ов из Plane на Analyst

Файл: src/webhooks/plane.py

Что сделать:

• В handle_issue_created / handle_issue_updated:
  • Если issue создан или переведён в статус/свойство, соответствующее Analysis → вызвать launcher.launch("analyst", repo, task_desc, task_id=task_id)
  • Сохранить plane_issue_id в таблицу tasks

Пример логики:

if stage == "analysis" and not has_brd(task_id):
    run_id = launcher.launch("analyst", repo, task_desc, task_id=task_id)
    plane_sync.post_comment(plane_issue_id, "Analyst запущен. BRD в работе.")

3. Quality Gate для Analysis

Файл: src/qg/checks.py

Что сделать:

• Добавить функцию check_analysis_approved(repo: str, branch: str) -> tuple[bool, str]
• Проверка:
  • Наличие docs/work-items/<id>/01-brd.md
  • Наличие docs/work-items/<id>/02-trz.md
  • Наличие docs/work-items/<id>/03-acceptance-criteria.md
  • Комментарий стейкхолдера с :approved: (или reaction)

Вызывать в handle_push / handle_status (аналогично check_ci_green).

4. Автоматическое продвижение после approve от стейкхолдера

Файл: src/webhooks/plane.py (или gitea.py для комментариев)

Что сделать:

• При получении комментария с :approved: на Work Item:
  • Если текущая стадия analysis и QG check_analysis_approved проходит → advance_stage(task_id, "analysis", "architecture")
  • Запустить Architect: launcher.launch("architect", repo, task_desc, task_id=task_id)

5. Обновить документацию

Файлы:

• tasks/multi-agent/BRD.md — добавить описание стадии Analysis и QG
• tasks/multi-agent/STATUS.md — обновить таблицу этапов и roadmap
• tasks/multi-agent/DEV_TASK_ORCHESTRATOR_MVP.md — отметить выполненный пункт

6. (Опционально) Поддержка 00-business-request.md

Файл: src/webhooks/plane.py

Что сделать:

• При создании тикета автоматически создавать 00-business-request.md из описания issue + кастомных полей
• Передавать путь к этому файлу в промпт Analyst'а

---

Файлы для изменения

Файл	Изменения	Приоритет
src/stages.py	Добавить analysis стадию + QG	High
src/webhooks/plane.py	Роутинг на analyst + обработка approve	High
src/qg/checks.py	check_analysis_approved()	High
src/agents/launcher.py	(возможно) спец. обработка analyst	Medium
tasks/multi-agent/BRD.md	Документация Analysis	Medium
tasks/multi-agent/STATUS.md	Обновить статус	Low

---

Ограничения

• НЕ менять порт 8500
• НЕ ломать существующий цикл (ET-002 и дальше должны продолжать работать)
• Analyst НЕ пишет код (только документы)
• Analyst всегда ждёт :approved: перед закрытием подзадачи Analysis

---

Порядок выполнения

1. stages.py (добавить analysis)
2. qg/checks.py (check_analysis_approved)
3. plane.py (роутинг + approve handler)
4. Документация
5. Тест: создать тестовый тикет в Plane → Analyst запускается → пишет BRD → Слава ставит :approved: → stage → architecture

---

Команды проверки после деплоя

# 1. Health
curl -s http://localhost:8500/health

# 2. Создать тестовый тикет в Plane (статус Analysis) → проверить, что в БД tasks появилась запись
docker exec orchestrator python -c "
import sqlite3
conn = sqlite3.connect('/app/data/orchestrator.db')
conn.row_factory = sqlite3.Row
r = conn.execute('SELECT * FROM tasks ORDER BY id DESC LIMIT 1').fetchone()
print(dict(r))
"

# 3. Проверить, что Analyst запустился (в agent_runs)
docker exec orchestrator python -c "
import sqlite3
conn = sqlite3.connect('/app/data/orchestrator.db')
conn.row_factory = sqlite3.Row
for r in conn.execute('SELECT * FROM agent_runs WHERE agent=\"analyst\" ORDER BY id DESC LIMIT 3').fetchall():
    print(dict(r))
"

---

Результат

После выполнения этой задачи:

• Analyst становится полноценной первой стадией автоматического конвейера
• Создание тикета в Plane с описанием фичи → Analyst автоматически пишет BRD/ТЗ/AC/Test Plan
• Слава только отвечает на вопросы и ставит :approved:
• Дальше пайплайн идёт автоматически (architecture → development → review → testing → deploy)