av/dev-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

вычитка ревью: пережитки трёх плагинов и язык слияния

Browse Source 
Восемнадцать веток «плагина нет» описывали недостижимое: скиллы и агенты теперь
в одном плагине и разрешаются всегда. Где предмет всё же может отсутствовать —
ветка переписана на след в проекте (нет docs/, нет каталога задач, нет
openspec/); где отсутствовать нечему — снята. Туда же анонсы, обещавшие ветку,
которой в разделе больше нет.

Правило копий и его применение разъезжались в одном коммите: правило называло
два законных случая, а absence.md разослан семью копиями по SKILL.md. Назван
третий случай, и разрез проверяемый — файл, который модель получает целиком,
против файла, за которым она идёт отдельным чтением. Заодно сняты объявления
копий там, где копию сменила ссылка, и довод у карты домов в doc-consistency:
он ссылался на отсутствие плагина, хотя устав едет вместе с плагином.

Описания скиллов во фронтматтерах звали снятые короткие имена — по ним скилл не
находится. task-track перестал обещать повышение: версию двигает doc-canon.

Язык: сняты кросс-вызов, опцион и деградация, конверсия и «читатель» в
config.py, charter'ы против уставов, замер против подсчёта, страдательный залог
в журнале. Строка «настройки av-dev» в таблице отсутствия — слово «раскладка»
называло и целое, и его часть.

