README, HISTORY и REMAINING пересобраны под новую картину

- README: три плагина, канон документов, явное обновление маркетплейса - HISTORY: сжатый AGENTIC-TASKS — что отвергнуто и почему, числа первого замера - REMAINING: главным риском названа несделанная калибровка при двух подряд переписываниях charter'ов; закрытые разбором вопросы убраны
2026-08-03 14:31:41 +03:00
parent 9cef45252c
commit bff3c9e118
3 changed files with 248 additions and 159 deletions
@@ -1,77 +1,116 @@
 # av-dev-skills

-Личный маркетплейс плагинов и скилов для разработки — чтобы подключать их к
-проектам по мере необходимости, а не держать в глобальном `~/.claude`.
+Личный маркетплейс плагинов для разработки. Процесс имени не имеет — он и есть
+`av-dev`.
+
+Что решено и почему — [DECISIONS.md](DECISIONS.md). Что осталось сделать —
+[TODO.md](TODO.md) и [REMAINING.md](REMAINING.md). Как процесс дошёл до текущей
+формы — [HISTORY.md](HISTORY.md).
+
+## Плагины
+
+- **av-dev-pm** — управление продуктом. Владеет всем `docs/`.
+  - `init` — новый проект: интервью по свободному описанию замысла → первичная
+    документация;
+  - `canon` — привести проект к канону документов: `check` / `adopt` /
+    `upgrade`, плюс скрипт `docs.py`;
+  - `docs` — содержимое канона по ходу разработки: ADR из архивного
+    `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка
+    архитектуры;
+  - `tasks` — задачи и цели каталогом markdown-файлов;
+  - `session` — ритуал между спринтами и ведение спринта.
+- **av-dev-pipeline** — исполнение. **Требует OpenSpec.**
+  - `task-pipeline` — задача через полный цикл SDD, от постановки до коммита;
+  - `task-batch` — несколько задач разом, каждая в своём worktree;
+  - `review-pipeline` — конвейер ревью: гейт, сверка со спеками, враждебные
+    постановки, эксплуатационный постмортем, независимая реализация,
+    архитектура, обязательный триаж. Девять агентов-проходов.
+- **av-dev-git** — `commit`: сообщения в личном стиле.
+- **av-dev-backlog** — **устарел**, заменён `av-dev-pm`. Живёт до перевода
+  последнего проекта.
+
+Соглашение об именах: имя **плагина** длинное с префиксом `av-dev-`, имена
+**скилов** внутри — короткие. Вызов выходит вида `/av-dev-<плагин>:<скилл>`.
+
+## Канон документов проекта
+
+Все проекты приводятся к одной раскладке — так проще ориентироваться, когда
+проектов много, и рядом OpenSpec тоже держит строгую структуру. Определение —
+[av-dev-pm/skills/canon/references/canon.md](av-dev-pm/skills/canon/references/canon.md).
+
+```
+CLAUDE.md                      инварианты с severity, команды, семантика гейта
+docs/
+  .pm.json                     версия канона и пути для проверок
+  passport.md                  зачем и для кого; чем НЕ является
+  architecture.md              как сложено — обзор; окружение и эксплуатация
+  database.md                  схема хранилища; настройки с числовым значением
+  security.md                  периметр; недоверенный вход; что вне модели
+  conventions/                 как пишем код + что уже механизировано
+  research/                    что показала реальность; числа с провенансом
+  adr/                         почему — промоут поверх архивных design.md
+  review.md                    настройка конвейера + журнал дефектов
+  tasks/                       цели, беклог, спринт, отклонённое
+openspec/
+  specs/<capability>/spec.md   что система делает — нормативно
+  changes/archive/             архив изменений с design.md
+```
+
+**Отдельного файла-брифа для ревью нет.** Проходы читают эти документы напрямую;
+карта «что нужно проходу → где лежит» —
+[project-facts.md](av-dev-pipeline/skills/review-pipeline/references/project-facts.md).
+
+Прийти в старый проект и перевести его на канон — `/av-dev-pm:canon`. Канон
+версионируется, и проекты повышаются по [журналу
+версий](av-dev-pm/skills/canon/references/changelog.md).

 ## Подключение

-Типичный способ — подключить плагин **на уровне проекта**, чтобы он был активен у
-всех, кто открывает репозиторий. Флаг `--scope project` пишет прямо в
-`.claude/settings.json` проекта (коммитится в репозиторий) — из интерактивной
-сессии Claude Code:
+Плагин подключается **на уровне проекта**, чтобы был активен у всех, кто
+открывает репозиторий:

 ```
 /plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --scope project
