diff --git a/README.md b/README.md index 548a806..f2eed6a 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,230 @@ -# Схема OpenSpec `use-case-driven` +# Общие инструменты для OpenSpec и Codex -`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на -базовой `spec-driven`. Она задаёт формат артефактов change и спецификаций -поведения; подробные правила схемы находятся в -[README схемы](openspec/schemas/use-case-driven/README.md). +Репозиторий содержит три переиспользуемых артефакта: +| Артефакт | Назначение | Где находится | +|---|---|---| +| Схема OpenSpec `use-case-driven` | Русскоязычные спецификации поведения и workflow `proposal → specs / design → tasks → apply` | [`openspec/schemas/use-case-driven/`](openspec/schemas/use-case-driven/) | +| Заготовки `AGENTS.md` и `config.yaml` с контекстом проекта | Правила агента, параметры проекта и начальная навигация по постоянным документам | [`examples/project-bootstrap/`](examples/project-bootstrap/) | +| Скилл Codex `task-tracker` | Одна задача на change: привязка, метка приложения, синхронизация, учёт времени, archive и коммит | [`skills/task-tracker/SKILL.md`](skills/task-tracker/SKILL.md) | -## Чем отличается от `spec-driven` +Схема и скилл хранятся и развиваются здесь. Подключайте их символическими +ссылками из пользовательских каталогов; обновление клона обновляет общий +источник. Проектные `AGENTS.md` и `config.yaml` копируйте и адаптируйте: +они содержат настройки конкретного приложения. -- В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`. - Здесь используются сценарии использования без Gherkin: полные или - сокращённые, связанные с функциональными требованиями. -- Один `Requirement` описывает завершённую функцию и содержит один `Scenario`. - Подробные правила, устойчивые контракты и обязательные ограничения - фиксируются в локальных `FR`; HTTP-контракт размещается в `CONTRACT`. -- Master-спецификация явно описывает `Purpose`, `Границы` ответственности - capability и полный набор `Requirements`. Delta-спецификации меняют требования - стандартными операциями OpenSpec. -- Инструкции и пояснительный текст ориентированы на русский язык; технические - идентификаторы и синтаксис OpenSpec сохраняются. +## 1. Схема `use-case-driven` -## Подключение схемы в проектах +В отличие от базовой `spec-driven`, схема описывает поведение полными или +сокращёнными use cases без Gherkin. Один `Requirement` задаёт завершённую +функцию с одним `Scenario`; локальные `FR` фиксируют подробные правила, +устойчивые контракты и ограничения. HTTP-контракт находится в `CONTRACT`. +Master specs описывают `Purpose`, границы capability и требования; delta specs +используют стандартные операции OpenSpec. Технический синтаксис сохраняется, +пояснения пишутся по-русски. Подробности — в [README схемы](openspec/schemas/use-case-driven/README.md). -Схему можно подключить один раз для всех проектов пользователя. OpenSpec ищет -пользовательские схемы в `~/.local/share/openspec/schemas` на macOS и Linux, -а в `%LOCALAPPDATA%\openspec\schemas` на Windows. Если задана переменная -`XDG_DATA_HOME`, OpenSpec использует `$XDG_DATA_HOME/openspec/schemas` вместо -стандартного пути. +На macOS/Linux пользовательские схемы находятся в +`${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas`, на Windows — +в `%LOCALAPPDATA%\openspec\schemas`, либо под `XDG_DATA_HOME`, если он задан. -1. Клонируйте этот репозиторий в удобную папку. Путь к клону можно выбрать - самостоятельно. -2. В пользовательской папке схем создайте ссылку с именем `use-case-driven`, - ведущую на `openspec/schemas/use-case-driven` внутри клона. +## 2. Заготовки проектных инструкций и конфигурации + +После `openspec init` перенесите в прикладной проект нужные части +[`examples/project-bootstrap/`](examples/project-bootstrap/): + +- [`AGENTS.md`](examples/project-bootstrap/AGENTS.md) — навигация по контексту, + правила OpenSpec и вызовы `task-tracker` в жизненном цикле change; +- [`openspec/config.yaml`](examples/project-bootstrap/openspec/config.yaml) — + выбор схемы и начальный контекст OpenSpec; +- `openspec/context/` — индекс контекста, правила ADR и шаблон решения. + +Объедините заготовки с существующими файлами, сохраняя применимые инструкции +и настройки проекта. Заполните в проектном `AGENTS.md`: + +```markdown +## Task Management + +Для всех OpenSpec Changes используй скилл `task-tracker`. + +Task tracker configuration: + +- Project key: +- Application label: + +Lifecycle: + +- Если пользователь передал ID задачи YouTrack для начала Explore/Propose или + change, используй эту задачу и не создавай новую. +- При создании change без переданного ID создай или привяжи задачу после содержательного proposal. +- При существенном изменении change синхронизируй существующую задачу. +- После каждого рабочего сеанса Apply синхронизируй фактическое время. +- Перед archive выполни финальную синхронизацию; после успешной архивации + закрой задачу и закоммить изменения change с русским описанием в 4–7 слов. + При ошибке archive задачу не закрывай. +- При повторном запросе возобнови незавершённую синхронизацию по существующей + связи, включая архивные changes. + +Все операции управления задачами выполняй через скилл `task-tracker`. +``` + +`Project key` — ключ проекта в трекере, `Application label` — имя приложения, +которым маркируется каждая задача. Без обоих значений скилл не создаёт задачу. +Заполните эти значения для каждого прикладного проекта в его `AGENTS.md`. +Типовая заготовка хранится только в `examples/project-bootstrap/AGENTS.md`. + +В `openspec/config.yaml` укажите `schema: use-case-driven` и дополните +предметный контекст и правила OpenSpec. Правила внешнего трекера в этот файл +не добавляются. Локальный [`openspec/config.yaml`](openspec/config.yaml) +описывает настройки самого репозитория; переносимая заготовка находится +в `examples/project-bootstrap/`. + +## 3. Скилл `task-tracker` + +Скилл создаёт или привязывает одну верхнеуровневую +задачу на change либо использует явно переданный ID, сохраняет метку приложения, +обновляет содержательное описание без копирования `tasks.md`, учитывает время +от Explore и коммитит изменения после успешной архивации и синхронизации задачи. + +Границы компонентов: + +| Компонент | Ответственность | +|---|---| +| Проектный `AGENTS.md` | Когда вызывать скилл, ключ проекта и метка приложения | +| `task-tracker` | Логические операции, связь с change и правила провайдера | +| OpenSpec | Спецификации, Change, Apply и Archive | +| MCP | Технический доступ к внешнему трекеру | + +Текущая реализация использует YouTrack MCP; настройте его доступность в Codex. +Выбор поля `Labels` или YouTrack-тега, синхронизация статусов и учёт времени описаны +[в едином SKILL.md](skills/task-tracker/SKILL.md). +Для смены трекера меняйте только скилл. Перенос существующих +задач требует явного соответствия ID, чтобы не потерять историю связи. + +### Связь, сохраняющаяся после archive + +Источник связи — `task-tracker.yaml` внутри каталога change: + +```text +openspec/changes//task-tracker.yaml + ↓ openspec archive +openspec/changes/archive//task-tracker.yaml +``` + +Archive переносит весь каталог, включая файл связи. После успешного переноса +закройте YouTrack-задачу и зафиксируйте относящиеся к change изменения +Git-коммитом с русским сообщением из 4–7 слов. Исходный `change_id`, +непрозрачный `task_id`, URL и снимок проектных параметров остаются в файле. +Не пытайтесь восстанавливать ID только из архивного имени: change сам может +начинаться с даты. Сохраняйте файл в Git вместе с change и архивом. +Формат и правила восстановления — в +[`SKILL.md`](skills/task-tracker/SKILL.md). + +Запись содержит незавершённую операцию и журнал уже учтённого времени. +После ошибки MCP скилл проверяет внешнее состояние перед повтором. При +неизвестном результате создания или записи времени автоматический повтор +запрещён до сверки. Если задача не закрылась после archive, связь и pending +остаются в архиве для следующей сессии. + +Это агентный workflow: самостоятельный запуск `openspec archive` вне Codex +переносит файл, но не вызывает скилл, не синхронизирует задачу и не создаёт +коммит. Для последующей +синхронизации попросите Codex использовать `$task-tracker` для архивного change. +При одновременной работе нескольких агентов требуется согласовать операции: +файл связи не является распределённой блокировкой. + +## Подключение из домашней директории ### macOS и Linux -Команды учитывают `XDG_DATA_HOME`, если он задан. Замените путь в `ln -s` на -путь к своему клону: +Замените `/path/to/openspec-schema` на абсолютный путь к своему клону: ```sh +tooling_repo="/path/to/openspec-schema" schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas" -mkdir -p "$schemas_dir" -ln -s "/path/to/openspec-schema/openspec/schemas/use-case-driven" \ +skills_dir="$HOME/.agents/skills" + +mkdir -p "$schemas_dir" "$skills_dir" +ln -s "$tooling_repo/openspec/schemas/use-case-driven" \ "$schemas_dir/use-case-driven" +ln -s "$tooling_repo/skills/task-tracker" "$skills_dir/task-tracker" ``` +Codex обнаруживает пользовательские скиллы в `~/.agents/skills` и поддерживает +ссылки на каталоги скиллов. Если новый скилл не появился, перезапустите Codex. +См. [официальную документацию о скиллах](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills). + ### Windows PowerShell -Замените путь в `$schemaSource` на путь к своему клону. Junction создаёт ссылку -на папку без копирования файлов: +Junction позволяет использовать исходные каталоги без копирования: ```powershell +$toolingRepo = 'D:\path\to\openspec-schema' $schemasDir = if ($env:XDG_DATA_HOME) { Join-Path $env:XDG_DATA_HOME 'openspec\schemas' } else { Join-Path $env:LOCALAPPDATA 'openspec\schemas' } -$schemaSource = 'D:\path\to\openspec-schema\openspec\schemas\use-case-driven' -New-Item -ItemType Directory -Force -Path $schemasDir -New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') -Target $schemaSource +$skillsDir = Join-Path $HOME '.agents\skills' +New-Item -ItemType Directory -Force -Path $schemasDir, $skillsDir +New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') ` + -Target (Join-Path $toolingRepo 'openspec\schemas\use-case-driven') +New-Item -ItemType Junction -Path (Join-Path $skillsDir 'task-tracker') ` + -Target (Join-Path $toolingRepo 'skills\task-tracker') ``` -После этого изменения схемы в клоне сразу доступны всем проектам, в которых -указано `schema: use-case-driven`. Проверьте подключение из каталога проекта: +Команды предполагают, что пути назначения ещё свободны. Если схема уже +подключена, создайте только ссылку на скилл. Перед заменой существующей +папки/ссылки проверьте её содержимое и источник. + +Проверьте схему из каталога прикладного проекта: ```sh openspec schema which use-case-driven openspec schema validate use-case-driven ``` -Если в проекте есть собственная схема `openspec/schemas/use-case-driven`, она -имеет приоритет над пользовательской. +Затем убедитесь, что `$task-tracker` появился среди доступных скиллов Codex. +Ссылка на скилл не устанавливает MCP и не заполняет проектный `AGENTS.md`. -Команды создания ссылки предполагают, что путь назначения ещё не занят. Если -там уже есть папка или ссылка `use-case-driven`, сначала проверьте её содержимое -и источник, прежде чем заменять. +Проектная схема `openspec/schemas/use-case-driven` имеет приоритет над +пользовательской. Кроме того, схема ссылается на вспомогательные файлы +относительно проекта (`validate_format.py`, `patterns/`). Для доступа к ним +создайте в проекте ссылку `openspec/schemas/use-case-driven` на ту же общую +схему либо адаптируйте пути инструкций. Пользовательская ссылка сама +эти проектные пути не создаёт. -В текущей схеме инструкции также ссылаются на дополнительные файлы по путям -относительно проекта, например -`openspec/schemas/use-case-driven/validate_format.py` и `patterns/`. Одна -пользовательская ссылка делает схему и шаблоны доступными OpenSpec, но не -создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная -проектная ссылка либо адаптация инструкций к расположению активной схемы. +## Переход со старой интеграции -### Заготовки контекста проекта +В прикладных проектах перенесите ключ и метку из старого `context` в +`AGENTS.md`, добавьте lifecycle из заготовки и подключите скилл. Удалите +старые инструкции трекера из `config.yaml`, включая +`operations.archive.guidance`; остальные контекст и правила сохраните. +Если схема скопирована в проект вместо ссылки, обновите также её копию. -Ссылка на пользовательскую схему также не устанавливает `AGENTS.md` или -`openspec/context/` в проект-потребитель. Для начальной настройки можно вручную -скопировать и адаптировать файлы из -[`examples/project-bootstrap/`](examples/project-bootstrap/). Комплект включает -инструкции агента, индекс контекста, правила ADR и копию ADR-шаблона. Содержимое -индекса и любые дополнительные документы контекста должны соответствовать -конкретному проекту. В комплекте нет принятых ADR и описаний бизнес-домена. +Существующие ID/URL в proposal сохраняйте до проверенной привязки. +Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после +проверки задачи. Архивным changes без однозначной связи новую задачу +автоматически не создаёт. +## Проверки и ограничения -## Статус +```sh +openspec schema validate use-case-driven +python3 -m unittest discover -s tests -v +``` -Схема находится в стадии доработки. Описаны ещё не все типы функциональных -требований и форматы контрактов: например, для FR `[UI]` пока нет подробного -паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует, -что при подготовке спецификации будут выявлены все применимые требования — в -том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно -учитывать при анализе изменения. +Тесты `test_task_tracker_archive.py` используют установленный `openspec` CLI +во временных каталогах и проверяют сохранение связи и журнала при успешном +archive, отказе валидации и конфликте архива. Они не обращаются к трекеру; +без CLI пропускаются. Frontmatter скилла можно отдельно проверить +`scripts/quick_validate.py` из установленного `skill-creator`. + +Создание, повторная привязка, обновление, закрытие, ошибки MCP и отсутствие +конфигурации описаны в скилле. Их внешнее выполнение требует доступного +провайдера; инструктивный скилл не даёт программных гарантий исполнения. +Для сквозной проверки используйте согласованный тестовый проект, не создавайте +тестовые задачи в рабочем проекте без согласования. + +Схема продолжает развиваться: не все типы FR и форматы контрактов имеют +подробные паттерны, например FR `[UI]`. Применимые требования безопасности, +аудита и ролевой модели нужно явно учитывать при анализе изменения. diff --git a/examples/project-bootstrap/AGENTS.md b/examples/project-bootstrap/AGENTS.md index 949c173..41daa3e 100644 --- a/examples/project-bootstrap/AGENTS.md +++ b/examples/project-bootstrap/AGENTS.md @@ -20,3 +20,28 @@ обновляй `openspec/context/index.md`. - Не принимай Proposed ADR самостоятельно. При конфликте запроса с принятым ADR явно сообщи о нём и запроси решение владельца. + +## Task Management + +Для всех OpenSpec Changes используй скилл `task-tracker`. + +Task tracker configuration: + +- Project key: +- Application label: + +Lifecycle: + +- Если пользователь передал ID задачи YouTrack для начала Explore/Propose или + change, используй эту задачу как контекст; новую задачу не создавай. +- При создании change без переданного ID создай или привяжи задачу после + содержательного proposal. +- При существенном изменении change синхронизируй существующую задачу. +- После каждого рабочего сеанса Apply синхронизируй фактическое время. +- Перед archive выполни финальную синхронизацию; после успешной архивации + закрой связанную задачу и создай коммит с изменениями change и русским + описанием в 4–7 слов. При ошибке archive задачу не закрывай и коммит не создавай. +- При повторном запросе или незавершённой синхронизации возобнови работу + с существующей связью, включая архивные changes. + +Все операции управления задачами выполняй через скилл `task-tracker`. diff --git a/examples/project-bootstrap/README.md b/examples/project-bootstrap/README.md index a03bf45..2f33400 100644 --- a/examples/project-bootstrap/README.md +++ b/examples/project-bootstrap/README.md @@ -8,7 +8,8 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав В комплект входят: -- `AGENTS.md` — навигация по проектному контексту и правила OpenSpec; +- `AGENTS.md` — навигация по контексту, правила OpenSpec и вызовы `task-tracker`; +- `openspec/config.yaml` — выбор схемы и начальный контекст OpenSpec; - `openspec/context/index.md` — карта постоянных документов проекта; - `openspec/context/adr/README.md` — правила ведения ADR; - `openspec/context/adr/ADR-template.md` — заготовка нового решения. @@ -22,20 +23,29 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав `openspec/schemas/use-case-driven/templates/adr.md` в этом репозитории. При изменении исходного шаблона обновляйте его копию здесь. -После `openspec init` настройте в `openspec/config.yaml` проектные параметры -интеграции YouTrack в существующем блоке `context`, сохранив остальной контекст: +После `openspec init` объедините заготовку `openspec/config.yaml` с конфигурацией +проекта, сохранив существующие настройки. Выберите `schema: use-case-driven` +и дополните предметный контекст. Настройки задач заполняйте в `AGENTS.md`: -```yaml -context: | - YouTrack project key: - YouTrack application label: +```markdown +Task tracker configuration: + +- Project key: +- Application label: ``` -Укажите ключ проекта и имя приложения, которое должно записываться в тег каждой -задачи. Общие правила создания задачи, учёта времени и архивации берутся из -схемы `use-case-driven`. Добавьте также `operations.archive.guidance` из раздела -«Настройка YouTrack» в README схемы: OpenSpec загружает эту подсказку отдельно -при вызове `openspec instructions archive`. +Укажите ключ проекта и имя приложения, которым маркируется каждая задача. Скилл +сохраняет его в строковое поле `Labels`, если оно есть в проекте, иначе — как +точный тег YouTrack. Если +пользователь начинает Explore/Propose с переданным ID задачи, используйте эту +задачу и не создавайте новую. +Подключите общий скилл `task-tracker` по +[инструкции корневого README](../../README.md#подключение-из-домашней-директории). +Создание или привязка, содержательные обновления, учёт времени, закрытие задачи +и коммит после успешного archive выполняются по Lifecycle из `AGENTS.md`. +Сообщение коммита должно быть на русском языке и состоять из 4–7 слов. Эти правила не нужно +добавлять в схему или `config.yaml`. Запуск OpenSpec CLI вне Codex не вызывает +скилл; для завершения внешней синхронизации обратитесь к агенту. Заготовка не содержит готовых решений или описания бизнес-домена. ADR создаются в проекте только для конкретных долгосрочных архитектурных решений. diff --git a/examples/project-bootstrap/openspec/config.yaml b/examples/project-bootstrap/openspec/config.yaml new file mode 100644 index 0000000..0ef81c3 --- /dev/null +++ b/examples/project-bootstrap/openspec/config.yaml @@ -0,0 +1,5 @@ +schema: use-case-driven + +# Дополните предметной областью и ограничениями конкретного проекта. +context: | + Постоянный контекст проекта: openspec/context/index.md. diff --git a/openspec/config.yaml b/openspec/config.yaml index e4e0cd4..9bc138f 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,11 +1,5 @@ schema: use-case-driven -# Проектные настройки YouTrack. Общие правила работы заданы в schema.yaml. -# В проектах, скопировавших эту схему, замените значения на свои. -context: | - YouTrack project key: PL - YouTrack application label: openspec-schema - rules: tasks: - >- @@ -17,13 +11,3 @@ rules: публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей, MAJOR для несовместимых изменений публичного контракта. - -operations: - archive: - guidance: - - >- - Перед `openspec archive` внеси в связанную задачу YouTrack оставшееся - фактическое время, учитывая только ещё не записанное и используя - доступный проекту тип работы. После успешной архивации переведи задачу - в конечный статус проекта по доступным полям и значениям; не угадывай - статус. Change завершён только после архивации и закрытия задачи. diff --git a/openspec/schemas/use-case-driven/README.md b/openspec/schemas/use-case-driven/README.md index 58e046a..5f22a0b 100644 --- a/openspec/schemas/use-case-driven/README.md +++ b/openspec/schemas/use-case-driven/README.md @@ -5,37 +5,6 @@ формат требований определён в `schema.yaml` и шаблонах. Существующие changes с явно указанной `schema: spec-driven` продолжают использовать свою схему. -## Настройка YouTrack - -Правила YouTrack входят в `schema.yaml`. Для каждого проекта укажи в блоке -`context` файла `openspec/config.yaml` ключ проекта и имя приложения. Добавь -строки в существующий блок, сохранив остальной проектный контекст: - -```yaml -context: | - YouTrack project key: - YouTrack application label: -``` - -Схема создаёт одну задачу `Task` на change, добавляет к ней тег с указанным -именем приложения и учитывает фактическое время от Explore до архивации. В -YouTrack этот механизм называется тегом; настройка `application label` задаёт -точное имя этого тега. Если интеграция или тег недоступны, workflow останавливается -и сообщает о проблеме, а не создаёт задачу без метки приложения. -Завершающие действия YouTrack для команды `openspec archive` настраиваются отдельно -от схемы — в `operations.archive.guidance` файла `openspec/config.yaml`: - -```yaml -operations: - archive: - guidance: - - >- - Перед openspec archive внеси в связанную задачу YouTrack оставшееся - фактическое время, учитывая только ещё не записанное. После успешной - архивации переведи задачу в конечный статус проекта по доступным полям; - не угадывай статус. Change завершён после архивации и закрытия задачи. -``` - ## Уровни спецификации - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. diff --git a/openspec/schemas/use-case-driven/schema.yaml b/openspec/schemas/use-case-driven/schema.yaml index f25f75a..f56313e 100644 --- a/openspec/schemas/use-case-driven/schema.yaml +++ b/openspec/schemas/use-case-driven/schema.yaml @@ -62,25 +62,6 @@ artifacts: Specs в Context. Отсутствующий индекс включай в scope только при введении постоянных документов контекста или принятии проектом этой навигационной модели. - YouTrack: - В `context` файла `openspec/config.yaml` обязательны строки - `YouTrack project key: ` и `YouTrack application label: `. - До создания задачи проверь через YouTrack MCP проект, тип `Task`, обязательные - поля и доступность/применимость тега ``. При отсутствии настройки, - тега, невозможности проверки или недоступности MCP остановись, сообщи о проблеме - и уточни конфигурацию либо дальнейшее действие. Не используй проект `Default`. - - После содержательного proposal, до specs/design/tasks, создай ровно одну - задачу `Task` на change, включая `skip_specs: true`. Заголовок и описание - сформируй по причине и scope proposal, добавь slug change и тег с точным - именем из `YouTrack application label`; ключ и URL внеси в YouTrack раздел - `proposal.md`. При изменении причины, scope, capabilities или impact в proposal - обновляй связанную задачу без дубликатов. Тег приложения сохраняй до изменения настройки. - - Учитывай фактическое время всей работы от Explore и подготовки proposal: - при создании задачи внеси уже затраченное; после каждого сеанса Apply добавляй - только неучтённое время отдельным work item с доступным проекту типом работы. - Финальную синхронизацию времени и статуса выполняй по `openspec instructions archive`. requires: [] - id: specs @@ -285,7 +266,4 @@ apply: контекста и его индекса. Если индекс существует или его создание входит в tasks.md, проверь, что он соответствует фактическому набору документов. Убедись, что требования Specs не продублированы в Context. - Для связанной задачи YouTrack после каждого рабочего сеанса запиши только - ещё не учтённое фактическое время через MCP, используя доступный тип работы. - Перед архивацией change проверь, что учтено всё время начиная с Explore. Остановись, если столкнёшься с препятствием или потребуется уточнение. diff --git a/openspec/schemas/use-case-driven/templates/proposal.md b/openspec/schemas/use-case-driven/templates/proposal.md index 0191b18..7c84679 100644 --- a/openspec/schemas/use-case-driven/templates/proposal.md +++ b/openspec/schemas/use-case-driven/templates/proposal.md @@ -33,7 +33,3 @@ - -## YouTrack - -- Задача: `` — diff --git a/skills/task-tracker/SKILL.md b/skills/task-tracker/SKILL.md new file mode 100644 index 0000000..54ce2b3 --- /dev/null +++ b/skills/task-tracker/SKILL.md @@ -0,0 +1,118 @@ +--- +name: task-tracker +description: Веди задачу YouTrack при работе с OpenSpec Change, сохраняй связь после archive и учитывай фактическое время. +--- + +# Task Tracker + +Одна верхнеуровневая задача на change; без подзадач и копирования `tasks.md`. +Используй YouTrack MCP по текущим контрактам инструментов. +Если пользователь передал ID задачи для начала Explore/Propose или работы над +change, начинай с контекста этой задачи и используй её; новую задачу не создавай. + +## Настройки и связь + +Читай `Project key` и `Application label` из применимого `AGENTS.md`. +Способ хранения метки определяй по схеме полей проекта: используй строковое +custom field `Labels`, если оно есть; иначе используй точный тег YouTrack. +Не записывай значение одновременно в поле и тег. Отсутствующие значения, +placeholders или конфликт настроек требуют уточнения. + +Храни `task-tracker.yaml` в каталоге change реального OpenSpec store, +включай в Git: archive переносит файл вместе с change. + +```yaml +version: 1 +change_id: improve-validation +project_key: EXAMPLE +application_label: order-service +task_id: null +task_url: null +sync: {pending: null, last_error: null} +worklog: + - {id: session-1, date: '2026-10-14', minutes: 25, description: Explore, status: pending} +``` + +`change_id` сохраняет исходный ID, `task_id` непрозрачен, URL берётся из ответа. +Перед изменениями YouTrack сохраняй `sync.pending`: `create`, `update` или `close`; +очищай вместе с `last_error` после проверки всей операции, включая тег и время. +Записывай атомарно, сохраняя неизвестные поля; разрешай конфликты записей до вызовов. + +## Жизненный цикл + +1. **Найди:** приоритет у явно переданного пользователем ID, затем у связи + в активном каталоге/архиве по точному `change_id`, старых ссылок proposal + и результатов поиска. Для переданного ID сразу вызови `get_issue`; проверь + существование задачи, проект, тип и отсутствие `subtask of`. Используй её + как авторитетную связь для этого запроса, даже если локальная связь отсутствует + или содержит прежний ID; прежнюю задачу не обновляй. Если ID не существует + или не подходит по проекту/типу, остановись и сообщи об этом — замену не создавай. + Для остальных найденных задач через `get_issue` проверь принадлежность change, + проект и отсутствие `subtask of`. + Без ID ищи `search_issues` по проекту и маркеру + `OpenSpec Change: /`; для старых задач также slug. + Проверь кандидатов, все страницы, открытые и закрытые задачи. + Неоднозначность требует уточнения; ошибка чтения/поиска, включая 404, + не разрешает создание замены. +2. **Создай/привяжи:** если пользователь передал ID, привяжи эту задачу до + Explore/Propose и используй её описание как исходный контекст; `create_issue` + запрещён для этого запроса. Иначе, после содержательного proposal и до + specs/design/tasks (включая `skip_specs`), привяжи найденную задачу или создай + новую только для активного change после полного поиска без результатов и + незавершённых попыток. + Через `get_project` и `get_issue_fields_schema` проверь проект, + `Type: Task` и обязательные поля. Сверь схему проекта с правилом выбора + способа хранения в разделе «Настройки и связь». + `create_issue`: русский заголовок по proposal и блок описания из шага 3, + без родителя. Если найдено строковое поле `Labels`, передай в `customFields` + точное значение `Application label`; если поля нет, добавь точный тег через + `manage_issue_tags`. Сразу сохрани ID/URL и проверь через `get_issue`, что + метка записана выбранным способом. + Для существующей задачи сначала прочитай поле/теги через `get_issue`. + Если метка уже есть — не меняй её. Если поле `Labels` непустое и содержит + другое значение, не перезаписывай его и уточни, как сохранить оба значения. + При работе через тег не подменяй имя похожим. Если `manage_issue_tags` вернул + ошибку, сохрани полный ответ, включая подсказки, и перечитай задачу на случай + частично успешной операции. Сообщение «tag not found or not accessible» не + различает отсутствующий тег и тег, скрытый настройками доступа: проверь точное + имя; при верном имени попроси владельца/администратора проверить владельца, + видимость и права изменения тега. При отказе по задаче проверь права проекта. + После устранения причины повтори действие для той же задачи и подтверди через + `get_issue`; новую задачу из-за ошибки метки не создавай. +3. **Обнови:** через `update_issue` только при содержательных изменениях proposal. + В описании меняй только блок между `` + и ``, содержащий маркер change; добавь его старой задаче. + Сохраняй чужой текст, поля и теги; конфликт привязки/смену метки согласуй. +4. **Заархивируй, закрой и закоммить:** перед archive синхронизируй описание и + время. После подтверждённого переноса каталога читай связь из архива; через + `update_issue` установи успешный конечный статус из схемы полей и проверь + resolved. Перед изменением сохраняй `sync.pending: close`; после проверки + очисти его и `last_error`. Неясный статус уточни. При отмене или ошибке archive + задачу не закрывай и коммит не создавай. Уже завершённую задачу не закрывай + повторно и не переоткрывай. + После успешного archive и синхронизации YouTrack создай Git-коммит со всеми + относящимися к change изменениями, включая архив и очищенную связь. Перед + коммитом проверь `git status` и diff; не включай несвязанные или чужие + staged/working-tree изменения. Если изменения нельзя безопасно отделить, + оставь файлы незакоммиченными, сообщи о блокере и не создавай частичный коммит. + Сообщение коммита должно быть на русском, описывать фактические изменения и + содержать 4–7 слов, считая слова по пробелам. Для архивного change продолжай + только незавершённые шаги и не запускай archive повторно. + +## Время и восстановление + +Измеряй время от Explore/proposal, без ожиданий и перерывов; синхронизируй +после сеансов Apply и перед archive. Старую длительность не выдумывай. +У каждого интервала уникальный неизменный ID: перед `log_work` сохраняй `sending`, +после подтверждения — `recorded`. Передавай локальную дату, положительные минуты, доступный проекту +`workType` и описание с `OpenSpec Worklog: `; `recorded` повторно не отправляй. + +При ошибке MCP/локальной записи останови синхронизацию, сохрани связь, +незавершённые операции и `last_error`. Если archive уже выполнен, проверь +архивную связь, состояние задачи и Git status/log; продолжи только незавершённые +закрытие или коммит, не повторяя archive и уже выполненный коммит. Перед повтором +сверяй внешнее состояние. +Неопределённый результат создания запрещает автоматическое повторное создание +даже при пустом поиске; `sending` требует сверки work items или ручной проверки, +если MCP их не читает. Выполненный archive не откатывай. +Сообщи change, ID/URL задачи, результат и оставшееся действие. diff --git a/tests/test_task_tracker_archive.py b/tests/test_task_tracker_archive.py new file mode 100644 index 0000000..976f07d --- /dev/null +++ b/tests/test_task_tracker_archive.py @@ -0,0 +1,121 @@ +"""Check the binding's storage contract with the real CLI; no tracker calls.""" + +import json +import shutil +import subprocess +import tempfile +import unittest +from pathlib import Path + + +OPENSPEC = shutil.which("openspec") +SCHEMA_DIR = Path(__file__).resolve().parents[1] / "openspec/schemas/use-case-driven" + + +@unittest.skipUnless(OPENSPEC, "OpenSpec CLI is not installed") +class TaskTrackerArchiveTests(unittest.TestCase): + def setUp(self) -> None: + self.temp_dir = tempfile.TemporaryDirectory() + self.project = Path(self.temp_dir.name).resolve() + self.root = self.project / "openspec" + shutil.copytree(SCHEMA_DIR, self.root / "schemas/use-case-driven", + ignore=shutil.ignore_patterns("__pycache__")) + (self.root / "config.yaml").write_text("schema: use-case-driven\n") + (self.root / "specs").mkdir() + + def tearDown(self) -> None: + self.temp_dir.cleanup() + + def create_change(self, change_id: str) -> tuple[Path, bytes]: + change = self.root / "changes" / change_id + change.mkdir(parents=True) + (change / ".openspec.yaml").write_text( + "schema: use-case-driven\ncreated: '2026-10-14'\nskip_specs: true\n" + ) + (change / "proposal.md").write_text( + "## Why\nImprove tooling.\n\n## What Changes\nUpdate instructions.\n" + "\n## Capabilities\nNo behavior changes.\n\n## Impact\nDocumentation.\n" + ) + (change / "tasks.md").write_text("## 1. Documentation\n- [x] 1.1 Update\n") + binding = { + "version": 1, "change_id": change_id, + "project_key": "EXAMPLE", "application_label": "order-service", + "task_id": "opaque-id/123", "task_url": "https://tracker.example/task/123", + "sync": {"pending": "close", "last_error": "MCP unavailable"}, + "worklog": [{"id": "session-1", "date": "2026-10-14", "minutes": 25, + "description": "Proposal", "status": "recorded"}], + } + # JSON is valid YAML; the test needs only the standard library. + content = json.dumps(binding, ensure_ascii=False, indent=2).encode() + (change / "task-tracker.yaml").write_bytes(content) + return change, content + + def archive(self, change_id: str) -> tuple[subprocess.CompletedProcess, dict]: + result = subprocess.run( + [OPENSPEC, "archive", change_id, "--yes", "--json"], + cwd=self.project, capture_output=True, text=True, timeout=30, + ) + self.assertTrue(result.stdout, result.stderr) + return result, json.loads(result.stdout) + + def test_archive_moves_binding_and_pending_sync_then_retry_preserves_it(self) -> None: + change_id = "improve-order-validation" + change, content = self.create_change(change_id) + + result, output = self.archive(change_id) + + self.assertEqual(result.returncode, 0, result.stderr + result.stdout) + archived = Path(output["archive"]["path"]) + self.assertFalse(change.exists()) + self.assertEqual((archived / "task-tracker.yaml").read_bytes(), content) + # A fresh session can find the original ID without interpreting the archive name. + matches = [path for path in (self.root / "changes/archive").glob("*/task-tracker.yaml") + if json.loads(path.read_text())["change_id"] == change_id] + self.assertEqual(matches, [archived / "task-tracker.yaml"]) + + retry, _ = self.archive(change_id) + + self.assertNotEqual(retry.returncode, 0) + self.assertEqual(matches[0].read_bytes(), content) + + def test_archive_preserves_change_id_that_already_starts_with_date(self) -> None: + change_id = "2026-10-01-improve-validation" + _, content = self.create_change(change_id) + + result, output = self.archive(change_id) + + self.assertEqual(result.returncode, 0, result.stderr + result.stdout) + archived = Path(output["archive"]["path"]) + self.assertEqual((archived / "task-tracker.yaml").read_bytes(), content) + self.assertEqual(json.loads(content)["change_id"], change_id) + + def test_failed_validation_retains_active_binding_and_pending_sync(self) -> None: + change, content = self.create_change("invalid-change") + specs = change / "specs" + specs.mkdir() + (specs / "spec.md").write_text("## ADDED Requirements\nInvalid root spec.\n") + + result, output = self.archive(change.name) + + self.assertNotEqual(result.returncode, 0) + self.assertIsNone(output["archive"]) + self.assertEqual((change / "task-tracker.yaml").read_bytes(), content) + self.assertEqual(list((self.root / "changes").glob("archive/*/task-tracker.yaml")), []) + + def test_archive_collision_retains_both_bindings(self) -> None: + change, content = self.create_change("2026-10-01-existing-name") + archived = self.root / "changes/archive" / change.name + archived.mkdir(parents=True) + previous_binding = b'{"change_id": "earlier", "task_id": "other-task"}' + (archived / "task-tracker.yaml").write_bytes(previous_binding) + + result, output = self.archive(change.name) + + self.assertNotEqual(result.returncode, 0) + self.assertIsNone(output["archive"]) + self.assertEqual((change / "task-tracker.yaml").read_bytes(), content) + self.assertEqual((archived / "task-tracker.yaml").read_bytes(), previous_binding) + + +if __name__ == "__main__": + unittest.main()