SMP_V8StorageKit

Плагін Claude Code v8storagekit — контур роботи агента з 1С:Підприємством поруч з Unica. Unica редагує метадані, форми, СКД і код, валідує, збирає й тестує; kit закриває те, чого Unica не вміє: сховища конфігурацій, дамп із живої бази, база агента, звірка git зі сховищем, старт сесії.

Три речі, на яких тримається контур:

• Сховище конфігурації — істина в останній інстанції. Kit у сховище ніколи не пише, лише читає. Git — робоче середовище агента й історія «хто і коли змінив рядок».
• Агент працює у своїй базі й ніколи не пише в базу людини. Базу людини kit лише читає дампом, і лише на явне прохання.
• Результат агента — зібрані .cf, .cfe, .epf у build/artifacts/. Застосовує їх людина своїм Конфігуратором і сама кладе у сховище; kit підхоплює нову версію далі.

Встановлення

claude plugin marketplace add VSydorenko/SMP_V8StorageKit
claude plugin install v8storagekit@smp-v8storagekit

Потрібно: PowerShell 7+, git, платформа 1С гілки 8.3.27.x, модуль powershell-yaml (Install-Module powershell-yaml -Scope CurrentUser), gh для PR у finish, плагін Unica для роботи з вихідниками. Перевірити все одразу:

pwsh -NoProfile -File tools/check-environment.ps1

Категорії у виводі відповідають реальним залежностям: без категорії «Конвеєр» скрипти не запустяться; без Unica синхронізація зі сховищем працює повністю, а редагувати синхронізоване нема чим.

Як це працює

• Маніфест v8storagekit.yaml у корені репозиторію описує воркспейси й джерела. Для кожного джерела — truth: storage (сховище, дзеркалиться в git), vendor або dump (дамп із живої бази), git (живе лише в git). Локальне для машини — підключення до баз, шляхи сховищ, шаблон .dt — у гітігнорованій накладці v8storagekit.local.yaml, паролі лише там. Слів «клієнт» і «продукт» у логіці немає: одна форма описує і продуктовий репозиторій з кількома варіаціями розширення, і клієнтську базу з конфігурацією, адаптацією та спільними розширеннями.
• Дзеркала сховищ — orphan-гілки storage/<джерело>, по коміту на версію сховища з автором, датою й коментарем поміщення; AUTHORS перекладає логін сховища в git-автора. Стан живе в трейлерах комітів, файлу стану немає. Глибина першого реплею — питання за джерелом: з початку, з версії N або лише поточна. Головна гілка приймає дзеркала злиттям; гілки задач агента йдуть від головної й закриваються PR.
• База агента — файлова під build/ воркспейсу або серверна. provision спершу перевіряє, що на диску є конфігурація-власник, потім розгортає базу порожньою з джерел, з .dt або приймає серверну; наповнює її operation=build Unica. Базу можна зламати й розгорнути знову.
• Хук старту сесії живе в репозиторії-споживачі, не в плагіні: показує, чи є у сховищах нові версії, і пропонує оновити. Плагін власних хуків не оголошує, щоб не спрацьовувати в чужих проєктах цієї ж машини.
• Перед PR finish звіряє гілку зі сховищем: версії, що з'явились у сховищі під час задачі, переносяться, а перетин зачеплених файлів називається людині до злиття.

Архітектура й знахідки живих прогонів — docs/storage-and-git.md.

Команди kit.ps1

