документация: README, TODO и журнал решений знают про один плагин
README переписан под два плагина: состав скиллов с префиксами, диаграмма одним контуром, команды установки и обновления, раздел версий про .av-dev.toml. Правка про копии сказала главное — копия была платой за неразрешимый путь, а не за важность правила, и внутри одного дерева остаётся только там, где текст обязан лежать в промпте. DECISIONS: тема 64 с замером цены раскола и четырьмя следствиями. Довод «а вдруг понадобится» снят наблюдением: режим, ради которого раскол держали, покрыт сценарием обслуживания.
This commit is contained in:
@@ -3919,3 +3919,64 @@ change по нему не будет никогда, — и такое реше
|
|||||||
когда весь материал для неё у исполнителя. Стоп обязан принести названный
|
когда весь материал для неё у исполнителя. Стоп обязан принести названный
|
||||||
тип, объяснение и закрытый список решений — иначе выбор делается вслепую или
|
тип, объяснение и закрытый список решений — иначе выбор делается вслепую или
|
||||||
не делается вовсе, и работа доезжает до коммита не тем процессом.
|
не делается вовсе, и работа доезжает до коммита не тем процессом.
|
||||||
|
|
||||||
|
|
||||||
|
## 64. Три плагина слились в один: раскол платили, а не пользовались (2026-08-13)
|
||||||
|
|
||||||
|
Плагинов было три — `av-dev-docs`, `av-dev-tasks`, `av-dev-code`, — и разрез
|
||||||
|
между ними шёл по признаку «ставится порознь» (решение 51). Признак был выбран
|
||||||
|
верно, но **посылка под ним не проверялась**: за всё время подмножество не
|
||||||
|
понадобилось ни разу, а платился раскол постоянно.
|
||||||
|
|
||||||
|
Цена измерена, а не оценена: шестьдесят с лишним кросс-вызовов при цикле
|
||||||
|
зависимостей `docs → code → docs`, язык проектных текстов четырьмя помеченными
|
||||||
|
копиями по 213 строк, словарь сопровождения двумя, правило границы семью,
|
||||||
|
дюжина веток «плагина нет» — и `copies.py`, заведённый ровно затем, чтобы это
|
||||||
|
не разъезжалось молча.
|
||||||
|
|
||||||
|
**Довод «а вдруг понадобится» снят наблюдением владельца, а не спором.** Ждали
|
||||||
|
случая «документы и задачи без OpenSpec» — например, ansible-репозиторий. Он
|
||||||
|
уже покрыт: сценарий обслуживания в `resolve` OpenSpec не требует по
|
||||||
|
построению, а `docs.py` считает отсутствие `openspec/` неприменимостью, а не
|
||||||
|
отказом. То есть режим, ради которого держали раскол, работает и в слитом
|
||||||
|
плагине.
|
||||||
|
|
||||||
|
**Слияние оказалось дешевле, чем выглядело, потому что граница была сделана
|
||||||
|
правильно.** Присутствие соседа узнавалось **следом в проекте**
|
||||||
|
(`.docs.json`, `.tasks.json`, `openspec/config.yaml`), а не перечнем
|
||||||
|
установленных плагинов. Значит мягкость поведения держалась на состоянии
|
||||||
|
проекта и пережила слияние без единой правки логики: сменилась упаковка, а не
|
||||||
|
механика. Дом правила переехал из `plugin-boundary.md` в `absence.md` и стал
|
||||||
|
говорить о том, чем он и был на деле, — о частях раскладки, которых может не
|
||||||
|
быть.
|
||||||
|
|
||||||
|
**Версия стала одна и начинается с 1.** Две версии — канон 14 и формат задач 1 —
|
||||||
|
двигались порознь, потому что порознь ставились плагины; с одним плагином два
|
||||||
|
числа означали бы только вопрос, по какому журналу повышать. Прежние журналы
|
||||||
|
закрыты и не переписаны: адрес, верный на день записи, остаётся свидетельством.
|
||||||
|
Служебный файл один, `.av-dev.toml` в корне репозитория, и **формат выбран ради
|
||||||
|
комментариев** — файл живёт в чужом репозитории, и назначение числа должно
|
||||||
|
читаться из него самого, а не из документации плагина. Отсюда правило записи:
|
||||||
|
скрипт правит строку, а не переписывает файл.
|
||||||
|
|
||||||
|
**Опцион не потерян.** Понадобится инфраструктурный плагин — расколоть обратно
|
||||||
|
будет переименованием пространства имён, а не переделкой: граница по-прежнему
|
||||||
|
держится на следе в проекте. Платить за этот опцион копиями сегодня незачем.
|
||||||
|
|
||||||
|
### Что из этого следует
|
||||||
|
|
||||||
|
218. **Разрез, оправданный сценарием, обязан этот сценарий однажды увидеть.**
|
||||||
|
«Ставится порознь» — проверяемое утверждение, и проверяется оно не
|
||||||
|
рассуждением, а тем, поставил ли кто-нибудь половину. Пока не поставил,
|
||||||
|
разрез оплачивается копиями за случай, которого нет.
|
||||||
|
219. **Механика, привязанная к состоянию проекта, переживает перестановку
|
||||||
|
плагинов; привязанная к их составу — нет.** Это и есть практическая разница
|
||||||
|
между «узнаём следом» и «узнаём перечнем», и обнаруживается она только на
|
||||||
|
слиянии или расколе.
|
||||||
|
220. **Копия дословного текста — плата за неразрешимый путь, а не за важность
|
||||||
|
правила.** Путь разрешился — копия становится вторым домом без причины.
|
||||||
|
Остаётся она там, где текст обязан лежать внутри промпта: устав агента и
|
||||||
|
скелет, уезжающий в проект.
|
||||||
|
221. **Формат служебного файла выбирается по тому, кто его читает.** Читает
|
||||||
|
человек в чужом репозитории через полгода — значит комментарии, значит
|
||||||
|
TOML, значит построчная правка вместо перезаписи.
|
||||||
|
|||||||
@@ -9,83 +9,98 @@
|
|||||||
|
|
||||||
## Плагины
|
## Плагины
|
||||||
|
|
||||||
- **av-dev-docs** — документация проекта. Владеет `docs/` и `CLAUDE.md`.
|
Плагина два: **av-dev** — весь процесс, и **av-dev-git** — сообщения коммитов,
|
||||||
- `init` — новый проект: интервью по свободному описанию замысла → первичная
|
работающие в любом репозитории. До 13 августа 2026 процесс жил тремя плагинами
|
||||||
документация;
|
(`av-dev-docs`, `av-dev-tasks`, `av-dev-code`); раскол делался под раздельную
|
||||||
- `canon` — привести проект к канону документов: `check` / `adopt` /
|
установку, она не понадобилась ни разу, и плагины слились — тема 52
|
||||||
`upgrade`, плюс скрипт `docs.py`. Там же лежит копия языка проектных
|
[DECISIONS.md](DECISIONS.md).
|
||||||
текстов — информационный стиль, англицизмы, жаргон; дом у него общий,
|
|
||||||
`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-`, имена
|
Имя **скилла** несёт префикс прежнего плагина: `doc-`, `task-`, `code-`. Вызов
|
||||||
**скилов** внутри — короткие. Вызов выходит вида `/av-dev-<плагин>:<скилл>`.
|
выходит вида `/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
|
```mermaid
|
||||||
flowchart TB
|
flowchart TB
|
||||||
subgraph pipe["av-dev-code — исполнение; сценарий решения требует OpenSpec"]
|
subgraph avdev["av-dev — один плагин, девять скиллов"]
|
||||||
direction LR
|
subgraph pipe["работа по задачам; сценарий решения требует OpenSpec"]
|
||||||
tp["resolve<br/>3 сценария: разведка,<br/>решение, обслуживание"] --> rp["review<br/>10 агентов-проходов"]
|
direction LR
|
||||||
osp["openspec<br/>заводит и проверяет openspec/"]
|
tp["code-resolve<br/>3 сценария: разведка,<br/>решение, обслуживание"] --> rp["code-review<br/>10 агентов-проходов"]
|
||||||
end
|
osp["code-openspec<br/>заводит и проверяет openspec/"]
|
||||||
subgraph docsp["av-dev-docs — документация, владеет docs/"]
|
end
|
||||||
direction LR
|
subgraph docsp["документы, владеют docs/"]
|
||||||
init["init"]
|
direction LR
|
||||||
canon["canon"]
|
init["doc-init"]
|
||||||
docs["docs"]
|
canon["doc-canon"]
|
||||||
hc["healthcheck"]
|
docs["doc-sync"]
|
||||||
end
|
hc["doc-healthcheck"]
|
||||||
subgraph tasksp["av-dev-tasks — учёт работ"]
|
end
|
||||||
direction LR
|
subgraph tasksp["учёт работ"]
|
||||||
groom["groom"] --> tasks["tasks"]
|
direction LR
|
||||||
|
groom["task-groom"] --> tasks["task-track"]
|
||||||
|
end
|
||||||
end
|
end
|
||||||
init --> tasks
|
init --> tasks
|
||||||
init --> osp
|
init --> osp
|
||||||
@@ -127,18 +144,17 @@ flowchart TB
|
|||||||
tp --> tasks
|
tp --> tasks
|
||||||
```
|
```
|
||||||
|
|
||||||
Зависимости **взаимные, но каждая мягкая**. `av-dev-code` зовёт обоих соседей;
|
**Скиллы зовут друг друга полным именем, а не по пути.** Внутри одного плагина
|
||||||
обратные вызовы тоже есть — `av-dev:doc-init` и `av-dev:doc-canon` заводят
|
путь бы разрешился, но короткое имя разрешается в устаревшую проектную копию из
|
||||||
OpenSpec скиллом `av-dev:code-openspec`, `av-dev:doc-sync` берёт у
|
`.claude/skills/` — молча и без признаков подмены.
|
||||||
`av-dev:code-review` форму записи журнала дефектов и процедуру промоута,
|
|
||||||
`av-dev:doc-canon` и `av-dev:doc-healthcheck` зовут `av-dev:task-track`.
|
**Отсутствовать может не плагин, а часть раскладки проекта**: `docs/`, каталог
|
||||||
**Мягкая** значит, что у любого вызова есть ветка «не разрешился»: соседа в
|
задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает
|
||||||
проекте нет — вызывающий называет строкой, чего теперь не делает никто, и работу
|
никто, и работу не останавливает. Правило целиком —
|
||||||
не останавливает. Как именно зовут соседа и что делают, когда вызов не
|
[shared/absence.md](av-dev/shared/absence.md): оно нужно почти каждому скиллу, и
|
||||||
разрешился, — `shared/plugin-boundary.md`: правило нужно большинству скиллов, и
|
ни один им не владеет. Там же, в `shared/`, живут язык проектных текстов и
|
||||||
ни один плагин им не владеет. То, что нужно нескольким дословно — граница
|
словарь сопровождения; скиллы читают их по ссылке, а дословной копией они
|
||||||
плагинов, язык проектных текстов, словарь сопровождения, — живёт домом в
|
уезжают только в уставы вычитки — туда, где текст обязан лежать внутри промпта.
|
||||||
`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).
|
[project-facts.md](av-dev/skills/code-review/references/project-facts.md).
|
||||||
|
|
||||||
Прийти в старый проект и перевести его на канон — `/av-dev:doc-canon`. Канон
|
Прийти в старый проект и перевести его на канон — `/av-dev:doc-canon`.
|
||||||
версионируется, и проекты повышаются по [журналу
|
Раскладка версионируется, и проекты повышаются по [журналу
|
||||||
версий](av-dev/skills/doc-canon/references/changelog.md); версия проекта живёт в
|
версий](av-dev/skills/doc-canon/references/changelog.md).
|
||||||
`docs/.docs.json`.
|
|
||||||
|
|
||||||
**Версий две, и они независимы.** У каталога задач своя — ключ `tasks` в
|
**Версия одна, и живёт она в `.av-dev.toml` в корне репозитория** — вместе с
|
||||||
`<каталог задач>/.tasks.json`, свой [журнал
|
настройками: `[docs] migrations` и секция `[tasks]`, где лежит каталог задач и
|
||||||
версий](av-dev/skills/task-track/references/changelog.md) и своё повышение
|
как названы его части. Версий было две, пока плагинов было три и проект мог
|
||||||
скиллом `/av-dev:task-track`. Плагины ставятся порознь: у проекта, взявшего учёт
|
взять учёт работ без канона документов; теперь плагин один, и второе число
|
||||||
работ без канона документов, `docs/` нет вовсе, и общее число оказалось бы домом,
|
означало бы только вопрос, по какому журналу повышать. Прежние
|
||||||
которого у половины проектов не существует. Имя служебного файла при этом
|
`docs/.docs.json` и `<каталог задач>/.tasks.json` не читаются: увидев их,
|
||||||
называет владельца — `.docs.json`, `.tasks.json`, `openspec/config.yaml`.
|
`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
|
claude plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --scope project
|
||||||
|
|
||||||
# плагины: scope обязателен, умолчание у команды — user, а нам нужен project
|
# плагины: scope обязателен, умолчание у команды — user, а нам нужен project
|
||||||
claude plugin install av-dev-docs@av-dev-skills --scope project
|
claude plugin install av-dev@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-git@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": {
|
"enabledPlugins": {
|
||||||
"av-dev-docs@av-dev-skills": true,
|
"av-dev@av-dev-skills": true,
|
||||||
"av-dev-tasks@av-dev-skills": true,
|
|
||||||
"av-dev-code@av-dev-skills": true,
|
|
||||||
"av-dev-git@av-dev-skills": true
|
"av-dev-git@av-dev-skills": true
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -240,9 +255,7 @@ claude plugin marketplace update av-dev-skills
|
|||||||
|
|
||||||
# 2. снимки плагинов — из каталога проекта, где они установлены
|
# 2. снимки плагинов — из каталога проекта, где они установлены
|
||||||
cd /path/to/project
|
cd /path/to/project
|
||||||
claude plugin update av-dev-docs@av-dev-skills --scope project
|
claude plugin update av-dev@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-git@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>/references/ что читается по ссылке из скилла
|
||||||
<plugin>/skills/<skill>/scripts/ tasks.py, docs.py, openspec.py
|
<plugin>/skills/<skill>/scripts/ tasks.py, docs.py, openspec.py
|
||||||
<plugin>/agents/ charter'ы сабагентов
|
<plugin>/agents/ charter'ы сабагентов
|
||||||
shared/ дома правил, общих для нескольких плагинов
|
av-dev/shared/ дома правил и общий читатель .av-dev.toml
|
||||||
scripts/ проверки репозитория и пересборка копий
|
scripts/ проверки репозитория и пересборка копий
|
||||||
pyproject.toml линтеры скриптов, только для этого репозитория
|
pyproject.toml линтеры скриптов, только для этого репозитория
|
||||||
lefthook.yml гейт коммита: проверки документов
|
lefthook.yml гейт коммита: проверки документов
|
||||||
@@ -398,19 +411,23 @@ python3 scripts/copies.py # 0 сошлось, 1 расхождение, 2 р
|
|||||||
сверку не входят. Маркер, уехавший в проект вместе со скелетом, там полезен: он
|
сверку не входят. Маркер, уехавший в проект вместе со скелетом, там полезен: он
|
||||||
говорит, что у текста есть дом и правится он там.
|
говорит, что у текста есть дом и правится он там.
|
||||||
|
|
||||||
**Дом правила, общего для нескольких плагинов, лежит в `shared/` и ни одному из
|
**Дом правила, общего нескольким скиллам, лежит в `av-dev/shared/` и ни одному
|
||||||
них не принадлежит.** Так живёт язык проектных текстов: он одинаково нужен
|
из них не принадлежит.** Так живут язык проектных текстов, словарь
|
||||||
документам канона и задачам, и хранить его внутри одного плагина значило бы
|
сопровождения и правило об отсутствующих частях раскладки: каждое нужно
|
||||||
отдать общее правило во владение половине. Так же живёт граница плагинов —
|
многим, и хранить его внутри одного скилла значило бы отдать общее правило во
|
||||||
правило обращения к соседу. Плагин везёт копию и потому остаётся
|
владение части.
|
||||||
самодостаточным — `shared/` нужен этому репозиторию, а не установленному
|
|
||||||
плагину.
|
**Копия при этом делается не всегда.** Пока плагинов было три, копия была
|
||||||
|
единственным способом: путь в дерево соседа не разрешался. Внутри одного дерева
|
||||||
|
скилл читает дом **по ссылке**, и дословная копия остаётся там, где текст обязан
|
||||||
|
лежать внутри самого промпта, — в уставах вычитки, где он и есть критерий
|
||||||
|
суждения, — и в скелетах, уезжающих в репозиторий проекта.
|
||||||
|
|
||||||
**Дом ставится в `shared/` только тогда, когда владельца нет.** У адресов
|
**Дом ставится в `shared/` только тогда, когда владельца нет.** У адресов
|
||||||
владелец есть: раскладку `docs/` держит канон, каталог задач — плагин задач, и
|
владелец есть: раскладку `docs/` держит `doc-canon`, каталог задач —
|
||||||
переносить их наружу значило бы отобрать у владельца его же предмет. Общее без
|
`task-track`, и переносить их наружу значило бы отобрать у владельца его же
|
||||||
владельца едет копией из `shared/`; чужое с владельцем остаётся дома, а
|
предмет. Общее без владельца живёт в `shared/`; чужое с владельцем остаётся
|
||||||
потребитель на него ссылается.
|
дома, а потребитель на него ссылается.
|
||||||
|
|
||||||
Скрипт ловит четыре вещи: копия разошлась с домом (с диффом), копия указывает не
|
Скрипт ловит четыре вещи: копия разошлась с домом (с диффом), копия указывает не
|
||||||
на тот файл, дом остался без копий, разметка сломана. Чего он **не** ловит —
|
на тот файл, дом остался без копий, разметка сломана. Чего он **не** ловит —
|
||||||
|
|||||||
@@ -15,13 +15,16 @@
|
|||||||
|
|
||||||
## Где мы сейчас
|
## Где мы сейчас
|
||||||
|
|
||||||
Плагинов четыре, и каждый ставится отдельно: `av-dev-docs` (канон документов и
|
Плагина два: `av-dev` — весь процесс девятью скиллами (`doc-*` — документы,
|
||||||
их содержимое), `av-dev-tasks` (задачи и цели), `av-dev-code` (код по задачам:
|
`task-*` — учёт работ, `code-*` — работа по задачам), и `av-dev-git` —
|
||||||
цикл SDD, конвейер ревью, OpenSpec), `av-dev-git`. Общее, что нужно нескольким
|
сообщения коммитов. Прежние три (`av-dev-docs`, `av-dev-tasks`, `av-dev-code`)
|
||||||
дословно, живёт домом в `shared/` и уезжает копиями.
|
слились 13 августа 2026, тема 64 DECISIONS. Общее, что нужно нескольким скиллам,
|
||||||
|
живёт домом в `av-dev/shared/`.
|
||||||
|
|
||||||
Канон документов — **версия 14**; формат задач — **версия 1**, своя и со своим журналом. Живые проекты стоят на 2–3 и на плагине
|
Раскладка — **версия 1**, одна на документы и на каталог задач, в
|
||||||
`av-dev-pm`, которого больше нет.
|
`.av-dev.toml` в корне проекта. Живые проекты стоят на каноне 2–3 и на плагине
|
||||||
|
`av-dev-pm`, которого больше нет: им идти сперва по закрытому журналу канона до
|
||||||
|
14, потом по записи 1 действующего.
|
||||||
|
|
||||||
Бумажная часть закрыта аудитом четырёх плагинов и четырьмя пропусками правок
|
Бумажная часть закрыта аудитом четырёх плагинов и четырьмя пропусками правок
|
||||||
(DECISIONS, запись 59). Всё, что ниже, проверяется **только на живом коде**.
|
(DECISIONS, запись 59). Всё, что ниже, проверяется **только на живом коде**.
|
||||||
@@ -35,19 +38,18 @@
|
|||||||
### healthlog — первым
|
### healthlog — первым
|
||||||
|
|
||||||
- [ ] переустановить плагины: снять `av-dev-pm` и `av-dev-pipeline`, поставить
|
- [ ] переустановить плагины: снять `av-dev-pm` и `av-dev-pipeline`, поставить
|
||||||
`av-dev-docs`, `av-dev-tasks`, `av-dev-code`, `av-dev-git`. Оба прежних
|
`av-dev` и `av-dev-git`. Прежние имена мертвы, и `plugin update` их не
|
||||||
имени мертвы, и `plugin update` их не переименует — только снять и
|
переименует — только снять и поставить. `marketplace update`, затем `plugin update` — одного шага мало
|
||||||
поставить. `marketplace update`, затем `plugin update` — одного шага мало
|
|
||||||
(README, «Обновление»)
|
(README, «Обновление»)
|
||||||
- [ ] удалить проектные копии: `.claude/skills/healthlog-{task,review}-pipeline`
|
- [ ] удалить проектные копии: `.claude/skills/healthlog-{task,review}-pipeline`
|
||||||
и девять `.claude/agents/healthlog-review-*.md`. Они прошлого поколения и
|
и девять `.claude/agents/healthlog-review-*.md`. Они прошлого поколения и
|
||||||
после переезда указывают на документы, которых уже не будет
|
после переезда указывают на документы, которых уже не будет
|
||||||
- [ ] `av-dev:doc-canon` в режиме `adopt` — он приведёт проект к канону 14
|
- [ ] `av-dev:doc-canon` в режиме `adopt` — он приведёт проект к раскладке 1
|
||||||
сразу, картой и с подтверждением. Файл-в-файл здесь не расписан: раскладку
|
сразу, картой и с подтверждением. Файл-в-файл здесь не расписан: раскладку
|
||||||
знает скилл, и второй перечень разошёлся бы с ним
|
знает скилл, и второй перечень разошёлся бы с ним
|
||||||
- [ ] каталог задач — в `tasks/` корня (канон 11), не в `docs/tasks/`, без
|
- [ ] каталог задач — в `tasks/` корня (канон 11), не в `docs/tasks/`, без
|
||||||
`SPRINT.md` (канон 12) и с версией формата в `tasks/.tasks.json` (журнал
|
`SPRINT.md` (канон 12); версия и настройки — в `.av-dev.toml` корня, там
|
||||||
задач, версия 1). Скилл задач зовётся из `adopt` сам
|
же секция `[tasks]`. Скилл задач зовётся из `adopt` сам
|
||||||
- [ ] гейт проекта: три шага вместо одного — `docs.py check`, `tasks.py check
|
- [ ] гейт проекта: три шага вместо одного — `docs.py check`, `tasks.py check
|
||||||
--dir tasks`, `openspec.py check`. **Второй и третий раньше не были
|
--dir tasks`, `openspec.py check`. **Второй и третий раньше не были
|
||||||
нужны:** согласованность задач тянул за собой `docs.py`, форму `config.yaml`
|
нужны:** согласованность задач тянул за собой `docs.py`, форму `config.yaml`
|
||||||
|
|||||||
Reference in New Issue
Block a user