Робочий процес OPSX

Зворотний зв'язок вітається на Discord.

Що це таке?

OPSX наразі є стандартним робочим процесом для OpenSpec.

Це гнучкий, ітеративний робочий процес для змін OpenSpec. Більше ніяких жорстких фаз — лише дії, які ви можете виконувати будь-коли.

Навіщо це існує

Застарілий робочий процес OpenSpec працює, але він заблокований:

• Інструкції захардкоджені — заховані в TypeScript, ви не можете їх змінити
• Все або нічого — одна велика команда створює все, неможливо тестувати окремі частини
• Фіксована структура — однаковий робочий процес для всіх, без кастомізації
• Чорний ящик — коли вивід AI поганий, ви не можете підкрутити промпти

OPSX відкриває це. Тепер кожен може:

1. Експериментувати з інструкціями — редагуйте шаблон, перевірте чи AI працюватиме краще
2. Тестувати гранулярно — валідуйте інструкції кожного артефакту окремо
3. Кастомізувати робочі процеси — визначайте власні артефакти та залежності
4. Швидко ітерувати — змініть шаблон, протестуйте одразу, без перезбірки

Застарілий робочий процес:           OPSX:
┌────────────────────────┐           ┌────────────────────────┐
│  Захардкоджено в       │           │  schema.yaml           │◄── Ви редагуєте це
│  пакеті (не змінити)   │           │  templates/*.md        │◄── Або це
│        ↓               │           │        ↓               │
│  Чекати нового релізу  │           │  Миттєвий ефект        │
│        ↓               │           │        ↓               │
│  Сподіватись що краще  │           │  Тестуйте самі         │
└────────────────────────┘           └────────────────────────┘

Це для всіх:

• Команди — створюйте робочі процеси, що відповідають тому, як ви реально працюєте
• Просунуті користувачі — підкручуйте промпти для кращого виводу AI для вашої кодової бази
• Контриб'ютори OpenSpec — експериментуйте з новими підходами без релізів

Ми всі досі вчимося, що працює найкраще. OPSX дозволяє нам вчитися разом.

Користувацький досвід

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

Підхід OPSX:

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

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

Встановлення

# Переконайтеся що openspec встановлено — скіли генеруються автоматично
openspec init

Це створює скіли в .claude/skills/ (або еквіваленті), які AI-асистенти з кодування автоматично визначають.

За замовчуванням OpenSpec використовує профіль робочого процесу core (propose, explore, apply, sync, archive). Якщо ви хочете розширені команди робочого процесу (new, continue, ff, verify, bulk-archive, onboard), налаштуйте їх через openspec config profile та застосуйте через openspec update.

Під час встановлення вам буде запропоновано створити конфігурацію проєкту (openspec/config.yaml). Це необов'язково, але рекомендується.

Конфігурація проєкту

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

Створення конфігурації

Конфігурація створюється під час openspec init, або вручну:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

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

Поле	Тип	Опис
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>
• Допомагає AI зрозуміти конвенції вашого проєкту

Впровадження правил:

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

ID артефактів за схемою

spec-driven (за замовчуванням):

• proposal — Пропозиція зміни
• specs — Специфікації
• design — Технічний дизайн
• tasks — Завдання реалізації

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

• Невідомі ID артефактів у rules генерують попередження
• Назви схем валідуються проти доступних схем
• Контекст має обмеження розміру 50KB
• Невалідний YAML повідомляється з номерами рядків

Усунення проблем

"Unknown artifact ID in rules: X"

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

Конфігурація не застосовується:

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

Контекст занадто великий:

• Контекст обмежений 50KB
• Підсумуйте або посилайтесь на зовнішню документацію

Команди

Команда	Що робить
/opsx:propose	Створити зміну та згенерувати артефакти планування за один крок (шлях за замовчуванням)
/opsx:explore	Обміркувати ідеї, дослідити проблеми, уточнити вимоги
/opsx:new	Розпочати новий каркас зміни (розширений робочий процес)
/opsx:continue	Створити наступний артефакт (розширений робочий процес)
/opsx:ff	Швидке перемотування артефактів планування (розширений робочий процес)
/opsx:apply	Реалізувати завдання, оновлюючи артефакти за потреби
/opsx:verify	Валідувати реалізацію відносно артефактів (розширений робочий процес)
/opsx:sync	Синхронізувати дельта-специфікації до основної (робочий процес за замовчуванням, опціонально)
/opsx:archive	Архівувати коли завершено
/opsx:bulk-archive	Архівувати кілька завершених змін (розширений робочий процес)
/opsx:onboard	Керований огляд зміни від початку до кінця (розширений робочий процес)

Використання

Дослідити ідею

/opsx:explore

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

Розпочати нову зміну

/opsx:propose

Створює зміну та генерує артефакти планування, необхідні перед реалізацією.

Якщо ви увімкнули розширені робочі процеси, можете натомість використати:

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

Створити артефакти

/opsx:continue

Показує що готове до створення на основі залежностей, потім створює один артефакт. Використовуйте повторно для поступового нарощування вашої зміни.

/opsx:ff add-dark-mode

Створює всі артефакти планування одразу. Використовуйте коли у вас є чітке уявлення того, що ви будуєте.

Реалізація (гнучка частина)

/opsx:apply

Працює над завданнями, відмічаючи їх по ходу. Якщо ви жонглюєте кількома змінами, можете запустити /opsx:apply <name>; інакше він повинен вивести з контексту розмови та запропонувати вибір, якщо не зможе визначити.

Завершити

/opsx:archive   # Перемістити в архів коли завершено (запропонує синхронізувати специфікації за потреби)

Коли оновлювати vs. починати заново

Ви завжди можете редагувати пропозицію або специфікації перед реалізацією. Але коли вдосконалення стає "це інша робота"?

Що фіксує пропозиція

Пропозиція визначає три речі:

1. Намір — яку проблему ви вирішуєте?
2. Обсяг — що входить/не входить в межі?
3. Підхід — як ви будете це вирішувати?

Питання: що змінилося, і наскільки?

Оновлюйте існуючу зміну коли:

Той самий намір, вдосконалене виконання

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

Обсяг звужується

• Ви розумієте що повний обсяг занадто великий, хочете спочатку випустити MVP
• "Додати темний режим" → "Додати перемикач темного режиму (системні налаштування у v2)"

Виправлення на основі набутого досвіду

• Кодова база не структурована так, як ви думали
• Залежність працює не так, як очікувалось
• "Використати CSS-змінні" → "Натомість використати Tailwind dark: prefix"

Розпочинайте нову зміну коли:

Намір кардинально змінився

• Проблема тепер зовсім інша
• "Додати темний режим" → "Додати комплексну систему тем з користувацькими кольорами, шрифтами, відступами"

Обсяг вибухнув

• Зміна виросла настільки, що це фактично інша робота
• Оригінальна пропозиція була б невпізнанною після оновлень
• "Виправити баг логіну" → "Переписати систему автентифікації"

Оригінал можна завершити

• Оригінальну зміну можна позначити як "готово"
• Нова робота стоїть окремо, а не є вдосконаленням
• Завершити "Додати MVP темного режиму" → Архівувати → Нова зміна "Покращити темний режим"

Евристики

                        ┌─────────────────────────────────────┐
                        │     Це та сама робота?              │
                        └──────────────┬──────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
             Той самий намір?  >50% перекриття?   Чи можна оригінал
             Таж сама          Той самий обсяг?   позначити "готово"
             проблема?                             без цих змін?
                    │                  │                  │
          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
          │                 │  │             │   │               │
         ТАК              НІ ТАК           НІ  НІ              ТАК
          │                 │  │             │   │               │
          ▼                 ▼  ▼             ▼   ▼               ▼
       ОНОВИТИ          НОВА ОНОВИТИ      НОВА ОНОВИТИ         НОВА

Тест	Оновити	Нова зміна
Ідентичність	"Те саме, вдосконалене"	"Інша робота"
Перекриття обсягу	>50% перекривається	<50% перекривається
Завершення	Не можна позначити "готово" без змін	Можна завершити оригінал, нова робота стоїть окремо
Історія	Ланцюжок оновлень розповідає зв'язну історію	Латки заплутають більше, ніж прояснять

Принцип

Оновлення зберігає контекст. Нова зміна забезпечує ясність.

Обирайте оновлення, коли історія ваших роздумів цінна. Обирайте нову зміну, коли почати з нуля було б зрозуміліше, ніж латати.

Думайте про це як про гілки git:

• Продовжуйте комітити, працюючи над тим самим фічам
• Розпочинайте нову гілку, коли це справді нова робота
• Іноді злийте часткову фічу та починайте заново для фази 2

Що змінилося?

	Legacy (/openspec:proposal)	OPSX (/opsx:*)
Структура	Один великий документ пропозиції	Окремі артефакти з залежностями
Робочий процес	Лінійні фази: планування → реалізація → архівація	Гнучкі дії — можна робити що завгодно в будь-який час
Ітерація	Незручно повертатися назад	Оновлюйте артефакти, коли дізнаєтеся нове
Кастомізація	Фіксована структура	Керованою схемою (визначайте власні артефакти)

Ключова думка: робота не є лінійною. OPSX перестає робити вигляд, що це не так.

Глибоке занурення в архітектуру

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

Філософія: Фази проти Дій

┌─────────────────────────────────────────────────────────────────────────────┐
│                         ЗАСТАРІЛИЙ РОБОЧИЙ ПРОЦЕС                           │
│                    (Фазова фіксація, все або нічого)                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐             │
│   │   ПЛАНУВАННЯ │ ───► │  РЕАЛІЗАЦІЯ  │ ───► │  АРХІВАЦІЯ   │             │
│   │    ФАЗА      │      │    ФАЗА      │      │    ФАЗА      │             │
│   └──────────────┘      └──────────────┘      └──────────────┘             │
│         │                     │                     │                       │
│         ▼                     ▼                     ▼                       │
│   /openspec:proposal   /openspec:apply      /openspec:archive              │
│                                                                             │
│   • Створює ВСІ артефакти одночасно                                        │
│   • Неможливо повернутися для оновлення специфікацій під час реалізації    │
│   • Фазові бар'єри забезпечують лінійну послідовність                      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                            РОБОЧИЙ ПРОЦЕС OPSX                              │
│                      (Гнучкі дії, ітеративний)                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│              ┌────────────────────────────────────────────┐                 │
│              │           ДІЇ (не фази)                    │                 │
│              │                                            │                 │
│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
│              │    │          │           │           │    │                 │
│              │    └──────────┴───────────┴───────────┘    │                 │
│              │              будь-який порядок              │                 │
│              └────────────────────────────────────────────┘                 │
│                                                                             │
│   • Створюйте артефакти по одному АБО пропускайте вперед                    │
│   • Оновлюйте специфікації/дизайн/завдання під час реалізації              │
│   • Залежності забезпечують прогрес, фази не існують                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

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

Застарілий робочий процес використовує зашаблоновані шаблони на TypeScript:

┌─────────────────────────────────────────────────────────────────────────────┐
│                      КОМПОНЕНТИ ЗАСТАРІЛОГО РОБОЧОГО ПРОЦЕСУ                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Зашаблоновані шаблони (рядки TypeScript)                                  │
│                    │                                                        │
│                    ▼                                                        │
│   Конфігуратори/адаптери для конкретних інструментів                       │
│                    │                                                        │
│                    ▼                                                        │
│   Згенеровані файли команд (.claude/commands/openspec/*.md)                 │
│                                                                             │
│   • Фіксована структура, без обізнаності про артефакти                     │
│   • Зміни потребують модифікації коду + перебудови                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

OPSX використовує зовнішні схеми та графовий рушій залежностей:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         КОМПОНЕНТИ OPSX                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Визначення схем (YAML)                                                    │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  name: spec-driven                                                  │   │
│   │  artifacts:                                                         │   │
│   │    - id: proposal                                                   │   │
│   │      generates: proposal.md                                         │   │
│   │      requires: []              ◄── Залежності                       │   │
│   │    - id: specs                                                      │   │
│   │      generates: specs/**/*.md  ◄── Glob-патерни                     │   │
│   │      requires: [proposal]      ◄── Активується після proposal       │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   Рушій графа артефактів                                                    │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • Топологічне сортування (упорядкування за залежностями)          │   │
│   │  • Виявлення стану (наявність у файловій системі)                   │   │
│   │  • Генерація детальних інструкцій (шаблони + контекст)              │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   Файли навичок (.claude/skills/openspec-*/SKILL.md)                        │
│                                                                             │
│   • Сумісність між редакторами (Claude Code, Cursor, Windsurf)              │
│   • Навички запитують CLI для структурованих даних                          │
│   • Повна кастомізація через файли схем                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Модель графа залежностей

