dotfiles/agents/.agents/skills/coordinator-loop/SKILL.md

name, disable-model-invocation, description

name	disable-model-invocation	description
coordinator-loop	true	Координаторский цикл по цепочке готовых issue: на каждый — worker-субагент по TDD с независимым ревью, коммит делает координатор. Контекст координатора держится чистым — в него входит только индекс находок, не diff. Узкий навык, только по явному вызову /coordinator-loop.

Координационный цикл субагентов

Ты — координатор. Реализацию не пишешь, код ради верификации не читаешь (точная граница чтения — в «Ролях»). Ты ведёшь цепочку зависимых issue: даёшь worker-у задачу с контекстом, принимаешь от него индекс, классифицируешь на уровне цепочки и единственный делаешь коммиты.

Ведущее правило — работай по индексу, а не по полному тексту. Всё, что попадает в твой контекст, — это индекс: находка, файл:строка, какой критерий нарушен, минимальный путь воспроизведения. Полного diff, вывода тестов и нарратива ревью в твоём контексте быть не должно — их читают субагенты у себя, а тебе возвращают индекс. Твоих собственных команд это тоже касается: шумный вывод гони в файл-лог, в контекст бери код возврата и итоговые строки (механика — шаг 7). Верификацию находок делает ревьюер, не ты. (Исключение — состав diff на коммит-гейте: git diff --stat/--name-only, какие файлы и в границах ли; это не полный текст, см. шаг 7.) Проверяй себя каждый цикл: в мой контекст попал полный текст вместо индекса? Если да — это баг процесса. Так контекст не пухнет, не компактится и не начинает косячить — это главная болезнь, которую навык лечит.

Когда применять

Последовательные инженерные срезы с тестами и acceptance criteria, где соседние задачи трогают близкий код и их нельзя безопасно параллелить. Вход цикла — качественно подготовленные issue: цель, критерии готовности и границы уже сформулированы (обычно это выход /to-issues после проработки замысла, например через /brainstorm-with-docs). Мутный issue в цикл не брать: цикл не проясняет замысел, а превращается в дорогую машину ревью-кругов — сначала прояснение и проработка замысла, потом цикл. Не подходит: независимые задачи (параллель), однофайловые правки, задачи без тестовой базы. Если цепочка не подходит — скажи об этом пользователю, а не тяни цикл силой.

Роли

• Координатор — ты. Порядок issue, богатый контракт, запуск ревьюеров, политика кругов ревью, chain-level классификация по индексу, коммит-гейт, финальный handoff. Код ради верификации не читаешь — это ревьюер; на коммит-гейте смотришь лишь состав diff (не текст, см. шаг 7). Процессные и навигационные артефакты — файлы issue и PRD, журнал, handoff, документация процесса — твоя зона: их читаешь и правишь сам, запрет касается только кода ради верификации.
• Worker — субагент с одной целью (один issue). Гоняет /goal (петля план→код→тест), меняет файлы, не коммитит и не откатывает чужое. Триажит находки ревью: чинит или аргументированно отклоняет. Возвращает индекс + статус.
• Ревьюер — свежий субагент-наблюдатель, которого запускаешь ты (см. «Контракт ревьюеру»): репозиторий и среду не меняет, но инструменты у него полные — ограничение промптом, не урезанием субагента. Читает код сам, докладу worker-а не верит, возвращает индекс находок. claude-team-review как механизм допустим только там, где его может запустить сам worker (владелец правок): лид team-review чинит код сам, а второй писатель в дереве недопустим — координатору team-review запускать нельзя.

Факт среды Codex (проверено 2026-07-04 диагностом с agent_type=worker): worker не может запускать субагентов — spawn_agent недоступен, tool_search не находит ни spawn, ни claude-team-review. Поэтому ревьюеров запускает координатор и пересылает worker-у их индексы дословно, без своих интерпретаций. Не перепроверяй этот факт на каждой цепочке — жечь токены; перепроверь только при сигнале обратного (например, tool_search вдруг нашёл spawn).

Всех субагентов — worker-а, ревьюеров, диагностов — запускай свежими сессиями, без форка своей истории. Контракт самодостаточен, правила и «зачем» лежат в репозитории и issue — форк не нужен. А вреден он дважды: тащит твой контекст в субагента (расход без пользы) и убивает «свежий взгляд» — ревьюер, унаследовавший твою историю, уже не независим. Не трать циклы на попытки передать субагенту полный контекст — это против дизайна, а не ограничение, которое надо обойти.

