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

name, disable-model-invocation, description

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

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

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

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

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

Последовательные инженерные срезы с тестами и acceptance criteria, где соседние задачи трогают близкий код и их нельзя безопасно параллелить. Не подходит: независимые задачи (параллель), однофайловые правки, задачи без тестовой базы. Если цепочка не подходит — скажи об этом пользователю, а не тяни цикл силой.

Роли

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

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

1. Чистое дерево. git status --short до старта. Чужие правки — стоп, спроси пользователя. Свои процессные — отдели docs-коммитом.
2. Прочитай issue и зависимости. Предыдущие в цепочке не закрыты — не начинай.
3. Контракт worker-у (см. ниже) и запусти одного worker-а.
4. Дождись индекса. Долго молчит — запроси промежуточный статус, не жди вслепую. Пришло push-уведомление — сразу обрабатывай, не крути опрос по кругу.
5. Классифицируй по индексу — только chain-level (см. «Классификация»).
6. Коммит-гейт. Прогони полный тест-сет, но в контекст возьми только сводку: код возврата и имена упавших тестов (pytest -q/хвост вывода), не полный вывод. Так же проверь состав diff (git diff --stat/--name-only: какие файлы, в границах ли — не полный текст) и коммить. Упали тесты — верни их worker-у по именам, трейсбеки в свой контекст не тащи. Сверь происхождение ревью в индексе с назначенным режимом: нет происхождения или механизм подменён — верни worker-у. В коммит issue стейджи только файлы worker-а; coordinator-journal.md в грязном дереве — ожидаемый процессный файл, не нарушение границ: он уходит отдельным docs-коммитом (шаг 1 следующего цикла, на последнем issue — перед выходом). Это последняя точка контроля состава изменений.
7. Закрой субагентов. Следующий issue стартует в новом worker-е.

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

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

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

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

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

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

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

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

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

Порог риска: state и сериализация, формат данных, интеграция сервиса, статистические модели, честность документации, межмодульные инварианты.

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

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

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

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

1. Ревью на соответствие замыслу (рекомендуется для любой нетривиальной цепочки). В самом конце — один прогон субагента-ревьюера сильной моделью (не дешёвой): читает всю реализацию против исходной спеки/PRD и проверяет, не разъехалась ли поэтапная реализация с замыслом. Возвращает индекс. Один прогон добавляет к общей стоимости немного, а ловит дрейф, который per-issue срезы не видят — ни одно ревью отдельной задачи не сверяло целое с целым замыслом. Это Codex (одна линия): берёт охват (целое против замысла), но не кросс-линию — глубокие сквозные слепые пятна линии остаются на п.2.

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

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

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

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

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

Подробнее

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

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

• /to-issues, /tdd, /claude-team-review — инженерные скиллы (набор Matt Pocock и внутренние).
• /goal — встроенная петля Codex (план→код→тест→проверка готовности внешним ревьюером).