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

документация: README, TODO и журнал решений знают про один плагин

Browse Source 
README переписан под два плагина: состав скиллов с префиксами, диаграмма одним
контуром, команды установки и обновления, раздел версий про .av-dev.toml. Правка
про копии сказала главное — копия была платой за неразрешимый путь, а не за
важность правила, и внутри одного дерева остаётся только там, где текст обязан
лежать в промпте.

DECISIONS: тема 64 с замером цены раскола и четырьмя следствиями. Довод «а вдруг
понадобится» снят наблюдением: режим, ради которого раскол держали, покрыт
сценарием обслуживания.
This commit is contained in:
av
2026-08-13 10:33:44 +03:00
parent 95c9499f06
commit a00e132f29
3 changed files with 227 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+152 -135
View File
@@ -9,83 +9,98 @@
## Плагины
- **av-dev-docs** — документация проекта. Владеет `docs/` и `CLAUDE.md`.
- `init` — новый проект: интервью по свободному описанию замысла → первичная
документация;
- `canon` — привести проект к канону документов: `check` / `adopt` /
`upgrade`, плюс скрипт `docs.py`. Там же лежит копия языка проектных
текстов — информационный стиль, англицизмы, жаргон; дом у него общий,
`shared/language.md`;
- `healthcheck` — здоровье документации **судом, а не машиной**: не разошлись
ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом —
`doc-consistency` (документы между собой и с openspec) и `doc-code-drift`
(факты против кода) — и разбирает урожай порциями. Дорого, поэтому не на
каждой задаче. Язык документов вычитывает отдельный агент `doc-wording`, и
зовут его не отсюда, а те, кто только что писал текст: `docs`, `init` и
`canon`;
- `docs` — содержимое канона по ходу разработки: ADR из архивного
`design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка
архитектуры.
- **av-dev-tasks** — учёт работ. Владеет каталогом задач.
- `tasks` — задачи и цели каталогом markdown-файлов, у каждой записи тип
(`goal`, `feature`, `fix`, `chore`, `research`), и тип задаёт её схему;
вычитывают их два отдельных прохода: `task-form` (форма записи) и
`task-wording` (язык записей);
- `groom` — груминг беклога: что сейчас самое важное и что перестало быть
важным. Ответ записывается **порядком строк** — приоритет это свойство
очереди, и живёт он в индексе. Интерактивный: разбирает вопросы пачкой,
переоценивает порциями по 5–8, расставляет верх очереди с доводом на
каждое движение.
- **av-dev-code** — работа по задачам: разведка, решение и проверка сделанного.
Владеет `openspec/`. **Требует OpenSpec и сам его заводит** — кроме сценариев
разведки и обслуживания, которым он не нужен.
- `openspec` — завести, настроить и **проверить** `openspec/` в проекте:
`openspec init`, замена примера в `config.yaml` настройкой канонической
формы, скрипт `openspec.py` (форма файла + сверка слепка с живой версией
инструмента). Каталог принадлежит конвейеру, а не канону: без конвейера он
проекту не нужен, и `docs.py` о нём молчит;
- `resolve` — одна задача от постановки до закрытия. **Точка входа одна, а
сценария три, и выбирает сценарий сам скилл, прочитав постановку:**
классифицировать задачу до вызова человек всё равно не может — «есть ли
очевидный способ решения» и «меняется ли спека» видно после чтения записи.
**Решение** идёт циклом SDD с чекпоинтом после ревью дизайна: объяснение
человеческим языком, повод скорректировать ход.
**Обслуживание** (тип `chore`: тулчейн и сборка, зависимости, гит-хуки,
перенос, чистка) change не заводит и планового стопа не имеет вовсе: дельта-спек
у него нет **по построению**, то есть цикл SDD здесь не урезан, а остаётся без
входа. Ревью идёт фиксированным планом без метки и без разметчика — `autotests`
и `operations`, плюс `conventions` с техническим разбором, если дифф трогает
код; главный шаг сценария — синк документации, потому что обслуживание чаще
прочих двигает как раз те факты, которые сверяются с кодом. Правка гейта
сверяется по составу проверок, а не по цвету. Нашлась дельта-спека — задача
**оказалась шире своего типа**: работа останавливается, тип называется
(`fix` или `feature`), человек получает объяснение простым языком и два
решения — переформулировать запись и решать её процессом того типа следующим
прогоном либо прекратить; «доделать как обслуживание» решением не является.
**Разведка** (тип `research`, сырая идея, мутная постановка) кода не пишет
вовсе: её чекпоинт — варианты, 2–4 способа решить с ценой каждого, — стоит до
первого написанного требования, а исход уезжает в документы канона и в
задачи. Обе пачки — документы и записи — **вычитываются перед коммитом**
своими проходами: `doc-wording` по документам, `task-form` и `task-wording`
по записям. Выбранный способ реализуется **следующим прогоном**, и запускает его
человек: смена сценария по ходу — событие с названным исходом, а не тихий
поворот. Все три сценария лежат справочниками и одинаково —
`references/solve.md`, `references/maintain.md` и `references/research.md`; в
самом скилле только вход, развилка и правила, не зависящие от сценария.
OpenSpec нужен решению, разведке и обслуживанию — нет;
- `review` — конвейер ревью **по темам**: документ проекта либо
заводит тему проверки, либо питает чужую тему источником, либо процессный и в
ревью не читается вовсе. Разметка идёт **один раз на задачу**, сразу после
`propose`: агент `review-scope` меряет изменение по двум осям — размер и
сложность — и берёт метку как максимум по ним. Одна метка правит **обе**
стадии ревью: дизайна (`small` — только сверка спек; `medium` — плюс
рубрика; `large` — плюс архитектурный проход) и кода (`small` — гейт, спеки,
код, триаж; `medium` — плюс приёмник тем; `large` — плюс доказательство:
запуск, замер, построенный путь, 5–10% задач). Десять агентов-проходов.
- **av-dev-git** — `commit`: сообщения в личном стиле.
Плагина два: **av-dev** — весь процесс, и **av-dev-git** — сообщения коммитов,
работающие в любом репозитории. До 13 августа 2026 процесс жил тремя плагинами
(`av-dev-docs`, `av-dev-tasks`, `av-dev-code`); раскол делался под раздельную
установку, она не понадобилась ни разу, и плагины слились — тема 52
[DECISIONS.md](DECISIONS.md).
Соглашение об именах: имя **плагина** длинное с префиксом `av-dev-`, имена
**скилов** внутри — короткие. Вызов выходит вида `/av-dev-<плагин>:<скилл>`.
Имя **скилла** несёт префикс прежнего плагина: `doc-`, `task-`, `code-`. Вызов
выходит вида `/av-dev:<скилл>`.
### av-dev — документы, учёт, работа
**Документы проекта.** Владеют `docs/` и `CLAUDE.md`.
- `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` — содержимое канона по ходу разработки: ADR из архивного
`design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка
архитектуры.
**Учёт работ.** Владеет каталогом задач.
- `task-track` — задачи и цели каталогом markdown-файлов, у каждой записи тип
(`goal`, `feature`, `fix`, `chore`, `research`), и тип задаёт её схему;
вычитывают их два отдельных прохода: `task-form` (форма записи) и
`task-wording` (язык записей);
- `task-groom` — груминг беклога: что сейчас самое важное и что перестало быть
важным. Ответ записывается **порядком строк** — приоритет это свойство
очереди, и живёт он в индексе. Интерактивный: разбирает вопросы пачкой,
переоценивает порциями по 5–8, расставляет верх очереди с доводом на каждое
движение.
**Работа по задачам.** Владеет `openspec/`. **Сценарий решения требует OpenSpec
и заводит его сам** — разведке и обслуживанию он не нужен.
- `code-openspec` — завести, настроить и **проверить** `openspec/` в проекте:
`openspec init`, замена примера в `config.yaml` настройкой канонической формы,
скрипт `openspec.py` (форма файла + сверка слепка с живой версией
инструмента). Каталог принадлежит конвейеру, а не канону: без конвейера он
проекту не нужен, и `docs.py` о нём молчит;
- `code-resolve` — одна задача от постановки до закрытия. **Точка входа одна, а
сценария три, и выбирает сценарий сам скилл, прочитав постановку:**
классифицировать задачу до вызова человек всё равно не может — «есть ли
очевидный способ решения» и «меняется ли спека» видно после чтения записи.
**Решение** идёт циклом SDD с чекпоинтом после ревью дизайна: объяснение
человеческим языком, повод скорректировать ход.
**Обслуживание** (тип `chore`: тулчейн и сборка, зависимости, гит-хуки,
перенос, чистка) change не заводит и планового стопа не имеет вовсе:
дельта-спек у него нет **по построению**, то есть цикл SDD здесь не урезан, а
остаётся без входа. Ревью идёт фиксированным планом без метки и без
разметчика — `autotests` и `operations`, плюс `conventions` с техническим
разбором, если дифф трогает код; главный шаг сценария — синк документации,
потому что обслуживание чаще прочих двигает как раз те факты, которые
сверяются с кодом. Правка гейта сверяется по составу проверок, а не по цвету.
Нашлась дельта-спека — задача **оказалась шире своего типа**: работа
останавливается, тип называется (`fix` или `feature`), человек получает
объяснение простым языком и два решения — переформулировать запись и решать её
процессом того типа следующим прогоном либо прекратить; «доделать как
обслуживание» решением не является.
**Разведка** (тип `research`, сырая идея, мутная постановка) кода не пишет
вовсе: её чекпоинт — варианты, 2–4 способа решить с ценой каждого, — стоит до
первого написанного требования, а исход уезжает в документы канона и в задачи.
Обе пачки — документы и записи — **вычитываются перед коммитом** своими
проходами: `doc-wording` по документам, `task-form` и `task-wording` по
записям. Выбранный способ реализуется **следующим прогоном**, и запускает его
человек: смена сценария по ходу — событие с названным исходом, а не тихий
поворот. Все три сценария лежат справочниками и одинаково —
`references/solve.md`, `references/maintain.md` и `references/research.md`; в
самом скилле только вход, развилка и правила, не зависящие от сценария;
- `code-review` — конвейер ревью **по темам**: документ проекта либо заводит
тему проверки, либо питает чужую тему источником, либо процессный и в ревью не
читается вовсе. Разметка идёт **один раз на задачу**, сразу после `propose`:
агент `review-scope` меряет изменение по двум осям — размер и сложность — и
берёт метку как максимум по ним. Одна метка правит **обе** стадии ревью:
дизайна (`small` — только сверка спек; `medium` — плюс рубрика; `large` — плюс
архитектурный проход) и кода (`small` — гейт, спеки, код, триаж; `medium` —
плюс приёмник тем; `large` — плюс доказательство: запуск, замер, построенный
путь, 5–10% задач). Десять агентов-проходов.
### av-dev-git
`commit` — сообщения в личном стиле. Отдельным плагином потому, что нужен и в
репозитории, который к канону не приведён и никогда не будет.
Кто кого зовёт. Сплошная стрелка — вызов скилла через пространство имён, не
импорт; пунктир — совет позвать, а не вызов. Агенты-проходы в графе не показаны:
@@ -93,21 +108,23 @@
```mermaid
flowchart TB
subgraph pipe["av-dev-code — исполнение; сценарий решения требует OpenSpec"]
direction LR
tp["resolve<br/>3 сценария: разведка,<br/>решение, обслуживание"] --> rp["review<br/>10 агентов-проходов"]
osp["openspec<br/>заводит и проверяет openspec/"]
end
subgraph docsp["av-dev-docs — документация, владеет docs/"]
direction LR
init["init"]
canon["canon"]
docs["docs"]
hc["healthcheck"]
end
subgraph tasksp["av-dev-tasks — учёт работ"]
direction LR
groom["groom"] --> tasks["tasks"]
subgraph avdev["av-dev — один плагин, девять скиллов"]
subgraph pipe["работа по задачам; сценарий решения требует OpenSpec"]
direction LR
tp["code-resolve<br/>3 сценария: разведка,<br/>решение, обслуживание"] --> rp["code-review<br/>10 агентов-проходов"]
osp["code-openspec<br/>заводит и проверяет openspec/"]
end
subgraph docsp["документы, владеют docs/"]
direction LR
init["doc-init"]
canon["doc-canon"]
docs["doc-sync"]
hc["doc-healthcheck"]
end
subgraph tasksp["учёт работ"]
direction LR
groom["task-groom"] --> tasks["task-track"]
end
end
init --> tasks
init --> osp
@@ -127,18 +144,17 @@ flowchart TB
tp --> tasks
```
Зависимости **взаимные, но каждая мягкая**. `av-dev-code` зовёт обоих соседей;
обратные вызовы тоже есть — `av-dev:doc-init` и `av-dev:doc-canon` заводят
OpenSpec скиллом `av-dev:code-openspec`, `av-dev:doc-sync` берёт у
`av-dev:code-review` форму записи журнала дефектов и процедуру промоута,
`av-dev:doc-canon` и `av-dev:doc-healthcheck` зовут `av-dev:task-track`.
**Мягкая** значит, что у любого вызова есть ветка «не разрешился»: соседа в
проекте нет — вызывающий называет строкой, чего теперь не делает никто, и работу
не останавливает. Как именно зовут соседа и что делают, когда вызов не
разрешился, — `shared/plugin-boundary.md`: правило нужно большинству скиллов, и
ни один плагин им не владеет. То, что нужно нескольким дословно — граница
плагинов, язык проектных текстов, словарь сопровождения, — живёт домом в
`shared/` и уезжает в каждый плагин помеченной копией.
**Скиллы зовут друг друга полным именем, а не по пути.** Внутри одного плагина
путь бы разрешился, но короткое имя разрешается в устаревшую проектную копию из
`.claude/skills/` — молча и без признаков подмены.
**Отсутствовать может не плагин, а часть раскладки проекта**: `docs/`, каталог
задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает
никто, и работу не останавливает. Правило целиком —
[shared/absence.md](av-dev/shared/absence.md): оно нужно почти каждому скиллу, и
ни один им не владеет. Там же, в `shared/`, живут язык проектных текстов и
словарь сопровождения; скиллы читают их по ссылке, а дословной копией они
уезжают только в уставы вычитки — туда, где текст обязан лежать внутри промпта.
## Канон документов проекта
@@ -165,18 +181,21 @@ OpenSpec скиллом `av-dev:code-openspec`, `av-dev:doc-sync` берёт у
«тема → её дом → что оттуда берётся» —
[project-facts.md](av-dev/skills/code-review/references/project-facts.md).
Прийти в старый проект и перевести его на канон — `/av-dev:doc-canon`. Канон
версионируется, и проекты повышаются по [журналу
версий](av-dev/skills/doc-canon/references/changelog.md); версия проекта живёт в
`docs/.docs.json`.
Прийти в старый проект и перевести его на канон — `/av-dev:doc-canon`.
Раскладка версионируется, и проекты повышаются по [журналу
версий](av-dev/skills/doc-canon/references/changelog.md).
**Версий две, и они независимы.** У каталога задач своя — ключ `tasks` в
`<каталог задач>/.tasks.json`, свой [журнал
версий](av-dev/skills/task-track/references/changelog.md) и своё повышение
скиллом `/av-dev:task-track`. Плагины ставятся порознь: у проекта, взявшего учёт
работ без канона документов, `docs/` нет вовсе, и общее число оказалось бы домом,
которого у половины проектов не существует. Имя служебного файла при этом
называет владельца — `.docs.json`, `.tasks.json`, `openspec/config.yaml`.
**Версия одна, и живёт она в `.av-dev.toml` в корне репозитория** — вместе с
настройками: `[docs] migrations` и секция `[tasks]`, где лежит каталог задач и
как названы его части. Версий было две, пока плагинов было три и проект мог
взять учёт работ без канона документов; теперь плагин один, и второе число
означало бы только вопрос, по какому журналу повышать. Прежние
`docs/.docs.json` и `<каталог задач>/.tasks.json` не читаются: увидев их,
`docs.py check` называет прежнюю раскладку и зовёт `upgrade` — запись 1
журнала. Формат TOML взят ради комментариев: файл лежит в репозитории проекта,
и назначение числа читают из него самого, а скрипты правят строку, а не
переписывают файл. Имя служебного файла по-прежнему называет владельца —
`.av-dev.toml`, `openspec/config.yaml`.
## Подключение
@@ -191,9 +210,7 @@ cd /path/to/project
claude plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --scope project
# плагины: scope обязателен, умолчание у команды — user, а нам нужен project
claude plugin install av-dev-docs@av-dev-skills --scope project
claude plugin install av-dev-tasks@av-dev-skills --scope project
claude plugin install av-dev-code@av-dev-skills --scope project
claude plugin install av-dev@av-dev-skills --scope project
claude plugin install av-dev-git@av-dev-skills --scope project
```
@@ -209,9 +226,7 @@ claude plugin install av-dev-git@av-dev-skills --scope project
}
},
"enabledPlugins": {
"av-dev-docs@av-dev-skills": true,
"av-dev-tasks@av-dev-skills": true,
"av-dev-code@av-dev-skills": true,
"av-dev@av-dev-skills": true,
"av-dev-git@av-dev-skills": true
}
}
@@ -240,9 +255,7 @@ claude plugin marketplace update av-dev-skills
# 2. снимки плагинов — из каталога проекта, где они установлены
cd /path/to/project
claude plugin update av-dev-docs@av-dev-skills --scope project
claude plugin update av-dev-tasks@av-dev-skills --scope project
claude plugin update av-dev-code@av-dev-skills --scope project
claude plugin update av-dev@av-dev-skills --scope project
claude plugin update av-dev-git@av-dev-skills --scope project
```
@@ -316,7 +329,7 @@ claude plugin uninstall <плагин>@av-dev-skills --scope project
<plugin>/skills/<skill>/references/ что читается по ссылке из скилла
<plugin>/skills/<skill>/scripts/ tasks.py, docs.py, openspec.py
<plugin>/agents/ charter'ы сабагентов
shared/ дома правил, общих для нескольких плагинов
av-dev/shared/ дома правил и общий читатель .av-dev.toml
scripts/ проверки репозитория и пересборка копий
pyproject.toml линтеры скриптов, только для этого репозитория
lefthook.yml гейт коммита: проверки документов
@@ -398,19 +411,23 @@ python3 scripts/copies.py # 0 сошлось, 1 расхождение, 2 р
сверку не входят. Маркер, уехавший в проект вместе со скелетом, там полезен: он
говорит, что у текста есть дом и правится он там.
**Дом правила, общего для нескольких плагинов, лежит в `shared/` и ни одному из
них не принадлежит.** Так живёт язык проектных текстов: он одинаково нужен
документам канона и задачам, и хранить его внутри одного плагина значило бы
отдать общее правило во владение половине. Так же живёт граница плагинов —
правило обращения к соседу. Плагин везёт копию и потому остаётся
самодостаточным — `shared/` нужен этому репозиторию, а не установленному
плагину.
**Дом правила, общего нескольким скиллам, лежит в `av-dev/shared/` и ни одному
из них не принадлежит.** Так живут язык проектных текстов, словарь
сопровождения и правило об отсутствующих частях раскладки: каждое нужно
многим, и хранить его внутри одного скилла значило бы отдать общее правило во
владение части.
**Копия при этом делается не всегда.** Пока плагинов было три, копия была
единственным способом: путь в дерево соседа не разрешался. Внутри одного дерева
скилл читает дом **по ссылке**, и дословная копия остаётся там, где текст обязан
лежать внутри самого промпта, — в уставах вычитки, где он и есть критерий
суждения, — и в скелетах, уезжающих в репозиторий проекта.
**Дом ставится в `shared/` только тогда, когда владельца нет.** У адресов
владелец есть: раскладку `docs/` держит канон, каталог задач — плагин задач, и
переносить их наружу значило бы отобрать у владельца его же предмет. Общее без
владельца едет копией из `shared/`; чужое с владельцем остаётся дома, а
потребитель на него ссылается.
владелец есть: раскладку `docs/` держит `doc-canon`, каталог задач —
`task-track`, и переносить их наружу значило бы отобрать у владельца его же
предмет. Общее без владельца живёт в `shared/`; чужое с владельцем остаётся
дома, а потребитель на него ссылается.
Скрипт ловит четыре вещи: копия разошлась с домом (с диффом), копия указывает не
на тот файл, дом остался без копий, разметка сломана. Чего он **не** ловит —