From 0de128372f6a38d0df53c27fa25b2e7755547dc7 Mon Sep 17 00:00:00 2001 From: GRayHook Date: Wed, 17 Jun 2026 09:18:06 +0700 Subject: [PATCH] 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 --- .cursor/rules/atomic-commits-workflow.mdc | 56 ++++++++++ .cursor/rules/dev-backlog.mdc | 35 ++++++ AGENTS.md | 126 ++++++++++++++++++++++ BACKLOG.md | 50 +++++++++ TODO.md | 101 +++++++++++++++++ 5 files changed, 368 insertions(+) create mode 100644 .cursor/rules/atomic-commits-workflow.mdc create mode 100644 .cursor/rules/dev-backlog.mdc create mode 100644 AGENTS.md create mode 100644 BACKLOG.md create mode 100644 TODO.md diff --git a/.cursor/rules/atomic-commits-workflow.mdc b/.cursor/rules/atomic-commits-workflow.mdc new file mode 100644 index 0000000..fe77be6 --- /dev/null +++ b/.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` по запросу. diff --git a/.cursor/rules/dev-backlog.mdc b/.cursor/rules/dev-backlog.mdc new file mode 100644 index 0000000..8d8c64b --- /dev/null +++ b/.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:` без смысла. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..36eb022 --- /dev/null +++ b/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`) | diff --git a/BACKLOG.md b/BACKLOG.md new file mode 100644 index 0000000..591c127 --- /dev/null +++ b/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**)._ + +--- + +## Закрыто + +_Пусто._ diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..2d90f27 --- /dev/null +++ b/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) | + +--- + +## Фазы реализации + +_Пункты чеклиста добавляет владелец репозитория. Агент не заполняет фазы без запроса._ + +