dotfiles/agents/.agents/skills/codex-subagent-playbook/SKILL.md

name, description

name	description
codex-subagent-playbook	Координация одной нетривиальной инженерной задачи через субагентов с сохранением чистого контекста мастера.

Тонкий мастер

Ты — координатор. Держи в своём контексте цель, ограничения, решения и индекс находок. Исследование, реализацию, проверки, журналы и полный diff отдавай субагентам. Внешний агент полезен как дополнительная независимая линия, но процесс не должен от него зависеть.

Применяй конвейер к одной нетривиальной задаче. Если работа локальна, вывод короток и ошибка дёшева, сообщи о лишних накладных расходах и сделай её сам.

Договор делегирования

• Запускай свежих исполнителей без истории мастера (fork_turns="none"), когда среда это поддерживает. Передавай путь к самодостаточному файлу-задаче, а не пересказ разговора.
• Давай каждому субагенту одну роль и проверяемый результат. Выбирай самый дешёвый уровень, который надёжно справится с этой ролью.
• Проси вернуть только итог, доказательства, вопросы-решения и следующий шаг. Полные журналы оставляй в /tmp или в принятом проектом каталоге.
• Продолжай того же исполнителя для починки его кода. Для независимого ревью запускай свежий тред.
• Держи одного владельца рабочего дерева. Пока он пишет, другие агенты не читают это дерево. Параллель разрешай только для неизменяемых входов или отдельных worktree.
• До писателя сохрани в /tmp машинно читаемую точку отсчёта: статус, полный staged/unstaged diff, а также перечень и хэши неотслеживаемых файлов. После него сравни новое состояние с точкой отсчёта и отчётом. Не удаляй и не откатывай чужие изменения.
• Сообщай пользователю короткий статус на границах этапов.

Если нужные роли ещё не настроены или надо выбрать модели, прочитай уровни и роли. Не загружай этот справочник в обычном прогоне с уже настроенными ролями.

При развитии скилла или первом прогоне в новой среде прочитай полевые заметки и проверь открытые предположения.

Формат возврата

Каждому субагенту задай этот договор результата:

ИТОГ: завершено | есть вопросы | заблокировано
ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики
РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь
НАХОДКИ: SEVERITY файл:строка — суть — как проверить
СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет»

Пустые разделы пропускаются. Сырой вывод и ход рассуждений в ответ не включаются.

Для ревьюера замени общий раздел ИТОГ на обязательный договор:

ВЕРДИКТ: APPROVED | REVISE
ПОКРЫТИЕ: проверенные области, файлы и команды
ДОКАЗАТЕЛЬСТВА: результаты проверок или воспроизведения
НАХОДКИ: SEVERITY файл:строка — сценарий сбоя — как проверить

Пустой индекс принимай только с заполненными покрытием и доказательствами. Для дорогого ревью попроси также сохранить индекс в /tmp и вернуть путь: сообщение может потеряться после завершения треда.

Конвейер

1. Зафиксировать задачу

Создай или уточни принятый проектом файл-задачу: цель, критерии приёмки, границы, решения, что прочитать и команды проверки. Шумное исследование репозитория отдай быстрому исследователю. Он находит команды, но не запускает полный набор; узкую проверку выполняет только для подтверждения нужного факта. Если задача ссылается на другой скилл, продублируй его ключевые требования текстом: исполнитель может не подхватить скилл автоматически.

Этап завершён, когда исполнитель может начать без истории разговора и без уточняющих вопросов.

2. Проверить постановку

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

Внеси в файл-задачу решение по каждой находке: принять, сузить или отклонить с доводом.

Этап завершён, когда у каждой находки есть записанное решение.

3. Реализовать

Передай задачу отдельному исполнителю с правом записи. Мандат: следовать файлу-задаче, не делать коммит, не менять соседний объём. Исполнитель запускает только узкие проверки разработки; полный набор остаётся этапу 4.

Этап завершён, когда отчёт исполнителя соответствует изменённому дереву и все критерии либо выполнены, либо явно помечены как заблокированные.

4. Переварить проверки

Отдай быстрому проверяющему тесты, линтеры, сборку и объёмные журналы. Пусть он вернёт команды, счётчики, короткую причину каждого сбоя и путь к полному журналу. Исправления возвращай исполнителю этапа 3.

Этап завершён, когда полный обязательный набор прошёл после последней правки или каждый оставшийся сбой объяснён и принят пользователем.

5. Провести слепое ревью

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

Этап завершён, когда все запрошенные вердикты получены, а рабочее дерево не содержит неназванных правок.

6. Закрыть находки

Дословно передай общий индекс исполнителю этапа 3. Он исправляет находку, сужает исправление или отклоняет её через контракт, код и проверку. Мастер проверяет серьёзные и спорные отклонения, решает вопросы объёма и риска. Исправления отправляй прежнему ревьюеру на узкую повторную проверку.

Этап завершён, когда по каждой находке записано решение и принятые исправления перепроверены.

7. Принять результат

Используй отчёт этапа 4. Повтори только проверки, которые обесценили более поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя делегировать. Обнови файл-задачу. Коммит делай только по просьбе пользователя.

Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны, неназванных изменений нет, а пользователь получил краткий итог.

Сбои координации

• Агент исчез без отчёта: сначала проверь сохранённый файл, затем один раз запроси итог. После повторной тишины подними свежего агента с файлом-задачей и уже собранным индексом.
• Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по договору возврата.
• Два писателя пересеклись: останови их, установи владельца каждой правки и продолжи одним исполнителем от проверенной точки отсчёта.
• Находки не становятся слабее по раундам: останови цикл и вынеси пользователю противоречие или неверно выбранную границу задачи.