pi-kit/README.md

@mvideo/pi-kit

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

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

---

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

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

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

Скрипт проверит Node.js (>= 20), поставит Pi (если нет), установит этот пакет, спросит твой профиль, поставит нужные скилы и интерактивно настроит окружение (TRACKER_URL, JIRA_TOKEN, GITLAB_TOKEN, ключ LLM-провайдера). Секреты вводятся скрыто и сохраняются в ~/.config/pi-kit/env.sh (chmod 600), который подключается из твоего ~/.zshrc/~/.bashrc. Pi провайдер-агностичен — модель/провайдера пакет не навязывает, каждый выбирает свой (Anthropic, OpenAI, OpenRouter, …).

Пропустить интерактивную настройку окружения: PI_KIT_SETUP_ENV=0. Значения потом можно поменять прямо в ~/.config/pi-kit/env.sh или перезапустив ./install.sh.

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

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

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

Общее для всех: команды /bugfix /feature /review /rfc /kit-config /kit-doctor /kit-help, 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	kotlin, swift	—

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

Либо вручную (канал stable по умолчанию):

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

Обновление и каналы

pi update --extensions

Установка идёт по каналу — движущемуся git-ref: stable (проверенные релизы, по умолчанию) или beta (обкатка). pi update --extensions следует за твоим каналом. Сменить канал: PI_KIT_CHANNEL=beta ./install.sh (или закрепиться на теге: PI_KIT_CHANNEL=v1.2.3). Процесс релизов — в RELEASING.md.

Команды

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

Скиллы

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

• 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-*, тег v* (прод-деплой), прод-kubectl, docker system prune, sudo).
• secret-scanner — блокирует запись контента, похожего на секрет (по содержимому).
• commit-guard — требует Conventional Commits и сканирует сообщение коммита на секреты.
• llm-redaction — вырезает секреты из payload перед отправкой в LLM.
• audit-log — локальный аудит срабатываний в ~/.config/pi-kit/audit.jsonl (опц. endpoint).

---

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

⚠️ 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.

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

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.
• Общий код расширений — в extensions/lib/*.ts (не index.ts → Pi не грузит как расширение).
• Pi-библиотеки — только в peerDependencies ("*"), не бандлить.
• Guardrails/секреты покрыты тестами — npm test (test/guardrails.test.ts).

Релизы

Раскатка по каналам (stable/beta) и semver-тегам — процесс в RELEASING.md. CHANGELOG.md обновляется в каждом релизе. Аудит-endpoint — поле auditEndpoint в config/company.json.

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

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

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

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