diff --git a/DECISIONS.md b/DECISIONS.md index 253df09..20c47e7 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -3928,7 +3928,7 @@ change по нему не будет никогда, — и такое реше верно, но **посылка под ним не проверялась**: за всё время подмножество не понадобилось ни разу, а платился раскол постоянно. -Цена измерена, а не оценена: шестьдесят с лишним кросс-вызовов при цикле +Цена измерена, а не оценена: шестьдесят с лишним вызовов между скиллами при цикле зависимостей `docs → code → docs`, язык проектных текстов четырьмя помеченными копиями по 213 строк, словарь сопровождения двумя, правило границы семью, дюжина веток «плагина нет» — и `copies.py`, заведённый ровно затем, чтобы это @@ -3959,9 +3959,10 @@ change по нему не будет никогда, — и такое реше читаться из него самого, а не из документации плагина. Отсюда правило записи: скрипт правит строку, а не переписывает файл. -**Опцион не потерян.** Понадобится инфраструктурный плагин — расколоть обратно -будет переименованием пространства имён, а не переделкой: граница по-прежнему -держится на следе в проекте. Платить за этот опцион копиями сегодня незачем. +**Возможность расколоть обратно не потеряна.** Понадобится инфраструктурный +плагин — раскол будет переименованием пространства имён, а не переделкой: +граница по-прежнему держится на следе в проекте. Платить за эту возможность +копиями сегодня незачем. ### Что из этого следует @@ -3975,8 +3976,10 @@ change по нему не будет никогда, — и такое реше слиянии или расколе. 220. **Копия дословного текста — плата за неразрешимый путь, а не за важность правила.** Путь разрешился — копия становится вторым домом без причины. - Остаётся она там, где текст обязан лежать внутри промпта: устав агента и - скелет, уезжающий в проект. + Остаётся она там, где текст обязан лежать **внутри промпта**: устав агента, + `SKILL.md` скилла и скелет, уезжающий в проект. Разрез проверяемый: файл, + который модель получает целиком, против файла, за которым она идёт + отдельным чтением. 221. **Формат служебного файла выбирается по тому, кто его читает.** Читает человек в чужом репозитории через полгода — значит комментарии, значит TOML, значит построчная правка вместо перезаписи. diff --git a/README.md b/README.md index a6e5991..4f6b9be 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ ## Плагины -Плагина два: **av-dev** — весь процесс, и **av-dev-git** — сообщения коммитов, -работающие в любом репозитории. До 13 августа 2026 процесс жил тремя плагинами +Плагина два: **av-dev** — весь процесс, и **av-dev-git** — сообщения коммитов. +Второй работает в любом репозитории, в том числе не приведённом к канону. До 13 августа 2026 процесс жил тремя плагинами (`av-dev-docs`, `av-dev-tasks`, `av-dev-code`); раскол делался под раздельную -установку, она не понадобилась ни разу, и плагины слились — тема 52 +установку, она не понадобилась ни разу, и плагины слились — тема 64 [DECISIONS.md](DECISIONS.md). Имя **скилла** несёт префикс прежнего плагина: `doc-`, `task-`, `code-`. Вызов @@ -148,8 +148,8 @@ flowchart TB путь бы разрешился, но короткое имя разрешается в устаревшую проектную копию из `.claude/skills/` — молча и без признаков подмены. -**Отсутствовать может не плагин, а часть раскладки проекта**: `docs/`, каталог -задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает +**Отсутствовать может не плагин, а часть раскладки проекта**: `.av-dev.toml`, +`docs/`, каталог задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает никто, и работу не останавливает. Правило целиком — [shared/absence.md](av-dev/shared/absence.md): оно нужно почти каждому скиллу, и ни один им не владеет. Там же, в `shared/`, живут язык проектных текстов и @@ -186,8 +186,8 @@ flowchart TB версий](av-dev/skills/doc-canon/references/changelog.md). **Версия одна, и живёт она в `.av-dev.toml` в корне репозитория** — вместе с -настройками: `[docs] migrations` и секция `[tasks]`, где лежит каталог задач и -как названы его части. Версий было две, пока плагинов было три и проект мог +настройками: `[docs] migrations` и секция `[tasks]`, которая говорит, где лежит +каталог задач и как названы его части. Версий было две, пока плагинов было три и проект мог взять учёт работ без канона документов; теперь плагин один, и второе число означало бы только вопрос, по какому журналу повышать. Прежние `docs/.docs.json` и `<каталог задач>/.tasks.json` не читаются: увидев их, @@ -375,7 +375,7 @@ python3 scripts/frontmatter.py # 0 в порядке, 1 расхождени а не «имя не то»; - **цвет charter'а, не отвечающий его модели.** Цвет кодирует модель, а не роль прохода — раскладка живёт в - [review/SKILL.md](av-dev/skills/code-review/SKILL.md), + [code-review/SKILL.md](av-dev/skills/code-review/SKILL.md), разделе «Модель по проходу», здесь только её механизация. Держаться вниманием правило не может: цвет ставится один раз при заведении charter'а, а модель потом меняется калибровкой; @@ -419,9 +419,11 @@ python3 scripts/copies.py # 0 сошлось, 1 расхождение, 2 р **Копия при этом делается не всегда.** Пока плагинов было три, копия была единственным способом: путь в дерево соседа не разрешался. Внутри одного дерева -скилл читает дом **по ссылке**, и дословная копия остаётся там, где текст обязан -лежать внутри самого промпта, — в уставах вычитки, где он и есть критерий -суждения, — и в скелетах, уезжающих в репозиторий проекта. +справочник читается **по ссылке**, и дословная копия остаётся ровно там, где +текст обязан лежать **внутри самого промпта**: в уставе агента, где правило и +есть критерий суждения; в `SKILL.md`, который целиком и есть промпт скилла, — за +ссылкой скилл пошёл бы отдельным чтением, а правило нужно ему в тот момент, +когда он решает; и в скелетах, уезжающих в репозиторий проекта. **Дом ставится в `shared/` только тогда, когда владельца нет.** У адресов владелец есть: раскладку `docs/` держит `doc-canon`, каталог задач — diff --git a/REMAINING.md b/REMAINING.md index eb8d42b..7f4895b 100644 --- a/REMAINING.md +++ b/REMAINING.md @@ -84,7 +84,7 @@ check` сверяет версию, но не то, что миграционн смотрели» обязательна в докладе `check`, `adopt`, интейка, штурма и всех пяти агентов канона и задач (`doc-consistency`, `doc-code-drift`, `doc-wording`, `task-form`, `task-wording`) — девять мест, и проверить её исполнение некому: -приёмщик и исполнитель одно лицо (`groom/SKILL.md`, «Стимулы»). Выродившаяся +приёмщик и исполнитель одно лицо (`task-groom/SKILL.md`, «Стимулы»). Выродившаяся строка **хуже отсутствия**: доклад выглядит проверенным. Приём не правится: это гипотеза об износе, а не находка, и менять работающее по diff --git a/av-dev/agents/doc-consistency.md b/av-dev/agents/doc-consistency.md index 360dea1..c7d60d0 100644 --- a/av-dev/agents/doc-consistency.md +++ b/av-dev/agents/doc-consistency.md @@ -16,8 +16,9 @@ color: yellow Карта домов, по которой ты судишь о правиле 1, — дословная копия канона; дом её `av-dev/skills/doc-canon/references/canon.md`, раздел «Правило единственного -дома», и правится она там. Здесь она стоит потому, что ты работаешь в -репозитории проекта, где плагина может не быть вовсе. +дома», и правится она там. Здесь она стоит потому, что устав — это твой промпт +целиком: за ссылкой ты пошёл бы отдельным чтением, а карта нужна тебе в тот +момент, когда ты судишь. | Факт | Дом | @@ -47,7 +48,7 @@ color: yellow Корень проекта. Твоё чтение — `docs/**`, `CLAUDE.md`, `openspec/specs/**` и `openspec/config.yaml`. **Каталог задач не твой** — он лежит в `tasks/` (или в -`docs/tasks/` на непереехавшем проекте), принадлежит другому плагину и ведётся +`docs/tasks/` на непереехавшем проекте), принадлежит другому скиллу и ведётся своим скриптом; не открывай его ни в той форме, ни в другой. Плюс `openspec/changes/archive/`, когда проверяешь ADR: там лежат `design.md`, из которых записи промоутятся. **Источник у ADR бывает и второй — записка diff --git a/av-dev/agents/doc-wording.md b/av-dev/agents/doc-wording.md index 3be0d08..d197d83 100644 --- a/av-dev/agents/doc-wording.md +++ b/av-dev/agents/doc-wording.md @@ -31,7 +31,7 @@ color: green ## Правила -Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем +Дом — `shared/language.md` в репозитории плагина, и там же объяснено, зачем стиль вообще нужен. Здесь только то, что нужно тебе для работы. diff --git a/av-dev/agents/task-wording.md b/av-dev/agents/task-wording.md index 2b8207b..b7098db 100644 --- a/av-dev/agents/task-wording.md +++ b/av-dev/agents/task-wording.md @@ -39,7 +39,7 @@ color: green ## Правила -Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем +Дом — `shared/language.md` в репозитории плагина, и там же объяснено, зачем стиль вообще нужен. Здесь только то, что нужно тебе для работы. @@ -175,7 +175,7 @@ color: green отдельной задачи — самый дешёвый способ сделать беклог нечитаемым тому, кто вернётся к нему через квартал. -**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py` — +**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py check` — про них молчи. Твоё — **транслит**, потому что машина проверяет его эвристикой и ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — готовый английский слаг на замену плюс напоминание, что переименование это перенос diff --git a/av-dev/shared/absence.md b/av-dev/shared/absence.md index dc7f388..453ed8e 100644 --- a/av-dev/shared/absence.md +++ b/av-dev/shared/absence.md @@ -15,9 +15,9 @@ узнавалась она следом на диске, а не перечнем плагинов. Перечень того, чего может не быть, стал короче на три имени — механика не изменилась вовсе. -Заведено правило по замеру: к первому расколу оно стояло в пяти местах в пяти +Правило завели по подсчёту: к первому расколу оно стояло в пяти местах в пяти редакциях, и три из пяти молчали о том, ради чего написано, — что делать, когда -недостающее обнаружено. +недостающее нашлось. @@ -26,7 +26,7 @@ | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | diff --git a/av-dev/shared/config.py b/av-dev/shared/config.py index d0113b2..c2903ff 100644 --- a/av-dev/shared/config.py +++ b/av-dev/shared/config.py @@ -1,9 +1,9 @@ #!/usr/bin/env python3 -"""Служебный файл проекта `.av-dev.toml`: чтение, запись, конверсия старого. +"""Служебный файл проекта `.av-dev.toml`: чтение, запись, узнавание прежних. -**Это дом.** Файл один на весь плагин, поэтому и читатель у него один: `docs.py` -и `tasks.py` берут настройки отсюда, а не каждый своим разбором. Два разбора -одного формата — это два дома для одной схемы, и расходятся они молча: первым +**Это дом.** Файл один на весь плагин, поэтому и разбор у него один: `docs.py` +и `tasks.py` берут настройки отсюда, а не каждый своим кодом. Два разбора одного +формата — это два дома для одной схемы, и расходятся они молча: первым разъезжается не значение ключа, а то, что скрипт делает, ключа не увидев. Формат TOML выбран ради **комментариев**: файл лежит в чужом репозитории, и diff --git a/av-dev/shared/language.md b/av-dev/shared/language.md index 2749bff..f2945c7 100644 --- a/av-dev/shared/language.md +++ b/av-dev/shared/language.md @@ -4,7 +4,7 @@ канона, для задач и для решений ADR, и хранить его внутри одного из них значило бы отдать общее правило во владение части. Скиллы читают **этот файл** по ссылке; дословные **копии**, помеченные разметкой `copies.py`, уезжают только в -charter'ы вычитки — там текст обязан лежать внутри самого промпта, потому что +уставы вычитки — там текст обязан лежать внутри самого промпта, потому что именно он и есть критерий суждения. Расхождение ловит гейт коммита, а не внимание. diff --git a/av-dev/skills/code-openspec/SKILL.md b/av-dev/skills/code-openspec/SKILL.md index 72e691d..6eaaa71 100644 --- a/av-dev/skills/code-openspec/SKILL.md +++ b/av-dev/skills/code-openspec/SKILL.md @@ -7,11 +7,12 @@ description: "Завести и настроить OpenSpec в проекте Каталог `openspec/` — **предпосылка конвейера**, а не канона документов. Без него не работают ни `opsx:propose`, ни ревью дизайна, ни `review-specs`: у требований -не остаётся дома. Поэтому заводит и настраивает его этот плагин — тот, кто по +не остаётся дома. Поэтому заводит и настраивает его этот скилл — тот, кто по OpenSpec и работает. Канон документов о файле не высказывается вовсе: `docs.py` его не открывает и об -его отсутствии молчит. Проект без конвейера живёт без OpenSpec законно, и +его отсутствии молчит. Проект, не ведущий задачи циклом SDD, живёт без OpenSpec +законно, и проверять там нечего. За каноном остаётся одно — **единственный дом**: не пересказан ли в `context` документ, у которого есть свой файл. Это суждение, а не форма, и смотрит его агент. @@ -134,7 +135,7 @@ python3 $os form # слепок формы против жив | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | diff --git a/av-dev/skills/code-resolve/SKILL.md b/av-dev/skills/code-resolve/SKILL.md index d228ffe..a6cf1a9 100644 --- a/av-dev/skills/code-resolve/SKILL.md +++ b/av-dev/skills/code-resolve/SKILL.md @@ -61,7 +61,7 @@ description: "Взять одну задачу и довести её до за | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | @@ -87,9 +87,9 @@ description: "Взять одну задачу и довести её до за -Скилл зовёт `av-dev:code-review`, `av-dev:doc-sync` и -`av-dev:task-track`. Чем оборачивается отсутствие каждого — на самих шагах и в -разделе «Границы». +Скилл зовёт `av-dev:code-review`, `av-dev:doc-sync` и `av-dev:task-track` — +все трое в этом же плагине и разрешаются всегда. Чем оборачивается отсутствие +части раскладки, под которую они работают, сказано на самих шагах сценариев. Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта, diff --git a/av-dev/skills/code-resolve/references/maintain.md b/av-dev/skills/code-resolve/references/maintain.md index 92e2173..ec03ad1 100644 --- a/av-dev/skills/code-resolve/references/maintain.md +++ b/av-dev/skills/code-resolve/references/maintain.md @@ -7,7 +7,7 @@ Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел «Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его -ход; общее для всех трёх сценариев — вход, обращение к соседним плагинам, правило +ход; общее для всех трёх сценариев — вход, чего может не быть, правило записанного вопроса, правило необратимого — живёт в SKILL.md и тут не пересказывается. @@ -351,8 +351,8 @@ Change ты не передаёшь — его нет. оставило бы задачу закрытой без следа работы, если шаг 6 упадёт. **Закрытие тоже коммитится — вторым коммитом, тут же**, сообщением про учёт: -`закрыта задача `. Плагина нет — ничего не выдумывай: скажи, что учёт -остаётся за владельцем, и назови исход. +`закрыта задача `. Каталога задач в проекте нет — ничего не выдумывай: +скажи, что учёт остаётся за владельцем, и назови исход. ## Границы: чего обслуживание не делает diff --git a/av-dev/skills/code-resolve/references/research.md b/av-dev/skills/code-resolve/references/research.md index 7fde100..9d3acdf 100644 --- a/av-dev/skills/code-resolve/references/research.md +++ b/av-dev/skills/code-resolve/references/research.md @@ -6,7 +6,7 @@ Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел «Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его -ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило +ход; общее для всех трёх сценариев — вход, чего может не быть, правило необратимого, доклад — живёт в SKILL.md и тут не пересказывается. **Разведка кончается своим исходом, а не переходом к коду.** Выбранный способ @@ -20,7 +20,7 @@ **OpenSpec этому сценарию не нужен**, и это единственное место скилла, где он не предпосылка. Разведка не заводит change и не пишет дельта-спеки: её артефакты — документы канона и записи каталога задач. Скилл `opsx:explore` полезен и зовётся, -когда плагин в проекте есть; не разрешился — разведка идёт чтением документов, +когда внешний плагин установлен; не разрешился — разведка идёт чтением документов, кода и внешних источников, и это говорится строкой доклада, а не отменяет работу. @@ -28,7 +28,7 @@ `av-dev:doc-sync` (ответ уезжает в документы канона), `av-dev:task-track` (задачи заводятся и уточняются), `av-dev-git:commit`. Правило обращения к соседям -и ветка «вызов не разрешился» — общие, они в [SKILL.md](../SKILL.md). +и правило «чего может не быть» — общие, они в [SKILL.md](../SKILL.md). **Отсутствие канона бьёт по разведке сильнее, чем по решению**, и сказать об этом строкой мало: без документов у ответа нет дома, и знание осядет в переписке. @@ -37,7 +37,8 @@ ## Что этот сценарий требует от входа -Вход общий у обоих сценариев (SKILL.md, раздел «Вход»); своего здесь три условия. +Вход общий у всех трёх сценариев (SKILL.md, раздел «Вход»); своего здесь три +условия. **Паспорт читается раньше кода.** Граница домена и «чем проект **не** является» отсекают половину вариантов до того, как их начнут сравнивать, — а сравнение @@ -288,8 +289,8 @@ git и читается диффом, а второй стоп на каждой способ надуть беклог: она порождает идеи быстрее, чем кто-либо успевает их оценивать, а заведённая задача живёт, пока её кто-то не выкинет руками. -Плагина нет — задачи остаются **списком формулировок в докладе**, и это говорится -строкой: учёт работ остаётся за владельцем. +Каталога задач в проекте нет — задачи остаются **списком формулировок в +докладе**, и это говорится строкой: учёт работ остаётся за владельцем. ### 6. Вычитка написанного — до гейта, не после @@ -322,8 +323,9 @@ git и читается диффом, а второй стоп на каждой Ни один проход ничего не правит: они возвращают готовые формулировки, подставляешь их ты — и уже с подставленными идёшь на гейт. -Плагина нет — вызов не разрешится: скажи строкой, что написанное не вычитывал -никто, и обходного пути не выдумывай. +Проходы вычитки — агенты этого же плагина, и разрешаются они всегда. Не +разрешились — это поломка установки, а не раскладки проекта: скажи строкой, что +написанное не вычитывал никто, и обходного пути не выдумывай. ### 7. Гейт и коммит @@ -361,8 +363,8 @@ git и читается диффом, а второй стоп на каждой учёт, а не про работу: `закрыта задача `. Правило «одна разведка — один коммит» про работу, а учёт — не работа. -Плагина в проекте нет — **ничего не выдумывай**: скажи в докладе, что учёт задач -остаётся за владельцем, и назови исход. +Каталога задач в проекте нет — **ничего не выдумывай**: скажи в докладе, что +учёт задач остаётся за владельцем, и назови исход. ## Доклад разведки diff --git a/av-dev/skills/code-resolve/references/solve.md b/av-dev/skills/code-resolve/references/solve.md index bc9483a..4c99c81 100644 --- a/av-dev/skills/code-resolve/references/solve.md +++ b/av-dev/skills/code-resolve/references/solve.md @@ -6,7 +6,7 @@ Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел «Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его -ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило +ход; общее для всех трёх сценариев — вход, чего может не быть, правило записанного вопроса, правило необратимого — живёт в SKILL.md и тут не пересказывается. @@ -364,8 +364,8 @@ flowchart TD работу: `закрыта задача `. Это второй коммит осознанно: правило «одна задача — один осмысленный коммит» про работу, а учёт — не работа. -Плагина в проекте нет — вызов не разрешится. Тогда **ничего не выдумывай**: скажи -в докладе, что учёт задач остаётся за владельцем, и назови исход. +Каталога задач в проекте нет — **ничего не выдумывай**: скажи в докладе, что +учёт задач остаётся за владельцем, и назови исход. ## Доклад решения @@ -394,8 +394,8 @@ flowchart TD расхождение с одобренным — отдельным пунктом доклада. - **Заведение задач из урожая ревью — не твоя работа.** Отложенные находки отдаются **списком**; превращает их в задачи `av-dev:task-track`, у него на - этот вход отдельный сценарий «задачи из ревью и аудита». Плагина нет — урожай - остаётся списком в докладе, и это говорится строкой. + этот вход отдельный сценарий «задачи из ревью и аудита». Каталога задач в + проекте нет — урожай остаётся списком в докладе, и это говорится строкой. - **Способ решения ты не выбираешь.** Он приходит известным: из постановки, из разведки, от человека. Выбор между двумя подходами с разной ценой делается в разведке, у своего чекпоинта, — не по ходу этого сценария. diff --git a/av-dev/skills/code-review/SKILL.md b/av-dev/skills/code-review/SKILL.md index 537d700..ddcb355 100644 --- a/av-dev/skills/code-review/SKILL.md +++ b/av-dev/skills/code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review -description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Разметка задачи идёт один раз, после propose: агент review-scope выводит размер и сложность, из их максимума — метка, и раздаёт темы проходам обеих стадий. Метка правит и ревью дизайна (small — только specs; medium — плюс rubric; large — плюс architecture), и ревью кода (small — гейт, спеки, код, триаж; medium — плюс приёмник тем; large — плюс доказательство: враждебные постановки, эксплуатационный постмортем, архитектурный проход на широком входе). Триаж обязателен всегда. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, проходы с пометкой «держит машину» идут цепочкой, триаж — единственный сток. Проектная специфика приходит из документов канона проекта. Вызывается из скилла resolve — двумя стадиями: ревью дизайна до кода и ревью кода после apply. Третий вызов идёт от сценария обслуживания: без change и без метки, фиксированным планом (autotests, operations, плюс conventions, если тронут код), разметчик при этом не запускается." +description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Разметка задачи идёт один раз, после propose: агент review-scope выводит размер и сложность, из их максимума — метка, и раздаёт темы проходам обеих стадий. Метка правит и ревью дизайна (small — только specs; medium — плюс rubric; large — плюс architecture), и ревью кода (small — гейт, спеки, код, триаж; medium — плюс приёмник тем; large — плюс доказательство: враждебные постановки, эксплуатационный постмортем, архитектурный проход на широком входе). Триаж обязателен всегда. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, проходы с пометкой «держит машину» идут цепочкой, триаж — единственный сток. Проектная специфика приходит из документов канона проекта. Вызывается из скилла av-dev:code-resolve — двумя стадиями: ревью дизайна до кода и ревью кода после apply. Третий вызов идёт от сценария обслуживания: без change и без метки, фиксированным планом (autotests, operations, плюс conventions, если тронут код), разметчик при этом не запускается." --- # Конвейер ревью @@ -78,7 +78,7 @@ description: "Конвейер ревью изменения, устроенны | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | @@ -1002,8 +1002,8 @@ flowchart TD какой change). Заведение задач принадлежит `av-dev:task-track` — зови его со списком урожая, у него на этот вход отдельный сценарий «задачи из ревью и аудита»: свой формат, кластеризация по причине, дедуп против беклога и - кладбища. Плагина нет — урожай остаётся списком в отчёте, и это говорится - строкой доклада: задачи из него не заведёт никто. Мелочь класса `nit` + кладбища. Каталога задач в проекте нет — урожай остаётся списком в отчёте, и + это говорится строкой доклада: задачи из него не заведёт никто. Мелочь класса `nit` идёт в урожай одной пачкой, а не записью на находку. - `Promote candidates` — по процедуре [references/promote.md](references/promote.md): находка → конвенция → правило линтера → **удаление формулировки из конвенций**. diff --git a/av-dev/skills/code-review/references/calibration.md b/av-dev/skills/code-review/references/calibration.md index bea5e50..468afc2 100644 --- a/av-dev/skills/code-review/references/calibration.md +++ b/av-dev/skills/code-review/references/calibration.md @@ -55,7 +55,7 @@ stateDiagram-v2 поведения библиотеки и драйвера**, — и находка, воспроизведённая числом, отменила решение, принятое по ощущению. -## Состав проходов принадлежит плагину, а не проекту +## Состав проходов принадлежит скиллу, а не проекту Проходы общие. Проект не может удалить проход — он может **не звать** его, и тогда это идёт строкой «не запускался» в границы покрытия, как любой другой @@ -67,7 +67,7 @@ stateDiagram-v2 - **правка charter'а — правка для всех проектов.** Прежде чем сужать формулировку под свою боль, проверь, не место ли ей в документах проекта: предмет проверки живёт там, метод — в charter'е; -- **удаление прохода из плагина требует замера на двух проектах**, а не на одном: +- **удаление прохода из конвейера требует замера на двух проектах**, а не на одном: класс, не всплывший здесь, мог быть единственным работающим там. ## Пробы дефектов по проходам diff --git a/av-dev/skills/doc-canon/SKILL.md b/av-dev/skills/doc-canon/SKILL.md index 8409345..b49ec57 100644 --- a/av-dev/skills/doc-canon/SKILL.md +++ b/av-dev/skills/doc-canon/SKILL.md @@ -1,6 +1,6 @@ --- name: doc-canon -description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл init. +description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл av-dev:doc-init. --- # Приведение проекта к канону @@ -48,7 +48,8 @@ description: Привести проект к канону документов ds="$CLAUDE_PLUGIN_ROOT/skills/doc-canon/scripts/docs.py" python3 $ds check --dir <корень> [--base ] # раскладка, ссылки, версия, сверки -python3 $ds version --dir <корень> # версия канона скрипта и проекта +python3 $ds version --dir <корень> # версия раскладки: скрипта и проекта +python3 $ds bump --dir <корень> # поднять версию проекта до версии скрипта ``` **Формы `openspec/config.yaml` здесь больше нет.** Каталог принадлежит конвейеру, @@ -103,7 +104,7 @@ capability: незаполненный канон это переходное с | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | @@ -141,7 +142,7 @@ capability: незаполненный канон это переходное с форма», `doc-healthcheck` — на «не разошлись ли утверждения». 3. Доклад: вывод скрипта строкой исхода и **граница покрытия** — что смотрели и чего не смотрели. Если суждение здесь нужно, скажи это строкой и предложи - `healthcheck`, а не зови агентов сам. + `doc-healthcheck`, а не зови агентов сам. Дрейф раскладки чинится переносом; смысловые находки — это либо правка документа, либо задача, если работы больше чем на абзац. @@ -192,8 +193,9 @@ capability), `openspec/config.yaml`. Skill `av-dev:code-openspec`**. Каталог принадлежит конвейеру, и команда заведения с формой файла живут там. Пересказ инвариантов, конвенций и правил ревью из `context` вычисти ссылкой на дом — на переводимом проекте он там - почти наверняка есть. Вызов не разрешился — `docs.py` о каталоге тогда тоже - молчит, и форму `config.yaml` не проверяет никто; скажи это строкой; + почти наверняка есть. Проект решил жить без OpenSpec — `docs.py` о каталоге + тогда тоже молчит, и форму `config.yaml` не проверяет никто; скажи это + строкой; 4. переносы содержимого; 5. каталог задач — **вызови скилл `av-dev:task-track`**, сценарий адаптации: он владеет форматом задач. Он же переименует транслитные слаги в английские и @@ -274,8 +276,9 @@ capability), `openspec/config.yaml`. 3. Иначе иди по [changelog.md](references/changelog.md) снизу вверх от версии проекта до текущей и делай названное в каждой записи. Записи независимы и применяются по порядку. -4. Подними `version` в `.av-dev.toml` до текущей — правь **строку**, а не - переписывай файл: комментарии в нём принадлежат проекту. +4. Подними версию — `docs.py bump`. Он правит **строку**, а не переписывает + файл: комментарии в нём принадлежат проекту. Последним шагом, потому что + число объявляет пройденными записи журнала. 5. `docs.py check`. 6. **Позови судей** — Skill `av-dev:doc-healthcheck`. 7. **Позови вычитку** — агент `doc-wording`, но **только по тем документам, @@ -295,7 +298,7 @@ capability), `openspec/config.yaml`. **Шаг 6 обязателен, и вот почему.** `check` сверяет **число** в `.av-dev.toml` с версией скрипта — и только его. Применена ли запись журнала **по существу**, -он не знает: проект несёт `version = 6` и может не иметь того, чего требовала любая +он не знает: проект несёт `version` текущей версии и может не иметь того, чего требовала любая из пройденных версий. Записи применяются руками (переименовать секцию, проставить типы, дописать раздел каждому `fix`), а ручной проход по нескольким записям подряд — ровно то место, где половина шага делается и забывается. Судьи и есть diff --git a/av-dev/skills/doc-canon/references/canon.md b/av-dev/skills/doc-canon/references/canon.md index 2d46c74..0884da4 100644 --- a/av-dev/skills/doc-canon/references/canon.md +++ b/av-dev/skills/doc-canon/references/canon.md @@ -347,10 +347,10 @@ kebab-case.** Причина не эстетическая: имя файла с **Каталог задач канону не принадлежит.** Его ведёт скилл `task-track` — своим скриптом и своими проверками; где каталог лежит и как названы его части, говорит секция `[tasks]` в `.av-dev.toml`. Версия там одна на всю раскладку: канон и -каталог задач двигаются вместе, потому что двигает их один плагин. +каталог задач двигаются вместе, потому что ведёт их один плагин. Канон **резервирует место** в `docs/` и внутрь не смотрит: `docs.py` каталог не открывает, его отсутствия не считает дрейфом и согласованность -задач не проверяет. Проект, поставивший только канон документов, задач не ведёт +задач не проверяет. Проект, не заведший каталог задач, их не ведёт вовсе, и отказом это быть не может. Раскладку, форму записи и команды держит скилл `av-dev:task-track`. Ниже — то, @@ -379,9 +379,8 @@ kebab-case.** Причина не эстетическая: имя файла с **Схемы записи здесь нет намеренно.** Какие разделы тип требует, нужна ли ему цель и берётся ли он в работу — скилл `av-dev:task-track`, раздел «Тип -записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Ссылки в -дерево того плагина здесь нет намеренно: он ставится отдельно, и путь наружу -разрешился бы не всегда. Канон фиксирует **словарь**, потому что +записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Канон +фиксирует **словарь**, потому что от него зависит, читается ли проект как продукт; схема — механика ведения задач, и второй её экземпляр разошёлся бы с первым (он и разошёлся: канон успел объявить цель у `fix` запрещённой, хотя она там необязательна). @@ -525,7 +524,7 @@ kebab-case.** Причина не эстетическая: имя файла с разрез, что между `task-form` и `task-wording`. **Зовутся оба одинаково и одним скиллом — `av-dev:doc-healthcheck`, на весь -канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке +канон разом; шагом `adopt` и шагом `upgrade` его зовёт `doc-canon`.** Не на синке документации: `doc-consistency` на `opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по определению требует двух, и на большинстве задач синк правит один. Пачка, diff --git a/av-dev/skills/doc-canon/references/changelog-before-merge.md b/av-dev/skills/doc-canon/references/changelog-before-merge.md index 1c60a8d..a9cc12c 100644 --- a/av-dev/skills/doc-canon/references/changelog-before-merge.md +++ b/av-dev/skills/doc-canon/references/changelog-before-merge.md @@ -646,7 +646,7 @@ ADR объясняет прошлое решение, а не предъявля 5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех индексах. Написание канонических секций и отбивку правит `check --fix`; он же сводит написание секции в мете файла с заголовком индекса. -6. **Язык проектных текстов** — [language.md](language.md), общий дом для +6. **Язык проектных текстов** — [language.md](../../../shared/language.md), общий дом для документов канона, задач, решений ADR и записок разведки: информационный стиль (глагол вместо отглагольного существительного, активный залог, факт вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и @@ -711,7 +711,7 @@ ADR объясняет прошлое решение, а не предъявля 11. Переписать заголовки задач в форму действия — по мере того, как задача попадает в работу, а не «заодно»: `check` печатает их число, а `task-form` предложит формулировки на замену пачкой. -12. Прочитать [language.md](language.md) — и **ничего не переписывать задним +12. Прочитать [language.md](../../../shared/language.md) — и **ничего не переписывать задним числом**. Правила языка применяются к тому, что пишется и правится сейчас; сплошная вычитка старых документов стоит дороже, чем даёт. 13. `docs/.pm.json`: `"canon": 3`. diff --git a/av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md b/av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md index a01ccda..ee53712 100644 --- a/av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md +++ b/av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md @@ -1,7 +1,7 @@ # Журнал версий формата задач до слияния плагинов -**Журнал закрыт.** У каталога задач была своя версия, пока плагином его ведал -`av-dev-tasks` и ставился он отдельно. Версия теперь одна на всю раскладку — +**Журнал закрыт.** У каталога задач была своя версия, пока его вёл отдельный +плагин `av-dev-tasks`. Версия теперь одна на всю раскладку — действующий журнал [changelog.md](changelog.md), и переезд числа описан его записью 1. diff --git a/av-dev/skills/doc-canon/references/changelog.md b/av-dev/skills/doc-canon/references/changelog.md index 6b684c1..681ee5f 100644 --- a/av-dev/skills/doc-canon/references/changelog.md +++ b/av-dev/skills/doc-canon/references/changelog.md @@ -1,8 +1,8 @@ # Журнал версий раскладки Одна запись на версию. Проект знает свою версию из ключа `version` в -`.av-dev.toml`; `canon upgrade` идёт по записям снизу вверх от версии проекта до -текущей и делает то, что в них названо. +`.av-dev.toml`; операция `upgrade` скилла `av-dev:doc-canon` идёт по записям +снизу вверх от версии проекта до текущей и делает то, что в них названо. Правило записи: **что добавилось, что переехало, что удалено, что сделать проекту**. Без последнего пункта запись бесполезна — по ней и работает @@ -26,9 +26,9 @@ Три плагина — `av-dev-docs`, `av-dev-tasks` и `av-dev-code` — слились в один, `av-dev`. Раскол делался под раздельную установку: проект мог взять учёт работ -без документов канона или конвейер без обоих. Практикой посылка не подтвердилась -— подмножество не понадобилось ни разу, — а платился раскол помеченными копиями -общих правил и ветками деградации на каждый вызов соседа. +без документов канона или конвейер без обоих. Практика посылку не подтвердила — +подмножество не понадобилось ни разу, — а платился раскол помеченными копиями +общих правил и веткой «плагина нет» на каждый вызов соседа. **Что переехало в проекте.** Служебных файла было два, стал один: @@ -74,7 +74,9 @@ 6. **Поправить свои вызовы скиллов** — в `CLAUDE.md`, в `Taskfile`, в записях задач: короткое имя разрешится в проектную копию, а прежнее полное не разрешится вовсе. -7. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия +7. **Поднять версию** — `docs.py bump`. Последним шагом: число объявляет + пройденными шаги журнала, и раньше времени поднятое врёт. +8. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия дрейфа. **Чего делать не надо.** Переписывать прошлые записи журналов под новые имена. diff --git a/av-dev/skills/doc-canon/references/skeletons.md b/av-dev/skills/doc-canon/references/skeletons.md index 9fe56b7..113a417 100644 --- a/av-dev/skills/doc-canon/references/skeletons.md +++ b/av-dev/skills/doc-canon/references/skeletons.md @@ -1,6 +1,6 @@ # Скелеты документов канона -Что кладут `init` и `canon adopt` в незаполненный слот. Правило одно: +Что кладут `init` и `doc-canon adopt` в незаполненный слот. Правило одно: **честная информативная строка вместо заглушки**. Проход читает строку как факт; `` он читает как пробел, и `docs.py check` о таком плейсхолдере напоминает. @@ -428,9 +428,10 @@ severity стоит здесь, а не выводится каждым прох ## `openspec/config.yaml` -**Образец переехал.** Файл заводит и заполняет конвейер — скилл +**Образец переехал.** Файл заводит и заполняет скилл `av-dev:code-openspec`, — потому что по OpenSpec работает он, а не канон -документов. Проект без конвейера каталога `openspec/` не имеет вовсе, и образец +документов. Проект, не ведущий задачи циклом SDD, каталога `openspec/` не имеет +вовсе, и образец файла, которого у него нет, в скелетах канона лежал бы мёртвым грузом. **Форму не проверяет и `docs.py`** — с канона 10 он о файле молчит вовсе. @@ -455,7 +456,7 @@ dir = "tasks" ``` `<текущая версия>` подставляет `init` или `adopt`, целым числом; берётся она из -`docs.py version` (строка «раскладка скрипта»), а не из памяти. Литерал здесь +`docs.py version` (строка «версия раскладки, скрипт»), а не из памяти. Литерал здесь протухает при каждом повышении, поэтому его тут и нет: незамещённый плейсхолдер ломает разбор TOML громко, а отставшее число дало бы дрейф молча. diff --git a/av-dev/skills/doc-healthcheck/SKILL.md b/av-dev/skills/doc-healthcheck/SKILL.md index c2622c9..634e4c8 100644 --- a/av-dev/skills/doc-healthcheck/SKILL.md +++ b/av-dev/skills/doc-healthcheck/SKILL.md @@ -1,6 +1,6 @@ --- name: doc-healthcheck -description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию канона проверяет скилл canon, язык документов — агент doc-wording." +description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:doc-canon, язык документов — агент doc-wording." --- # Здоровье документации @@ -47,7 +47,7 @@ check` и его скрипт; здесь начинается там, где к | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | @@ -116,8 +116,8 @@ check` и его скрипт; здесь начинается там, где к не с чем, и откладывание превращает её в задачу дороже самой правки. 2. **Работа больше чем на абзац** — задача типа `chore`. Заводит её **не этот скилл**: вызови Skill `av-dev:task-track`, у него свой формат, дедупликация - против беклога и кладбища. Плагина нет — отдай списком в докладе и скажи это - строкой. + против беклога и кладбища. Каталога задач в проекте нет — отдай списком в + докладе и скажи это строкой. 3. **Не находка** — агент ошибся, документ прав. Скажи это прямо: неразобранная находка и отклонённая различаются, и вторая экономит время на следующем прогоне. Класс ошибок, который повторяется, идёт в `docs/review.*`, раздел @@ -136,11 +136,11 @@ check` и его скрипт; здесь начинается там, где к ## Чего этот скилл не делает -- **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина. +- **Не проверяет раскладку, версию и ссылки** — это `doc-canon check`, там машина. - **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это агент `doc-wording`, и зовут его отдельно, по пачке правленных документов. Звонящие у него названные — последний шаг синка в `av-dev:doc-sync`, шаг 9 - `av-dev:doc-init` и шаг вычитки в обоих режимах `canon`, — просто ни один из + `av-dev:doc-init` и шаг вычитки в обоих режимах `doc-canon`, — просто ни один из них не здесь. У него другой ритм: он нужен там, где текст только что писали, а не там, где он год лежал. Оркестровать его нечем — он один и работает по названному списку. diff --git a/av-dev/skills/doc-init/SKILL.md b/av-dev/skills/doc-init/SKILL.md index 8cbfa41..32cede9 100644 --- a/av-dev/skills/doc-init/SKILL.md +++ b/av-dev/skills/doc-init/SKILL.md @@ -34,8 +34,9 @@ description: "Завести новый проект — сессия вопро **`tasks/ROADMAP.md` в таблице нет намеренно.** Первые цели `init` собирает интервью (блок 6), но записывает их не он: каталогом задач и формой целей владеет -`av-dev:task-track`, и это шаг 7. Плагина нет — цели остаются списком в докладе, -роадмапа в проекте не появляется, и это говорится строкой. +`av-dev:task-track`, и это шаг 7. Человек от каталога задач отказался — цели +остаются списком в докладе, роадмапа в проекте не появляется, и это говорится +строкой. ## Порядок интервью — зависимость, а не удобство @@ -84,7 +85,7 @@ description: "Завести новый проект — сессия вопро | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | @@ -110,8 +111,9 @@ description: "Завести новый проект — сессия вопро -Чем оборачивается отсутствие каждого — на самих шагах 3 и 7. Заведение проекта -из-за этого не останавливается: проект без конвейера и без учёта задач законен. +Оба скилла в этом же плагине и разрешаются всегда; чем оборачивается отказ от +того, что они заводят, — на самих шагах 3 и 7. Заведение проекта из-за этого не +останавливается: проект без OpenSpec и без учёта задач законен. ## Порядок работы @@ -123,8 +125,9 @@ description: "Завести новый проект — сессия вопро ни сверка требований. Каталог принадлежит конвейеру, а не канону, поэтому здесь только вызов — ни команды, ни формы файла `init` не знает. - **Вызов не разрешился** — проект без конвейера живёт без OpenSpec законно: - строка доклада, и дальше; `docs.py check` о каталоге тоже промолчит. + **Человек от OpenSpec отказался** — проект живёт без него законно: строка + доклада, и дальше; `docs.py check` о каталоге тоже промолчит. Цикл SDD в + таком проекте не запускается, и это надо назвать, а не обойти. 4. Заведи `.av-dev.toml` в корне с текущей версией раскладки — число берётся из `docs.py version`, а не из памяти. 5. Напиши заполняемые документы. **Бриф переезжает в `passport.md`** и @@ -149,7 +152,7 @@ description: "Завести новый проект — сессия вопро ## Что дальше - Содержимое канона по ходу разработки ведёт скилл `doc-sync`. -- Раскладку проверяет `canon check`. +- Раскладку проверяет `doc-canon check`. - Первую задачу берёт конвейер проекта; `architecture.md` и `conventions/` наполняются его шагом синка, а не заранее. @@ -157,6 +160,6 @@ description: "Завести новый проект — сессия вопро - **Не проектирует систему.** Архитектура выводится из кода, а не наоборот. - **Не пишет код** и не заводит сборку. -- **Не переводит существующий проект** — это `canon adopt`. Признак: в +- **Не переводит существующий проект** — это `doc-canon adopt`. Признак: в репозитории уже есть документация или беклог в какой-то раскладке. - **Не решает за человека**, что важно: цель, границы и периметр — его ответы. diff --git a/av-dev/skills/doc-sync/SKILL.md b/av-dev/skills/doc-sync/SKILL.md index a264b7e..db4e788 100644 --- a/av-dev/skills/doc-sync/SKILL.md +++ b/av-dev/skills/doc-sync/SKILL.md @@ -1,11 +1,11 @@ --- name: doc-sync -description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл canon. +description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл av-dev:doc-canon. --- # Ведение содержимого канона -Скилл владеет **содержимым** документов канона; раскладкой владеет `canon`. +Скилл владеет **содержимым** документов канона; раскладкой владеет `doc-canon`. Определение канона и роли документов — [канон](../doc-canon/references/canon.md), здесь не пересказывается. @@ -158,7 +158,7 @@ description: Вести содержимое документов канона | Чего нет | Как видно | Чего теперь не делает никто | | --- | --- | --- | -| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | +| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет | | документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты | | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | @@ -184,8 +184,8 @@ description: Вести содержимое документов канона -Чем оборачивается отсутствие конвейера — в каждом из двух разделов отдельно: без -него работа не отменяется, отменяется только его процедура. +Здесь это значит: документов канона может не быть вовсе — тогда синка нет, и +это исход, а не повод раскладывать документы по своему усмотрению. ## Запись в `review.md` @@ -217,8 +217,8 @@ av-dev:code-review`, его `references/review-journal.md`. ## Чего этот скилл не делает -- **Не проверяет раскладку** — это `canon`. -- **Не заводит недостающие документы** — их скелет кладёт `canon adopt` или - `init`. +- **Не проверяет раскладку** — это `doc-canon`. +- **Не заводит недостающие документы** — их скелет кладёт `doc-canon adopt` или + `doc-init`. - **Не сочиняет содержание.** Нечего записать — так и пишется, честной строкой. - **Не переоформляет документы «заодно»**: правится то, чего коснулась работа. diff --git a/av-dev/skills/task-groom/SKILL.md b/av-dev/skills/task-groom/SKILL.md index 0b3ef2f..7f8570e 100644 --- a/av-dev/skills/task-groom/SKILL.md +++ b/av-dev/skills/task-groom/SKILL.md @@ -1,6 +1,6 @@ --- name: task-groom -description: "Груминг беклога — интерактивный разбор, отвечающий на два вопроса: что сейчас самое важное и что перестало быть важным. Ответ записывается порядком строк в беклоге: первая строка — то, что делают следующим. Разбирает накопившиеся вопросы, переоценивает задачи порциями по 5–8 (сделано попутно, отменено решением, слилось с соседней, подешевело, разрослось, стало сырьём), закрывает отжившее с причиной и расставляет очередь. Использовать, когда просят разобрать беклог, расставить приоритеты, решить «что делать дальше», провести груминг или переоценку, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое записей — скилл tasks; выполнение задачи — конвейер проекта." +description: "Груминг беклога — интерактивный разбор, отвечающий на два вопроса: что сейчас самое важное и что перестало быть важным. Ответ записывается порядком строк в беклоге: первая строка — то, что делают следующим. Разбирает накопившиеся вопросы, переоценивает задачи порциями по 5–8 (сделано попутно, отменено решением, слилось с соседней, подешевело, разрослось, стало сырьём), закрывает отжившее с причиной и расставляет очередь. Использовать, когда просят разобрать беклог, расставить приоритеты, решить «что делать дальше», провести груминг или переоценку, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое записей — скилл av-dev:task-track; выполнение задачи — конвейер проекта." --- # Груминг: что важно, что перестало @@ -29,7 +29,7 @@ description: "Груминг беклога — интерактивный ра 1. **Порядок назначает человек, машина его не выводит.** Ни давность, ни тип, ни число задач под целью приоритетом не являются. Единственное место в очереди, назначенное не человеком, — конец секции у сырья, и оно из очереди изъято - (`tasks`, правило 4). + (`task-track`, правило 4). 2. **Порция важнее охвата.** Тридцать задач за заход — это усталость и штамповка: последние десять получат «оставить» не потому, что живы, а потому, что разбор затянулся. Лучше две честные порции, чем один полный проход. @@ -164,8 +164,8 @@ flowchart TD Но повод назвать это здесь есть: беклог и документы протухают от одного и того же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан десяток задач, — скажи строкой, что документы стоит сверить -(`av-dev:doc-healthcheck`), и иди дальше. Плагина в проекте нет — сверять нечем, -и это тоже строка. +(`av-dev:doc-healthcheck`), и иди дальше. Документов канона в проекте нет — +сверять нечем, и это тоже строка. ## Интерактив diff --git a/av-dev/skills/task-track/SKILL.md b/av-dev/skills/task-track/SKILL.md index e1bd63a..eabc8b1 100644 --- a/av-dev/skills/task-track/SKILL.md +++ b/av-dev/skills/task-track/SKILL.md @@ -1,6 +1,6 @@ --- name: task-track -description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Он же повышает каталог до текущей версии формата по своему журналу версий, когда tasks.py check говорит, что каталог отстал. Расстановка приоритетов и разбор накопившегося — скилл groom. Не реализует задачи — этим занимается скилл решения задачи. +description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Каталог отстал от версии раскладки — это скажет tasks.py check, а повышает проект скилл av-dev:doc-canon по общему журналу версий. Расстановка приоритетов и разбор накопившегося — скилл av-dev:task-groom. Не реализует задачи — этим занимается скилл решения задачи. --- # Задачи @@ -223,11 +223,10 @@ stateDiagram-v2 **Сопровождение и эксплуатация — целое и часть**, а не синонимы, и та же тема живёт ещё в двух местах: разделе «Эксплуатация» в `architecture.md` и теме ревью -`operations`. Словарь у всех трёх общий, дом у него один — `shared/operations.md` -в репозитории плагинов, — а здесь лежит дословная копия: -[shared/operations.md](../../shared/operations.md). Пересказывать его своими -словами нельзя: три перечня «чем держат проект» уже разъезжались на «метриках и -логах» против «мониторинга». +`operations`. Словарь у всех трёх общий, и дом у него один: +[shared/operations.md](../../shared/operations.md) — читается по ссылке. +Пересказывать его своими словами нельзя: три перечня «чем держат проект» уже +разъезжались на «метриках и логах» против «мониторинга». Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`; тянется долго и очереди не имеет — `Направления`; не про приложение, а про то, @@ -354,11 +353,10 @@ stateDiagram-v2 **Предметно, но без усложнения.** Текст задачи читает человек, который решает, брать её или нет, и делает это по строке индекса и одному экрану тела. -Язык — общий для всех проектных текстов, и дом у него один, -`shared/language.md` в репозитории плагинов; здесь лежит дословная копия: -[shared/language.md](../../shared/language.md) (информационный стиль, +Язык — общий для всех проектных текстов, и дом у него один: +[shared/language.md](../../shared/language.md) — информационный стиль, применённый к задачам и документам канона; там же таблицы англицизмов и жаргона -и то, что из стиля отброшено намеренно). Задаче он даёт четыре требования, +и то, что из стиля отброшено намеренно. Задаче он даёт четыре требования, которые нарушаются чаще прочих: - **глагол вместо отглагольного существительного**: «обработчик не проверяет @@ -701,9 +699,9 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап > («закрой задачу `<слаг>`, реализована»). Скилл разрешает свой > `$CLAUDE_PLUGIN_ROOT` сам. Путь наружу не выносится вовсе. -Плагина в проекте нет — вызов не разрешится, и вызывающий **не выдумывает путь и -не правит индекс руками**, а сообщает в докладе, что учёт задач остаётся за -владельцем. +Каталога задач в проекте нет — вызывающий **не выдумывает путь и не правит +индекс руками**, а сообщает в докладе, что учёт остаётся за владельцем. Скилл +при этом разрешится: он в том же плагине, что и вызывающий. ## Слоты проекта diff --git a/av-dev/skills/task-track/references/adopt.md b/av-dev/skills/task-track/references/adopt.md index 47811e3..680d043 100644 --- a/av-dev/skills/task-track/references/adopt.md +++ b/av-dev/skills/task-track/references/adopt.md @@ -6,7 +6,7 @@ **Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл `av-dev:doc-canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что -форматом задач владеет `tasks`, а не `canon`. Отдельно сценарий вызывается, +форматом задач владеет `task-track`, а не `doc-canon`. Отдельно сценарий вызывается, когда переводить надо **только** задачи. Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`, diff --git a/av-dev/skills/task-track/references/task-chore.md b/av-dev/skills/task-track/references/task-chore.md index 6dc121c..601a729 100644 --- a/av-dev/skills/task-track/references/task-chore.md +++ b/av-dev/skills/task-track/references/task-chore.md @@ -66,8 +66,8 @@ у работы, не меняющей поведения, дельта-спек нет по построению. Тип записи там только **предлагает** сценарий, а подтверждает его отсутствие дельт: разошлись — работа останавливается, и это тот самый случай, когда тип, оставшийся от первой -формулировки, врёт. Плагина нет — задача решается как проект привык, а этот скилл -её только заводит и закрывает. +формулировки, врёт. Задачу ведут не этим процессом — она решается как проект +привык, а этот скилл её только заводит и закрывает. ## Что видит машина, а что человек diff --git a/scripts/addresses.py b/scripts/addresses.py index f4ca068..12b76e3 100644 --- a/scripts/addresses.py +++ b/scripts/addresses.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Сверка чужих адресов в прозе плагинов с перечнем их владельца. +"""Сверка чужих адресов в прозе скиллов с перечнем их владельца. Судится **упразднённое, а не незнакомое**, и это следует из канона, а не из осторожности: список тем открытый — всё, что проект кладёт в `docs/` сверх @@ -9,9 +9,9 @@ единственная догадка — имя, **почти** совпавшее с каноническим: это опечатка с куда большей вероятностью, чем новая тема. -Адрес документа принадлежит одному плагину, а называют его все: `docs/*` стоит -примерно в сорока местах `av-dev-code`, `tasks/ROADMAP.md` — в четырёх местах -`av-dev-docs`. Переименование в каноне до этих мест не доходит. +Адрес документа принадлежит одному скиллу, а называют его все: `docs/*` стоит +примерно в сорока местах конвейера, `tasks/ROADMAP.md` — в четырёх местах +канона. Переименование в каноне до этих мест не доходит. **Почему тут нужна машина, а не аккуратность.** Прогон ревью умеет честно деградировать: дома темы нет — в границах покрытия появляется строка «документа в @@ -123,8 +123,9 @@ def vocabularies(root: Path) -> tuple[dict[str, set[str]], dict[str, str]]: docs_names = {stem(n) for n in docs.DOCS} docs_names |= {stem(n) for n in docs.CONDITIONAL_DOCS} docs_names |= {stem(n) for n in docs.NOT_DOCS} - # `docs/.docs.json` объявлен обязательным файлом вне раскладки. - docs_names |= {stem(Path(p).name) for p in docs.REQUIRED if p.startswith("docs/")} + # Обязательные файлы канона живут вне `docs/` (`CLAUDE.md`, `.av-dev.toml`), + # и в перечень имён внутри каталога не идут вовсе. Ветка осталась бы мёртвой + # молча, поэтому её тут нет: имя служебного файла добавляется ниже поимённо. tasks_names = {stem(tasks.DEFAULTS[k]) for k in tasks.PATH_KEYS} tasks_names |= {stem(tasks.CONFIG_NAME)} diff --git a/scripts/diagrams.py b/scripts/diagrams.py index d2a9127..780d3d4 100644 --- a/scripts/diagrams.py +++ b/scripts/diagrams.py @@ -3,7 +3,7 @@ Диаграммы заведены там, где структура — граф или автомат: порядок проходов ревью, жизненный цикл записи по индексам, исходы задачи в спринте, храповик -промоута, счётчик калибровки, граф вызовов между плагинами. +промоута, счётчик калибровки, граф вызовов между скиллами. Проверка нужна по одной причине: **синтаксическая ошибка в блоке не видна при чтении**. Текст диаграммы выглядит правдоподобно, `git diff` показывает разумную