Add agent workflow for phased development.

Introduce AGENTS.md, TODO maintenance rules, BACKLOG, and Cursor rules
so agents can run the full cycle: changes, review, fixes, and commits.

Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/rules/atomic-commits-workflow.mdc

@@ -0,0 +1,56 @@
+---
+description: Обязательные атомарные коммиты после каждого пункта TODO (pi-skill-reinject)
+alwaysApply: true
+---
+
+# Атомарные коммиты (pi-skill-reinject)
+
+В этом репозитории коммит — **обязательный шаг цикла**, не «только если пользователь попросил». Исключение: явный запрет («без коммитов», «только diff»).
+
+Полный workflow: [`AGENTS.md`](../../AGENTS.md) (фазы, review, конец фазы). Здесь — жёсткие правила коммитов.
+
+## Разрешение коммитить без отдельного запроса
+
+Когда агент идёт **по фазе** из `TODO.md` (пользователь начал фазу, продолжает «фазу N», или явно работает по чеклисту фазы):
+
+- **Можно и нужно** делать `git commit` после каждого закрытого пункта чеклиста **без** отдельного «закоммить» в сообщении.
+- Один пункт → один коммит → чистый `git status` → следующий пункт.
+
+Это правило **pi-skill-reinject** имеет приоритет над общим user rule «коммит только по запросу» **только** в активном цикле фазы в этом репозитории.
+
+**Вне цикла фазы** (разовый вопрос, review-only, правка не из `TODO.md`) — коммит **только** по явной просьбе.
+
+## Цикл на один пункт чеклиста
+
+1. Правки — **только один** пункт `TODO.md`. Не открывать следующий, пока текущий не закоммичен.
+2. Проверка — `npm test` / `npx tsc --noEmit` если применимо; иначе явно «tests: n/a». Не пропускать без причины.
+3. Code review (субагент code-reviewer) по затронутым файлам.
+4. Исправления по ревью **и** красным проверкам — в **том же** пункте, до коммита.
+5. **Коммит** — ровно один атомарный коммит; `git status` чистый.
+6. Следующий пункт — **только после** п.5.
+
+**Запрещено:** копить несколько пунктов; перейти к следующему без коммита; коммитить с красными тестами/tsc.
+
+## Одна мысль = один коммит
+
+- Один пункт чеклиста → один коммит кода (`Phase N: …`).
+- Крупный пункт — разбить в `TODO.md` на подпункты.
+- Фаза из **N** пунктов → **не меньше N** коммитов кода + отдельный `TODO:`/`AGENTS:` в конце фазы.
+
+## `TODO.md` / `AGENTS.md`
+
+- Не в одном коммите с кодом.
+- Отметки `[x]` — в коммите конца фазы, не вместе с кодом пункта.
+
+## Сообщения коммита
+
+| Тип | Subject |
+|-----|---------|
+| Код | `Phase N: …` |
+| План | `TODO: …` / `AGENTS: …` |
+
+Тело: 1–3 предложения **зачем**.
+
+## Fixup
+
+`git commit --amend` — только если коммит не запушен и создан в этой сессии; иначе узкий коммит или `fup-blame-commits` по запросу.

.cursor/rules/dev-backlog.mdc

