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

name, description

name

description

coordinator-loop

Координаторский цикл для цепочки зависимых задач (issues из /to-issues): на каждую задачу запускается worker-субагент с одной конкретной целью, затем саморевью, классификация находок, независимый ревьюер на рискованных местах и коммит силами координатора. Узкоспециализированный навык — НЕ включай автоматически. Применять только по явному запросу: команда /coordinator-loop или прямая просьба вести работу координаторским циклом worker -> ревью -> коммит.

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

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

Ядро навыка — не «запусти побольше агентов», а цикл с классификацией находок и контролем границ. Главная формула:

worker реализует -> worker сам себя ревьюит -> координатор фильтрует ->
worker чинит выбранное -> независимый ревьюер проверяет риск -> координатор фильтрует ->
при большом исправлении повторить ревью -> координатор коммитит

С чего начать

1. Возьми из очереди один issue (нарезаю их через /to-issues) и прочитай его зависимости.
2. Проверь, что рабочее дерево чистое.
3. Сформулируй контракт worker-у: цель = issue, границы, методика.
4. Запусти одного worker-а. Дальше — по циклу ниже.

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

Подходит для последовательных инженерных срезов с тестами, документами и явными acceptance criteria, когда соседние задачи трогают близкий код и их нельзя безопасно параллелить.

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

Роли

• Координатор — ты. Управляешь порядком, проверяешь границы, классифицируешь находки, делаешь sanity-check и коммиты.
• Worker — субагент-исполнитель с одной конкретной целью (один issue). Работает в общем дереве, меняет файлы, гоняет тесты, но не коммитит.
• Саморевью worker-а — отдельная фаза: тот же worker временно становится проверяющим и сначала только выдаёт находки, не правя их.
• Независимый ревьюер — отдельный субагент со свежим контекстом. Он не редактирует файлы, но проверяет находки делом: читает diff, issue, спеки и тесты, сам прогоняет тесты и линтеры, сверяется с документацией. Ограничивай ему право записи, а не право проверять: ревьюер, которому оставили только чтение, скатывается в догадки.
• Находка — гипотеза о проблеме, а не автоматическое требование правки. Решение принимаешь ты.

Все агенты работают с одним рабочим деревом. Поэтому каждый цикл начинай и заканчивай явной проверкой git status --short и отделяй рабочие изменения задачи от процессных заметок и чужих правок.

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

1. Прочитай issue и его зависимости. На них строятся цель, границы и порядок. Если предыдущие задачи цепочки не закрыты — не начинай.
2. Чистое дерево. Проверь git status --short до запуска worker-а. Если есть чужие правки — сразу остановись и спроси пользователя, что с ними делать. Если есть только твои процессные правки — после проверки diff отдели их отдельным docs-коммитом.
3. Запусти одного worker-а на этот issue. Дай задание как контракт (см. ниже).
4. Дождись отчёта. Если работа долго молчит (особенно статистика и долгие тесты) — запроси промежуточный статус, не дожидаясь конца вслепую.
5. Саморевью без правок. Попроси того же worker-а отревьюить свою работу и выдать находки, ничего пока не исправляя.
6. Классифицируй находки (см. ниже).
7. Верни worker-у только одобренное для исправления.
8. Свой sanity-check. Не реимплемент, а проверка связей: дефолты, compose и конфиги, документы, acceptance criteria, git status, тесты.
9. На рискованном месте — независимый ревьюер в свежем субагенте (см. «Когда звать ревьюера»).
10. Классифицируй находки ревьюера.
11. Большое исправление — повторный круг ревью. Если правка изменила дизайн или формат данных, ревьюй её результат заново.
12. Коммит делаешь ты. Это последняя точка контроля состава diff.
13. Закрой субагентов. Следующая задача стартует в новом worker-е.

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

Worker — это субагент с одной конкретной целью, который гоняет её как самопроверяющуюся петлю (план → делает → тест → ревью, пока цель не достигнута; в Codex это встроенная команда /goal, по сути «петля Ральфа»). Цель берётся из одного issue (issues удобно нарезать через /to-issues).

В задании worker-у должны быть:

• одна конкретная цель из issue и критерий «готово» (acceptance criteria);
• границы задачи (что трогать нельзя);
• методика /tdd (короткие срезы «тест → код»);
• запрет на коммит;
• запрет на откат чужих изменений;
• формат финального отчёта: файлы, тесты, проверки, выполненные acceptance criteria, риски и git status --short.

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

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

Ревьюер и саморевью — не источник истины. Каждую находку проверь и отнеси к одной из категорий:

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

Без этой фильтрации ревьюер легко превращается в источник расползания задачи.

Когда звать независимого ревьюера

Не после каждой мелкой правки — это дорого и раздувает задачу. Зови на рискованных точках:

• state и сериализация;
• интеграция сервиса;
• изменения формата данных;
• статистические модели;
• документация (честность README и операционных документов);
• после большого исправления — повторный круг.

Ревьюер проверяет не только падения, но и силу доказательства: достаточно ли тест доказывает нужное поведение, а не просто «что-то прошло».

Свежий контекст вместо другой модели

Дисциплинированный цикл (worker + саморевью + ревьюер той же линии) хорошо ловит точечные дефекты. Но до внешнего взгляда доживают два семейства, которые одна линия систематически не видит:

• межмодульные инварианты — свойство тянется через несколько модулей или путей, и ни один тест не сводит их вместе;
• форма распределения — среднее и пороги на цели, но форма уехала.

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

Облегчённый и полный режим

Навык параметризуемый — не запускай полную схему всегда.

• Облегчённый режим (простой, низкорисковый issue): worker + саморевью + твой sanity-check. Без отдельного ревьюера.
• Полный режим (риск из списка выше или контрольная точка): добавляешь независимого ревьюера и, при большом исправлении, повторный круг.

Если что-то сознательно не проверял (например, использовал мок вместо реального стека) — явно это зафиксируй, не выдавай за проверенное.

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

• Дерево чистое перед стартом; чужие правки обнаружены сразу и согласованы с пользователем, процессные правки отделены.
• Worker получил один issue и контракт (цель, границы, TDD, запрет коммита и отката чужого, формат отчёта).
• Саморевью сделано без правок; находки классифицированы.
• Свой sanity-check связей пройден.
• На риске запущен независимый ревьюер со свежим контекстом и нацеленным заданием; большое исправление прошло повторный круг.
• Незакрытое ревью другой родословной зафиксировано как риск.
• Коммит сделан координатором, diff узкий и в границах задачи.
• Субагенты закрыты; git status чист на выходе.

Подробнее

Эмпирика, на которой стоят эти правила (что именно ловил и пропускал цикл), вынесена в references/rationale.md.

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

• /to-issues, /tdd — из набора инженерных скиллов Matt Pocock: https://github.com/mattpocock/skills.
• /goal — встроенная команда Codex CLI.
• /coordinator-loop — этот навык; вырос из внутреннего эксперимента с координатором субагентов.