diff --git a/README.md b/README.md new file mode 100644 index 0000000..5c3a41e --- /dev/null +++ b/README.md @@ -0,0 +1,154 @@ +# @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 (если нет), установит этот пакет и подскажет, +какие переменные окружения нужны (`ANTHROPIC_API_KEY` / ключ прокси, `TRACKER_URL`, `JIRA_TOKEN`). + +Либо вручную: + +```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//SKILL.md` с фронтматтером: + ```yaml + --- + name: my-skill # a-z, 0-9, дефисы; ≤ 64 символов + description: ... # ЧЁТКО: что делает и КОГДА применять (по этому триггерится) + --- + ``` +2. Вспомогательные файлы — в `scripts/`, `references/`, `assets/` внутри папки скилла. +3. **Никаких секретов и URL в тексте** — только ссылки на корпоративный контекст сессии и + переменные окружения. + +### Как добавить шаблон-команду + +1. Создай `prompts/.md` — имя файла станет командой `/`. +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` +без других правок.