spec-driven

Артефакти робочого процесу за замовчуванням: їхній порядок, формати та папка змін, яку вони створюють.

spec-driven — вбудована схема OpenSpec за замовчуванням. schema.yaml визначає поля, які вона задає.

Артефакти

Робочий процес формує чотири артефакти:

Артефакт	Файл	Призначення
proposal	proposal.md	Чому потрібна зміна
specs	specs/<capability-path>/spec.md, по одному на кожну можливість	Яка поведінка змінюється
design	design.md	Як це побудувати
tasks	tasks.md	Контрольний список реалізації

Порядок складання

             ┌─ specs ──┐
proposal ────┤          ├── tasks ── apply
             └─ design ─┘

Спочатку йде proposal. Specs і design слідують у будь-якому порядку, а tasks потребує обох. Реалізація (apply) починається, коли tasks.md на місці.

Два артефакти можна пропустити:

• design: коли жодна з його умов не застосовується, агент його пропускає і все одно складає tasks.
• specs: встановіть skip_specs: true у файлі .openspec.yaml зміни.

Приклад папки зміни

Зміна з назвою add-user-auth з усіма складеними артефактами:

openspec/changes/add-user-auth/
├── .openspec.yaml      метадані зміни, записуються під час створення зміни
├── proposal.md
├── specs/
│   └── user-auth/
│       └── spec.md     один delta spec на кожну можливість
├── design.md
└── tasks.md

proposal.md

Визначає, чому потрібна ця зміна.

Структура

Шаблон, який агент отримує як формат виводу (templates/proposal.md):

# Proposal

## Why

<!-- Explain the motivation for this change. What problem does this solve? Why now? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->

## Capabilities

### New Capabilities
<!-- Capabilities being introduced. Name each capability for a cohesive system
     behavior that can own related requirements as the system evolves. Do not name
     implementation tasks or proposal sections. Avoid broad catch-all names. Use
     kebab-case for path segments you introduce (e.g., user-auth or identity/user-auth)
     that follow the project's existing spec organization. Each creates
     specs/<capability-path>/spec.md. -->
- `<capability-path>`: <brief description of what this capability covers>

### Modified Capabilities
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
     Only list here if spec-level behavior changes. Each needs a delta spec file.
     Use the exact existing path under openspec/specs/. Leave empty if no requirement
     changes. A change with no capabilities at all (pure refactor, tooling, docs)
     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
     a zero-delta change without that marker. Do not invent a requirement just to
     satisfy validation. -->
- `<existing-capability-path>`: <what requirement is changing>

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Інструкції

Інструкція, що надсилається агенту під час складання цього артефакту (з schema.yaml):

Створіть документ proposal, який визначає, ЧОМУ потрібна ця зміна.

Секції:
- **Why**: 1-2 речення про проблему або можливість. Яку проблему це вирішує? Чому саме зараз?
- **What Changes**: Маркований список змін. Будьте конкретні щодо нових можливостей, модифікацій або видалень. Позначайте ламані зміни як **BREAKING**.
- **Capabilities**: Визначте, які specs будуть створені або змінені:
  - **New Capabilities**: Перелічіть можливості, що вводяться. Кожна стає новим `specs/<capability-path>/spec.md`. Називайте кожну можливість за стійку системну поведінку (наприклад, `user-auth`), а не за роботою в цій зміні (наприклад, `add-login-endpoint`). Обирайте цілісний кордон, який може володіти пов'язаними вимогами в майбутньому; уникайте широких узагальнених можливостей. Використовуйте kebab-case для сегментів шляху, які ви вводите (наприклад, `user-auth` або `identity/user-auth`), і дотримуйтесь існуючої організації spec проєкту.
  - **Modified Capabilities**: Перелічіть існуючі можливості, чиї ВИМОГИ змінюються. Включайте тільки якщо змінюється поведінка на рівні spec (а не лише деталі реалізації). Кожна потребує окремого файлу delta spec. Використовуйте точний існуючий шлях у `openspec/specs/`. Залиште порожнім, якщо вимоги не змінюються.
- **Impact**: Задіяний код, API, залежності або системи.

