Схемы

Измените то, что создаёт 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: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...что говорится агенту при создании tasks.md...
    requires:
      - specs
      - design

Встроенные схемы поставляются внутри пакета openspec, поэтому вы никогда не редактируете их на месте. Вы получаете собственную копию через форк.

Создание собственной схемы

Есть два способа получить собственную схему:

1. Создать форк существующей схемы и отредактировать копию. Начните с этого, если существующая схема близка к тому, что вам нужно, поскольку всё в ней уже работает.
2. Начать с нуля, если ни одна не подходит, создав пустую схему через openspec schema init.

Создание форка существующей схемы

1. Создайте форк схемы, с которой хотите начать, запустив команду из корня проекта:

   $ 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. Новые предложения об изменении теперь следуют вашей схеме. Ранее созданные изменения сохраняют схему, с которой начали.

Чтобы заменить схему по умолчанию везде, не трогая config.yaml, создайте форк с тем же именем: openspec schema fork spec-driven spec-driven. Копия вашего проекта затем перекроет встроенную, как объясняется в разделе Где находятся схемы.

Начало с нуля

openspec schema init создаёт новую схему, а не копирует существующую:

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

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

Скелет минимален. Артефакты берутся только из четырёх встроенных id, а сгенерированные шаблоны не содержат инструкций, поэтому агент получает меньше руководства, пока вы не напишете своё. Далее применяются те же шаги, что и для форка: проверьте схему, затем укажите на неё в config.yaml.

Редактирование вашего форка

Форк содержит два типа файлов для редактирования:

• templates/ меняют скелет каждого документа. Добавьте раздел в шаблон tasks, и каждый новый tasks.md начнётся с него. Сохраняйте заголовок # в первой строке: артефакт наследует его, поэтому каждый сгенерированный файл открывается как документ с заголовком.
• schema.yaml меняет сам рабочий процесс: какие артефакты существуют, что требуется перед каждым из них и инструкцию, которую агент получает при его создании.

Например, чтобы убрать документ design для более простого процесса:

1. Удалите запись design из schema.yaml.

2. Удалите design из списка requires у tasks.

3. Проверьте:

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

   Пропустите шаг 2, и проверка обнаружит ошибку:

✗ 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

Поддерживаемая сообществом схема superpowers-bridge связывает артефакты OpenSpec с навыками выполнения Superpowers. Следуйте инструкциям по установке и совместимости перед копированием её в ваш проект.

Мост выпускается вне OpenSpec. OpenSpec не тестирует и не версионирует его интеграцию с Superpowers.