KB Orchestrator Workflow

Цель

Сделать выполнение задач через оркестратор воспроизводимым: чёткие этапы → артефакты → проверки → ревью → фиксы → (для UI) Playwright‑проверка → финальный отчёт.

Codex-like Tasks (продуктовый режим)

• •Пользователь ставит задачу как Task (repo + base ref + prompt + N версий).
• •Каждая версия (TaskVersion) живёт в своём изолированном окружении (у нас: отдельный worktree/workspace на worker’е).
• •Запуск “как в Codex”: Task сразу попадает в очередь, а worker сам берёт следующее из очереди (без ручного “run-next”/кнопок запуска воркера).
• •Пайплайн стадий (MVP): research? → execute → tests → review → fix.
  • •research опционален: orchestrator решает, нужен ли он по контексту/задаче.
  • •tests может включать “run/smoke/Playwright” для веб‑приложений → обычно это делает tester с capability=network.
  • •“user‑facing deploy” (URL/порт для пользователя) — отдельный опциональный Job/подстадия, включаемая только при явной необходимости.
  • •review должен быть read-only (например, codex exec -s read-only ...), результат — отчёт, а не изменения.
  • •fix применяет выводы ревью; при необходимости повторить tests.
• •UX “версий”:
  • •Код-ревью: параллельно запустить N версий, собрать фидбэк и агрегировать уникальное.
  • •Креатив: выбрать лучшую версию/вариант и продолжать только её (или разветвить выбранную ещё на 2–4).

Связанные навыки (использовать как подпроцессы)

• •Code review request: .codex/skills/requesting-code-review/SKILL.md
• •Code review apply: .codex/skills/receiving-code-review/SKILL.md
• •Frontend дизайн: .codex/skills/frontend-design/SKILL.md
• •Отправка файлов в Telegram: .codex/skills/tg-mcp-send-files/SKILL.md

Инварианты (safety)

• •Не делать git push без явного запроса пользователя.
• •Не использовать sudo.
• •Держать рабочее дерево чистым: всё нужное — закоммитить, рантайм/артефакты — в .gitignore.
• •Для “executor без сети”: не полагаться на удачу. Если нужен интернет — добывать материалы control‑plane’ом и передавать локально.

Артефакты (канонично)

• •В целевом проекте держать ORCH_RUN.md: старт/финиш, исходный prompt, точные команды, ссылки, итерации, job_id.
• •В оркестраторе использовать артефакты orchestrator/state/artifacts/<job_id>/summary.json и iterations.json как источник правды по времени/итерациям.

Этапы (строго по порядку)

0) Зафиксировать вводные

• •Зафиксировать pwd и целевую папку работы (если нужно “не захламлять” — подняться уровнем выше и работать рядом).
• •Создать/обновить ORCH_RUN.md (в целевом репо): Start, цель, URL (если UI), критерии DoD.
• •Сформулировать DoD и stop‑условие (по умолчанию COMPLETED строго последней строкой stdout).

1) Подготовить целевой репозиторий

• •Создать папку/репо, настроить git‑identity (локально).
• •Добавить .gitignore, базовый README.md, тестовый каркас, ruff/mypy.
• •Прогнать проверки локально и сделать baseline commit.

2) Сформировать prompt для executor (качество постановки)

• •Явно перечислить: ограничения (no push/sudo), DoD, команды проверок, артефакты.
• •Если задача про UI: указать URL и требование проверить сценарии через Playwright MCP.
• •Встроить “loop hook”: COMPLETED (и опционально BLOCKER) как последняя строка stdout.
• •Записать prompt в ORCH_RUN.md (как “исходный запрос”).

3) Выполнить реализацию (executor)

• •Делать маленькие, проверяемые шаги.
• •Коммитить осмысленными порциями; не оставлять мусор/временные файлы вне .gitignore.
• •Не менять тесты executor’ом (если политика включена) — для тестов использовать отдельный этап/роль.

4) Прогнать проверки через KB Orchestrator (валидировать и собрать артефакты)

• •Зарегистрировать repo:
  • •cd orchestrator
  • •../.venv/bin/python -m kb_orchestrator repo add --id <id> --path <abs_path>
• •Создать job на проверки (пример):
  • •../.venv/bin/python -m kb_orchestrator job create --repo <id> --max-iters 3 --completion-keyword COMPLETED -- bash -lc '<checks...>; echo COMPLETED'
• •Запустить worker:
  • •../.venv/bin/python -m kb_orchestrator worker run (по умолчанию в цикле; --once чтобы выполнить один job)
• •Если blocked:
  • •“грязное дерево” → создать отдельную cleanup‑подзадачу (commit/ignore), без авто‑удалений.
  • •“executor modified tests” → откатить/перенести изменения тестов в отдельный этап.

5) Создать агента на code review (requesting-code-review)

• •В отдельном запуске/топике попросить review по {BASE_SHA}..{HEAD_SHA}.
• •Следовать .codex/skills/requesting-code-review/SKILL.md.
• •Сохранить результат в целевом репо (например CODE_REVIEW.md) и залинковать из ORCH_RUN.md.

6) Создать агента на фиксы по ревью (receiving-code-review)

• •В отдельном запуске/топике применить рекомендации, проверяя техническую корректность.
• •Следовать .codex/skills/receiving-code-review/SKILL.md.
• •После каждого батча фиксов повторить этап 4 (оркестратор‑проверки).

7) Для UI: проверить поведение через Playwright MCP

• •Поднять сервер на 0.0.0.0 (и зафиксировать PID/лог/stop‑команду в ORCH_RUN.md).
• •Проверить сценарий “как пользователь” через MCP Playwright:
  • •mcp__playwright__browser_navigate → URL (например http://192.168.77.4:8000)
  • •mcp__playwright__browser_snapshot → зафиксировать состояние
  • •при проблемах: mcp__playwright__browser_console_messages, mcp__playwright__browser_network_requests
• •Если найдены ошибки/несостыковки: создать fix‑подзадачу и повторить 4 → 7.

8) Финализировать и отчитаться

• •Обновить ORCH_RUN.md:
  • •время (start/end), итерации, job_id, список команд, исходный prompt, ссылку на результат.
• •В ответ пользователю всегда дать:
  1. •сколько времени заняло
  2. •сколько итераций (по iterations.json)
  3. •.md с командами+prompt
  4. •ссылку/URL
  5. •доп. заметки/риски/ограничения
• •Отправить ORCH_RUN.md в Telegram документом через MCP (см. .codex/skills/tg-mcp-send-files/SKILL.md).