grayhook
2f666cab6a
All checklist items done: source fallback, steer delivery, kept inject entries, 93 tests, b003-repro gate; full two-compact RPC deferred. Co-authored-by: Cursor <cursoragent@cursor.com>
128 lines
10 KiB
Markdown
128 lines
10 KiB
Markdown
# 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 |
|
||
| Статус | **Фазы 0–15 завершены** (v1 + B-002/B-003); полный RPC two-compact E2E — см. `docs/e2e-b003-post-fix.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
|
||
├── kept.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`) |
|