diff --git a/AGENTS.md b/AGENTS.md index 62ea917..c3d215f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,3 +66,17 @@ This repository contains personal dotfiles and configurations for a highly produ Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов. Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов. + +## Agent skills + +### Issue tracker + +Задачи хранятся в отслеживаемых Git Markdown-файлах текущей ветки под `.scratch/`. Перед `merge --no-ff` они удаляются. См. `docs/agents/issue-tracker.md`. + +### Triage labels + +Используются стандартные названия состояний triage. См. `docs/agents/triage-labels.md`. + +### Domain docs + +Используется схема single-context: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..b6596de --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,34 @@ +# Документы предметной области + +Репозиторий использует схему single-context. + +## Что читать перед изучением репозитория + +- Корневой `CONTEXT.md`, если он существует. +- Относящиеся к задаче ADR из `docs/adr/`, если они существуют. + +Отсутствие этих файлов не считается ошибкой. Не нужно предлагать создать их +заранее: навык `/domain-modeling` создаёт их по мере появления устойчивых +терминов и архитектурных решений. + +## Структура + +``` +/ +├── CONTEXT.md +└── docs/ + └── adr/ +``` + +## Термины + +В названиях задач, предложениях по изменению, гипотезах и тестах нужно +использовать термины из `CONTEXT.md`. + +Если нужного понятия нет, сначала следует проверить, не вводится ли лишний +синоним. Настоящий пробел в словаре нужно передать навыку `/domain-modeling`. + +## Противоречия с ADR + +Если предлагаемое изменение противоречит существующему ADR, это нужно явно +указать, а не молча отменять принятое решение. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..6fb8fc7 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,47 @@ +# Хранилище задач: локальные Markdown-файлы + +Задачи и спецификации этого репозитория хранятся в `.scratch/`. + +## Структура + +- Одна возможность на каталог: `.scratch//`. +- Спецификация: `.scratch//spec.md`. +- Каждая задача хранится в отдельном файле: + `.scratch//issues/-.md`. +- Нумерация задач начинается с `01`. +- Состояние triage записывается строкой `Status:` в начале файла. +- Обсуждение дописывается в конец файла под заголовком `## Comments`. + +## Жизненный цикл + +- Файлы в `.scratch/` отслеживаются Git. +- Они принадлежат рабочей ветке и считаются эфемерными. +- Перед `merge --no-ff` относящийся к ветке каталог `.scratch//` + удаляется и удаление фиксируется в этой же ветке. +- После слияния содержимое задач остаётся доступно в истории Git. + +## Публикация задачи + +Когда навык просит опубликовать задачу, нужно создать файл внутри +`.scratch//`, при необходимости создав каталог. + +## Получение задачи + +Нужно прочитать файл по переданному пути. Обычно пользователь указывает путь +или номер задачи. + +## Работа `/wayfinder` + +Карта работы хранится отдельно от дочерних задач: + +- Карта: `.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`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..98bf50c --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Состояния triage + +Навыки используют пять стандартных ролей. Для локального хранилища выбранное +значение записывается в строке `Status:` файла задачи. + +| Роль навыка | Значение `Status:` | Смысл | +| --- | --- | --- | +| `needs-triage` | `needs-triage` | Задачу должен оценить сопровождающий | +| `needs-info` | `needs-info` | Нужна дополнительная информация от автора | +| `ready-for-agent` | `ready-for-agent` | Задача полностью описана и готова для агента | +| `ready-for-human` | `ready-for-human` | Задачу должен выполнить человек | +| `wontfix` | `wontfix` | Задача не будет выполняться | + +Когда навык упоминает роль triage, нужно использовать соответствующее значение +из этой таблицы.