Один диспетчер pwsh tools/kit.ps1 <команда> -RepoRoot <репозиторій-споживач> зі спільними параметрами -RepoRoot, -Workspace, -Source, -Apply. Команди — окремі модулі tools/commands/*.psm1.

Команда	Що робить
check	аудит: маніфест ↔ v8project.yaml ↔ .gitignore/.gitattributes ↔ Configuration.xml ↔ інваріанти storage/* ↔ хуки ↔ артефакти збірки в git; нічого не мутує
session-check	дешевий сигнал старту сесії: нові версії у сховищах, розбіжність storage/* з головною гілкою; спершу виконує повний check
sync	реплей нових версій кожного джерела truth: storage у storage/<джерело>; перше злиття в головну гілку; -FromVersion N або -FromLatest для першого реплею
dump	дамп джерела truth: dump або vendor із живої бази людини; розпізнає відкритий Конфігуратор
verify	звірка дерева гілки з канонічним дампом сховища на версії з трейлера; звірочний коміт — лише з -Apply
canon	/DumpConfigToFiles з бази агента назад у дерево кожного джерела воркспейсу
provision	база агента: перевірка власника, потім порожня з джерел, з .dt або серверна
build	.epf через платформу в build/artifacts/; туди ж operation=make Unica кладе .cf і .cfe
install-hooks	.githooks/ + core.hooksPath, шим .claude/hooks/session-start.ps1, .claude/settings.json
rename-edt	перенесення EDT-дерева gitsync-вивантаження в точні Designer-шляхи — крок переходу наявних репозиторіїв

Коди виходу: 0 — виконано; 1 — зупинка; 2 — стан змінено частково, решта за людиною (лише sync); 3 — нічого не змінено, але є що робити (verify, session-check). Без -Apply жодна команда нічого не змінює в git, сховищі чи базах, але sync і verify усе одно піднімають платформу — хвилина-дві й ліцензія.

Скіли

Усі з префіксом плагіна: v8storagekit:sync, а не sync — голе ім'я дає Unknown skill.

Скіл	Коли
using-v8storagekit	вступ до контуру; вантажиться хуком старту сесії, вручну не викликається
onboarding	підключити репозиторій, воркспейс або джерело — діалогом: розпізнає форму репозиторію, показує, що бачить, пропонує кроки
sync	перенести нові версії сховища в git
dump	вивантажити стан із живої бази людини в дерево джерела
provision	розгорнути або перестворити базу агента
reconcile	звести гілку задачі зі сховищем після того, як людина сама поклала туди частину
verify	звірити гілку зі сховищем
finish	закрити задачу: sync → canon → merge → verify → тести й синтаксис Unica → артефакти → PR

Перехід наявних репозиторіїв

Репозиторії, які колись вивантажували сховища через gitsync у EDT-формат, переводить той самий onboarding, окремої команди немає. Він розпізнає форму за текою DT-INF/, ставить тег legacy/gitsync-<дата> на останній старий коміт, перейменовує кожен файл у його точний Designer-шлях і перезаписує дерево реплеєм зі сховища. Конвертер EDT не потрібен: сховище містить усі версії. git log --follow лишається безперервним для всіх файлів, git blame через межу — для коду модулів; виміряно на живих переходах. Довідка — docs/migration/legacy-gitsync-repo.md.

Межі

• Сховища конфігурацій — тільки читання: жодних ConfigurationRepositoryCommit, Lock, UnlockObjects. Запис у сховище виконує людина в Конфігураторі.
• -Apply — лише коли людина явно попросила. git push, PR і релізи — лише за її словом.
• Рядки лиценз, ліценз, license, HASP у виводі платформи зупиняють роботу.
• Артефакти збірки в git не лежать; check попереджає про закомічені.
• Накладка з паролями пишеться лише після того, як .gitignore її ховає.

Що всередині

Тека	Що це
tools/	диспетчер kit.ps1, команди commands/*.psm1, модулі lib/*.psm1, Pester-тести tests/, check-environment.ps1, стаб assets/empty-extension/
skills/	вісім скілів, які плагін роздає споживачам
templates/	файли, які onboarding копіює в репозиторій-споживач; відповідність «файл тут → файл там» — templates/README.md
docs/	архітектура, контракт з Unica, політика тексту, припаркована робота, довідка переходу
.claude/skills/kit-dev/	проєктний скіл для того, хто розробляє сам плагін; споживачам не роздається

Розробка

Робоча копія — звичайний клон. Тести без платформи, паралельно (~95 с на 12 ядрах, вимір 2026-09-22):

pwsh -NoProfile -File tools/tests/Run-Tests.ps1 -ExcludeTag Integration

Повний прогін з тегом Integration запускає 1cv8.exe, створює файлову ІБ і вантажить у неї розширення. Живе тестування на реальному репозиторії — claude --plugin-dir <шлях до клону>; /reload-plugins підхоплює правки без перезапуску сесії.

${CLAUDE_PLUGIN_ROOT} — лише всередині шляху. У тілі SKILL.md цей токен замінюється абсолютним шляхом плагіна в момент завантаження, і підстановка сліпа: речення, яке про токен розповідає, після неї стає вказівкою вписати шлях конкретної машини. Тому теорія механізму живе тут, у README, який скілом не є. Перевірка, що правило не порушене (має бути порожньо):

grep -rnP 'CLAUDE_PLUGIN_ROOT\}(?!/)' skills/

Перевіряється форма вживання — «за токеном одразу /». Попередня форма відсіювала рядки за переліком тек (/tools/, /templates/, /docs/) і через це кричала на легітимний ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json, а справжню пастку в рядку зі словом /tools/ пропускала мовчки. Те саме інваріантом тримає tools/tests/Skills.Tests.ps1.

Кеш встановленої копії — знімок. claude plugin update перезаписує ~/.claude/plugins/cache/... лише коли змінилась версія в .claude-plugin/plugin.json; кожна зміна для споживачів потребує підняття версії. install і update на встановлений плагін можуть мовчки відповісти «вже встановлено», і тоді оновлює лише uninstall → install з новою сесією. За локального маркетплейсу сесії читають робочу копію, а не кеш; як це виміряно — .claude/skills/kit-dev/references/cases.md, випадок 13.

Правила роботи в цьому репозиторії, зібрані з живих прогонів, — проєктний скіл kit-dev; він активується сам за моментом дії.

Реліз

Споживачі отримують не вершину main, а протегований реліз. Каталог маркетплейсу читається з дефолтної гілки, але сам плагін прив'язаний у ньому до тега:

"source": {
  "source": "url",
  "url": "https://github.com/VSydorenko/SMP_V8StorageKit.git",
  "ref": "v1.0.0"
}

Тип саме url з явним HTTPS, а не github: тип github клонує по SSH, і на машині без ключів для GitHub встановлення падає з No ED25519 host key is known for github.com (перевірено 2026-09-11). Маркетплейс при цьому додається нормально, бо його Claude Code тягне по HTTPS — тож помилка з'являється лише на plugin install і виглядає як проблема доступу до репозиторію.

Так коміти в main — спеки, плани, документація, фікси в процесі — не доходять до споживачів, доки не зміниться ref. Поле sha замість ref пінить точний коміт і має над ним пріоритет. Версію бере plugin.json плагіна: вона переважає над version у записі маркетплейсу без попередження, тому дублювати її в обох файлах не варто (тут її в записі немає).

Порядок релізу:

1. підняти версію в plugin.json;
2. PR у main;
3. тег vX.Y.Z на злитий коміт, gh release create vX.Y.Z з описом і порівнянням проти попереднього тега;
4. оновити ref у marketplace.json на новий тег і запушити в main — цей коміт і відкриває реліз споживачам.

Формат тега — vX.Y.Z, як в Unica, без префікса з іменем плагіна. Теги: v0.6.0 (останній стан конвеєра 0.6.0), v1.0.0. Застереження на майбутнє: вбудована claude plugin tag пише <name>--vX.Y.Z, і саме за цим префіксом Claude Code шукає теги, коли розв'язує semver-обмеження залежностей між плагінами. Поки ніхто не оголошує v8storagekit своєю залежністю, це не потрібно; якщо знадобиться — тегувати додатково в тому форматі, не замінюючи vX.Y.Z.

Споживачам на машині після релізу: claude plugin marketplace update smp-v8storagekit, потім claude plugin update v8storagekit@smp-v8storagekit і нова сесія. Якщо update мовчки відповів «вже встановлено» — ознака застряглого кеша одна, відсутність нових скілів, і лікує лише uninstall плюс install.

Документація

Питання	Відповідь у
Як влаштований контур «сховище ↔ git ↔ база агента»	docs/storage-and-git.md
На що покладаємось в Unica і що там зламано	docs/unica-contract.md
Чому вихідники не конвертуються за кінцями рядків	docs/text-policy.md
Чому щось відоме не полагоджено	docs/follow-ups.md
Перехід gitsync-репозиторію (і числа спайку історії — розділ 12)	docs/migration/legacy-gitsync-repo.md
Що саме роздається споживачам	templates/README.md
Архітектурне обґрунтування моделі 1.0	docs/superpowers/specs/2026-09-03-agent-contour-design.md