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

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

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

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

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

Один профиль тоже подходит: PI_KIT_PROFILE=backend. Скилы выбранных профилей объединяются (дубли убираются), а jira-workflow/repo-map/docs-map и общие публичные скилы ставятся всегда.

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

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

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

Профиль pm — для продакт-менеджеров: подключает скилл pm-task-spec (доведение сжатой постановки задачи до структурированной, пригодной для передачи в разработку) без языковых стандартов кода.

Сменить/добавить профиль позже: PI_KIT_PROFILE=frontend,qa ./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 [фокус]	Ревью текущего диффа по стандартам кода профиля (с фокусом, если задан)
/rfc <тема>	Черновик RFC по типовому шаблону
/kit-config	Показать действующие корпоративные значения и их источник (local/remote)
/kit-doctor	Health-check окружения (node, версия/канал, конфиг, env, токены; подсветит незаполненные поля)
/kit-help	Каталог возможностей: команды, скилы, guardrails

Нативные инструменты (Jira / Confluence / GitLab)

Вместо MCP-моста и bash-скриптов работа с корпоративными API реализована как нативные инструменты pi (pi.registerTool) — агент вызывает их напрямую. URL берутся из config/company.json, токены — из env.sh.

Область	Инструменты
Jira	jira_issue_get, jira_issue_create, jira_issue_update, jira_issue_comment, jira_issue_transition, jira_search, jira_link_mr
GitLab	gitlab_mr_create, gitlab_pipeline_status, gitlab_code_search
Confluence	confluence_search, confluence_page_get, confluence_page_create

Разбирают их скиллы jira-workflow и confluence; логика вынесена в чистые модули extensions/lib/{jira,gitlab,confluence}.ts (unit-тестируются).

Скиллы

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

• jira-workflow — работа с трекером через нативные инструменты jira_issue_* (чтение, создание/обновление, комментарии, переходы, JQL-поиск, привязка MR).
• confluence — поиск/чтение/создание страниц через confluence_search, confluence_page_*.
• repo-map — как ориентироваться в наших репозиториях (если карта не заполнена — скилл скажет об этом и не будет выдумывать).
• docs-map — как искать и куда писать документацию.
• pm-task-spec — постановка задачи продакт-менеджером: выявляет слабые места, опрашивает по ключевым доменам и выдаёт готовую структурированную постановку (подключается по профилю pm).
• Языковые стандарты — <lang>-standards для go/rust/python/typescript/kotlin/swift: структура, линтеры, тесты, коммиты/MR. Подключаются по профилю (см. таблицу выше), промпты команд ссылаются на них обобщённо (<lang>-standards), а не на конкретный язык.

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

• protected-paths — блокирует запись/редактирование секретов, ключей, .git/, прод-конфигов (по пути).
• permission-gate — переспрашивает перед опасными командами (rm -rf/rm -r -f, force push, push в main/master/release-*, тег v* (в т.ч. через refs/tags/ — прод-деплой), git reset --hard, git clean, прод-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
│   ├── jira-tools.ts   gitlab-tools.ts   confluence-tools.ts   # нативные инструменты API
│   ├── protected-paths.ts
│   ├── permission-gate.ts
│   ├── secret-scanner.ts   commit-guard.ts   llm-redaction.ts   audit-log.ts
│   ├── kit-cli.ts                             # /kit-doctor, /kit-help
│   └── lib/                                   # общий код (jira, gitlab, confluence, secrets, audit, company-config)
├── skills/              # SKILL.md-скиллы (jira-workflow/confluence/repo-map/docs-map/pm-task-spec + <lang>-standards)
├── prompts/             # шаблоны команд (/bugfix, /feature, /review, /rfc)
├── test/                # guardrails.test.ts + api.test.ts (node) + shell/uninstall shell-тесты
├── install.sh           # bootstrap для новых сотрудников (дефолты URL из company.json + справки по токенам)
└── uninstall.sh         # полное удаление кита (с подтверждением)

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

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

config/company.json:

{
  "gitHost": "gitlab.tech.mvideo.ru",
  "trackerUrl": "https://jira.mvideo.ru",
  "docsUrl": "https://wiki.mvideo.ru",
  "repoMap": "TODO: где какой код лежит",
  "rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"],
  "remoteConfigUrl": null,
  "auditEndpoint": null
}

Значения выше — текущие действующие; в этом файле хранится единственный источник правды (адрес самого репозитория pi-kit — git.codelab.vc — к нему отношения не имеет, он живёт только в install.sh).

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

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

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 читает эту папку). Чужой код в наш репо не вендорится.

Наборы скилов нескольких профилей объединяются (путь frontend+qa даст и typescript и python стандарты). Чтобы поменять маппинг профиль→скилы — правь функцию profile_skills() и COMMON_PUBLIC_SKILLS в install.sh. Языковой скилл добавляется как обычный (см. ниже) и подключается к нужному профилю в этой функции. Профили: frontend, backend, qa, mobile, pm — любые сочетаются между собой.

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

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 + test/shell.test.sh).

Релизы

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

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

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

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

⚠️ npm test требует Node.js ≥ 22.6 (type-stripping). Для сотрудников в install.sh достаточно Node ≥ 20 — это требование тест-харнеса мейнтейнеров, не установки.

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