Схеми

Змінюйте те, що OpenSpec генерує: артефакти, їх порядок та шаблони.

Схема визначає, що генерує пропозиція зміни: які артефакти, в якому порядку та з яких шаблонів. Наприклад, spec-driven, замовлена вбудована схема, генерує ці четыре в приблизному такому порядку, кожна будуючи на попередньому:

proposal → specs → design → tasks

Форк схеми, коли ви хочете, щоб ці документи були різними, чи то менше їх, різні назви, чи інша структура.

Де живуть схеми

OpenSpec шукає схему в трьох місцях, послідовно, і використовує першу знайдену:

1. Ваш проект: openspec/schemas/, закомічене з репозиторію, щоб вся команда отримала його.

2. Ваш комп’ютер: ~/.local/share/openspec/schemas на macOS та Linux (або під $XDG_DATA_HOME, якщо ви його задали), або %LOCALAPPDATA%\openspec\schemas на Windows. Схеми тут доступні у кожному проекті, в якому ви працюєте.

3. Пакет: вбудовані схеми, такі як spec-driven, постачаються разом з openspec.

Те саме ім’я може існувати в кількох місцях, і більш специфічне місце переважає. openspec schema which показує, яка копія використовується:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Що таке схема

Схема визначається папкою з простими файлами: один файл schema.yaml, який оголошує артефакти, і шаблон для кожного з них.

Ось вбудований spec-driven:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: оголошує кожен артефакт, файл, який він генерує, шаблон, від якого він починається, що вимагає спочатку, і інструкцію, яку отримує агент під час створення. Умови кожного поля описані в schema.yaml.

• templates/: один markdown‑скелет для кожного артефакта, який агент заповнює.

Ось вхід для артефакту tasks у schema.yaml, зменшений:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Список перевірки реалізації з відстежуваними завданнями
    template: tasks.md
    instruction: |
      ...що сказано агенту під час створення tasks.md...
    requires:
      - specs
      - design

Вбудовані схеми постачаються разом з пакетом openspec, тому ви ніколи не редагуєте їх на місці. Ви отримуєте свою копію, фаркнувши.

Створення власної кастомної схеми

Існує два способи отримати власну схему:

1. Форк існуючої схеми і редагуйте свою копію. Починайте тут, коли існуюча схема близько до того, що ви хочете, бо все в ній вже працює.

2. Починати з нуля, коли жодна з них не підходить, Scaffolding пустого шаблону з openspec schema init.

Fork існуючої схеми

1. Forkуйте схему, яку хочете почати, виконуючи команду з корені вашого проекту:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Передайте другий аргумент для вибору назви (openspec schema fork spec-driven team-flow). Назви пишаться kebab-case.

2. Редагуйте копію: schema.yaml та шаблони. Редагування вашого форку описує, що саме змінити.

3. Валідуйте його:

   openspec schema validate spec-driven-custom

   Це є един команда, яка виявляє зламувану схему (пропущені шаблони, погана YAML, цикли залежностей) ще до того, як ви зайдете в середину зміни.

4. вкажіть ваш проект на нього в openspec/config.yaml. Цей крок виконайте сами, бо форк не змінює config.yaml:

   schema: spec-driven-custom

5. Нові пропозиції зміни тепер дотримуються вашої схеми. Зміни, створені раніше, залишаються з тієї схеми, з якої вони почалися.

Починати з нуля

openspec schema init Scaffolding нового шаблону замість копіювання:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

Scaffold представляє собою порожній шаблон. Артефакти берються лише з чотирьох ідів вбудованих, а сформовані шаблони не містять інструкцій, тому агент отримує менше підказок, доки ви не напишете їх сами. Після цього кроки форкування залишаються незмінними: валідуйте її, потім вкажіть config.yaml.

Редагування вашого форку

У форку є два типи файлів, які можна редагувати:

• templates/ змінює скелет кожного документа. Додайте розділ у шаблон задач, і кожен новий tasks.md починається з нього. Збережіть символ # на першій лінії: артефакт нащадок його, тому кожен сформований файл відкривається як документальний.

• schema.yaml змінює сам процес: які артефакти існують, що кожен вимагає спочатку, і інструкцію, яку отримує агент під час створення.

Наприклад, щоб зніщити документ дизайну для більш лагідного процесу:

1. Видаліть запис design у schema.yaml.

2. Видаліть design зі списку requires у tasks.

3. Валідуйте:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

   Пропустивши крок 2, validate виявить помилку:

   ✗ Schema 'spec-driven-custom' has errors:
     error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

   Валідуйте після кожної ручної редакції. Порожна схема інше виявляється в середині зміни, коли процес вимагає файл, якого немає. Як і config.yaml, правки схеми дораз доступу до агента на наступному запуску.

Форк – це копія

openspec update оновлює встановлені навички та команди, і ніколи не доторкається до openspec/schemas/. Ваш форк працює точно так, як ви його залишили, що означає, що він перестає отримувати покращення, коли вбудована схема змінюється. Щоб пізніше підхопити ці зміни, форкніть вбудовану схему з новим іменем і перенесіть різницю.

Спількування схеми

Спількування схеми означає копіювання її папки.

• За вашою командою: закомітьте openspec/schemas/ і всі члени репозиторію використовують його.

• На всіх ваших проектах: розмістіть папку в каталозі користувача з Де живуть схеми.

• З спільноти: спільнотачний каталог перелічує спільні схеми. Скопіюйте одну у openspec/schemas/<name> і вона працюватиме як ваша.

Ми працюємо над реєстром схеми, відкритим і приватним, щоб схеми можна було встановлювати за назвою, а не копіювати вручну.

Використовуйте OpenSpec з Суперсилами

Спостерігаємо superpowers-bridge, яка сполучає артефакти OpenSpec з навичками Superpowers. Перевірте ноти про встановлення та сумісність перед копіюванням його у ваш проект.

Містo випускається поза OpenSpec. OpenSpec не тестує та не версійнює свою інтеграцію з Superpowers. OpenSpec не тестує та не версійнює свою інтеграцію з Superpowers.