diff --git a/agents/.agents/skills/coordinator-loop/README.md b/agents/.agents/skills/coordinator-loop/README.md new file mode 100644 index 0000000..6382988 --- /dev/null +++ b/agents/.agents/skills/coordinator-loop/README.md @@ -0,0 +1,90 @@ +# coordinator-loop + +Координаторский цикл: проводит готовые issues через subagent-worker по TDD, держит +границы задач, фильтрует находки и сам делает коммиты. + +## Зачем + +Когда подряд идёт несколько связанных кодовых срезов, писать их «одним потоком» — +значит терять границы задач и контроль над тем, что попало в коммит. Навык +разделяет роли: один subagent-worker делает **одну** issue по TDD и не коммитит, а +координатор проверяет, классифицирует находки и фиксирует результат. Навык узкий и +работает только по явному вызову (`/coordinator-loop`): он не проектирует, он +исполняет. + +## Где в потоке + +coordinator-loop — исполнительное звено в середине цепочки, а не вся цепочка: + +```text +проектная документация (/brainstorm-with-docs | /grill-with-docs) + ↓ +узкие проверяемые issues (/to-issues) + ↓ +coordinator-loop каждый issue: worker по /tdd → саморевью → ревью → коммит + ↓ +приёмка ревью другим агентом (обычно Claude) + ручная проверка +``` + +- **До скилла — проектирование.** Сначала выверенная верхнеуровневая документация + (`/brainstorm-with-docs` или `/grill-with-docs`): без неё issues не на чем + основывать. Затем `/to-issues` режет её на узкие задачи. Именно здесь + закладывается проверяемость результата (см. «Что получается»). +- **Скилл — исполнение.** Берёт **готовые** issues по одной и проводит каждую через + цикл worker → саморевью → классификация → ревью на риске → коммит. +- **После скилла — приёмка.** Результат уходит на ревью другим агентом (обычно + Claude — это и есть взгляд другой родословной) и на ручную проверку. + +## Что делает и чего не делает + +Делает: ведёт по одному issue за раз, держит границы, фильтрует находки, коммитит. +Подробный цикл и роли — в [SKILL.md](SKILL.md). + +Не делает: + +- не проектирует и не пишет документацию — это upstream; +- не нарезает issues — это `/to-issues`; +- не отвечает за проверяемость результата — она закладывается при проектировании; +- не делает финальную приёмку — это ревью другим агентом плюс человек; +- не готовит набор issues «пачкой» автоматически — пока не цель. + +## Что получается + +Результат прогона по одной issue — «пакет для проверки»: + +- **отдельный коммит на каждую issue** с узким, в границах задачи, diff; +- **финальный отчёт worker-а**: какие файлы, какие тесты прогнаны, какие acceptance + criteria закрыты, риски, `git status`; +- **классификация находок** (чинили / риск / ложная тревога / вне скоупа). + +Один issue = один проверяемый коммит плюс отчёт — так пост-цикловое ревью и ручная +проверка остаются посильными. + +**Про проверяемость.** Прошлый прогон показал: если «готово» у issue — это «прочитай +diff», проверить всю цепочку руками не выходит. Лекарство — на уровне +проектирования: формулировать issue так, чтобы «готово» было **наблюдаемым** (запись +в Kafka-топик, строки в конкретной таблице, панель дашборда, вывод команды). Это +ответственность `/to-issues` и брейншторма, **не** этого скилла. Если issue пришла +без наблюдаемого критерия, координатор отметит это как **риск** («проверять придётся +чтением кода») и вернёт сигнал на уровень выше, но сам проверку не выдумывает. + +## Как вызвать + +Только по явному запросу — навык узкий и не срабатывает сам: + +```text +/coordinator-loop +``` + +## Статус и что дальше + +Экспериментальный — прямое продолжение эксперимента с координатором субагентов, +будет дорабатываться. Открытые вопросы (когда нужен отдельный ревьюер, обязательные +промежуточные отчёты, бюджет кругов ревью) собраны в разделе «Открытые вопросы» +файла [references/rationale.md](references/rationale.md). + +## Что читать рядом + +- [SKILL.md](SKILL.md) — как координатор исполняет цикл (инструкция для агента). +- [references/rationale.md](references/rationale.md) — почему цикл устроен так: + эмпирика эксперимента, находка про ревьюера другой родословной, открытые вопросы.