grayhook
0de128372f
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>
102 lines
5.3 KiB
Markdown
102 lines
5.3 KiB
Markdown
# 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
|
||
|
||
-->
|