pi-auto-reinject/AGENTS.md

AGENTS.md — pi-skill-reinject

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

---

Обзор

Продукт	Extension skill-reinject для Pi Coding Agent
Цель	Отслеживать вызванные skills и повторно инжектить их после auto compaction
Статус	Спецификация готова; реализация — по фазам в TODO.md
Целевой API	Публичный ExtensionAPI Pi (extensions.md), без приватных internal imports
Совместимость	@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 при любых архитектурных решениях.

---

BACKLOG

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

---

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

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