Правки процесс работы с task tracker

This commit is contained in:
2026-10-16 21:39:10 +03:00
parent a0fe47d4d3
commit e2e2d0bcc2
10 changed files with 481 additions and 149 deletions
+190 -64
View File
@@ -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`. ## 1. Схема `use-case-driven`
Здесь используются сценарии использования без Gherkin: полные или
сокращённые, связанные с функциональными требованиями.
- Один `Requirement` описывает завершённую функцию и содержит один `Scenario`.
Подробные правила, устойчивые контракты и обязательные ограничения
фиксируются в локальных `FR`; HTTP-контракт размещается в `CONTRACT`.
- Master-спецификация явно описывает `Purpose`, `Границы` ответственности
capability и полный набор `Requirements`. Delta-спецификации меняют требования
стандартными операциями OpenSpec.
- Инструкции и пояснительный текст ориентированы на русский язык; технические
идентификаторы и синтаксис OpenSpec сохраняются.
## Подключение схемы в проектах В отличие от базовой `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 ищет На macOS/Linux пользовательские схемы находятся в
пользовательские схемы в `~/.local/share/openspec/schemas` на macOS и Linux, `${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas`, на Windows —
а в `%LOCALAPPDATA%\openspec\schemas` на Windows. Если задана переменная в `%LOCALAPPDATA%\openspec\schemas`, либо под `XDG_DATA_HOME`, если он задан.
`XDG_DATA_HOME`, OpenSpec использует `$XDG_DATA_HOME/openspec/schemas` вместо
стандартного пути.
1. Клонируйте этот репозиторий в удобную папку. Путь к клону можно выбрать ## 2. Заготовки проектных инструкций и конфигурации
самостоятельно.
2. В пользовательской папке схем создайте ссылку с именем `use-case-driven`, После `openspec init` перенесите в прикладной проект нужные части
ведущую на `openspec/schemas/use-case-driven` внутри клона. [`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: <KEY>
- Application label: <APP-NAME>
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/<change-id>/task-tracker.yaml
↓ openspec archive
openspec/changes/archive/<archive-name>/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 ### macOS и Linux
Команды учитывают `XDG_DATA_HOME`, если он задан. Замените путь в `ln -s` на Замените `/path/to/openspec-schema` на абсолютный путь к своему клону:
путь к своему клону:
```sh ```sh
tooling_repo="/path/to/openspec-schema"
schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas" schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas"
mkdir -p "$schemas_dir" skills_dir="$HOME/.agents/skills"
ln -s "/path/to/openspec-schema/openspec/schemas/use-case-driven" \
mkdir -p "$schemas_dir" "$skills_dir"
ln -s "$tooling_repo/openspec/schemas/use-case-driven" \
"$schemas_dir/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 ### Windows PowerShell
Замените путь в `$schemaSource` на путь к своему клону. Junction создаёт ссылку Junction позволяет использовать исходные каталоги без копирования:
на папку без копирования файлов:
```powershell ```powershell
$toolingRepo = 'D:\path\to\openspec-schema'
$schemasDir = if ($env:XDG_DATA_HOME) { $schemasDir = if ($env:XDG_DATA_HOME) {
Join-Path $env:XDG_DATA_HOME 'openspec\schemas' Join-Path $env:XDG_DATA_HOME 'openspec\schemas'
} else { } else {
Join-Path $env:LOCALAPPDATA 'openspec\schemas' Join-Path $env:LOCALAPPDATA 'openspec\schemas'
} }
$schemaSource = 'D:\path\to\openspec-schema\openspec\schemas\use-case-driven' $skillsDir = Join-Path $HOME '.agents\skills'
New-Item -ItemType Directory -Force -Path $schemasDir New-Item -ItemType Directory -Force -Path $schemasDir, $skillsDir
New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') -Target $schemaSource 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 ```sh
openspec schema which use-case-driven openspec schema which use-case-driven
openspec schema validate use-case-driven openspec schema validate use-case-driven
``` ```
Если в проекте есть собственная схема `openspec/schemas/use-case-driven`, она Затем убедитесь, что `$task-tracker` появился среди доступных скиллов Codex.
имеет приоритет над пользовательской. Ссылка на скилл не устанавливает MCP и не заполняет проектный `AGENTS.md`.
Команды создания ссылки предполагают, что путь назначения ещё не занят. Если Проектная схема `openspec/schemas/use-case-driven` имеет приоритет над
там уже есть папка или ссылка `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` или Существующие ID/URL в proposal сохраняйте до проверенной привязки.
`openspec/context/` в проект-потребитель. Для начальной настройки можно вручную Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после
скопировать и адаптировать файлы из проверки задачи. Архивным changes без однозначной связи новую задачу
[`examples/project-bootstrap/`](examples/project-bootstrap/). Комплект включает автоматически не создаёт.
инструкции агента, индекс контекста, правила ADR и копию ADR-шаблона. Содержимое
индекса и любые дополнительные документы контекста должны соответствовать
конкретному проекту. В комплекте нет принятых ADR и описаний бизнес-домена.
## Проверки и ограничения
## Статус ```sh
openspec schema validate use-case-driven
python3 -m unittest discover -s tests -v
```
Схема находится в стадии доработки. Описаны ещё не все типы функциональных Тесты `test_task_tracker_archive.py` используют установленный `openspec` CLI
требований и форматы контрактов: например, для FR `[UI]` пока нет подробного во временных каталогах и проверяют сохранение связи и журнала при успешном
паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует, archive, отказе валидации и конфликте архива. Они не обращаются к трекеру;
что при подготовке спецификации будут выявлены все применимые требования — в без CLI пропускаются. Frontmatter скилла можно отдельно проверить
том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно `scripts/quick_validate.py` из установленного `skill-creator`.
учитывать при анализе изменения.
Создание, повторная привязка, обновление, закрытие, ошибки MCP и отсутствие
конфигурации описаны в скилле. Их внешнее выполнение требует доступного
провайдера; инструктивный скилл не даёт программных гарантий исполнения.
Для сквозной проверки используйте согласованный тестовый проект, не создавайте
тестовые задачи в рабочем проекте без согласования.
Схема продолжает развиваться: не все типы FR и форматы контрактов имеют
подробные паттерны, например FR `[UI]`. Применимые требования безопасности,
аудита и ролевой модели нужно явно учитывать при анализе изменения.
+25
View File
@@ -20,3 +20,28 @@
обновляй `openspec/context/index.md`. обновляй `openspec/context/index.md`.
- Не принимай Proposed ADR самостоятельно. При конфликте запроса с принятым ADR - Не принимай Proposed ADR самостоятельно. При конфликте запроса с принятым ADR
явно сообщи о нём и запроси решение владельца. явно сообщи о нём и запроси решение владельца.
## Task Management
Для всех OpenSpec Changes используй скилл `task-tracker`.
Task tracker configuration:
- Project key: <KEY>
- Application label: <APP-NAME>
Lifecycle:
- Если пользователь передал ID задачи YouTrack для начала Explore/Propose или
change, используй эту задачу как контекст; новую задачу не создавай.
- При создании change без переданного ID создай или привяжи задачу после
содержательного proposal.
- При существенном изменении change синхронизируй существующую задачу.
- После каждого рабочего сеанса Apply синхронизируй фактическое время.
- Перед archive выполни финальную синхронизацию; после успешной архивации
закрой связанную задачу и создай коммит с изменениями change и русским
описанием в 4–7 слов. При ошибке archive задачу не закрывай и коммит не создавай.
- При повторном запросе или незавершённой синхронизации возобнови работу
с существующей связью, включая архивные changes.
Все операции управления задачами выполняй через скилл `task-tracker`.
+22 -12
View File
@@ -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/index.md` — карта постоянных документов проекта;
- `openspec/context/adr/README.md` — правила ведения ADR; - `openspec/context/adr/README.md` — правила ведения ADR;
- `openspec/context/adr/ADR-template.md` — заготовка нового решения. - `openspec/context/adr/ADR-template.md` — заготовка нового решения.
@@ -22,20 +23,29 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав
`openspec/schemas/use-case-driven/templates/adr.md` в этом репозитории. При `openspec/schemas/use-case-driven/templates/adr.md` в этом репозитории. При
изменении исходного шаблона обновляйте его копию здесь. изменении исходного шаблона обновляйте его копию здесь.
После `openspec init` настройте в `openspec/config.yaml` проектные параметры После `openspec init` объедините заготовку `openspec/config.yaml` с конфигурацией
интеграции YouTrack в существующем блоке `context`, сохранив остальной контекст: проекта, сохранив существующие настройки. Выберите `schema: use-case-driven`
и дополните предметный контекст. Настройки задач заполняйте в `AGENTS.md`:
```yaml ```markdown
context: | Task tracker configuration:
YouTrack project key: <KEY>
YouTrack application label: <APP-NAME> - Project key: <KEY>
- Application label: <APP-NAME>
``` ```
Укажите ключ проекта и имя приложения, которое должно записываться в тег каждой Укажите ключ проекта и имя приложения, которым маркируется каждая задача. Скилл
задачи. Общие правила создания задачи, учёта времени и архивации берутся из сохраняет его в строковое поле `Labels`, если оно есть в проекте, иначе — как
схемы `use-case-driven`. Добавьте также `operations.archive.guidance` из раздела точный тег YouTrack. Если
«Настройка YouTrack» в README схемы: OpenSpec загружает эту подсказку отдельно пользователь начинает Explore/Propose с переданным ID задачи, используйте эту
при вызове `openspec instructions archive`. задачу и не создавайте новую.
Подключите общий скилл `task-tracker` по
[инструкции корневого README](../../README.md#подключение-из-домашней-директории).
Создание или привязка, содержательные обновления, учёт времени, закрытие задачи
и коммит после успешного archive выполняются по Lifecycle из `AGENTS.md`.
Сообщение коммита должно быть на русском языке и состоять из 4–7 слов. Эти правила не нужно
добавлять в схему или `config.yaml`. Запуск OpenSpec CLI вне Codex не вызывает
скилл; для завершения внешней синхронизации обратитесь к агенту.
Заготовка не содержит готовых решений или описания бизнес-домена. ADR создаются Заготовка не содержит готовых решений или описания бизнес-домена. ADR создаются
в проекте только для конкретных долгосрочных архитектурных решений. в проекте только для конкретных долгосрочных архитектурных решений.
@@ -0,0 +1,5 @@
schema: use-case-driven
# Дополните предметной областью и ограничениями конкретного проекта.
context: |
Постоянный контекст проекта: openspec/context/index.md.
-16
View File
@@ -1,11 +1,5 @@
schema: use-case-driven schema: use-case-driven
# Проектные настройки YouTrack. Общие правила работы заданы в schema.yaml.
# В проектах, скопировавших эту схему, замените значения на свои.
context: |
YouTrack project key: PL
YouTrack application label: openspec-schema
rules: rules:
tasks: tasks:
- >- - >-
@@ -17,13 +11,3 @@ rules:
публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений, публичный контракт. Начиная с 1.0.0 используй PATCH для исправлений,
рефакторинга и документации, MINOR для обратно совместимых возможностей, рефакторинга и документации, MINOR для обратно совместимых возможностей,
MAJOR для несовместимых изменений публичного контракта. MAJOR для несовместимых изменений публичного контракта.
operations:
archive:
guidance:
- >-
Перед `openspec archive` внеси в связанную задачу YouTrack оставшееся
фактическое время, учитывая только ещё не записанное и используя
доступный проекту тип работы. После успешной архивации переведи задачу
в конечный статус проекта по доступным полям и значениям; не угадывай
статус. Change завершён только после архивации и закрытия задачи.
@@ -5,37 +5,6 @@
формат требований определён в `schema.yaml` и шаблонах. Существующие changes формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему. с явно указанной `schema: spec-driven` продолжают использовать свою схему.
## Настройка YouTrack
Правила YouTrack входят в `schema.yaml`. Для каждого проекта укажи в блоке
`context` файла `openspec/config.yaml` ключ проекта и имя приложения. Добавь
строки в существующий блок, сохранив остальной проектный контекст:
```yaml
context: |
YouTrack project key: <KEY>
YouTrack application label: <APP-NAME>
```
Схема создаёт одну задачу `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 — отдельная бизнес-функция или понятный результат в иерархии доменов. - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
@@ -62,25 +62,6 @@ artifacts:
Specs в Context. Отсутствующий индекс включай в scope только при введении Specs в Context. Отсутствующий индекс включай в scope только при введении
постоянных документов контекста или принятии проектом этой навигационной модели. постоянных документов контекста или принятии проектом этой навигационной модели.
YouTrack:
В `context` файла `openspec/config.yaml` обязательны строки
`YouTrack project key: <KEY>` и `YouTrack application label: <APP-NAME>`.
До создания задачи проверь через YouTrack MCP проект, тип `Task`, обязательные
поля и доступность/применимость тега `<APP-NAME>`. При отсутствии настройки,
тега, невозможности проверки или недоступности 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: [] requires: []
- id: specs - id: specs
@@ -285,7 +266,4 @@ apply:
контекста и его индекса. Если индекс существует или его создание входит в контекста и его индекса. Если индекс существует или его создание входит в
tasks.md, проверь, что он соответствует фактическому набору документов. tasks.md, проверь, что он соответствует фактическому набору документов.
Убедись, что требования Specs не продублированы в Context. Убедись, что требования Specs не продублированы в Context.
Для связанной задачи YouTrack после каждого рабочего сеанса запиши только
ещё не учтённое фактическое время через MCP, используя доступный тип работы.
Перед архивацией change проверь, что учтено всё время начиная с Explore.
Остановись, если столкнёшься с препятствием или потребуется уточнение. Остановись, если столкнёшься с препятствием или потребуется уточнение.
@@ -33,7 +33,3 @@
<!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно <!-- Оцени постоянный контекст проекта: укажи документы и ADR, которые нужно
создать или обновить. Если обновления не нужны, напиши это явно. создать или обновить. Если обновления не нужны, напиши это явно.
Не переноси сюда функциональные требования из OpenSpec Specs. --> Не переноси сюда функциональные требования из OpenSpec Specs. -->
## YouTrack
- Задача: `<PROJECT-123>` — <issue URL>
+118
View File
@@ -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: <application-label>/<change-id>`; для старых задач также 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.
В описании меняй только блок между `<!-- openspec-task:start -->`
и `<!-- openspec-task:end -->`, содержащий маркер 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: <id>`; `recorded` повторно не отправляй.
При ошибке MCP/локальной записи останови синхронизацию, сохрани связь,
незавершённые операции и `last_error`. Если archive уже выполнен, проверь
архивную связь, состояние задачи и Git status/log; продолжи только незавершённые
закрытие или коммит, не повторяя archive и уже выполненный коммит. Перед повтором
сверяй внешнее состояние.
Неопределённый результат создания запрещает автоматическое повторное создание
даже при пустом поиске; `sending` требует сверки work items или ручной проверки,
если MCP их не читает. Выполненный archive не откатывай.
Сообщи change, ID/URL задачи, результат и оставшееся действие.
+121
View File
@@ -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()