Stores: Планування у власному репозиторії

Бета. Stores, посилання, робочий контекст та worksets є новими. Назви команд, прапорці, формати файлів та JSON-вивід можуть ще змінюватися між релізами. Кожне покрокове керівництво нижче було протестовано на поточній збірці, але перечитайте цей посібник після оновлення.

Проблема, яку це вирішує

Зазвичай OpenSpec розміщується всередині одного репозиторію коду: папка openspec/ поруч з вашим кодом, що містить специфікації та зміни для цього репозиторію.

Це перестає підходити, щойно ваше планування виходить за межі одного репозиторію:

• Ваша робота охоплює кілька репозиторіїв — одна функція зачіпає API-сервер, веб-застосунок та спільної бібліотеки. У якій папці openspec/ має зберігатися план?
• Ваша команда планує роботу до появи коду, або планує речі, які ніколи не стануть кодом у цьому репозиторії.
• Вимоги належать одній команді та використовуються іншими. Версія у вікі відходить від актуальної, а ваш coding agent все одно не може її прочитати.

Сховище — це відповідь: окремий репозиторій, єдина мета якого — планування. Він має ту саму структуру папки openspec/, що ви вже знаєте — специфікації та зміни — а також невеликий файл ідентифікації. Ви реєструєте його на своєму комп'ютері один раз за ім'ям, а потім будь-яка стандартна команда OpenSpec може працювати з ним з будь-якого місця.

Схема

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

Два прості правила, які зберігають всю систему простою:

1. Сховище — це просто git-репозиторій. Ви самостійно робите коміти, push, pull та рев'ю його. OpenSpec ніколи не клонує, не синхронізує та не робить push нічого самостійно.
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
Спільно використовуйте це сховище, роблячи коміти та push, як у будь-якого 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 навмисно. Зміна, яку ви створюєте, існує лише у вашому локальному репозиторії, поки ви не зробите коміт та push — так само, як і код. Плани автоматично отримують гілки, pull-запити та рев'ю, оскільки сховище є звичайним репозиторієм.

Підключення репозиторіїв коду команди. Репозиторій коду, планування якого повністю винесено в окреме сховище, потребує рівно одного рядка у 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/        │          │   (їх власні дизайни)    │
   │   платформна робота       │          │ 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, що містить весь набір — це єдиний запис, який виконує ця команда.

Робочі набори: повторно відкрийте папки, з якими ви працюєте разом

Окремо від всього вище: більшість людей відкриває одні й ті ж кілька папок разом під час кожної сесії — репозиторій планування плюс два-три репозиторії коду. Робочий набір (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>.

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

Як команди визначають місце виконання

Кожна звичайна команда визначає свій корінь за однаковим порядком:

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

Рядок Using OpenSpec root: (та блок root у виводі з --json) повідомляє, який з випадків у вас застосовується.

Відомі обмеження

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

Де що знаходиться

Що	Де	Спільний доступ?
Планування сховища	<store>/openspec/ (специфікації, зміни)	Так — зробіть коміт і відправте його
Ідентифікація сховища	<store>/.openspec-store/store.yaml	Так — додається до коміту разом із сховищем
Реєстр сховищ	<data dir>/openspec/stores/registry.yaml	Ні — лише для цієї машини
Робочі набори	<data dir>/openspec/worksets/	Ні — лише для цієї машини

<data dir> — це ~/.local/share/openspec на macOS і Linux (або $XDG_DATA_HOME/openspec, якщо встановлено), та %LOCALAPPDATA%\openspec на Windows.

Довідка

Точні прапорці та JSON-структури для кожної команди на цій сторінці: Довідка CLI (Сховища, Doctor, Робочий контекст, Особисті робочі набори) та контракт агента.