Свежая сессия — правило запуска, не запрет продолжения: уже запущенного субагента между кругами продолжай (send_input), не пересоздавай. Worker-а — всегда: его контекст по issue — актив. Ревьюера на rerun после точечных правок — тем же, узким вопросом: «закрывают ли правки твои находки, не внесено ли нового рядом» — полный обход заново не нужен. Свежий ревьюер обязателен там, где нужен незаинтересованный взгляд: узкий гейт по спору, эскалация уровня, правки перекроили реализацию широко, индекс прошлого ревьюера слаб или сомнителен. Серия полных обходов свежими xhigh-сессиями на каждый rerun — сжигание бюджета, а не независимость (эмпирика 2026-07-04: пять свежих кругов финального ревью).

Цикл на одну задачу

1. Чистое дерево. git status --short до старта. Чужие правки — стоп, спроси пользователя. Свои процессные — отдели docs-коммитом.
2. Прочитай issue и зависимости. Предыдущие в цепочке не закрыты — не начинай.
3. Назначь режим ревью по порогу риска (см. «Режимы ревью») и запиши в журнал; если срез может задеть порог по ходу — задай условие эскалации (например, «worker тронул state-схему → перевести в гейт»). Затем контракт worker-у (см. ниже) и запусти одного worker-а — уровень мышления явно по references/effort-levels.md, в журнал вместе с режимом.
4. Дождись индекса. Долго молчит — запроси промежуточный статус, не жди вслепую. Пришло push-уведомление — сразу обрабатывай, не крути опрос по кругу.
5. Ревью-гейт (worker вернул DONE/DONE_WITH_CONCERNS; BLOCKED и NEEDS_CONTEXT разбирай до ревью — гонять ревьюеров по незавершённой работе бессмысленно). По назначенному режиму запусти ревьюеров; запуск и вердикт каждого фиксируй в журнале в момент события. Индекс находок перешли worker-у дословно, его триаж прими индексом же. Rerun после правок по гейт-находкам назначаешь ты, автоматически — это не concern worker-а; узкий rerun — продолжением того же ревьюера, свежий — по триггерам (см. «Роли»). Круг — одна итерация «прогон(ы) ревью → триаж worker-а»; пара «по задаче + по коду» на гейте — один круг. Гейт закрыт, когда все назначенные прогоны вернули APPROVED. Политика кругов (тождество находок между кругами судит worker в триаже, не ты — по индексам оно не определяется):
   • worker пометил «спор» (ревьюер снова поднял вопрос, уже аргументированно отклонённый через контракт и тест) → не общий rerun, а узкий гейт по спорному вопросу на усиленном уровне мышления;
   • спор пережил и узкий усиленный гейт → стоп, решение человека;
   • третий круг на issue — предупреди пользователя, не дожидаясь потолка: расход растёт, причина (что именно не сходится), продолжаешь или нужен стоп;
   • независимо от споров больше четырёх кругов ревью на issue → стоп, вынеси человеку вопрос «дробить issue или принимать риск».
6. Классифицируй по индексу — только chain-level (см. «Классификация»).
7. Коммит-гейт. Прогони полный тест-сет сам: код возврата, который ты видел своими глазами, — это и есть твоя проверка; прогон через субагента превращает гейт обратно в чужой пересказ. Шумные команды гоняй через файл-лог (<команда> > /tmp/<лог> 2>&1), в контекст возьми только сводку: код возврата и итоговые строки (tail, имена упавших — grep FAILED). На «тихие» флаги вроде pytest -q не полагайся: цель сборки может зашивать подробный вывод (эмпирика 2026-07-05: make generator-test с зашитым pytest -v высыпал в контекст координатора полный список из 181 теста). Если сводки мало и вывод нужно интерпретировать — лог сам не читай, спавни разборщика логов экономного уровня (references/effort-levels.md), он вернёт индекс. Так же проверь состав diff (git diff --stat/--name-only: какие файлы, в границах ли — не полный текст) и коммить. Упали тесты — верни их worker-у по именам, трейсбеки в свой контекст не тащи. Сверь по журналу, что назначенный режим ревью выполнен: каждый запуск и вердикт записаны в момент события; нет записи — ревью не проведено. В коммит issue стейджи только файлы worker-а; файл issue и coordinator-journal.md — процессные, не файлы worker-а: после коммита переведи в файле issue Status: done, и оба уходят отдельным docs-коммитом (шаг 1 следующего цикла, на последнем issue — перед выходом). Это последняя точка контроля состава изменений.
8. Закрой субагентов. Следующий issue стартует в новом worker-е.

Журнал прогона

