diff --git a/agents/.agents/skills/codex-subagent-playbook/SKILL.md b/agents/.agents/skills/codex-subagent-playbook/SKILL.md index a350760..4f270d7 100644 --- a/agents/.agents/skills/codex-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/codex-subagent-playbook/SKILL.md @@ -1,169 +1,132 @@ --- name: codex-subagent-playbook -description: Координация одной нетривиальной инженерной задачи через субагентов с сохранением чистого контекста мастера. +description: Оптика тонкого мастера для одной нетривиальной задачи: субагенты сохраняют контекст и приносят нужную независимость. --- # Тонкий мастер -Ты — координатор. Держи в своём контексте цель, ограничения, решения и -индекс находок. Исследование, реализацию, проверки, журналы и полный diff -отдавай субагентам. Внешний агент полезен как дополнительная независимая -линия, но процесс не должен от него зависеть. +Это оптика работы, а не обязательный конвейер. Цель — решить одну +нетривиальную задачу, сохранив внимание мастера для цели, ограничений, +решений и рисков. Субагенты нужны результату, а не процессу. -Применяй конвейер к одной нетривиальной задаче. Если работа локальна, вывод -короток и ошибка дёшева, сообщи о лишних накладных расходах и сделай её сам. +Тонкий мастер не пустой мастер. Он сам принимает решения, делает дешёвые +точечные проверки и смотрит ключевые артефакты. Исследование, реализацию или +проверку он отдаёт только тогда, когда отдельный контекст даст задаче +конкретное преимущество. -## Договор делегирования +## Основная оптика -- Запускай свежих исполнителей без истории мастера (`fork_turns="none"`). - Если схема `spawn_agent` открывает `agent_type`, `model` и - `reasoning_effort`, выбери один источник истины: для TOML-роли передай - только `agent_type`; для разового выбора передай `model` и - `reasoning_effort` без роли с закреплённой моделью. Полный fork `all` - несовместим с этими переопределениями; плейбук использует `none` ради - чистого контекста. Передавай путь к самодостаточному файлу-задаче, а не - пересказ разговора. -- Давай каждому субагенту одну роль и проверяемый результат. Выбирай самый - дешёвый уровень, который надёжно справится с этой ролью. Если хост скрыл - параметры модели, пометь стоимость как незакреплённую. -- В начале прогона создай один обменный каталог во временном каталоге ОС с - непредсказуемым именем (`mktemp -d` или аналог) и передай агентам его - абсолютный путь. Индекс держи у мастера; длинные отчёты, журналы и - повторно используемые промпты — файлами. Прочитай полезную нагрузку один - раз, дальше передавай путь: аргументы `spawn_agent`, `send_message` и - `followup_task` остаются в истории мастера. -- Проси вернуть только итог, доказательства, вопросы-решения и следующий - шаг. Полные журналы оставляй в обменном каталоге. В репозиторий клади - только долговечные артефакты, предусмотренные его правилами. -- Продолжай того же исполнителя для починки его кода. Для независимого - ревью запускай свежий тред. -- Держи одного владельца рабочего дерева. Пока он пишет, другие агенты не - читают это дерево. Параллель разрешай только для неизменяемых входов или - отдельных worktree. -- До писателя сохрани в `/tmp` машинно читаемую точку отсчёта: статус, - полный staged/unstaged diff, а также перечень и хэши неотслеживаемых - файлов. После него сравни новое состояние с точкой отсчёта и отчётом. Не - удаляй и не откатывай чужие изменения. -- Сообщай пользователю короткий статус на границах этапов. +- Перед каждым запуском ответь: что этот агент добавит — защиту контекста, + свежий взгляд, специализацию, параллельность или отдельную среду проверки? + Если ничего, работай сам или продолжи существующий тред. +- Держи у мастера короткий индекс: цель, ограничения, принятые решения, + риски, вердикты и доказательства, влияющие на следующий шаг. Полные diff, + журналы и нарративы ему не нужны. +- Исследование с неизвестным или шумным объёмом делегируй до погружения. + Одну узкую гипотезу с предсказуемо короткой командой мастер может проверить + сам; если ответа нет, продолжение уходит агенту. +- Свежий тред даёт независимость от исполнителя, но не разнообразие ошибок. + Другое семейство моделей даёт отдельную линию; второй агент того же + семейства оправдан только высоким риском или действительно иным фокусом. +- Выбирай самый дешёвый надёжный уровень для выбранной работы. Если хост не + показывает модель и глубину, считай стоимость незакреплённой и не умножай + совместимые роли без явной пользы. +- Один исполнитель владеет изменениями исходников. Его же продолжай для + исправлений; независимую оценку отдавай свежему треду. Права + `workspace-write` сами по себе не делают агента владельцем исходников. -Если нужные роли ещё не настроены или надо выбрать модели, прочитай -[уровни и роли](references/roles.md). Не загружай этот справочник в обычном -прогоне с уже настроенными ролями. +Внешняя модель полезна как дополнительная линия, когда её родословная и цена +оправданы риском. Процесс не должен от неё зависеть. + +## Контекст и обмен + +- Если результат понадобится следующему агенту, полный отчёт запиши в + уникальный файл временного обменного каталога. Мастеру верни только итог, + счётчики, вопросы-решения и путь. Короткий конечный результат можно вернуть + одним сообщением. +- Канал результата не связан с правами агента. Ревьюеру можно дать рабочие + права для тестов, кэшей, поиска и документации, а запрет менять исходники и + постоянное окружение удерживать мандатом и сверкой Git до и после. +- Не возвращай один полный отчёт одновременно файлом и сообщением. Не + переписывай находки между файлами: передавай исходный путь или собирай новый + промпт механической конкатенацией. +- Не выводи в контекст мастера полную точку отсчёта, diff, перечень хэшей или + сырой журнал. Если дерево грязное или возможны пересечения, порученный + агент либо готовый скрипт сохраняет подробности во временный файл и сообщает + только состояние, счётчики, пересечение с разрешённым объёмом и путь. +- Временные обменные файлы веди на английском. Долговечные документы и текст + для пользователя пиши на языке проекта. +- Сообщай пользователю короткий статус на действительно значимых границах, а + не на каждом служебном переходе. Тайм-аут и `idle` не являются результатом. + +## Когда какой приём полезен + +- **Самодостаточная постановка** нужна, когда исполнитель начинает без истории + разговора или проекту важен долговечный след. Для локальной ясной правки + достаточно короткого мандата. +- **Исследователь** нужен для неизвестного объёма, внешних фактов или шумного + обхода репозитория. Его результат — факты и вопросы, не реализация. +- **Ревью постановки** окупается при скрытых проектных решениях, дорогой ошибке + или критериях, которые можно выполнить формально без нужного результата. +- **Исполнитель** нужен, когда отдельный контекст реализации ценнее прямой + работы мастера. Он не коммитит и не расширяет объём без решения мастера. +- **Проверяющий** нужен для шумных журналов, специальной среды, стенда или + независимого подтверждения команд. Не создавай отдельную роль, если те же + проверки дёшево и надёжно выполняет исполнитель либо ревьюер. +- **Свежий ревьюер** нужен, когда цена пропущенного дефекта выше стоимости + обзора. По умолчанию достаточно одного. Вторую линию добавляй ради другого + семейства моделей или отдельного класса риска, а не ради числа два. + +## Типичный ход задачи + +Часто полезно уточнить постановку, дать одному исполнителю реализовать её, +проверить обязательные свойства и при заметном риске получить свежий обзор. +Пропускай, объединяй и меняй порядок этих действий, если так надёжнее и +дешевле достигается результат. + +- Перед реализацией разреши продуктовые, архитектурные и относящиеся к + границам решения вне мандата исполнителя. Технический способ внутри мандата + оставь ему. +- Пока исполнитель меняет исходники, не запускай другого владельца тех же + файлов. Параллель разрешай для независимых неизменяемых входов, отдельных + worktree или команд без общего изменяемого состояния. +- Обязательные и доступные сквозные проверки должны пройти до финальной + приёмки. Недоступную или падающую проверку нельзя молча превратить в зелёную: + риск принимает пользователь либо полномочие, заранее записанное в задаче. +- Ревьюеру дай задачу, изменённый объём, проверки и один выбранный фокус. Он + исследует и проверяет гипотезы, но не исправляет исходники. Вердикт без + находок должен назвать просмотренный объём и выполненные проверки либо + проверенные гипотезы. +- Находки возвращай тому же исполнителю. Он исправляет или аргументированно + отклоняет их через контракт и проверку. Исходный ревьюер при необходимости + узко проверяет свои находки; новый соседний дефект не скрывает. +- На финале мастер смотрит только решения, остаточные риски, итоговые счётчики + и действительно ключевые артефакты. Полный diff и отчёты читают агенты, + которым поручена их проверка. Коммит делай только по просьбе пользователя. + +## Нативные договоры + +Если нужны готовые роли или выбор моделей, прочитай +[уровни и роли](references/roles.md). Если роли не настроены, не имитируй +экономию названиями: честно отметь незакреплённую стоимость. + +Когда выбран конкретный приём, возьми только его договор из +[сборки нативных промптов](references/prompt-templates.md). Не загружай все +шаблоны заранее и не переписывай их текст в вызов агента. При развитии скилла или первом прогоне в новой среде прочитай -[полевые заметки](references/field-notes.md) и проверь открытые предположения. - -Точные договоры заданий и результатов бери из нужного раздела -[скелетов нативных промптов](references/prompt-templates.md). Это их -единственный источник; не переписывай форматы в других файлах. - -## Формат возврата - -Если результат понадобится следующему агенту, полный отчёт сначала запиши в -отдельный файл обменного каталога. Финальный ответ ограничь состоянием, -счётчиками, коротким индексом и путём. Для параллельных агентов используй -разные пути. Не возвращай один полный отчёт одновременно файлом и сообщением. -До запуска выбери канал: агент с записью в обменный каталог сохраняет полный -отчёт файлом; `read-only`-агент возвращает короткий индекс один раз -сообщением. Для длинного переиспользуемого отчёта заранее выбери -`workspace-write`, запрети правки исходников и сверь Git до и после. - -## Конвейер - -### 1. Зафиксировать задачу - -Создай или уточни принятый проектом файл-задачу: цель, критерии приёмки, -границы, решения, что прочитать и команды проверки. Шумное исследование -репозитория отдай быстрому исследователю. Он находит команды, но не запускает -полный набор; узкую проверку выполняет только для подтверждения нужного -факта. Если задача ссылается на другой скилл, продублируй его ключевые -требования текстом: исполнитель может не подхватить скилл автоматически. - -Этап завершён, когда исполнитель может начать без истории разговора и без -уточняющих вопросов. - -### 2. Проверить постановку - -Для сложной или дорогой ошибки отдай постановку свежему сильному ревьюеру. -Попроси проверить её против реального кода: выполнимость, скрытые решения, -пропущенные критерии и способы формально отчитаться без нужного результата. -Для особенно дорогой ошибки используй два слепых ревью. - -Внеси в файл-задачу решение по каждой находке: принять, сузить или отклонить -с доводом. - -Этап завершён, когда у каждой находки есть записанное решение. - -### 3. Реализовать - -Передай задачу отдельному исполнителю с правом записи. Мандат: следовать -файлу-задаче, не делать коммит, не менять соседний объём. Исполнитель -запускает только узкие проверки разработки; полный набор остаётся этапу 4. - -Этап завершён, когда отчёт исполнителя соответствует изменённому дереву и -все критерии либо выполнены, либо явно помечены как заблокированные. - -### 4. Переварить проверки - -Отдай быстрому проверяющему тесты, линтеры, сборку и объёмные журналы. Пусть -он вернёт команды, счётчики, короткую причину каждого сбоя и путь к полному -журналу. Исправления возвращай исполнителю этапа 3. - -Этап завершён, когда полный обязательный набор прошёл после последней правки -или каждый оставшийся сбой объяснён и принят пользователем. - -### 5. Провести слепое ревью - -Создай один канонический файл ревью на всех слепых ревьюеров. Запусти свежего -ревьюера без контекста исполнителя; в `message` передай путь к этому файлу и -выбранный канал результата. Для `workspace-write` добавь уникальный путь -файла, для `read-only` запроси один короткий индекс сообщением. Для высокого -риска запусти двух ревьюеров параллельно с разными фокусами и каналами, -которые не конфликтуют. -Внешнюю модель подключай дополнительной линией, если она доступна и её -стоимость оправдана. Ревьюеры исследуют и проверяют гипотезы, но не -исправляют код. Канал результата выбери по правилам раздела «Формат -возврата»; точный договор — в скелете слепого ревью. - -Этап завершён, когда все запрошенные вердикты получены, а рабочее дерево не -содержит неназванных правок. - -### 6. Закрыть находки - -Продолжи исполнителя этапа 3 и передай пути к исходным индексам без -пересказа. Он исправляет находку, сужает исправление или отклоняет её через -контракт, код и проверку. Мастер проверяет серьёзные и спорные отклонения, -решает вопросы объёма и риска. Исполнитель сохраняет отчёт о решениях -файлом; прежнему ревьюеру передай только путь к нему и запрос на узкую -проверку собственных находок. - -Этап завершён, когда по каждой находке записано решение и принятые -исправления перепроверены. - -### 7. Принять результат - -Используй отчёт этапа 4. Повтори только проверки, которые обесценили более -поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя -делегировать. Обнови файл-задачу. Коммит делай только по просьбе -пользователя. После завершения всех агентов перенеси нужные долговечные -артефакты по правилам проекта и удали только обменный каталог этого прогона. - -Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны, -неназванных изменений нет, а пользователь получил краткий итог. +[полевые заметки](references/field-notes.md) и проверь живые предположения. ## Сбои координации -- После запуска жди через `wait_agent` с реалистичным сроком только когда - результат блокирует следующий шаг. Тайм-аут, idle и сводка об обновлении - не являются результатом; не засоряй историю статусными пингами. -- Агент завершился без отчёта: сначала проверь сохранённый файл, затем один - раз запроси короткий итог через `followup_task`. После повторной тишины - подними свежего агента с файлами задачи и уже собранного индекса. -- При блокировке перенеси нужные для продолжения данные в долговечный - артефакт по правилам проекта и удали остальной обменный каталог прогона. -- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по - договору возврата. -- Два писателя пересеклись: останови их, установи владельца каждой правки и - продолжи одним исполнителем от проверенной точки отсчёта. -- Находки не становятся слабее по раундам: останови цикл и вынеси пользователю - противоречие или неверно выбранную границу задачи. +- Агент завершился без ожидаемого файла: один раз запроси короткий итог в том + же треде; после повторной тишины продолжи свежим агентом от сохранённых + артефактов. +- Агент вернул длинный рассказ в сообщение: попроси повторить ответ индексом и + путём, не переноси рассказ дальше. +- Два исполнителя пересеклись в исходниках: останови их, установи одного + владельца и продолжи от проверенного состояния, не откатывая чужие правки. +- Находки не становятся слабее по раундам: если аргументы исчерпаны, вынеси + пользователю противоречие, риск или неверную границу задачи. +- После завершения сохрани только предусмотренные проектом долговечные + решения и удали временные артефакты именно этого прогона. diff --git a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260712-optika-tonkogo-mastera.md b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260712-optika-tonkogo-mastera.md new file mode 100644 index 0000000..05950b0 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260712-optika-tonkogo-mastera.md @@ -0,0 +1,52 @@ +# Handoff: плейбук возвращён к оптике тонкого мастера + +Дата: 2026-07-12. Для следующей сессии, которая проверит обновлённый скилл на +нетривиальной задаче с кодом, тестами и шумным выводом. + +## Состояние + +Скилл переработан после самоприменения и сравнения с +`claude-subagent-playbook`. Текущий источник поведения — +[`../SKILL.md`](../SKILL.md); это набор приёмов, а не обязательный конвейер. +Нативная механика раскрывается только по выбранной ветке через +[`../references/prompt-templates.md`](../references/prompt-templates.md) и +[`../references/roles.md`](../references/roles.md). + +Факты двух прогонов и ещё непроверенные предположения дистиллированы в +[`../references/field-notes.md`](../references/field-notes.md). Не переносить +их обратно в основной файл без нового наблюдаемого сбоя. + +Ключевая граница следующей работы: субагент запускается ради конкретной пользы +задаче или контексту мастера. Свежий тред не считается второй независимой +родословной. Права агента не определяют канал результата. Полная полезная +нагрузка не должна проходить через контекст мастера. + +## Что проверено + +- Один свежий обзор проверил переработку через оптику `writing-great-skills` и + исходного Claude-плейбука; все принятые находки закрыты, одно предложение + вернуть `read-only` обоснованно отклонено по принятой практике пользователя. +- `git diff --check` проходит. +- Относительные ссылки и сборка промптов проверялись в ходе итераций; найден и + исправлен пропущенный путь отчёта триажа. +- Посторонние неотслеживаемые скиллы в объём не входят. + +## Следующая сессия + +1. Выбрать одну подходящую задачу с кодом; не создавать искусственный полный + прогон ради проверки скилла. +2. До каждого запуска агента записывать ожидаемую отдельную пользу, после — + сверить её с фактическим вкладом. +3. Измерить только мастерский след: какие полные отчёты или diff всё ещё попали + в его контекст, сколько агентов можно было не запускать. +4. Проверить живые предположения из `references/field-notes.md`: управляемость + ролей и стоимости, `workspace-write`-ревью, сеть и файловый канал. +5. Менять скилл только по фактам прогона; дистиллировать поглощённые уроки. + +## Suggested skills + +- `$codex-subagent-playbook` — провести выбранную задачу с новой оптикой. +- `$writing-great-skills` — проверить, что новые уроки не вернули каркас, + дублирование или осадок. +- `$handoff` — заменить эту записку после следующего содержательного прогона. +- `$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 index 478a633..0e3df2b 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md @@ -1,73 +1,39 @@ # Полевые заметки -Читай этот файл при развитии скилла и при первом прогоне в новой среде. После -боевого прогона записывай только факты, которые меняют процесс. Когда урок -поглощён `SKILL.md` или `roles.md`, сжимай запись до одной строки со ссылкой. +Читай при развитии скилла и первом прогоне в новой среде. Храни здесь только +факты, которые меняют выбор приёма, и живые предположения. Поглощённый урок +сжимай до одной строки с указателем на действующий договор. -## Перенесено из исходного плейбука +## Наблюдения -- Разные семейства моделей находили почти непересекающиеся классы ошибок. - Это аргумент за внешний обзор, но не обязательная часть конвейера. -- Ревьюер без прав на запись хуже проверял гипотезы, когда тестам нужны кэши - и временные артефакты. Рабочая защита: точка отсчёта Git, явный мандат не - менять исходники и сверка дерева после ревью. -- Пустой вердикт сам по себе не доказывает работу ревьюера. Нужны покрытие, - выполненные команды или другие наблюдаемые доказательства. -- Настройки модели, унаследованные от интерактивной сессии, менялись между - запусками. Для управляемой стоимости модель и глубину надо закреплять. -- Критичный отчёт фонового агента мог потеряться после его завершения. - Надёжнее сообщение плюс файл с индексом. -- Ссылка на другой скилл в файле-задаче не проверена как надёжный способ его - включить. Ключевые требования надо дублировать текстом. -- Прямой запуск внешнего Codex зависел от версии песочницы, AppArmor и сети. - Нативный конвейер не должен зависеть от внешнего CLI. +- 2026-07-10 — хост скрыл выбор роли и модели; стоимость осталась + незакреплённой. Исследователь нашёл блокирующий `.gitignore`, но без нужды + запустил полный набор тестов. Вывод поглощён в + [основную оптику](../SKILL.md) и [мандаты](roles.md). +- 2026-07-10 — главной утечкой контекста была повторная передача отчётов и + промптов через мастера. Вывод поглощён в [правила обмена](../SKILL.md) и + [сборку промптов](prompt-templates.md). +- 2026-07-12 — разные семейства ревьюеров пересеклись в двух темах примерно из + восьми и сохранили заметный независимый вклад. Вывод поглощён в + [основную оптику](../SKILL.md). +- 2026-07-12 — самоприменение поймало сломанную сборку с необязательным + `notes.md` и показало, что язык обмена надо задавать явно. Вывод поглощён в + [сборку промптов](prompt-templates.md). +- 2026-07-12 — тот же прогон выявил регрессии производного скилла: второй + ревьюер того же семейства не давал новой родословной; мастер вывел в свой + контекст 44 хэша, полный отчёт и почти весь diff; права ревьюера смешались с + каналом результата; семь буквальных этапов породили лишние проверки. Вывод + поглощён в [основную оптику](../SKILL.md). ## Проверить боем 1. Выбирает ли текущий хост пользовательского агента по имени и показывает ли - фактически использованную модель после запуска новой сессии с TOML. -2. Даёт ли набор быстрых ролей экономию без повторной работы сильной модели. -3. Остаётся ли дерево неизменным после ревьюера с `workspace-write`. + фактически использованную модель после новой сессии с TOML. +2. Даёт ли дешёвая роль экономию без повторной работы сильной модели. +3. Остаётся ли дерево неизменным после ревьюера с `workspace-write` и явным + мандатом не менять исходники. 4. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях. -5. Достаточно ли общего договора возврата, чтобы мастер не открывал сырые - журналы и полные отчёты. -6. Где проходит практический порог между прямой работой и полным конвейером. - -## 2026-07-10 — пробный прогон этапов 1–2 - -- Мастер без истории исходного плейбука поднял исследователя и ревьюера, - свёл их вывод в самодостаточную постановку и не вынес сырые журналы в - итоговый контекст. -- Конкретный tool-backed хост скрыл из схемы `spawn_agent` поля `agent_type`, - `model`, `reasoning_effort` и `service_tier`. Это ограничение той сессии, - а не Codex в целом: актуальная нативная схема поддерживает все четыре поля. - Роли в прогоне были только мандатами в промпте; мастер верно отметил - стоимость той сессии как неуправляемую. -- Исследователь обнаружил блокирующее правило `.gitignore` для будущих TOML, - которое мастер без шумного обхода репозитория мог пропустить. -- Исследователь без необходимости запустил полный набор тестов. Ограничение - «карта команд, а не полный прогон» поглощено в `SKILL.md` и `roles.md`. - -## 2026-07-10 — проверка документации и исходного кода Codex - -- Нативный `spawn_agent` принимает `agent_type`, `model`, - `reasoning_effort` и `service_tier`. -- Полный fork `all` наследует модель мастера и отклоняет роль, модель и - глубину. Плейбук выбирает `none` ради чистого контекста; ограниченный fork - числом технически совместим с переопределениями. -- Хост может намеренно скрыть эти поля из видимой схемы. В такой сессии - мастер не может гарантировать стоимость через нативный вызов. -- TOML-роли остаются правильным способом закрепить модель и глубину. После - их установки нужна новая сессия и проверка фактической схемы инструмента. -- `service_tier` не блокируется полным fork, но задаётся только по явному - запросу. - -## 2026-07-10 — ретро утечки контекста прародителя - -- Главная утечка была не в работе агентов, а в повторной передаче одного - текста через мастера: отчёт, новый промпт, повторная проверка и tool-call. -- Нативный Codex не наследует буквально поведение Claude `SendMessage`, но - длинные аргументы `spawn_agent`, `send_message` и `followup_task` всё равно - остаются в истории мастера. -- Лечение поглощено в `SKILL.md` и `prompt-templates.md`: файловый канал, - один канонический промпт и ожидание только на критическом пути. +5. Достаточно ли файлового канала, чтобы мастер не открывал полный отчёт и + сырые журналы. +6. Когда отдельный проверяющий или вторая линия ревью окупаются лучше + объединения совместимой работы. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md b/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md index da3c567..7a18c25 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md @@ -1,87 +1,88 @@ -# Скелеты нативных промптов +# Сборка нативных промптов -Читай только тот раздел, который нужен на текущем этапе. Полный текст -задания и отчёта живёт в обменном временном каталоге; вызов агента содержит -короткую обёртку с абсолютными путями. +Открывай только раздел выбранного приёма. Это справочник готовых договоров, +а не обязательная последовательность. Постоянный текст живёт в +[prompts/](prompts/): -## Общий договор результата +- [result-contract.md](prompts/result-contract.md) — обычный результат; +- [review-boilerplate.md](prompts/review-boilerplate.md) — слепое ревью; +- [triage-header.md](prompts/triage-header.md) — закрытие находок; +- [recheck-header.md](prompts/recheck-header.md) — узкая перепроверка; +- [runtime-language.md](prompts/runtime-language.md) — язык временного обмена. -Полный отчёт, независимо от канала: +Текст договора меняй только в его авторитетном файле. Здесь остаются выбор и +механика сборки. + +## Канал результата + +Канал выбери по [основной оптике](../SKILL.md). Здесь важна только механика: +для файлового канала задай уникальный `REPORT`, для сообщения не создавай +вторую копию результата. + +## Обычный исполнитель или исследователь + +Параметрический файл содержит только нужные конкретной задаче поля: ```text -ИТОГ: завершено | есть вопросы | заблокировано -ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики -РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь -НАХОДКИ: SEVERITY файл:строка — суть — как проверить -СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет» +GOAL: one verifiable goal +BOUNDARIES: allowed and forbidden work +READ FIRST: paths to contracts and examples +CHECKS: commands this agent should run +REPORT: path, only when the result will be reused ``` -Пустые разделы пропускаются. Сырой вывод и ход рассуждений не включаются. -При файловом канале этот договор заполняется в файле, а финальное сообщение -содержит только `ИТОГ`, счётчики и `АРТЕФАКТ: абсолютный путь`. При -`read-only` договор возвращается один раз сообщением без поля `АРТЕФАКТ`. +Добавь общий результат и язык временного обмена: -## Исполнитель - -Файл задачи должен содержать: - -```text -ЦЕЛЬ: одна проверяемая цель -КРИТЕРИИ: исчерпывающий список -ГРАНИЦЫ: разрешённые и запрещённые изменения -СНАЧАЛА ПРОЧИТАТЬ: пути к контрактам и образцам -ПРОВЕРКИ: узкие команды разработки -ОТЧЁТ: отдельный путь в обменном каталоге +```bash +cat "$D/params.md" "$P/result-contract.md" "$P/runtime-language.md" \ + > "$D/prompt.md" ``` -Короткий вызов: прочитать файл задачи и выполнить буквально. Агент с записью -в обменный каталог сохраняет полный отчёт по заданному пути и финальным -сообщением возвращает состояние, счётчики и путь. `read-only`-агент -возвращает короткий результат один раз сообщением. Коммит не делать. +Самодостаточный файл задачи, критерии и подробное обязательное чтение добавляй +только когда они действительно нужны выбранной работе. -## Слепое ревью +## Свежий ревьюер -Один канонический файл на всех ревьюеров: +Общая часть содержит задачу, изменённый объём и известные проверки. Фокус +содержит только выбранный для этого ревью класс риска. Для одного ревьюера: -```text -АРТЕФАКТ: задача и изменённый объём -ФОКУС: корректность, контракт, краевые случаи, честность тестов -МАНДАТ: исследовать и проверять гипотезы, исходники не исправлять -ФОРМАТ: severity, файл:строка, сценарий сбоя, доказательство, проверка -ВЕРДИКТ: APPROVED | REVISE +```bash +cat "$D/review-common.md" "$D/review-focus.md" \ + "$P/review-boilerplate.md" "$P/runtime-language.md" \ + > "$D/review-prompt.md" ``` -Вызов каждого ревьюера добавляет только его фокус и канал результата: - -- `workspace-write`: уникальный путь файла; финальное сообщение — вердикт, - счётчики по severity и путь; исходники не менять, Git сверить до и после; -- `read-only`: короткий индекс один раз финальным сообщением, без требования - записать файл. +Если осознанно выбраны несколько линий, каждому ревьюеру дай отдельный файл +фокуса и отдельный путь результата. Не создавай вторую линию только ради +симметрии или свежего треда того же семейства. ## Закрытие находок -Исполнителю передаются пути к исходным индексам ревью и такой короткий -мандат: +Передай исполнителю исходные индексы без пересказа. Обязательный +`triage-params.md` задаёт путь полного отчёта и нужные проверки. `notes.md` +добавляй только для новых решений мастера, которых у исполнителя ещё нет: -```text -По каждой находке: исправить, сузить или отклонить через контракт и проверку. -Не менять соседний объём. Полный отчёт решений записать по указанному пути. -Финальным сообщением вернуть счётчики, проверки и путь. +```bash +cat "$P/triage-header.md" "$D/triage-params.md" "$D/review-a.md" \ + > "$D/fix-prompt.md" +if [ -f "$D/review-b.md" ]; then + cat "$D/review-b.md" >> "$D/fix-prompt.md" +fi +if [ -f "$D/notes.md" ]; then + cat "$D/notes.md" >> "$D/fix-prompt.md" +fi +cat "$P/runtime-language.md" >> "$D/fix-prompt.md" ``` -Не переписывай находки в сообщение или новый файл: исходные индексы уже -являются неизменяемым входом. - ## Узкая перепроверка -Прежнему ревьюеру передаются путь к его исходному индексу и путь к отчёту -решений исполнителя: +Используй прежний тред ревьюера. Параметры содержат пути к его исходному +индексу и отчёту решений, а также проверку, если она нужна: -```text -Проверь только прежние находки и новые правки рядом с ними. -По каждой: CLOSED | NOT_CLOSED | REJECTION_VALID | REJECTION_INVALID. -Полный повторный обход не выполнять. +```bash +cat "$P/recheck-header.md" "$D/recheck-params.md" \ + "$P/runtime-language.md" > "$D/recheck-prompt.md" ``` -Финальное сообщение: `ALL_CLOSED` или `ISSUES_REMAIN`, счётчики и путь к -файлу перепроверки. +Не запускай перепроверку автоматически: она нужна для принятых исправлений, +спорного отклонения или дорогой ошибки, а не для закрытия ритуального этапа. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompts/recheck-header.md b/agents/.agents/skills/codex-subagent-playbook/references/prompts/recheck-header.md new file mode 100644 index 0000000..08f8a09 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/recheck-header.md @@ -0,0 +1,14 @@ +# Narrow re-check + +Re-check only your original findings and the changes immediately adjacent to +their resolution. Do not perform a full review. + +For every original finding report `CLOSED`, `NOT_CLOSED`, `REJECTION_VALID`, +or `REJECTION_INVALID`, with concise evidence. If this narrow work exposes a +new adjacent defect, report it in the normal findings format; the scope bound +limits exploration, not honest reporting. + +Return the full re-check through the channel named by the caller. For a file +channel, write it to the supplied path and return only +`RECHECK: ALL_CLOSED | ISSUES_REMAIN`, counters, and `REPORT: `. +For a message channel, return the concise finding statuses once. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompts/result-contract.md b/agents/.agents/skills/codex-subagent-playbook/references/prompts/result-contract.md new file mode 100644 index 0000000..4bb4f8e --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/result-contract.md @@ -0,0 +1,14 @@ +## Result contract + +Write the full result through the channel chosen by the caller: + +- `STATUS: complete | questions | blocked` +- `EVIDENCE:` changed files, executed commands, and final counters +- `DECISIONS:` only questions for the orchestrator or user +- `FINDINGS:` severity, location, essence, and verification method +- `NEXT:` one concrete action or `none` + +Omit empty sections. Do not include raw output or a reasoning narrative. For a +file channel, put the full result in the named file and return only status, +counters, and `REPORT: `. For a message channel, return one +concise result without a report path. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompts/review-boilerplate.md b/agents/.agents/skills/codex-subagent-playbook/references/prompts/review-boilerplate.md new file mode 100644 index 0000000..fe5ca5b --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/review-boilerplate.md @@ -0,0 +1,21 @@ +## Mandate + +- Review and test hypotheses; do not edit source files or persistent + environment state. +- Use the working permissions needed for checks, caches, temporary artifacts, + documentation and primary-source research. The caller verifies Git before + and after the review. +- Do not run `git add`, `git commit`, or commands that discard changes. +- Report only the findings index and verdict through the channel named by the + caller. + +## Findings index + +For each finding: + +`SEVERITY(BLOCKER|MAJOR|MINOR|NIT) | file:line or task section | failure scenario | evidence | how to verify` + +If there are no findings, list the reviewed scope and every executed check or +tested hypothesis with its outcome. A bare no-findings assertion is invalid. + +Final line: `VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUIRED` diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompts/runtime-language.md b/agents/.agents/skills/codex-subagent-playbook/references/prompts/runtime-language.md new file mode 100644 index 0000000..c14d544 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/runtime-language.md @@ -0,0 +1,4 @@ +## Runtime language + +Write every runtime prompt result, report, findings index, and exchange file in +English. Do not infer the output language from the repository or conversation. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompts/triage-header.md b/agents/.agents/skills/codex-subagent-playbook/references/prompts/triage-header.md new file mode 100644 index 0000000..f7658a5 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/triage-header.md @@ -0,0 +1,15 @@ +# Triage blind-review findings + +The review indexes below are immutable input. Process every finding and change +nothing outside their scope. For each finding, either: + +- fix it and name the contract or check that proves closure; or +- reject it with evidence from the contract and a check, never a bare claim. + +Do not commit or stage changes. Propose accepted rejections and residual risks +for the orchestrator to own and record as durable task decisions. The +orchestrator cannot silently accept risk; authority must come from the user or +already be explicit in the task. + +Write a full resolution report to the path supplied by the caller. Return only +status, counters, executed checks, and that path in the final message. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/roles.md b/agents/.agents/skills/codex-subagent-playbook/references/roles.md index 8ad15af..1d0d025 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/roles.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/roles.md @@ -1,7 +1,9 @@ # Уровни и роли Читай этот файл только при настройке ролей или когда нужная роль недоступна. -Сам конвейер описан в `SKILL.md`. +[Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен. +Этот файл — условные настройки мандата, а не список обязательных участников. +Один агент может совмещать совместимую работу; не создавай тред на каждое имя. - [Возможности хоста](#возможности-хоста) - [Выбор уровня](#выбор-уровня) @@ -28,7 +30,8 @@ конфигурации агента. Если способ выбора роли не виден в доступном инструменте, считай стоимость -неуправляемой и отметь это в итоговом отчёте. +неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу +на дополнительные роли без явной пользы. Вызов TOML-роли: @@ -86,7 +89,7 @@ Конкретные названия моделей держи в конфигурации агентов, а не в `SKILL.md`. Так замена модельной линейки не меняет процесс. -## Роли +## Возможные мандаты ### `fast-worker` @@ -128,13 +131,12 @@ корректности, безопасности, контракта и тестов. Каждая находка содержит сценарий сбоя, доказательство, влияние и способ проверки. -Для чистого чтения: `sandbox_mode = "read-only"`. Если ревью требует запуска -инструментов, которые пишут кэш или артефакты, использовать -`workspace-write`, запретить правки исходников мандатом и сверить Git до и -после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и -доступ к документации. Непроверенную внешнюю механику отмечать как гипотезу. -Для длинного или повторно используемого индекса нужен доступ на запись в -обменный каталог; иначе вернуть короткий индекс один раз сообщением. +Для полноценного ревью обычно нужен `sandbox_mode = "workspace-write"`: тесты, +кэши, временные артефакты и исследование не следует урезать ради запрета +правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется +до и после. Доступ к сети проверять отдельно: право записи не гарантирует +поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу. +Канал результата от песочницы не зависит. ### `verifier` @@ -168,6 +170,8 @@ developer_instructions = """ - Держи глубину `1`: субагенты не создают собственное дерево исполнителей. - Оставляй один слот мастеру. -- Параллельно запускай чтение, независимые исследования и слепые ревью. +- Параллельно запускай только работу без конфликтующих входов, команд и + изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а + не ради заполнения свободного слота. - Реализацию и починку одного рабочего дерева выполняй последовательно одним владельцем.