# Handoff: первая версия Codex Subagent Playbook

Дата: 2026-07-10. Для следующей сессии, которая добавит настоящие роли
Codex и проверит полный конвейер на боевой задаче.

## Состояние

Первая версия скилла готова и формально валидна:

- процесс тонкого мастера — [`../SKILL.md`](../SKILL.md);
- выбор ролей и уровней — [`../references/roles.md`](../references/roles.md);
- перенесённые уроки и открытые проверки —
  [`../references/lessons.md`](../references/lessons.md);
- точные договоры нативных агентов —
  [`../references/prompt-templates.md`](../references/prompt-templates.md);
- явный вызов скилла — [`../agents/openai.yaml`](../agents/openai.yaml).

Нативные TOML-роли ещё не созданы. В интерфейсе пробной tool-backed сессии
хост скрыл поля `agent_type`, `model`, `reasoning_effort` и `service_tier`,
поэтому прогон использовал роли только как мандаты в промпте и честно
пометил стоимость как неуправляемую. Это не общее ограничение Codex:
нативная схема поддерживает все четыре поля.

## Принятые решения

- Главная цель — сохранить контекст мастер-модели для требований, решений и
  синтеза. Внешняя модель остаётся необязательной дополнительной линией.
- Скилл запускается только явно. Текущий валидатор не принимает
  `disable-model-invocation`; используется
  `policy.allow_implicit_invocation: false` в `openai.yaml`.
- Модели закрепляются в файлах ролей, а не в `SKILL.md`, чтобы процесс не
  зависел от смены модельной линейки.
- Для TOML-роли передаётся `agent_type`; для разового выбора — `model` и
  `reasoning_effort` без роли с закреплённой моделью. Плейбук использует
  `fork_turns="none"` ради чистого контекста; полный fork `all` наследует
  модель мастера.
- Один агент владеет рабочим деревом. До записи сохраняется точка отсчёта,
  включая хэши неотслеживаемых файлов.
- Полный отчёт ревьюера сохраняется файлом; сообщение содержит только
  вердикт, счётчики и путь. `read-only`-ревьюер возвращает короткий индекс
  один раз сообщением.
- На прогон создаётся один обменный временный каталог. Полные отчёты и
  повторно используемые промпты передаются между агентами путями; мастер не
  вставляет их повторно в tool-call.
- После завершения или сохранения блокирующего handoff обменный каталог
  этого прогона удаляется.
- Нативный конвейер не зависит от вложенного запуска `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`. Затем начать новую сессию и проверить, что её схема
   `spawn_agent` открывает `agent_type`, `model`, `reasoning_effort` и
   `service_tier`.
   Синтаксический разбор TOML не доказывает поддержку схемы.
7. Прогнать этапы 3–7 на подходящей задаче, обновить полевые заметки только
   подтверждёнными фактами и убрать поглощённый осадок.
8. Измерить, сколько длинных отчётов реально попало в контекст мастера.
   Цель — каждый полный артефакт читается не более одного раза и больше не
   пересказывается между агентами.

## Известные ловушки

- Простое исключение `!codex/.codex/agents/*.toml` может не сработать, пока
  не раскрыты игнорируемые родительские каталоги. Нужны положительные и
  отрицательные проверки `git check-ignore`.
- Текущее рабочее дерево dotfiles содержит посторонние изменения. Работать
  от сохранённой точки отсчёта, не очищать и не включать их в коммиты.
- `task_name` нативного `spawn_agent` — имя треда, а не доказанный выбор
  пользовательской конфигурации агента.
- Полный fork `all` несовместим с другой ролью, моделью и глубиной. Плейбук
  использует `none` для свежего контекста; ограниченный fork числом
  технически допускает переопределения.
- Некоторые tool-backed хосты скрывают поля управления моделью, хотя Codex
  их поддерживает. Проверять фактическую схему в начале сессии.
- Права `workspace-write` не гарантируют сеть. Проверку документации и поиск
  отмечать как непроверенные, если сеть недоступна.
- Длинный текст в `spawn_agent`, `send_message` или `followup_task` остаётся
  в истории мастера. Передавать путь к файлу и короткий вопрос.

## Suggested skills

- `$writing-great-skills` — удерживать плотность и предсказуемость скилла.
- `$skill-creator` — валидировать структуру и проводить пробные прогоны.
- `$tdd` — сначала закрепить установку и договоры ролей тестами.
- `$claude-team-review` — независимое ревью после появления TOML и тестов.
- `$conventional-commits` — зафиксировать следующую завершённую поставку.