aidd-orchestrator

name	aidd-orchestrator
description	Автономный оркестратор итерации в AIDD workflow. Используй когда: запусти оркестратор, прогони итерацию, оркестрируй feat-XXX, реализуй итерацию автономно, дирижируй сабагентами, AIDD pipeline, конвейер итерации.
user-invocable	true

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, cloud merge-policy, logging). Если не загружен — не приступать к фазам.
2. doc/workflow.md — методология AIDD, жизненный цикл итерации.

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

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

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

• Запись итерации существует в doc/tasks/tasklist-<scope>.md со статусом 📋 или 🚧
• design-brief.md создан в директории итерации
• test-cases.md создан в директории итерации (входное условие, оркестратор test-cases не пишет)
• Активна ветка/worktree для итерации
• make check (и make check-fe для фичей с frontend) проходит на старте

plan.md может отсутствовать — его создаёт первая фаза конвейера. Если plan.md уже есть — оркестратор использует его без перезаписи.

Платформа

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

• Opus → highest reasoning (используется для критичных решений: planner, code-reviewer, tester)
• Sonnet → balanced default (implementer на первом проходе, docs-updater)
• Haiku → fast / cheap (если нужны лёгкие проверки)

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

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

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

Принципы:

• Один сабагент за раз. Параллелизм не используется — общая ветка, риск конфликтов. Если кажется, что фазу можно распараллелить — это сигнал, что план неудачный, лучше переплантировать.
• Состояние = файлы в worktree. Сабагенты не получают «контекста от предыдущего сабагента» в памяти; всё, что нужно следующей роли, должно быть зафиксировано в файле (plan.md, summary.md, test-cases.md, отчёт code-reviewer'а).
• Оркестратор не принимает архитектурных решений. При неоднозначности — эскалирует.

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

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

START
  │
  ▼
PLAN (если plan.md нет)
  │
  ▼
TRACK loop (по фазам плана):
  IMPLEMENT → TEST(track) → [≤2 fix-цикла] → локальный коммит
  │
  ▼ (после последнего трека)
INTEGRATION_TEST(final) → [≤2 fix-цикла] → локальный коммит
  │
  ▼
CODE_REVIEW → [фиксы] → локальный коммит
  │
  ▼
DOC_UPDATE → локальный коммит
  │
  ▼
[ARCH] PRE-COMMIT GATE
  │
  ▼
COMMIT (без push)
  │
  ▼
END

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

Фаза PLAN

Параметр	Значение
Когда	plan.md отсутствует
Сабагент	prompts/planner.md
Модель	Opus
Вход	tasklist-запись, design-brief, test-cases, релевантная архитектурная дока
Выход	plan.md с пофазным планом, секцией Open Questions
Переход	Open Questions пуст → IMPLEMENT первой фазы. Непуст → эскалация архитектору

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

Параметр	Значение
Когда	Текущий трек ещё не реализован
Сабагент	prompts/implementer.md
Модель	Sonnet (default), Opus при перевызове после 2 fail подряд
Вход	plan.md, summary.md, {track_id}
Выход	Код + дополнения в summary.md
Cross-check	make check (и make check-fe где применимо), миграции применяются на чистой БД
Переход	TEST на этом же треке

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

Параметр	Значение
Когда	После IMPLEMENT или после IMPLEMENT-фиксов
Сабагент	prompts/tester.md
Модель	Opus
Вход	test-cases.md, plan.md, summary.md, {track_id} (значение трека: T1, T2, ...)
Scope	Tester прогоняет только кейсы с префиксом {track_id} (например, {T1.1}) + Layer 0 automated gate. Cross-cutting кейсы Layer 2/3 пропускаются — закрываются в INTEGRATION_TEST
Выход	Обновлённые статусы в test-cases.md + краткий отчёт оркестратору
Loop bound	На один test-case ≤2 fix-цикла с implementer'ом. Не сдвинулся — эскалация
Переход	Все кейсы трека прошли → локальный коммит → следующий трек или INTEGRATION_TEST (если был последний трек)

Фаза INTEGRATION_TEST

Параметр	Значение
Когда	После TEST последнего трека плана
Сабагент	prompts/tester.md
Модель	Opus
Вход	test-cases.md, plan.md, summary.md, {track_id}=final
Scope	Layer 2 (Integration) + Layer 3 (E2E) — кейсы без префикса трека. Кейсы с пометкой 👤 (UI / браузер) tester помечает как требующие ручной проверки и эскалирует архитектору
Выход	Обновлённые статусы cross-cutting кейсов + отчёт
Loop bound	На один test-case ≤2 fix-цикла с implementer'ом. Не сдвинулся — эскалация
Переход	Все cross-cutting кейсы прошли (или эскалированы как 👤) → локальный коммит → CODE_REVIEW

Фаза CODE_REVIEW

Параметр	Значение
Когда	Все треки реализованы и тесты прошли
Сабагент	prompts/code-reviewer.md
Модель	Opus
Вход	diff от base ветки, plan.md, summary.md, conventions.md
Выход	Отчёт с замечаниями по severity (blocker / nit / nice-to-have)
Переход	Blocker без прецедента в conventions → эскалация. Иначе implementer фиксит → опционально повторный code-review (на усмотрение оркестратора по severity) → DOC_UPDATE

Фаза DOC_UPDATE

Параметр	Значение
Когда	Code review закрыт
Сабагент	prompts/docs-updater.md
Модель	Sonnet
Вход	plan.md, summary.md, список изменённых файлов, doc/workflow.md шаг 4, skill aidd-methodology
Выход	Актуализированные/новые документы в doc/, ADR при необходимости, обновлённый doc/index.md
Переход	Pre-commit gate

Pre-commit gate (ARCH)

Перед коммитом оркестратор подаёт архитектору:

• Финальный git diff от base ветки
• Финальный summary.md
• Список затронутых документов в doc/
• Резюме: что сделано по плану, что было эскалировано и как разрешилось, что осталось вне scope

Архитектор апрувит → оркестратор делает коммит. Не пушит.

Модельные тиры

Роль	Модель	Перевызов
planner	Opus	—
implementer	Sonnet; Opus при перевызове	После 2 fail подряд (не прошёл make check или сабагент сам сообщил, что не справился) → перевызов с Opus
tester	Opus	—
code-reviewer	Opus	—
docs-updater	Sonnet	—

Тиры зафиксированы здесь. Не дублируй в шаблонах промптов — модель передаётся параметром Agent tool, шаблон ничего не знает о модели.

Параметр model в Agent tool передавать явно по таблице. Дефолт harness'а — нестабильная величина (зависит от того, какая модель активна в сессии), полагаться на него не стоит: тир в таблице — единственный надёжный источник.

Принципы автономности и эскалации

Базовый принцип

Оркестратор и сабагенты решают самостоятельно, если из совокупности doc/workflow.md + doc/tech/conventions.md + design-brief.md + релевантных ADR существует ровно одна интерпретация без противоречий.

Если интерпретаций несколько и доминирующей по trade-offs нет — эскалация.

Whitelist обязательной эскалации

Эти триггеры эскалируются всегда, даже при «уверенности» агента:

1. План требует решения, не покрытого ни одним ADR / design-brief'ом.
2. Появляется новый публичный контракт (REST endpoint, event vocabulary, схема БД, SSE event) или меняется существующий.
3. Тестовый кейс не воспроизводится после 2 fix-циклов с implementer'ом.
4. Code-reviewer выставил blocker-замечание без прецедента в conventions.md.

Прочие неоднозначности — оркестратор разруливает сам по базовому принципу.

Open Questions от planner'а

plan.md обязан заканчиваться секцией Open Questions. Оркестратор после фазы PLAN читает её:

• Пустая → переход к IMPLEMENT
• Непустая → эскалация архитектору с этим списком, конвейер на паузе

Формат эскалации

При эскалации оркестратор подаёт архитектору структурированный отчёт. Минимум:

• Фаза: где встал
• Что пытался сделать: конкретное действие
• Что мешает: ссылки на файлы/строки/документы
• Какие варианты рассмотрены: список с trade-offs
• Что нужно от архитектора: выбор из вариантов / новая информация / переформулировка scope

Не «у меня вопрос», не «не получается». Структурированный отчёт сокращает время разрешения тупика.

Перевызов implementer'а на Opus

Если implementer-Sonnet вернулся с fail дважды подряд по той же подзадаче (не прошёл make check, не справился с фиксом, не реализовал указанное в фазе) — оркестратор перевызывает ту же роль с моделью Opus. Если Opus тоже не справился — эскалация. Не «пробовать ещё раз с Sonnet», не «придумать workaround» — стоп.

Loop bounds

Цикл	Бюджет	Что после исчерпания
Tester ↔ implementer на один test-case (TEST или INTEGRATION_TEST)	2 fix-цикла	Эскалация архитектору
Implementer fail подряд по фазе	2 (Sonnet) → перевызов Opus	Эскалация после fail Opus
Code-reviewer ↔ implementer	На усмотрение оркестратора, ориентир — пока blocker'ы не закрыты	Эскалация при blocker без прецедента

Локальные коммиты между фазами

Коммиты внутри ветки feat-XXX делаются:

• После каждого трека (когда все test-cases трека прошли)
• После закрытия CODE_REVIEW (фиксы blocker/nit замечаний)
• После DOC_UPDATE

Сообщения коммитов следуют doc/tech/conventions.md (Conventional Commits).

Не коммитить:

• Локальные файлы с черновиками промптов / заметок (my_prompts.txt, notes.md в корне и т.п.) — если оказались в worktree, не добавлять в коммит
• Файлы с секретами (.env, credentials)

Pull в remote оркестратор не делает. Push после финального коммита — отдельная команда архитектора.

Использование промпт-шаблонов

Шаблоны лежат в prompts/<role>.md рядом со SKILL.md. Каждый шаблон содержит:

1. Роль агента (1-2 строки)
2. Входные артефакты с переменными для подстановки
3. Задачу
4. Принципы поведения (что не делать, когда эскалировать)
5. Формат вывода

Алгоритм вызова

1. Прочитать prompts/<role>.md
2. Подставить переменные в текст шаблона
3. Вызвать Agent tool: subagent_type=general-purpose, model=<тир из таблицы> (передавать явно — см. примечание к таблице тиров), prompt=<подставленный шаблон>
4. Дождаться завершения, прочитать результат, обновить state (файлы артефактов уже на диске — сабагент пишет туда сам)
5. Перейти к следующей фазе по FSM или эскалировать

Стандартные переменные подстановки

Переменная	Значение
{tasklist_path}	Путь к doc/tasks/tasklist-<scope>.md
{design_brief_path}	Путь к design-brief итерации
{plan_path}	Путь к plan.md итерации
{summary_path}	Путь к summary.md итерации
{test_cases_path}	Путь к test-cases.md итерации
{track_id}	Идентификатор фазы плана (T1, T2, ...) или final для прогона cross-cutting кейсов в INTEGRATION_TEST
{fix_list}	Структурированный список фиксов от tester'а или code-reviewer'а

Если шаблон требует переменную, для которой нет значения, — оркестратор останавливается и эскалирует. Не подставлять заглушки.

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

Каждый вызов — новый сабагент с пустой памятью. Всё, что нужно сабагенту, должно быть в его prompt'е и/или в файлах worktree. Не рассчитывать на «он помнит, что было в предыдущем вызове».

Ограничения скилла

Оркестратор НЕ делает следующее:

• Не пишет design-brief.md (архитектор)
• Не пишет test-cases.md (архитектор)
• Не редактирует tasklist кроме статусов фазы и references на артефакты итерации
• Не пушит в remote
• Не мерджит PR
• Не запускает сабагентов параллельно
• Не запускает оркестратор оркестратора (рекурсии нет)
• Не работает без всех предусловий из чек-листа выше

При попытке сделать что-то из списка — стоп и эскалация архитектору.

Запуск

Триггеры:

• Естественный язык: «запусти оркестратор на feat-XXX», «прогони итерацию feat-XXX»
• Slash: /aidd-orchestrator feat-XXX

Аргумент — идентификатор итерации (feat-005, fix-001 и т.п.). По нему оркестратор находит запись в tasklist'е и директорию итерации.

Ссылки

• doc/workflow.md — методология AIDD, жизненный цикл итерации, делегирование агентам
• doc/tech/conventions.md — соглашения проекта (Git flow, naming, код)
• skill aidd-methodology — принципы документации и работы с артефактами
• skill prompt-engineering — принципы написания промптов (применимо при правках шаблонов в prompts/)