diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index baa667e..aad088e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ { "name": "av-dev", "source": "./av-dev", - "description": "Личный процесс разработки одним плагином: документы проекта, учёт работ и работа по задачам. Документы — канон раскладки (CLAUDE.md плюс docs/: паспорт, архитектура, схема БД, безопасность, конвенции, разведка, ADR, журнал ревью), три операции одной машиной сравнения в doc-canon (check, adopt, upgrade) со скриптом docs.py, заведение нового проекта интервью в doc-init, ведение содержимого по ходу разработки в doc-sync, суд о смысловом здоровье в doc-healthcheck двумя агентами разом. Учёт — задачи и цели каталогом markdown-файлов в task-track, у записи тип (goal, feature, fix, chore, research), и тип решает её схему; приоритет расставляет интерактивный task-groom порядком строк. Работа — одна задача от постановки до закрытия скиллом code-resolve: точка входа одна, сценария три (решение циклом SDD с чекпоинтом, разведка без кода, обслуживание без change), и выбирает сценарий сам скилл, прочитав постановку; плюс конвейер ревью code-review с детерминированным гейтом, сверкой со спеками и обязательным триажем, плюс code-openspec, который заводит и проверяет openspec/. Версия раскладки и настройки живут в .av-dev.toml в корне репозитория. Части включаются следом в проекте, а не установкой: нет docs/ — документы не ведутся, нет каталога задач — учёт остаётся владельцу, нет openspec/ — его заводит сценарий решения. Коммиты — отдельный плагин av-dev-git." + "description": "Личный процесс разработки одним плагином: форма раскладки, документы проекта, учёт работ и работа по задачам. Форму держит скилл canon — три операции одной машиной сравнения (check, adopt, upgrade) со скриптом docs.py и общим журналом версий, по которому повышается вся раскладка, включая каталог задач; имя без префикса, потому что форма общая у всех частей. Документы — канон раскладки (CLAUDE.md плюс docs/: паспорт, архитектура, схема БД, безопасность, конвенции, разведка, ADR, журнал ревью), заведение нового проекта интервью в doc-init, ведение содержимого по ходу разработки в doc-sync, суд о смысловом здоровье в doc-healthcheck двумя агентами разом. Учёт — задачи и цели каталогом markdown-файлов в task-track, у записи тип (goal, feature, fix, chore, research), и тип решает её схему; приоритет расставляет интерактивный task-groom порядком строк. Работа — одна задача от постановки до закрытия скиллом code-resolve: точка входа одна, сценария три (решение циклом SDD с чекпоинтом, разведка без кода, обслуживание без change), и выбирает сценарий сам скилл, прочитав постановку; плюс конвейер ревью code-review с детерминированным гейтом, сверкой со спеками и обязательным триажем, плюс code-openspec, который заводит и проверяет openspec/. Версия раскладки и настройки живут в .av-dev.toml в корне репозитория. Части включаются следом в проекте, а не установкой: нет docs/ — документы не ведутся, нет каталога задач — учёт остаётся владельцу, нет openspec/ — его заводит сценарий решения. Коммиты — отдельный плагин av-dev-git." }, { "name": "av-dev-git", diff --git a/README.md b/README.md index 6f2e289..79c9277 100644 --- a/README.md +++ b/README.md @@ -13,25 +13,33 @@ установку, она не понадобилась ни разу, и плагины слились — [тема 64](decisions/64-three-plugins-merged.md) журнала решений. -Имя **скилла** несёт префикс прежнего плагина: `doc-`, `task-`, `code-`. Вызов -выходит вида `/av-dev:<скилл>`. +Имя **скилла** несёт префикс материала, с которым он работает: `doc-`, `task-`, +`code-`. Вызов выходит вида `/av-dev:<скилл>`. Префикса нет ровно у одного — +`canon`: он работает не с материалом, а с **формой**, общей у всех частей +проекта. -### av-dev — документы, учёт, работа +### av-dev — форма, документы, учёт, работа -**Документы проекта.** Владеют `docs/` и `CLAUDE.md`. +**Форма раскладки.** Одна на весь проект, и держит её один скилл. + +- `canon` — раскладка проекта и её обновление: `check` / `adopt` / `upgrade`, + плюс скрипт `docs.py`. `check` сверяет раскладку документов, `adopt` заводит + все части сразу и зовёт владельцев каталога задач и `openspec/`, `upgrade` + повышает **всю** раскладку по журналу версий — общему, и на документы, и на + каталог задач. Содержимого он не ведёт: это соседние скиллы. + +**Документы проекта.** Владеют **содержимым** `docs/` и `CLAUDE.md`; раскладка — +у `canon`. - `doc-init` — новый проект: интервью по свободному описанию замысла → первичная документация; -- `doc-canon` — привести проект к канону документов: `check` / `adopt` / - `upgrade`, плюс скрипт `docs.py`. Он же ведёт журнал версий раскладки — - общий, и на документы, и на каталог задач; - `doc-healthcheck` — здоровье документации **судом, а не машиной**: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — `doc-consistency` (документы между собой и с openspec) и `doc-code-drift` (факты против кода) — и разбирает урожай порциями. Дорого, поэтому не на каждой задаче. Язык документов вычитывает отдельный агент `doc-wording`, и зовут его не отсюда, а те, кто только что писал текст: - `doc-sync`, `doc-init` и `doc-canon`; + `doc-sync`, `doc-init` и `canon`; - `doc-sync` — содержимое канона по ходу разработки: ADR из архивного `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка архитектуры. @@ -112,10 +120,10 @@ flowchart TB tp["code-resolve
3 сценария: разведка,
решение, обслуживание"] --> rp["code-review
10 агентов-проходов"] osp["code-openspec
заводит и проверяет openspec/"] end - subgraph docsp["документы, владеют docs/"] + canon["canon
форма раскладки всего проекта"] + subgraph docsp["документы, владеют содержимым docs/"] direction LR init["doc-init"] - canon["doc-canon"] docs["doc-sync"] hc["doc-healthcheck"] end @@ -156,14 +164,14 @@ flowchart TB где дом каждого и чего он **не** решает. Скиллы читают эти дома по ссылке, а дословной копией оттуда уезжает лишь то, что обязано лежать внутри промпта. -## Канон документов проекта +## Канон раскладки проекта Все проекты приводятся к одной раскладке — так проще ориентироваться, когда проектов много, и рядом OpenSpec тоже держит строгую структуру. `CLAUDE.md` плюс `docs/` (паспорт, архитектура, база, безопасность, конвенции, разведка, ADR, ревью, задачи) и `openspec/` — **раскладка целиком, роли документов и правило единственного дома живут одним домом**: -[canon.md](av-dev/skills/doc-canon/references/canon.md). Здесь она не +[canon.md](av-dev/skills/canon/references/canon.md). Здесь она не пересказывается: копия перечня путей уже расходилась с домом, и как раз в обязательных — в ней не хватало путей, чьё отсутствие `docs.py check` считает нарушением. @@ -181,9 +189,9 @@ flowchart TB «тема → её дом → что оттуда берётся» — [project-facts.md](av-dev/skills/code-review/references/project-facts.md). -Прийти в старый проект и перевести его на канон — `/av-dev:doc-canon`. +Прийти в старый проект и перевести его на канон — `/av-dev:canon`. Раскладка версионируется, и проекты повышаются по [журналу -версий](av-dev/skills/doc-canon/references/changelog.md). +версий](av-dev/skills/canon/references/changelog.md). **Версия одна, и живёт она в `.av-dev.toml` в корне репозитория** — вместе с настройками: `[docs] migrations` и секция `[tasks]`, которая говорит, где лежит @@ -426,7 +434,7 @@ python3 scripts/copies.py # 0 сошлось, 1 расхождение, 2 р когда он решает; и в скелетах, уезжающих в репозиторий проекта. **Дом ставится в `shared/` только тогда, когда владельца нет.** У адресов -владелец есть: раскладку `docs/` держит `doc-canon`, каталог задач — +владелец есть: раскладку `docs/` держит `canon`, каталог задач — `task-track`, и переносить их наружу значило бы отобрать у владельца его же предмет. Общее без владельца живёт в `shared/`; чужое с владельцем остаётся дома, а потребитель на него ссылается. diff --git a/av-dev/.claude-plugin/plugin.json b/av-dev/.claude-plugin/plugin.json index 7af400f..07f8c84 100644 --- a/av-dev/.claude-plugin/plugin.json +++ b/av-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "av-dev", - "description": "Личный процесс разработки одним плагином: документы проекта, учёт работ и работа по задачам. Документы — канон раскладки (CLAUDE.md плюс docs/: паспорт, архитектура, схема БД, безопасность, конвенции, разведка, ADR, журнал ревью), три операции одной машиной сравнения в doc-canon (check, adopt, upgrade) со скриптом docs.py, заведение нового проекта интервью в doc-init, ведение содержимого по ходу разработки в doc-sync, суд о смысловом здоровье в doc-healthcheck двумя агентами разом. Учёт — задачи и цели каталогом markdown-файлов в task-track, у записи тип (goal, feature, fix, chore, research), и тип решает её схему; приоритет расставляет интерактивный task-groom порядком строк. Работа — одна задача от постановки до закрытия скиллом code-resolve: точка входа одна, сценария три (решение циклом SDD с чекпоинтом, разведка без кода, обслуживание без change), и выбирает сценарий сам скилл, прочитав постановку; плюс конвейер ревью code-review с детерминированным гейтом, сверкой со спеками и обязательным триажем, плюс code-openspec, который заводит и проверяет openspec/. Версия раскладки и настройки живут в .av-dev.toml в корне репозитория. Части включаются следом в проекте, а не установкой: нет docs/ — документы не ведутся, нет каталога задач — учёт остаётся владельцу, нет openspec/ — его заводит сценарий решения. Коммиты — отдельный плагин av-dev-git.", + "description": "Личный процесс разработки одним плагином: форма раскладки, документы проекта, учёт работ и работа по задачам. Форму держит скилл canon — три операции одной машиной сравнения (check, adopt, upgrade) со скриптом docs.py и общим журналом версий, по которому повышается вся раскладка, включая каталог задач; имя без префикса, потому что форма общая у всех частей. Документы — канон раскладки (CLAUDE.md плюс docs/: паспорт, архитектура, схема БД, безопасность, конвенции, разведка, ADR, журнал ревью), заведение нового проекта интервью в doc-init, ведение содержимого по ходу разработки в doc-sync, суд о смысловом здоровье в doc-healthcheck двумя агентами разом. Учёт — задачи и цели каталогом markdown-файлов в task-track, у записи тип (goal, feature, fix, chore, research), и тип решает её схему; приоритет расставляет интерактивный task-groom порядком строк. Работа — одна задача от постановки до закрытия скиллом code-resolve: точка входа одна, сценария три (решение циклом SDD с чекпоинтом, разведка без кода, обслуживание без change), и выбирает сценарий сам скилл, прочитав постановку; плюс конвейер ревью code-review с детерминированным гейтом, сверкой со спеками и обязательным триажем, плюс code-openspec, который заводит и проверяет openspec/. Версия раскладки и настройки живут в .av-dev.toml в корне репозитория. Части включаются следом в проекте, а не установкой: нет docs/ — документы не ведутся, нет каталога задач — учёт остаётся владельцу, нет openspec/ — его заводит сценарий решения. Коммиты — отдельный плагин av-dev-git.", "author": { "name": "Anton Vakhrushev", "email": "anwinged@gmail.com" diff --git a/av-dev/agents/doc-consistency.md b/av-dev/agents/doc-consistency.md index c7d60d0..d94273b 100644 --- a/av-dev/agents/doc-consistency.md +++ b/av-dev/agents/doc-consistency.md @@ -15,12 +15,12 @@ color: yellow машина, а что человек», и её правая колонка — твой устав дословно. Карта домов, по которой ты судишь о правиле 1, — дословная копия канона; дом её -`av-dev/skills/doc-canon/references/canon.md`, раздел «Правило единственного +`av-dev/skills/canon/references/canon.md`, раздел «Правило единственного дома», и правится она там. Здесь она стоит потому, что устав — это твой промпт целиком: за ссылкой ты пошёл бы отдельным чтением, а карта нужна тебе в тот момент, когда ты судишь. - + | Факт | Дом | | --- | --- | | поведение системы | `openspec/specs//spec.md` | diff --git a/av-dev/agents/doc-wording.md b/av-dev/agents/doc-wording.md index d197d83..8f9fd5f 100644 --- a/av-dev/agents/doc-wording.md +++ b/av-dev/agents/doc-wording.md @@ -1,6 +1,6 @@ --- name: doc-wording -description: "Вычитка языка документов проекта по информационному стилю — паспорт, архитектура, конвенции, безопасность, решения ADR, записки разведки, CLAUDE.md. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, «одна мысль — одно предложение», англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта, транслит в имени файла. Отдаёт готовые формулировки на замену и ничего не правит сам. Записи каталога задач вычитывает отдельный агент task-wording, их форму — task-form. Зовётся по названной пачке правленных документов, а не на весь канон: последним шагом синка документации (av-dev:doc-sync), шагом заведения проекта (av-dev:doc-init), шагами adopt и upgrade скилла av-dev:doc-canon. Скилл healthcheck его не зовёт — там сверка утверждений, а не языка. Только чтение." +description: "Вычитка языка документов проекта по информационному стилю — паспорт, архитектура, конвенции, безопасность, решения ADR, записки разведки, CLAUDE.md. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, «одна мысль — одно предложение», англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта, транслит в имени файла. Отдаёт готовые формулировки на замену и ничего не правит сам. Записи каталога задач вычитывает отдельный агент task-wording, их форму — task-form. Зовётся по названной пачке правленных документов, а не на весь канон: последним шагом синка документации (av-dev:doc-sync), шагом заведения проекта (av-dev:doc-init), шагами adopt и upgrade скилла av-dev:canon. Скилл healthcheck его не зовёт — там сверка утверждений, а не языка. Только чтение." tools: Read, Grep, Glob model: sonnet color: green diff --git a/av-dev/shared/absence.md b/av-dev/shared/absence.md index 453ed8e..bc8d307 100644 --- a/av-dev/shared/absence.md +++ b/av-dev/shared/absence.md @@ -31,7 +31,7 @@ | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. diff --git a/av-dev/shared/axes.md b/av-dev/shared/axes.md index 5c8cbe8..713b4e8 100644 --- a/av-dev/shared/axes.md +++ b/av-dev/shared/axes.md @@ -21,7 +21,7 @@ | метка | `small` `medium` `large` | `code-review/SKILL.md`, «Метки» | | режим прогона | с меткой · без метки | здесь, ниже | | стадия ревью | дизайн · код | `code-review/SKILL.md`, «Ревью дизайна» | -| категория документа | тема · источник темы · процессный | `doc-canon/references/canon.md` | +| категория документа | тема · источник темы · процессный | `canon/references/canon.md` | | severity находки | `critical` `major` `minor` `nit` | `code-review/references/finding-contract.md` | | коды выхода | 0 1 2 3 4 | здесь, ниже | diff --git a/av-dev/shared/config.py b/av-dev/shared/config.py index c2903ff..5982f3a 100644 --- a/av-dev/shared/config.py +++ b/av-dev/shared/config.py @@ -55,8 +55,8 @@ LEGACY = ("docs/.docs.json", "docs/.pm.json") LEGACY_TASKS = ".tasks.json" # Версия раскладки — одна на плагин. Журнал версий — references/changelog.md -# скилла `doc-canon`, повышает его операция `upgrade`. -VERSION = 1 +# скилла `canon`, повышает его операция `upgrade`. +VERSION = 2 VERSION_KEY = "version" diff --git a/av-dev/shared/operations.md b/av-dev/shared/operations.md index 46c4125..233ec03 100644 --- a/av-dev/shared/operations.md +++ b/av-dev/shared/operations.md @@ -2,7 +2,7 @@ **Это дом.** Словарь «чем держат проект» назван в трёх местах трёх разных скиллов: секция `Сопровождение` в роадмапе (`task-track`), раздел «Эксплуатация» -в `architecture.md` (`doc-canon`) и тема ревью `operations` (`code-review`). Ни +в `architecture.md` (`canon`) и тема ревью `operations` (`code-review`). Ни один из трёх им не владеет, поэтому дом стоит в `shared/`. Три перечня «чем держат проект» уже разъезжались — на «метриках и логах» против diff --git a/av-dev/skills/doc-canon/SKILL.md b/av-dev/skills/canon/SKILL.md similarity index 92% rename from av-dev/skills/doc-canon/SKILL.md rename to av-dev/skills/canon/SKILL.md index f1ce87f..5096f22 100644 --- a/av-dev/skills/doc-canon/SKILL.md +++ b/av-dev/skills/canon/SKILL.md @@ -1,9 +1,9 @@ --- -name: doc-canon -description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл av-dev:doc-init. +name: canon +description: Форма раскладки проекта под av-dev и её обновление — три операции одной машиной сравнения. check — что разошлось с текущей версией раскладки; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов и вызовом владельцев каталога задач и openspec/; upgrade — повышение проекта с версии N до текущей по журналу версий, и повышается им вся раскладка, включая каталог задач. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию раскладки или когда пришли в старый проект и надо понять, что в нём не так. Имя без префикса намеренно — скилл держит форму всех артефактов проекта, а не один их вид. Содержимое документов ведёт av-dev:doc-sync, форму записей задач — av-dev:task-track, заведение проекта с нуля — av-dev:doc-init. --- -# Приведение проекта к канону +# Форма раскладки проекта Три операции, одна машина сравнения с разными исходами: @@ -13,6 +13,14 @@ description: Привести проект к канону документов | `adopt` | проект в чужой раскладке | перенос в канон | | `upgrade` | канон вырос, проект отстал | по журналу версий | +**Имя без префикса, и это не случайность.** Остальные скиллы названы по +материалу, с которым работают, — `doc-`, `task-`, `code-`; этот работает не с +материалом, а с **формой**, и она у всех частей проекта одна. `check` сверяет +раскладку документов, `adopt` заводит все части сразу и зовёт владельцев каталога +задач и `openspec/`, `upgrade` повышает **всю** раскладку одним журналом версий — +и документы, и каталог задач. Содержимое при этом не его: документы ведёт +`av-dev:doc-sync`, записи задач — `av-dev:task-track`. + **Определение канона — [references/canon.md](references/canon.md).** Здесь оно не пересказывается: два описания одной раскладки разъедутся, и работать будет то, которое прочитали последним. Прочитай его **до** первой правки. @@ -45,7 +53,7 @@ description: Привести проект к канону документов ## Инструмент ``` -ds="$CLAUDE_PLUGIN_ROOT/skills/doc-canon/scripts/docs.py" +ds="$CLAUDE_PLUGIN_ROOT/skills/canon/scripts/docs.py" python3 $ds check --dir <корень> [--base ] # раскладка, ссылки, версия, сверки python3 $ds version --dir <корень> # версия раскладки: скрипта и проекта @@ -128,7 +136,7 @@ capability: незаполненный канон это переходное с | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. diff --git a/av-dev/skills/doc-canon/references/canon.md b/av-dev/skills/canon/references/canon.md similarity index 99% rename from av-dev/skills/doc-canon/references/canon.md rename to av-dev/skills/canon/references/canon.md index 96727c1..5738498 100644 --- a/av-dev/skills/doc-canon/references/canon.md +++ b/av-dev/skills/canon/references/canon.md @@ -6,7 +6,7 @@ [журнала](changelog.md). Литерал в шапке был третьим и отстал на первом же повышении — версию 13 он пережил, объявляя канон двенадцатым. -Это **единственный дом определения канона**. Скиллы `doc-init`, `doc-canon` и `doc-sync` +Это **единственный дом определения канона**. Скиллы `doc-init`, `canon` и `doc-sync` читают его, а не пересказывают: три описания одной раскладки разъедутся, и работать будет то, которое прочитали последним. Меняется канон — меняется этот файл и появляется запись в [changelog.md](changelog.md). @@ -19,7 +19,7 @@ Рядом лежит OpenSpec, у которого структура тоже строгая. Цена принята сознательно: плагин не переносится на чужой репозиторий как есть — -чужой репозиторий **приводится** к канону скиллом `doc-canon`. +чужой репозиторий **приводится** к канону скиллом `canon`. Раскладка отвечает, **где** текст лежит и на какой вопрос отвечает. Каким он должен быть **словами** — общий для всех документов канона файл @@ -527,7 +527,7 @@ kebab-case.** Причина не эстетическая: имя файла с разрез, что между `task-form` и `task-wording`. **Зовутся оба одинаково и одним скиллом — `av-dev:doc-healthcheck`, на весь -канон разом; шагом `adopt` и шагом `upgrade` его зовёт `doc-canon`.** Не на синке +канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке документации: `doc-consistency` на `opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по определению требует двух, и на большинстве задач синк правит один. Пачка, diff --git a/av-dev/skills/doc-canon/references/changelog-before-merge.md b/av-dev/skills/canon/references/changelog-before-merge.md similarity index 100% rename from av-dev/skills/doc-canon/references/changelog-before-merge.md rename to av-dev/skills/canon/references/changelog-before-merge.md diff --git a/av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md b/av-dev/skills/canon/references/changelog-tasks-before-merge.md similarity index 100% rename from av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md rename to av-dev/skills/canon/references/changelog-tasks-before-merge.md diff --git a/av-dev/skills/doc-canon/references/changelog.md b/av-dev/skills/canon/references/changelog.md similarity index 77% rename from av-dev/skills/doc-canon/references/changelog.md rename to av-dev/skills/canon/references/changelog.md index 0f29fff..905d237 100644 --- a/av-dev/skills/doc-canon/references/changelog.md +++ b/av-dev/skills/canon/references/changelog.md @@ -1,7 +1,7 @@ # Журнал версий раскладки Одна запись на версию. Проект знает свою версию из ключа `version` в -`.av-dev.toml`; операция `upgrade` скилла `av-dev:doc-canon` идёт по записям +`.av-dev.toml`; операция `upgrade` скилла `av-dev:canon` идёт по записям снизу вверх от версии проекта до текущей и делает то, что в них названо. Правило записи: **что добавилось, что переехало, что удалено, что сделать @@ -22,6 +22,37 @@ --- +## Версия 2 — 2026-08-13 + +Скилл `doc-canon` стал `canon`: префикс называл материал (`doc-`), а скилл +занят не материалом, а **формой** — раскладкой всех частей проекта и общим +повышением версии. Ни один файл проекта от этого не переехал; сменились **путь к +скрипту** и **имя вызова**, а оба живут в проекте: первый — строкой гейта, второй +— в `CLAUDE.md` и в записях задач. + +**Что переехало в вызовах.** `av-dev:doc-canon` → `av-dev:canon`. Прочие имена не +тронуты. + +**Что сделать проекту.** + +1. **Поправить шаг гейта.** Путь к `docs.py` сменился вместе с именем каталога + скилла: `skills/doc-canon/scripts/docs.py` → + `skills/canon/scripts/docs.py`. Шаг, который не нашёл скрипт, обязан + краснеть, а не пропускаться, — проверь, что он краснеет. +2. **Поправить свои вызовы скилла** — `grep -rn "doc-canon" --exclude-dir=.git .` + по проекту целиком: имя встречается в `CLAUDE.md`, в `Taskfile`, в записях + задач и в документах канона. Прежнее полное имя не разрешится вовсе. +3. **Поднять версию** — `docs.py bump`. Последним шагом. +4. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия + дрейфа. + +**Проект, не прошедший запись 1, переименовывает дважды подряд** — `skills/canon/` +→ `skills/doc-canon/` записью 1 и обратно этой. Порядок записей от этого не +меняется: каждая исполняется на том состоянии, которое оставила предыдущая, и +прошлая запись под новое имя не переписывается. + +--- + ## Версия 1 — 2026-08-13 Три плагина — `av-dev-docs`, `av-dev-tasks` и `av-dev-code` — слились в один, diff --git a/av-dev/skills/doc-canon/references/skeletons.md b/av-dev/skills/canon/references/skeletons.md similarity index 99% rename from av-dev/skills/doc-canon/references/skeletons.md rename to av-dev/skills/canon/references/skeletons.md index 113a417..2a93c16 100644 --- a/av-dev/skills/doc-canon/references/skeletons.md +++ b/av-dev/skills/canon/references/skeletons.md @@ -1,6 +1,6 @@ # Скелеты документов канона -Что кладут `init` и `doc-canon adopt` в незаполненный слот. Правило одно: +Что кладут `init` и `canon adopt` в незаполненный слот. Правило одно: **честная информативная строка вместо заглушки**. Проход читает строку как факт; `` он читает как пробел, и `docs.py check` о таком плейсхолдере напоминает. @@ -209,7 +209,7 @@ Верно одно из трёх: - + - **дорогой откат** — переделка стоит дороже переписывания одного файла; - **намеренный отказ** от очевидного подхода; - **пересмотр прежнего решения** — тогда у старой записи обязателен статус diff --git a/av-dev/skills/doc-canon/scripts/docs.py b/av-dev/skills/canon/scripts/docs.py similarity index 99% rename from av-dev/skills/doc-canon/scripts/docs.py rename to av-dev/skills/canon/scripts/docs.py index 7e33a02..275bf79 100644 --- a/av-dev/skills/doc-canon/scripts/docs.py +++ b/av-dev/skills/canon/scripts/docs.py @@ -316,7 +316,7 @@ def check_version(root: Path, cfg: dict, rep: Report) -> None: if got < LAYOUT_VERSION: rep.error( f"проект приведён к раскладке версии {got}, текущая — {LAYOUT_VERSION}:" - f" нужно повышение (скилл av-dev:doc-canon, операция upgrade)" + f" нужно повышение (скилл av-dev:canon, операция upgrade)" ) elif got > LAYOUT_VERSION: rep.error( @@ -373,7 +373,7 @@ def check_legacy(root: Path, rep: Report) -> None: f"нет {CONFIG}, а настройки лежат по прежней раскладке" f" ({', '.join(legacy)}) — она осталась от трёх плагинов, которые" f" слились в один: перенеси значения и удали старые файлы операцией" - f" upgrade скилла av-dev:doc-canon (журнал, версия 1). Прежние имена не" + f" upgrade скилла av-dev:canon (журнал, версия 1). Прежние имена не" f" читаются, поэтому в этом прогоне всё остальное проверено так, будто" f" настроек нет вовсе" ) diff --git a/av-dev/skills/code-openspec/SKILL.md b/av-dev/skills/code-openspec/SKILL.md index 112f5c2..a3f17e2 100644 --- a/av-dev/skills/code-openspec/SKILL.md +++ b/av-dev/skills/code-openspec/SKILL.md @@ -138,7 +138,7 @@ python3 $os form # слепок формы против жив ## Кто зовёт этот скилл - `av-dev:doc-init` — шагом заведения нового проекта, до первого документа; -- `av-dev:doc-canon` в режиме `adopt` — если на переводимом проекте каталога нет +- `av-dev:canon` в режиме `adopt` — если на переводимом проекте каталога нет или `config.yaml` остался примером; - `av-dev:code-resolve` и `av-dev:code-review` — не вызовом по ходу, а отсылкой: OpenSpec у обоих жёсткая предпосылка, и на проекте без каталога оба посылают @@ -160,7 +160,7 @@ python3 $os form # слепок формы против жив | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. @@ -188,7 +188,7 @@ python3 $os form # слепок формы против жив ## Чего этот скилл не делает - **Не пишет спеки и предложения.** Это `opsx:propose` и конвейер задачи. -- **Не ведёт документы канона** — их дом скилл `av-dev:doc-canon`, и адреса в +- **Не ведёт документы канона** — их дом скилл `av-dev:canon`, и адреса в `context` только на них ссылаются. - **Не чинит расхождение формы с версией OpenSpec в проекте.** Оно чинится в плагине: константы скрипта, образец здесь, запись в журнал версий канона. diff --git a/av-dev/skills/code-openspec/scripts/openspec.py b/av-dev/skills/code-openspec/scripts/openspec.py index 072fc9e..69e1039 100644 --- a/av-dev/skills/code-openspec/scripts/openspec.py +++ b/av-dev/skills/code-openspec/scripts/openspec.py @@ -216,7 +216,7 @@ def check_form(root: Path, rep: Report) -> None: rep.skip( f"{where} в проекте нет — ссылка на него в context не " f"требуется. Документы канона проект не завёл, и без них " - f"конвейер работает вслепую: заводит их av-dev:doc-canon" + f"конвейер работает вслепую: заводит их av-dev:canon" ) continue if pointer not in live: diff --git a/av-dev/skills/code-resolve/SKILL.md b/av-dev/skills/code-resolve/SKILL.md index c155915..12e894b 100644 --- a/av-dev/skills/code-resolve/SKILL.md +++ b/av-dev/skills/code-resolve/SKILL.md @@ -66,7 +66,7 @@ description: "Взять одну задачу и довести её до за | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. @@ -97,7 +97,7 @@ description: "Взять одну задачу и довести её до за карта «что где» — `references/project-facts.md` конвейера ревью. **Документов канона нет — проект к нему не приведён.** Скажи это строкой и -предложи скилл `av-dev:doc-canon`: одна операция на проект против поразрядной +предложи скилл `av-dev:canon`: одна операция на проект против поразрядной деградации на каждой задаче. Работу при этом не останавливай. ## Вход diff --git a/av-dev/skills/code-resolve/references/maintain.md b/av-dev/skills/code-resolve/references/maintain.md index ec03ad1..b940c89 100644 --- a/av-dev/skills/code-resolve/references/maintain.md +++ b/av-dev/skills/code-resolve/references/maintain.md @@ -333,7 +333,7 @@ Change ты не передаёшь — его нет. Список документов и их триггеров здесь не дублируется — он в чек-листе скилла `av-dev:doc-sync`; копия уже однажды разошлась с оригиналом. Документов канона в проекте нет — синка нет вовсе: скажи это исходом и предложи завести канон -скиллом `av-dev:doc-canon`. +скиллом `av-dev:canon`. ### 6. Коммит diff --git a/av-dev/skills/code-resolve/references/research.md b/av-dev/skills/code-resolve/references/research.md index 9d3acdf..63e8a3f 100644 --- a/av-dev/skills/code-resolve/references/research.md +++ b/av-dev/skills/code-resolve/references/research.md @@ -32,7 +32,7 @@ **Отсутствие канона бьёт по разведке сильнее, чем по решению**, и сказать об этом строкой мало: без документов у ответа нет дома, и знание осядет в переписке. -Назови исход и предложи `av-dev:doc-canon`; работу не останавливай, но адрес +Назови исход и предложи `av-dev:canon`; работу не останавливай, но адрес ответа тогда выбираешь сам и говоришь об этом вслух. ## Что этот сценарий требует от входа @@ -267,7 +267,7 @@ git и читается диффом, а второй стоп на каждой перечня адресов неотличим от доклада о ненаписанном. **Документов канона в проекте нет** — писать ответ некуда: назови это исходом, -предложи завести канон скиллом `av-dev:doc-canon` и оставь ответ в докладе +предложи завести канон скиллом `av-dev:canon` и оставь ответ в докладе целиком, чтобы работа не пропала. Заводить `docs/` мимо канона нельзя. ### 5. Задачи: завести и уточнить diff --git a/av-dev/skills/code-resolve/references/solve.md b/av-dev/skills/code-resolve/references/solve.md index 4c99c81..0f567c5 100644 --- a/av-dev/skills/code-resolve/references/solve.md +++ b/av-dev/skills/code-resolve/references/solve.md @@ -333,7 +333,7 @@ flowchart TD триггера. **Документов канона в проекте нет** — синка нет вовсе: назови это исходом и -предложи завести канон скиллом `av-dev:doc-canon`. Придумывать раскладку под +предложи завести канон скиллом `av-dev:canon`. Придумывать раскладку под задачу нельзя: документ, заведённый мимо канона, окажется вторым домом ровно тому, что канон потом заведёт своим. diff --git a/av-dev/skills/code-review/SKILL.md b/av-dev/skills/code-review/SKILL.md index 718e1cd..9da9bc3 100644 --- a/av-dev/skills/code-review/SKILL.md +++ b/av-dev/skills/code-review/SKILL.md @@ -54,7 +54,7 @@ description: "Конвейер ревью изменения, устроенны непроверенная ветка деградации хуже честного отказа. Заводить руками не надо: этим владеет скилл `av-dev:code-openspec` — он заводит каталог и заменяет пример в `config.yaml` настройкой. Его же зовут `av-dev:doc-init` на новом - проекте и `av-dev:doc-canon` в режиме `adopt` — на переводимом. + проекте и `av-dev:canon` в режиме `adopt` — на переводимом. **Предпосылка эта — про изменение поведения, а не про всякий прогон:** сценарий обслуживания зовёт конвейер без change и без дельта-спек, и ни один проход его плана на них не завязан. См. «Прогон без change». @@ -83,7 +83,7 @@ description: "Конвейер ревью изменения, устроенны | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. @@ -132,7 +132,7 @@ description: "Конвейер ревью изменения, устроенны критерий, по которому судит изменение. `adr.*`, `research.*` и `tasks/` не открывает никто. -Дом канона этой раскладки — скилл `av-dev:doc-canon`, раздел «Три категории +Дом канона этой раскладки — скилл `av-dev:canon`, раздел «Три категории документов». Конвейер её **читатель**: категории и имена тем он берёт оттуда и своих не заводит. @@ -191,7 +191,7 @@ description: "Конвейер ревью изменения, устроенны дом для тех же фактов разошёлся бы и выглядел актуальным. **Документов канона нет вовсе** — проект не приведён к канону. Скажи это строкой -и предложи скилл `av-dev:doc-canon`: одна операция на проект против деградации на +и предложи скилл `av-dev:canon`: одна операция на проект против деградации на каждой задаче. Прогон при этом не останавливается. ## Что получает каждый проход @@ -1142,7 +1142,7 @@ flowchart TD и где это лежит в документах проекта; таблица поразрядной деградации. - [references/review-levels.md](references/review-levels.md) — дом правила выбора метки: две оси, спорное вниз, чем `small` дешевле, доли как проверка правила. -- Skill `av-dev:doc-canon` — приведение проекта к канону документов. +- Skill `av-dev:canon` — приведение проекта к канону документов. - [references/finding-contract.md](references/finding-contract.md) — контракт находок. - [references/promote.md](references/promote.md) — промоут находка → конвенция → правило → удаление. - [references/calibration.md](references/calibration.md) — калибровка инъекцией, вердикты keep/retune/drop. diff --git a/av-dev/skills/code-review/references/project-facts.md b/av-dev/skills/code-review/references/project-facts.md index 65266a4..da08938 100644 --- a/av-dev/skills/code-review/references/project-facts.md +++ b/av-dev/skills/code-review/references/project-facts.md @@ -8,7 +8,7 @@ и проход читает их напрямую: пути жёсткие, посредник не нужен, а второй дом для тех же фактов разошёлся бы и выглядел актуальным. -Определение канона держит скилл `av-dev:doc-canon`. Здесь только карта «тема → +Определение канона держит скилл `av-dev:canon`. Здесь только карта «тема → её дом → что оттуда берётся». ## Карта тем @@ -118,7 +118,7 @@ строка неотличима от «мы просто не стали» и перестаёт читаться на третьей задаче. **Документов канона нет вовсе** — проект не приведён к канону. Это не повод -работать вслепую: скажи об этом строкой и предложи `av-dev:doc-canon`. Одна +работать вслепую: скажи об этом строкой и предложи `av-dev:canon`. Одна операция на проект против деградации на каждой задаче. ## Правило чтения diff --git a/av-dev/skills/code-review/references/review-journal.md b/av-dev/skills/code-review/references/review-journal.md index e368024..07e4911 100644 --- a/av-dev/skills/code-review/references/review-journal.md +++ b/av-dev/skills/code-review/references/review-journal.md @@ -41,7 +41,7 @@ ## Форма записи **Это дом формы, и у него есть копия.** Скелет `docs/review.md`, который кладёт -в проект `av-dev:doc-canon`, повторяет её дословно — он уезжает в репозиторий и обязан там что-то говорить. Правка формы +в проект `av-dev:canon`, повторяет её дословно — он уезжает в репозиторий и обязан там что-то говорить. Правка формы здесь **обязана** тянуть правку скелета и запись в журнал версий канона; иначе проекты продолжат писать по старой форме, а конвейер — ждать поля, которого нет. Дословность сверяет `scripts/copies.py` маркетплейса по маркерам ниже — но diff --git a/av-dev/skills/doc-healthcheck/SKILL.md b/av-dev/skills/doc-healthcheck/SKILL.md index 634e4c8..671f540 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. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:doc-canon, язык документов — агент doc-wording." +description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording." --- # Здоровье документации @@ -23,7 +23,7 @@ check` и его скрипт; здесь начинается там, где к `architecture.md` и уже живущий в `CLAUDE.md`; - **вернулись к проекту после перерыва** — прежде чем опираться на написанное; - **перед тем как опереться на документ в решении**, если оно дорогое; -- шагом `adopt` и шагом `upgrade` — их зовёт скилл `doc-canon` сам. +- шагом `adopt` и шагом `upgrade` — их зовёт скилл `canon` сам. **Не на каждой задаче и не на каждом синке документации.** Цена реальная: `doc-consistency` идёт на `opus`, потому что сличение утверждений — суждение; @@ -52,7 +52,7 @@ check` и его скрипт; здесь начинается там, где к | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. @@ -132,15 +132,15 @@ check` и его скрипт; здесь начинается там, где к идёт из его собственного отчёта — перечень фактов у него закрытый, и он называет, какие из них проверить было нечем. - Канона в проекте нет вовсе — это исход, а не пустой прогон: скажи строкой и - предложи `av-dev:doc-canon`. + предложи `av-dev:canon`. ## Чего этот скилл не делает -- **Не проверяет раскладку, версию и ссылки** — это `doc-canon check`, там машина. +- **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина. - **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это агент `doc-wording`, и зовут его отдельно, по пачке правленных документов. Звонящие у него названные — последний шаг синка в `av-dev:doc-sync`, шаг 9 - `av-dev:doc-init` и шаг вычитки в обоих режимах `doc-canon`, — просто ни один из + `av-dev:doc-init` и шаг вычитки в обоих режимах `canon`, — просто ни один из них не здесь. У него другой ритм: он нужен там, где текст только что писали, а не там, где он год лежал. Оркестровать его нечем — он один и работает по названному списку. diff --git a/av-dev/skills/doc-init/SKILL.md b/av-dev/skills/doc-init/SKILL.md index 32cede9..9545af6 100644 --- a/av-dev/skills/doc-init/SKILL.md +++ b/av-dev/skills/doc-init/SKILL.md @@ -1,6 +1,6 @@ --- name: doc-init -description: "Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром и скелет остальных документов; первые цели собирает интервью, а записывает их вызовом скилла av-dev:task-track — роадмап принадлежит учёту работ. OpenSpec заводит не сам, а вызовом скилла av-dev:code-openspec — каталог принадлежит конвейеру. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл doc-canon." +description: "Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром и скелет остальных документов; первые цели собирает интервью, а записывает их вызовом скилла av-dev:task-track — роадмап принадлежит учёту работ. OpenSpec заводит не сам, а вызовом скилла av-dev:code-openspec — каталог принадлежит конвейеру. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon." --- # Заведение нового проекта @@ -8,9 +8,9 @@ description: "Завести новый проект — сессия вопро Вход — свободный текст «что мне нужно и почему». Выход — канон документов, с которого дальше работают все остальные скиллы. -**Определение канона — [канон](../doc-canon/references/canon.md).** Прочитай его до +**Определение канона — [канон](../canon/references/canon.md).** Прочитай его до первого вопроса: интервью идёт по слотам канона, а не по вкусу. Что класть в -каждый файл — [скелеты](../doc-canon/references/skeletons.md); не выдумывай заглушки +каждый файл — [скелеты](../canon/references/skeletons.md); не выдумывай заглушки своей формы, `docs.py` узнаёт только плейсхолдер оттуда. ## Что `init` физически не может произвести @@ -90,7 +90,7 @@ description: "Завести новый проект — сессия вопро | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. @@ -133,12 +133,12 @@ description: "Завести новый проект — сессия вопро 5. Напиши заполняемые документы. **Бриф переезжает в `passport.md`** и отдельным файлом не остаётся: два дома для одного замысла разойдутся на первом же уточнении. -6. Заведи скелет остальных по [скелетам](../doc-canon/references/skeletons.md) — +6. Заведи скелет остальных по [скелетам](../canon/references/skeletons.md) — каждый с честной строкой. 7. Каталог задач и первые цели — **вызови скилл `av-dev:task-track`**: он владеет форматом целей и задач. Не разрешился — учёт задач остаётся владельцу, и это тоже строка доклада. -8. `docs.py check` из скилла `doc-canon` — до отсутствия дрейфа. Замечания о +8. `docs.py check` из скилла `canon` — до отсутствия дрейфа. Замечания о незаполненных плейсхолдерах остаются: их закрывает не `init`, а работа. 9. **Вычитай написанное — агент `doc-wording`**, по пачке заполненных документов (`passport.md`, `CLAUDE.md`, `security.md`). Здесь он нужен сильнее, чем где @@ -152,7 +152,7 @@ description: "Завести новый проект — сессия вопро ## Что дальше - Содержимое канона по ходу разработки ведёт скилл `doc-sync`. -- Раскладку проверяет `doc-canon check`. +- Раскладку проверяет `canon check`. - Первую задачу берёт конвейер проекта; `architecture.md` и `conventions/` наполняются его шагом синка, а не заранее. @@ -160,6 +160,6 @@ description: "Завести новый проект — сессия вопро - **Не проектирует систему.** Архитектура выводится из кода, а не наоборот. - **Не пишет код** и не заводит сборку. -- **Не переводит существующий проект** — это `doc-canon adopt`. Признак: в +- **Не переводит существующий проект** — это `canon adopt`. Признак: в репозитории уже есть документация или беклог в какой-то раскладке. - **Не решает за человека**, что важно: цель, границы и периметр — его ответы. diff --git a/av-dev/skills/doc-sync/SKILL.md b/av-dev/skills/doc-sync/SKILL.md index db4e788..88e89ca 100644 --- a/av-dev/skills/doc-sync/SKILL.md +++ b/av-dev/skills/doc-sync/SKILL.md @@ -1,12 +1,12 @@ --- name: doc-sync -description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл av-dev:doc-canon. +description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл av-dev:canon. --- # Ведение содержимого канона -Скилл владеет **содержимым** документов канона; раскладкой владеет `doc-canon`. -Определение канона и роли документов — [канон](../doc-canon/references/canon.md), +Скилл владеет **содержимым** документов канона; раскладкой владеет `canon`. +Определение канона и роли документов — [канон](../canon/references/canon.md), здесь не пересказывается. Главный вызывающий — **шаг синка документации в конвейере задачи**: скилл @@ -106,11 +106,11 @@ description: Вести содержимое документов канона `av-dev:code-resolve`, сценарий разведки: решение, принятое разведкой (намеренный отказ, выбор подхода, «проверили и не делаем»), `design.md` не имеет по построению — change по нему не будет никогда. Промоут при этом тот же: цитата и ссылка, но на записку. -Перечень источников закрыт и живёт в [каноне](../doc-canon/references/canon.md), +Перечень источников закрыт и живёт в [каноне](../canon/references/canon.md), раздел `adr/`. **Триггер заведения, форма имени и правило замены — в -[каноне](../doc-canon/references/canon.md), раздел `adr/`.** Здесь они не +[каноне](../canon/references/canon.md), раздел `adr/`.** Здесь они не повторяются: копия правила расходится с оригиналом на первой же смене версии канона, а расходится незаметно. @@ -126,7 +126,7 @@ description: Вести содержимое документов канона Обзор не держит поведение — его нормативный дом `openspec/specs/`. **Форма маркера долга и правило «гейт от них не краснеет» — в -[каноне](../doc-canon/references/canon.md), раздел `architecture.md`.** +[каноне](../canon/references/canon.md), раздел `architecture.md`.** Разбирается порциями: раздел вычищает та задача, которая его касается. Содержимое не выбрасывается, а переезжает — требования в дельта-спеку change, @@ -136,7 +136,7 @@ description: Вести содержимое документов канона Наблюдение о внешнем мире: что реально шлёт источник, чем документация формата расходится с практикой. **Требование провенанса и правило про расходящееся -число — в [каноне](../doc-canon/references/canon.md), раздел `research/`.** +число — в [каноне](../canon/references/canon.md), раздел `research/`.** Твоя часть — заметить, что по ходу задачи узналось новое о внешних данных, и не дать этому остаться в контексте. Признак: ты правил разбор, опираясь на то, чего @@ -163,7 +163,7 @@ description: Вести содержимое документов канона | учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе | | источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять | -**Свой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`, +**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`, `av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. @@ -191,7 +191,7 @@ description: Вести содержимое документов канона Файл держит два раздела с разными сроками жизни — журнал дефектов и настройку конвейера. **Что в каком и в какой форме — в -[каноне](../doc-canon/references/canon.md), раздел `review.md`**; подробности формы +[каноне](../canon/references/canon.md), раздел `review.md`**; подробности формы записи и выбор адреса, куда она ведёт, — у конвейера ревью: `Skill av-dev:code-review`, его `references/review-journal.md`. @@ -205,7 +205,7 @@ av-dev:code-review`, его `references/review-journal.md`. Находка → конвенция → правило линтера → **удаление из прозы**. Процедура целиком принадлежит конвейеру ревью — его `references/promote.md`, читается через `Skill av-dev:code-review`; роль каталога конвенций — в -[каноне](../doc-canon/references/canon.md). **Прогон идёт вне конвейера** +[каноне](../canon/references/canon.md). **Прогон идёт вне конвейера** (находку принесли руками) — три шага всё равно твои, просто без его процедуры: сформулируй правило, поищи, чем оно механизируется, и вычеркни прозу, если механизировалось. @@ -217,8 +217,8 @@ av-dev:code-review`, его `references/review-journal.md`. ## Чего этот скилл не делает -- **Не проверяет раскладку** — это `doc-canon`. -- **Не заводит недостающие документы** — их скелет кладёт `doc-canon adopt` или +- **Не проверяет раскладку** — это `canon`. +- **Не заводит недостающие документы** — их скелет кладёт `canon adopt` или `doc-init`. - **Не сочиняет содержание.** Нечего записать — так и пишется, честной строкой. - **Не переоформляет документы «заодно»**: правится то, чего коснулась работа. diff --git a/av-dev/skills/task-groom/SKILL.md b/av-dev/skills/task-groom/SKILL.md index 7f8570e..746fb66 100644 --- a/av-dev/skills/task-groom/SKILL.md +++ b/av-dev/skills/task-groom/SKILL.md @@ -244,4 +244,4 @@ flowchart TD себе — формат и содержимое ведёт `task-track` (груминг зовёт его операции). Не решает за человека, что важно: он готовит развилки и рекомендует. Не принимает закрытые задачи отдельным ритуалом — `reopen` есть, момента у него нет. Не судит -документы проекта — это скиллы `av-dev:doc-canon` и `av-dev:doc-healthcheck`. +документы проекта — это скиллы `av-dev:canon` и `av-dev:doc-healthcheck`. diff --git a/av-dev/skills/task-track/SKILL.md b/av-dev/skills/task-track/SKILL.md index 373edc4..9a8dced 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, а повышает проект скилл av-dev:doc-canon по общему журналу версий. Расстановка приоритетов и разбор накопившегося — скилл av-dev:task-groom. Не реализует задачи — этим занимается скилл решения задачи. +description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Каталог отстал от версии раскладки — это скажет tasks.py check, а повышает проект скилл av-dev:canon по общему журналу версий. Расстановка приоритетов и разбор накопившегося — скилл av-dev:task-groom. Не реализует задачи — этим занимается скилл решения задачи. --- # Задачи @@ -511,7 +511,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап Формат каталога задач меняется, и проект должен знать, к какой версии он приведён. Число живёт ключом `version` в `.av-dev.toml` в корне репозитория, -журнал версий — [журнал скилла `doc-canon`](../doc-canon/references/changelog.md), +журнал версий — [журнал скилла `canon`](../canon/references/changelog.md), сверяет их `tasks.py check`: отстало — строка расхождения, ушло вперёд — устарел плагин. Обратной совместимости нет: есть «приведён» и «не приведён». @@ -521,7 +521,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап половины проектов нет. Плагин один — довод ушёл, а два числа оставляли бы вопрос, по какому журналу повышать. -**Повышает проект скилл `av-dev:doc-canon`, операция `upgrade`** — он идёт по +**Повышает проект скилл `av-dev:canon`, операция `upgrade`** — он идёт по журналу, двигает число и зовёт этот скилл там, где запись касается задач. Здесь повышения нет намеренно: две операции, двигающие одно число, разъезжаются на первом же проекте, где прошла только одна из них. @@ -580,7 +580,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап **одним проходом вместе с починкой перекрёстных ссылок**, а не по одному слагу. Если переводить надо не только задачи, а весь `docs/` — это скилл -`av-dev:doc-canon`, и он зовёт этот сценарий сам на своём шаге. +`av-dev:canon`, и он зовёт этот сценарий сам на своём шаге. ### Декомпозиция и штурм сырья @@ -685,7 +685,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап - **Каталог задач — `tasks/` в корне, жёстко**, и `--dir` передаётся явно всегда: раскладка канона одинакова во всех проектах, и искать больше нечего. Каталога нет — код 3 и вопрос человеку; `init` заводит его **только** когда проект - действительно новый, а перевод чужой раскладки делает `av-dev:doc-canon`. + действительно новый, а перевод чужой раскладки делает `av-dev:canon`. У скрипта поиск вверх по дереву ещё жив — он для непереведённых проектов, и полагаться на него скилл не должен: молча найденный чужой каталог это дрейф. - **Версия и настройки живут в `.av-dev.toml` в корне репозитория** — версия diff --git a/av-dev/skills/task-track/references/adopt.md b/av-dev/skills/task-track/references/adopt.md index 680d043..864def6 100644 --- a/av-dev/skills/task-track/references/adopt.md +++ b/av-dev/skills/task-track/references/adopt.md @@ -5,8 +5,8 @@ после неё проект живёт скиллами `task-track` и `task-groom`. **Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл -`av-dev:doc-canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что -форматом задач владеет `task-track`, а не `doc-canon`. Отдельно сценарий вызывается, +`av-dev:canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что +форматом задач владеет `task-track`, а не `canon`. Отдельно сценарий вызывается, когда переводить надо **только** задачи. Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`, diff --git a/av-dev/skills/task-track/scripts/tasks.py b/av-dev/skills/task-track/scripts/tasks.py index 4096b82..370d545 100755 --- a/av-dev/skills/task-track/scripts/tasks.py +++ b/av-dev/skills/task-track/scripts/tasks.py @@ -11,7 +11,7 @@ называется ключом `[tasks] dir`. Каталог принадлежит этому скиллу, а не канону документов: учёт работ ведут и в проекте, который к канону не приведён. Имена частей и **версия раскладки** живут в `.av-dev.toml` в корне; журнал версий — -references/changelog.md скилла doc-canon. +references/changelog.md скилла canon. tasks/ items/ задачи и цели файлами, .md @@ -503,7 +503,7 @@ def _validate_config(data: dict, path: Path) -> dict: if "plan" in unknown: raise Env(f"{path}: ключ «plan» переименован в «roadmap»," f" а PLAN.md — в ROADMAP.md. Повысь проект скиллом" - f" av-dev:doc-canon (upgrade), а не правь ключ в одиночку:" + f" av-dev:canon (upgrade), а не правь ключ в одиночку:" f" файл и ссылки на него переезжают вместе с ним") if unknown: known = sorted({*DEFAULTS, DIR_KEY}) @@ -582,10 +582,10 @@ def version_problems(lay: Layout) -> list[str]: if legacy: return [f"нет {path}, а прежняя раскладка на месте" f" ({', '.join(legacy)}): перенеси настройки и удали старые" - f" файлы операцией upgrade скилла av-dev:doc-canon"] + f" файлы операцией upgrade скилла av-dev:canon"] return [f"нет {path} — версия раскладки не объявлена." f" Заведи файл с «{VERSION_KEY} = {LAYOUT_VERSION}» (журнал" - f" версий — references/changelog.md скилла av-dev:doc-canon)"] + f" версий — references/changelog.md скилла av-dev:canon)"] # Что число целое, уже проверил общий читатель — иначе сюда не дошли бы # вовсе (код 3). Здесь `isinstance` значит ровно «ключ есть». got = conf.version(lay.full) @@ -595,7 +595,7 @@ def version_problems(lay: Layout) -> list[str]: elif got < LAYOUT_VERSION: out.append(f"проект приведён к раскладке версии {got}, текущая —" f" {LAYOUT_VERSION}: нужно повышение по журналу" - f" (скилл av-dev:doc-canon, операция upgrade)") + f" (скилл av-dev:canon, операция upgrade)") elif got > LAYOUT_VERSION: out.append(f"проект приведён к раскладке версии {got}, а скрипт знает" f" {LAYOUT_VERSION}: устарел плагин, обнови маркетплейс") diff --git a/pyproject.toml b/pyproject.toml index db53f8f..1a88477 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,7 +57,7 @@ quote-style = "double" [tool.pyrefly] project-includes = [ "av-dev/skills/task-track/scripts/tasks.py", - "av-dev/skills/doc-canon/scripts/docs.py", + "av-dev/skills/canon/scripts/docs.py", "av-dev/skills/code-openspec/scripts/openspec.py", "scripts/addresses.py", "scripts/copies.py", diff --git a/scripts/addresses.py b/scripts/addresses.py index 82c111e..96956a7 100644 --- a/scripts/addresses.py +++ b/scripts/addresses.py @@ -45,7 +45,7 @@ SKIP_DIRS = {".git", ".venv", "node_modules", "__pycache__", "tmp"} # Владельцы: префикс адреса → скрипт, который этим каталогом и владеет. OWNERS = { - "docs": "av-dev/skills/doc-canon/scripts/docs.py", + "docs": "av-dev/skills/canon/scripts/docs.py", "tasks": "av-dev/skills/task-track/scripts/tasks.py", } @@ -54,10 +54,10 @@ OWNERS = { # Ключ, кончающийся на `/`, — каталог целиком: журнал решений разложен по теме # на файл, и каждый новый файл в нём — журнал по построению, а не по списку. JOURNALS = { - "av-dev/skills/doc-canon/references/changelog.md": "журнал версий раскладки", - "av-dev/skills/doc-canon/references/changelog-before-merge.md": + "av-dev/skills/canon/references/changelog.md": "журнал версий раскладки", + "av-dev/skills/canon/references/changelog-before-merge.md": "журнал версий канона до слияния", - "av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md": + "av-dev/skills/canon/references/changelog-tasks-before-merge.md": "журнал версий формата задач до слияния", "decisions/": "журнал решений", "NOTES.md": "рабочие заметки", @@ -66,8 +66,8 @@ JOURNALS = { # Файлы, где упразднённый адрес назван по делу: карта переездов и сценарии # перевода чужой раскладки. Неизвестные адреса в них проверяются как везде. RETIRED_OK = { - "av-dev/skills/doc-canon/references/canon.md": "карта упразднённых слотов", - "av-dev/skills/doc-canon/SKILL.md": "adopt: что где искать в чужой раскладке", + "av-dev/skills/canon/references/canon.md": "карта упразднённых слотов", + "av-dev/skills/canon/SKILL.md": "adopt: что где искать в чужой раскладке", "av-dev/skills/task-track/references/adopt.md": "перевод чужого каталога задач", }