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/main/install.sh | bash
```

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

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

```bash
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`   | kotlin, swift | — |

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

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

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

### Обновление

```bash
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](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": "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` с фронтматтером:
   ```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`.
- Pi-библиотеки — только в `peerDependencies` (`"*"`), не бандлить.

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

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

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

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