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

name, description

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

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

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

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

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

• Запускай свежих исполнителей без истории мастера (fork_turns="none"). Если схема spawn_agent открывает agent_type, model и reasoning_effort, выбери один источник истины: для TOML-роли передай только agent_type; для разового выбора передай model и reasoning_effort без роли с закреплённой моделью. Полный fork all несовместим с этими переопределениями; плейбук использует none ради чистого контекста. Передавай путь к самодостаточному файлу-задаче, а не пересказ разговора.
• Давай каждому субагенту одну роль и проверяемый результат. Выбирай самый дешёвый уровень, который надёжно справится с этой ролью. Если хост скрыл параметры модели, пометь стоимость как незакреплённую.
• В начале прогона создай один обменный каталог во временном каталоге ОС с непредсказуемым именем (mktemp -d или аналог) и передай агентам его абсолютный путь. Индекс держи у мастера; длинные отчёты, журналы и повторно используемые промпты — файлами. Прочитай полезную нагрузку один раз, дальше передавай путь: аргументы spawn_agent, send_message и followup_task остаются в истории мастера.
• Проси вернуть только итог, доказательства, вопросы-решения и следующий шаг. Полные журналы оставляй в обменном каталоге. В репозиторий клади только долговечные артефакты, предусмотренные его правилами.
• Продолжай того же исполнителя для починки его кода. Для независимого ревью запускай свежий тред.
• Держи одного владельца рабочего дерева. Пока он пишет, другие агенты не читают это дерево. Параллель разрешай только для неизменяемых входов или отдельных worktree.
• До писателя сохрани в /tmp машинно читаемую точку отсчёта: статус, полный staged/unstaged diff, а также перечень и хэши неотслеживаемых файлов. После него сравни новое состояние с точкой отсчёта и отчётом. Не удаляй и не откатывай чужие изменения.
• Сообщай пользователю короткий статус на границах этапов.

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

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

Точные договоры заданий и результатов бери из нужного раздела скелетов нативных промптов. Это их единственный источник; не переписывай форматы в других файлах.

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

Если результат понадобится следующему агенту, полный отчёт сначала запиши в отдельный файл обменного каталога. Финальный ответ ограничь состоянием, счётчиками, коротким индексом и путём. Для параллельных агентов используй разные пути. Не возвращай один полный отчёт одновременно файлом и сообщением. До запуска выбери канал: агент с записью в обменный каталог сохраняет полный отчёт файлом; read-only-агент возвращает короткий индекс один раз сообщением. Для длинного переиспользуемого отчёта заранее выбери workspace-write, запрети правки исходников и сверь Git до и после.

Конвейер

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создай один канонический файл ревью на всех слепых ревьюеров. Запусти свежего ревьюера без контекста исполнителя; в message передай путь к этому файлу и выбранный канал результата. Для workspace-write добавь уникальный путь файла, для read-only запроси один короткий индекс сообщением. Для высокого риска запусти двух ревьюеров параллельно с разными фокусами и каналами, которые не конфликтуют. Внешнюю модель подключай дополнительной линией, если она доступна и её стоимость оправдана. Ревьюеры исследуют и проверяют гипотезы, но не исправляют код. Канал результата выбери по правилам раздела «Формат возврата»; точный договор — в скелете слепого ревью.

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

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

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

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

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

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

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

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

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