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>
This commit is contained in:
@@ -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`) |
|
||||
Reference in New Issue
Block a user