OPSX Workflow

Обратная связь приветствуется на Discord.

Что это такое?

OPSX теперь является стандартным рабочим процессом для OpenSpec.

Это гибкий, итеративный рабочий процесс для изменений в OpenSpec. Больше никаких жёстких фаз — только действия, которые можно выполнять в любой момент.

Зачем это существует

Устаревший workflow OpenSpec работает, но он закрыт:

• Инструкции захардкожены — встроены в TypeScript, их нельзя изменить
• Всё или ничего — одна большая команда создаёт всё, нельзя протестировать отдельные части
• Фиксированная структура — один и тот же workflow для всех, без кастомизации
• Чёрный ящик — когда вывод ИИ плохой, вы не можете подкрутить промпты

OPSX открывает это. Теперь любой может:

1. Экспериментировать с инструкциями — редактировать шаблон, смотреть, станет ли ИИ лучше
2. Тестировать гранулярно — валидировать инструкции каждого артефакта независимо
3. Кастомизировать workflow — определять свои артефакты и зависимости
4. Итеративно улучшать — изменить шаблон, протестировать сразу, без пересборки

Устаревший workflow:                      OPSX:
┌────────────────────────┐           ┌────────────────────────┐
│  Захардкожен в пакете  │           │  schema.yaml           │◄── Вы редактируете это
│  (нельзя изменить)     │           │  templates/*.md        │◄── Или это
│        ↓               │           │        ↓               │
│  Ждать нового релиза   │           │  Мгновенный эффект     │
│        ↓               │           │        ↓               │
│  Надеяться, что лучше  │           │  Тестируйте сами       │
└────────────────────────┘           └────────────────────────┘

Это для всех:

• Команды — создавайте workflow, которые соответствуют тому, как вы реально работаете
• Продвинутые пользователи — настраивайте промпты для лучшего вывода ИИ под вашу кодовую базу
• Контрибьюторы OpenSpec — экспериментируйте с новыми подходами без релизов

Мы все ещё учимся, что работает лучше всего. OPSX позволяет нам учиться вместе.

Пользовательский опыт

Проблема линейных workflow: Вы «в фазе планирования», затем «в фазе реализации», затем «готово». Но реальная работа не так устроена. Вы реализуете что-то, понимаете, что дизайн был неверным, нужно обновить спецификации, продолжить реализацию. Линейные фазы противоречат тому, как работа происходит на самом деле.

Подход OPSX:

• Действия, а не фазы — создать, реализовать, обновить, архивировать — делайте любое из них в любое время
• Зависимости — это возможности — они показывают, что возможно, а не что требуется следующим

  proposal ──→ specs ──→ design ──→ tasks ──→ implement

Установка

# Убедитесь, что у вас установлен openspec — навыки генерируются автоматически
openspec init

Это создаёт навыки в .claude/skills/ (или эквиваленте), которые ИИ-ассистенты по коду обнаруживают автоматически.

По умолчанию OpenSpec использует профиль workflow core (propose, explore, apply, sync, archive). Если вы хотите расширенные команды workflow (new, continue, ff, verify, bulk-archive, onboard), настройте их с помощью openspec config profile и примените с помощью openspec update.

Во время установки вам будет предложено создать конфигурацию проекта (openspec/config.yaml). Это необязательно, но рекомендуется.

Конфигурация проекта

Конфигурация проекта позволяет задавать значения по умолчанию и вводить специфичный для проекта контекст во все артефакты.

Создание конфигурации

Конфигурация создаётся во время openspec init или вручную:

# openspec/config.yaml
schema: spec-driven

context: |
  Технологический стек: TypeScript, React, Node.js
  API-конвенции: RESTful, JSON-ответы
  Тестирование: Vitest для юнит-тестов, Playwright для e2e
  Стиль: ESLint с Prettier, строгий TypeScript

rules:
  proposal:
    - Включать план отката
    - Определять затронутые команды
  specs:
    - Использовать формат Given/When/Then для сценариев
  design:
    - Включать диаграммы последовательностей для сложных потоков

Поля конфигурации

Поле	Тип	Описание
schema	string	Схема по умолчанию для новых изменений (например, spec-driven)
context	string	Контекст проекта, вводимый во все инструкции артефактов
rules	object	Правла для каждого артефакта, ключ — ID артефакта

Как это работает

Приоритет схем (от высшего к низшему):

1. Флаг CLI (--schema <name>)
2. Метаданные изменения (.openspec.yaml в каталоге изменения)
3. Конфигурация проекта (openspec/config.yaml)
4. По умолчанию (spec-driven)

Ввод контекста:

• Контекст добавляется в начало инструкций каждого артефакта
• Оборачивается в теги <context>...</context>
• Помогает ИИ понять конвенции вашего проекта

Ввод правил:

• Правила вводятся только для соответствующих артефактов
• Оборачиваются в теги <rules>...</rules>
• Появляются после контекста, перед шаблоном

ID артефактов по схемам

spec-driven (по умолчанию):

• proposal — Предложение об изменении
• specs — Спецификации
• design — Технический дизайн
• tasks — Задачи реализации

Валидация конфигурации

• Неизвестные ID артефактов в rules генерируют предупреждения
• Имена схем валидируются по доступным схемам
• Контекст имеет ограничение в 50 КБ
• Невалидный YAML сообщается с номерами строк

Устранение неполадок

"Неизвестный ID артефакта в правилах: X"

• Проверьте, что ID артефактов соответствуют вашей схеме (см. список выше)
• Запустите openspec schemas --json, чтобы увидеть ID артефактов для каждой схемы

Конфигурация не применяется:

• Убедитесь, что файл находится по пути openspec/config.yaml (не .yml)
• Проверьте синтаксис YAML с помощью валидатора
• Изменения конфигурации вступают в силу немедленно (перезапуск не требуется)

Контекст слишком большой:

• Контекст ограничен 50 КБ
• Суммируйте или ссылайтесь на внешние документы

Команды

Команда	Что делает
/opsx:propose	Создать изменение и сгенерировать артефакты планирования за один шаг (путь по умолчанию)
/opsx:explore	Продумать идеи, исследовать проблемы, уточнить требования
/opsx:new	Начать новый каркас изменения (расширенный workflow)
/opsx:continue	Создать следующий артефакт (расширенный workflow)
/opsx:ff	Быстрое создание артефактов планирования (расширенный workflow)
/opsx:apply	Реализовать задачи, обновляя артефакты по мере необходимости
/opsx:verify	Валидировать реализацию относительно артефактов (расширенный workflow)
/opsx:sync	Синхронизировать дельта-спецификации с основными (workflow по умолчанию, опционально)
/opsx:archive	Архивировать по завершении
/opsx:bulk-archive	Архивировать несколько завершённых изменений (расширенный workflow)
/opsx:onboard	Проводник по сквозному изменению (расширенный workflow)

Использование

Исследовать идею

/opsx:explore

Продумайте идеи, исследуйте проблемы, сравните варианты. Не требуется структура — просто партнёр для размышлений. Когда инсайты кристаллизуются, переходите к /opsx:propose (по умолчанию) или /opsx:new//opsx:ff (расширенный).

Начать новое изменение

/opsx:propose

Создаёт изменение и генерирует необходимые артефакты планирования перед реализацией.

Если вы включили расширенные workflow, вы можете вместо этого использовать:

/opsx:new        # только каркас
/opsx:continue   # создать один артефакт за раз
/opsx:ff         # создать все артефакты планирования сразу

Создать артефакты

/opsx:continue

Показывает, что готово к созданию на основе зависимостей, затем создаёт один артефакт. Используйте многократно для постепенного построения вашего изменения.

/opsx:ff add-dark-mode

Создаёт все артефакты планирования сразу. Используйте, когда у вас есть чёткое представление о том, что вы создаёте.

Реализовать (гибкая часть)

/opsx:apply

Работает над задачами, отмечая их по мере выполнения. Если вы управляете несколькими изменениями, вы можете запустить /opsx:apply <name>; в противном случае он должен вывести из контекста и предложить выбор, если не сможет определить.

Завершить

/opsx:archive   # Переместить в архив по завершении (предложит синхронизировать спецификации, если нужно)

Когда обновлять, а когда начинать заново

Вы всегда можете редактировать своё предложение или спецификации перед реализацией. Но когда уточнение становится «это другая работа»?

Что фиксирует предложение

Предложение определяет три вещи:

1. Намерение — Какую проблему вы решаете?
2. Объём — Что входит/не входит в границы?
3. Подход — Как вы будете это решать?

Вопрос в том: что изменилось и насколько?

Обновляйте существующее изменение, когда:

То же намерение, уточнённое исполнение

• Вы обнаруживаете граничные случаи, которые не рассматривали
• Подход нуждается в корректировке, но цель не изменилась
• Реализация показывает, что дизайн был слегка неточным

Объём сужается

• Вы понимаете, что полный объём слишком велик, хотите сначала выпустить MVP
• «Добавить тёмную тему» → «Добавить переключатель тёмной темы (системное предпочтение в v2)»

Корректировки на основе обучения

• Кодовая база структурирована не так, как вы думали
• Зависимость работает не так, как ожидалось
• «Использовать CSS-переменные» → «Использовать префикс dark: от Tailwind вместо этого»

Начинайте новое изменение, когда:

Намерение кардинально изменилось

• Сама проблема теперь другая
• «Добавить тёмную тему» → «Добавить комплексную систему тем с пользовательскими цветами, шрифтами, отступами»

Объём взорвался

• Изменение выросло настолько, что это по сути другая работа
• Исходное предложение после обновлений было бы неузнаваемым
• «Исправить баг входа» → «Переписать систему аутентификации»

Оригинал завершаем

• Исходное изменение можно пометить как «готово»
• Новая работа стоит отдельно, а не является уточнением
• Завершить «Добавить MVP тёмной темы» → Архивировать → Новое изменение «Улучшить тёмную тему»

Эвристики

                        ┌─────────────────────────────────────┐
                        │     Это та же работа?               │
                        └──────────────┬──────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
             То же намерение?  >50% перекрытия?   Оригинал может быть
             Та же проблема?   Тот же объём?      «готов» без этих
                    │                  │          изменений?
                    │                  │                  │
          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
          │                 │  │             │   │               │
         ДА               НЕТ ДА           НЕТ НЕТ             ДА
          │                 │  │             │   │               │
          ▼                 ▼  ▼             ▼   ▼               ▼
       ОБНОВИТЬ          НОВОЕ ОБНОВИТЬ    НОВОЕ ОБНОВИТЬ      НОВОЕ

Тест	Обновление	Новое изменение
Идентичность	«То же самое, уточнённое»	«Другая работа»
Перекрытие объёма	>50% перекрытий	<50% перекрытий
Завершение	Невозможно быть «готовым» без изменений	Можно завершить оригинал, новая работа стоит отдельно
История	Цепочка обновлений рассказывает связную историю	Платы запутают больше, чем прояснят

Принцип

Обновление сохраняет контекст. Новое изменение обеспечивает ясность.

Выбирайте обновление, когда история ваших размышлений ценна. Выбирайте новое, когда начинать с нуля было бы яснее, чем латать.

Думайте об этом как о ветках git:

• Продолжайте коммитить, пока работаете над одной фичей
• Начинайте новую ветку, когда это действительно новая работа
• Иногда мержьте частичную фичу и начинайте заново для фазы 2

В чём отличие?

	Устаревший (/openspec:proposal)	OPSX (/opsx:*)
Структура	Один большой документ предложения	Отдельные артефакты с зависимостями
Рабочий процесс	Линейные фазы: план → реализация → архив	Гибкие действия — выполняйте что угодно в любое время
Итерации	Неудобно возвращаться назад	Обновляйте артефакты по мере изучения
Настройка	Фиксированная структура	Управляемая схемой (определите свои артефакты)

Ключевой вывод: работа не является линейной. OPSX прекращает делать вид, что это не так.

Глубокое погружение в архитектуру

В этом разделе объясняется, как OPSX работает «под капотом» и как он соотносится с устаревшим рабочим процессом. Примеры в этом разделе используют расширенный набор команд (new, continue и т.д.); пользователи core по умолчанию могут отобразить тот же поток на propose → apply → sync → archive.

Философия: фазы vs действия

┌─────────────────────────────────────────────────────────────────────────────┐
│                         LEGACY WORKFLOW                                      │
│                    (Phase-Locked, All-or-Nothing)                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐             │
│   │   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │             │
│   │    PHASE     │      │    PHASE     │      │    PHASE     │             │
│   └──────────────┘      └──────────────┘      └──────────────┘             │
│         │                     │                     │                       │
│         ▼                     ▼                     ▼                       │
│   /openspec:proposal   /openspec:apply      /openspec:archive              │
│                                                                             │
│   • Creates ALL artifacts at once                                          │
│   • Can't go back to update specs during implementation                    │
│   • Phase gates enforce linear progression                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                            OPSX WORKFLOW                                     │
│                      (Fluid Actions, Iterative)                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│              ┌────────────────────────────────────────────┐                 │
│              │           ACTIONS (not phases)             │                 │
│              │                                            │                 │
│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
│              │    │          │           │           │    │                 │
│              │    └──────────┴───────────┴───────────┘    │                 │
│              │              any order                     │                 │
│              └────────────────────────────────────────────┘                 │
│                                                                             │
│   • Create artifacts one at a time OR fast-forward                         │
│   • Update specs/design/tasks during implementation                        │
│   • Dependencies enable progress, phases don't exist                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Архитектура компонентов

Устаревший рабочий процесс использует зашаблоненные шаблоны на TypeScript:

┌─────────────────────────────────────────────────────────────────────────────┐
│                      LEGACY WORKFLOW COMPONENTS                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Hardcoded Templates (TypeScript strings)                                  │
│                    │                                                        │
│                    ▼                                                        │
│   Tool-specific configurators/adapters                                      │
│                    │                                                        │
│                    ▼                                                        │
│   Generated Command Files (.claude/commands/openspec/*.md)                  │
│                                                                             │
│   • Fixed structure, no artifact awareness                                  │
│   • Change requires code modification + rebuild                             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

OPSX использует внешние схемы и графовый движок зависимостей:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         OPSX COMPONENTS                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Schema Definitions (YAML)                                                 │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  name: spec-driven                                                  │   │
│   │  artifacts:                                                         │   │
│   │    - id: proposal                                                   │   │
│   │      generates: proposal.md                                         │   │
│   │      requires: []              ◄── Dependencies                     │   │
│   │    - id: specs                                                      │   │
│   │      generates: specs/**/*.md  ◄── Glob patterns                    │   │
│   │      requires: [proposal]      ◄── Enables after proposal           │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   Artifact Graph Engine                                                     │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • Topological sort (dependency ordering)                           │   │
│   │  • State detection (filesystem existence)                           │   │
│   │  • Rich instruction generation (templates + context)                │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   Skill Files (.claude/skills/openspec-*/SKILL.md)                          │
│                                                                             │
│   • Cross-editor compatible (Claude Code, Cursor, Windsurf)                 │
│   • Skills query CLI for structured data                                    │
│   • Fully customizable via schema files                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Модель графа зависимостей

