# Общие инструменты для OpenSpec и Codex Репозиторий содержит три переиспользуемых артефакта: | Артефакт | Назначение | Где находится | |---|---|---| | Схема 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) | Схема и скилл хранятся и развиваются здесь. Подключайте их символическими ссылками из пользовательских каталогов; обновление клона обновляет общий источник. Проектные `AGENTS.md` и `config.yaml` копируйте и адаптируйте: они содержат настройки конкретного приложения. ## 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). На macOS/Linux пользовательские схемы находятся в `${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas`, на Windows — в `%LOCALAPPDATA%\openspec\schemas`, либо под `XDG_DATA_HOME`, если он задан. ## 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 Замените `/path/to/openspec-schema` на абсолютный путь к своему клону: ```sh tooling_repo="/path/to/openspec-schema" schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas" 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 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' } $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') ``` Команды предполагают, что пути назначения ещё свободны. Если схема уже подключена, создайте только ссылку на скилл. Перед заменой существующей папки/ссылки проверьте её содержимое и источник. Проверьте схему из каталога прикладного проекта: ```sh openspec schema which use-case-driven openspec schema validate use-case-driven ``` Затем убедитесь, что `$task-tracker` появился среди доступных скиллов Codex. Ссылка на скилл не устанавливает MCP и не заполняет проектный `AGENTS.md`. Проектная схема `openspec/schemas/use-case-driven` имеет приоритет над пользовательской. Кроме того, схема ссылается на вспомогательные файлы относительно проекта (`validate_format.py`, `patterns/`). Для доступа к ним создайте в проекте ссылку `openspec/schemas/use-case-driven` на ту же общую схему либо адаптируйте пути инструкций. Пользовательская ссылка сама эти проектные пути не создаёт. ## Переход со старой интеграции В прикладных проектах перенесите ключ и метку из старого `context` в `AGENTS.md`, добавьте lifecycle из заготовки и подключите скилл. Удалите старые инструкции трекера из `config.yaml`, включая `operations.archive.guidance`; остальные контекст и правила сохраните. Если схема скопирована в проект вместо ссылки, обновите также её копию. Существующие ID/URL в proposal сохраняйте до проверенной привязки. Скилл умеет читать прежние ссылки и записывает `task-tracker.yaml` после проверки задачи. Архивным changes без однозначной связи новую задачу автоматически не создаёт. ## Проверки и ограничения ```sh openspec schema validate use-case-driven python3 -m unittest discover -s tests -v ``` Тесты `test_task_tracker_archive.py` используют установленный `openspec` CLI во временных каталогах и проверяют сохранение связи и журнала при успешном archive, отказе валидации и конфликте архива. Они не обращаются к трекеру; без CLI пропускаются. Frontmatter скилла можно отдельно проверить `scripts/quick_validate.py` из установленного `skill-creator`. Создание, повторная привязка, обновление, закрытие, ошибки MCP и отсутствие конфигурации описаны в скилле. Их внешнее выполнение требует доступного провайдера; инструктивный скилл не даёт программных гарантий исполнения. Для сквозной проверки используйте согласованный тестовый проект, не создавайте тестовые задачи в рабочем проекте без согласования. Схема продолжает развиваться: не все типы FR и форматы контрактов имеют подробные паттерны, например FR `[UI]`. Применимые требования безопасности, аудита и ролевой модели нужно явно учитывать при анализе изменения.