pi-kit/README.md

# @mvideo/pi-kit

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

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

---

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

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

```bash
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/неинтерактивной установки):

```bash
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 /mcp-status`,
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` по умолчанию):

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

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

```bash
pi update --extensions
```

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

### Команды

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

### Скиллы

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

- **jira-workflow** — работа с трекером (чтение тикетов, комментарии, ссылки и создание MR).
- **repo-map** — как ориентироваться в наших репозиториях (если карта не заполнена — скилл
  скажет об этом и не будет выдумывать).
- **docs-map** — как искать и куда писать документацию.
- **Языковые стандарты** — `<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
│   ├── protected-paths.ts
│   ├── permission-gate.ts
│   ├── secret-scanner.ts   commit-guard.ts   llm-redaction.ts   audit-log.ts
│   ├── mcp-bridge.ts                          # Jira/Confluence/GitLab MCP (по умолч. выкл.)
│   ├── kit-cli.ts                             # /kit-doctor, /kit-help
│   └── lib/                                   # общий код (secrets, audit, company-config)
├── skills/              # SKILL.md-скиллы (jira-workflow/repo-map/docs-map + <lang>-standards)
├── prompts/             # шаблоны команд (/bugfix, /feature, /review, /rfc)
├── test/                # guardrails.test.ts (node) + shell/uninstall shell-тесты
├── docs/mcp.md          # документация MCP-интеграций
├── install.sh           # bootstrap для новых сотрудников
└── uninstall.sh         # полное удаление кита (с подтверждением)
```

Формат: [packages](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md),
[extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md),
[skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md),
[prompt-templates](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/prompt-templates.md).

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

`config/company.json`:

```json
{
  "gitHost": "gitlab.tech.mvideo.ru",
  "trackerUrl": "https://jira.mvideo.ru",
  "docsUrl": "https://wiki.mvideo.ru",
  "repoMap": "TODO: где какой код лежит",
  "rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"],
  "remoteConfigUrl": 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` с фронтматтером:
   ```yaml
   ---
   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` + `test/shell.test.sh`).

### Релизы

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

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

```bash
# из корня репозитория
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`
без других правок.