Артефакты образуют ориентированный ациклический граф (DAG). Зависимости являются активаторами, а не воротами:

                              proposal
                             (root node)
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
                    ▼                           ▼
                 specs                       design
              (requires:                  (requires:
               proposal)                   proposal)
                    │                           │
                    └─────────────┬─────────────┘
                                  │
                                  ▼
                               tasks
                           (requires:
                           specs, design)
                                  │
                                  ▼
                          ┌──────────────┐
                          │ APPLY PHASE  │
                          │ (requires:   │
                          │  tasks)      │
                          └──────────────┘

Переходы состояний:

   BLOCKED ────────────────► READY ────────────────► DONE
      │                        │                       │
   Missing                  All deps               File exists
   dependencies             are DONE               on filesystem

Поток информации

Устаревший рабочий процесс — агент получает статические инструкции:

  User: "/openspec:proposal"
           │
           ▼
  ┌─────────────────────────────────────────┐
  │  Static instructions:                   │
  │  • Create proposal.md                   │
  │  • Create tasks.md                      │
  │  • Create design.md                     │
  │  • Create specs/<capability>/spec.md    │
  │                                         │
  │  No awareness of what exists or         │
  │  dependencies between artifacts         │
  └─────────────────────────────────────────┘
           │
           ▼
  Agent creates ALL artifacts in one go

