diff --git a/agents/.agents/skills/codex-subagent-playbook/SKILL.md b/agents/.agents/skills/codex-subagent-playbook/SKILL.md new file mode 100644 index 0000000..67703a5 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/SKILL.md @@ -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. Повтори только проверки, которые обесценили более +поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя +делегировать. Обнови файл-задачу. Коммит делай только по просьбе +пользователя. + +Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны, +неназванных изменений нет, а пользователь получил краткий итог. + +## Сбои координации + +- Агент исчез без отчёта: сначала проверь сохранённый файл, затем один раз + запроси итог. После повторной тишины подними свежего агента с + файлом-задачей и уже собранным индексом. +- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по + договору возврата. +- Два писателя пересеклись: останови их, установи владельца каждой правки и + продолжи одним исполнителем от проверенной точки отсчёта. +- Находки не становятся слабее по раундам: останови цикл и вынеси пользователю + противоречие или неверно выбранную границу задачи. diff --git a/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml b/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml new file mode 100644 index 0000000..64d08c7 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Codex Subagent Playbook" + short_description: "Делегирование без засорения контекста мастера" + default_prompt: "Используй $codex-subagent-playbook, чтобы провести задачу через субагентов и сохранить контекст мастера чистым." +policy: + allow_implicit_invocation: false diff --git a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md new file mode 100644 index 0000000..b101d53 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md @@ -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` — зафиксировать следующую завершённую поставку. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md b/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md new file mode 100644 index 0000000..3f81b90 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md @@ -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`. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/roles.md b/agents/.agents/skills/codex-subagent-playbook/references/roles.md new file mode 100644 index 0000000..ff427c7 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/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`: субагенты не создают собственное дерево исполнителей. +- Оставляй один слот мастеру. +- Параллельно запускай чтение, независимые исследования и слепые ревью. +- Реализацию и починку одного рабочего дерева выполняй последовательно одним + владельцем.