Артефакти утворюють спрямований ациклічний граф (DAG). Залежності є активаторами, а не бар'єрами:

                              proposal
                            (кореневий вузол)
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
                    ▼                           ▼
                 specs                       design
              (requires:                  (requires:
               proposal)                   proposal)
                    │                           │
                    └─────────────┬─────────────┘
                                  │
                                  ▼
                               tasks
                           (requires:
                           specs, design)
                                  │
                                  ▼
                          ┌──────────────┐
                          │  ФАЗА APPLY  │
                          │ (requires:   │
                          │  tasks)      │
                          └──────────────┘

Переходи станів:

   BLOCKED ────────────────► READY ────────────────► DONE
      │                        │                       │
   Відсутні                 Всі залежності         Файл існує
   залежності               мають стан DONE        у файловій системі

Потік інформації

Застарілий робочий процес — агент отримує статичні інструкції:

  Користувач: "/openspec:proposal"
           │
           ▼
  ┌─────────────────────────────────────────┐
  │  Статичні інструкції:                   │
  │  • Створити proposal.md                 │
  │  • Створити tasks.md                    │
  │  • Створити design.md                   │
  │  • Створити specs/<capability>/spec.md  │
  │                                         │
  │  Немає обізнаності про те, що вже       │
  │  існує, або про залежності між          │
  │  артефактами                            │
  └─────────────────────────────────────────┘
           │
           ▼
  Агент створює ВСІ артефакти за один раз

