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,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`: субагенты не создают собственное дерево исполнителей.
+- Оставляй один слот мастеру.
+- Параллельно запускай чтение, независимые исследования и слепые ревью.
+- Реализацию и починку одного рабочего дерева выполняй последовательно одним
+  владельцем.