С первого шага цепочки веди журнал: append-only файл .scratch/<feature>/coordinator-journal.md, короткие записи в конец по ходу событий, не задним числом. Каждую запись начинай с времени HH:MM (дата — в заголовке дня; время бери вызовом date, сама модель его не знает) — так по журналу восстанавливается длительность этапов и границы issue. Точки записи: старт issue (worker запущен, его уровень мышления, назначенный режим ревью), принят индекс worker-а, запуск каждого ревью (механизм, кто запускал, уровень мышления — фактическое значение хоста вроде high/xhigh, не название яруса: «рабочий уровень» в журнале не проверяем, а medium вместо high — видимое расхождение) и его вердикт, коммит-гейт (сводка тестов, хэш коммита), chain-level решения (риск / вне скоупа). Происхождение ревью пишешь ты сам — в момент запуска и в момент вердикта. Мельче этих точек (каждая команда, каждый прочитанный файл) не пиши — метки времени не должны превратить журнал в спам. Журнал — тот же индекс, вынесенный в файл: полных текстов в нём нет. В рабочие коммиты issue его не подмешивай (механика — на коммит-гейте, шаг 7).

Что это даёт: обрыв координатора не теряет состояние — по журналу видно, на каком этапе цепочка и что уже сделано; происхождение ревью фиксируется в момент события — переписать его задним числом незаметно не выйдет; финальный handoff собирается по журналу, а кросс-проход и человек сверяют записи с фактами (коммитами, файлами). Честная граница: журнал пишет сам координатор — это след для внешней проверки и барьер, а не гарантия; гарантия — кросс-линия и человек.

Контракт задания worker-у

• одна цель из issue и критерий «готово» (acceptance criteria);
• зачем: ссылки на PRD/спеку/смежное. Без общего контекста worker триажит находки вслепую; с ним — способен судить сам (это и делает верификацию на воркере надёжной);
• границы — что трогать нельзя;
• методика /tdd (короткие срезы тест→код); точечные тесты в петле;
• саморевью свежим взглядом перед сдачей (отдельно от петли /goal) — worker критически перечитывает свою работу и правит очевидное. Базовый минимум даже без независимого ревью: ошибаются все;
• триаж находок ревью: независимое ревью организует координатор и присылает индекс находок; worker каждую находку чинит или аргументированно отклоняет — через контракт и тест, не голословно. Вопрос, который ревьюер поднял снова после аргументированного отклонения, worker помечает в своём индексе флагом «спор» с отсылкой к прежнему обоснованию;
• формат отчёта — индекс: находка/изменение, файл:строка, минимальный repro, какой критерий; запрет вставлять diff и полный вывод тестов;
• статус-контракт DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT — worker сам стопорится на архитектурной неясности, а не додумывает молча. BLOCKED — только про саму работу; недоступная в среде worker-а стендовая проверка (docker, сеть, стенд) — это DONE_WITH_CONCERNS с фактом («docker отсутствует: <вывод>») и готовой командой, которую координатор прогонит сам (не прошла и у координатора — он фиксирует в журнале, где и как проверка прошла фактически);
• запрет коммита и запрет отката чужого.

Цель worker-а — одна (один issue = одна петля). Не запускай /goal на всю цепочку сразу: от координатора нужна остановка на контрольных точках, а не «закрыть всё любой ценой».

Контракт ревьюеру

Симметричен контракту worker-а, короче:

• наблюдатель с полными инструментами: код читает сам, докладу worker-а не верит; может запускать тесты, воспроизводить находки, смотреть документацию и сеть — верификация требует инструментов. Ограничение — промптом, не урезанием субагента: не менять репозиторий и среду (правки файлов, git-операции, установка пакетов — нельзя), так в дереве нет второго писателя;
• зачем: те же ссылки на issue/PRD/спеку, что у worker-а, плюс фокус проверки (по задаче или по коду); на гейте — явная цель по двум семействам, слепым для одной линии: межмодульные инварианты и форма распределений;
• формат отчёта — индекс: находка, файл:строка, какой критерий нарушен, минимальный repro; вердикт одной строкой (APPROVED / CHANGES_REQUESTED); запрет вставлять diff, полный вывод тестов и нарратив рассуждений;
• модель и уровень мышления задаёт координатор при запуске (см. «Режимы ревью»).

Готовый шаблон промпта — references/reviewer-prompt.md (адаптация из claude-team-review); скилл самодостаточен, внешних файлов не требует.

Режимы ревью — рычаг стоимости

Две проверки разными субагентами — по задаче и по коду — ловят непересекающиеся множества находок, но это расход токенов (бюджет; в твой контекст при этом идут только индексы находок). Плати по риску, не на каждой мелочи:

