Сторы: Планирование в отдельном репозитории

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

Решаемая проблема

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

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

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

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

Структура

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

Два простых правила:

1. Хранилище — это обычный git-репозиторий. Вы сами делаете в него коммиты, отправляете, забираете изменения и ревьюируете их. 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 — с флагом --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

Используется корень OpenSpec: team-plans (/Users/you/openspec/team-plans)
...

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

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

openspec config set defaultStore team-plans

Теперь любая команда, запущенная за пределами корня планирования — и без флага --store и без проектной ссылки — будет использовать team-plans. Он находится в самом низу списка приоритетов, поэтому флаг --store, локальный корень и проектная ссылка store: все равно имеют приоритет. В заголовке корня и в JSON-блоке root указывается source: "global_default" с идентификатором хранилища, поэтому вы всегда можете отличить общесистемный стандартный вариант от ссылки в репозитории. Удалите его командой openspec config unset defaultStore. Если идентификатор не зарегистрирован, команды возвращают ошибку и предлагают зарегистрировать хранилище или удалить устаревший стандартный вариант.

Сценарий: требования, которые затрагивают несколько команд

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

   platform-reqs (хранилище)                 api-server (репозиторий кода)
   принадлежит платформенной команде        принадлежит продуктовой команде
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ читает   │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (собственные проекты)  │
   │   platform work          │          │ 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" }

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

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, содержащий весь набор — это единственная операция записи, которую выполняет эта команда.

Worksets: повторно откройте папки для совместной работы

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

  workset "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>.

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

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

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

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

Строка Using OpenSpec root: (и блок root в выводе с флагом --json) указывает, какой из перечисленных случаев у вас используется.

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

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

Где хранятся данные

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

<data dir> — это ~/.local/share/openspec в macOS и Linux (или $XDG_DATA_HOME/openspec, если переменная установлена), и %LOCALAPPDATA%\openspec в Windows.

Справочные материалы

Точные флаги и структуры JSON для всех команд на этой странице: Справочник по CLI (Хранилища, Doctor, Рабочий контекст, Персональные worksets) и контракт агента.