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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Конвейер

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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