orchestrator/docs/ARCHITECTURE.md

Архитектура Orchestrator

Обзор

Orchestrator — event-driven FastAPI сервис, который управляет жизненным циклом задач разработки через мульти-агентный пайплайн. Каждая задача проходит через фиксированные стадии, на каждой из которых работает специализированный Claude CLI агент.

Компоненты

1. Webhook Receivers

Plane Webhook (src/webhooks/plane.py)

• Принимает work_item.created — создаёт задачу в DB, запускает analyst
• Принимает work_item.updated — синхронизация статусов

Gitea Webhook (src/webhooks/gitea.py)

• push — проверяет наличие артефактов (docs/, src/), продвигает стадию
• pull_request* (wildcard) — обрабатывает review approved/rejected, PR merge
• status — CI green/failure, продвигает development → review

2. State Machine (src/stages.py)

Линейный пайплайн с одним возможным откатом (review → development):

STAGE_TRANSITIONS = {
    created:      → analysis      (agent: None)
    analysis:     → architecture  (agent: architect,  QG: check_analysis_complete)
    architecture: → development   (agent: developer,  QG: check_architecture_done)
    development:  → review        (agent: reviewer,   QG: check_ci_green)
    review:       → testing       (agent: tester,     QG: check_review_approved)
    testing:      → deploy        (agent: None,       QG: check_tests_passed)
    deploy:       → done          (agent: None,       QG: None)
}

3. Quality Gates (src/qg/checks.py)

Check	Метод проверки
check_analysis_complete	Filesystem: 4 файла в docs/work-items/{id}/
check_architecture_done	Filesystem: ADR dir или infra-requirements.md
check_ci_green	Gitea API: GET /commits/{branch}/status
check_review_approved	Gitea API: GET /pulls/{n}/reviews (skip stale)
check_tests_passed	Filesystem: test-report.md содержит "PASS"

4. Agent Launcher (src/agents/launcher.py)

Запускает Claude CLI как subprocess:

claude.exe --print  --system-prompt  --allowedTools Read,Write,Edit,Bash

Каждый запуск:

1. Записывает run в DB (agent_runs)
2. Запускает subprocess с stdout → /app/data/runs/{id}.log
3. Стартует watchdog thread (timeout 30 мин → SIGKILL)
4. Стартует monitor thread (ждёт завершения → git commit/push → auto-advance)

5. Auto-advance (launcher._try_advance_stage)

После успешного завершения агента:

1. Определяет текущую стадию задачи
2. Проверяет QG для выхода из стадии
3. Если QG пройден — продвигает стадию
4. Запускает следующего агента (если определён)

Исключение: check_review_approved — обрабатывается через PR webhook, не через auto-advance.

6. Review Bounce

При REQUEST_CHANGES:

1. Считает количество developer runs для задачи
2. Если < MAX_DEV_RETRIES (3) — откатывает в development, перезапускает developer
3. Если >= MAX_DEV_RETRIES — эскалация (логирование + уведомление)

Database Schema

-- Задачи
CREATE TABLE tasks (
    id INTEGER PRIMARY KEY,
    work_item_id TEXT,          -- Plane issue identifier (e.g. "ET-006")
    plane_issue_id TEXT,        -- Plane UUID
    repo TEXT,
    branch TEXT,
    stage TEXT DEFAULT 'created',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Запуски агентов
CREATE TABLE agent_runs (
    id INTEGER PRIMARY KEY,
    task_id INTEGER REFERENCES tasks(id),
    agent TEXT,                 -- analyst/architect/developer/reviewer/tester
    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    finished_at TIMESTAMP,
    exit_code INTEGER,
    output_path TEXT            -- /app/data/runs/{id}.log
);

-- Сырые события
CREATE TABLE events (
    id INTEGER PRIMARY KEY,
    source TEXT,               -- plane/gitea
    event_type TEXT,
    payload TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Deployment

Docker Compose

services:
  orchestrator:
    build: .
    container_name: orchestrator
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/app/data                    # SQLite + logs
      - /home/slin/repos:/repos             # Git repositories
      - /var/run/docker.sock:/var/run/docker.sock  # Docker CLI
      - claude-code:/opt/claude-code:ro     # Claude CLI binary
      - /home/slin/.claude:/home/slin/.claude      # Claude config
    env_file: .env
    group_add: ["999"]         # docker group

Dockerfile

• Base: python:3.12-slim
• Docker CLI (sibling containers)
• tini как PID 1 (proper zombie reaping)
• git config --global safe.directory '*'
• ENTRYPOINT: tini → uvicorn

Потоки данных

Happy path (ET-006 пример)

1. Plane webhook: work_item.created → task created, analyst launched
2. Analyst: пишет BRD/TRZ/AC/TestPlan → git push docs/
3. Gitea push webhook: docs/ detected → QG check_analysis_complete → PASS
4. Auto-advance: analysis → architecture, architect launched
5. Architect: пишет ADR, infra-requirements → git push docs/
6. Gitea push webhook: ADR detected → QG check_architecture_done → PASS
7. Auto-advance: architecture → development, developer launched
8. Developer: пишет код src/ + tests/ → git push, creates PR
9. Gitea status webhook: CI green → QG check_ci_green → PASS
10. Auto-advance: development → review, reviewer launched
11. Reviewer: оставляет review (APPROVED или REQUEST_CHANGES)
12. Gitea PR webhook: review event → QG check_review_approved → PASS
13. Advance: review → testing, tester launched
14. Tester: прогоняет тесты, пишет test-report.md → git push
15. Auto-advance: testing → deploy (QG check_tests_passed → PASS)
16. PR merge → Gitea PR webhook: action=closed, merged=true → done

Review bounce path

11. Reviewer: REQUEST_CHANGES
12. Gitea PR webhook: review_state=REQUEST_CHANGES, stage=review
13. Rollback: review → development, developer relaunched (attempt N/3)
14. Developer: фиксит замечания → git push
15. CI green → development → review, reviewer relaunched
16. Reviewer: APPROVED → continue happy path

Resilience

Механизм	Описание
Orphan recovery	При старте: runs без finished_at старше 35 мин → exit_code=-1
Watchdog	Каждый агент: timeout 30 мин → SIGKILL + exit_code=-9
tini	PID 1 reaper — zombie processes невозможны
safe.directory	git операции работают в любой директории
Stale review skip	check_review_approved игнорирует stale reviews
Max retries	Developer: max 3 попытки, затем эскалация

Агенты

Каждый агент — Claude CLI с:

• System prompt: .openclaw/agents/{role}.md (в репозитории)
• Task file: .task-{suffix}.md (генерируется orchestrator)
• Tools: Read, Write, Edit, Bash
• Output: --print mode (весь вывод в stdout после завершения)

Агент	Артефакты	Время (типичное)
analyst	BRD, TRZ, AC, TestPlan	5-10 мин
architect	ADR, infra-requirements, tech-risks	5-10 мин
developer	src/, tests/, PR	15-30 мин
reviewer	review report, PR review	3-5 мин
tester	test-report.md, e2e results	10-25 мин