-/plugin install av-dev-backlog@av-dev-skills --scope project
+/plugin install av-dev-pm@av-dev-skills --scope project
+/plugin install av-dev-pipeline@av-dev-skills --scope project
+/plugin install av-dev-git@av-dev-skills --scope project
 ```

-…или те же команды из терминала:
-
-```
-claude plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --scope project
-claude plugin install av-dev-backlog@av-dev-skills --scope project
-```
-
-Обе формы дописывают в `.claude/settings.json` ровно то, что можно внести и
-руками — маркетплейс в `extraKnownMarketplaces`, плагин в `enabledPlugins`:
+…или те же команды из терминала через `claude plugin …`. Обе формы дописывают в
+`.claude/settings.json` проекта то, что можно внести и руками:

 ```json
 {
  "extraKnownMarketplaces": {
    "av-dev-skills": {
-      "source": {
-        "source": "git",
-        "url": "https://git.vakhrushev.me/av/dev-skills.git"
-      }
+      "source": { "source": "git", "url": "https://git.vakhrushev.me/av/dev-skills.git" }
    }
  },
  "enabledPlugins": {
-    "av-dev-backlog@av-dev-skills": true
+    "av-dev-pm@av-dev-skills": true,
+    "av-dev-pipeline@av-dev-skills": true,
+    "av-dev-git@av-dev-skills": true
  }
 }
 ```

-При первом открытии проекта Claude Code попросит доверять воркспейсу; после
-подтверждения маркетплейс и включённые плагины подгружаются автоматически. Ключ
-включения — `"<плагин>@<маркетплейс>": true`.
+**Маркетплейс — git-клон удалённого репозитория, и он обновляется явно:**
+`claude plugin marketplace update av-dev-skills`. Локальные коммиты, не
+отправленные на origin, до него не доедут — это уже однажды выглядело как
+«плагин не работает».

-Без `--scope project` те же команды пишут в user-конфиг — разовая установка
-только себе, настройки проекта не трогаются:
+**При установке в проект, где лежали проектные копии** скиллов и агентов
+(`.claude/skills/{task-pipeline,review-pipeline,task-batch}`,
+`.claude/agents/<проект>-review-*.md`) — снеси их. Две копии одного скилла
+расходятся, и побеждает та, что короче названа.
+
+## Структура репозитория

 ```
-/plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git
-/plugin install av-dev-backlog@av-dev-skills
-```
-
-## Плагины
-
- **av-dev-backlog** — ведение беклога задач как каталога markdown-файлов (одна
-  задача = один файл `<slug>.md` + строка в индексе `README.md`). Скилл
-  `backlog`: заведение задачи из диалога, разбор находок аудита/ревью, груминг,
-  приоритизация, декомпозиция, штурм идей. Реализацией не занимается. Вызов:
-  `/av-dev-backlog:backlog`.
- **av-dev-git** — git-обвязка для личных проектов. Скилл `commit`: сообщения
-  коммитов в личном стиле (русский, опциональный scope-префикс, первая строка
-  «что сделано», тело 1–3 пункта, без co-authored). Вызов: `/av-dev-git:commit`.
-
-Соглашение об именах: имя **плагина** длинное с префиксом `av-dev-` (уникально в
-маркетплейсе), имена **скилов** внутри — короткие. Вызов выходит вида
-`/av-dev-<плагин>:<скилл>`.
-
-## Структура
-
-```
-.claude-plugin/marketplace.json   — манифест маркетплейса
-<plugin>/.claude-plugin/plugin.json — манифест плагина
-<plugin>/skills/<skill>/SKILL.md    — скилы плагина (авто-обнаружение)
+.claude-plugin/marketplace.json      манифест маркетплейса
+<plugin>/.claude-plugin/plugin.json  манифест плагина
+<plugin>/skills/<skill>/SKILL.md     скилы (авто-обнаружение)
+<plugin>/skills/<skill>/references/  что читается по ссылке из скилла
+<plugin>/skills/<skill>/scripts/     tasks.py, docs.py
+<plugin>/agents/                     charter'ы сабагентов
 ```