diff --git a/agents/.agents/skills/codex-subagent-playbook/SKILL.md b/agents/.agents/skills/codex-subagent-playbook/SKILL.md index 4f270d7..f24b9f1 100644 --- a/agents/.agents/skills/codex-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/codex-subagent-playbook/SKILL.md @@ -1,132 +1,132 @@ --- name: codex-subagent-playbook -description: Оптика тонкого мастера для одной нетривиальной задачи: субагенты сохраняют контекст и приносят нужную независимость. +description: "Оптика тонкого мастера для одной нетривиальной задачи: исследование, планирование, реализация и независимая проверка через субагентов без поглощения контекста координатора." --- # Тонкий мастер -Это оптика работы, а не обязательный конвейер. Цель — решить одну -нетривиальную задачу, сохранив внимание мастера для цели, ограничений, -решений и рисков. Субагенты нужны результату, а не процессу. - -Тонкий мастер не пустой мастер. Он сам принимает решения, делает дешёвые -точечные проверки и смотрит ключевые артефакты. Исследование, реализацию или -проверку он отдаёт только тогда, когда отдельный контекст даст задаче -конкретное преимущество. +Это оптика, а не обязательный конвейер. Координатор сохраняет внимание для +цели, ограничений, решений, рисков и приёмки. Субагенты выясняют и выполняют; +координатор решает. ## Основная оптика -- Перед каждым запуском ответь: что этот агент добавит — защиту контекста, - свежий взгляд, специализацию, параллельность или отдельную среду проверки? - Если ничего, работай сам или продолжи существующий тред. -- Держи у мастера короткий индекс: цель, ограничения, принятые решения, - риски, вердикты и доказательства, влияющие на следующий шаг. Полные diff, - журналы и нарративы ему не нужны. -- Исследование с неизвестным или шумным объёмом делегируй до погружения. - Одну узкую гипотезу с предсказуемо короткой командой мастер может проверить - сам; если ответа нет, продолжение уходит агенту. -- Свежий тред даёт независимость от исполнителя, но не разнообразие ошибок. - Другое семейство моделей даёт отдельную линию; второй агент того же - семейства оправдан только высоким риском или действительно иным фокусом. -- Выбирай самый дешёвый надёжный уровень для выбранной работы. Если хост не - показывает модель и глубину, считай стоимость незакреплённой и не умножай - совместимые роли без явной пользы. +- Перед запуском агента назови его вклад: защита контекста, свежий взгляд, + специализация, параллельность или отдельная среда. Без вклада работай сам + либо продолжай существующий тред. +- Сам читай верхнеуровневые документы и принимай решения. Исследование кода, + журналов, зависимостей и вариантов с неизвестным объёмом по умолчанию + отдавай субагенту. Самостоятельно проверяй одну узкую гипотезу с коротким + выводом; дальнейшее погружение делегируй. +- Держи у себя цель, ограничения, решения, риски, краткие сводки и пути к + доказательствам. Полезную нагрузку передавай между агентами файлами, не + через контекст координатора. - Один исполнитель владеет изменениями исходников. Его же продолжай для - исправлений; независимую оценку отдавай свежему треду. Права - `workspace-write` сами по себе не делают агента владельцем исходников. - -Внешняя модель полезна как дополнительная линия, когда её родословная и цена -оправданы риском. Процесс не должен от неё зависеть. + обычных исправлений. Если исполнитель не справляется, останови его и дай + свежему более сильному агенту постановку, текущее дерево и файловые отчёты. +- Выбирай модель и уровень рассуждения независимо. Повышай effort, когда + подходящей модели не хватило глубины; повышай модель, когда не хватает + качества суждения. Текущая привязка ролей — в + [уровнях и ролях](references/roles.md). ## Контекст и обмен -- Если результат понадобится следующему агенту, полный отчёт запиши в - уникальный файл временного обменного каталога. Мастеру верни только итог, - счётчики, вопросы-решения и путь. Короткий конечный результат можно вернуть - одним сообщением. -- Канал результата не связан с правами агента. Ревьюеру можно дать рабочие - права для тестов, кэшей, поиска и документации, а запрет менять исходники и - постоянное окружение удерживать мандатом и сверкой Git до и после. -- Не возвращай один полный отчёт одновременно файлом и сообщением. Не - переписывай находки между файлами: передавай исходный путь или собирай новый - промпт механической конкатенацией. -- Не выводи в контекст мастера полную точку отсчёта, diff, перечень хэшей или - сырой журнал. Если дерево грязное или возможны пересечения, порученный - агент либо готовый скрипт сохраняет подробности во временный файл и сообщает - только состояние, счётчики, пересечение с разрешённым объёмом и путь. +`$SCRATCH` — логический общий каталог одного прогона, доступный координатору и +назначенным агентам. Физически это скретчпад сессии, временный каталог ОС либо +гарантированно игнорируемый каталог проекта. В нём живут временные промпты, +отчёты, триаж и перепроверки; это не артефакты проекта. + - Временные обменные файлы веди на английском. Долговечные документы и текст - для пользователя пиши на языке проекта. -- Сообщай пользователю короткий статус на действительно значимых границах, а - не на каждом служебном переходе. Тайм-аут и `idle` не являются результатом. + для партнёра пиши на языке проекта. +- Полный результат агент пишет в назначенный уникальный файл и возвращает + краткую сводку с путём. Не возвращай тот же полный текст сообщением и не + переписывай чужой отчёт: передавай путь или собирай новый файл механически. +- Если общий каталог недоступен, передай через контекст только компактный + индекс. Сразу сообщи партнёру наблюдаемый сбой, использованный запасной + канал и то, что нужно проверить после задачи. +- Права агента не определяют канал результата. Ревьюер может иметь рабочие + права для тестов и временных файлов, но его единственный назначенный + результат — отчёт. Исходники, Git и постоянное окружение он не меняет. -## Когда какой приём полезен +Точные способы сборки файлов и промптов бери из +[нативных шаблонов](references/prompt-templates.md) только после выбора +конкретного приёма. -- **Самодостаточная постановка** нужна, когда исполнитель начинает без истории - разговора или проекту важен долговечный след. Для локальной ясной правки - достаточно короткого мандата. -- **Исследователь** нужен для неизвестного объёма, внешних фактов или шумного - обхода репозитория. Его результат — факты и вопросы, не реализация. -- **Ревью постановки** окупается при скрытых проектных решениях, дорогой ошибке - или критериях, которые можно выполнить формально без нужного результата. -- **Исполнитель** нужен, когда отдельный контекст реализации ценнее прямой - работы мастера. Он не коммитит и не расширяет объём без решения мастера. -- **Проверяющий** нужен для шумных журналов, специальной среды, стенда или - независимого подтверждения команд. Не создавай отдельную роль, если те же - проверки дёшево и надёжно выполняет исполнитель либо ревьюер. -- **Свежий ревьюер** нужен, когда цена пропущенного дефекта выше стоимости - обзора. По умолчанию достаточно одного. Вторую линию добавляй ради другого - семейства моделей или отдельного класса риска, а не ради числа два. +## Выбор приёма -## Типичный ход задачи +- **Самодостаточная постановка** нужна исполнителю без истории разговора и + там, где проекту нужен долговечный след. Для ясной локальной правки хватит + короткого мандата. +- **Исследователь** собирает факты неизвестного объёма. Он возвращает записку + решений и пути к доказательствам, а не реализацию. +- **Deep-reasoner** готовит архитектурное предложение, декомпозицию или + сравнение компромиссов. Итоговое решение остаётся у координатора. Важное + решение полезно проверить двумя слепыми линиями разных семейств. +- **Исполнитель** получает одну цель, границы и критерии. Он не коммитит и не + расширяет объём без решения координатора. +- **Проверяющий** запускает известную проверку в специальной среде или с + шумным выводом. Не создавай роль, если координатор либо исполнитель может + получить тот же надёжный результат дёшево. -Часто полезно уточнить постановку, дать одному исполнителю реализовать её, -проверить обязательные свойства и при заметном риске получить свежий обзор. -Пропускай, объединяй и меняй порядок этих действий, если так надёжнее и -дешевле достигается результат. +### Режимы ревью -- Перед реализацией разреши продуктовые, архитектурные и относящиеся к - границам решения вне мандата исполнителя. Технический способ внутри мандата - оставь ему. -- Пока исполнитель меняет исходники, не запускай другого владельца тех же - файлов. Параллель разрешай для независимых неизменяемых входов, отдельных - worktree или команд без общего изменяемого состояния. -- Обязательные и доступные сквозные проверки должны пройти до финальной - приёмки. Недоступную или падающую проверку нельзя молча превратить в зелёную: - риск принимает пользователь либо полномочие, заранее записанное в задаче. -- Ревьюеру дай задачу, изменённый объём, проверки и один выбранный фокус. Он - исследует и проверяет гипотезы, но не исправляет исходники. Вердикт без - находок должен назвать просмотренный объём и выполненные проверки либо - проверенные гипотезы. -- Находки возвращай тому же исполнителю. Он исправляет или аргументированно - отклоняет их через контракт и проверку. Исходный ревьюер при необходимости - узко проверяет свои находки; новый соседний дефект не скрывает. -- На финале мастер смотрит только решения, остаточные риски, итоговые счётчики - и действительно ключевые артефакты. Полный diff и отчёты читают агенты, - которым поручена их проверка. Коммит делай только по просьбе пользователя. +Для нетривиальной делегируемой постановки один узкий свежий обзор — точка +отсчёта. Пропускай его для ясной ограниченной задачи, если можешь коротко +назвать причину. Сложную, рискованную или архитектурную постановку проверяй +двумя слепыми линиями, когда цена оправдана. -## Нативные договоры +Реализацию проверяй по риску: -Если нужны готовые роли или выбор моделей, прочитай -[уровни и роли](references/roles.md). Если роли не настроены, не имитируй -экономию названиями: честно отметь незакреплённую стоимость. +- тривиальная — саморевью исполнителя; +- обычная — один независимый ревьюер по коду; +- сложная или рискованная — два адверсариальных ревьюера: соответствие задаче + и качество кода. -Когда выбран конкретный приём, возьми только его договор из -[сборки нативных промптов](references/prompt-templates.md). Не загружай все -шаблоны заранее и не переписывай их текст в вызов агента. +Разные семейства моделей предпочтительны: они дают больше разнообразия, чем +два свежих треда одной родословной. Когда внешняя линия технически недоступна, +используй доступных ревьюеров; процесс от неё не зависит. -При развитии скилла или первом прогоне в новой среде прочитай -[полевые заметки](references/field-notes.md) и проверь живые предположения. +Выбрав ревью постановки или реализации, прочитай единый +[договор ревью и триажа](references/review-and-triage.md). Он определяет +владельца триажа, файловый канал, повторные проверки и предохранитель кругов. + +## Приёмка + +Координатор принимает результат, но углубляется в доказательства постепенно: + +1. состав изменений и краткие сводки ревью; +2. отдельные спорные фрагменты; +3. полный diff, только когда его объём ограничен и чтение нужно для решения. + +Доступную детерминированную финальную проверку запускай сам с выводом в файл. +В контекст возьми точную команду, код возврата, итоговые счётчики, имена +упавших тестов и путь к журналу. Зелёный журнал не читай. Красный журнал +направь исполнителю или отдельному разборщику; сам открывай детали, когда они +нужны для решения о границах, риске, среде или смене исполнителя. Если +проверка доступна только проверяющему в специальной среде, явно назови +свидетельство косвенным. + +Перед завершением: + +- сопоставь результат с исходной целью и назови всё неподтверждённое; +- убедись, что выбранная независимая проверка завершена либо риск принят + полномочным решением; +- дай партнёру короткую саморефлексию: что больше всего потратило контекст, + оправдана ли трата, что в следующий раз направить через файл или субагента, + какие отклонения процесса произошли. + +Новый урок для [эмпирики](references/lessons.md) только предложи партнёру. +Правь долговечную эмпирику после его согласия. ## Сбои координации -- Агент завершился без ожидаемого файла: один раз запроси короткий итог в том - же треде; после повторной тишины продолжи свежим агентом от сохранённых - артефактов. -- Агент вернул длинный рассказ в сообщение: попроси повторить ответ индексом и - путём, не переноси рассказ дальше. +- Нет ожидаемого файла: один раз запроси короткий итог в том же треде; после + повторной тишины продолжи свежим агентом от сохранённых артефактов. +- Длинный рассказ пришёл сообщением: попроси повторить ответ сводкой и путём, + не переноси рассказ дальше. - Два исполнителя пересеклись в исходниках: останови их, установи одного - владельца и продолжи от проверенного состояния, не откатывая чужие правки. -- Находки не становятся слабее по раундам: если аргументы исчерпаны, вынеси - пользователю противоречие, риск или неверную границу задачи. + владельца и продолжи от проверенного состояния без отката чужих правок. +- Процесс не сходится: используй точки вмешательства из договора ревью, + объясни партнёру причину, стоимость и принятое решение. - После завершения сохрани только предусмотренные проектом долговечные решения и удали временные артефакты именно этого прогона. 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 index 6538bc1..5712bbd 100644 --- 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 @@ -10,7 +10,7 @@ Codex и проверит полный конвейер на боевой зад - процесс тонкого мастера — [`../SKILL.md`](../SKILL.md); - выбор ролей и уровней — [`../references/roles.md`](../references/roles.md); - перенесённые уроки и открытые проверки — - [`../references/field-notes.md`](../references/field-notes.md); + [`../references/lessons.md`](../references/lessons.md); - точные договоры нативных агентов — [`../references/prompt-templates.md`](../references/prompt-templates.md); - явный вызов скилла — [`../agents/openai.yaml`](../agents/openai.yaml). 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 index 05950b0..024bcda 100644 --- 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 @@ -13,7 +13,7 @@ [`../references/roles.md`](../references/roles.md). Факты двух прогонов и ещё непроверенные предположения дистиллированы в -[`../references/field-notes.md`](../references/field-notes.md). Не переносить +[`../references/lessons.md`](../references/lessons.md). Не переносить их обратно в основной файл без нового наблюдаемого сбоя. Ключевая граница следующей работы: субагент запускается ради конкретной пользы @@ -39,7 +39,7 @@ сверить её с фактическим вкладом. 3. Измерить только мастерский след: какие полные отчёты или diff всё ещё попали в его контекст, сколько агентов можно было не запускать. -4. Проверить живые предположения из `references/field-notes.md`: управляемость +4. Проверить живые предположения из `references/lessons.md`: управляемость ролей и стоимости, `workspace-write`-ревью, сеть и файловый канал. 5. Менять скилл только по фактам прогона; дистиллировать поглощённые уроки. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md b/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md deleted file mode 100644 index 0e3df2b..0000000 --- a/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md +++ /dev/null @@ -1,39 +0,0 @@ -# Полевые заметки - -Читай при развитии скилла и первом прогоне в новой среде. Храни здесь только -факты, которые меняют выбор приёма, и живые предположения. Поглощённый урок -сжимай до одной строки с указателем на действующий договор. - -## Наблюдения - -- 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` и явным - мандатом не менять исходники. -4. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях. -5. Достаточно ли файлового канала, чтобы мастер не открывал полный отчёт и - сырые журналы. -6. Когда отдельный проверяющий или вторая линия ревью окупаются лучше - объединения совместимой работы. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/lessons.md b/agents/.agents/skills/codex-subagent-playbook/references/lessons.md new file mode 100644 index 0000000..d504100 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/lessons.md @@ -0,0 +1,47 @@ +# Эмпирика прогонов + +Храни здесь только датированные факты, которые меняют выбор приёма, и живые +гипотезы. Поглощённый урок сжимай до строки с указателем на действующий +договор. Правь этот долговечный файл только после согласования с партнёром. + +## Наблюдения + +- 2026-07-10 — хост скрыл выбор роли и модели; стоимость осталась + незакреплённой. Исследователь нашёл блокирующий `.gitignore`, но без нужды + запустил полный набор тестов. Вывод поглощён в + [основную оптику](../SKILL.md) и [роли](roles.md). +- 2026-07-10 — главной утечкой контекста была повторная передача отчётов и + промптов через координатора. Вывод поглощён в + [правила обмена](../SKILL.md) и [сборку промптов](prompt-templates.md). +- 2026-07-12 — разные семейства ревьюеров пересеклись в двух темах примерно из + восьми и сохранили заметный независимый вклад. Вывод поглощён в + [договор ревью](review-and-triage.md). +- 2026-07-12 — самоприменение поймало сломанную сборку с необязательным + `notes.md` и показало, что язык обмена надо задавать явно. Вывод поглощён в + [сборку промптов](prompt-templates.md). +- 2026-07-12 — второй ревьюер того же семейства не дал новой родословной; + координатор вывел в свой контекст 44 хэша, полный отчёт и почти весь diff; + права ревьюера смешались с каналом результата; семь буквальных этапов + породили лишние проверки. Вывод поглощён в + [основную оптику](../SKILL.md) и [договор ревью](review-and-triage.md). + +## Проверить боем + +1. Удерживает ли Sol оптику тонкого мастера: что больше всего расходует + контекст координатора и можно ли направить это через файл или субагента. +2. Достаточна ли Luna `medium` для простой ограниченной реализации и + подтверждается ли, что `low` даёт слишком много повторной работы. +3. Окупается ли Terra `medium` на узком обзоре постановки и проверке + реализации по задаче. +4. Сходится ли обычная реализация на Sol `medium`, а сложная — на Sol + `high`, с меньшей общей стоимостью петли. +5. Оправдан ли ручной `xhigh` хоть в одном классе задач; текущая гипотеза — + штатно переходить от `high` сразу к `max` только по сильному триггеру. +6. Остаётся ли дерево неизменным после ревьюера с `workspace-write` и явным + мандатом сохранять результат только в назначенный отчёт. +7. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях. +8. Достаточно ли файлового канала, чтобы координатор не открывал полный + отчёт, diff и сырые журналы. +9. Может ли будущая линия другого семейства читать и писать общий + `$SCRATCH`. Пока адаптер запуска не проверен, он не является действующим + договором. 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 7a18c25..e392fdf 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md @@ -1,88 +1,134 @@ # Сборка нативных промптов -Открывай только раздел выбранного приёма. Это справочник готовых договоров, -а не обязательная последовательность. Постоянный текст живёт в -[prompts/](prompts/): +Это механика после выбора приёма в [основной оптике](../SKILL.md). Смысл +ревью и триажа задаёт [единый договор](review-and-triage.md); здесь только +параметры, файловые пути и сборка. + +Постоянный текст живёт в [prompts/](prompts/): - [result-contract.md](prompts/result-contract.md) — обычный результат; -- [review-boilerplate.md](prompts/review-boilerplate.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`, для сообщения не создавай -вторую копию результата. +`$SCRATCH` определён в основном файле как общий временный каталог. Для задачи +создай уникальную подпапку: `D="$SCRATCH/"`. `P` указывает на +`references/prompts` этого скилла. Каждый агент получает отдельный `REPORT`. -## Обычный исполнитель или исследователь +Собирай файлы механически, не читая полезную нагрузку в контекст координатора. +Примеры ниже используют POSIX `cat`; в PowerShell применяй +`Get-Content | Set-Content -Encoding utf8 `. -Параметрический файл содержит только нужные конкретной задаче поля: +## Исполнитель или исследователь + +`params.md`: ```text 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 +REPORT: absolute unique path ``` -Добавь общий результат и язык временного обмена: - ```bash cat "$D/params.md" "$P/result-contract.md" "$P/runtime-language.md" \ > "$D/prompt.md" ``` -Самодостаточный файл задачи, критерии и подробное обязательное чтение добавляй -только когда они действительно нужны выбранной работе. +Самодостаточную постановку и подробное обязательное чтение добавляй только +когда они нужны выбранной работе. -## Свежий ревьюер +## Ревью постановки или реализации -Общая часть содержит задачу, изменённый объём и известные проверки. Фокус -содержит только выбранный для этого ревью класс риска. Для одного ревьюера: +`review-common.md` одинаков для одного обзора: + +```text +TITLE: short review title +WORKING DIRECTORY: absolute repo path +STATEMENT: task and parent spec paths +SCOPE: changed files or task sections under review +BASELINE: what is explicitly outside this review +CHECKS: commands and expected counters +``` + +`review-output.md` задаёт поля конкретной линии: + +```text +TYPE: spec | task | code +FINDING PREFIX: SPEC-A | SPEC-B | TASK | CODE +REPORT: absolute unique path +``` + +`review-focus.md` задаёт один выбранный фокус. Для постановки: + +```text +Review the task statement, not an implementation. Check facts against code, +hidden one-line decisions, boundaries, checkable acceptance criteria, and +ways to satisfy the wording without the intended result. +``` + +Для реализации выбери task lens или code lens из договора ревью: + +```text +TASK LENS: compare the implementation with the statement, acceptance criteria, +boundaries, and intended observable result. + +CODE LENS: seek correctness bugs, broken invariants, regressions, security +issues, and tests that can pass without proving the behavior. +``` ```bash -cat "$D/review-common.md" "$D/review-focus.md" \ +cat "$D/review-common.md" "$D/review-focus.md" "$D/review-output.md" \ "$P/review-boilerplate.md" "$P/runtime-language.md" \ > "$D/review-prompt.md" ``` -Если осознанно выбраны несколько линий, каждому ревьюеру дай отдельный файл -фокуса и отдельный путь результата. Не создавай вторую линию только ради -симметрии или свежего треда того же семейства. +Для двух слепых линий создай `review-focus-a.md` и `review-focus-b.md`, +`review-output-a.md` и `review-output-b.md` со своими `TYPE`, уникальными +`FINDING PREFIX` и разными путями `REPORT`. `review-common.md` используй один; +отчёты и финальные сообщения линий не объединяй до их завершения. -## Закрытие находок +## Триаж постановки -Передай исполнителю исходные индексы без пересказа. Обязательный -`triage-params.md` задаёт путь полного отчёта и нужные проверки. `notes.md` -добавляй только для новых решений мастера, которых у исполнителя ещё нет: +Координатор читает краткие строки и нужные подробности, принимает решение по +каждому `SPEC-*` и обновляет постановку. Резолюции сохраняет в +`spec-resolutions.md`; этот файл и новая постановка идут исходному ревьюеру +на узкую перепроверку. + +## Триаж реализации + +Передай исполнителю исходные отчёты без пересказа. `triage-params.md` +содержит путь итогового отчёта и проверки. `coordinator-notes.md` добавляй +только для совпадений, противоречий и новых решений уровня задачи. ```bash -cat "$P/triage-header.md" "$D/triage-params.md" "$D/review-a.md" \ - > "$D/fix-prompt.md" +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" +if [ -f "$D/coordinator-notes.md" ]; then + cat "$D/coordinator-notes.md" >> "$D/fix-prompt.md" fi cat "$P/runtime-language.md" >> "$D/fix-prompt.md" ``` ## Узкая перепроверка -Используй прежний тред ревьюера. Параметры содержат пути к его исходному -индексу и отчёту решений, а также проверку, если она нужна: +Продолжай исходный тред ревьюера. `recheck-params.md` задаёт пути к его +исходному отчёту и файлу резолюций, нужную проверку и новый уникальный +`REPORT`. ```bash cat "$P/recheck-header.md" "$D/recheck-params.md" \ "$P/runtime-language.md" > "$D/recheck-prompt.md" ``` -Не запускай перепроверку автоматически: она нужна для принятых исправлений, -спорного отклонения или дорогой ошибки, а не для закрытия ритуального этапа. +Перепроверка следует решению координатора по договору ревью, а не номеру этапа. 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 index 08f8a09..5cb0c09 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompts/recheck-header.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/recheck-header.md @@ -1,14 +1,17 @@ # Narrow re-check -Re-check only your original findings and the changes immediately adjacent to +Read your original report and the resolution report supplied by the caller. +Re-check only your original findings and 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. +For every original ID report `CLOSED`, `NOT_CLOSED`, `REJECTION_VALID`, +or `REJECTION_INVALID`, with concise evidence. Report a newly exposed +adjacent defect with a new stable ID; the narrow scope 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. +Write the detailed re-check to REPORT. Return only: + +- `VERDICT: APPROVED | CHANGES_REQUESTED`; +- status counters; +- one line per original or new ID: `ID | status | one-phrase essence`; +- `REPORT: `. 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 index 4bb4f8e..7ca109d 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompts/result-contract.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/result-contract.md @@ -4,7 +4,7 @@ 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 +- `DECISIONS:` only questions for the coordinator or partner - `FINDINGS:` severity, location, essence, and verification method - `NEXT:` one concrete action or `none` 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 index fe5ca5b..f8c2b8f 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompts/review-boilerplate.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/review-boilerplate.md @@ -1,21 +1,30 @@ ## Mandate -- Review and test hypotheses; do not edit source files or persistent - environment state. +- Review independently and test hypotheses. Do not edit source files, + persistent environment state, or Git. - 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. + documentation, and primary-source research. +- Write the detailed report only to REPORT. This assigned exchange file is the + sole write exception to the observer mandate. +- Treat another agent's claims as untrusted until evidence supports them. -## Findings index +## Detailed report -For each finding: +Use stable IDs with FINDING PREFIX: -`SEVERITY(BLOCKER|MAJOR|MINOR|NIT) | file:line or task section | failure scenario | evidence | how to verify` +`PREFIX-N | BLOCKER|MAJOR|MINOR|NIT | file:line or task section | violated +criterion | failure scenario | evidence | minimal verification` -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. +If there are no findings, record the reviewed scope and every executed check +or tested hypothesis with its outcome. A bare approval is invalid. -Final line: `VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUIRED` +## Final message + +Return only: + +- `VERDICT: APPROVED | CHANGES_REQUESTED` +- severity counters; +- one line per finding: `ID | severity | area | one-phrase essence`; +- `REPORT: `. + +Do not repeat the detailed report or reasoning narrative in the final message. 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 index f7658a5..8f1b721 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompts/triage-header.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompts/triage-header.md @@ -1,15 +1,17 @@ -# Triage blind-review findings +# Triage independent-review findings -The review indexes below are immutable input. Process every finding and change -nothing outside their scope. For each finding, either: +The review reports below are immutable input. Process every stable finding ID +and change nothing outside their scope. Assign exactly one disposition: -- 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. +- `FIXED`: change it and name the contract or check that proves closure; +- `REJECTED`: cite the contract and a check, never a bare claim; +- `OUT_OF_SCOPE`: explain the boundary decision needed; +- `NEEDS_DECISION`: state the unresolved product, architecture, or risk choice. -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. +Do not commit, stage, or rewrite the source reports. Write detailed resolutions +to REPORT. Return only: -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. +- overall status and disposition counters; +- one line per finding: `ID | disposition | one-phrase essence`; +- questions for the coordinator and executed-check counters; +- `REPORT: `. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/review-and-triage.md b/agents/.agents/skills/codex-subagent-playbook/references/review-and-triage.md new file mode 100644 index 0000000..c04460e --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/review-and-triage.md @@ -0,0 +1,144 @@ +# Ревью и триаж + +Читай этот файл целиком после выбора независимого ревью постановки или +реализации. Режим и стоимость выбираются в [основной оптике](../SKILL.md); +здесь один авторитетный договор выполнения. + +- [Независимость и фокус](#независимость-и-фокус) +- [Файловый маршрут](#файловый-маршрут) +- [Отчёт ревьюера](#отчёт-ревьюера) +- [Владелец триажа](#владелец-триажа) +- [Перепроверка и круги](#перепроверка-и-круги) +- [Что читает координатор](#что-читает-координатор) + +## Независимость и фокус + +Запускай ревьюера свежей сессией без истории исполнителя и других ревьюеров. +Повторную проверку точечных исправлений продолжает тот же ревьюер: его контекст +находок полезен и не отменяет независимость исходного обзора. + +Для двойного ревью разделяй фокусы: + +- **по задаче** — соответствие постановке, критериям, границам и ожидаемому + результату; +- **по коду** — корректность, межмодульные инварианты, регрессии, безопасность + и честность тестов. + +Давай обоим общую постановку и изменённый объём, но отдельный файл фокуса и +отдельный путь отчёта. Они не знают о второй линии до завершения исходных +обзоров. Разные семейства моделей предпочтительны; две доступные линии одного +семейства всё равно полезны на сложной задаче, если их фокусы различаются. + +Ревьюер — наблюдатель с нужными инструментами. Он может читать код, запускать +тесты, проверять гипотезы, создавать временные кэши и писать назначенный файл +отчёта. Исходники, постоянное окружение и Git он не меняет. Координатор +сверяет состояние дерева до и после. + +## Файловый маршрут + +Назначь каждому участнику уникальные файлы в каталоге задачи внутри +`$SCRATCH`. Временные промпты и отчёты веди на английском. + +```text +reviewer -> detailed report file -> triage owner + | + +-> short summary -> coordinator +``` + +Ревьюер сам пишет полный отчёт в назначенный файл. Координатор не принимает +полный отчёт сообщением и не переписывает его перед передачей. Владелец +триажа читает исходные отчёты напрямую и пишет подробные резолюции в следующий +файл. + +Если общий каталог недоступен, верни через контекст компактный индекс без +нарратива. Координатор сразу сообщает партнёру, какой агент не получил доступ, +к какому пути, какой запасной канал использован и что нужно проверить после +задачи. Сбой канала ухудшает экономию контекста, но не отменяет ревью. + +## Отчёт ревьюера + +Каждая находка получает устойчивый идентификатор с уникальным префиксом +линии: `SPEC-A-N` и `SPEC-B-N` для постановки, `TASK-N` для соответствия +реализации задаче и `CODE-N` для качества кода. Полный файл содержит: + +- идентификатор, тяжесть и `файл:строка` либо раздел постановки; +- нарушенный критерий; +- сценарий сбоя и доказательство; +- минимальный способ проверки. + +В сообщение координатору верни только: + +- `VERDICT: APPROVED | CHANGES_REQUESTED`; +- счётчики по тяжести; +- по одной строке на находку: идентификатор, область, суть и тяжесть; +- абсолютный путь к полному отчёту. + +При отсутствии находок полный файл перечисляет просмотренный объём и +выполненные проверки. Голая строка `APPROVED` без подтверждения работы не +засчитывается. + +## Владелец триажа + +**Постановка.** Координатор принимает или отклоняет каждую находку, потому что +цель, границы и критерии — его решения. Открытое техническое исследование он +может отдать deep-reasoner, но сам читает верхнеуровневые документы и итоговую +постановку. Продуктовый выбор и принятие риска выносит партнёру. + +**Реализация.** Пофиндинговый триаж делает исполнитель, у которого есть +контекст кода. Координатор передаёт оба исходных отчёта без изменений и +добавляет отдельную короткую шапку: совпадения, противоречия и возможный выход +за границы. Он не сливает и не удаляет «дубликаты». + +Для каждого идентификатора исполнитель возвращает один статус: + +- `FIXED` — исправлено и названо доказательство; +- `REJECTED` — отклонено через контракт и проверку; +- `OUT_OF_SCOPE` — требует отдельного решения о границах; +- `NEEDS_DECISION` — технического решения недостаточно. + +Подробности остаются в файле триажа. Координатор получает по одной компактной +строке `ID | status | essence` на находку, счётчики, вопросы уровня задачи и +путь. Риск и выход за границы решает координатор; техническую истинность +находки — исполнитель и ревьюер. + +## Перепроверка и круги + +Один круг — назначенные обзоры, триаж его владельца и узкая перепроверка. +Исходный ревьюер читает свой отчёт и файл резолюций, проверяет только свои +находки и соседние изменения. Выбранное независимое ревью закрывается +`APPROVED` либо явным принятием риска полномочным координатором или партнёром. +Координатор получает по одной компактной строке со статусом каждого исходного +или нового идентификатора; подробности остаются в файле перепроверки. + +Повторно поднятое аргументированно отклонённое замечание пометь как спор и +отправь на отдельную узкую проверку усиленного уровня. Полный новый обзор +нужен, когда реализация широко изменилась, исходный отчёт слаб или требуется +новая независимая линия. + +Третий круг — точка вмешательства: сообщи партнёру, почему процесс не сходится, +какова стоимость и что меняешь. Координатор может уточнить постановку, +повысить модель или effort, заменить исполнителя свежим сильным агентом, +разделить задачу, назначить усиленный гейт либо принять риск в пределах +мандата. + +Пятый круг не начинай автоматически. Сначала прими явное решение и объясни его +партнёру; если полномочий недостаточно, остановись и запроси решение. Это +предохранитель от дорогой вложенной петли, а не запрет координатору управлять +работой. + +## Что читает координатор + +Краткие строки находок нужны координатору для сравнения линий. Подробный файл +открывай, когда находка меняет границы или риск, ревьюеры противоречат друг +другу, возник спор, сводка непонятна либо без деталей нельзя выбрать следующий +шаг. + +Для обычной починки координатор видит переход: + +```text +CHANGES_REQUESTED -> triaged -> rechecked -> APPROVED +``` + +Полный diff, доказательства и журналы читают назначенные агенты. Координатор +углубляется в них по правилам приёмки основной оптики, когда это нужно для его +собственного решения. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/roles.md b/agents/.agents/skills/codex-subagent-playbook/references/roles.md index 1d0d025..edf0720 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/roles.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/roles.md @@ -1,5 +1,8 @@ # Уровни и роли +Маршрутизация моделей обновлена 2026-07-13. Имена и уровни здесь — датированная +настройка среды; логика [основной оптики](../SKILL.md) остаётся относительной. + Читай этот файл только при настройке ролей или когда нужная роль недоступна. [Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен. Этот файл — условные настройки мандата, а не список обязательных участников. @@ -7,6 +10,7 @@ - [Возможности хоста](#возможности-хоста) - [Выбор уровня](#выбор-уровня) +- [Текущая маршрутизация](#текущая-маршрутизация) - [Роли](#роли) - [Файл пользовательского агента](#файл-пользовательского-агента) - [Пределы параллельности](#пределы-параллельности) @@ -23,7 +27,7 @@ `reasoning_effort` без пользовательской роли с закреплённой моделью. Плейбук использует `fork_turns="none"` ради чистого контекста. Технически ограниченный fork числом тоже допускает переопределения; только полный - fork `all` наследует модель мастера и отклоняет их. + fork `all` наследует модель координатора и отклоняет их. - **Неуправляемая стоимость.** Интерфейс запуска принимает только задачу и имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана дешёвая или сильная модель. `task_name` — идентификатор треда, а не выбор @@ -69,25 +73,40 @@ | Уровень | Для чего | Настройка | |---|---|---| -| Быстрый | Поиск, чтение журналов, тесты, пакетная механика | Быстрая дешёвая модель, `low` или `medium` | -| Рабочий | Обычная реализация по ясной постановке | Сильная модель для кода, `medium` или `high` | -| Глубокий | Архитектура, сложная диагностика, ревью высокого риска | Самая сильная доступная модель, `high` или выше | +| Быстрый | Поиск, журналы, известные проверки, ограниченная механика | Дешёвая подходящая модель, обычно `medium` | +| Рабочий | Обычная реализация и проверка по задаче | Подходящая ролевая модель, `medium` | +| Глубокий | Архитектура, сложная реализация, ревью кода | Сильная модель, `high` | +| Исключительный | Необратимое решение или несходимость сильных агентов | Самая сильная модель, `max` | -Начинай с самого дешёвого подходящего уровня. Повышай уровень, когда агент -не может проверить предположение, дважды возвращает слабый результат или -задача требует решения с высокой ценой ошибки. Не повышай уровень ради -объёма механической работы: дели её на независимые части. +Модель задаёт потолок способности, effort — глубину работы этой модели. +Повышай effort, когда подходящей модели не хватило поиска или рассуждения. +Повышай модель, когда не хватает качества решения. После двух слабых +результатов замени исполнителя свежим более сильным агентом вместо переноса +его неудачного контекста. -- `low`/`medium`: детерминированная механика, поиск и известные проверки. -- `medium`/`high`: реализация по ясному контракту, несколько связанных - файлов, нет необратимых решений. -- `high`: публичный контракт, безопасность, целостность данных, конкуренция, - миграция или неоднозначная архитектура. -- `xhigh` и выше: необратимый дорогой выбор либо повторное противоречие - сильных агентов. Это исключение, а не обычный режим ревью. +`xhigh` не является автоматической ступенью: текущая эмпирика показывает +малый прирост относительно `high` при заметной цене. Выбирай его вручную для +узкой задачи. `max` заметно сильнее и дороже; используй по явному триггеру и +объясняй партнёру причину. -Конкретные названия моделей держи в конфигурации агентов, а не в `SKILL.md`. -Так замена модельной линейки не меняет процесс. +## Текущая маршрутизация + +Это начальная рабочая таблица, а не рейтинг моделей. Проверяй её на прогонах и +меняй после согласования эмпирики с партнёром. + +| Роль | Модель и effort | +|---|---| +| Простая ограниченная реализация, `fast-worker`, известная проверка | Luna `medium` | +| Узкий обзор постановки, проверка реализации по задаче | Terra `medium` | +| Обычная нетривиальная реализация | Sol `medium` | +| Сложная или рискованная реализация | Sol `high` | +| `deep-reasoner`: архитектурное предложение, декомпозиция, компромиссы | Sol `high` | +| Ревью кода | Sol `high` | +| Необратимое решение, спор сильных агентов, повторная несходимость | Sol `max` | + +Официальное назначение текущих уровней семейства — в +[каталоге моделей OpenAI](https://developers.openai.com/api/docs/models). +Конкретные имена держи здесь и в конфигурации агентов, а не в `SKILL.md`. ## Возможные мандаты @@ -104,7 +123,7 @@ Уровень: быстрый. Строит карту кода, находит точки входа, контракты и команды проверки. Не запускает полный набор тестов и не проектирует решение, пока -мастер прямо не попросит. Узкую команду запускает только для проверки факта, +координатор прямо не попросит. Узкую команду запускает только для проверки факта, без которого карта ненадёжна. Обычно: `sandbox_mode = "read-only"`. @@ -120,8 +139,8 @@ ### `deep-reasoner` Уровень: глубокий. Принимает одно сложное решение: архитектура, алгоритм, -диагноз, противоречие требований. Возвращает рекомендацию, ключевые доводы и -непроверенные предположения. +диагноз, противоречие требований. Возвращает предложение, ключевые доводы и +непроверенные предположения; итоговое решение принимает координатор. Обычно: `sandbox_mode = "read-only"`. @@ -136,7 +155,9 @@ правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется до и после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу. -Канал результата от песочницы не зависит. +Канал результата от песочницы не зависит. При выбранном ревью используй +[единый договор](review-and-triage.md): назначенный файл отчёта — единственный +результат наблюдателя; временные кэши допустимы, исходники и Git неизменны. ### `verifier` @@ -169,7 +190,7 @@ developer_instructions = """ ## Пределы параллельности - Держи глубину `1`: субагенты не создают собственное дерево исполнителей. -- Оставляй один слот мастеру. +- Оставляй один слот координатору. - Параллельно запускай только работу без конфликтующих входов, команд и изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а не ради заполнения свободного слота.