From f49b5847f93fdf7f1854cd8ce71d529a88b14ad5 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 6 Sep 2026 11:06:16 -0400 Subject: [PATCH] =?UTF-8?q?chore(skills):=20=D1=81=D0=BE=D1=85=D1=80=D0=B0?= =?UTF-8?q?=D0=BD=D0=B5=D0=BD=D0=BE=20=D1=81=D0=BE=D1=81=D1=82=D0=BE=D1=8F?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D0=BF=D0=BB=D0=B5=D0=B9=D0=B1=D1=83=D0=BA?= =?UTF-8?q?=D0=B0=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B4=20=D1=81=D0=BB=D0=B8?= =?UTF-8?q?=D1=8F=D0=BD=D0=B8=D0=B5=D0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - Завершена текущая работа и подготовлено продолжение без старых записок. - Что: - Три прежних handoff заменены актуальной запиской со ссылками на решения и проверки. - Включены пользовательские исключения для установленных сторонних скиллов. - Проверка: - Проверены 53 относительные ссылки, 11 якорей, YAML и обе политики включения. - Подтверждены сохранность 11 игнорируемых каталогов и доступность документов в Git. - Пройден git diff --check. --- agents/.agents/skills/.gitignore | 11 ++ .../handoffs/20260710-1643-first-version.md | 110 ------------------ .../20260712-optika-tonkogo-mastera.md | 52 --------- .../20260713-1411-review-optics-and-sync.md | 55 --------- .../20260906-1102-coordinator-refactor.md | 66 +++++++++++ 5 files changed, 77 insertions(+), 217 deletions(-) delete mode 100644 agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md delete mode 100644 agents/.agents/skills/codex-subagent-playbook/handoffs/20260712-optika-tonkogo-mastera.md delete mode 100644 agents/.agents/skills/codex-subagent-playbook/handoffs/20260713-1411-review-optics-and-sync.md create mode 100644 agents/.agents/skills/codex-subagent-playbook/handoffs/20260906-1102-coordinator-refactor.md diff --git a/agents/.agents/skills/.gitignore b/agents/.agents/skills/.gitignore index 951dba3..e8cf9e5 100644 --- a/agents/.agents/skills/.gitignore +++ b/agents/.agents/skills/.gitignore @@ -22,6 +22,17 @@ codebase-design/ code-review/ ask-matt/ find-skills/ +migrate-to-shoehorn/ +writing-shape/ +writing-fragments/ +writing-beats/ +setup-ts-deep-modules/ +setup-pre-commit/ +scaffold-exercises/ +claude-handoff/ +git-guardrails-claude-code/ +loop-me/ +implement-spec/ to-questionnaire/ wait-what/ 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 deleted file mode 100644 index 5712bbd..0000000 --- a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md +++ /dev/null @@ -1,110 +0,0 @@ -# Handoff: первая версия Codex Subagent Playbook - -Дата: 2026-07-10. Для следующей сессии, которая добавит настоящие роли -Codex и проверит полный конвейер на боевой задаче. - -## Состояние - -Первая версия скилла готова и формально валидна: - -- процесс тонкого мастера — [`../SKILL.md`](../SKILL.md); -- выбор ролей и уровней — [`../references/roles.md`](../references/roles.md); -- перенесённые уроки и открытые проверки — - [`../references/lessons.md`](../references/lessons.md); -- точные договоры нативных агентов — - [`../references/prompt-templates.md`](../references/prompt-templates.md); -- явный вызов скилла — [`../agents/openai.yaml`](../agents/openai.yaml). - -Нативные TOML-роли ещё не созданы. В интерфейсе пробной tool-backed сессии -хост скрыл поля `agent_type`, `model`, `reasoning_effort` и `service_tier`, -поэтому прогон использовал роли только как мандаты в промпте и честно -пометил стоимость как неуправляемую. Это не общее ограничение Codex: -нативная схема поддерживает все четыре поля. - -## Принятые решения - -- Главная цель — сохранить контекст мастер-модели для требований, решений и - синтеза. Внешняя модель остаётся необязательной дополнительной линией. -- Скилл запускается только явно. Текущий валидатор не принимает - `disable-model-invocation`; используется - `policy.allow_implicit_invocation: false` в `openai.yaml`. -- Модели закрепляются в файлах ролей, а не в `SKILL.md`, чтобы процесс не - зависел от смены модельной линейки. -- Для TOML-роли передаётся `agent_type`; для разового выбора — `model` и - `reasoning_effort` без роли с закреплённой моделью. Плейбук использует - `fork_turns="none"` ради чистого контекста; полный fork `all` наследует - модель мастера. -- Один агент владеет рабочим деревом. До записи сохраняется точка отсчёта, - включая хэши неотслеживаемых файлов. -- Полный отчёт ревьюера сохраняется файлом; сообщение содержит только - вердикт, счётчики и путь. `read-only`-ревьюер возвращает короткий индекс - один раз сообщением. -- На прогон создаётся один обменный временный каталог. Полные отчёты и - повторно используемые промпты передаются между агентами путями; мастер не - вставляет их повторно в tool-call. -- После завершения или сохранения блокирующего handoff обменный каталог - этого прогона удаляется. -- Нативный конвейер не зависит от вложенного запуска `codex exec`. - -## Что проверено - -- `quick_validate.py` завершился с `Skill is valid!`. -- Независимое ревью закрыло договор ревьюера, точку отсчёта, выбор стоимости - и устранение лишних повторных прогонов. -- Безопасный пробный прогон этапов 1–2 поднял исследователя и ревьюера, - сформировал самодостаточную постановку и не вынес сырые журналы в итог - мастера. Файлы проекта не менялись. -- Прогон выявил лишний полный запуск тестов исследователем; ограничение роли - уже внесено в процесс и справочник. - -## Следующая сессия - -1. Решить, входят ли Windows/chezmoi в первую поставку ролей. Пробная - постановка ограничила первую поставку Linux/WSL. -2. Выбрать модели для быстрого, рабочего и глубокого уровней. Локально - подтверждена только `gpt-5.6-sol`; не считать это готовой таблицей ролей. -3. Создать шесть ролей: `fast-worker`, `explorer`, `worker`, - `deep-reasoner`, `reviewer`, `verifier`. -4. Разместить Linux/WSL-источник в `codex/.codex/agents/` и узко открыть - нужные TOML в `.gitignore`. Сейчас родительское правило игнорирует весь - каталог. -5. Расширить `tests/test_install.sh`: разобрать TOML через `tomllib`, - проверить смысловые договоры ролей, повторную установку, стороннюю роль и - конфликт совпадающего имени. -6. Проверить обнаружение ролей установленным Codex CLI в отдельном - `CODEX_HOME`. Затем начать новую сессию и проверить, что её схема - `spawn_agent` открывает `agent_type`, `model`, `reasoning_effort` и - `service_tier`. - Синтаксический разбор TOML не доказывает поддержку схемы. -7. Прогнать этапы 3–7 на подходящей задаче, обновить полевые заметки только - подтверждёнными фактами и убрать поглощённый осадок. -8. Измерить, сколько длинных отчётов реально попало в контекст мастера. - Цель — каждый полный артефакт читается не более одного раза и больше не - пересказывается между агентами. - -## Известные ловушки - -- Простое исключение `!codex/.codex/agents/*.toml` может не сработать, пока - не раскрыты игнорируемые родительские каталоги. Нужны положительные и - отрицательные проверки `git check-ignore`. -- Текущее рабочее дерево dotfiles содержит посторонние изменения. Работать - от сохранённой точки отсчёта, не очищать и не включать их в коммиты. -- `task_name` нативного `spawn_agent` — имя треда, а не доказанный выбор - пользовательской конфигурации агента. -- Полный fork `all` несовместим с другой ролью, моделью и глубиной. Плейбук - использует `none` для свежего контекста; ограниченный fork числом - технически допускает переопределения. -- Некоторые tool-backed хосты скрывают поля управления моделью, хотя Codex - их поддерживает. Проверять фактическую схему в начале сессии. -- Права `workspace-write` не гарантируют сеть. Проверку документации и поиск - отмечать как непроверенные, если сеть недоступна. -- Длинный текст в `spawn_agent`, `send_message` или `followup_task` остаётся - в истории мастера. Передавать путь к файлу и короткий вопрос. - -## Suggested skills - -- `$writing-great-skills` — удерживать плотность и предсказуемость скилла. -- `$skill-creator` — валидировать структуру и проводить пробные прогоны. -- `$tdd` — сначала закрепить установку и договоры ролей тестами. -- `$claude-team-review` — независимое ревью после появления TOML и тестов. -- `$conventional-commits` — зафиксировать следующую завершённую поставку. 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 deleted file mode 100644 index 024bcda..0000000 --- a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260712-optika-tonkogo-mastera.md +++ /dev/null @@ -1,52 +0,0 @@ -# Handoff: плейбук возвращён к оптике тонкого мастера - -Дата: 2026-07-12. Для следующей сессии, которая проверит обновлённый скилл на -нетривиальной задаче с кодом, тестами и шумным выводом. - -## Состояние - -Скилл переработан после самоприменения и сравнения с -`claude-subagent-playbook`. Текущий источник поведения — -[`../SKILL.md`](../SKILL.md); это набор приёмов, а не обязательный конвейер. -Нативная механика раскрывается только по выбранной ветке через -[`../references/prompt-templates.md`](../references/prompt-templates.md) и -[`../references/roles.md`](../references/roles.md). - -Факты двух прогонов и ещё непроверенные предположения дистиллированы в -[`../references/lessons.md`](../references/lessons.md). Не переносить -их обратно в основной файл без нового наблюдаемого сбоя. - -Ключевая граница следующей работы: субагент запускается ради конкретной пользы -задаче или контексту мастера. Свежий тред не считается второй независимой -родословной. Права агента не определяют канал результата. Полная полезная -нагрузка не должна проходить через контекст мастера. - -## Что проверено - -- Один свежий обзор проверил переработку через оптику `writing-great-skills` и - исходного Claude-плейбука; все принятые находки закрыты, одно предложение - вернуть `read-only` обоснованно отклонено по принятой практике пользователя. -- `git diff --check` проходит. -- Относительные ссылки и сборка промптов проверялись в ходе итераций; найден и - исправлен пропущенный путь отчёта триажа. -- Посторонние неотслеживаемые скиллы в объём не входят. - -## Следующая сессия - -1. Выбрать одну подходящую задачу с кодом; не создавать искусственный полный - прогон ради проверки скилла. -2. До каждого запуска агента записывать ожидаемую отдельную пользу, после — - сверить её с фактическим вкладом. -3. Измерить только мастерский след: какие полные отчёты или diff всё ещё попали - в его контекст, сколько агентов можно было не запускать. -4. Проверить живые предположения из `references/lessons.md`: управляемость - ролей и стоимости, `workspace-write`-ревью, сеть и файловый канал. -5. Менять скилл только по фактам прогона; дистиллировать поглощённые уроки. - -## Suggested skills - -- `$codex-subagent-playbook` — провести выбранную задачу с новой оптикой. -- `$writing-great-skills` — проверить, что новые уроки не вернули каркас, - дублирование или осадок. -- `$handoff` — заменить эту записку после следующего содержательного прогона. -- `$conventional-commits` — зафиксировать следующую доказанную поставку. diff --git a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260713-1411-review-optics-and-sync.md b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260713-1411-review-optics-and-sync.md deleted file mode 100644 index 13d1732..0000000 --- a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260713-1411-review-optics-and-sync.md +++ /dev/null @@ -1,55 +0,0 @@ -# Handoff: оптика ревью и синхронизация - -## Назначение - -Продолжить полевую проверку `codex-subagent-playbook` после согласования -тонкого координатора, файлового канала и ревью высокоуровневых документов. -Действующий договор находится в [SKILL.md](../SKILL.md), механика ревью — в -[review-and-triage.md](../references/review-and-triage.md), текущая -маршрутизация — в [roles.md](../references/roles.md). - -## Зафиксированное состояние - -- `6cc1b26` пересобрал скилл вокруг оптики тонкого мастера. -- `70b18b9` убрал shell-зависимые и конвейерные допущения из шаблонов. -- `02a98df` закрепил ревью на уровне самого документа: открытые детали - реализации не мешают `APPROVED`, существенный отложенный риск можно вернуть - как неблокирующее соображение. -- `quick_validate.py`, `git diff --check` и локальные Markdown-ссылки - проходили после изменений. - -## Оптика триажа ревью - -Находки ревьюера — сигналы о возможных слабых местах, а не руководство к -действию. Перед правкой проверять, реальна ли проблема в рамках замысла и не -превращает ли предложенное решение оптику в обязательный конвейер. - -Типичный уклон ревьюера: лечить неоднозначность новыми манифестами, состояниями, -фиксированными именами и преждевременными деталями. Сохранять жёсткими только -границы ответственности, независимость, файловый канал, владельца триажа и -предохранители несходимости. Выбор приёма и модели оставлять оптикой. - -## Незавершённая синхронизация - -Первый `git pull --no-rebase origin master` вернул `Already up to date`. -Следующий `git push origin master` был отклонён: удалённый `master` успел -перейти с `a4985b3` на `9c047f9`. - -Следующему агенту: - -1. Закоммитить этот handoff отдельным Conventional Commit. -2. Выполнить `git fetch origin` и изучить новые удалённые коммиты. -3. Слить `origin/master` обычным merge, сохранив локальный замысел и удалённые - изменения. Не выбирать сторону конфликта целиком без чтения. -4. Повторить проверки скилла и отправить `master` в origin. - -В рабочем дереве есть посторонние неотслеживаемые каталоги скиллов и -`.skill-lock.json`. Они не относятся к этой работе; не добавлять и не удалять -их. - -## Suggested skills - -- `$codex-subagent-playbook` — применять и оценивать текущую оптику. -- `$writing-great-skills` — проверять ясность и отсутствие скрытого процесса. -- `$conventional-commits` — формировать сообщения следующих коммитов. -- `$code-review` — только для нового независимого обзора по явной потребности. diff --git a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260906-1102-coordinator-refactor.md b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260906-1102-coordinator-refactor.md new file mode 100644 index 0000000..2b70e67 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260906-1102-coordinator-refactor.md @@ -0,0 +1,66 @@ +# Состояние после переработки плейбука + +2026-09-06. Партнер завершил обсуждение и попросил сохранить эту записку, +заменить старые handoffs, включить его правку `agents/.agents/skills/.gitignore` +и влить ветку `refactor/codex-subagent-playbook` в `master` через `merge --no-ff`. +Публикацию на удаленный сервер не запрашивал. + +## С чего продолжать + +Дальше полезна обычная задача с новой редакцией скилла. Проверить, удерживает +ли координатор замысел, бюджет внимания и соразмерность после ревью. Партнер +хочет остановить накопление правил по предположениям; следующие изменения +должны опираться на конкретные случаи работы. + +Действующий договор — [SKILL.md](../SKILL.md) и справочники по его указателям. +Роль координатора теперь отделена от модели. Конфигурация Sol-координатор → +Terra-исполнитель допустима, но полного прогона с ней в этой сессии не было. +Открытые вопросы и порядок архивации находятся в +[lessons.md](../references/lessons.md). + +## Где основания решений + +- `65c802f` — принятая спецификация. Доступна через + `git show 65c802f:.scratch/codex-subagent-playbook/spec.md`. +- `3a72ce9` — основной рефакторинг и отчет проверки: + `git show 3a72ce9:.scratch/codex-subagent-playbook/validation.md`. +- Последующие уточнения — коммиты от `781a2e2` до `af86322` включительно. + Актуальные формулировки уже находятся в скилле; ранняя спецификация + описывает состояние до этих уточнений. +- Июльская эмпирика дословно сохранена в + [архиве](../references/lessons-archive.md). Прежние handoffs доступны в Git + по дереву `af86322:agents/.agents/skills/codex-subagent-playbook/handoffs`. + +## Что подтверждено и что осталось проверить + +Основной рефакторинг прошел ревью Claude и узкие перепроверки с `APPROVED`; +ограниченный поведенческий пример прошел три теста. Подробности и ограничения +этой проверки — в отчете коммита `3a72ce9`. Последующие уточнения прошли +вычитку, проверки ссылок, YAML и `git diff --check`; нового независимого +обзора всей последней редакции не было. Это не повод автоматически запускать +ревью постановки следующей задачи: выбор обзора остается ситуативным. + +Штатный `quick_validate.py` не знает сохраненное поле +`disable-model-invocation`. Совместимая копия с удалением только этого поля +проходит проверку. Поле и `allow_implicit_invocation: false` сохраняют явное +включение скилла; удалять их ради зеленого валидатора не следует. + +Точные затраты токенов не измерялись. Наблюдаемые накладные расходы этой +сессии: повторные чтения документов координатором, большой вывод журнала CLI +и уточнение поведения Claude `--resume`. Проверенная механика продолжения +уже записана в [claude.md](../references/claude.md). + +Временные подробные отчеты остались в `/tmp/codex-playbook-refactor.dW8ZC3`; +они могут исчезнуть. Для продолжения достаточно текущих документов и Git. +Состояние веток и завершение слияния проверяй по `git status` и `git log`. +`.scratch/` удаляется последним коммитом ветки перед слиянием; ее содержимое +сохраняется в истории. + +## Рекомендуемые скиллы + +- `codex-subagent-playbook` — по выбору партнера для следующей рабочей задачи. +- `writing-for-agents` — при изменении инструкций и указателей. +- `conventional-commits` — при анализе diff и фиксации изменений. +- `brainstorm-with-docs` — если новый опыт требует пересмотреть решение. +- `tdd` — когда для рабочей задачи выбран этот подход; находить по имени. +- `handoff` — при следующей передаче состояния.