IMPORTANT: Секція Capabilities є критичною. Вона створює контракт між
proposal і specs фазами. Дослідіть існуючі specs перед заповненням:
виконайте `openspec list --specs` для інвентаризації можливостей проєкту, потім
`openspec show "<spec-id>" --type spec --json --no-scenarios` для тих,
що виглядають пов'язаними — це повертає призначення та тексти вимог можливості
без завантаження цілих файлів spec у контекст. Додайте `--store "<id>"` до
обох команд лише для зареєстрованого окремого сховища, і зберігайте `--type
spec`: зміна і spec з однаковим іменем інакше викликають помилку неоднозначного елемента.
`openspec list` без `--specs` показує поточні зміни, а не
specs — він ніколи не показує, що проєкт уже охоплює. Використовуйте точний шлях
існуючої можливості замість введення майже дубльованої назви.
Відфільтроване читання — лише огляд. Перш ніж вирішувати, що вже
охоплено або що має змінитися, прочитайте кожен відповідний spec повністю, включаючи
сценарії, за допомогою `openspec show "<spec-id>" --type spec` (те саме правило `--store`).
Кожна можливість, перелічена тут, потребуватиме відповідного файлу spec.

Кожна зміна має або оголошувати принаймні одну можливість (нову або
змінену), або явно відмовитися від specs: `openspec validate` відхиляє
зміну з нульовими deltas, якщо тільки `.openspec.yaml` зміни не встановлює
`skip_specs: true`. Використовуйте `skip_specs: true` тільки коли немає змін поведінки
на рівні spec (чистий рефакторинг, інструменти, документація) — specs описують
поведінку, тому якщо поведінка не змінюється, жоден spec не має змінюватися.
Не вигадуйте вимогу лише для проходження валідації.

Зберігайте стислість (1-2 сторінки). Сосредоточьтеся на "чому", а не на "як" —
деталі реалізації належать до design.md.

Це фундамент — specs, design і tasks будуються на цьому.

Delta specs (spec.md)

Визначає, яка поведінка змінюється, з одним delta spec на кожну можливість, перелічену в proposal.

Кожен delta spec — це spec.md у папці своєї можливості. openspec validate і openspec archive відхиляють секції delta, написані в будь-якому іншому файлі в specs/, наприклад specs/user-auth.md, оскільки archive ніколи їх не об'єднує.

Структура

Шаблон, який агент отримує як формат виводу (templates/spec.md):

# Spec Delta

## Purpose
<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->

## ADDED Requirements

### Requirement: <!-- requirement name -->
<!-- requirement text -->

#### Scenario: <!-- scenario name -->
- **WHEN** <!-- condition -->
- **THEN** <!-- expected outcome -->

Інструкції

Інструкція, що надсилається агенту під час складання цього артефакту (з schema.yaml):

Створіть файли специфікацій, які визначають, ЩО має робити система.

Spec — це контракт поведінки, а не план реалізації.

Хороший вміст spec:
- Спостережувана поведінка, на яку покладаються користувачі або низхідні системи
- Вхідні дані, вихідні дані та умови помилок
- Зовнішні обмеження (безпека, конфіденційність, надійність, сумісність)
- Сценарії, які можна протестувати або явно перевірити

Уникайте в specs:
- Внутрішні назви класів/функцій
- Вибір бібліотек або фреймворків
- Покрокові деталі реалізації
- Детальні плани виконання (вони належать до design.md або tasks.md)

Швидкий тест: якщо реалізація може змінитися без зміни зовнішньо видимої поведінки, ймовірно, це не належить до spec.

Створюйте один файл spec на кожну можливість, перелічену в секції Capabilities proposal.
`<capability-path>` — це директорія spec відносно `specs/` (наприклад,
`user-auth` або `identity/user-auth`). Зберігайте повний шлях:
- Нові можливості: використовуйте точний шлях з proposal за адресою `specs/<capability-path>/spec.md`. Будь-який сегмент шляху, 新ведений у proposal, має бути в kebab-case. Дотримуйтесь існуючої організації проєкту; не додавайте новий рівень домену, коли проєкт використовує плаский макет.
- Змінені можливості: використовуйте точний існуючий шлях з `openspec/specs/<capability-path>/` під час створення delta за адресою `specs/<capability-path>/spec.md`. Виконайте `openspec list --specs`, щоб підтвердити цей шлях перед написанням delta, додаючи `--store "<id>"` лише для зареєстрованого окремого сховища — помилково написаний або вигаданий шлях вказує на можливість, якої не існує, замість тієї, яку ви мали на увазі. Не переміщуйте та не перейменовуйте можливість.

