wiki/tasks/multi-agent/ORCHESTRATOR_DOCS.md

Документация: Orchestrator Multi-Agent Pipeline

Статус: 2026-06-01 (актуально)

---

Архитектура

Plane (Work Items) → Webhook → Orchestrator → Claude CLI agents → Gitea → Deploy

Orchestrator — Python FastAPI приложение в Docker на mva154 (port 8500). Слушает webhooks от Plane и Gitea, управляет жизненным циклом задач.

---

Конвейер (Pipeline)

created → analysis → architecture → development → review → testing → deploy → done

Stage	Agent	QG (вход)	Что делает
analysis	analyst	—	BRD, ТЗ, AC, Test Plan
architecture	architect	check_analysis_approved (:approved: от Славы)	ADR, архитектурные решения
development	developer	check_architecture_done (файлы ADR есть)	Код + тесты + PR
review	reviewer	check_ci_green (Gitea CI status)	Code review → 12-review.md
testing	tester	check_reviewer_verdict (APPROVED в 12-review.md)	Прогон тестов → 13-test-report.md
deploy	deployer	check_tests_passed (PASS в 13-test-report.md)	Merge PR → tag → deploy → smoke
done	—	—	Задача завершена

---

Агенты

Конфигурация (AGENT_CONFIGS)

Agent	Task file	System prompt	Model
analyst	.task.md	.openclaw/agents/analyst.md	claude-sonnet-4-6
architect	.task-arch.md	.openclaw/agents/architect.md	claude-sonnet-4-6
developer	.task-dev.md	.openclaw/agents/developer.md	claude-sonnet-4-6
reviewer	.task-review.md	.openclaw/agents/reviewer.md	claude-sonnet-4-6
tester	.task-test.md	.openclaw/agents/tester.md	claude-sonnet-4-6
deployer	.task-deploy.md	.openclaw/agents/deployer.md	claude-sonnet-4-6

Deployer (добавлен 2026-06-01)

Функции:

1. Merge PR через Gitea API
2. Создать semver tag (patch increment)
3. Deploy (git pull main на сервере)
4. Healthcheck (до 60 сек, 12 попыток)
5. Smoke test (ключевые endpoints)
6. Rollback к предыдущему тегу при fail
7. Записать 14-deploy-log.md + обновить CHANGELOG.md

Запрещено: менять код, force push, деплоить без merge.

---

Quality Gates

QG	Функция	Что проверяет
check_analysis_approved	:approved: в комментарии Plane от стейкхолдера	Человеческое подтверждение ТЗ
check_architecture_done	Наличие ADR файлов в docs/work-items/<id>/06-adr/	Архитектура задокументирована
check_ci_green	Gitea commit status API	CI pipeline зелёный
check_reviewer_verdict	Парсинг 12-review.md → APPROVED/REQUEST_CHANGES	Код прошёл ревью
check_tests_passed	Парсинг 13-test-report.md → PASS/FAIL	Тесты пройдены

---

Механизмы автономности

Auto-advance

После завершения агента (exit 0), _monitor_agent вызывает _try_advance_stage:

1. Определяет текущий stage задачи
2. Проверяет QG следующего stage
3. Если QG green → advance stage → launch next agent
4. Если QG red → stop (ждёт внешнего события)

Auto-PR

После developer push, _ensure_pr() автоматически создаёт PR в Gitea.

Retry (developer)

При REQUEST_CHANGES от reviewer'а — developer перезапускается (до 3 раз).

Notifications

Telegram уведомления на каждом переходе stage + при ошибках.

---

Файловая структура

/home/slin/repos/orchestrator/
├── src/
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings (env vars)
│   ├── db.py                # SQLite (tasks, agent_runs)
│   ├── stages.py            # STAGE_TRANSITIONS
│   ├── notifications.py     # Telegram + Plane comments
│   ├── plane_sync.py        # Plane API integration
│   ├── agents/
│   │   ├── launcher.py      # AgentLauncher (AGENT_CONFIGS, launch, monitor)
│   │   └── __init__.py
│   ├── webhooks/
│   │   ├── gitea.py         # Push, PR, CI status handlers
│   │   ├── plane.py         # Comment handlers (:approved:)
│   │   └── __init__.py
│   └── qg/
│       ├── checks.py        # QG check functions
│       └── __init__.py
├── docker-compose.yml
├── Dockerfile
└── requirements.txt

---

Инфраструктура

• Host: mva154 (82.22.50.71)
• Container: orchestrator (port 8500)
• Gitea: localhost:3000 (в docker network)
• Repos: /home/slin/repos/orchestrator, /repos/enduro-trails (в контейнере)
• DB: SQLite (/app/data/orchestrator.db)
• Logs: /app/data/logs/ (per-agent run logs)

---

Единственная точка ручного вмешательства

:approved: после analyst'а — Слава подтверждает ТЗ в Plane.

Всё остальное — полностью автономно:

• architect запускается автоматически после approve
• developer → после architecture done
• reviewer → после CI green
• tester → после review approved
• deployer → после tests passed
• done → после deploy success

---

Расхождения с Proposal v1

Полная таблица: tasks/multi-agent/PROPOSAL_VS_REALITY.md

Ключевые отличия от идеала:

• Designer не реализован (skip для не-UI задач)
• QG упрощены (проверка файлов, не lint-скрипты)
• Один environment (test), нет prod
• Нет budget tracking
• Все агенты на Sonnet (proposal: Architect/Reviewer на Opus)

---

Changelog

Дата	Изменение
2026-05-31	Fix: _monitor_agent PIPE streaming (race condition)
2026-05-31	Fix: check_reviewer_verdict вместо check_review_approved
2026-05-31	Add: _ensure_pr (auto-PR after developer push)
2026-05-31	Add: REQUEST_CHANGES retry logic (3 attempts)
2026-06-01	Add: deployer agent (merge → tag → deploy → smoke → rollback)
2026-06-01	Remove: _auto_merge_pr hardcode from _try_advance_stage