Spec Workflow

Содержание

• Что такое Spec Workflow
• Требования
• Установка и настройка
• Структура проекта
• Состояния и роли
• Команды пользователя
• Роли AI-агентов
• Полный рабочий процесс
• Режим восстановления
• Решение проблем

Что такое Spec Workflow

Spec Workflow — это approval-gated workflow для AI-кодинга с разделением ответственности между ролями. Каждое изменение проходит через строгую цепочку: планирование → тесты → реализация → валидация → документирование.

Каждое изменение получает собственную папку с артефактами:

• proposal.md — зачем и что меняется
• tasks.md — чеклист реализации с нумерацией T-XX
• test-matrix.md — матрица тестов со статусом RED/GREEN
• changelog.md — описание изменений после архивации

Source of truth и накопление знаний

После архивации спецификации обновляются — это источник правды о том, как работает система. Каждый заархивированный change добавляет или модифицирует требования в основных спецификациях.

При повторном запуске AI читает openspec/specs/ и получает полную картину всех реализованных требований. Архивные папки openspec/changes/archive/ не читаются автоматически — они служат только для аудита.

открытые изменения ──► proposal + tasks ──► при архивации ──► openspec/specs/ (source of truth)

Плюсы

| Преимущество | Описание | |-------------|----------| | Approval gates | Три точки контроля: approve (план), approve tests (тесты), merge (валидация). Невозможно пропустить этап. | | Разделение ответственности | Planner пишет спецификации, Tester — тесты, Implementer — код, Documenter — документацию. Каждая роль имеет чёткий мандат. | | RED → GREEN | Тесты пишутся ДО кода. Это гарантирует, что код проходит проверку по заранее определённым критериям. | | Implementer harness | Обязательный lint + regression + e2e после каждой реализации. Нельзя пометить задачу как выполненную без прохождения всех проверок. | | Recovery mode | Если состояние workflow рассинхронизировано с файлами — вход в режим восстановления с явным выбором действий. | | Один workflow | Пользователь взаимодействует только с AI-ассистентом через команды workflow. | | История накопления | Source of truth (openspec/specs/) растёт с каждым архивированным change. AI видит полную картину при исследовании. | | Явный state machine | Состояния IDLE → PLANNED → TESTS_RED → IMPLEMENTED → TESTS_GREEN → ARCHIVED → IDLE. Никаких неявных переходов. |

Минусы и ограничения

| Проблема | Описание | |----------|----------| | Зависимость от AI | Весь workflow построен вокруг AI-ассистента. Без AI workflow не работает — AI должен правильно создавать артефакты, следовать ролям, соблюдать gates. | | Один AI-контекст | AI читает specs при start:, но не при обычном кодинге. Если разработчик пишет код в обычном режиме — AI не видит spec-контекст. | | Дрейф между кодом и спеками | Workflow описывает что должно быть, но не проверяет что есть. Код может эволюционировать независимо от спецификаций. | | Ручная поддержка актуальности | Когда разработчики меняют код без workflow, спецификации быстро устаревают. Никто не заставляет проходить workflow перед коммитом. | | Одномерный workflow | Нет поддержки параллельных изменений. Пока один change не заархивирован, новый не может начаться. | | Масштабируемость | В больших проектах openspec/specs/ может стать огромным. AI имеет ограниченный контекст, поэтому при большой кодовой specs могут не помещаться. | | Жёсткая последовательность | Нельзя пропустить фазы. Нельзя начать реализацию без тестов. Нельзя заархивировать без Documenter. | | Фрагментация артефактов | Артефакты разбросаны: proposal.md, tasks.md, test-matrix.md, changelog.md, workflow_state.md. Нужно поддерживать их все в согласованном состоянии. |

Краткий рабочий процесс

1. start: <описание задачи>     → Planner создаёт proposal + tasks
2. approve                       → Tester пишет RED тесты + test-matrix
3. approve tests                 → Implementer пишет код + harness
4. merge                         → Documenter обновляет спеки + архивирует
5. Повторить шаг 1               → AI видит все прошлые изменения

Требования