@@ -0,0 +1,35 @@
+---
+description: Фиксировать проблемы Pi/extension в BACKLOG.md при разработке и ручном тесте
+alwaysApply: true
+---
+
+# Dev backlog (pi-skill-reinject)
+
+При разработке extension, ручном прогоне с `pi`, интеграции с pi-auto-compact или расхождении с [`SPEC.md`](../../SPEC.md) — дописать пункт в [`BACKLOG.md`](../../BACKLOG.md). Цель: позже закрыть пачкой (код, SPEC, upstream issue).
+
+## Когда писать в BACKLOG
+
+| Ситуация | Действие |
+|----------|----------|
+| API Pi ведёт себя иначе, чем в docs/SPEC | Новый пункт |
+| Гонка / ошибка с pi-auto-compact | Новый пункт |
+| E2E нестабилен, обход хрупкий | Новый пункт |
+| Пришлось копировать приватную логику Pi | Новый пункт |
+
+Не писать: extension выключен по умолчанию; нет установленного `pi`; единичный сбой без воспроизведения; задачи из плана фаз (`TODO.md`).
+
+## Как дописать
+
+1. Открыть `BACKLOG.md`, секция **Открыто**.
+2. Следующий id **`B-###`** (max + 1).
+3. Блок по шаблону из файла.
+4. Новый пункт — **вверх** секции «Открыто».
+5. Продолжить задачу пользователя — backlog не блокирует ответ.
+
+## Закрытие
+
+По запросу или при правке: `done`, дата, ссылка на коммит/issue; перенести в **Закрыто**.
+
+## Коммиты
+
+Запись в `BACKLOG.md` — отдельная мысль; не смешивать с атомарным `Phase N:` без смысла.

AGENTS.md

@@ -0,0 +1,126 @@
+# 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`) |

BACKLOG.md

