feat(agents): добавлен плейбук оркестрации субагентов

- Зачем: - нужен повторяемый процесс делегирования без засорения контекста мастер-модели. - Что: - добавлен явно вызываемый скилл с этапами, договорами возврата и защитой рабочего дерева. - описаны роли, уровни стоимости, полевые заметки и handoff для следующей версии. - Проверка: - quick_validate.py agents/.agents/skills/codex-subagent-playbook. - git diff --cached --check.
2026-07-10 16:46:57 +03:00
1 parent 6e767d13ff
commit 4d074adda6
@@ -0,0 +1,156 @@
+---
+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. Повтори только проверки, которые обесценили более
+поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя
+делегировать. Обнови файл-задачу. Коммит делай только по просьбе
+пользователя.
+
+Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны,
+неназванных изменений нет, а пользователь получил краткий итог.
+
+## Сбои координации
+
+- Агент исчез без отчёта: сначала проверь сохранённый файл, затем один раз
+  запроси итог. После повторной тишины подними свежего агента с
+  файлом-задачей и уже собранным индексом.
+- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по
+  договору возврата.
+- Два писателя пересеклись: останови их, установи владельца каждой правки и
+  продолжи одним исполнителем от проверенной точки отсчёта.
+- Находки не становятся слабее по раундам: останови цикл и вынеси пользователю
+  противоречие или неверно выбранную границу задачи.
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Codex Subagent Playbook"
+  short_description: "Делегирование без засорения контекста мастера"
+  default_prompt: "Используй $codex-subagent-playbook, чтобы провести задачу через субагентов и сохранить контекст мастера чистым."
+policy:
+  allow_implicit_invocation: false
@@ -0,0 +1,83 @@
+# Handoff: первая версия Codex Subagent Playbook
+
+Дата: 2026-07-10. Для следующей сессии, которая добавит настоящие роли
+Codex и проверит полный конвейер на боевой задаче.
+
+## Состояние
+
+Первая версия скилла готова и формально валидна:
+
+- процесс тонкого мастера — [`../SKILL.md`](../SKILL.md);
+- выбор ролей и уровней — [`../references/roles.md`](../references/roles.md);
+- перенесённые уроки и открытые проверки —
+  [`../references/field-notes.md`](../references/field-notes.md);
+- явный вызов скилла — [`../agents/openai.yaml`](../agents/openai.yaml).
+
+Нативные TOML-роли ещё не созданы. В текущем интерфейсе `spawn_agent` роль,
+модель и глубина рассуждений не выбираются явно, поэтому первый пробный
+прогон использовал роли только как мандаты в промпте и честно пометил
+стоимость как неуправляемую.
+
+## Принятые решения
+
+- Главная цель — сохранить контекст мастер-модели для требований, решений и
+  синтеза. Внешняя модель остаётся необязательной дополнительной линией.
+- Скилл запускается только явно. Текущий валидатор не принимает
+  `disable-model-invocation`; используется
+  `policy.allow_implicit_invocation: false` в `openai.yaml`.
+- Модели закрепляются в файлах ролей, а не в `SKILL.md`, чтобы процесс не
+  зависел от смены модельной линейки.
+- Один агент владеет рабочим деревом. До записи сохраняется точка отсчёта,
+  включая хэши неотслеживаемых файлов.
+- Критичный отчёт ревьюера возвращается сообщением и сохраняется в `/tmp`.
+- Нативный конвейер не зависит от вложенного запуска `codex exec`.
+
+## Что проверено
+
+- `quick_validate.py` завершился с `Skill is valid!`.
+- Независимое ревью закрыло договор ревьюера, точку отсчёта, выбор стоимости
+  и устранение лишних повторных прогонов.
+- Безопасный пробный прогон этапов 1–2 поднял исследователя и ревьюера,
+  сформировал самодостаточную постановку и не вынес сырые журналы в итог
+  мастера. Файлы проекта не менялись.
+- Прогон выявил лишний полный запуск тестов исследователем; ограничение роли
+  уже внесено в процесс и справочник.
+
+## Следующая сессия
+
+1. Решить, входят ли Windows/chezmoi в первую поставку ролей. Пробная
+   постановка ограничила первую поставку Linux/WSL.
+2. Выбрать модели для быстрого, рабочего и глубокого уровней. Локально
+   подтверждена только `gpt-5.6-sol`; не считать это готовой таблицей ролей.
+3. Создать шесть ролей: `fast-worker`, `explorer`, `worker`,
+   `deep-reasoner`, `reviewer`, `verifier`.
+4. Разместить Linux/WSL-источник в `codex/.codex/agents/` и узко открыть
+   нужные TOML в `.gitignore`. Сейчас родительское правило игнорирует весь
+   каталог.
+5. Расширить `tests/test_install.sh`: разобрать TOML через `tomllib`,
+   проверить смысловые договоры ролей, повторную установку, стороннюю роль и
+   конфликт совпадающего имени.
+6. Проверить обнаружение ролей установленным Codex CLI в отдельном
+   `CODEX_HOME`. Синтаксический разбор TOML не доказывает поддержку схемы.
+7. Прогнать этапы 3–7 на подходящей задаче, обновить полевые заметки только
+   подтверждёнными фактами и убрать поглощённый осадок.
+
+## Известные ловушки
+
+- Простое исключение `!codex/.codex/agents/*.toml` может не сработать, пока
+  не раскрыты игнорируемые родительские каталоги. Нужны положительные и
+  отрицательные проверки `git check-ignore`.
+- Текущее рабочее дерево dotfiles содержит посторонние изменения. Работать
+  от сохранённой точки отсчёта, не очищать и не включать их в коммиты.
+- `task_name` нативного `spawn_agent` — имя треда, а не доказанный выбор
+  пользовательской конфигурации агента.
+- Права `workspace-write` не гарантируют сеть. Проверку документации и поиск
+  отмечать как непроверенные, если сеть недоступна.
+
+## Suggested skills
+
+- `$writing-great-skills` — удерживать плотность и предсказуемость скилла.
+- `$skill-creator` — валидировать структуру и проводить пробные прогоны.
+- `$tdd` — сначала закрепить установку и договоры ролей тестами.
+- `$claude-team-review` — независимое ревью после появления TOML и тестов.
+- `$conventional-commits` — зафиксировать следующую завершённую поставку.
@@ -0,0 +1,47 @@
+# Полевые заметки
+
+Читай этот файл при развитии скилла и при первом прогоне в новой среде. После
+боевого прогона записывай только факты, которые меняют процесс. Когда урок
+поглощён `SKILL.md` или `roles.md`, сжимай запись до одной строки со ссылкой.
+
+## Перенесено из исходного плейбука
+
+- Разные семейства моделей находили почти непересекающиеся классы ошибок.
+  Это аргумент за внешний обзор, но не обязательная часть конвейера.
+- Ревьюер без прав на запись хуже проверял гипотезы, когда тестам нужны кэши
+  и временные артефакты. Рабочая защита: точка отсчёта Git, явный мандат не
+  менять исходники и сверка дерева после ревью.
+- Пустой вердикт сам по себе не доказывает работу ревьюера. Нужны покрытие,
+  выполненные команды или другие наблюдаемые доказательства.
+- Настройки модели, унаследованные от интерактивной сессии, менялись между
+  запусками. Для управляемой стоимости модель и глубину надо закреплять.
+- Критичный отчёт фонового агента мог потеряться после его завершения.
+  Надёжнее сообщение плюс файл с индексом.
+- Ссылка на другой скилл в файле-задаче не проверена как надёжный способ его
+  включить. Ключевые требования надо дублировать текстом.
+- Прямой запуск внешнего Codex зависел от версии песочницы, AppArmor и сети.
+  Нативный конвейер не должен зависеть от внешнего CLI.
+
+## Проверить боем
+
+1. Выбирает ли текущий хост пользовательского агента по имени и показывает ли
+   фактически использованную модель.
+2. Даёт ли набор быстрых ролей экономию без повторной работы сильной модели.
+3. Остаётся ли дерево неизменным после ревьюера с `workspace-write`.
+4. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях.
+5. Достаточно ли общего договора возврата, чтобы мастер не открывал сырые
+   журналы и полные отчёты.
+6. Где проходит практический порог между прямой работой и полным конвейером.
+
+## 2026-07-10 — пробный прогон этапов 1–2
+
+- Мастер без истории исходного плейбука поднял исследователя и ревьюера,
+  свёл их вывод в самодостаточную постановку и не вынес сырые журналы в
+  итоговый контекст.
+- Доступный `spawn_agent` не позволил закрепить пользовательскую роль,
+  модель или стоимость. Роли были только мандатами в промпте; мастер честно
+  отметил неуправляемую стоимость.
+- Исследователь обнаружил блокирующее правило `.gitignore` для будущих TOML,
+  которое мастер без шумного обхода репозитория мог пропустить.
+- Исследователь без необходимости запустил полный набор тестов. Ограничение
+  «карта команд, а не полный прогон» поглощено в `SKILL.md` и `roles.md`.
@@ -0,0 +1,134 @@
+# Уровни и роли
+
+Читай этот файл только при настройке ролей или когда нужная роль недоступна.
+Сам конвейер описан в `SKILL.md`.
+
+- [Возможности хоста](#возможности-хоста)
+- [Выбор уровня](#выбор-уровня)
+- [Роли](#роли)
+- [Файл пользовательского агента](#файл-пользовательского-агента)
+- [Пределы параллельности](#пределы-параллельности)
+
+## Возможности хоста
+
+Сначала установи, позволяет ли текущий хост выбрать пользовательского агента
+и его конфигурацию.
+
+- **Управляемая стоимость.** Хост видит агентов из `~/.codex/agents` или
+  `.codex/agents` и позволяет выбрать агента по имени. Вызывай именованную
+  роль; модель и глубину рассуждений закрепляй в её TOML-файле. Не наследуй
+  плавающие настройки мастер-сессии для роли с известным бюджетом.
+- **Неуправляемая стоимость.** Интерфейс запуска принимает только задачу и
+  имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана
+  дешёвая или сильная модель. `task_name` — идентификатор треда, а не выбор
+  конфигурации агента.
+
+Если способ выбора роли не виден в доступном инструменте, считай стоимость
+неуправляемой и отметь это в итоговом отчёте.
+
+## Выбор уровня
+
+| Уровень | Для чего | Настройка |
+|---|---|---|
+| Быстрый | Поиск, чтение журналов, тесты, пакетная механика | Быстрая дешёвая модель, `low` или `medium` |
+| Рабочий | Обычная реализация по ясной постановке | Сильная модель для кода, `medium` или `high` |
+| Глубокий | Архитектура, сложная диагностика, ревью высокого риска | Самая сильная доступная модель, `high` или выше |
+
+Начинай с самого дешёвого подходящего уровня. Повышай уровень, когда агент
+не может проверить предположение, дважды возвращает слабый результат или
+задача требует решения с высокой ценой ошибки. Не повышай уровень ради
+объёма механической работы: дели её на независимые части.
+
+- `low`/`medium`: детерминированная механика, поиск и известные проверки.
+- `medium`/`high`: реализация по ясному контракту, несколько связанных
+  файлов, нет необратимых решений.
+- `high`: публичный контракт, безопасность, целостность данных, конкуренция,
+  миграция или неоднозначная архитектура.
+- `xhigh` и выше: необратимый дорогой выбор либо повторное противоречие
+  сильных агентов. Это исключение, а не обычный режим ревью.
+
+Конкретные названия моделей держи в конфигурации агентов, а не в `SKILL.md`.
+Так замена модельной линейки не меняет процесс.
+
+## Роли
+
+### `fast-worker`
+
+Уровень: быстрый. Читает шумный ввод, запускает проверки, выполняет простые
+пакетные операции. Возвращает только выжимку и пути к полным журналам.
+
+Обычно: `sandbox_mode = "workspace-write"`, потому что тесты и инструменты
+создают временные файлы. В инструкциях ограничить изменения явно названной
+механикой.
+
+### `explorer`
+
+Уровень: быстрый. Строит карту кода, находит точки входа, контракты и команды
+проверки. Не запускает полный набор тестов и не проектирует решение, пока
+мастер прямо не попросит. Узкую команду запускает только для проверки факта,
+без которого карта ненадёжна.
+
+Обычно: `sandbox_mode = "read-only"`.
+
+### `worker`
+
+Уровень: рабочий или глубокий по сложности задачи. Единственный владелец
+реализации. Читает самодостаточный файл-задачу, меняет код и проверяет свою
+часть. Не делает коммит.
+
+Обычно: `sandbox_mode = "workspace-write"`.
+
+### `deep-reasoner`
+
+Уровень: глубокий. Принимает одно сложное решение: архитектура, алгоритм,
+диагноз, противоречие требований. Возвращает рекомендацию, ключевые доводы и
+непроверенные предположения.
+
+Обычно: `sandbox_mode = "read-only"`.
+
+### `reviewer`
+
+Уровень: глубокий. Свежий тред без истории исполнителя. Ищет ошибки
+корректности, безопасности, контракта и тестов. Каждая находка содержит
+сценарий сбоя, доказательство, влияние и способ проверки.
+
+Для чистого чтения: `sandbox_mode = "read-only"`. Если ревью требует запуска
+инструментов, которые пишут кэш или артефакты, использовать
+`workspace-write`, запретить правки исходников мандатом и сверить Git до и
+после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и
+доступ к документации. Непроверенную внешнюю механику отмечать как гипотезу.
+
+### `verifier`
+
+Уровень: быстрый. Запускает уже известные команды приёмки, разбирает сбои и
+возвращает счётчики. Не ищет новые требования и не исправляет продуктовый
+код.
+
+Обычно: `sandbox_mode = "workspace-write"`.
+
+## Файл пользовательского агента
+
+Роли Codex хранятся в `~/.codex/agents/*.toml` или `.codex/agents/*.toml`.
+Минимальный шаблон:
+
+```toml
+name = "role-name"
+description = "Когда координатору выбирать эту роль."
+model = "<актуальная модель нужного уровня>"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Одна узкая роль и её договор результата.
+"""
+```
+
+Не подменяй выбор роли совпадением `task_name` с её именем: это работает
+только при явной гарантии хоста.
+
+## Пределы параллельности
+
+- Держи глубину `1`: субагенты не создают собственное дерево исполнителей.
+- Оставляй один слот мастеру.
+- Параллельно запускай чтение, независимые исследования и слепые ревью.
+- Реализацию и починку одного рабочего дерева выполняй последовательно одним
+  владельцем.