chore(skills): сохранено состояние плейбука перед слиянием

- Зачем: - Завершена текущая работа и подготовлено продолжение без старых записок. - Что: - Три прежних handoff заменены актуальной запиской со ссылками на решения и проверки. - Включены пользовательские исключения для установленных сторонних скиллов. - Проверка: - Проверены 53 относительные ссылки, 11 якорей, YAML и обе политики включения. - Подтверждены сохранность 11 игнорируемых каталогов и доступность документов в Git. - Пройден git diff --check.
2026-09-06 11:06:16 -04:00
1 parent af8632274b
commit f49b5847f9
@@ -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/
@@ -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` — зафиксировать следующую завершённую поставку.
@@ -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` — зафиксировать следующую доказанную поставку.
@@ -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` — только для нового независимого обзора по явной потребности.
@@ -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` — при следующей передаче состояния.