Пишіть файли spec по одному, щоб користувач бачив прогрес, а перерваний запуск зберіг уже написані файли:
- Перш ніж писати щось, порівняйте можливості, перелічені в proposal, з файлами `specs/<capability-path>/spec.md`, які вже існують, і почніть з першої можливості, яка не має файлу. Не переписуйте існуючий файл, якщо користувач не просить вас про це.
- Перед кожним файлом скажіть одним рядком, яку можливість ви пишете.
- Пишіть кожен файл одразу після його складання. Не плануйте всі файли перед написанням першого.
- Зупиніться, коли кожна можливість, перелічена в proposal, матиме свій файл.

Має бути принаймні один файл spec, якщо тільки `.openspec.yaml` зміни не встановлює `skip_specs: true` (немає змін поведінки на рівні spec) — `openspec validate` відхиляє зміну з нульовими deltas без цього маркера. Якщо proposal не перелічує жодної можливості і `skip_specs` не встановлено, спочатку перегляньте proposal.

Операції delta (використовуйте заголовки ##):
- **ADDED Requirements**: Нові можливості
- **MODIFIED Requirements**: Змінена поведінка — МАЄ включати повний оновлений вміст
- **REMOVED Requirements**: Застарілі функції — МАЄ включати **Reason** і **Migration**
- **RENAMED Requirements**: Лише зміни назв — використовуйте формат FROM:/TO:

Вимоги до формату:
- Кожна вимога: `### Requirement: <name>`, за якою йде опис
- Використовуйте SHALL/MUST для нормативних вимог (уникайте should/may)
- Кожен сценарій: `#### Scenario: <name>` у форматі WHEN/THEN
- **КРИТИЧНО**: Сценарії МАЮТЬ використовувати рівно 4 хеш-теги (`####`). Використання 3 хеш-тегів або маркерів призведе до тихого збою.
- Кожна вимога МАЄ мати принаймні один сценарій.
- Кожен сценарій МАЄ мати крок WHEN/GIVEN (його тригер) і крок THEN (його результат). Сценарій, що містить лише рядки AND або звичайну прозу, все одно вважається сценарієм, але `openspec validate` позначає його як попередження: звичайна валідація все одно проходить, але `openspec validate --strict` завершується з помилкою.
- Зберігайте опис кожної вимоги (текст між `### Requirement:` і її першим сценарієм) обсягом не більше 500 символів. `openspec validate` позначає довші описи в ADDED requirements і в основному spec. Це попередження: звичайна валідація все одно проходить, але `openspec validate --strict` завершується з помилкою. Створюючи нову вимогу, формулюйте одну поведінку на вимогу: переносіть приклади та крайні випадки в сценарії, а вимогу, що охоплює кілька поведінок, розділіть на окремі блоки `### Requirement:`, кожен зі своїми сценаріями. У розділі MODIFIED зберігайте існуючий блок вимоги цілком; ніколи не розділяйте, не обрізайте та не переписуйте існуючий текст лише для відповідності довжині. Розділяйте існуючу довгу вимогу тільки коли користувач просить про це, у зміні, зробленій з цією метою: у розділі MODIFIED збережіть її заголовок і кожен сценарій, скоротивши опис до однієї поведінки без зміни сенсу, а потім додайте кожну видалену поведінку як окрему ADDED вимогу з власними сценаріями.

Тільки для нових можливостей: перша секція delta spec — `## Purpose` — одне або два речення (50+ символів, або `openspec validate --strict` повідомляє, що воно занадто коротке), що описує, для чого потрібна ця можливість. Archive копіює його в основний spec, який він створює; без нього новий основний spec залишиться з заповнювачем `TBD ... Update Purpose after archive` для ручного заповнення. НЕ додавайте `## Purpose` до delta для існуючої можливості — цей spec уже має його, а delta ігнорується. Щоб змінити Purpose існуючої можливості — включаючи залишений заповнювач `TBD` — відредагуйте `<planningHome.root>/openspec/specs/<capability-path>/spec.md` напряму. `planningHome.root` надходить з відповіді `openspec instructions ... --json`. Завжди використовуйте його замість шляху відносно репозиторію: він вказує на сховище, коли зміна знаходиться в ньому — незалежно від того, чи це від `--store`, проєктного вказівника `store:`, чи глобального сховища за замовчуванням — і на поточний репозиторій в іншому випадку. Не намагайтеся з'ясувати, який випадок застосовується; поле вже це має.

Робочий процес MODIFIED requirements:
1. Знайдіть існуючу вимогу в `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (той самий store-орієнтований корінь, що вище)
2. Скопіюйте ВЕСЬ блок вимоги (від `### Requirement:` до всіх сценаріїв)
3. Вставте під `## MODIFIED Requirements` і відредагуйте, щоб відобразити нову поведінку
4. Переконайтеся, що текст заголовка точно збігається (чутливість до пробілів відсутня)

Поширена пастка: Використання MODIFIED з частковим вмістом втрачає деталі під час archive.
Якщо додаєте нові аспекти без зміни існуючої поведінки, використовуйте ADDED.

Приклад (нова можливість, тому її перша секція — `## Purpose`):
```
# Spec Delta

## Мета

Дозволяє користувачам вилучати свої дані з продукту у переносному форматі.

## ДОДАНО Вимоги

### Вимога: Користувач може експортувати дані
Система ПОВИННА дозволяти користувачам експортувати їхні дані у форматі CSV.

#### Сценарій: Успішний експорт
- **КОЛИ** користувач натискає кнопку "Експорт"
- **ТОДІ** система завантажує файл CSV із усіма даними користувача

## ВИДАЛЕНО Вимоги

### Вимога: Застарілий експорт
**Причина**: Замінено новою системою експорту
**Міграція**: Використовуйте нову кінцеву точку експорту за адресою /api/v2/export

```

Специфікації мають бути придатними для тестування — кожен сценарій є потенційним випадком тесту.

design.md

Пояснює, як реалізувати зміну. Створюється лише тоді, коли це необхідно.

Структура

Шаблон, який агент отримує як формат виводу (templates/design.md):

# Design

## Context

<!-- Поточний стан та обмеження, що формують підхід. Див. proposal.md для мотивації - не повторюйте її -->

## Goals / Non-Goals

**Цілі:**
<!-- Чого прагне досягти цей дизайн -->

**Нецілі:**
<!-- Що явно виходить за межі області видимості -->

## Decisions

<!-- Ключові рішення щодо дизайну з обґрунтуванням та розглянутими альтернативами -->

## Risks / Trade-offs

<!-- Відомі ризики та компроміси -->

Інструкції

Інструкція, яка надсилається агенту при створенні цього артефакту (з schema.yaml):

Створіть документ дизайну, який пояснює ЯК реалізувати зміну.

Коли включати design.md (створювати тільки якщо застосовується хоча б один пункт):
- Зміна, що охоплює кілька сервісів/модулів, або новий архітектурний патерн
- Нове зовнішнє залежність або суттєві зміни моделі даних
- Складність безпеки, продуктивності або міграції
- Невизначеність, яка виграє від технічних рішень перед початком кодування

Розділи:
- **Context**: Лише поточний стан та обмеження, необхідні для пояснення підходу. Посилайтеся на пропозицію щодо мотивації, а не повторюйте її (наприклад, "Див. proposal.md - Чому").
- **Goals / Non-Goals**: Чого досягає цей дизайн і що явно виключається. Не повторюйте область видимості пропозиції - додавайте лише межі рівня дизайну.
- **Decisions**: Ключові технічні вибори з обґрунтуванням (чому X замість Y?). Включайте розглянуті альтернативи для кожного рішення.
- **Risks / Trade-offs**: Відомі обмеження, те, що може піти не так. Формат: [Ризик] → Пом'якшення
- **Migration Plan**: Кроки для розгортання, стратегія відкату (якщо застосовно)
- **Open Questions**: Незнання, які можна безпечно вирішити пізніше, не змінюючи специфікації, підхід або розбиття задач. Пропустіть, якщо немає.

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

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

Хороші документи дизайну пояснюють "чому" за технічними рішеннями.

tasks.md

Розбиває реалізацію на перевірені задачі. apply відстежує прогрес тут.

Структура

Шаблон, який агент отримує як формат виводу (templates/tasks.md):

# Tasks

## 1. <!-- Назва групи задач -->

- [ ] 1.1 <!-- Опис задачі -->
- [ ] 1.2 <!-- Опис задачі -->

## 2. <!-- Назва групи задач -->

- [ ] 2.1 <!-- Опис задачі -->
- [ ] 2.2 <!-- Опис задачі -->

Інструкції

Інструкція, яка надсилається агенту при створенні цього артефакту (з schema.yaml):

Створіть список задач, який розбиває роботу з реалізації.

Перед написанням задач перевірте design.md на наявність Open Questions. Якщо будь-які з них
змінять те, що будується, спочатку вирішіть їх із користувачем - не закладайте
неозначене припущення у список задач.

**ВАЖЛИВО: Дотримуйтесь шаблону нижче для відстежуваних задач.** Фаза apply парсить
формат чекбоксів для відстеження прогресу. Бокс, що містить лише `x`, вважається виконаним,
верхній або нижній регістр та будь-який пробіл, тому `- [ x]` також вважається виконаним. Будь-який
інший маркер, включаючи `- [~]`, `- [-]` та порожній `- []`, читається як невиконаний. Рядок без
чекбокса взагалі не відстежується.

Рекомендації:
- Групуйте пов'язані відстежувані задачі під нумерованими заголовками ##
- Кожна відстежувана задача ОБОВ'ЯЗКОВО має бути чекбоксом: `- [ ] X.Y Опис задачі`
- Задачі мають бути достатньо малими, щоб завершити їх за одну сесію
- Розставляйте задачі за залежністю (що потрібно зробити спочатку?)
- Відстежуйте роботу з реалізації та перевірки, яку можна завершити до
  архівування. Якщо запитуваний робочий процес включає архівування або роботу, яка вимагає
  архівування цієї зміни, збережіть ці кроки як прості марковані пункти в
  необов'язковому розділі `## Workflow follow-up` в кінці tasks.md. Ці
  пункти є довідковою інформацією поза межами відстежуваного прогресу задач.
- Кожна задача ОБОВ'ЯЗКОВО повинна вказувати, як перевірити завершення (тест, команда,
  спостережувана поведінка або доставлений артефакт). Помістіть перевірку в
  опис чекбокса цієї задачі. Використовуйте окрему задачу для перевірки лише
  тоді, коли вона перевіряє ширшу інтеграцію або системну поведінку, що охоплює
  кілька задач реалізації.