Мелкое: тема 52 в README была 64, транслит в task-wording машина не проверяет,
мёртвая ветка REQUIRED в addresses.py, ссылки на язык в закрытом журнале.
This commit is contained in:
av
2026-08-13 11:03:11 +03:00
parent 423f9798ef
commit 441469d78d
31 changed files with 158 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DECISIONS.md
+9 -6
View File
@@ -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, значит построчная правка вместо перезаписи.
README.md
+13 -11
View File
@@ -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`, каталог задач —
REMAINING.md
+1 -1
View File
@@ -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`, «Стимулы»). Выродившаяся
строка **хуже отсутствия**: доклад выглядит проверенным.
Приём не правится: это гипотеза об износе, а не находка, и менять работающее по
av-dev/agents/doc-consistency.md
+4 -3
View File
@@ -16,8 +16,9 @@ color: yellow
Карта домов, по которой ты судишь о правиле 1, — дословная копия канона; дом её
`av-dev/skills/doc-canon/references/canon.md`, раздел «Правило единственного
дома», и правится она там. Здесь она стоит потому, что ты работаешь в
репозитории проекта, где плагина может не быть вовсе.
дома», и правится она там. Здесь она стоит потому, что устав — это твой промпт
целиком: за ссылкой ты пошёл бы отдельным чтением, а карта нужна тебе в тот
момент, когда ты судишь.
<!-- копия: карта-домов из 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 бывает и второй — записка
av-dev/agents/doc-wording.md
+1 -1
View File
@@ -31,7 +31,7 @@ color: green
## Правила
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
Дом — `shared/language.md` в репозитории плагина, и там же объяснено, зачем
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
<!-- копия: язык-правила из av-dev/shared/language.md -->
av-dev/agents/task-wording.md
+2 -2
View File
@@ -39,7 +39,7 @@ color: green
## Правила
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
Дом — `shared/language.md` в репозитории плагина, и там же объяснено, зачем
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
<!-- копия: язык-правила из av-dev/shared/language.md -->
@@ -175,7 +175,7 @@ color: green
отдельной задачи — самый дешёвый способ сделать беклог нечитаемым тому, кто
вернётся к нему через квартал.
**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py` —
**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py check` —
про них молчи. Твоё — **транслит**, потому что машина проверяет его эвристикой и
ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — готовый
английский слаг на замену плюс напоминание, что переименование это перенос
av-dev/shared/absence.md
+3 -3
View File
@@ -15,9 +15,9 @@
узнавалась она следом на диске, а не перечнем плагинов. Перечень того, чего
может не быть, стал короче на три имени — механика не изменилась вовсе.
Заведено правило по замеру: к первому расколу оно стояло в пяти местах в пяти
Правило завели по подсчёту: к первому расколу оно стояло в пяти местах в пяти
редакциях, и три из пяти молчали о том, ради чего написано, — что делать, когда
недостающее обнаружено.
недостающее нашлось.
<!-- дом: отсутствие -->
@@ -26,7 +26,7 @@
| Чего нет | Как видно | Чего теперь не делает никто |
| --- | --- | --- |
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
av-dev/shared/config.py
+4 -4
View File
@@ -1,9 +1,9 @@
#!/usr/bin/env python3
"""Служебный файл проекта `.av-dev.toml`: чтение, запись, конверсия старого.
"""Служебный файл проекта `.av-dev.toml`: чтение, запись, узнавание прежних.
**Это дом.** Файл один на весь плагин, поэтому и читатель у него один: `docs.py`
и `tasks.py` берут настройки отсюда, а не каждый своим разбором. Два разбора
одного формата — это два дома для одной схемы, и расходятся они молча: первым
**Это дом.** Файл один на весь плагин, поэтому и разбор у него один: `docs.py`
и `tasks.py` берут настройки отсюда, а не каждый своим кодом. Два разбора одного
формата — это два дома для одной схемы, и расходятся они молча: первым
разъезжается не значение ключа, а то, что скрипт делает, ключа не увидев.
Формат TOML выбран ради **комментариев**: файл лежит в чужом репозитории, и
av-dev/shared/language.md
+1 -1
View File
@@ -4,7 +4,7 @@
канона, для задач и для решений ADR, и хранить его внутри одного из них значило
бы отдать общее правило во владение части. Скиллы читают **этот файл** по
ссылке; дословные **копии**, помеченные разметкой `copies.py`, уезжают только в
charter'ы вычитки — там текст обязан лежать внутри самого промпта, потому что
уставы вычитки — там текст обязан лежать внутри самого промпта, потому что
именно он и есть критерий суждения. Расхождение ловит гейт коммита, а не
внимание.
av-dev/skills/code-openspec/SKILL.md
+4 -3
View File
@@ -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 не запускается: спеки не с чем сверять |
av-dev/skills/code-resolve/SKILL.md
+4 -4
View File
@@ -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` проекта и то, на что он ссылается, если ещё
не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта,
av-dev/skills/code-resolve/references/maintain.md
+3 -3
View File
@@ -7,7 +7,7 @@
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
ход; общее для всех трёх сценариев — вход, обращение к соседним плагинам, правило
ход; общее для всех трёх сценариев — вход, чего может не быть, правило
записанного вопроса, правило необратимого — живёт в SKILL.md и тут не
пересказывается.
@@ -351,8 +351,8 @@ Change ты не передаёшь — его нет.
оставило бы задачу закрытой без следа работы, если шаг 6 упадёт.
**Закрытие тоже коммитится — вторым коммитом, тут же**, сообщением про учёт:
`закрыта задача <slug>`. Плагина нет — ничего не выдумывай: скажи, что учёт
остаётся за владельцем, и назови исход.
`закрыта задача <slug>`. Каталога задач в проекте нет — ничего не выдумывай:
скажи, что учёт остаётся за владельцем, и назови исход.
## Границы: чего обслуживание не делает
av-dev/skills/code-resolve/references/research.md
+12 -10
View File
@@ -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 и читается диффом, а второй стоп на каждой
учёт, а не про работу: `закрыта задача <slug>`. Правило «одна разведка — один
коммит» про работу, а учёт — не работа.
Плагина в проекте нет — **ничего не выдумывай**: скажи в докладе, что учёт задач
остаётся за владельцем, и назови исход.
Каталога задач в проекте нет — **ничего не выдумывай**: скажи в докладе, что
учёт задач остаётся за владельцем, и назови исход.
## Доклад разведки
av-dev/skills/code-resolve/references/solve.md
+5 -5
View File
@@ -6,7 +6,7 @@
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило
ход; общее для всех трёх сценариев — вход, чего может не быть, правило
записанного вопроса, правило необратимого — живёт в SKILL.md и тут не
пересказывается.
@@ -364,8 +364,8 @@ flowchart TD
работу: `закрыта задача <slug>`. Это второй коммит осознанно: правило «одна задача
— один осмысленный коммит» про работу, а учёт — не работа.
Плагина в проекте нет — вызов не разрешится. Тогда **ничего не выдумывай**: скажи
в докладе, что учёт задач остаётся за владельцем, и назови исход.
Каталога задач в проекте нет — **ничего не выдумывай**: скажи в докладе, что
учёт задач остаётся за владельцем, и назови исход.
## Доклад решения
@@ -394,8 +394,8 @@ flowchart TD
расхождение с одобренным — отдельным пунктом доклада.
- **Заведение задач из урожая ревью — не твоя работа.** Отложенные находки
отдаются **списком**; превращает их в задачи `av-dev:task-track`, у него на
этот вход отдельный сценарий «задачи из ревью и аудита». Плагина нет — урожай
остаётся списком в докладе, и это говорится строкой.
этот вход отдельный сценарий «задачи из ревью и аудита». Каталога задач в
проекте нет — урожай остаётся списком в докладе, и это говорится строкой.
- **Способ решения ты не выбираешь.** Он приходит известным: из постановки, из
разведки, от человека. Выбор между двумя подходами с разной ценой делается в
разведке, у своего чекпоинта, — не по ходу этого сценария.
av-dev/skills/code-review/SKILL.md
+4 -4
View File
@@ -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):
находка → конвенция → правило линтера → **удаление формулировки из конвенций**.
av-dev/skills/code-review/references/calibration.md
+2 -2
View File
@@ -55,7 +55,7 @@ stateDiagram-v2
поведения библиотеки и драйвера**, — и находка, воспроизведённая числом, отменила
решение, принятое по ощущению.
## Состав проходов принадлежит плагину, а не проекту
## Состав проходов принадлежит скиллу, а не проекту
Проходы общие. Проект не может удалить проход — он может **не звать** его, и
тогда это идёт строкой «не запускался» в границы покрытия, как любой другой
@@ -67,7 +67,7 @@ stateDiagram-v2
- **правка charter'а — правка для всех проектов.** Прежде чем сужать
формулировку под свою боль, проверь, не место ли ей в документах проекта: предмет проверки
живёт там, метод — в charter'е;
- **удаление прохода из плагина требует замера на двух проектах**, а не на одном:
- **удаление прохода из конвейера требует замера на двух проектах**, а не на одном:
класс, не всплывший здесь, мог быть единственным работающим там.
## Пробы дефектов по проходам
av-dev/skills/doc-canon/SKILL.md
+12 -9
View File
@@ -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 <rev>] # раскладка, ссылки, версия, сверки
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`), а ручной проход по нескольким записям
подряд — ровно то место, где половина шага делается и забывается. Судьи и есть
av-dev/skills/doc-canon/references/canon.md
+5 -6
View File
@@ -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` по каждой сделанной задаче не окупается, а расхождение между двумя документами по
определению требует двух, и на большинстве задач синк правит один. Пачка,
av-dev/skills/doc-canon/references/changelog-before-merge.md
+2 -2
View File
@@ -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`.
av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md
+2 -2
View File
@@ -1,7 +1,7 @@
# Журнал версий формата задач до слияния плагинов
**Журнал закрыт.** У каталога задач была своя версия, пока плагином его ведал
`av-dev-tasks` и ставился он отдельно. Версия теперь одна на всю раскладку —
**Журнал закрыт.** У каталога задач была своя версия, пока его вёл отдельный
плагин `av-dev-tasks`. Версия теперь одна на всю раскладку —
действующий журнал [changelog.md](changelog.md), и переезд числа описан его
записью 1.
av-dev/skills/doc-canon/references/changelog.md
+8 -6
View File
@@ -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 <каталог задач>` — до отсутствия
дрейфа.
**Чего делать не надо.** Переписывать прошлые записи журналов под новые имена.
av-dev/skills/doc-canon/references/skeletons.md
+5 -4
View File
@@ -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 громко, а отставшее число дало бы дрейф молча.
av-dev/skills/doc-healthcheck/SKILL.md
+6 -6
View File
@@ -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`, — просто ни один из
них не здесь. У него другой ритм: он нужен там, где текст только что писали, а
не там, где он год лежал. Оркестровать его нечем — он один и работает по
названному списку.
av-dev/skills/doc-init/SKILL.md
+12 -9
View File
@@ -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`. Признак: в
репозитории уже есть документация или беклог в какой-то раскладке.
- **Не решает за человека**, что важно: цель, границы и периметр — его ответы.
av-dev/skills/doc-sync/SKILL.md
+8 -8
View File
@@ -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`.
- **Не сочиняет содержание.** Нечего записать — так и пишется, честной строкой.
- **Не переоформляет документы «заодно»**: правится то, чего коснулась работа.
av-dev/skills/task-groom/SKILL.md
+4 -4
View File
@@ -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`), и иди дальше. Документов канона в проекте нет —
сверять нечем, и это тоже строка.
## Интерактив
av-dev/skills/task-track/SKILL.md
+11 -13
View File
@@ -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` сам. Путь наружу не выносится вовсе.
Плагина в проекте нет — вызов не разрешится, и вызывающий **не выдумывает путь и
не правит индекс руками**, а сообщает в докладе, что учёт задач остаётся за
владельцем.
Каталога задач в проекте нет — вызывающий **не выдумывает путь и не правит
индекс руками**, а сообщает в докладе, что учёт остаётся за владельцем. Скилл
при этом разрешится: он в том же плагине, что и вызывающий.
## Слоты проекта
av-dev/skills/task-track/references/adopt.md
+1 -1
View File
@@ -6,7 +6,7 @@
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
`av-dev:doc-canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
форматом задач владеет `tasks`, а не `canon`. Отдельно сценарий вызывается,
форматом задач владеет `task-track`, а не `doc-canon`. Отдельно сценарий вызывается,
когда переводить надо **только** задачи.
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
av-dev/skills/task-track/references/task-chore.md
+2 -2
View File
@@ -66,8 +66,8 @@
у работы, не меняющей поведения, дельта-спек нет по построению. Тип записи там
только **предлагает** сценарий, а подтверждает его отсутствие дельт: разошлись —
работа останавливается, и это тот самый случай, когда тип, оставшийся от первой
формулировки, врёт. Плагина нет — задача решается как проект привык, а этот скилл
её только заводит и закрывает.
формулировки, врёт. Задачу ведут не этим процессом — она решается как проект
привык, а этот скилл её только заводит и закрывает.
## Что видит машина, а что человек
scripts/addresses.py
+7 -6
View File
@@ -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)}
scripts/diagrams.py
+1 -1
View File
@@ -3,7 +3,7 @@
Диаграммы заведены там, где структура — граф или автомат: порядок проходов
ревью, жизненный цикл записи по индексам, исходы задачи в спринте, храповик
промоута, счётчик калибровки, граф вызовов между плагинами.
промоута, счётчик калибровки, граф вызовов между скиллами.
Проверка нужна по одной причине: **синтаксическая ошибка в блоке не видна при
чтении**. Текст диаграммы выглядит правдоподобно, `git diff` показывает разумную