@@ -0,0 +1,50 @@
+# BACKLOG — pi-skill-reinject
+
+Журнал **открытых** ограничений и сбоев при разработке, ручном тесте с `pi`, интеграции с [pi-auto-compact](https://github.com/capyup/pi-auto-compact) или неясностях API Pi.
+
+Не путать с [`TODO.md`](./TODO.md): там план разработки; здесь — наблюдения из runtime, которые потом закрывают пачкой (правка кода, документация, issue upstream Pi).
+
+Правило для агентов: [`.cursor/rules/dev-backlog.mdc`](./.cursor/rules/dev-backlog.mdc).
+
+---
+
+## Когда добавлять пункт
+
+- Поведение Pi / extension API не совпало с [`SPEC.md`](./SPEC.md) или [документацией Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md).
+- Ошибка или гонка при совместной работе с pi-auto-compact (`sendUserMessage`, `before_agent_start`, follow-up).
+- Ручной E2E не воспроизводится стабильно; обходной путь есть, но хрупкий.
+- Неясность в публичном API (события без `reason`, формат entries, settings merge).
+- Пришлось дублировать приватную логику Pi — зафиксировать риск и желаемый upstream.
+
+**Не добавлять:** ожидаемое «extension выключен по умолчанию»; отсутствие установленного `pi`; разовый сбой без воспроизведения; пункты из плана фаз (это `TODO.md`).
+
+---
+
+## Формат пункта
+
+Следующий свободный id: **`B-###`** (смотреть заголовки ниже, увеличивать номер).
+
+```markdown
+### B-001 · open · pi-api · 2026-06-17
+
+- **Сценарий:** что пытались сделать
+- **Проблема:** одно предложение — в чём затык
+- **Место:** `session_compact` / `before_agent_start` / pi-auto-compact / `src/…`
+- **Факт:** текст ошибки, неожиданное поведение, расхождение с SPEC
+- **Обход:** что сработало (или «нет»)
+- **Предложение:** правка в extension / SPEC / issue в Pi / pi-auto-compact
+```
+
+При закрытии: статус `open` → `done`, дата закрытия, ссылка на коммит/issue; блок перенести в [Закрыто](#закрыто).
+
+---
+
+## Открыто
+
+_Новые пункты — ниже (следующий id: **B-001**)._
+
+---
+
+## Закрыто
+
+_Пусто._

TODO.md

@@ -0,0 +1,101 @@
+# TODO: pi-skill-reinject
+
+План реализации extension для Pi Coding Agent. ТЗ — [`SPEC.md`](./SPEC.md). Workflow агента — [`AGENTS.md`](./AGENTS.md).
+
+---
+
+## Правила ведения `TODO.md`
+
+### Роль файла
+
+- **Единственный** источник фаз и чеклистов для цикла «работай по фазе».
+- `AGENTS.md` — как исполнять пункты; `TODO.md` — **что** делать и в каком порядке.
+- Не дублировать полное ТЗ из `SPEC.md`; в пунктах — ссылки на разделы SPEC при необходимости.
+
+### Структура фазы
+
+Каждая фаза — заголовок `### Фаза N — …` и чеклист `- [ ]` / `- [x]`.
+
+| Элемент | Правило |
+|---------|---------|
+| Нумерация | `0`, `1`, `2`, … — монотонно; не переиспользовать номера |
+| Пункт | Одна атомарная мысль = один коммит кода (см. AGENTS.md) |
+| Крупный пункт | Разбить на подпункты `- [ ]` до размера «один коммит» |
+| Статус фазы | В конце секции или в таблице в `AGENTS.md` при необходимости |
+| Зависимости | Явно: «после фазы N», «блокируется …» |
+
+### Формат пункта чеклиста
+
+```markdown
+- [ ] **Краткое имя** — что сделать; зачем в одной фразе; ссылка на SPEC §X при нужде
+```
+
+Хорошо: «**state.ts** — load/save через `appendEntry`, dedupe skills by name (SPEC §6.1)».
+
+Плохо: «сделать state» (неатомарно, непонятен scope коммита).
+
+### Коммиты и отметки `[x]`
+
+| Действие | Когда |
+|----------|--------|
+| Код по пункту | Коммит `Phase N: …` — **без** `TODO.md` в том же коммите |
+| `[x]` на пункте | В коммите **конца фазы** `TODO: …` (или отдельном `TODO:`), не вместе с кодом пункта |
+| Правки workflow | `TODO:` / `AGENTS:` — отдельный коммит; оба файла можно в одном |
+| Черновик плана | Можно править `TODO.md` по ходу; финальные галочки — с концом фазы |
+
+### Добавление и изменение плана
+
+- Новая фаза — в конец раздела «Фазы реализации», не вставлять между завершёнными без причины.
+- Отменённый пункт — `[x]` с пометкой «отменено» в тексте или удалить с записью в коммите `TODO:`.
+- Перенос между фазами — обновить оба файла (`TODO.md` + при необходимости таблицу статуса в `AGENTS.md`).
+
+### Чего не писать в `TODO.md`
+
+- Длинные спецификации (они в `SPEC.md`).
+- Журнал багов при ручном тесте — в [`BACKLOG.md`](./BACKLOG.md).
+- Секреты, пути к личным `~/.pi/…` с токенами.
+
+### Старт работы агентом
+
+1. Прочитать `AGENTS.md` и актуальную фазу в этом файле.
+2. Найти первый `- [ ]` в запрошенной фазе (или текущей незавершённой).
+3. Выполнить цикл: правки → проверка → review → исправления → коммит → следующий пункт.
+4. В конце фазы — коммит `TODO:`/`AGENTS:`, пауза для пользователя (если не сказано иначе).
+
+---
+
+## Контекст
+
+| Сейчас | Цель |
+|--------|------|
+| Только `SPEC.md` + `README.md` | Рабочий extension `src/index.ts` + тесты |
+| Default off | `/skill-reinject on` / `global on` |
+| Нет re-inject после compaction | Auto compaction → re-inject tracked skills (SPEC §5–6) |
+
+---
+
+## Решения (зафиксировано в SPEC)
+
+Ключевые решения не дублировать здесь — см. [`SPEC.md`](./SPEC.md) §5–8, §16. При расхождении при реализации — сначала обновить SPEC или зафиксировать в «Решения» ниже.
+
+| Тема | Где |
+|------|-----|
+| Триггер re-inject | `session_compact`, auto only (§5.2, §8) |
+| Доставка с pi-auto-compact | `defer` + `before_agent_start` (§6.5, §16) |
+| Персистенция | `pi.appendEntry("skill-reinject:state", …)` (§6.1) |
+| Команды | `/skill-reinject` (§7) |
+
+---
+
+## Фазы реализации
+
+_Пункты чеклиста добавляет владелец репозитория. Агент не заполняет фазы без запроса._
+
+<!-- Пример структуры (удалить при первом заполнении):
+
+### Фаза 0 — Каркас
+
+- [ ] **package.json** — manifest, devDependencies Pi
+- [ ] **src/index.ts** — пустой extension, регистрация на session_start
+
+-->