OPSX — агент запитує детальний контекст:

  Користувач: "/opsx:continue"
           │
           ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Крок 1: Запит поточного стану                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec status --change "add-auth" --json                      │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "artifacts": [                                                  │  │
  │  │      {"id": "proposal", "status": "done"},                         │  │
  │  │      {"id": "specs", "status": "ready"},      ◄── Перший готовий   │  │
  │  │      {"id": "design", "status": "ready"},                          │  │
  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
  │  │    ]                                                               │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  Крок 2: Отримати детальні інструкції для готового артефакту             │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec instructions specs --change "add-auth" --json          │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "template": "# Specification\n\n## ADDED Requirements...",      │  │
  │  │    "dependencies": [{"id": "proposal", "path": "...", "done": true}│  │
  │  │    "unlocks": ["tasks"]                                            │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  Крок 3: Прочитати залежності → Створити ОДИН артефакт → Показати,      │
  │          що розблоковано                                                 │
  └──────────────────────────────────────────────────────────────────────────┘

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

Застарілий робочий процес — незручно ітерувати:

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │/proposal│ ──► │ /apply  │ ──► │/archive │
  └─────────┘     └─────────┘     └─────────┘
       │               │
       │               ├── "Зачекайте, дизайн неправильний"
       │               │
       │               ├── Варіанти:
       │               │   • Редагувати файли вручну (порушує контекст)
       │               │   • Скасувати і почати з нуля
       │               │   • Продовжити і виправити пізніше
       │               │
       │               └── Немає офіційного механізму «повернутися назад»
       │
       └── Створює ВСІ артефакти за один раз

OPSX — природна ітерація:

  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
      │                │                  │
      │                │                  ├── "Дизайн неправильний"
      │                │                  │
      │                │                  ▼
      │                │            Просто відредагуйте design.md
      │                │            і продовжуйте!
      │                │                  │
      │                │                  ▼
      │                │         /opsx:apply підхоплює
      │                │         з того місця, де ви зупинилися
      │                │
      │                └── Створює ОДИН артефакт, показує, що розблоковано
      │
      └── Створює каркас зміни, чекає на вказівки

Кастомні схеми

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

# Створити нову схему з нуля (інтерактивно)
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.