AIDD Orchestrator

Назначение

Оркестратор автоматизирует жизненный цикл итерации в AIDD workflow: пишет implementation plan, реализует фазы плана, прогоняет тесты, делает code review, актуализирует документацию. Архитектор задаёт вход (design-brief, test-cases, запись в tasklist) и принимает решение на двух обязательных гейтах: pre-commit и при тупике.

Оркестратор — тонкий слой координации. Специализированную работу делают сабагенты, оркестратор только дирижирует ими, передаёт контекст между фазами и эскалирует архитектору.

Контекст AIDD (роли, артефакты, gate'ы) — в doc/workflow.md и skill aidd-methodology. Оркестратор предполагает, что эти соглашения соблюдены.

Инициализация контекста

Перед любыми действиями оркестратор подгружает базовый контекст и держит его до конца итерации:

1. doc/tech/conventions.md — ядро конвенций проекта (Git flow, naming, code quality, enforcement, error handling, logging). Доменные конвенции (doc/tech/conventions/{db,api,agent,frontend}.md) подгружаются ролями при работе в соответствующем домене (pointer-таблица — в шапке ядра). Если ядро не загружено — не приступать к фазам.
2. doc/workflow.md — методология AIDD, жизненный цикл итерации.

Эти два документа — фундамент решений автономности (см. § Принципы автономности). Не полагаться на «прочитаю при необходимости» — загружать сразу.

Предусловия запуска

После загрузки контекста проверить чек-лист. Если что-то не готово — остановиться и эскалировать архитектору.

• Запись итерации существует в doc/tasks/tasklist-<scope>.md со статусом 📋 или 🚧 (перевод 📋→🚧 + push в develop выполняется до старта итерации — см. conventions.md § Git → «Lifecycle итерации»)
• design-brief.md создан в директории итерации
• Активна ветка/worktree для итерации
• make check (и make check-fe для фичей с frontend) проходит на старте

test-cases.md не входное условие: его автономно авторит роль test-author из design-brief по каждому треку (tracks/<id>/test-cases.md), а не подаёт архитектор. Per-track plan.md может отсутствовать — его создаёт фаза PLAN трека; если tracks/<id>/plan.md уже есть, оркестратор использует его без перезаписи. Раскладка документов — § Раскладка документов (context bus).

Платформа

Skill написан с примерами Claude Code (Agent tool, subagent_type, имена моделей Opus / Sonnet / Haiku). В OpenAI Codex Cloud sub-agent delegation идёт через встроенный механизм Codex; имена моделей в таблице тиров маппятся на capability-уровни:

• Opus → highest reasoning (используется для критичных решений: planner, plan-reviewer, reviewer-a/reviewer-b, tester, test-author, test-reviewer, fixer, sofa-contributor, general-purpose ревьюер партиции)
• Sonnet → balanced default (implementer на первом проходе, docs-updater, harvester)
• Haiku → fast / cheap (если нужны лёгкие проверки)

Логика фаз, escalation policy и acceptance gates — идентичны для обеих платформ. Если на текущей платформе нет аналога Agent tool — используй штатный sub-agent / sub-task механизм платформы; контракт по входам/выходам тот же.

Ментальная модель

Сущность	Роль
Оркестратор	Conductor. Не выполняет специализированной работы. Читает state, выбирает следующую фазу, вызывает сабагента, разбирает результат
Сабагенты	Players. Каждый знает только свою роль. Не общаются между собой — обмен только через файлы в worktree
Архитектор	Переключатель ручного режима. Разрешает тупики, апрувит коммит, опционально ревьюит любые артефакты

Принципы:

• Fan-out по непересекающимся трекам. Параллелизм — штатный режим, не исключение. Оркестратор МОЖЕТ запускать 2-3+ сабагентов одновременно в одной ветке/worktree, когда их файловые скоупы не пересекаются. Непересечение гарантирует ## Партиция треков design-brief (её проверяет general-purpose ревьюер) — изоляция идёт через партицию, а не через worktree-на-агента. Параллелятся между собой разные треки: одноимённые фазы (IMPLEMENT T1 ∥ IMPLEMENT T2) и, где партиция это явно разрешает, разные фазы (T1 в TEST_AUTHORING, пока T2 ещё в IMPLEMENT). Внутри одного трека роли строго последовательны — двое не пишут одновременно. Перед фазами, требующими цельного состояния (INTEGRATION_TEST, CODE_REVIEW и далее), — барьер: все треки должны дойти до конца своих per-track фаз. Read-only ревьюеры (reviewer-a/reviewer-b) в CODE_REVIEW параллелятся, кода не трогая. Конфликт, которого партиция не предвидела (два трека тянут один файл, аномалии в worktree), — стоп fan-out и эскалация архитектору. Механика, барьеры и эскалации — § Партиция треков и fan-out. Вырожденный случай (один трек) — конвейер последовательный, параллелизации нет.
• Состояние = файлы в worktree. Сабагенты не получают «контекста от предыдущего сабагента» в памяти; всё, что нужно следующей роли, должно быть зафиксировано в файле — per-track (tracks/<id>/plan.md, summary.md, test-cases.md) и на ярусе итерации (design-brief.md, review-a.md/review-b.md, harvest-proposals.md, sofa-proposals.md). Полная раскладка — § Раскладка документов (context bus).
• Оркестратор не принимает архитектурных решений. При неоднозначности — эскалирует.

Раскладка документов (context bus)

Документы итерации живут в двух ярусах; имя документа — по продукту работы, не по агенту (не «файл на агента»).

Ярус итерации (один экземпляр, параллельных писателей нет — пишется в последовательных фазах):

• design-brief.md — дизайн-процесс (архитектор + агент) → planner и все роли. Несёт секцию ## Партиция треков (идентификаторы треков итерации; заполняет оркестратор после входа архитектора, до PLAN) и секцию ## SOFA consulted (Blueprint, к которым обращались при проработке дизайна по правилу conventions.md § Blueprint-ресёрч; писатель — дизайн-процесс, читатель — sofa-contributor на финализации).
• review-a.md / review-b.md — ревьюеры → implementer, docs-updater (дрейф), harvester. Код-ревью — барьер над цельным diff'ом, поэтому single.
• harvest-proposals.md — harvester → архитектор на гейте.
• sofa-proposals.md — sofa-contributor → архитектор на апруве. Пост-кандидаты и write-back-кандидаты (verify/vote/reply).

Ярус трека (tracks/<id>/, комплект из трёх документов на каждый трек). Идентификаторы треков берутся из секции ## Партиция треков design-brief; в вырожденном случае (один трек) секция ## Партиция треков может отсутствовать — трек именуется T1. Комплект:

• plan.md — planner трека → plan-reviewer/implementer/tester/fixer трека. Секция ## Open Questions → оркестратор/архитектор.
• summary.md — содержательно пишут implementer и fixer → tester/reviewers/docs-updater/sofa-contributor/harvester. Обязательные секции:
  • ## TL;DR — шапка файла, ≤15 строк: что сделано; отступления от plan/design-brief; решения сверх design-brief. Единственная human-facing секция summary — архитектор читает её на гейте PR как вход в ревью (doc/tech/conventions/review.md). Поддерживают актуальной implementer (после каждой фазы) и fixer (после фиксов): секция отражает трек целиком, не последнюю фазу.
  • ## Решения и обоснования — почему так сделано (не код-выводимый статус). Заменяет устный финальный отчёт сабагента оркестратору, который иначе умирает в памяти; несёт непрерывность через границы ролей. Оркестратор требует её заполнения от implementer, fixer и docs-updater (последний фиксирует здесь свои содержательные doc-решения).
  • ## Follow-ups — любой агент → harvester (backlog) и sofa-contributor.
  • ## SOFA-посты (id / применил / результат) — заводится структурно; наполняет fixer в цикле фикса (TIL-зонд 2-го захода: id поста / применил ли / результат), читатель — sofa-contributor на финализации (write-back). Пустая секция — валидный исход (consume не происходил).
• test-cases.md — единый дом всего тестового трека (дизайн автотестов, ручные кейсы + run-log, находки ревью), авторится автономно (test-author) из design-brief. Секции:
  • Дизайн автотестов — test-author: что покрываем автотестом, что осознанно нет и почему.
  • Ручные кейсы + статусы — test-author пишет кейсы; tester и fixer ведут версионированный run-log флипов (r1 ✅ → r2 ❌ → r3 ✅). Fixer сюда — только статус-флип и максимум одна тезисная фраза, без деталей (содержательный контекст фикса — в ## Решения и обоснования summary). Cross-cutting кейсы (Layer 2 Integration / Layer 3 E2E, без префикса трека) test-author формулирует здесь же — в test-cases того трека, из которого они вытекают; на INTEGRATION_TEST tester собирает их по всем tracks/*/test-cases.md и флипает статусы in-place в файле кейса.
  • Находки ревью [severity+owner] — test-reviewer: severity (blocker/major/minor) + владелец фикса ([test] test-author / [prod] fixer / [infra] / [doc]) для фазы GREEN.

Почему общий файл внутри трека безопасен. Роли трека идут строго последовательно — двое не пишут одновременно (implementer → test-author → test-reviewer → GREEN → tester). A6 держится на этой последовательности ролей, не на разделении файлов. Пересечение писателей возможно только между разными треками, но у каждого трека свой tracks/<id>/ — клоббера нет.

Конвейер итерации

Высокоуровневая FSM:

START
  │
  ▼
PARTITION (оркестратор считает `## Партиция треков` design-brief → general-purpose
           ревьюер проверяет непересечение → коррекция; без апрув-гейта архитектора)
  │
  ▼
FAN-OUT треков — партиция задаёт, какие треки и какие фазы идут параллельно (∥):
  ┌── трек T1 ───────────────────────────────────────────────────┐   ┌── трек T2 … ──┐
  │ PLAN → PLAN_REVIEW → IMPLEMENT → TEST_AUTHORING → TEST_REVIEW │ ∥ │  (аналогично) │
  │      → GREEN → TEST(track) → локальный коммит                 │   │               │
  └───────────────────────────────────────────────────────────────┘   └───────────────┘
  (внутри трека роли строго последовательны; параллельность — только между треками)
  │
  ▼
═══ БАРЬЕР: все треки дошли до конца своих per-track фаз ═══
  │
  ▼
INTEGRATION_TEST(final) (smoke/e2e + узкий ручной cross-cutting хвост) → [≤2 fix-цикла] → локальный коммит
  │
  ▼
CODE_REVIEW:
  arch-checker (детерминированно) → reviewer-A ∥ reviewer-B (read-only, параллельно)
  → [фиксы implementer'а + ре-верификация затронутого] → локальный коммит
  │
  ▼
DOC_UPDATE → локальный коммит
  │
  ▼
SOFA (опц., только кандидаты) → локальный коммит
  │
  ▼
HARVEST (хвосты → harvest-proposals.md) → локальный коммит
  │
  ▼
[ARCH] PRE-COMMIT GATE  (апрув завершённости + апрув harvest-landing)
  │
  ▼
COMMIT (🚧→✅ + landing одобренных harvest-кандидатов, без push)
  │
  ▼
END

Тупик в любой фазе → эскалация архитектору.

Партиция треков и fan-out

Единица параллельности — трек: целостный файловый/модульный скоуп, который агенты трека ведут, не пересекаясь с другими треками. Партиция определяет, сколько треков и насколько глубоко можно вести параллельно; глубину задаёт она, а не жёсткий порядок фаз («сначала все тесты, потом весь impl» не зашивается).

Как считается партиция (перед PLAN, автономно).

1. После входа архитектора (design-brief готов), до фазы PLAN, оркестратор сам прикидывает партицию — грубо, на уровне модулей/сервисов (пересечения обычно видны уже по design-brief, между сервисами их часто нет). Фиксирует в секции ## Партиция треков design-brief: какие треки (T1, T2, …), файловый/модульный скоуп каждого, вердикт непересечения, какие фазы каких треков можно вести параллельно.
2. Партицию проверяет general-purpose сабагент-ревьюер (свежий контекст, модель Opus): смотрит design-brief + партицию и даёт фидбэк («здесь параллелить плохо: пересечение по X»). Оркестратор корректирует секцию по фидбэку. Апрув-гейта архитектора нет — шаг полностью автономный.
3. Детальный implementation-план каждого трека по-прежнему пишет per-track planner в tracks/<id>/plan.md; партиция задаёт скоупы, план их детализирует.

Вырожденный случай — один трек: партиция тривиальна, ревью не нужно, конвейер последовательный.

Как исполняется fan-out.

• Оркестратор запускает сабагентов разных треков параллельно в общей ветке/worktree: одноимённые фазы (IMPLEMENT T1 ∥ IMPLEMENT T2) и — где партиция это явно разрешает — разные фазы (T1 уже в TEST_AUTHORING, пока T2 ещё в IMPLEMENT). Изоляция — непересечение файловых скоупов, зафиксированное партицией, без worktree-на-агента.
• Внутри одного трека роли строго последовательны (IMPLEMENT → TEST_AUTHORING → TEST_REVIEW → GREEN → TEST(track)) — двое никогда не пишут одновременно (§ Раскладка документов, A6-guardrails).
• Read-only ревьюеры A/B в CODE_REVIEW параллелятся всегда — кода не трогают, пишут в разные файлы.

Барьер синхронизации. Барьер один — на границе fan-out: все треки должны дойти до конца своих per-track фаз (через TEST(track) и локальный коммит трека), прежде чем конвейер войдёт в фазы, требующие цельного состояния. После барьера всё идёт single-последовательностью — INTEGRATION_TEST (final), CODE_REVIEW (цельный diff), DOC_UPDATE, SOFA, HARVEST, pre-commit gate — параллельных писателей нет.

Эскалации fan-out. Конфликт, которого партиция не предвидела, — стоп fan-out и эскалация архитектору (не разруливать инфраструктурные конфликты самостоятельно, см. CLAUDE.md § Параллельная разработка):

• Два трека тянут один файл (пропущенное пересечение) — партицию надо перекроить.
• planner в своём треке обнаружил выход за заявленный скоуп (нужен файл из чужого трека) — эскалирует оркестратору (не молча), тот перекраивает партицию.
• Наблюдаемые аномалии в worktree (файлы меняются вне правок агента, самопроизвольные перезапуски).

Перекраивать секцию ## Партиция треков design-brief оркестратор может только когда затронутые треки остановлены или ещё не запущены: design-brief — файл яруса итерации, его нельзя править под живыми читателями (сабагентами работающих треков).

Фаза PLAN

Параметр	Значение
Когда	tracks/<id>/plan.md трека отсутствует
Сабагент	prompts/planner.md
Модель	Opus
Вход	tasklist-запись, design-brief (вкл. ## Партиция треков), релевантная архитектурная дока, {track_id}
Выход	tracks/<id>/plan.md трека с планом и секцией Open Questions
Переход	Open Questions пуст → PLAN_REVIEW трека. Непуст → эскалация архитектору

Фаза PLAN_REVIEW (по треку)

План — единственная инструкция implementer'а: расхождение плана с брифом молча становится расхождением кода с брифом, а тесты по плану его закрепят. Свежий ревьюер судит план против design-brief до старта имплементации.

Параметр	Значение
Когда	После PLAN трека (план создан, Open Questions пуст)
Сабагент	prompts/plan-reviewer.md
Модель	Opus
Запуск	Read-only, свежий агент (≠ planner трека) — ни план, ни код не трогает
Вход	{design_brief_path}, {plan_path}, {track_id}
Выход	Отчёт оркестратору: findings (blocker / nit / question) с цитатами «бриф ↔ план» по осям покрытие / отсебятина / потери
Loop bound	Цикл planner ↔ plan-reviewer ≤2 итераций (blocker'ы → перевызов planner'а с {fix_list} → повторное ревью); по исчерпании — эскалация архитектору
Переход	Blocker'ов нет → IMPLEMENT трека. question-находки оркестратор разруливает по базовому принципу автономности или эскалирует

Фаза IMPLEMENT (по треку)

IMPLEMENT трека — цикл по фазам плана (T1.1, T1.2, …): один вызов implementer'а = одна фаза ({phase_id}). Оркестратор идёт по фазам плана трека последовательно, передавая {phase_id} каждым вызовом. При fan-out циклы IMPLEMENT разных треков идут параллельно между собой (T1 ∥ T2), но внутри одного трека фазы строго последовательны.

Параметр	Значение
Когда	Текущий трек ещё не реализован (есть незакрытые фазы плана трека)
Сабагент	prompts/implementer.md
Модель	Sonnet (default), Opus при перевызове после 2 fail подряд
Вход	tracks/<id>/plan.md, tracks/<id>/summary.md, {track_id}, {phase_id}
Выход	Код + дополнения в tracks/<id>/summary.md (секция ## Решения и обоснования обязательна)
Cross-check	make check (и make check-fe где применимо), миграции применяются на чистой БД
Целостность	Имплементер не пишет и не правит тест-файлы своего скоупа (A6 — см. § Целостность тестов в оркестраторе). Тесты пишет независимый автор
Переход	TEST_AUTHORING на этом же треке

Фаза TEST_AUTHORING (по треку)

Независимый автор пишет автотесты скоупа — основная масса проверок (testing.md § Граница авто/ручное). Оракульное свойство держится на независимости автора тестов от автора кода (A6), не на порядке «тест раньше кода».

Параметр	Значение
Когда	После IMPLEMENT трека
Сабагент	prompts/test-author.md
Модель	Opus
Вход	doc/tech/conventions/testing.md, tracks/<id>/plan.md, tracks/<id>/summary.md, {design_brief_path}, {test_cases_path}, {scope_id}
Scope	Автотесты скоупа {scope_id} (директория tests/<scope>/, не пересекается с другими скоупами). Автор ≠ имплементер трека (A6)
Выход	Тест-файлы в tests/{scope_id}/ + секция «Дизайн автотестов» в tracks/<id>/test-cases.md (авторится автономно из design-brief); прогон по написанному зелёный
Cross-check	Прогон только через Makefile (make test-scope / make test-fe); общие утилиты — из packages/testing, не дублировать
Переход	TEST_REVIEW

Фаза TEST_REVIEW (по треку)

Параметр	Значение
Когда	После TEST_AUTHORING трека
Сабагент	prompts/test-reviewer.md
Модель	Opus
Запуск	Read-only — ни тестов, ни кода не трогает (как ревьюеры A/B)
Вход	doc/tech/conventions/testing.md, diff тест-файлов скоупа, tracks/<id>/plan.md, tracks/<id>/summary.md, {scope_id}, {test_cases_path}
Выход	Находки в секцию «Находки ревью [severity+owner]» tracks/<id>/test-cases.md: severity (blocker/major/minor) + владелец фикса ([test] / [infra] / [prod] / [doc])
Целостность	Ревьюер ≠ автор тестов ≠ автор кода (A6)
Переход	Есть открытые находки → GREEN; чисто → TEST(track) (ручной хвост)

Фаза GREEN (по треку)

Доводим набор скоупа до честного зелёного по реестру находок. Разделение по владельцу фикса — ядро A6: тест-правки делает автор тестов, прод-баги — отдельный fixer (не автор теста), чтобы баг не «чинился» эрозией ассерта.

Параметр	Значение
Когда	После TEST_REVIEW, если в реестре есть открытые находки
Сабагенты	[test]-правки → prompts/test-author.md; [prod]-баги → prompts/fixer.md (fixer ≠ автор теста); [infra] (packages/testing) → отдельный фикс-агент
Модель	Opus
Вход	{test_cases_path} (секция «Находки ревью»), {fix_list}, {scope_id}; fixer дополнительно {track_id}, {plan_path}, tracks/<id>/summary.md, {attempt} (номер попытки фикса — оркестратор передаёт при каждом вызове fixer'а)
Loop bound	≤2 цикла на находку. Прод-рефактор / новый или меняющийся публичный контракт / спорный контракт → эскалация (whitelist)
Ре-верификация	После фиксов — make check / make check-fe + перепрогон затронутых тестов (make test-scope)
Переход	Все blocker/major закрыты или эскалированы → TEST(track) (ручной хвост)

Фаза TEST (по треку) — узкий ручной хвост

Параметр	Значение
Когда	После GREEN трека (автотесты зелёные и отревьюены)
Сабагент	prompts/tester.md
Модель	Opus
Вход	tracks/<id>/test-cases.md, tracks/<id>/plan.md, tracks/<id>/summary.md, {track_id} (значение трека: T1, T2, ...)
Scope	Узкий ручной хвост (testing.md § Граница авто/ручное): многошаговые сценарии, exploratory, приёмка UX — то, что не покрыто автотестом. Кейсы с префиксом {track_id}. Cross-cutting кейсы — в INTEGRATION_TEST
Выход	Обновлённые статусы (run-log флипов) в «Ручные кейсы + статусы» tracks/<id>/test-cases.md + краткий отчёт оркестратору. В summary tester не пишет
Loop bound	На один test-case ≤2 fix-цикла: прод-баг чинит fixer (не автор теста, A6), не сам tester. Не сдвинулся — эскалация
Переход	Все кейсы трека прошли → локальный коммит трека → трек ждёт барьера. Когда все треки партиции дошли до конца своих per-track фаз — барьер снят, вход в INTEGRATION_TEST

Фаза INTEGRATION_TEST

Параметр	Значение
Когда	После барьера: все треки прошли TEST(track) и закоммичены
Сабагент	prompts/tester.md
Модель	Opus
Вход	tracks/*/test-cases.md, tracks/*/plan.md, tracks/*/summary.md, {track_id}=final
Scope	Cross-cutting проверки: автоматический smoke/e2e (create_app(), Playwright — авторятся в TEST_AUTHORING) проходят машинным гейтом; здесь tester прогоняет ручной cross-cutting хвост — кейсы без префикса трека. Кейсы с пометкой 👤 (UI / браузер) tester помечает как требующие ручной проверки и эскалирует архитектору
Выход	Обновлённые статусы cross-cutting кейсов + отчёт
Loop bound	На один test-case ≤2 fix-цикла: прод-баг чинит fixer (не автор теста, A6). Не сдвинулся — эскалация
Переход	Все cross-cutting кейсы прошли (или эскалированы как 👤) → локальный коммит → CODE_REVIEW

Фаза CODE_REVIEW

Три уровня по убыванию детерминизма: машинный arch-checker → два LLM-ревьюера по когнитивным режимам. Машина разгружает ревьюеров от того, что выразимо правилом.

Под-шаг 1 — arch-checker (детерминированно). Оркестратор прогоняет make check + make check-fe (туда сведены import-linter, AST-ассерты, eslint-boundaries). Падение — детерминированное нарушение архитектурного инварианта: implementer фиксит до запуска ревьюеров (тот же loop bound, что в IMPLEMENT: 2 fail Sonnet → Opus → эскалация). arch-checker-report — не отдельный файл, а краткая сводка оркестратора ревьюерам: «make check/make check-fe зелёные; детерминированно покрытые инварианты (слои, FSD-границы, middleware-order, зеркала problem.py — см. arch-checker.md) не перепроверять». Разгрузка ревьюеров от дублирования машины, не формальный артефакт.

Под-шаг 2 — два LLM-ревьюера (параллельно, read-only).

Параметр	Значение
Когда	Все треки реализованы, тесты прошли, arch-checker зелёный
Сабагенты	prompts/reviewer-a.md (качество кода) и prompts/reviewer-b.md (соответствие контракту)
Модель	Opus (оба)
Запуск	Параллельно — оба read-only, пишут в разные файлы (review-a.md / review-b.md), кода не трогают (read-only fan-out, см. § Принципы). Барьер: оркестратор дожидается обоих файлов перед фазой фиксов
Вход	diff от base, tracks/*/plan.md, tracks/*/summary.md, arch-checker-report (см. под-шаг 1); reviewer-B дополнительно — ядро conventions.md + затронутые conventions/<domain>.md + затронутые doc/
Выход	review-a.md и review-b.md: severity (blocker / nit / pre-existing) + ось намерения (issue / suggestion / question)
Переход	Implementer фиксит по обоим отчётам. Конфликт A↔B (режим A за читаемость, режим B за конвенцию) implementer разруливает в пользу зафиксированной нормы; любой A↔B-конфликт, которого implementer касался, получает targeted re-glance того ревьюера, чьё замечание он отклонил — иначе non-blocker-конфликт закрывается без проверки; неразрешимый — эскалация (whitelist №4). После фиксов — ре-верификация затронутого (см. ниже). Blocker без прецедента в conventions → эскалация (whitelist №4)