OPSX — агент запрашивает расширенный контекст:

  User: "/opsx:continue"
           │
           ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Step 1: Query current state                                             │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec status --change "add-auth" --json                      │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "artifacts": [                                                  │  │
  │  │      {"id": "proposal", "status": "done"},                         │  │
  │  │      {"id": "specs", "status": "ready"},      ◄── First ready      │  │
  │  │      {"id": "design", "status": "ready"},                          │  │
  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
  │  │    ]                                                               │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  Step 2: Get rich instructions for ready artifact                        │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec instructions specs --change "add-auth" --json          │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "template": "# Specification\n\n## ADDED Requirements...",      │  │
  │  │    "dependencies": [{"id": "proposal", "path": "...", "done": true}│  │
  │  │    "unlocks": ["tasks"]                                            │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  Step 3: Read dependencies → Create ONE artifact → Show what's unlocked  │
  └──────────────────────────────────────────────────────────────────────────┘

Модель итераций

Устаревший рабочий процесс — неудобно итерировать:

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │/proposal│ ──► │ /apply  │ ──► │/archive │
  └─────────┘     └─────────┘     └─────────┘
       │               │
       │               ├── "Wait, the design is wrong"
       │               │
       │               ├── Options:
       │               │   • Edit files manually (breaks context)
       │               │   • Abandon and start over
       │               │   • Push through and fix later
       │               │
       │               └── No official "go back" mechanism
       │
       └── Creates ALL artifacts at once

OPSX — естественная итерация:

  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
      │                │                  │
      │                │                  ├── "The design is wrong"
      │                │                  │
      │                │                  ▼
      │                │            Just edit design.md
      │                │            and continue!
      │                │                  │
      │                │                  ▼
      │                │         /opsx:apply picks up
      │                │         where you left off
      │                │
      │                └── Creates ONE artifact, shows what's unlocked
      │
      └── Scaffolds change, waits for direction

Пользовательские схемы

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

# Создание новой схемы с нуля (интерактивно)
openspec schema init my-workflow

# Или форк существующей схемы в качестве отправной точки
openspec schema fork spec-driven my-workflow

# Валидация структуры схемы
openspec schema validate my-workflow

# Просмотр источника разрешения схемы (полезно для отладки)
openspec schema which my-workflow

Схемы хранятся в openspec/schemas/ (локально для проекта, с контролем версий) или ~/.local/share/openspec/schemas/ (глобально для пользователя).

Структура схемы:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

Пример schema.yaml:

name: research-first
artifacts:
  - id: research        # Добавлен перед proposal
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]  # Теперь зависит от research

  - id: tasks
    generates: tasks.md
    requires: [proposal]

