agentleFS
Bbar0n234Bbar0n234/learnflow-ai/.claude/skills/aidd-orchestrator/SKILL.md

aidd-orchestrator

Skill35 starsChanged 3 months agoApache-2.0View on GitHub

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

  • Reads credentials

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read-only ревьюеры A/B в CODE_REVIEW параллелятся всегда — кода не трогают, пишут в разные файлы.

    line 158

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-checkmake 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
ScopeCross-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)

Ре-верификация после фиксов. Правка по ревью — изменение кода; она аннулирует прошлый зелёный статус затронутого (тривиальность правки гарантий не даёт). После фиксов: arch-checker (make check/make check-fe) — перепрогон всегда (цена ≈ ноль); затронутые тест-кейсы — перепрогон только их области (полный прогон не нужен). Опциональный повторный проход ревьюеров — на усмотрение оркестратора по severity (после первого прохода — только blocker'ы).

Фаза DOC_UPDATE

ПараметрЗначение
КогдаCode review закрыт
Сабагентprompts/docs-updater.md
МодельSonnet
Входtracks/*/plan.md, tracks/*/summary.md, список изменённых файлов, review-b.md (секция «Незамеченный дрейф документации» — её адресат именно docs-updater), doc/workflow.md шаг 4, skill aidd-methodology
ВыходАктуализированные/новые документы в doc/, ADR при необходимости, обновлённый doc/index.md
ПереходSOFA

Фаза SOFA (опциональная)

ПараметрЗначение
КогдаПосле DOC_UPDATE
Сабагентprompts/sofa-contributor.md
МодельOpus
Входtracks/*/summary.md (вкл. ## SOFA-посты), design-brief.md (вкл. ## SOFA consulted), ADR (doc/tech/adr/), tracks/*/plan.md, diff итерации, skill sofa-contributor
Выходsofa-proposals.md в директории итерации — ранжированные пост-кандидаты и write-back-кандидаты (verify/vote/reply из ## SOFA-посты + ## SOFA consulted) с обоснованием (или «кандидатов нет»)
ГраницаТолько генерация кандидатов. Никаких внешних вызовов на запись — ни постинг, ни голоса/верификации/реплаи (write-back). Публикация и отправка write-back — author-driven вне конвейера, под апрувом архитектора
ПереходHARVEST

Фаза всегда отрабатывает, но может закончиться выводом «переносимых кандидатов нет» — это валидный результат, не блокер (в т.ч. когда секции ## SOFA-посты / ## SOFA consulted пусты — consume не происходил, write-back нечего замыкать). Локальный коммит включает sofa-proposals.md.

Consume-точки, откуда write-back берёт материал, лежат вне этой фазы: Blueprint — на дизайне (правило conventions.md, пишется в ## SOFA consulted design-brief), TIL — у fixer в цикле фикса (2-й заход, пишется в ## SOFA-посты summary трека). planner в SOFA не ходит — осознанное решение против избыточности; consume — только дизайн и цикл фикса.

Фаза HARVEST

ПараметрЗначение
КогдаПосле SOFA, перед pre-commit gate
Сабагентprompts/harvester.md
МодельSonnet
Входtracks/*/summary.md (секция ## Follow-ups каждого трека), harvest-proposals.md (anytime-кандидаты, если есть), ADR (doc/tech/adr/), review-a.md/review-b.md, diff, doc/backlog.md
Выходharvest-proposals.md: отобранные по рубрике кандидаты в backlog / в конвенции / known-trivial + отсеянный шум; каждый backlog-кандидат прошёл проверку «не закрыто ли уже» (grep + git log)
ГраницаТолько предложения. Harvester не пишет в backlog.md/conventions.md — landing после апрува архитектора на гейте
ПереходPre-commit gate

Фаза всегда отрабатывает; «кандидатов нет» — валидный исход. Локальный коммит включает harvest-proposals.md.

Anytime-путь. Заметив по ходу итерации достойного кандидата (повторяющаяся ошибка, всплывшее правило, отложенный долг), сабагент фиксирует его строкой в секции ## Follow-ups своего tracks/<id>/summary.md — чтобы не потерять до фазы HARVEST. Напрямую в harvest-proposals.md (файл яруса итерации) по ходу итерации дописывает только оркестратор: у него нет своего трека, а при fan-out два параллельных трека не должны писать в один файл яруса итерации. Harvester на финализации читает ## Follow-ups всех треков и anytime-записи оркестратора, консолидирует их, не теряя и не дублируя.

Pre-commit gate (ARCH)

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

  • Финальный git diff от base ветки
  • Финальные summary.md треков (tracks/*/summary.md)
  • Список затронутых документов в doc/
  • harvest-proposals.md — кандидаты в backlog / конвенции на апрув (какие landить)
  • Резюме: что сделано по плану, что было эскалировано и как разрешилось, что осталось вне scope

Архитектор апрувит завершённость и отмечает, какие harvest-кандидаты landить. Оркестратор: вносит одобренные кандидаты в doc/backlog.md / doc/tech/conventions.md (или делегирует docs-updater'у), затем делает финальный коммит. Не пушит.

Апрув на этом gate — и есть «явный апрув завершённости» из conventions.md § Git → «Lifecycle итерации». Поэтому финальный коммит включает перевод статуса итерации 🚧→✅ Done в tasklist + landing одобренных harvest-кандидатов. Без апрува статус остаётся 🚧.

Тестирование: единый источник истины

Всё содержательное про тесты — что и чем тестируем, как раскладываем и пишем, что считаем зелёным — живёт в doc/tech/conventions/testing.md (доменная специфика — conventions/{db,api,agent,frontend}.md). Оркестратор и его промпты эту конвенцию не дублируют и не пересказывают — они на неё ссылаются. Промпт роли говорит «делай по testing.md § X», а норму не копирует: копия гниёт и создаёт второе место для синхронизации. Чек-листы автора тестов и ревьюера — там же (testing.md § Чек-лист автора тестов / § Чек-лист ревьюера); test-author и test-reviewer проходят их построчно.

Целостность тестов (A6-guardrails)

Оракульное свойство теста — объективный pass/fail, на который можно замкнуть автономную итерацию, — даёт не порядок (тест раньше кода), а независимость теста от реализации. Иначе тесты тавтологичны (валидируют реализованное, а не требуемое контрактом) и зелёное при автономном прогоне перестаёт что-либо значить. Отсюда инварианты, которые оркестратор держит на каждой итерации с тестами:

  1. Автор тестов независим от автора кода. Тесты скоупа пишет не тот, кто писал его прод-код (отдельный сабагент test-author). Желательно — из свежего контекста, чтобы не унаследовать допущения реализации.
  2. Имплементер не трогает тест-файлы своего скоупа — не правит и не удаляет ассерты под себя. Дифф на тронутые тест-файлы — предмет ревью (против «удалил/переписал падающий тест, чтобы стало зелёно»).
  3. Фиксер прод-багов ≠ автор теста (fixer). Прод-баг, вскрытый тестом, чинится в проде, не эрозией ассерта; разделение владельца фикса не даёт «починить» тест вместо кода. Фиксером может быть автор прод-кода — он не автор теста.
  4. Adversarial-ревью тестов свежим агентом (test-reviewer): дифф тестов против контракта и чек-листа — реализовано ли требование, есть ли краевые случаи, не тронуто ли лишнее, нет ли false-green/тавтологии. Ревьюер независим от автора тестов и автора кода.

Test-first не обязателен. Допустимо: код → потом тесты → оракул-loop; оракул сохраняется, если тесты пишет не тот, кто писал код. От порядка отказываемся свободно — критична независимость автора, а не «ни строки без падающего теста». Регламент целостности и границы авто/ручное — testing.md § Целостность тестов / § Граница авто/ручное.

Порядок тест-работ (convention-first, инфра-заморозка)

Когда итерация заводит или меняет тестовые конвенции/инфраструктуру, оркестратор соблюдает порядок:

  • Convention-first. Сначала формализуются тест-конвенции и чек-листы (testing.md), и только по ним пишутся тесты. Тесты против неустоявшейся нормы переписываются впустую.
  • Инфра-заморозка перед раздачей скоупов. Общий тест-фундамент (packages/testing, conftest-иерархия, фейки, шов модели, тестовая БД) строится и замораживается одним проходом до того, как авторы тестов начнут работу по скоупам. После заморозки скоупы инфру не трогают; если правка фундамента реально нужна — эскалация, а не локальный форк у одного скоупа.
  • Партиция по непересекающимся скоупам. Скоуп = тест-директория tests/<scope>/, целостная подсистема (сервис не пилится между агентами). Непересекающиеся директории — условие бесконфликтной работы по скоупам.
  • Green отдельными фиксерами. Прод-баги, вскрытые тестами, доводятся до зелёного фиксерами (§ Целостность тестов, инвариант 3), не авторами тестов.

Журналирование (test-cases.md трека)

Состояние конвейера — файлы в worktree (§ Ментальная модель). Тестовая работа трека журналируется в едином tracks/<id>/test-cases.md — версионируемый дрибл контекста, чтобы инсайты/шаги/ошибки не умирали в памяти сабагента:

  • test-author пишет секцию «Дизайн автотестов» (что покрыто автотестом, что осознанно нет и почему) и авторит ручные кейсы — автономно из design-brief.
  • test-reviewer дописывает секцию «Находки ревью [severity+owner]»: severity + владелец фикса ([test] / [infra] / [prod] / [doc]), не перезаписывая чужое.
  • tester и fixer ведут run-log флипов в «Ручные кейсы + статусы» (r1 ✅ → r2 ❌ → r3 ✅). Fixer читает «Находки ревью», чинит по [prod]-находкам, помечает находку закрытой/эскалированной; в test-cases от него — только статус-флип и максимум одна тезисная фраза. Содержательный контекст фикса (первопричина, как починен) идёт в ## Решения и обоснования summary трека.
  • Каждый трек ведёт свой tracks/<id>/test-cases.md — записи разных треков не конфликтуют; внутри трека роли последовательны, поэтому клоббера нет.

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

РольМодельПеревызов
plannerOpus—
plan-reviewerOpus—
implementerSonnet; Opus при перевызовеПосле 2 fail подряд (не прошёл make check или сабагент сам сообщил, что не справился) → перевызов с Opus
testerOpus—
test-authorOpus—
test-reviewerOpus—
fixerOpus—
reviewer-aOpus—
reviewer-bOpus—
docs-updaterSonnet—
sofa-contributorOpus—
harvesterSonnet—
general-purpose ревьюер партицииOpus—

Ревьюер партиции — на Opus: проверка непересечения треков correctness-critical (пропущенное пересечение ломает fan-out коллизией в общей ветке), а прогон one-shot и дёшев.

Тиры зафиксированы здесь. Не дублируй в шаблонах промптов — модель передаётся параметром 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. Один из ревьюеров (A/B) выставил blocker без прецедента в conventions.md, либо конфликт замечаний A↔B неразрешим implementer'ом.

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

Open Questions от planner'а

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

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

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

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

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

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

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

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

Loop bounds

ЦиклБюджетЧто после исчерпания
PLAN_REVIEW: planner ↔ plan-reviewer2 итерации на трекЭскалация архитектору
GREEN: находка реестра ↔ fixer/test-author2 fix-цикла на находкуЭскалация (прод-рефактор / спорный контракт — whitelist)
Tester ↔ fixer на один ручной test-case (TEST или INTEGRATION_TEST)2 fix-циклаЭскалация архитектору
Implementer fail подряд по фазе2 (Sonnet) → перевызов OpusЭскалация после fail Opus
Ревьюеры (A/B) ↔ implementerНа усмотрение оркестратора, ориентир — пока blocker'ы не закрыты; после фиксов — ре-верификация затронутогоЭскалация при blocker без прецедента или неразрешимом конфликте A↔B

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

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

  • После каждого трека (автотесты скоупа написаны и отревьюены, набор зелёный, ручной хвост пройден). При параллельных треках коммить только файлы скоупа трека (git add <файлы скоупа>, не -a): соседние треки могут быть незавершёнными
  • После закрытия CODE_REVIEW (фиксы по обоим отчётам + ре-верификация)
  • После DOC_UPDATE
  • После SOFA (если создан/обновлён sofa-proposals.md)
  • После HARVEST (если создан/обновлён harvest-proposals.md)

Сообщения коммитов следуют 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 итерации
{track_id}Идентификатор трека (T1, T2, ...) из ## Партиция треков design-brief, или final для прогона cross-cutting кейсов в INTEGRATION_TEST
{phase_id}Идентификатор фазы плана трека (T1.1, T1.2, …) — фазы внутри tracks/<track_id>/plan.md. Передаётся implementer'у при вызове: один вызов = одна фаза
{plan_path}tracks/<track_id>/plan.md — план трека
{summary_path}tracks/<track_id>/summary.md — summary трека (секции ## Решения и обоснования, ## Follow-ups, ## SOFA-посты)
{test_cases_path}tracks/<track_id>/test-cases.md — единый дом тестового трека (дизайн автотестов, ручные кейсы + run-log флипов, находки ревью). При {track_id} = final не резолвится — tester читает все tracks/*/test-cases.md
{scope_id}Тестовый скоуп = непересекающаяся директория tests/<scope>/ (целостная подсистема трека) для test-author / test-reviewer / fixer
{fix_list}Структурированный список фиксов от tester'а, test-reviewer'а (находки из test-cases.md) или ревьюеров (A/B)
{attempt}Номер попытки фикса по данному списку находок (1..N). Оркестратор передаёт fixer'у при каждом вызове в fix-цикле (GREEN, а также прод-баги в TEST/INTEGRATION_TEST): fixer — свежий агент и сам не знает, что он «второй», а TIL-зонд привязан к {attempt} = 2

Если шаблон требует переменную, для которой нет значения, — оркестратор останавливается и эскалирует. Не подставлять заглушки. Исключение — документированный случай {test_cases_path} при {track_id} = final: он не резолвится намеренно, tester в INTEGRATION_TEST читает все tracks/*/test-cases.md напрямую (см. строку {test_cases_path} в таблице выше).

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

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

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

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

  • Не пишет design-brief.md (архитектор) — кроме секции ## Партиция треков, которую оркестратор заполняет сам на фазе PARTITION
  • Не пишет test-cases.md сам — его автономно авторит test-author из design-brief по каждому треку (tracks/<id>/test-cases.md); архитектор его на вход не подаёт
  • Не редактирует tasklist кроме: статусов фазы, references на артефакты итерации и перевода статуса итерации 🚧→✅ в финальном коммите после апрува на pre-commit gate (по conventions.md § Git → «Lifecycle итерации»)
  • Не пушит в remote
  • Не мерджит PR
  • Не запускает сабагентов параллельно вне партиции — параллелит только непересекающиеся треки по ## Партиция треков (+ read-only ревьюеры A/B); при непредвиденном конфликте — стоп fan-out и эскалация (§ Партиция треков и fan-out)
  • Не запускает оркестратор оркестратора (рекурсии нет)
  • Не работает без всех предусловий из чек-листа выше

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

Запуск

Триггеры:

  • Естественный язык: «запусти оркестратор на 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/)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.