Хранилища: планирование в отдельном репозитории

Бета-версия. Хранилища, ссылки, рабочий контекст и рабочие наборы — новые функции. Названия команд, флаги, форматы файлов и вывод JSON могут меняться между выпусками. Все примеры ниже проверены на текущей сборке, но после обновления перечитайте это руководство.

Какую проблему решает эта функция

Обычно OpenSpec находится внутри одного репозитория с кодом: в каталоге openspec/ рядом с кодом хранятся спецификации и изменения этого репозитория.

Но такой подход перестаёт подходить, когда планирование выходит за рамки одного репозитория:

• Работа охватывает несколько репозиториев: одна функция затрагивает сервер API, веб-приложение и общую библиотеку. В каком из каталогов openspec/ хранить план?
• Команда планирует работу до появления кода или планирует задачи, которые никогда не станут кодом этого репозитория.
• Одна команда владеет требованиями, а другие команды их используют. Версия вики устаревает, а ИИ-агент для программирования всё равно не может её прочитать.

Решение — хранилище: отдельный репозиторий, предназначенный для планирования. В нём привычная структура openspec/ — спецификации и изменения — и небольшой файл идентификации. Достаточно один раз зарегистрировать хранилище на компьютере под именем, после чего с ним можно работать любой обычной командой OpenSpec откуда угодно.

Структура

            team-plans  (хранилище: планирование в отдельном репозитории)
            ├── .openspec-store/store.yaml     идентификация: «я — team-plans»
            └── openspec/
                ├── specs/      что уже верно
                └── changes/    что сейчас меняется
                      ▲
                      │ регистрируется на компьютерах по имени;
                      │ публикуется и клонируется, как любой репозиторий
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (репозиторий кода)   (репозиторий кода)    (репозиторий кода)

Два правила упрощают эту схему:

1. Хранилище — это обычный репозиторий git. Вы самостоятельно создаёте коммиты, выполняете push и pull и проверяете изменения. OpenSpec не клонирует, не синхронизирует и не отправляет изменения самостоятельно.
2. Объявления, а не механизмы. Репозитории могут объявлять связь с хранилищами (см. ниже). Объявления меняют доступную OpenSpec информацию, но не место выполнения команд.

Первое хранилище за пять минут

Две команды помогут создать хранилище и изменение в нём:

openspec store setup team-plans --path ~/openspec/team-plans

Хранилище готово: team-plans
Расположение: /Users/you/openspec/team-plans
Корень OpenSpec: готов
Реестр: зарегистрировано

Далее: выполняйте обычные команды OpenSpec для этого хранилища, например:
  openspec new change <change-id> --store team-plans
Чтобы поделиться этим хранилищем, создайте коммит и отправьте его, как в любом репозитории Git.

openspec new change add-login --store team-plans

Используется корень OpenSpec: team-plans (/Users/you/openspec/team-plans)
Создано изменение 'add-login' в /Users/you/openspec/team-plans/openspec/changes/add-login/
Схема: spec-driven
Далее: openspec status --change add-login --store team-plans

На этом модель заканчивается. Дальнейший жизненный цикл уже знаком — status, instructions, validate, archive — with --store team-plans добавляйте к каждой команде; все подсказки уже будут содержать этот флаг. Строка Using OpenSpec root: всегда показывает, где выполняется команда.

Сценарий: одна команда, один репозиторий планирования

Команда хранит спецификации и изменения в team-plans, а не распределяет их по репозиториям с кодом.

Первый день (для того, кто настраивает хранилище):

openspec store setup team-plans --path ~/openspec/team-plans \
  --remote git@github.com:acme/team-plans.git
git -C ~/openspec/team-plans push -u origin main

Передача --remote записывает URL для клонирования в файл идентификации хранилища (.openspec-store/store.yaml) в первом коммите. Каждый последующий клон сразу знает свой источник, поэтому проверки состояния и сообщения об ошибках могут предложить коллегам, у которых хранилище ещё не установлено, полную команду исправления, готовую к копированию.

Каждый участник команды (один раз на каждом компьютере):

git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans

После этого все работают с одним репозиторием планирования по имени:

openspec status --store team-plans --change add-login
openspec show add-login --store team-plans

