---
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`. Оркестратор предполагает, что эти соглашения соблюдены.

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

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

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

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

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

| Сущность | Роль |
|----------|------|
| Оркестратор | 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/`)