diff --git a/AGENTS.md b/AGENTS.md index 47ff1ce..df3551d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,27 +52,27 @@ This repository contains personal dotfiles and configurations for a highly produ Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов. -## Agent skills +## Навыки агентов -### Issue tracker +### Хранилище задач -Задачи хранятся локальными Markdown-файлами под `.scratch/`. См. `docs/agents/issue-tracker.md`. +Задачи хранятся в Gitea Issues (`git.dementev.space`), работа с ними — через CLI `tea`. См. `docs/agents/issue-tracker.md`. -### Triage labels +### Состояния triage -Используются стандартные названия состояний triage. См. `docs/agents/triage-labels.md`. +Состояния triage — метки Gitea со стандартными названиями. См. `docs/agents/triage-labels.md`. -### Domain docs +### Документы предметной области -Используется схема single-context: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`. +Одна предметная область на весь репозиторий: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`. -### Handoffs +### Записки для передачи работы Записки для продолжения работы в новой сессии — `.scratch/handoffs/YYYYMMDD-HHMM-.md` (одноразовые, уборка best-effort; скилл `/handoff` пишет сюда). ### `.scratch/` — локальная рабочая зона -Весь `.scratch/` — заметки по ходу дела: handoffs, PRD фич, нарезка задач. Каталог в `.gitignore`: он живёт только на этой машине и в Git не попадает. +Весь `.scratch/` — заметки по ходу дела: handoffs и черновики (задачи живут в Gitea). Каталог в `.gitignore`: он живёт только на этой машине и в Git не попадает. Долговечное знание держим **вне** `.scratch/` (в `docs/`, `CONTEXT.md`) и коммитим вместе с работой. Прежде чем сливать фиче-ветку, убедись, что долговечная часть уже вынесена туда: остальное из `.scratch/` потом не восстановить. diff --git a/docs/agents/domain.md b/docs/agents/domain.md index b6596de..e7b9a54 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -1,6 +1,6 @@ # Документы предметной области -Репозиторий использует схему single-context. +В репозитории одна предметная область: один `CONTEXT.md` в корне и общие ADR. ## Что читать перед изучением репозитория diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index ff1e4f7..242f722 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,47 +1,62 @@ -# Хранилище задач: локальные Markdown-файлы +# Хранилище задач: Gitea -Задачи и спецификации этого репозитория хранятся в `.scratch/`. +Задачи и спецификации этого репозитория хранятся в Gitea Issues на +`git.dementev.space` (репозиторий `ddmitry/dotfiles`). Все операции — через +CLI `tea`. Внутри клона `tea` сам находит репозиторий и учётную запись по +`git remote`; если не нашёл, добавь `--repo ddmitry/dotfiles`. -## Структура +GitVerse — только зеркало, задачи там не ведём. -- Одна возможность на каталог: `.scratch//`. -- Спецификация: `.scratch//spec.md`. -- Каждая задача хранится в отдельном файле: - `.scratch//issues/-.md`. -- Нумерация задач начинается с `01`. -- Состояние triage записывается строкой `Status:` в начале файла. -- Обсуждение дописывается в конец файла под заголовком `## Comments`. +Заголовки, описания и комментарии задач пишутся по-русски. -## Жизненный цикл +## Команды -- `.scratch/` указан в `.gitignore`: задачи живут только на этой машине и в - Git не попадают. -- Они эфемерны: после завершения работы каталог можно удалить. -- Всё, что должно пережить задачу (решения, спецификации), до слияния - переносится в `docs/` и коммитится. +- **Создать задачу**: `tea issues create --title "..." --description-file -` + с текстом через heredoc. Метки — `--labels "a,b"`. +- **Прочитать задачу**: `tea issues <номер> --comments`. +- **Список задач**: `tea issues list --state open --labels "..." --fields + index,title,labels,assignees --output json`. +- **Комментарий**: `tea comment <номер> "..."`. +- **Метки**: `tea issues edit <номер> --add-labels "..."` / + `--remove-labels "..."`. Если метки ещё нет в репозитории, создай её: + `tea labels create --name "..." --color "#..."`. +- **Закрыть**: сначала комментарий с причиной, затем `tea issues close <номер>`. + +## PR как источник задач + +**PR как источник запросов: нет.** _(Поставь `да`, если внешние PR в этом +репозитории нужно разбирать как запросы на доработку; `/triage` читает этот +флаг.)_ + +У задач и PR в Gitea общая нумерация: голый `#42` может оказаться и тем, и +другим. Проверяй через `tea issues 42` или `tea pulls 42`. ## Публикация задачи -Когда навык просит опубликовать задачу, нужно создать файл внутри -`.scratch//`, при необходимости создав каталог. +Когда навык просит опубликовать задачу, нужно создать задачу в Gitea. ## Получение задачи -Нужно прочитать файл по переданному пути. Обычно пользователь указывает путь -или номер задачи. +Нужно выполнить `tea issues <номер> --comments`. ## Работа `/wayfinder` -Карта работы хранится отдельно от дочерних задач: +Карта — одна задача, дочерние задачи — отдельные задачи Gitea. -- Карта: `.scratch//map.md`. -- Дочерняя задача: `.scratch//issues/NN-.md`. -- Строка `Type:` содержит тип: `research`, `prototype`, `grilling` или `task`. -- Строка `Status:` содержит состояние `claimed` или `resolved`. -- Зависимости перечисляются строкой `Blocked by: NN, NN`. -- Задача свободна, если она открыта, не заблокирована и не занята. -- Из нескольких свободных задач первой выбирается задача с меньшим номером. -- При взятии задачи нужно установить `Status: claimed` и сохранить файл. -- При завершении нужно добавить ответ под заголовком `## Answer`, установить - `Status: resolved` и добавить краткий итог со ссылкой в раздел решений - файла `map.md`. +- **Карта**: задача с меткой `wayfinder:map`; в описании — разделы + «Заметки», «Принятые решения» и «Неясности». +- **Дочерняя задача**: первой строкой описания — `Часть #<карта>`; в + описании карты — список дочерних задач. Метка типа: `wayfinder:<тип>` + (`research`, `prototype`, `grilling` или `task`). +- **Зависимости**: встроенные зависимости Gitea. Добавить блокирующую + задачу: + `tea api -X POST repos/ddmitry/dotfiles/issues/<дочерняя>/dependencies + -d '{"owner":"ddmitry","repo":"dotfiles","index":<блокирующая>}'`. + Посмотреть: `tea api repos/ddmitry/dotfiles/issues//dependencies`. + Задача свободна от блокировок, когда все блокирующие задачи закрыты. +- **Свободные задачи**: открытые дочерние задачи карты без открытых + блокирующих и без исполнителя; первой берётся та, что раньше в списке карты. +- **Взять задачу**: `tea issues edit --add-assignees ddmitry` — первым + действием сессии. +- **Завершить**: комментарий с ответом, `tea issues close `, затем краткий + итог со ссылкой в раздел «Принятые решения» описания карты. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index 98bf50c..4974a73 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,9 +1,10 @@ # Состояния triage -Навыки используют пять стандартных ролей. Для локального хранилища выбранное -значение записывается в строке `Status:` файла задачи. +Навыки используют пять стандартных ролей. В Gitea каждая роль — метка +задачи с тем же названием. Если метки ещё нет в репозитории, её нужно +создать (`tea labels create`), а не придумывать другое название. -| Роль навыка | Значение `Status:` | Смысл | +| Роль навыка | Метка в Gitea | Смысл | | --- | --- | --- | | `needs-triage` | `needs-triage` | Задачу должен оценить сопровождающий | | `needs-info` | `needs-info` | Нужна дополнительная информация от автора | @@ -11,5 +12,5 @@ | `ready-for-human` | `ready-for-human` | Задачу должен выполнить человек | | `wontfix` | `wontfix` | Задача не будет выполняться | -Когда навык упоминает роль triage, нужно использовать соответствующее значение +Когда навык упоминает роль triage, нужно использовать соответствующую метку из этой таблицы.