diff --git a/.scratch/codex-subagent-playbook/validation.md b/.scratch/codex-subagent-playbook/validation.md new file mode 100644 index 0000000..3aa6132 --- /dev/null +++ b/.scratch/codex-subagent-playbook/validation.md @@ -0,0 +1,67 @@ +# Проверка переработанного плейбука + +Дата: 2026-09-06. Спецификация зафиксирована коммитом `65c802f`. + +## Что проверено + +Основной текст и справочники сверены с принятой спецификацией. Astra сохраняет +замысел и приемку, Sol ведет реализацию и технический триаж, Luna выполняет +ограниченную механику. Выбор ревью и канала обмена остается ситуативным. +Механики Claude больше не требуют чтения его отдельного плейбука. + +Детерминированные проверки прошли: + +- `git diff --check`; +- 46 относительных Markdown-ссылок, включая 8 ссылок с якорями; +- разбор YAML, длина `short_description`, наличие имени скилла в подсказке; +- сохранение явного включения: `disable-model-invocation: true` и + `allow_implicit_invocation: false`. + +Штатный `quick_validate.py` не знает существующее поле +`disable-model-invocation` и отклоняет исходник. На временной копии с удалением +только этого поля он возвращает `Skill is valid!`. Исходное поле сохранено для +мостов между инструментами; успешная проверка копии не выдается за успешную +прямую проверку исходника. + +## Поведение и независимое ревью + +Свежая Astra получила изолированную задачу с настоящим дефектом и спорными +находками ревью. Она исправила обработку нулевого приоритета, добавила +регрессионную проверку, отклонила ненужное усиление безопасности и вынесла +расширение архитектуры за границы задачи. Координатор подтвердил сохранение +границ. Проверка нового случая сначала падала, после исправления все три теста +прошли; координатор повторил их. Это один ограниченный сценарий, а не оценка +общей эффективности скилла. Независимой перепроверки кода этого примера не было. + +Реализацию скилла проверил Claude CLI с `--permission-mode auto`. Метаданные +подтвердили `claude-opus-5` и `high`. Пользователь явно разрешил передачу diff и +фрагментов кода этому каналу ревью; после этого автоматическая проверка +разрешила ранее отклоненный запуск. + +Из девяти находок Claude восемь исправлены. Требование удалить исторические +заметки отклонено: они не входят в обязательное чтение и не задают текущую +механику. Дополнительно исправлена находка координатора: отклонение чрезмерного +способа починки не закрывает подтвержденный дефект. + +Узкая перепроверка в продолжении контекста исходного ревью дала `APPROVED`: +8 `CLOSED`, 1 `REJECTION_VALID`, без новых дефектов и `OVERREACH`. +Хеши всех 15 файлов до и после обоих обзоров совпали. + +## Проверка запуска + +Схема нативных инструментов подтверждает выбор модели, глубины и истории. +Полная история наследует модель и глубину; явные переопределения требуют +свежего или ограниченного контекста. Принятый параметр сам по себе не доказывает +фактически примененную глубину рассуждения. + +Claude CLI 2.1.263 показал дополнительную особенность: повторное задание +параметров при `--resume` создает копию даже завершенной сессии. Поэтому первая +перепроверка продолжила историю в копии. Пример в справочнике исправлен на +`claude --bg --resume "<поручение>"` без переопределений. +Следующий запуск подтвердил тот же идентификатор и сохраненные настройки +доступа, модели и глубины. Ревьюер отдельно одобрил эту последнюю поправку; +хеши исходников после проверки не изменились. + +Исторические handoffs, `lessons.md`, принятая спецификация и посторонние +неотслеживаемые каталоги не изменены. Временные отчеты и пробный код оставлены +в `/tmp/codex-playbook-refactor.dW8ZC3`; они не являются частью скилла. diff --git a/agents/.agents/skills/codex-subagent-playbook/SKILL.md b/agents/.agents/skills/codex-subagent-playbook/SKILL.md index 447f5f9..585a82d 100644 --- a/agents/.agents/skills/codex-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/codex-subagent-playbook/SKILL.md @@ -1,207 +1,89 @@ --- name: codex-subagent-playbook disable-model-invocation: true -description: "Оптика тонкого мастера для координатора на стороне Codex: Codex-специфика поверх базовых механик claude-subagent-playbook, плюс запуск Claude-субагентов. Со стороны Claude Code используй claude-subagent-playbook." +description: "Оптика Astra-координатора: делегирование, защита контекста и осмысленное ревью." --- -# Тонкий мастер +# Координатор задачи -Это оптика, а не обязательный конвейер. Координатор сохраняет внимание для -цели, ограничений, решений, рисков и приёмки. Субагенты выясняют и выполняют; -координатор решает. +Ты ведешь задачу как Astra: держишь замысел, выбираешь подход и принимаешь +результат. Sol берет основную реализацию, Luna - понятную механику. Этот +скилл добавляет оптику управления. Выбирай полезные приемы по текущему +состоянию задачи; его подключение посреди работы не обнуляет сделанное. -## Базовый плейбук +## Где нужно твое суждение -Механики конвейера живут в соседнем `claude-subagent-playbook` -(`../claude-subagent-playbook/SKILL.md`) — при развёртывании конвейера -прочитай его и бери оттуда: этапы от постановки до финала, «одно ревью на -версию артефакта», назначение ревью-линий по семействам и вкусу, триаж -находок у исполнителя, предохранитель кругов. Он написан для оркестратора на -стороне Claude Code: его харнесс-механику (Agent-тул, `codex exec`) заменяй -нативными средствами Codex и разделом «Запуск Claude-субагентов» ниже. В -общих механиках конвейера при расхождении побеждает базовый; Codex-специфика -этого файла — запуск Claude и назначение моделей линиям — действует как -записано здесь, даже где расходится с картой ролей базового. +Сохраняй цель пользователя, существенные ограничения и основания выбранного +подхода. В постановке объясняй, почему решения достаточны для этой задачи: +одни формальные критерии оставляют исполнителю возможность потерять смысл. +Локальные технические решения принадлежат исполнителю. Изменение границ, +новые обязательства или существенное усложнение требуют твоего суждения. -## Основная оптика +Читай ключевые фрагменты, когда без них нельзя оценить устройство решения, +спорную находку или риск. Краткая сводка полезна, пока дает основания для +решения. Если их нет, раскрой нужное доказательство; исследование неизвестного +объема поручай агенту с конкретным вопросом. -- Перед запуском агента назови его вклад: защита контекста, свежий взгляд, - специализация, параллельность или отдельная среда. Без вклада работай сам - либо продолжай существующий тред. -- Сам читай верхнеуровневые документы и принимай решения. Исследование кода, - журналов, зависимостей и вариантов с неизвестным объёмом по умолчанию - отдавай субагенту. Самостоятельно проверяй одну узкую гипотезу с коротким - выводом; дальнейшее погружение делегируй. -- Держи у себя цель, ограничения, решения, риски, краткие сводки и пути к - доказательствам. Полезную нагрузку передавай между агентами файлами, не - через контекст координатора. -- Один исполнитель владеет изменениями исходников. Его же продолжай для - обычных исправлений. Если исполнитель не справляется, останови его и дай - свежему более сильному агенту постановку, текущее дерево и файловые отчёты. -- Выбирай модель и уровень рассуждения независимо. Повышай effort, когда - подходящей модели не хватило глубины; повышай модель, когда не хватает - качества суждения. Текущая привязка ролей — в - [уровнях и ролях](references/roles.md). +## Где беречь внимание -## Контекст и обмен +Делегирование должно давать понятную пользу: разгрузить контекст, добавить +свежий взгляд, нужную специализацию или независимую работу в параллель. +Продолжай существующего исполнителя, пока полезен его контекст. Отдельный +агент оправдан вкладом в задачу, а не наличием свободного слота. -`$SCRATCH` — логический общий каталог одного прогона, доступный координатору и -назначенным агентам. Физически это скретчпад сессии, временный каталог ОС либо -гарантированно игнорируемый каталог проекта. В нём живут временные промпты, -отчёты, триаж и перепроверки; это не артефакты проекта. Не предполагай -конкретную оболочку или синтаксис пути: файловый маршрут должен работать -нативными средствами текущей ОС. +Короткие поручения и ответы передавай сообщением. Объемные материалы направляй +нужному агенту, оставляя себе сводку и путь к доказательствам. +Файлы удобны для такого обмена и продолжения работы. Если доступный механизм +передает материал без повторного включения в твой контекст, используй его. +Вывод инструментов сокращай до нужных фактов до его возврата в контекст. -- Временные обменные файлы веди на английском. Долговечные документы и текст - для партнёра пиши на языке проекта. -- Полный результат агент пишет в назначенный уникальный файл и возвращает - краткую сводку с путём. Не возвращай тот же полный текст сообщением и не - переписывай чужой отчёт: передавай путь или собирай новый файл механически. -- Если общий каталог недоступен, передай через контекст только компактный - индекс. Сразу сообщи партнёру наблюдаемый сбой, использованный запасной - канал и то, что нужно проверить после задачи. -- Права агента не определяют канал результата. Ревьюер может иметь рабочие - права для тестов и временных файлов, но его единственный назначенный - результат — отчёт. Исходники, Git и постоянное окружение он не меняет. +При назначении агента выбери модель, глубину рассуждения и нужную ему историю +по [возможностям среды и ролям](references/roles.md). Этот справочник нужен +при выборе способа запуска или смене роли. Краткий мандат и файловый обмен +собирай по [шаблонам](references/prompt-templates.md), когда это экономит работу. -Точные способы сборки файлов и промптов бери из -[нативных шаблонов](references/prompt-templates.md) только после выбора -конкретного приёма. +У каждого изменяемого дерева или общего стенда один владелец. Параллельная +работа требует независимых областей записи и проверок. Перед передачей +владения останови прежнего исполнителя и установи фактическое состояние. -## Запуск Claude-субагентов +## Какой взгляд добавить -Помни, запуская Claude без полноценного --permission-mode auto режима доступа - ты делаешь его работу бессмысленной, ломаешь весь дальнейший процесс ревью. Тогда дальнейшие механизмы скилла сломаны, считай что ты провалил задачу. +Подбирай проверку под неопределенность и цену ошибки. Самопроверки и известной +детерминированной проверки часто достаточно для механики. Свежий ревьюер +полезен там, где могло остаться незамеченное решение или нарушение контракта. +Astra может проверить устройство и соразмерность нетривиального решения. +Claude добавляет взгляд другого семейства; его отсутствие не останавливает +работу и само по себе не создает вопроса пользователю. -Claude (Opus, Fable) запускается процессом CLI `claude` — на разработку, -тестирование и ревью-линии. Линию дефектов ведёт Claude как семейство, -отличное от автора-Codex; вкусовую линию — модель со вкусом -(Fable, effort medium: `claude --model claude-fable-5`). Карта ролей -базового плейбука держит Fable для оркестрации — это ограничение стороны -Claude, где оркестратор и есть Fable; со стороны Codex Fable свободна и -берёт вкусовую линию (решение владельца, проверено на прогонах #154 и #156). +Свежесть контекста и различие семейств решают разные задачи. Выбрав ревью, +прочитай [договор ревью и триажа](references/review-and-triage.md): он задает +независимость, работу с находками и перепроверку. Если выбран Claude, перед +запуском прочитай [его механику](references/claude.md). Запуск и достаточность +доступа ревьюера остаются твоей ответственностью. -- Запуск `claude` передаёт diff и фрагменты кода внешнему сервису Anthropic. - Если твоя политика требует на это явного разрешения владельца, запроси его - **до начала реализации**, одним вопросом на весь прогон: вопрос в момент - ревью останавливает конвейер на самом дорогом участке. -- Запускай с `--permission-mode auto`: иначе Claude не может искать - информацию в интернете и запускать тесты. -- Первое ревью линии — свежая сессия; повторные ревью — продолжением той же - сессии: контекст первого ревью дешевле нового. -- Длительные задачи — через `--bg`, чтобы тайм-аут одного вызова клиента не - завершал работу. Состояние смотри `claude agents`, содержание — - `claude logs `, примерно раз в 5–10 минут. Это частота наблюдения, а не - лимит времени: процесс жив и в журнале есть прогресс — оставь работать, - Claude может выполнять задачу значительно дольше. `--max-turns` — не ручка - ограничения времени. -- Тайм-аут отдельного запроса — не потеря сессии: продолжай через - `--resume `, это быстрее и дешевле, чем начинать заново. -- Прямолинейные суждения бери агентом `craftsman`, сложные решения и - высокоответственные ревью — `deep-reasoner`; карта «роль → модель и - ступень» — в базовом плейбуке, `references/claude-agents.md`. +Ревью возвращает утверждения для проверки. Исполнитель разбирает техническую +сторону находок; ты отвечаешь за уместность изменений и сохранение замысла. +Особенно внимательно смотри на исправления, которые добавляют сложность: +предписание ревьюера само по себе ее не оправдывает. Разбор всех находок - +часть выбранного ревью, даже когда отдельного этапа в плане нет. -## Выбор приёма +## Достаточно ли сделанного -- **Самодостаточная постановка** нужна исполнителю без истории разговора и - там, где проекту нужен долговечный след. Для ясной локальной правки хватит - короткого мандата. -- **Исследователь** собирает факты неизвестного объёма. Он возвращает записку - решений и пути к доказательствам, а не реализацию. -- **Deep-reasoner** готовит архитектурное предложение, декомпозицию или - сравнение компромиссов. Итоговое решение остаётся у координатора. Важное - решение полезно проверить двумя слепыми линиями разных семейств. -- **Исполнитель** получает одну цель, границы и критерии. Он не коммитит и не - расширяет объём без решения координатора. -- **Проверяющий** запускает известную проверку в специальной среде или с - шумным выводом. Не создавай роль, если координатор либо исполнитель может - получить тот же надёжный результат дёшево. +Сопоставь результат с исходной целью и фактическими проверками. Отчет агента +о тестах или состоянии среды оценивай по доказательствам; ключевое для +приемки проверь доступным тебе способом. Новая проверка нужна, когда она +разрешит оставшееся сомнение или проверит последующие изменения. -### Режимы ревью +После нескольких исправлений полезен проход на вычитание: какие добавления +все еще оправданы задачей? Решение об удалении принимай по нужному поведению +и стоимости поддержки. Исполнитель вносит выбранные изменения, затронутая +часть снова получает подходящую проверку. -Для нетривиальной делегируемой постановки один узкий свежий обзор — точка -отсчёта. Пропускай его для ясной ограниченной задачи, если можешь коротко -назвать причину. Сложную, рискованную или архитектурную постановку проверяй -двумя слепыми линиями, когда цена оправдана. +Когда спор повторяется без новых фактов, исправления разрастаются или новый +обзор мало что дает, пересмотри подход. Разбор несходимости находится в +[договоре триажа](references/review-and-triage.md#когда-работа-не-сходится). -Одно ревью на версию артефакта, а не на каждую передачу из рук в руки: -принятый и не изменившийся артефакт заново не ревьюится, после правок — -узкая проверка дельты тем же ревьюером. - -Перед внешними линиями — саморевью исполнителя тем же тредом: он проходит -свои изменения против критериев как ревьюер и сам чинит найденное; -координатору — одна строка «found N, fixed N». Доступную дешёвую сквозную -проверку прогони до запуска ревьюеров, иначе ревью уйдёт на код, который -прогон ещё поменяет. - -Реализацию проверяй по риску: - -- тривиальная — саморевью исполнителя; -- обычная — один независимый ревьюер по коду; -- сложная или рискованная — два адверсариальных ревьюера: соответствие задаче - и качество кода. - -Разные семейства моделей предпочтительны: они дают больше разнообразия, чем -два свежих треда одной родословной. Когда внешняя линия технически недоступна, -используй доступных ревьюеров; процесс от неё не зависит. Если же линию -держит не техника, а политика согласия — передача кода внешнему сервису -требует явного разрешения владельца, — сначала запроси разрешение: замена -односемейными ревьюерами теряет основание линии дефектов, а один ответ -владельца разблокирует задуманную схему. - -Выбрав ревью постановки или реализации, прочитай единый -[договор ревью и триажа](references/review-and-triage.md). Он определяет -владельца триажа, файловый канал, повторные проверки и предохранитель кругов. - -## Приёмка - -Координатор принимает результат, но углубляется в доказательства постепенно: - -1. состав изменений и краткие сводки ревью; -2. отдельные спорные фрагменты; -3. полный diff, только когда его объём ограничен и чтение нужно для решения. - -После закрытия триажа находок у заметной работы — **проход на вычитание**: -ревью умеет только прибавлять, и за круги правок набираются добавления. -Проход ведёт модель со вкусом с правом только резать и явным списком -неприкосновенного; сомнение «резать или нет» решается в пользу реза. Мелкой -правке достаточно саморевью — причину пропуска назови одной фразой. - -Доступную детерминированную финальную проверку запускай сам с выводом в файл. -В контекст возьми точную команду, код возврата, итоговые счётчики, имена -упавших тестов и путь к журналу. Зелёный журнал не читай. Красный журнал -направь исполнителю или отдельному разборщику; сам открывай детали, когда они -нужны для решения о границах, риске, среде или смене исполнителя. Если -проверка доступна только проверяющему в специальной среде, явно назови -свидетельство косвенным. - -Перед завершением: - -- сопоставь результат с исходной целью и назови всё неподтверждённое; -- убедись, что выбранная независимая проверка завершена либо риск принят - полномочным решением; -- дай партнёру короткую саморефлексию: что больше всего потратило контекст, - оправдана ли трата, что в следующий раз направить через файл или субагента, - какие отклонения процесса произошли. - -Новый урок для [эмпирики](references/lessons.md) только предложи партнёру. -Правь долговечную эмпирику после его согласия. - -## Партнёр в петле - -На границах этапов давай партнёру карту прогресса в 4–7 строк обычными -словами: что сделано, что идёт, что дальше. Термины плейбука — только с -расшифровкой. Карта дополняет содержательную сводку, не заменяет её. -Решения о скоупе и принятии остаточного риска остаются у партнёра. - -## Сбои координации - -- Нет ожидаемого файла: один раз запроси короткий итог в том же треде; после - повторной тишины продолжи свежим агентом от сохранённых артефактов. -- Длинный рассказ пришёл сообщением: попроси повторить ответ сводкой и путём, - не переноси рассказ дальше. -- Два исполнителя пересеклись в исходниках: останови их, установи одного - владельца и продолжи от проверенного состояния без отката чужих правок. -- Процесс не сходится: используй точки вмешательства из договора ревью, - объясни партнёру причину, стоимость и принятое решение. -- После завершения сохрани только предусмотренные проектом долговечные - решения и удали временные артефакты именно этого прогона. +Показывай пользователю содержательные изменения: что выяснено, какой выбор +возник и на чем основана приемка. Цель, расширение границ и существенный +остаточный риск остаются его решениями. Уже полученное разрешение сохраняет +силу; технические действия внутри него организуй самостоятельно. diff --git a/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml b/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml index 34798c1..fb9e213 100644 --- a/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml +++ b/agents/.agents/skills/codex-subagent-playbook/agents/openai.yaml @@ -1,6 +1,6 @@ interface: display_name: "Codex Subagent Playbook" - short_description: "Делегирование без засорения контекста мастера" - default_prompt: "Используй $codex-subagent-playbook как оптику: выбери полезное делегирование и независимую проверку, сохранив контекст мастера для решений." + short_description: "Оптика Astra: делегирование, контекст и ревью" + default_prompt: "Используй $codex-subagent-playbook как оптику Astra: выбери полезное делегирование и достаточную проверку для текущей задачи." policy: allow_implicit_invocation: false diff --git a/agents/.agents/skills/codex-subagent-playbook/references/claude.md b/agents/.agents/skills/codex-subagent-playbook/references/claude.md new file mode 100644 index 0000000..3d13333 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/claude.md @@ -0,0 +1,67 @@ +# Claude как независимый ревьюер + +Читай этот файл только после решения добавить взгляд другого семейства моделей. +Claude - необязательная линия; нативный процесс работает и без нее. + +## Выбор и доступ + +Модель и глубину выбирай по пользовательскому предпочтению и результатам +реальных прогонов. Прежние рейтинги Opus, Sonnet или других моделей не являются +постоянной гарантией. Записывай запрошенные настройки отдельно от фактически +подтвержденных метаданных запуска. + +Полноценному ревью нужны доступные тесты, документация, сеть и временные файлы. +Если установленная версия поддерживает `--permission-mode auto`, запускай +с этим режимом. Внешняя песочница только для чтения обедняет проверку; исходники +и постоянное состояние защищает [мандат ревьюера](prompts/review-boilerplate.md). +Запуск `claude` передает поручение и выбранные материалы внешнему сервису +Anthropic. Сначала примени уже полученное разрешение. Если действующая политика +требует отдельного разрешения, получи его до передачи материалов и сохрани +ценность выбранной линии при ожидании решения. При реальной блокировке назови +конкретную команду или ресурс и наблюдаемую ошибку, затем выбери доступного +ревьюера с честно указанным ограничением. Не засчитывай урезанный запуск как +полноценную выбранную линию. + +## Возможности установленного CLI + +По выводу `claude --help` версии 2.1.263 от 2026-09-06 доступны: + +- `--permission-mode auto`, `--model`, `--effort` и `--resume`; +- `--bg` для фоновой сессии; +- `claude agents --json --all`, `claude logs `, `claude attach ` и + `claude stop ` для управления фоновыми сессиями. + +Это подтверждение синтаксиса справкой CLI. Оно не доказывает выбранную +провайдером модель, примененную глубину или поведение конкретной фоновой +сессии. После обновления CLI сначала сверь актуальную справку. + +## Запуск и продолжение + +Первый обзор линии запускай свежей сессией с +[договором ревью](review-and-triage.md), отдельным фокусом и уникальным путем +отчета. Для короткого поручения подходит форма: + +```text +claude --permission-mode auto --model --effort --bg "" +``` + +Большой промпт оставь в общем временном каталоге и передай короткий мандат с +путем. Шумный поток CLI сохрани во временном журнале; координатору верни +ограниченный индекс и путь к отчету. + +Перед узкой перепроверкой убедись, что исходный обзор завершен. Если после +финального результата его фоновый процесс все еще активен, останови этот +простаивающий процесс; работающий обзор с прогрессом не останавливай. Продолжи +сохраненную сессию командой +`claude --bg --resume ""` без повторного +задания модели, `effort` и режима доступа: она использует настройки первого +запуска с `--permission-mode auto`. При сомнении сверь метаданные. Активная +сессия или переопределение ее сохраненных параметров создаст копию с новым +идентификатором. +Фоновую работу наблюдай через уведомления среды, ожидание и команды состояния; +`claude agents --json --all` включает завершенные сессии. Тайм-аут отдельного +запроса не означает гибель сессии: проверь состояние и журнал. Живую сессию с +прогрессом не останавливай из-за истечения времени ожидания. + +Если CLI отсутствует или неработоспособен, выбери подходящую свежую линию +Codex и точно назови утраченное преимущество другого семейства моделей. 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 539da9e..2f5e385 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md @@ -1,160 +1,109 @@ -# Сборка нативных промптов +# Мандаты и файловый обмен -Это механика после выбора приёма в [основной оптике](../SKILL.md). Смысл -ревью и триажа задаёт [единый договор](review-and-triage.md); здесь только -параметры, файловые пути и сборка. +Читай этот файл, когда готовишь поручение агенту или передаешь большой материал +между участниками. Смысл ревью и триажа задает +[единый договор](review-and-triage.md); здесь находятся короткие заготовки. -Постоянный текст живёт в [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) — язык временного обмена. +Ясное поручение, уточнение или вердикт передавай коротким сообщением. Файл +нужен, когда материал велик, используется повторно или должен попасть от одного +агента к другому, не проходя целиком через контекст координатора. -Меняй договор только в его авторитетном файле. В параметрических файлах держи -только факты конкретной задачи. +Для файлового обмена выбери общий временный каталог задачи. Дай каждому +результату уникальный абсолютный путь с версией артефакта и линией обзора в +имени. Получатель читает исходный файл напрямую; координатор передает путь и +короткую цель, не копирует полный материал в новый промпт. -## Каталог прогона +Постоянные английские блоки находятся в [prompts/](prompts/): -`$SCRATCH` определён в основном файле как общий временный каталог. Для задачи -создай в нём уникальную подпапку, далее `D`. `P` обозначает каталог -`references/prompts` этого скилла. Каждый агент получает отдельный `REPORT`. +- [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) - язык временного обмена. -Собирай файлы механически, не читая полезную нагрузку в контекст координатора. -В схемах ниже `A + B -> C` означает текстовое объединение файлов в заданном -порядке нативным средством текущей ОС; `[A]` означает необязательный файл. -Схема не предписывает оболочку, синтаксис пути или отдельный этап процесса. +## Короткое поручение -## Исполнитель или исследователь - -`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: absolute unique path +Goal: . +Scope: . +Read: . +Check: . +Return: . +Escalate design or scope changes with options, costs, and your recommendation. ``` +Убирай ненужные строки. Не создавай обменный файл ради нескольких предложений. + +## Большое поручение + +В параметрическом файле оставь только факты конкретной задачи: + ```text -D/params.md -+ P/result-contract.md -+ P/runtime-language.md --> D/prompt.md +GOAL: one verifiable outcome +WORKING DIRECTORY: absolute path +BOUNDARIES: allowed work and protected state +READ FIRST: exact paths +CHECKS: commands or hypotheses +REPORT: unique absolute path ``` -Самодостаточную постановку и подробное обязательное чтение добавляй только -когда они нужны выбранной работе. +Если агенту нужен полный отчет, передай ему пути к +[договору результата](prompts/result-contract.md) и +[правилу языка](prompts/runtime-language.md) либо механически собери эти файлы +с параметрами. Координатор не перепечатывает постоянные блоки. Передай агенту +короткое сообщение с путем к поручению. Сборка файлов служит оптимизацией для +длинного материала. -## Ревью постановки или реализации +## Независимое ревью -`review-common.md` одинаков для одного обзора: +Параметры обзора должны назвать: ```text TITLE: short review title -WORKING DIRECTORY: absolute repo path -STATEMENT: task and parent spec paths -REVIEW INPUT: task sections, exact paths, a prepared diff path, or a diff command -OUT OF SCOPE: what is explicitly outside this review -CHECKS: commands and expected counters +WORKING DIRECTORY: absolute path +STATEMENT: task and governing contract paths +REVIEWED VERSION: commit, prepared diff, exact paths, or other stable boundary +FOCUS: one explicit lens +OUT OF SCOPE: unrelated work +CHECKS: useful commands and expected observations +FINDING PREFIX: unique stable prefix +REPORT: unique absolute path ``` -`REVIEW INPUT` должен позволять отличить проверяемую работу от посторонних -изменений. Выбери достаточную форму для текущего дерева; диапазон коммитов не -обязателен, если точные пути, разделы или подготовленный diff уже задают границу. +Передай пути к этим параметрам, [мандату ревьюера](prompts/review-boilerplate.md) +и [правилу языка](prompts/runtime-language.md) либо механически собери из них +полное поручение. +Каждая линия получает свой фокус, префикс и путь. Отчеты параллельных линий не +передаются друг другу до завершения исходных обзоров. -`review-output.md` задаёт поля конкретной линии: +Для проверки формы можно добавить такой фокус: ```text -TYPE: spec | task | code -FINDING PREFIX: SPEC-A | SPEC-B | TASK | CODE -REPORT: absolute unique path +Before reading the changes, sketch one plausible solution shape from the +statement: responsibilities, boundaries, data movement, and necessary +artifacts. This is a hypothesis, not a prescribed design. Compare the actual +shape with it, identify decisions left open by the statement, and judge each +decision against repository values, risk, and task proportion. ``` -`review-focus.md` задаёт один выбранный фокус. Для постановки: +## Разбор и перепроверка -```text -Review the statement or plan at its own level of abstraction, not as an -implementation. Check facts against code, hidden one-line decisions, -boundaries, checkable acceptance criteria, and ways to satisfy the wording -without the intended result. +Исполнитель разбирает реализацию по +[triage-header.md](prompts/triage-header.md). Передай ему пути к подробным +отчетам без изменений, решения координатора и уникальный путь резолюций. +Короткая сводка ревьюера не заменяет исходные доказательства. -A high-level document is not incomplete merely because implementation choices -remain open. Request changes only for a defect the document itself must -resolve: one that changes its goal, boundaries, architectural direction, -acceptance criteria, dependencies, or the ability to decompose work safely. +Исходному ревьюеру для узкой перепроверки передай +[recheck-header.md](prompts/recheck-header.md), путь к его исходному отчету, +путь к резолюциям, границу новой версии, нужные проверки и новый уникальный +путь отчета. Продолжи тот же тред или сессию: здесь его прежний контекст +полезен. -When a detail can be decided locally by a downstream owner without changing -those properties, do not make it a finding or prescribe the implementation. -If deferring it carries a relevant risk, record that risk as a non-gating -consideration. - -APPROVED means that no defect at the document's own level requires revision. -It does not mean that all downstream questions have been answered. -``` - -Для реализации выбери 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. -``` - -```text -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` используй один; -отчёты и финальные сообщения линий не объединяй до их завершения. - -## Триаж постановки - -Координатор читает краткие строки и нужные подробности, принимает решение по -каждому `SPEC-*` и обновляет постановку. Резолюции сохраняет в -`spec-resolutions.md`; этот файл и новая постановка идут исходному ревьюеру -на узкую перепроверку. - -## Триаж реализации - -Передай исполнителю актуальные подробные отчёты без пересказа: исходные обзоры -в первом круге, отчёты перепроверки для оставшихся и новых находок в следующих. -`triage-params.md` содержит путь итогового отчёта и проверки. -`coordinator-notes.md` добавляй только для совпадений, противоречий и новых -решений уровня задачи. - -```text -P/triage-header.md -+ D/triage-params.md -+ -+ [] -+ [D/coordinator-notes.md] -+ P/runtime-language.md --> D/fix-prompt.md -``` - -## Узкая перепроверка - -Продолжай исходный тред ревьюера. `recheck-params.md` задаёт пути к его -исходному отчёту и файлу резолюций, нужную проверку и новый уникальный -`REPORT`. - -```text -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 5cb0c09..3ec1ac6 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,15 +1,24 @@ # Narrow re-check -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. +Continue from your original review. Read that report, the resolution report, +and the new reviewed version. Re-check only your original findings and changes +immediately adjacent to their resolution. -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. +For every `FIXED` or `REJECTED` ID report `CLOSED`, `NOT_CLOSED`, +`REJECTION_VALID`, or `REJECTION_INVALID` with concise evidence. Carry +`OUT_OF_SCOPE` and `NEEDS_DECISION` into the index unchanged; do not +re-judge them or include them in your verdict. They remain open for their +owner. Judge a rejection by its contract and evidence. For a `FIXED` +resolution also report +`PROPORTIONATE` or `OVERREACH`; put your own earlier prescription on trial +and price added complexity against the risk it removes. -Write the detailed re-check to REPORT. Return only: +Narrow scope limits exploration, not honest reporting. Give a newly exposed +adjacent defect a new stable ID and return it for triage. `OVERREACH` is an +upward signal and does not by itself reopen the original defect. + +Preserve sources and persistent state. Write the detailed re-check to REPORT. +Return only: - `VERDICT: APPROVED | CHANGES_REQUESTED`; - status counters; 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 7ca109d..2253850 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 @@ -1,14 +1,18 @@ ## Result contract -Write the full result through the channel chosen by the caller: +Use the channel selected by the caller. + +For a short message, return only the evidence and decision needed next. For a +file channel, write the detailed result to REPORT and return status, counters, +and `REPORT: `. + +When relevant, the detailed result contains: - `STATUS: complete | questions | blocked` -- `EVIDENCE:` changed files, executed commands, and final counters -- `DECISIONS:` only questions for the coordinator or partner -- `FINDINGS:` severity, location, essence, and verification method +- `EVIDENCE:` changed files, checks, and observed results +- `DECISIONS:` design or scope questions with options, costs, and a recommendation +- `FINDINGS:` severity, location, claim, 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. +Omit empty sections and raw tool output. Do not duplicate a file report in the +final message. 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 0bcef87..ffda425 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,40 +1,44 @@ -## Mandate +## Reviewer mandate -- 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. -- 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. +- Review the stated version independently. Treat prior claims and the proposed + implementation as hypotheses until evidence supports them. +- Read sources, run relevant tests, consult available documentation and + primary sources, and use temporary files or caches when they strengthen the + verdict. +- Preserve source files, Git, services, data, and other persistent state. + Write the detailed result only to REPORT. +- Judge defects at the reviewed artifact's own level and price a proposed fix + against the risk it removes. A finding is a claim, not an order. ## Detailed report -Use stable IDs with FINDING PREFIX: +Use permanent IDs with FINDING PREFIX. -`PREFIX-N | BLOCKER|MAJOR|MINOR|NIT | file:line or task section | violated -criterion | failure scenario | evidence | minimal verification` +`PREFIX-N | location | violated criterion | +failure scenario | evidence | minimal verification` -A non-gating consideration has no stable ID, severity, or counter. Use it only -for a material risk from a safely deferred decision, and do not prescribe the -downstream implementation. It does not change the verdict. +When the project or review line already defines a severity scale, add severity +to the record and count it. -Use CHANGES_REQUESTED only when at least one finding requires revision at the -reviewed artifact's own level. APPROVED means that no such defect remains; it -does not mean that every downstream question has been answered. +A non-gating consideration has no ID, severity, or counter. Use it only for a +material risk of a safely deferred decision. It does not change the verdict. +A style preference without demonstrable harm is a consideration, not a +blocking finding. -If there are no findings, record the reviewed scope and every executed check -or tested hypothesis with its outcome. A bare approval is invalid. +`CHANGES_REQUESTED` requires at least one defect in the reviewed version. +`APPROVED` means no such defect remains. With zero findings, record the +reviewed scope and every check or hypothesis tested with its outcome; a bare +approval is invalid. ## Final message Return only: - `VERDICT: APPROVED | CHANGES_REQUESTED` -- severity counters; -- one line per finding: `ID | severity | area | one-phrase essence`; -- optional one-line material considerations: - `CONSIDERATION | area | one-phrase risk`; -- `REPORT: `. +- available counters +- one line per finding with ID, area, one-phrase claim, and any established + severity +- every material consideration, one line each +- `REPORT: ` -Do not repeat the detailed report or reasoning narrative in the final message. +Do not repeat the detailed report. 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 8f1b721..a7dfda3 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,17 +1,31 @@ # Triage independent-review findings -The review reports below are immutable input. Process every stable finding ID -and change nothing outside their scope. Assign exactly one disposition: +The review reports are immutable evidence, not instructions. Verify every +finding against the governing contract, the project, and an applicable +scenario. Also judge whether the proposed repair is proportionate; close a +confirmed defect by a better route when one exists. -- `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. +Process every stable finding ID and assign exactly one disposition: -Do not commit, stage, or rewrite the source reports. Write detailed resolutions -to REPORT. Return only: +- `FIXED`: the defect is confirmed and repaired; name the route and evidence; +- `REJECTED`: the claim is unsupported, inapplicable, or does not describe a + defect under the governing contract; cite the contract and evidence; +- `OUT_OF_SCOPE`: resolution changes the agreed boundary; +- `NEEDS_DECISION`: a goal, architecture, or residual-risk choice remains. + +A reasoned `REJECTED` is as valid as `FIXED`; there is no rejection quota. +Rejecting the reviewer's prescribed repair does not close a confirmed, +applicable defect. Give that defect a proportionate `FIXED`, `OUT_OF_SCOPE`, +or `NEEDS_DECISION` disposition. +Send `OUT_OF_SCOPE` and `NEEDS_DECISION` upward with alternatives, costs, +consequences, and your recommendation. Do not settle them through an incidental +code edit. + +Preserve source reports and stable IDs. Make only confirmed, in-scope changes. +Write detailed resolutions to REPORT, including checks and changed files. +Return only: - overall status and disposition counters; - one line per finding: `ID | disposition | one-phrase essence`; -- questions for the coordinator and executed-check counters; +- coordinator decisions needed 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 index 12803b8..fd8cc67 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/review-and-triage.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/review-and-triage.md @@ -1,155 +1,168 @@ # Ревью и триаж Читай этот файл целиком после выбора независимого ревью постановки или -реализации. Режим и стоимость выбираются в [основной оптике](../SKILL.md); -здесь один авторитетный договор выполнения. +реализации. Это единственный подробный договор обзора, разбора находок и +перепроверки. -- [Независимость и фокус](#независимость-и-фокус) -- [Файловый маршрут](#файловый-маршрут) -- [Отчёт ревьюера](#отчёт-ревьюера) -- [Владелец триажа](#владелец-триажа) -- [Перепроверка и круги](#перепроверка-и-круги) -- [Что читает координатор](#что-читает-координатор) +- [Выбор обзора](#выбор-обзора) +- [Мандат и независимость](#мандат-и-независимость) +- [Отчет ревьюера](#отчет-ревьюера) +- [Разбор находок](#разбор-находок) +- [Перепроверка](#перепроверка) +- [Когда работа не сходится](#когда-работа-не-сходится) +- [Доказательства для координатора](#доказательства-для-координатора) -## Независимость и фокус +## Выбор обзора -Запускай ревьюера свежей сессией без истории исполнителя и других ревьюеров. -Повторную проверку точечных исправлений продолжает тот же ревьюер: его контекст -находок полезен и не отменяет независимость исходного обзора. +Подбирай ревью по неопределенности и цене ошибки. Нативный ревьюер, Claude и +свежая Astra - доступные линии. Обязательного набора нет. Отдельные основания: +свежий контекст ловит предположения автора, другое семейство моделей замечает +иные слепые зоны, Astra судит об устройстве и соразмерности. Одного обзора +достаточно, если он закрывает существенный риск. Две сфокусированные линии +оправданы, когда их независимый вклад стоит цены. -Для двойного ревью разделяй фокусы: +Для двух линий заранее раздели фокус, например: -- **по задаче** — соответствие постановке, критериям, границам и ожидаемому - результату; -- **по коду** — корректность, межмодульные инварианты, регрессии, безопасность - и честность тестов. +- соответствие задаче, границам и наблюдаемому результату; +- корректность, межмодульные инварианты, регрессии и честность проверок. -Давай обоим общую постановку и изменённый объём, но отдельный файл фокуса и -отдельный путь отчёта. Они не знают о второй линии до завершения исходных -обзоров. Разные семейства моделей предпочтительны; две доступные линии одного -семейства всё равно полезны на сложной задаче, если их фокусы различаются. +Перед первым обзором каждой линии зафиксируй проверяемую версию артефакта. +Одна линия делает один общий обзор этой версии. Не запускай новый общий обзор +той же линии без изменения версии или нового основания; точечные исправления +проверяются узко. -Ревьюер — наблюдатель с нужными инструментами. Он может читать код, запускать -тесты, проверять гипотезы, создавать временные кэши и писать назначенный файл -отчёта. Исходники, постоянное окружение и Git он не меняет. Координатор -сверяет состояние дерева до и после. +## Мандат и независимость -## Файловый маршрут +Исходный обзор запускается в свежем контексте без истории исполнителя и других +ревьюеров. Ревьюер получает постановку, точные границы версии, свой фокус, +доступные проверки и уникальный путь отчета. Он самостоятельно сверяет факты, +а утверждения других агентов считает гипотезами до подтверждения. -Назначь каждому участнику уникальные файлы в каталоге задачи внутри -`$SCRATCH`. Временные промпты и отчёты веди на английском. +Ревьюеру разрешены чтение, тесты, доступная сеть, документация и временные +файлы, нужные для проверки. Его мандат запрещает менять исходники, Git, +службы, данные и другое постоянное состояние. Результат обзора - назначенный +отчет; временные кэши и выводы инструментов допустимы. +Координатор остается владельцем общего дерева и стенда и при необходимости +сверяет их состояние до и после обзора. + +Полный отчет пишет сам ревьюер в место, доступное владельцу триажа. Координатор +не пересказывает и не восстанавливает доказательства по краткой сводке. Если +общий файл недоступен, используй доступный канал и точно назови ограничение +передачи: где остался полный отчет и какие доказательства не переживут сессию. +Готовые английские блоки мандата и языка лежат в +[шаблоне ревьюера](prompts/review-boilerplate.md) и +[правиле обмена](prompts/runtime-language.md). + +## Отчет ревьюера + +Ревью возвращает проверяемые утверждения. Каждая находка получает +устойчивый идентификатор с уникальным префиксом линии. Сохраняй идентификатор +во всех следующих разборах и перепроверках. Полная запись содержит: ```text -reviewer -> detailed report file -> triage owner - | - +-> short summary -> coordinator +PREFIX-N | location | violated criterion | failure scenario | evidence | +minimal verification ``` -Ревьюер сам пишет полный отчёт в назначенный файл. Координатор не принимает -полный отчёт сообщением и не переписывает его перед передачей. Владелец -триажа читает исходные отчёты напрямую и пишет подробные резолюции в следующий -файл. +Существенный риск безопасно отложенного решения можно записать как +неблокирующее соображение без идентификатора, тяжести и влияния на вердикт. +Если проект или линия уже задает шкалу, добавь в запись тяжесть и считай ее. +Замечание о стиле без проверяемого ущерба остается соображением и не требует +исправления. +`CHANGES_REQUESTED` означает, что версия содержит хотя бы один дефект, который +нужно исправить на ее собственном уровне. `APPROVED` означает отсутствие +такого дефекта. -Если общий каталог недоступен, верни через контекст компактный индекс без -нарратива. Координатор сразу сообщает партнёру, какой агент не получил доступ, -к какому пути, какой запасной канал использован и что нужно проверить после -задачи. Сбой канала ухудшает экономию контекста, но не отменяет ревью. +Даже при нуле находок отчет называет просмотренный объем, проверенные гипотезы, +запущенные команды и их результаты. Голый вердикт без свидетельств не +засчитывается. Сообщение координатору может содержать только вердикт, доступные +счетчики, по одной строке на идентификатор и на каждое существенное +неблокирующее соображение, а также путь к подробному отчету. -## Отчёт ревьюера +## Разбор находок -Каждая находка получает устойчивый идентификатор с уникальным префиксом -линии: `SPEC-A-N` и `SPEC-B-N` для постановки, `TASK-N` для соответствия -реализации задаче и `CODE-N` для качества кода. Полный файл содержит: +Каждую находку сначала проверяют на трех осях: фактическая верность, +применимость сценария к этому проекту и соразмерность исправления. Предложение +ревьюера - один из вариантов. Исполнитель может закрыть дефект более подходящим +путем. Аргументированное отклонение имеет тот же статус, что и подтвержденное +исправление; квота отклонений не нужна. -- идентификатор, тяжесть и `файл:строка` либо раздел постановки; -- нарушенный критерий; -- сценарий сбоя и доказательство; -- минимальный способ проверки. +Находки о постановке разбирает координатор. Он сохраняет цель и границы, +проверяет технические утверждения доступным способом и выносит владельцу +продуктовый выбор или существенный риск. -Неблокирующее соображение не получает идентификатор и тяжесть, не входит в -счётчики и не меняет вердикт. Так сохраняй только существенный риск от -отложенного решения, не проектируя реализацию за следующего владельца. -`CHANGES_REQUESTED` означает, что хотя бы одна находка требует исправить -документ на его собственном уровне. `APPROVED` означает отсутствие такого -дефекта, а не отсутствие всех будущих вопросов. +Находки реализации разбирает исполнитель с контекстом кода. Он получает +подробные отчеты напрямую. Координатор добавляет только решения уровня задачи, +совпадения или противоречия линий. Каждый идентификатор получает один исход: -В сообщение координатору верни только: +- `FIXED` - дефект подтвержден и исправлен; названы способ и проверка; +- `REJECTED` - утверждение не подтвердилось, неприменимо к проекту или не + описывает дефект по действующему договору; приведены контракт и доказательство; +- `OUT_OF_SCOPE` - решение меняет согласованные границы; +- `NEEDS_DECISION` - требуется выбор цели, устройства или остаточного риска. -- `VERDICT: APPROVED | CHANGES_REQUESTED`; -- счётчики по тяжести; -- по одной строке на находку: идентификатор, область, суть и тяжесть; -- по одной строке на существенное неблокирующее соображение, если оно есть; -- абсолютный путь к полному отчёту. +`OUT_OF_SCOPE` и `NEEDS_DECISION` поднимаются координатору с вариантами, +последствиями, стоимостью и рекомендацией исполнителя. Координатор не заменяет +этот разбор молчаливым решением. Подробный файл резолюций сохраняет связь +между исходной находкой, ее исходом и проверкой. -При отсутствии находок полный файл перечисляет просмотренный объём и -выполненные проверки. Голая строка `APPROVED` без подтверждения работы не -засчитывается. +Отклонение предложенного способа починки само по себе не закрывает +подтвержденный применимый дефект. Такой дефект получает соразмерное +`FIXED`, либо решение владельца через `OUT_OF_SCOPE` или +`NEEDS_DECISION`. -## Владелец триажа +## Перепроверка -**Постановка.** Координатор принимает или отклоняет каждую находку, потому что -цель, границы и критерии — его решения. Открытое техническое исследование он -может отдать deep-reasoner, но сам читает верхнеуровневые документы и итоговую -постановку. Продуктовый выбор и принятие риска выносит партнёру. +Точечные исправления и отклонения проверяет тот же ревьюер в продолжении +исходного контекста. Он читает собственный отчет, резолюции и измененную +версию, затем проверяет исходные идентификаторы и только соседние изменения. +Для каждого `FIXED` или `REJECTED` он возвращает `CLOSED`, `NOT_CLOSED`, +`REJECTION_VALID` или `REJECTION_INVALID` с кратким доказательством. +`OUT_OF_SCOPE` и `NEEDS_DECISION` переносятся в индекс без изменения: +ревьюер их не пересматривает и не включает в свой вердикт. Они остаются +открытыми до решения владельца. -**Реализация.** Пофиндинговый триаж делает исполнитель, у которого есть -контекст кода. Координатор передаёт актуальные подробные отчёты выбранных линий -без изменений и добавляет отдельную короткую шапку: совпадения, противоречия и -возможный выход за границы. Он не сливает и не удаляет «дубликаты». +Для `FIXED` ревьюер отдельно оценивает соразмерность починки: +`PROPORTIONATE` либо `OVERREACH` с объяснением лишнего охвата. Для +`REJECTED` он судит по аргументу и проверке; совпадение со вкусом не требуется. +Узкая область не требует скрывать замеченный рядом новый дефект: такой дефект +получает новый устойчивый идентификатор и возвращается владельцу триажа. -Для каждого идентификатора исполнитель возвращает один статус: +Выбранная линия ревью закрывается после начального `APPROVED` без открытых +вопросов либо после успешных нужных перепроверок и разрешения владельцем всех +вынесенных вопросов. Полномочный владелец также может явно записать принятие +оставшегося риска. Вердикт одной линии не закрывает открытые идентификаторы +другой. -- `FIXED` — исправлено и названо доказательство; -- `REJECTED` — отклонено через контракт и проверку; -- `OUT_OF_SCOPE` — требует отдельного решения о границах; -- `NEEDS_DECISION` — технического решения недостаточно. +Изменения шире прежней версии, слабый исходный отчет или новая независимая +неопределенность могут оправдать свежий общий обзор. Сам номер круга такого +основания не создает. -Подробности остаются в файле триажа. Координатор получает по одной компактной -строке `ID | status | essence` на находку, счётчики, вопросы уровня задачи и -путь. Риск и выход за границы решает координатор; техническую истинность -находки — исполнитель и ревьюер. +## Когда работа не сходится -## Перепроверка и круги +Сигналы несходимости: тот же спор повторяется без новых доказательств, +исправления разрастаются дальше исходного риска, новые общие обзоры мало что +добавляют или стороны проверяют разные версии и контракты. Координатор сначала +останавливает петлю и устанавливает общий предмет спора. Затем он может +уточнить постановку, сузить проверку, сменить исполнителя или ревьюера, +повысить доступную модель или глубину, разделить задачу либо принять риск в +пределах полномочий. -Один круг — назначенные обзоры, триаж его владельца и узкая перепроверка. -Исходный ревьюер читает свой отчёт и файл резолюций, проверяет только свои -находки и соседние изменения. Выбранное независимое ревью закрывается -`APPROVED` либо явным принятием риска полномочным координатором или партнёром. -Координатор получает по одной компактной строке со статусом каждого исходного -или нового идентификатора; подробности остаются в файле перепроверки. -Если идентификатор не закрыт либо появился рядом с исправлением, актуальный -отчёт перепроверки напрямую идёт владельцу следующего триажа. Координатор не -восстанавливает доказательства из компактной сводки. +Третий круг - практическое напоминание явно объяснить пользователю или +полномочному владельцу, почему работа не сходится, сколько стоит продолжение и +какой подход меняется. Пятый круг - напоминание не начинать еще один повтор +без явного решения. Это ориентиры наблюдения; обязательных этапов и +автоматических запросов разрешения здесь нет. -Повторно поднятое аргументированно отклонённое замечание пометь как спор и -отправь на отдельную узкую проверку усиленного уровня. Полный новый обзор -нужен, когда реализация широко изменилась, исходный отчёт слаб или требуется -новая независимая линия. +## Доказательства для координатора -Третий круг — точка вмешательства: сообщи партнёру, почему процесс не сходится, -какова стоимость и что меняешь. Координатор может уточнить постановку, -повысить модель или effort, заменить исполнителя свежим сильным агентом, -разделить задачу, назначить усиленный гейт либо принять риск в пределах -мандата. +Координатор обычно получает вердикт, счетчики, компактные строки находок и +пути. Он раскрывает подробный отчет, когда находка меняет границы или риск, +линии противоречат друг другу, возник спор, сводка не дает основания для +решения либо это нужно для собственной приемки. Для спорного утверждения он +читает соответствующее доказательство. Весь diff или журнал нужен лишь когда +узкого фрагмента недостаточно. -Пятый круг не начинай автоматически. Сначала прими явное решение и объясни его -партнёру; если полномочий недостаточно, остановись и запроси решение. Это -предохранитель от дорогой вложенной петли, а не запрет координатору управлять -работой. - -## Что читает координатор - -Краткие строки находок нужны координатору для сравнения линий. Подробный файл -открывай, когда находка меняет границы или риск, ревьюеры противоречат друг -другу, возник спор, сводка непонятна либо без деталей нельзя выбрать следующий -шаг. - -Для обычной починки координатор видит переход: - -```text -CHANGES_REQUESTED -> triaged -> rechecked -> APPROVED -``` - -Полный diff, доказательства и журналы читают назначенные агенты. Координатор -углубляется в них по правилам приёмки основной оптики, когда это нужно для его -собственного решения. +Так защита контекста остается ступенчатой: подробности доходят до владельца +триажа напрямую, а Astra читает ровно тот уровень, который нужен для +самостоятельного решения. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/roles.md b/agents/.agents/skills/codex-subagent-playbook/references/roles.md index f179269..f1488f8 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/roles.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/roles.md @@ -1,212 +1,55 @@ -# Уровни и роли +# Роли и возможности среды -Маршрутизация моделей обновлена 2026-07-13. Имена и уровни здесь — датированная -настройка среды; логика [основной оптики](../SKILL.md) остаётся относительной. +Читай этот файл при выборе агента, модели, глубины рассуждения или способа +передачи истории. Сначала посмотри на схему доступного инструмента: она +описывает текущую среду точнее датированных заметок. -Читай этот файл только при настройке ролей или когда нужная роль недоступна. -[Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен. -Этот файл — условные настройки мандата, а не список обязательных участников. -Один агент может совмещать совместимую работу; не создавай тред на каждое имя. +## Распределение ответственности -- [Возможности хоста](#возможности-хоста) -- [Выбор уровня](#выбор-уровня) -- [Текущая маршрутизация](#текущая-маршрутизация) -- [Возможные мандаты](#возможные-мандаты) -- [Файл пользовательского агента](#файл-пользовательского-агента) -- [Пределы параллельности](#пределы-параллельности) +- **Astra** держит замысел, выбирает устройство решения, разрешает спорные + вопросы и принимает результат. Свежая Astra полезна для отдельной проверки + формы и соразмерности, когда цена такого взгляда оправдана. +- **Sol** обычно реализует задачу, исследует техническую неопределенность, + проверяет код и исправляет подтвержденные дефекты. +- **Luna** удобна для ясной механики, пакетных операций и известных проверок + с объемным выводом. -## Возможности хоста +Эти назначения служат отправной точкой. Состав собирай под задачу; один агент +может совмещать совместимую работу. Выбор определяется вкладом в задачу и +качеством доступных моделей. Название роли вторично. -Сначала установи, позволяет ли текущий хост выбрать пользовательского агента -и его конфигурацию. +## Модель и глубина -- **Управляемая стоимость.** Хост видит агентов из `~/.codex/agents` или - `.codex/agents` и схема `spawn_agent` открывает `agent_type`, `model` и - `reasoning_effort` (про фактическое применение effort — кавеат в - [выборе уровня](#выбор-уровня)). Для TOML-роли передавай `agent_type`, а - модель и глубину бери из её файла. Для разового выбора передавай `model` и - `reasoning_effort` без пользовательской роли с закреплённой моделью. - Плейбук использует `fork_turns="none"` ради чистого контекста. Технически - ограниченный fork числом тоже допускает переопределения; только полный - fork `all` наследует модель координатора и отклоняет их. -- **Неуправляемая стоимость.** Интерфейс запуска принимает только задачу и - имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана - дешёвая или сильная модель. `task_name` — идентификатор треда, а не выбор - конфигурации агента. +Модель и глубину рассуждения выбирай независимо, если среда открывает обе +ручки. Для ограниченной работы разумная отправная точка - `medium`. Для +необратимого решения, высокой цены тихой ошибки или существенной +неопределенности - `high` либо более сильная доступная настройка. Это примеры: +повышай глубину, когда не хватило поиска и рассуждения, а модель - когда не +хватило качества суждения. -Если способ выбора роли не виден в доступном инструменте, считай стоимость -неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу -на дополнительные роли без явной пользы. +Не обещай, что запрошенная модель или глубина фактически применились, если +инструмент подтверждает лишь принятие параметра. Опирайся на метаданные запуска, +когда они доступны; иначе называй настройку запрошенной. -Вызов TOML-роли: +## Текущая схема Codex -```json -{ - "task_name": "explore_code", - "message": "Исследуй код и верни выжимку по договору роли.", - "fork_turns": "none", - "agent_type": "explorer" -} -``` +На момент обновления доступный `spawn_agent` принимает `model`, +`reasoning_effort` и `fork_turns`. Значение `fork_turns` может быть `none`, +`all` или положительным числом строкой. -Разовый выбор модели без TOML-роли с закреплёнными настройками: +- `none` дает свежий контекст. Используй его для независимого исходного ревью + и для роли, которой достаточно самодостаточного краткого задания. +- Положительное число передает ограниченный хвост истории. Это полезно, когда + без ближайшего контекста поручение раздуется, а вся история не нужна. +- `all` передает полную историю и наследует модель и глубину координатора. + В этом режиме явные переопределения модели и глубины отклоняются. -```json -{ - "task_name": "explore_code", - "message": "Исследуй код и верни выжимку по договору результата.", - "fork_turns": "none", - "model": "<быстрая модель>", - "reasoning_effort": "medium" -} -``` +Для явного выбора модели или глубины используй `none` либо ограниченную +историю. Продолжение через `followup_task` сохраняет полезный контекст уже +созданного агента; короткое уточнение работающему агенту передается сообщением. +Новый свежий обзор запускается отдельным агентом с `none`. -Не смешивай режимы: роль применяется отдельным слоем конфигурации и может -перекрыть прямые параметры. `service_tier` передавай только по явному запросу; -он технически совместим и с полным fork. Если TOML-роль закрепляет -`service_tier`, значение роли перекрывает аргумент вызова; для гарантированного -разового tier используй роль без закреплённого tier. - -Основание: [официальная документация о субагентах](https://learn.chatgpt.com/docs/agent-configuration/subagents) -и [актуальная схема `spawn_agent`](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/multi_agents_spec.rs). - -## Выбор уровня - -| Уровень | Для чего | Настройка | -|---|---|---| -| Быстрый | Поиск, журналы, известные проверки, ограниченная механика | Дешёвая подходящая модель, обычно `medium` | -| Рабочий | Обычная реализация и проверка по задаче | Подходящая ролевая модель, `medium` | -| Глубокий | Архитектура, сложная реализация, ревью кода | Сильная модель, `high` | -| Исключительный | Необратимое решение или несходимость сильных агентов | Самая сильная модель, `max` | - -Критерий выбора — цена *тихой* ошибки этапа, не сложность работы: где -пропущенный дефект никто ниже по конвейеру не поймает (постановка, слепое -ревью, диагноз), ставь глубокий уровень; где за результатом стоит приёмка -координатора и ошибка громкая (узкая перепроверка, механика), хватает -рабочего. Таблица «для чего» — иллюстрация этого критерия, не замена. -Экономию уровня считай по конвейеру целиком: дешёвый этап, породивший -длинный триаж находок, выходит дороже дорогого. - -Модель задаёт потолок способности, effort — глубину работы этой модели. -Повышай effort, когда подходящей модели не хватило поиска или рассуждения. -Повышай модель, когда не хватает качества решения. После двух слабых -результатов замени исполнителя свежим более сильным агентом вместо переноса -его неудачного контекста. От уверенной выдумки внешних фактов (форматы -артефактов, версии) не страхует никакой уровень — такие факты проверяй -реальным запросом или фикстурой из первоисточника. -Кавеат (2026-07-23): текущий хост принимает `reasoning_effort` субагента, -но фактически не применяет — рабочая ручка сейчас только модель; -перепроверяй после обновлений хоста. - -`xhigh` не является автоматической ступенью: текущая эмпирика показывает -малый прирост относительно `high` при заметной цене. Выбирай его вручную для -узкой задачи. `max` заметно сильнее и дороже; используй по явному триггеру и -объясняй партнёру причину. - -## Текущая маршрутизация - -Это начальная рабочая таблица, а не рейтинг моделей. Проверяй её на прогонах и -меняй после согласования эмпирики с партнёром. - -| Роль | Модель и 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`. - -## Возможные мандаты - -### `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 = "workspace-write"`: тесты, -кэши, временные артефакты и исследование не следует урезать ради запрета -правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется -до и после. Доступ к сети проверять отдельно: право записи не гарантирует -поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу. -Канал результата от песочницы не зависит. При выбранном ревью используй -[единый договор](review-and-triage.md): назначенный файл отчёта — единственный -результат наблюдателя; временные кэши допустимы, исходники и 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` с её именем: это работает -только при явной гарантии хоста. После добавления или изменения TOML начни -новую сессию и проверь, что имя роли появилось в описании `agent_type`. - -## Пределы параллельности - -- Держи глубину `1`: субагенты не создают собственное дерево исполнителей. -- Оставляй один слот координатору. -- Параллельно запускай только работу без конфликтующих входов, команд и - изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а - не ради заполнения свободного слота. -- Реализацию и починку одного рабочего дерева выполняй последовательно одним - владельцем. +Эти сведения описывают текущий интерфейс координации. После изменения схемы +заново проверь доступные поля. Файлы локальных +ролей, установка моделей и внешняя настройка среды в работу этого скилла не +входят. Владение общим состоянием задает [основная оптика](../SKILL.md).