wiki/tasks/multi-agent/DEV_TASK_ANALYST_IN_ORCHESTRATOR.md

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

**Статус:** Ready for dev  
**Проект:** 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`

**Пример логики:**
```python
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

---

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

```bash
# 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)