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

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

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

Ты — координатор. Держи в своём контексте цель, ограничения, решения и
индекс находок. Исследование, реализацию, проверки, журналы и полный 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, а также перечень и хэши неотслеживаемых
  файлов. После него сравни новое состояние с точкой отсчёта и отчётом. Не
  удаляй и не откатывай чужие изменения.
- Сообщай пользователю короткий статус на границах этапов.

Если нужные роли ещё не настроены или надо выбрать модели, прочитай
[уровни и роли](references/roles.md). Не загружай этот справочник в обычном
прогоне с уже настроенными ролями.

При развитии скилла или первом прогоне в новой среде прочитай
[полевые заметки](references/field-notes.md) и проверь открытые предположения.

Точные договоры заданий и результатов бери из нужного раздела
[скелетов нативных промптов](references/prompt-templates.md). Это их
единственный источник; не переписывай форматы в других файлах.

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

Если результат понадобится следующему агенту, полный отчёт сначала запиши в
отдельный файл обменного каталога. Финальный ответ ограничь состоянием,
счётчиками, коротким индексом и путём. Для параллельных агентов используй
разные пути. Не возвращай один полный отчёт одновременно файлом и сообщением.
До запуска выбери канал: агент с записью в обменный каталог сохраняет полный
отчёт файлом; `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`. После повторной тишины
  подними свежего агента с файлами задачи и уже собранного индекса.
- При блокировке перенеси нужные для продолжения данные в долговечный
  артефакт по правилам проекта и удали остальной обменный каталог прогона.
- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по
  договору возврата.
- Два писателя пересеклись: останови их, установи владельца каждой правки и
  продолжи одним исполнителем от проверенной точки отсчёта.
- Находки не становятся слабее по раундам: останови цикл и вынеси пользователю
  противоречие или неверно выбранную границу задачи.