# AGENTS.md — pi-skill-reinject

Инструкции для AI-агентов в репозитории **pi-auto-reinjection**: Pi Coding Agent extension (TypeScript), re-inject skills после auto compaction. План и чеклисты — в [`TODO.md`](./TODO.md). ТЗ — [`SPEC.md`](./SPEC.md).

---

## Обзор

| | |
|---|---|
| Продукт | Extension `skill-reinject` для [Pi Coding Agent](https://github.com/earendil-works/pi) |
| Цель | Отслеживать вызванные skills и повторно инжектить их после **auto** compaction |
| Статус | Спецификация готова; реализация — по фазам в `TODO.md` |
| Целевой API | Публичный `ExtensionAPI` Pi (`extensions.md`), без приватных internal imports |
| Совместимость | [@capyup/pi-auto-compact](https://github.com/capyup/pi-auto-compact) — режим `defer` по умолчанию (см. SPEC §16) |

Целевая структура кода (см. SPEC §9):

```
src/
├── index.ts            # export default function(pi: ExtensionAPI)
├── state.ts
├── detect.ts
├── expand.ts
├── reinject.ts
├── auto-compact.ts
├── settings.ts
└── commands.ts
test/
```

---

## Workflow разработки

Работаем **по фазам из `TODO.md`**, пока пользователь не сменит приоритет. Триггеры: «работай по фазе», «фаза N», «продолжай фазу», «следующий пункт чеклиста».

**Коммиты в этом репозитории** — часть цикла разработки, а не опция «по просьбе пользователя»: после каждого пункта чеклиста обязателен отдельный коммит, даже если пользователь не написал «закоммить». Исключение — только явный запрет («без коммитов», «только diff»).

**Приоритет над общим user rule:** пока агент идёт **по фазе** из `TODO.md`, коммиты отдельных пунктов **разрешены и ожидаются без отдельного разрешения** в каждом сообщении. Вне активного цикла фазы (разовая задача, review-only) — коммит только по явной просьбе.

### Цикл на один пункт чеклиста внутри фазы

1. **Правки** — минимальный дифф под **один** пункт; смотреть соседний код и стиль репозитория. Не начинать следующий пункт, пока текущий не закоммичен.
2. **Проверка** — если для пункта есть автотесты (`test/`, `npm test`), прогнать до зелёного; иначе `npx tsc --noEmit` (или `npm run build`) и smoke по SPEC (импорт extension, `--help` команд Pi при наличии). Явно отметить «tests: n/a», если покрытия ещё нет. Не пропускать без причины.
3. **Code review** — запустить субагента **code-reviewer** (отдельный Task/review) по затронутым файлам; дождаться ответа.
4. **Исправления** — закрыть Critical из ревью **и** красное на тестах/tsc; Suggestions — по смыслу. После правок — повторный прогон. Всё — **в том же** пункте, до коммита.
5. **Коммит (обязательный шлюз)** — ровно **один** атомарный коммит на пункт. Проверить `git status` — рабочее дерево чистое.
6. **Только после чистого дерева** — следующий пункт той же фазы.

Запрещено: накапливать правки нескольких пунктов и коммитить «в конце фазы»; переходить к п.6 без п.5; коммитить с красными тестами/tsc; откладывать коммит «на потом».

### Конец фазы

- Функциональные проверки всей фазы (manual E2E по SPEC §12 — когда extension готов к прогону).
- Отдельный коммит **`TODO.md`** и **`AGENTS.md`**: отметить выполненные `[x]`, статус фаз, правки workflow. Допустимо **одним** коммитом вместе.
- По умолчанию — **остановиться** и позвать пользователя на просмотр перед следующей фазой; если пользователь просит «без пауз между фазами» — коммит кода + коммит TODO/AGENTS и сразу следующая фаза.

### Атомарные коммиты

Один коммит = **одна атомарная мысль**: изменение, которое можно описать одной фразой «зачем», откатить одним `git revert` и ревьюить отдельно.

| Правило | |
|---------|--|
| Граница | Один пункт чеклиста `TODO.md` → один коммит кода (если пункт слишком крупный — **разбить пункт** в `TODO.md` на подпункты). |
| Scope | Только файлы, нужные для этой мысли; без «заодно поправил соседнее». |
| Subject | `Phase N: <глагол> <что> — <зачем в двух словах>`. |
| Размер | Предпочитать узкие коммиты; несколько независимых правок в одном коммите — ошибка workflow. |
| Fixup после ревью | Доработки по замечаниям **того же** пункта — в **тот же** коммит (`git commit --amend`) **только** если коммит ещё не запушен и создан в этой сессии; иначе — отдельный узкий коммит или skill **fup-blame-commits** по запросу. |

### `TODO.md` и `AGENTS.md` во время работы

- Можно **обновлять** оба файла по ходу (чеклисты, статус фаз, уточнения workflow).
- **Нельзя** включать `TODO.md` или `AGENTS.md` в тот же коммит, что и код — только отдельный коммит (subject `TODO: …` и/или `AGENTS: …`; **можно один коммит на оба файла**).
- Отметку `[x]` в `TODO.md` для пункта — в коммите **конца фазы** (или отдельном `TODO:`), не смешивать с коммитом кода по этому пункту.

### Тесты

- Автотесты **не добавлять**, если пользователь не просил и пункт плана не требует.
- Когда тесты есть — они обязательны в шаге 2 цикла. Manual E2E с `pi` — по чеклисту SPEC §12, обычно в конце фазы или по явному пункту.

---

## Git и коммиты

| Правило | |
|---------|--|
| Когда | После каждого пункта чеклиста в активной фазе: «правки → проверка → review → commit». |
| Сколько | Один коммит на пункт; фаза из N пунктов → не меньше N коммитов кода (+ отдельный `TODO:`/`AGENTS:` в конце фазы). |
| Subject | `Phase N: …` для кода; `TODO: …` / `AGENTS: …` для плана. |
| Тело | 1–3 предложения: **зачем**, не перечисление файлов. |
| Секреты | Не коммитить токены, `.env` с реальными ключами. |
| Force-push | Только если пользователь явно попросил; предупредить про переписанную историю. |

### Антипаттерны

- Один коммит на всю фазу или на несколько `[ ]` из чеклиста.
- WIP-коммиты (`wip`, `misc`, `fixes`) без одной мысли.
- Смешивать рефакторинг и фичу из разных пунктов плана в одном коммите.

---

## Стиль кода

- TypeScript, минимальный scope; без лишней абстракции.
- Только публичный API Pi; при необходимости зеркалить логику Pi с комментарием «mirror agent-session» (SPEC §10).
- Комментарии — только для неочевидной бизнес-логики (compaction source, defer vs immediate, kept window).
- Сверяться с [`SPEC.md`](./SPEC.md) при любых архитектурных решениях.

---

## BACKLOG

Проблемы при разработке, ручном тесте с `pi`, интеграции с pi-auto-compact или неясностях API Pi — фиксировать в [`BACKLOG.md`](./BACKLOG.md). Правило: [`.cursor/rules/dev-backlog.mdc`](./.cursor/rules/dev-backlog.mdc).

---

## Связанные файлы

| Файл | Назначение |
|------|------------|
| [`TODO.md`](./TODO.md) | План, фазы, чеклисты (ведение — правила в начале файла) |
| [`SPEC.md`](./SPEC.md) | Полное ТЗ |
| [`README.md`](./README.md) | Для людей |
| [`BACKLOG.md`](./BACKLOG.md) | Журнал открытых проблем runtime/интеграции |
| [`.cursor/rules/atomic-commits-workflow.mdc`](./.cursor/rules/atomic-commits-workflow.mdc) | Cursor: атомарные коммиты (`alwaysApply`) |