Aidd Orchestrator

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-.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//test-cases.md), а не подаёт архитектор. Per-track plan.md может отсутствовать — его создаёт фаза PLAN трека; если tracks//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 в TESTAUTHORING, пока T2 ещё в IMPLEMENT). Внутри одного трека роли строго последовательны — двое не пишут одновременно. Перед фазами, требующими цельного состояния (INTEGRATIONTEST, CODEREVIEW и далее), — барьер: все треки должны дойти до конца своих per-track фаз. Read-only ревьюеры (reviewer-a/reviewer-b) в CODEREVIEW параллелятся, кода не трогая. Конфликт, которого партиция не предвидела (два трека тянут один файл, аномалии в worktree), — стоп fan-out и эскалация архитектору. Механика, барьеры и эскалации — § Партиция треков и fan-out. Вырожденный случай (один трек) — конвейер последовательный, параллелизации нет.
• Состояние = файлы в worktree. Сабагенты не получают «контекста от предыдущего сабагента» в памяти; всё, что нужно следующей роли, должно быть зафиксировано в файле — per-track (tracks//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//, комплект из трёх документов на каждый трек). Идентификаторы треков берутся из секции ## Партиция треков 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// — клоббера нет.

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

Высокоуровневая 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//plan.md; партиция задаёт скоупы, план их детализирует.

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

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

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

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

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

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

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

Фаза PLAN

| Параметр | Значение | |----------|----------| | Когда | tracks//plan.md трека отсутствует | | Сабагент | prompts/planner.md | | Модель | Opus | | Вход | tasklist-запись, design-brief (вкл. ## Партиция треков), релевантная архитектурная дока, {track_id} | | Выход | tracks//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//plan.md, tracks//summary.md, {track_id}, `{

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Bbar0n234
• Source: Bbar0n234/learnflow-ai
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.