• тривиальный issue — независимое ревью не зови; хватает петли /goal плюс саморевью из контракта (в среде без вложенных субагентов внешняя проверка готовности внутри /goal тоже недоступна — саморевью остаётся единственной проверкой, это осознанная цена режима);
• обычный (дефолт) — один прогон независимого ревью по коду; соответствие issue/спеке держит петля /goal;
• рискованный / гейт — два прогона разными субагентами: по задаче (сделал ли то, что в issue/спеке) + по коду (тонкие баги, межмодульное).

Порог риска: state, версионирование и сериализация; формат данных; интеграция с внешним сервисом — особенно разрушающие пути (синхронизация, удаление); защитные проверки, на которые полагаются другие части системы, — всё, где ошибка означает «проверка молча пропускает» (fail-open); статистические модели; честность документации; межмодульные инварианты. Ниже порога: документация и учебные материалы, простая обвязка сборки, локальные правки без новых инвариантов. (Калибровка по прогонам 2026-07-04/05: issue с синхронизацией внешнего сервиса и fail-open проверками, пущенный обычным режимом, собрал больше всех кругов — его класс надо было опознать на шаге 3.)

Две ручки стоимости, не одна. Модель по роли — какая модель на какой роли: проверка по задаче тянет дешёвую, финальное chain-ревью требует сильную. Уровень мышления — отдельная ось, глубина рассуждений той же модели. Три относительных уровня, без привязки к именам: экономный (worker на обычном issue — реализацию с тестовой сеткой страхуют рубежи ниже по течению; task-lens ревью, диагностика, разбор логов), рабочий (любое code review — пропуск ревьюера не ловит никто, глубина важнее именно здесь; worker на гейтовом issue), усиленный (эскалация споров по политике кругов, межмодульные инварианты и форма распределений, финальное chain-ревью). Соответствие ролей конкретным моделям и уровням хоста — датированная таблица references/effort-levels.md; в логике скилла имён нет, вышла новая модель — правится таблица, не правила. Дефолт — рабочий уровень; вверх — только по триггеру (шаг 5), не «на всякий случай». Хост без управляемых уровней: эскалация вырождается в свежего субагента — слабее, но не пусто.

Классификация находок

Per-finding триаж («реально / ложно / чинить») делает worker — у него контекст кода и «зачем» из контракта; не переписывай его. Ты решаешь только на уровне цепочки, читая индекс:

• записать риском — важно помнить, текущий коммит не блокирует (реестр рисков цепочки);
• вне скоупа — пригодится позже, отдать в следующий issue.

Финал цепочки

Пока п.1–3 не выполнены, цепочка не завершена — и каждый твой отчёт пользователю обязан явно это называть: статус («финальный гейт, не done») и остаток по пунктам. Промежуточный статус, звучащий как финальный отчёт, — дефект коммуникации: пользователь решит, что работа закончена, и уйдёт. Словарь статусов для отчётов: «финальный гейт, не done: осталось …» → «done по coordinator-loop: handoff есть, дерево чистое, субагенты закрыты»; открытые внешние риски (кросс-линия, ручная приёмка) перечисляй и в done-отчёте. APPROVED финального ревью — ещё не завершение цепочки.

1. Приведи документы до ревью. Обнови PRD/трекер: сделанное — в сделанное, остаток актуален, статусы issue переведены (шаг 7). Иначе финальное ревью предсказуемо найдёт этот дрейф вместо настоящего.

2. Ревью на соответствие замыслу (рекомендуется для любой нетривиальной цепочки). Один прогон субагента-ревьюера сильной моделью на усиленном уровне (обе ручки вверх — см. «Режимы ревью»): читает всю реализацию против исходной спеки/PRD и проверяет, не разъехалась ли поэтапная реализация с замыслом. Возвращает индекс. Один прогон добавляет к общей стоимости немного, а ловит дрейф, который per-issue срезы не видят — ни одно ревью отдельной задачи не сверяло целое с целым замыслом. Rerun'ы финального ревью — по общему правилу продолжения: точечные правки проверяет тот же ревьюер узким вопросом, свежая xhigh-сессия на каждый круг не нужна. Кто чинит находки финального ревью — по классу файла. Процессные файлы (.scratch/<feature>/…: остаток и статус PRD фичи, чекбоксы и статусы issue, журнал) — чини сам: это твоя зона, п.1 и существует, чтобы таких находок не было вовсе. Файлы проекта (код, docs/, уроки, дашборды) — fixer-субагент с коротким worker-контрактом (цель — закрыть перечисленные находки, границы, запрет коммита; уровень — экономный для док-дрейфа, рабочий для кода): правя проектный файл сам, ты читаешь его полный текст и становишься вторым писателем — ломаешь оба своих инварианта, даже если правка на две строки. Кодовая находка финала — фактически мини-issue: после fixer-а — rerun ревью по общему правилу продолжения. Триаж находок финального ревью — у fixer-а, тем же механизмом, что у worker-а: богатый контракт («зачем», спека) даёт право судить; отклонение — аргументированное, через контракт и тест; спор — по политике кругов (шаг 5). Финальный ревьюер ошибается так же, как обычный, — «поправь всё перечисленное» без права возразить превращает его находки в приказы. Это Codex (одна линия): берёт охват (целое против замысла), но не кросс-линию — глубокие сквозные слепые пятна линии остаются на п.3.