- Кожна група задач ОБОВ'ЯЗКОВО повинна фіксувати тести та документацію, яких вимагає її власна робота.
  НЕ збирайте тестування чи документацію в останню групу -
  коли пізня група вперше використовує роботу з ранньої, помилки
  каскадно повертаються через кожну групу між ними і змушують переделувати. Група,
  робота якої не вимагає нічого, наприклад, каркас або налаштування залежностей,
  не несе нічого. Остання група призначена лише для перевірок інтеграції, а не для
  тестів і док., які мала попередня група.

Приклад:
```
# Tasks

## 1. Setup

- [ ] 1.1 Create new module structure and verify expected files are present
- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds

## 2. Core Implementation

- [ ] 2.1 Implement data export function and verify the export test passes
- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
- [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
```

Коли застосовно, додайте робочий процес як прості марковані пункти, наприклад:
```
## Workflow follow-up

- Archive the change after the project's review requirements are satisfied.
- Verify the archived result.
```

Посилайтеся на специфікації щодо того, що потрібно побудувати, на дизайн щодо того, як це зробити.

Apply

Передача від планування до реалізації. Apply — це фаза, яка працює з tasks.md, а не артефакт.

• Починається: коли tasks.md існує і містить хоча б одну задачу.
• Відстежує: чекбокси в tasks.md. Позначення їх виконаними є записом прогресу.
• Завершується: коли всі чекбокси позначено виконаними. OpenSpec тоді пропонує архівувати зміну.

Налаштування

Налаштування apply (з schema.yaml):

apply:
  requires: [tasks]
  tracks: tasks.md
  # instruction: показано нижче

Інструкції

Інструкція, яка надсилається агенту при початку реалізації (з schema.yaml):

Прочитайте контекстуальні файли, виконайте незавершені задачі, позначайте виконані по мірі проходження.
Зупиніться, якщо зіткнетеся з блокуючими проблемами або потрібне уточнення.

schema.yaml

Повний schema.yaml, з скороченими тілами інструкцій. Кожна показана повністю у відповідному розділі вище.

name: spec-driven
version: 1
description: Default OpenSpec workflow - proposal → specs → design → tasks
artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document outlining the change
    template: proposal.md
    # instruction: shown in full under proposal.md above
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    description: Detailed specifications for the change
    template: spec.md
    # instruction: shown in full under Delta specs above
    requires:
      - proposal

  - id: design
    generates: design.md
    description: Technical design document with implementation details
    template: design.md
    # instruction: shown in full under design.md above
    requires:
      - proposal

  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    # instruction: shown in full under tasks.md above
    requires:
      - specs
      - design

apply:
  requires: [tasks]
  tracks: tasks.md
  # instruction: shown in full under Apply above