• AI-ассистент, который читает AGENTS.md, .opencode/agents/* и workflow.md
• opencode (AI-ассистент)
• (Опционально) Node.js >= 20.19.0 и npm/yarn — только для установки через npm/npx и запуска install.js
• (Опционально) openspec CLI — для генерации артефактов через CLI

Workflow не привязан к языку проекта. Он может использоваться с Python, Go, Java, Ruby, PHP, Rust, мобильными проектами, инфраструктурными репозиториями и любым другим стеком, если в <project_context> указаны реальные артефакты проекта.

Установка и настройка

1. Установка workflow в проект

Пакет публикуется в npm как @pavelsmith/openspec-workflow.

Вызовите installer один раз, указав путь к проекту:

npx @pavelsmith/openspec-workflow install /path/to/your/project

Для текущей директории проекта:

npx @pavelsmith/openspec-workflow install .

Альтернатива через global install:

npm install -g @pavelsmith/openspec-workflow
openspec-workflow install /path/to/your/project

Installer скопирует агентов, команды, навыки, workflow.md, инициализирует openspec/ и добавит ссылку на workflow в AGENTS.md. Существующие файлы не перезаписываются.

2. Установка openspec CLI (опционально)

npm install -g openspec

Проверьте установку:

openspec --version

3. Настройка opencode.json

Отредактируйте .opencode/opencode.json, указав провайдера и модель:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "apiKey": "your-api-key",
      "models": {
        "gpt-4": {
          "name": "GPT-4"
        }
      }
    }
  },
  "model": "openai/gpt-4"
}

4. Настройка <project_context>

Во всех файлах .opencode/agents/*.md и workflow.md есть блоки <project_context>. Это единственное место, где workflow получает знания о конкретном проекте: области ответственности, source-of-truth спецификации, тестовые артефакты, команды проверки, контракты и ограничения.

Не копируйте чужую структуру. Объявите только те области и артефакты, которые есть в вашем проекте. Если проекту не нужны слои — не вводите их. Если слои нужны, назовите их так, как принято в проекте: domain, api, worker, mobile, infra, billing, admin, etl, contracts и т.д.

Один промпт для автоматической настройки:

Напишите AI-ассистенту:

Подготовь мой проект к spec workflow. Найди все блоки <project_context> в файлах .opencode/agents/*.md и workflow.md, определи реальные области проекта, source-of-truth спецификации, контракты, тестовые артефакты, команды проверки и замени <project_context> на значения моего проекта.

Или заполните вручную:

<project_context>
- Project overview: сервис обработки заявок на Python; основная бизнес-логика в `src/domain/`
- Project areas:
  - DOMAIN: `src/domain/` — правила, сценарии, инварианты
  - STORAGE: `src/storage/` — миграции, репозитории, схемы БД
  - API: `src/http/` — HTTP handlers и OpenAPI contract
  - CLI: `src/cli/` — команды оператора
- Source-of-truth specs:
  - Product behavior: `openspec/specs/product/spec.md`
  - Domain rules: `openspec/specs/domain/spec.md`
  - API contract: `openspec/specs/api/spec.md`
- Project contracts/artifacts:
  - OpenAPI: `contracts/openapi.yaml`
  - DB migrations: `migrations/`
- Test locations:
  - Unit: `tests/unit/`
  - Integration: `tests/integration/`
  - E2E: `tests/e2e/`
- Verification commands:
  - Lint: `ruff check .`
  - Unit tests: `pytest tests/unit`
  - Regression: `pytest`
  - E2E: `make e2e`
</project_context>

Структура проекта

Ниже пример структуры. Имена spec-директорий и набор артефактов должны соответствовать вашему <project_context>.

your-project/
├── openspec/
│   ├── config.yaml              # Конфигурация (schema, context, rules)
│   ├── specs/                   # Основные спецификации (источник правды)
│   │   ├── product/
│   │   │   └── spec.md          # Поведение продукта и пользовательские сценарии
│   │   ├── domain/
│   │   │   └── spec.md          # Бизнес-правила и инварианты
│   │   └── api/
│   │       └── spec.md          # Контракты интеграций, если они есть
│   └── changes/                 # Активные и архивные изменения
│       ├── <YYYY-MM-DD-slug>/
│       │   ├── proposal.md      # Зачем и что
│       │   ├── tasks.md         # Чеклист с нумерацией T-XX
│       │   ├── use-cases/       # Cucumber Gherkin сценарии (опционально)
│       │   │   └── *.feature
│       │   └── (артефакты от Tester/Implementer)
│       └── archive/             # Заархивированные изменения (для аудита)
│           └── YYYY-MM-DD-<name>/
├── .opencode/
│   ├── agents/                  # Правила ролей
│   │   ├── planner.md           # Planner: спецификации и планы
│   │   ├── tester.md            # Tester: тесты RED и GREEN
│   │   ├── implementer.md       # Implementer: код и harness
│   │   └── documenter.md        # Documenter: документация и архив
│   ├── commands/                # Команды-процедуры
│   │   ├── apply.md             # Процедура применения задач
│   │   ├── archive.md           # Процедура архивации
│   │   ├── explore.md           # Процедура исследования
│   │   └── propose.md           # Процедура предложения
│   ├── skills/                  # Навыки для AI
│   │   ├── apply.md
│   │   ├── archive.md
│   │   ├── explore.md
│   │   └── propose.md
│   └── opencode.json            # Провайдер и модель
├── workflow.md                  # Главный файл workflow
├── workflow_state.md            # Текущее состояние workflow (создаётся автоматически)
└── AGENTS.md                    # Описание проекта и конвенции

Ключевые файлы:

| Файл | Назначение | |------|-----------| | workflow.md | Главный файл — правила, роли, state machine, команды пользователя | | workflow_state.md | Текущее состояние (создаётся и обновляется автоматически) | | AGENTS.md | Описание проекта, конвенции, структура директорий | | openspec/specs/ | Source of truth — как система работает сейчас | | openspec/changes/ | Активные изменения — одно дерево на каждое изменение |

Состояния и роли

IDLE → PLANNED → TESTS_RED → IMPLEMENTED → TESTS_GREEN → ARCHIVED → IDLE

State machine

| Состояние | Роль | Что происходит | Следующее состояние | |-----------|------|----------------|---------------------| | IDLE | — | Ожидание команды пользователя | PLANNED (после start:) | | PLANNED | Planner | Создан proposal + tasks | TESTS_RED (после approve) | | TESTS_RED | Tester | Написаны FAILING тесты | IMPLEMENTED (после approve tests) | | IMPLEMENTED | Tester | Запущен GREEN валидация | TESTS_GREEN (после next) | | TESTS_GREEN | Documenter | Все тесты GREEN | ARCHIVED (после merge) | | ARCHIVED | — | Изменение заархивировано, спеки обновлены | IDLE (после next) |

Approval gates

Три точки контроля, которые нельзя пропустить:

1. approve — после создания proposal и tasks. Tester подтверждает, что план приемлем.
2. approve tests — после написания RED тестов. Implementer подтверждает, что тесты корректны.
3. merge — после GREEN валидации. Documenter подтверждает, что всё готово к архивации.

Команды пользователя

Все команды вводятся в чат AI-ассистента. Прямые вызовы ролей (@planner, @tester) заблокированы.

status

Показать текущее состояние workflow.

Ответ:

Current phase: TESTS_RED
Current change: 2026-07-06-add-payment-gateway
Next step: Implementer напишет код
Waiting for: user approve tests

start: <описание задачи>

Начать новое изменение. Доступно только в состоянии IDLE.

Пример:

start: Добавить шлюз оплаты для Stripe

Что происходит:

1. Planner определяет project-defined scope: одну или несколько областей из <project_context>
2. Проверяет зависимости между областями и артефактами проекта
3. Создаёт openspec/changes/<YYYY-MM-DD-slug>/
4. Создаёт proposal.md, tasks.md, Cucumber use-кейсы
5. Обновляет workflow_state.md → PLANNED
6. Ожидает команду approve

approve

Подтвердить план Planner и передать задачу Tester. Доступно только в состоянии PLANNED.

Что происходит:

1. Tester читает tasks.md и Definition of Done
2. Пишет FAILING тесты (только тесты, без production кода)
3. Создаёт test-matrix.md
4. Обновляет workflow_state.md → TESTS_RED
5. Ожидает команду approve tests

approve tests

Подтвердить тесты и передать задачу Implementer. Доступно только в состоянии TESTS_RED.

Что происходит:

1. Implementer читает proposal.md, tasks.md, test-matrix.md
2. Пишет production код (НЕ редактирует тесты)
3. Помечает задачи в tasks.md как выполненные
4. Обновляет workflow_state.md → IMPLEMENTED
5. Автоматически запускает GREEN валидацию (Tester)
6. Ожидает команду merge

next

Переход по workflow в зависимости от текущего состояния.

| Текущее состояние | Поведение | |-------------------|----------| | IDLE | Сказать что нет активного change, попросить start: | | PLANNED | Сказать что нужен approve, не запускать Tester | | TESTS_RED | Сказать что нужен approve tests, не запускать Implementer | | IMPLEMENTED | Запустить Tester GREEN валидацию → TESTS_GREEN | | TESTS_GREEN | Сказать что нужен merge, не запускать Documenter | | ARCHIVED | Нормализовать к IDLE, разрешить новый start: |

merge

Завершить change: Documenter обновляет спеки, создаёт changelog, архивирует. Доступно только в состоянии TESTS_GREEN.

Что происходит:

1. Documenter обновляет source-of-truth спецификации
2. Обновляет canonical artifacts из <project_context>, если изменился контракт, схема, миграция или общий артефакт
3. Создаёт changelog.md
4. Ставит proposal.md статус ARCHIVED
5. Обновляет workflow_state.md → ARCHIVED
6. Нормализует к IDLE

Роли AI-агентов

Planner

Мандат: Преобразовать бизнес-требование в OpenSpec change package. Не писать production код и тесты.

Создаёт:

• proposal.md — Problem, Solution, Out of scope, Dependencies, Definition of Done
• tasks.md — нумерованные задачи T-01, T-02, T-03 с project-defined tags
• use-cases/*.feature — Cucumber Gherkin сценарии (для user-facing функциональности)

Пример tasks.md:

# Tasks: Добавить шлюз оплаты Stripe
**Scope:** DOMAIN, API, CONTRACTS, UI

## Breakdown
- [ ] T-01 [CONTRACTS]: обновить публичный контракт платежа
- [ ] T-02 [DOMAIN]: добавить правила создания платежа
- [ ] T-03 [API]: добавить endpoint создания платежа
- [ ] T-04 [DOMAIN]: покрыть правила unit-тестами
- [ ] T-05 [UI]: добавить форму оплаты
- [ ] T-06 [UI]: покрыть форму поведенческими тестами

## Agent assignments
- Tester: T-04, T-06
- Implementer: T-01, T-02, T-03, T-05
- Documenter: specs, changelog, archival

Tester

Мандат: Обеспечить поведенческую корректность через тесты. Не писать production код.

RED фаза:

1. Читает tasks.md и Definition of Done
2. Пишет FAILING тесты для задач из declared scope
3. Для каждой области использует тестовый фреймворк, указанный в <project_context>
4. Для интеграционных сценариев — e2e тесты, contract tests или Cucumber, если они есть в проекте
5. Проверяет, что RED обусловлен ожидаемым поведением, а не ошибкой настройки
6. Создаёт test-matrix.md с таблицей статусов
7. Ожидает approve tests

GREEN фаза:

1. Запускает команды проверки, указанные в <project_context>
2. Запускает coverage отчёт, если он обязателен для проекта
3. Обновляет test-matrix.md → GREEN
4. Ожидает merge

Implementer

Мандат: Написать минимальный production код для прохождения тестов. Не редактировать тесты. Не расширять scope.

Процесс:

1. Работает по одной задаче T-XX за раз
2. Если задача меняет общий контракт или общий артефакт — сначала обновляет его, затем потребителей
3. Запускает узкие тесты для текущей задачи
4. Помечает задачу как выполненную немедленно после проверки
5. После всех задач запускает Implementer Harness

Implementer Harness (обязательно для каждого изменения):

• Lint/static analysis команда из <project_context>
• Regression команда из <project_context>
• E2E/acceptance/contract checks из <project_context>, если они обязательны
• Нельзя пометить реализацию как завершённую пока harness не GREEN

Запрещено без явного разрешения:

• Редактировать тестовые файлы
• Расширять scope текущего change
• Дублировать project contracts или общие модели вместо использования source-of-truth артефакта

Documenter

Мандат: Синхронизировать документацию и канонические артефакты проекта с реализацией. Не писать код и тесты.

После изменений в declared scope:

1. Обновляет source-of-truth спецификации, указанные в <project_context>
2. Если изменился контракт или общий артефакт — обновляет его в каноническом месте проекта
3. Создаёт changelog.md
4. Ставит proposal.md статус ARCHIVED
5. Обновляет workflow_state.md → ARCHIVED

Стиль документации:

• Правила и требования нумеруются по префиксам проекта: BR-01, UX-01, API-01, OPS-01 и т.д.
• Настоящее время: "Component displays..."
• Канонические контракты проекта не дублируются в отдельных областях

Полный рабочий процесс

Шаг 1: start: <описание>

Пользователь: start: Добавить шлюз оплаты для Stripe

AI → Planner:
  1. Определяет scope: DOMAIN, API, CONTRACTS, UI
  2. Проверяет зависимости
  3. Создаёт openspec/changes/2026-07-06-add-stripe/
  4. Создаёт proposal.md, tasks.md, use-cases/*.feature
  5. Обновляет workflow_state.md → PLANNED

AI сообщает:
  Change создан: 2026-07-06-add-stripe. Ожидается команда approve.

Шаг 2: approve

Пользователь: approve

AI → Tester:
  1. Читает tasks.md и Definition of Done
  2. Пишет FAILING тесты для T-04 и T-06
  3. Создаёт test-matrix.md
  4. Обновляет workflow_state.md → TESTS_RED

AI сообщает:
  Тесты RED готовы. 5 тестов добавлено. Ожидается команда approve tests.

Шаг 3: approve tests

Пользователь: approve tests

AI → Implementer:
  1. Читает proposal.md, tasks.md, test-matrix.md
  2. Реализует T-01 (контракт), T-02 (domain rules), T-03 (API handler), T-05 (UI flow)
  3. Помечает задачи в tasks.md как [x]
  4. Обновляет workflow_state.md → IMPLEMENTED
  5. Запускает GREEN валидацию (Tester)
  6. Запускает Implementer Harness (lint + regression + e2e)

AI сообщает:
  Реализация завершена, regression GREEN, coverage 91%. Ожидается команда merge.

Шаг 4: merge

Пользователь: merge

AI → Documenter:
  1. Обновляет source-of-truth specs из <project_context>
  2. Обновляет contract artifacts, если изменился публичный контракт
  3. Создаёт changelog.md
  4. Ставит proposal.md статус ARCHIVED
  5. Обновляет workflow_state.md → ARCHIVED
  6. Нормализует к IDLE

AI сообщает:
  Change архивирован. Обновлены specs и contract artifacts. Можно запускать следующий change.

Шаг 5: Следующий change

Пользователь: start: Добавить webhook для Stripe callback

AI → Planner:
  1. Читает релевантные specs из <project_context> (теперь включают Stripe payment)
  2. Создаёт новый change с учётом уже реализованного

Режим восстановления

Вход в recovery mode когда состояние workflow рассинхронизировано с файлами:

Примеры рассинхронизации:

• Current phase = IMPLEMENTED, но test-matrix.md отсутствует
• Current change != null, но директория change не существует
• TESTS_GREEN, но changelog.md уже существует
• Задачи неполные, а фаза заявляет завершённую реализацию или валидацию

Поведение:

1. Не выполнять автоматические переходы
2. Показать несоответствие явно
3. Предложить варианты:
   • recover: sync workflow state — синхронизировать состояние с файлами
   • recover: rebuild artifacts — пересоздать недостающие артефакты
   • recover: archive current change — заархивировать текущее изменение

Важно: Не пытаться "угадать" через recovery — это может уничтожить или исказить работу.

Решение проблем

Команды не распознаются

1. Проверьте что workflow.md присутствует в корне проекта
2. Перезапустите AI-ассистент (skills сканируются при старте)
3. Проверьте что workflow_state.md существует или создайте его

Неправильная фаза

Если фаза не соответствует файлам — это recovery mode. Не пытайтесь продолжить обычным путём.

Изменение не начинается

1. Проверьте что workflow_state.md показывает IDLE
2. Если есть активный change — нужно его сначала заархивировать
3. Невозможно начать новый change пока текущий не завершён

Harness падает

1. Исправьте проблему в scope текущего change и перезапустите
2. Если проблема не связана с current change — остановитесь и сообщите о блокере
3. Не пропускайте harness — это обязательная проверка

Конфликт в архивации

Целевое имя YYYY-MM-DD-<name> уже существует:

• Удалите дубликат (если это тот же change)
• Или подождите до следующего дня (разные changes с одинаковым slug)

Быстрый старт

Минимальная настройка проекта

your-project/
├── workflow.md                    # Установлено пакетом @pavelsmith/openspec-workflow
├── .opencode/                     # Установлено пакетом @pavelsmith/openspec-workflow
├── openspec/
│   ├── specs/
│   │   ├── product/
│   │   │   └── spec.md           # Пустой или с текущими требованиями
│   │   ├── domain/
│   │   │   └── spec.md           # Пустой или с текущими правилами
│   │   └── api/
│   │       └── spec.md           # Пустой или с текущими контрактами
│   └── changes/
│       └── archive/
└── AGENTS.md                      # Описание вашего проекта

Первая итерация

1. start: Добавить авторизацию через Google OAuth
2. approve
3. approve tests
4. merge

Полезные команды

status                              — текущее состояние workflow
start: <описание>                   — начать новое изменение
approve                             — подтвердить план Planner
approve tests                       — подтвердить тесты Tester
next                                — переход по workflow
merge                               — завершить change