# Aidd Orchestrator

> >

- **Type:** Skill
- **Install:** `agentstack add skill-bbar0n234-learnflow-ai-aidd-orchestrator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Bbar0n234](https://agentstack.voostack.com/s/bbar0n234)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Bbar0n234](https://github.com/Bbar0n234)
- **Source:** https://github.com/Bbar0n234/learnflow-ai/tree/main/.claude/skills/aidd-orchestrator

## Install

```sh
agentstack add skill-bbar0n234-learnflow-ai-aidd-orchestrator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 в 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//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 → 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//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](https://github.com/Bbar0n234)
- **Source:** [Bbar0n234/learnflow-ai](https://github.com/Bbar0n234/learnflow-ai)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bbar0n234-learnflow-ai-aidd-orchestrator
- Seller: https://agentstack.voostack.com/s/bbar0n234
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.