pi-kit/README.md

@mvideo/pi-kit

Корпоративный пакет для терминального кодинг-агента Pi: шаблоны задач, guardrails и скиллы со знанием того, где у нас код, трекер и документация.

Все корпоративные значения (адреса, правила) живут в одном файле — config/company.json. В коде, скиллах и шаблонах адресов нет.

---

Для сотрудника

Установка (одной командой)

curl -fsSL https://git.codelab.vc/ai/pi-kit/-/raw/main/install.sh | bash

Скрипт проверит Node.js (>= 20), поставит Pi (если нет), установит этот пакет, спросит твой профиль, поставит нужные скилы и подскажет, какие переменные окружения нужны (ключ вашего LLM-провайдера, TRACKER_URL, JIRA_TOKEN). Pi провайдер-агностичен — модель/провайдера пакет не навязывает, каждый выбирает свой (Anthropic, OpenAI, OpenRouter, …).

Профиль можно задать заранее (для CI/неинтерактивной установки):

PI_KIT_PROFILE=backend curl -fsSL https://git.codelab.vc/ai/pi-kit/-/raw/main/install.sh | bash

Профили и скилы

Общее для всех: команды /bugfix /feature /review /rfc /kit-config, guardrails, скилы jira-workflow, repo-map, docs-map, и публичные grill-me, grill-with-docs, code-review, diagnosing-bugs. Дополнительно по профилю:

Профиль	Языковые стандарты	Доп. публичные скилы
frontend	typescript	frontend-design
backend	go, rust, python	—
qa	python, typescript	—
mobile	— (TODO: kotlin/swift)	—

Сменить профиль позже: PI_KIT_PROFILE=frontend ./install.sh (или перезапусти установку).

Либо вручную:

pi install git:git.codelab.vc/ai/pi-kit

Обновление

pi update --extensions

Пакет установлен без версионного ref, поэтому обновление всегда тянет актуальный main.

Команды

Команда	Что делает
/bugfix <тикет>	Прочитать тикет → воспроизвести → падающий тест → починить → линтеры/тесты → описание MR
/feature <тикет>	Прочитать тикет → план в PLAN.md и остановка на согласование → реализация с тестами
/review [фокус]	Ревью текущего диффа по стандартам Go (с фокусом, если задан)
/rfc <тема>	Черновик RFC по типовому шаблону
/kit-config	Показать действующие корпоративные значения и их источник (local/remote)

Скиллы

Подключаются автоматически, когда задача им соответствует:

• jira-workflow — работа с трекером (чтение тикетов, комментарии, ссылки на MR).
• repo-map — как ориентироваться в наших репозиториях.
• docs-map — как искать и куда писать документацию.
• go-standards — стандарты Go: структура сервиса, линтеры, тесты, коммиты/MR.

Guardrails (встроенная защита)

• protected-paths — блокирует запись/редактирование секретов, ключей, .git/, прод-конфигов.
• permission-gate — переспрашивает перед опасными командами (rm -rf, force push, push в main/master/release/*, прод-kubectl, docker system prune, sudo).

---

Для мейнтейнера

⚠️ Supply-chain-критичный репозиторий. Пакет исполняет код на машинах всех разработчиков. Любые изменения — только через MR с обязательным ревью. Прямой push в защищённые ветки запрещён.

Устройство пакета

pi-kit/
├── package.json         # манифест: секция "pi" + Pi-библиотеки в peerDependencies ("*")
├── config/company.json  # ЕДИНЫЙ источник правды: gitHost, trackerUrl, docsUrl, repoMap, rules, remoteConfigUrl
├── extensions/          # TS-расширения (guardrails + инъекция контекста)
│   ├── company-context.ts   + company-context.md   # контекст сессии + /kit-config
│   ├── protected-paths.ts
│   └── permission-gate.ts
├── skills/              # SKILL.md-скиллы (jira-workflow/repo-map/docs-map/go-standards)
├── prompts/             # шаблоны команд (/bugfix, /feature, /review, /rfc)
└── install.sh           # bootstrap для новых сотрудников

Формат: packages, extensions, skills, prompt-templates.

Конфигурация — единственный файл

config/company.json:

{
  "gitHost": "git.codelab.vc",
  "trackerUrl": "TODO",
  "docsUrl": "TODO",
  "repoMap": "TODO: где какой код лежит",
  "rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"],
  "remoteConfigUrl": null
}

• Меняешь значение → правишь только этот файл. Скиллы и шаблоны на него ссылаются через корпоративный контекст сессии, который инжектит company-context.ts.
• remoteConfigUrl: если указать URL, при старте сессии company-context.ts скачает свежий конфиг (таймаут 2.5 с) и при успехе использует его вместо локального. Это позволяет менять значения централизованно без pi update. При любой ошибке — молча берётся локальный файл.
• Тексты формулировок (не значения) правятся в extensions/company-context.md между {{плейсхолдерами}} — можно доверить не-программистам.
• Проверить действующие значения и их источник: /kit-config.

Как добавить скилл

1. Создай skills/<name>/SKILL.md с фронтматтером:

   ---
   name: my-skill            # a-z, 0-9, дефисы; ≤ 64 символов
   description: ...          # ЧЁТКО: что делает и КОГДА применять (по этому триггерится)
   ---
   

2. Вспомогательные файлы — в scripts/, references/, assets/ внутри папки скилла.
3. Никаких секретов и URL в тексте — только ссылки на корпоративный контекст сессии и переменные окружения.

Профили и гейтинг скилов

install.sh спрашивает профиль (или берёт PI_KIT_PROFILE) и делает две вещи:

1. Гейтит наши скилы — переписывает запись пакета в ~/.pi/agent/settings.json в object-форму {"source": "...", "skills": ["skills/go-standards", ...]}, чтобы грузились только скилы профиля. Prompts и расширения не гейтятся (их ключи опущены → грузятся все).
2. Ставит публичные скилы через npx skills add <repo> --skill <name> --global в ~/.agents/skills/ (Pi читает эту папку). Чужой код в наш репо не вендорится.

Чтобы поменять маппинг профиль→скилы — правь блок case "$PROFILE" и COMMON_PUBLIC_SKILLS в install.sh. Языковой скилл добавляется как обычный (см. ниже) и подключается к нужному профилю в этом case. Профили: frontend, backend, qa, mobile (последний пока без языковых стандартов — TODO kotlin/swift).

Как добавить шаблон-команду

1. Создай prompts/<name>.md — имя файла станет командой /<name>.
2. Фронтматтер: description, argument-hint.
3. Плейсхолдеры — Pi-native: $1, $2, $ARGUMENTS/$@, ${1:-default} (⚠️ не {{...}} — их Pi в шаблонах команд не подставляет).

Как добавить/менять расширение

• Файл в extensions/*.ts, export default function (pi: ExtensionAPI) {}.
• В шапке каждого расширения — блок: что делает / как настроить / как отключить.
• Пути к файлам пакета резолвь через import.meta.url, не через cwd.
• Pi-библиотеки — только в peerDependencies ("*"), не бандлить.

Локальная проверка перед MR

# из корня репозитория
pi install ./          # установить пакет из локальной папки
pi                     # запустить: расширения загрузятся, команды /bugfix и т.д. появятся

# опциональный строгий typecheck (нужны peer-типы Pi):
npm install
npm run typecheck

Минимальный чек-лист MR: расширения загружаются без ошибок; /kit-config показывает значения; запись в .env реально блокируется; изменение config/company.json отражается в /kit-config без других правок.