Граф зависимостей:

   research ──► proposal ──► tasks

Итоги

Аспект	Устаревший процесс	OPSX
Шаблоны	Захардкоженные на TypeScript	Внешние YAML + Markdown
Зависимости	Отсутствуют (всё сразу)	DAG с топологической сортировкой
Состояние	Модель на основе фаз	Наличие файловой системы
Настройка	Редактирование исходного кода, пересборка	Создание schema.yaml
Итерации	Привязка к фазам	Свободное редактирование чего угодно
Поддержка редакторов	Специфичные конфигураторы/адаптеры инструментов	Единая директория навыков

Схемы

Схемы определяют, какие артефакты существуют и их зависимости. В настоящее время доступны:

• spec-driven (по умолчанию): proposal → specs → design → tasks

# Вывести список доступных схем
openspec schemas

# Показать все схемы с источниками их разрешения
openspec schema which --all

# Создать новую схему интерактивно
openspec schema init my-workflow

# Ответвить существующую схему для настройки
openspec schema fork spec-driven my-workflow

# Проверить структуру схемы перед использованием
openspec schema validate my-workflow

Советы

• Используйте /opsx:explore, чтобы обдумать идею перед внесением изменений.
• /opsx:ff, когда вы знаете, чего хотите; /opsx:continue, когда исследуете.
• Во время /opsx:apply, если что-то не так — исправьте артефакт, затем продолжайте.
• Задачи отслеживают прогресс через чекбоксы в tasks.md.
• Проверяйте статус в любое время: openspec status --change "name"

Обратная связь

Это сыро. Это сделано намеренно — мы учимся, что работает.

Нашли ошибку? Есть идеи? Присоединяйтесь к нам в Discord или создайте issue на GitHub.