avandClaude Opus 5
1fb006df4a
Два независимых сабагента на av-dev-pm и av-dev-pipeline. Две находки нашли оба. Главная — моя же перестановка закрытия за коммит сломала reopen и батч. close печатал «дорога назад из git», а reopen искал коммит удаления, которого в новом порядке ещё нет: шаг 11 последний, учёт остаётся незакоммиченным. Проверено прогоном — отказ кодом 2 на свежезакрытой задаче. Тем же грязным деревом ломались rebase и worktree remove в батче: каждая закрывшая задачу ветка уехала бы в провалившиеся. Починено с обеих сторон: reopen берёт текст из HEAD, если коммита удаления нет, а шаг 11 коммитит учёт вторым коммитом. Вторая — канонический пример docs/.pm.json убивал tasks.py. Четыре документа показывали ключ tasks.sections, которого скрипт не знает: неизвестный ключ это код 3 на любой команде. Проект, заведённый по канону дословно, остался бы без работы с задачами, а docs.py при этом печатал «канон соблюдён». Секции живут в заголовках индекса и второго дома не получают. Остальные восемнадцать: init писал конфиг в упразднённый .tasks.json; looks_like_tasks не видел переименованный индекс; урожай спринта терял автотег после sprint close; ответ на вопрос по инструкции оставлял задачу незабираемой; adopt требовал недостижимого зелёного; путь отчёта триажа не переживал archive; review-specs не имел режима для стыка после слияния; три остатка «шаг 9а» несли предкоммитную позицию закрытия; sprint.md отрицал сам себя в пункте «Сделана». Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
141 lines
8.6 KiB
Markdown
141 lines
8.6 KiB
Markdown
# av-dev-skills
|
||
|
||
Личный маркетплейс плагинов для разработки. Процесс имени не имеет — он и есть
|
||
`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).
|
||
|
||
## Подключение
|
||
|
||
Плагин подключается **на уровне проекта**, чтобы был активен у всех, кто
|
||
открывает репозиторий:
|
||
|
||
```
|
||
/plugin marketplace add https://git.vakhrushev.me/av/dev-skills.git --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 …`. Обе формы дописывают в
|
||
`.claude/settings.json` проекта то, что можно внести и руками:
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"av-dev-skills": {
|
||
"source": { "source": "git", "url": "https://git.vakhrushev.me/av/dev-skills.git" }
|
||
}
|
||
},
|
||
"enabledPlugins": {
|
||
"av-dev-pm@av-dev-skills": true,
|
||
"av-dev-pipeline@av-dev-skills": true,
|
||
"av-dev-git@av-dev-skills": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**Маркетплейс — git-клон удалённого репозитория, и он обновляется явно:**
|
||
`claude plugin marketplace update av-dev-skills`. Локальные коммиты, не
|
||
отправленные на origin, до него не доедут — это уже однажды выглядело как
|
||
«плагин не работает».
|
||
|
||
**При установке в проект, где лежали проектные копии** скиллов и агентов
|
||
(`.claude/skills/` — голые `task-pipeline`, `review-pipeline`, `task-batch`
|
||
и с префиксом проекта `<проект>-task-pipeline`,
|
||
`.claude/agents/<проект>-review-*.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'ы сабагентов
|
||
pyproject.toml линтеры скриптов, только для этого репозитория
|
||
```
|
||
|
||
## Проверка скриптов
|
||
|
||
`tasks.py` и `docs.py` запускаются **где угодно голым `python3` 3.12 без
|
||
установки чего-либо** — они лежат рядом со скиллами и работают в любом проекте.
|
||
`pyproject.toml` в корне не меняет этого: он живёт только здесь и держит
|
||
линтеры, а не зависимости скриптов.
|
||
|
||
```
|
||
uv sync # ставит ruff и pyrefly в .venv, версии прибиты точно
|
||
uv run ruff check . # правила; --fix для безопасных починок
|
||
uv run pyrefly check # типы
|
||
```
|
||
|
||
Ноль внешних зависимостей охраняется двумя способами: `banned-api` у ruff ловит
|
||
частые соблазны по имени, а pyrefly видит окружение, где нет ничего кроме
|
||
линтеров, и любой сторонний импорт у него не разрешается. Список запретов —
|
||
не перечень мира, настоящий страж второй.
|
||
|
||
`av-dev-backlog` из проверки исключён намеренно: плагин помечен устаревшим и
|
||
живёт до перевода последнего проекта, после чего удаляется целиком. Правки в
|
||
замороженный код — риск без выгоды.
|