diff --git a/AGENTS.md b/AGENTS.md index 99e1b2c..1565fa6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,11 +41,11 @@ ### Issue tracker -Локальный markdown: задачи и PRD живут файлами в `.scratch//` (коммитятся, `.scratch/` не в `.gitignore`). GitHub Issues не используются. См. `docs/agents/issue-tracker.md`. +GitHub Issues (через CLI `gh`). Спека фичи — файлом в `docs/specs/` (источник истины), корневой issue — тонкий, со ссылкой на спеку и чек-листом дочерних issues. См. `docs/agents/issue-tracker.md`. ### Triage labels -Пять канонических ролей, строки совпадают с именами (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`. +Пять канонических ролей как метки GitHub, имена совпадают (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`. ### Domain docs diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index d100558..aeb9959 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,24 +1,63 @@ -# Issue tracker: локальный markdown +# Issue tracker: GitHub -Задачи и PRD этого репозитория живут markdown-файлами в `.scratch/`. GitHub Issues -не используются — не вызывать `gh issue create`. Файлы в `.scratch/` коммитятся -(`.scratch/` не в `.gitignore`). +Задачи этого репозитория живут в GitHub Issues. Все операции — через CLI `gh`; +репозиторий `gh` определяет сам по `git remote`. -## Соглашения +- **Создать issue**: `gh issue create --title "..." --body "..."` (многострочное + тело — heredoc'ом). +- **Прочитать issue**: `gh issue view <номер> --comments`. +- **Список**: `gh issue list --state open --json number,title,labels` с нужными + фильтрами `--label` / `--state`. +- **Комментарий**: `gh issue comment <номер> --body "..."`. +- **Метки**: `gh issue edit <номер> --add-label "..."` / `--remove-label "..."`. +- **Закрыть**: `gh issue close <номер> --comment "..."`. -- Одна фича — один каталог: `.scratch//` -- PRD фичи — `.scratch//PRD.md` (по сути транзиентная спека: снимок - понимания на момент работы; долговечные решения идут в ADR — см. `docs/agents/domain.md`) -- Задачи реализации — `.scratch//issues/-.md`, нумерация с `01` -- Состояние триажа — строкой `Status:` у верха файла задачи (строки ролей — в `triage-labels.md`) -- Завершённая задача — `Status: done`: локальный аналог «закрыть issue» в GitHub. - Это состояние жизненного цикла трекера, а не роль триажа (в `triage-labels.md` его нет) -- Комментарии и история — в конец файла под заголовком `## Comments` +## Спека — источник истины + +- Спецификация фичи — файл в `docs/specs/`, версионируется с кодом. +- Корневой issue фичи — **тонкий**: ссылка на спеку + чек-лист дочерних issues + (`- [ ] #NN`). Содержание спеки в issue не дублируется — истина одна, в git. +- Дочерние issues — полноценные самодостаточные постановки: цель, критерии + приёмки чекбоксами, границы («что трогать нельзя»), «сначала прочитать», + команды проверки. +- Итоговые резолюции и решения — в спеку/ADR тем же PR; issue — рабочая + переписка, она не обязана переживать фичу. ## Когда скилл говорит «опубликовать в issue tracker» -Создать файл в `.scratch//` (каталог создать при необходимости). +Создать GitHub issue. ## Когда скилл говорит «достать тикет» -Прочитать файл по указанному пути. Обычно путь или номер задачи передаёт пользователь. +`gh issue view <номер> --comments`. + +## PR как поверхность триажа + +**Нет** — одиночный учебный репозиторий, внешних PR не ждём. (Если включить — +`/triage` начнёт гонять PR через те же метки и состояния командами `gh pr ...`.) + +## Wayfinding-операции + +Используются `/wayfinder`. Карта — один issue, тикеты — дочерние issues. + +- **Карта**: issue с меткой `wayfinder:map` (Notes / Decisions-so-far / Fog в теле). +- **Дочерний тикет**: sub-issue карты (`gh api` на endpoint sub-issues); если + sub-issues недоступны — пункт task-list в теле карты + `Part of #` в + начале тела тикета. Метки: `wayfinder:` (`research`/`prototype`/ + `grilling`/`task`). +- **Блокировки**: нативные issue dependencies — + `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=` + (`` — числовой database id: `gh api repos///issues/ --jq .id`, + не `#номер`). Fallback — строка `Blocked by: #` в начале тела. Тикет + разблокирован, когда все блокеры закрыты. +- **Фронтир**: открытые дети карты минус заблокированные и назначенные; первый + в порядке карты. +- **Взять в работу**: `gh issue edit --add-assignee @me`. +- **Закрыть**: комментарий с ответом, `gh issue close`, указатель на контекст — + в Decisions-so-far карты. + +## Архив + +До 2026-07-19 задачи велись markdown-файлами в `.scratch//issues/` +(фичи `data-generator` и `generator-model-time-startup-history`, задачи 01–21). +Не мигрированы; доступны в истории git — срез `0e312b3`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index 72c7dc3..a1a76a8 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,14 +1,15 @@ # Triage labels -Скиллы оперируют пятью каноническими ролями триажа. Здесь они сопоставлены со -строками, которые реально используются в этом репозитории (в строке `Status:` файла задачи). +Скиллы оперируют пятью каноническими ролями триажа. Здесь они сопоставлены с +метками GitHub Issues этого репозитория. -| Роль в mattpocock/skills | Строка у нас | Значение | +| Роль в mattpocock/skills | Метка GitHub | Значение | | ------------------------ | ----------------- | ---------------------------------------------- | | `needs-triage` | `needs-triage` | Мейнтейнеру нужно оценить задачу | | `needs-info` | `needs-info` | Ждём от репортёра дополнительную информацию | | `ready-for-agent` | `ready-for-agent` | Полностью специфицировано, можно отдать агенту | | `ready-for-human` | `ready-for-human` | Нужна ручная реализация человеком | -| `wontfix` | `wontfix` | Не будет сделано | +| `wontfix` | `wontfix` | Не будет сделано | -Правый столбец можно поменять под свою лексику. Сейчас — дефолт (строка = имя роли). +Правый столбец можно поменять под свою лексику. Сейчас — дефолт (метка = имя +роли); метки созданы в репозитории GitHub.