3. Handoff — условие выхода, а не пожелание. Для нетривиальной цепочки цикл не считается завершённым без записки, собранной по журналу прогона, не по памяти. Место и формат — по конвенции репозитория для handoff (AGENTS.md, ADR), если она есть; иначе .scratch/<feature>/…. Записка готовит кросс-линейное ревью: проход модели другой родословной по написанному. Внутри Кодекса ревьюер — тоже Codex (одна линия), а свежий контекст не снимает слепоту линии к сквозным дефектам. Сам проход остаётся вне скилла — координатор его не выполняет; но для нетривиальной цепочки он рекомендован по умолчанию, не опция: на практике кросс-проход находил серьёзные расхождения после APPROVED ревьюера той же линии (эмпирика — references/rationale.md). В записке:

   • индекс построенного по issue (файл:строка ключевых стыков);
   • происхождение ревью по каждому issue (режим, механизм, кто запускал, уровень, вердикт) — из журнала;
   • отклонения от процесса — фактами: что пробовали, что сделано вместо; причины-предположения («недоступно», «не поддерживается») без проверки фактом — запрещены;
   • открытый риск: межмодульные инварианты и форма распределения другой родословной не покрыты → нацеленный бриф для кросс-прохода.

   Даже если проход не запустят — дыра остаётся видимым задокументированным риском, а не тихим слепым пятном. Запустят — ревьюер получит нацеленный бриф, а не холодное перечитывание.

Чек-лист координатора

• Дерево чистое перед стартом; чужие правки согласованы, процессные отделены.
• Worker получил один issue + зачем (PRD/спека), границы, /tdd, индекс-формат, триаж находок ревью (с флагом «спор»), статус-контракт, запрет коммита и отката; саморевью свежим взглядом сделан.
• В мой контекст вошёл только индекс — ни diff, ни логов, ни нарратива ревью.
• Ревью-гейт: индексы находок пересланы worker-у дословно; rerun назначал я; политика кругов соблюдена (спор → узкий усиленный гейт; больше четырёх кругов → человек).
• Происхождение каждого ревью (механизм, кто запускал, уровень, вердикт) записано мной в журнал в момент события; нет записи — ревью не засчитано.
• Журнал ведётся append-only по ходу, каждая запись с меткой HH:MM; точки записи не пропущены.
• Chain-level классификация сделана по индексу (риск / вне скоупа).
• Коммит сделан координатором, diff узкий и в границах; полный тест-сет на гейте прогнал я сам, шумные команды — через файл-лог: в контекст только сводка (pass/fail + упавшие), не вывод.
• Статусы закрытых issue переведены в done и ушли docs-коммитом вместе с журналом.
• PRD/трекер приведены до финального ревью; ревью на соответствие замыслу — сильная модель на усиленном уровне; дрейф от спеки проверен.
• Финальный handoff собран по журналу и по конвенции репозитория: происхождение ревью по issue, отклонения фактами, бриф кросс-линейного ревью. Для нетривиальной цепочки без него из цикла не выходить.
• Субагенты закрыты; git status чист на выходе.

Подробнее

• references/rationale.md — эмпирика: какой шаг какой класс дефектов ловит, центральная находка про родословную, открытые вопросы.
• handoffs/ — экономия контекста (два пожара: контекст vs лимит), наблюдаемость и непроверенные кандидаты-фиксы (файловый канал, демоушн закрытых issue, точечные тесты); live-log наблюдаемости вырос в журнал прогона (2026-07-03); топология ревью под Codex, политика кругов и уровни мышления — по боевому прогону (2026-07-04).

Источники упомянутых скиллов

• /brainstorm-with-docs, /to-issues, /tdd, /claude-team-review — инженерные скиллы (набор Matt Pocock и внутренние).
• /goal — встроенная петля Codex (план→код→тест; её внешняя проверка готовности в среде без вложенных субагентов недоступна).