Для обмена изменениями намеренно используется git. Созданное вами изменение существует только в вашей рабочей копии, пока вы не закоммитите и не отправите его, как и код. Планы получают ветки, пул-реквесты и проверку автоматически, поскольку хранилище — обычный репозиторий.

Связь с репозиториями команды, содержащими код. Если планирование полностью вынесено из репозитория с кодом, достаточно одной строки в openspec/config.yaml:

web-app/openspec/config.yaml

store: team-plans

Теперь любая команда OpenSpec, запущенная в web-app, будет работать с team-plans без дополнительных флагов:

cd ~/src/web-app
openspec status --change add-login

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
...

Указатель служит запасным вариантом, а не переопределением: явно указанный --store всегда имеет приоритет. Если в репозитории появятся собственные каталоги планирования, приоритет будет у них (с предупреждением об удалении устаревшего указателя).

Настройка по умолчанию для всех репозиториев компьютера. Если вы работаете с несколькими репозиториями с кодом, использующими одно хранилище, задайте его один раз глобально вместо добавления строки store: в каждый репозиторий:

openspec config set defaultStore team-plans

Теперь любая команда, запущенная вне корня планирования без --store и указателя проекта, будет использовать team-plans. Настройка имеет наименьший приоритет, поэтому явный --store, локальный корень и указатель store: в проекте имеют приоритет. Баннер корня и блок root в JSON указывают ``source: “global_default”и ID хранилища, поэтому глобальную настройку всегда можно отличить от указателя самого репозитория. Сбросьте её командойopenspec config unset defaultStore`. Если ID не зарегистрирован, команды выдадут ошибку и предложат зарегистрировать хранилище или удалить устаревшую настройку.

Пример: одна функция, два репозитория компонентов

Предположим, что add-checkout-promo меняет и checkout-api, и checkout-web. Команде нужен общий продуктовый контракт, но для каждого репозитория всё равно необходимы собственные задачи реализации, ветка и проверка.

Используйте два уровня:

1. Храните общее описание поведения в team-plans.
2. Храните планы реализации в каждом репозитории компонента и подключите хранилище как доступный только для чтения контекст.

Сначала спланируйте общий контракт в хранилище:

openspec new change add-checkout-promo --store team-plans
openspec status --change add-checkout-promo --store team-plans

Предложение и спецификации должны описывать поведение на границе компонентов — например, поля скидки, возвращаемые сервисом, и обработку неподходящего заказа в интерфейсе. Проверяйте это изменение в репозитории хранилища, как любую другую ветку и пул-реквест.

Какой контекст доступен при планировании?

Выбор хранилища меняет корень OpenSpec, но не позволяет автоматически обнаружить или прочитать все репозитории с кодом, использующие это хранилище. Инструкции хранилища учитывают его артефакты и настроенный контекст. Код компонентов будет доступен, только если соответствующие каталоги открыты в агенте или редакторе и агент прочитал их.

Рабочий набор позволяет удобно открыть хранилище планирования и оба репозитория с кодом одновременно:

openspec workset create checkout-promo \
  --member ~/openspec/team-plans \
  --member ~/src/checkout-api \
  --member ~/src/checkout-web \
  --tool code
openspec workset open checkout-promo

Так каталоги будут видны в одном рабочем пространстве IDE. При этом исходный контекст не копируется в хранилище, затронутые репозитории не выбираются, а агент не получает разрешение изменять их. Долговременную информацию о взаимодействии компонентов указывайте в общих спецификациях; не полагайтесь на то, что планировщик запомнит случайно изученный исходный материал.

Как запускать реализацию в каждом репозитории?

Если не задан --store и поблизости нет другого корня openspec/, указатель store: team-plans направляет команды в это хранилище. Он не разделяет список задач хранилища в зависимости от каталога, из которого вызван apply. Сейчас OpenSpec не распределяет задачи между репозиториями.

Если для каждого компонента требуется отдельный цикл реализации и проверки, создайте для него локальный корень OpenSpec и укажите ссылку на центральное хранилище вместо перенаправления команд в него:

# checkout-api/openspec/config.yaml (and likewise in checkout-web)
schema: spec-driven
references:
  - team-plans

После проверки общего контракта и его появления в основных спецификациях хранилища создайте небольшое локальное изменение для соответствующей части компонента:

cd ~/src/checkout-api
openspec new change implement-checkout-promo-api

cd ~/src/checkout-web
openspec new change implement-checkout-promo-ui

Индекс ссылок в инструкциях каждого репозитория содержит краткое описание спецификации хранилища и точную команду получения openspec show ... --store team-plans. В каждом локальном предложении указывается общий контракт, а задачи описывают только работу над соответствующим компонентом. Затем запустите /opsx:apply отдельно в каждом репозитории: разрешение корня ограничивает артефакты и изменения реализации этим репозиторием. Теперь изменения сервиса и интерфейса можно независимо тестировать, проверять, объединять и архивировать.

Если нужно начать реализацию до завершения общего изменения в хранилище, получите его явно командой openspec show add-checkout-promo --store team-plans. В индексах ссылок перечислены основные спецификации хранилища, а не активные изменения. Свяжите ветку хранилища и ветки компонентов в описаниях их пул-реквестов, чтобы проверяющие видели, какой версии контракта соответствует каждая реализация.

Сценарий: требования нескольких команд

Команда платформы владеет требованиями. Продуктовые команды реализуют их в собственных репозиториях и по собственным проектным решениям. Ссылка описывает эту связь, не перемещая работу команд.

   platform-reqs (хранилище)             api-server (репозиторий с кодом)
   принадлежит платформенной команде     принадлежит продуктовой команде
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ чтение   │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │             │   (собственные решения)  │
   │   работа платформы       │          │ openspec/changes/        │
   │                          │          │   (собственная работа)   │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

Продуктовая команда указывает используемое хранилище в файле openspec/config.yaml своего репозитория:

references:
  - platform-reqs

Ссылки предоставляют контекст только для чтения. Репозиторий сохраняет собственный корень openspec/, и работа остаётся там. Меняется следующее: команда openspec instructions в этом репозитории теперь содержит индекс спецификаций указанного хранилища, у каждой из которых есть краткое описание и точная команда получения (openspec show <spec-id> --type spec --store platform-reqs). Агент, работающий в api-server, может найти исходные требования к платежам, сослаться на них и создать детальное проектное решение в собственном корне репозитория — без необходимости вручную передавать контекст.

Ссылка может содержать источник для клонирования, чтобы коллеги, у которых хранилище ещё не установлено, получили готовую инструкцию, а не тупик:

references:
  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }

Чтобы открыть план и код вместе, создайте рабочий набор. Он персональный и настраивается явно: каждый выбирает каталоги, с которыми работает на своём компьютере. Локальные пути рабочей копии не попадают в общий репозиторий планирования.

openspec workset create platform \
  --member ~/openspec/platform-reqs \
  --member ~/src/api-server \
  --member ~/src/web-app

Два вопроса, на которые всегда можно получить ответ

«Настройка в порядке?» — openspec doctor проверяет текущий корень и связанные хранилища в режиме только для чтения и предлагает готовую команду исправления для каждого результата:

Диагностика

Корень
  Расположение: /Users/you/src/api-server
  Корень OpenSpec: в порядке

Ссылки
  - platform-reqs: в порядке (/Users/you/openspec/platform-reqs)
  - design-system: Связанное хранилище 'design-system' не зарегистрировано на этом компьютере.
    Исправление: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' && openspec store register '/Users/you/openspec/design-system' --id design-system

«С чем я работаю?» — openspec context собирает рабочий набор из объявлений OpenSpec: корень и связанные с ним хранилища.

Рабочий контекст для api-server (/Users/you/src/api-server)

Корень OpenSpec
  api-server  /Users/you/src/api-server

Связанные хранилища
  platform-reqs  /Users/you/openspec/platform-reqs
    Получение: openspec show <spec-id> --type spec --store platform-reqs

Обе команды поддерживают --json для агентов. Команда openspec context --code-workspace <path> дополнительно записывает файл рабочего пространства VS Code со всем набором — это единственная команда записи, которую она выполняет.

Рабочие наборы: повторное открытие каталогов, с которыми вы работаете вместе

Всё описанное выше решает отдельную задачу: обычно при каждом сеансе люди открывают вместе одни и те же каталоги — репозиторий планирования и ещё два-три репозитория с кодом. Рабочий набор — это персональное именованное представление такой группы каталогов, которое можно открыть одной командой в выбранном инструменте.

  рабочий набор "platform"           openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       все три открываются в инструменте

openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list

platform  (открывается в VS Code)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

Затем openspec workset open platform запускает сохранённый инструмент: редакторы (VS Code, Cursor) открывают одно окно со всеми каталогами и завершают работу. Первый участник — основной. В любой момент можно переопределить инструмент с помощью --tool <id>.

Рабочие наборы намеренно не являются общим состоянием. Они хранятся на вашем компьютере, никогда не коммитятся и не описывают работу — в них лишь указано, какие каталоги удобно открывать вместе. Удаление рабочего набора не затрагивает каталоги-участники. Поддержка новых инструментов настраивается, а не кодируется: любой инструмент, запускаемый через файл рабочего пространства или флаги подключения каталогов, можно добавить в ключ openers глобальной конфигурации (openspec config edit).

Как команды выбирают место выполнения

Любая обычная команда выбирает корень одинаково, в таком порядке:

1. --store <id>          указан явно                    → это хранилище
2. ближайший openspec/   здесь есть корень планирования → этот репозиторий
   (поднимаясь от cwd)
3. указатель store:      хранилище указано в config.yaml→ это хранилище
4. defaultStore          глобальная конфигурация задаёт → это хранилище
                         значение по умолчанию
5. ничего из указанного  есть зарегистрированные       → ошибка с подсказкой
                         хранилища?                       выбора
                         хранилища не зарегистрированы? → текущий каталог
                                                          (как раньше)

Строка Using OpenSpec root: (и блок root в выводе --json) показывает, какой вариант был выбран.

Известные ограничения

• Бета-версия. Любая информация на этой странице может измениться между выпусками: названия, флаги, форматы файлов и ключи JSON.
• Одна рабочая копия на ID хранилища на каждом компьютере. Попытка зарегистрировать вторую копию под тем же ID завершится подсказкой сначала выполнить store unregister.
• Синхронизации нет — так задумано. OpenSpec никогда не клонирует, не выполняет pull или push. В устаревшей рабочей копии отображаются устаревшие спецификации, пока вы не выполните pull; ссылки индексируются по текущему содержимому диска.
• Каталоги планирования могут отсутствовать. В Git нового хранилища может ещё не быть openspec/changes/, openspec/specs/ или openspec/changes/archive/. В бета-версии это допустимо; каталоги появятся, когда обычные команды создадут в них файлы.
• Репозитории-указатели остаются указателями. Репозиторий только с конфигурацией, где openspec/config.yaml объявляет store: <id>, считается репозиторием с вынесенным планированием, а не рабочей копией хранилища для регистрации. Если вы намеренно хотите превратить его в локальный корень хранилища, сначала удалите строку store:.
• Некоторые команды остаются привязанными к текущему каталогу. templates и устаревшие именные формы (openspec change show и т. п.) работают только в текущем каталоге и не поддерживают --store. schemas соблюдает общий порядок выбора корня и принимает --store <id>, сохраняя прежнюю форму успешного массива JSON.
• Состояние компьютера остаётся локальным. Реестр хранилищ и рабочие наборы — локальные настройки. Сведения о структуре компьютера не попадают в общий репозиторий планирования.
• Для рабочих наборов подходят не все способы запуска. Инструмент, который нельзя запустить с файлом рабочего пространства или флагами подключения отдельных каталогов, нельзя добавить в качестве средства открытия.
• В JSON агента известны различия в регистре ключей (ключи группы store используют snake_case, а рабочие процессы — camelCase). Это описано в контракте агента; унификация отложена до выпуска с версионированными изменениями.

Где что находится

Что	Где	Общее?
Планирование хранилища	<store>/openspec/ (спецификации, изменения)	Да — добавьте в коммит и отправьте
Идентификатор хранилища	<store>/.openspec-store/store.yaml	Да — входит в хранилище
Реестр хранилищ	<data dir>/openspec/stores/registry.yaml	Нет — только на этом компьютере
Рабочие наборы	<data dir>/openspec/worksets/	Нет — только на этом компьютере

<data dir> is ~/.local/share/openspec on macOS and Linux (or $XDG_DATA_HOME/openspec when set), and %LOCALAPPDATA%\openspec on Windows.

Справочник

Точные флаги и структуры JSON всех команд на этой странице приведены в справочнике CLI (хранилища, doctor, рабочий контекст, рабочие наборы) и контракте агента.