Перейти к содержимому

Выбрать язык

Текущий язык: Русский

Справочник CLI

CLI OpenSpec (openspec) предоставляет команды терминала для настройки проекта, проверки, просмотра состояния и управления. Эти команды дополняют slash-команды ИИ (например, /opsx:propose), описанные в разделе Команды.

Категория Команды Назначение
Настройка init, update Инициализировать и обновить OpenSpec в проекте
Хранилища (отдельные репозитории OpenSpec) store setup, store register, store unregister, store remove, store list, store doctor Управлять зарегистрированными хранилищами — отдельными репозиториями OpenSpec
Состояние doctor Проверить состояние связей выбранного корня
Рабочий контекст context Собрать рабочий набор (корень и связанные хранилища)
Личные рабочие наборы workset create, workset list, workset open, workset remove Сохранять и открывать в инструменте личные локальные представления
Просмотр list, view, show Просматривать изменения и спецификации
Проверка validate Проверять изменения и спецификации на ошибки
Жизненный цикл archive Завершать изменения и архивировать их
Рабочий процесс new change, status, instructions, templates, schemas Поддержка рабочего процесса на основе артефактов
Схемы schema init, schema fork, schema validate, schema which Создавать и управлять пользовательскими рабочими процессами
Конфигурация config Просматривать и изменять настройки
Утилиты feedback, completion Отзывы и интеграция с оболочкой

Большинство команд CLI предназначено для пользователей, работающих в терминале. Некоторые команды также поддерживают использование agents и сценариями с помощью вывода JSON.

Эти команды интерактивны и предназначены для работы в терминале:

Команда Назначение
openspec init Инициализировать проект (интерактивные prompts)
openspec view Открыть интерактивный dashboard
openspec workset open <name> Открыть сохранённый рабочий набор (окно редактора или сеанс agent в терминале)
openspec config edit Открыть конфигурацию в редакторе
openspec feedback Отправить отзыв через GitHub
openspec completion install Установить автодополнение для оболочки

Эти команды поддерживают вывод --json для программного использования AI agents и сценариями:

Команда Для пользователя Для agent
openspec list Просмотр изменений/спецификаций --json для структурированных данных
openspec show <item> Чтение содержимого --json для разбора
openspec validate Поиск проблем --all --json для пакетной проверки
openspec status Просмотр хода создания артефактов --json для структурированного состояния
openspec instructions Получение следующих шагов --json для инструкций agent
openspec templates Поиск путей шаблонов --json для разрешения путей
openspec schemas Список доступных схем --json для обнаружения схем; --store <id> для выбора зарегистрированного корня
openspec store setup <id> Создание и регистрация локального хранилища --json с явными параметрами для структурированного вывода настройки
openspec store register <path> Регистрация существующего хранилища --json для структурированного вывода регистрации
openspec store unregister <id> Удаление регистрации локального хранилища --json для структурированного вывода очистки
openspec store remove <id> Удаление зарегистрированной локальной папки хранилища --yes --json для неинтерактивного удаления
openspec store list Просмотр зарегистрированных хранилищ --json для структурированного списка
openspec store doctor Проверка настройки локального хранилища --json для структурированной диагностики
openspec new change <id> Создание каркаса изменения в репозитории --json, а также --store <id> для использования зарегистрированного хранилища как корня OpenSpec
openspec workset create [name] Создание личного рабочего набора --member <path> --json для неинтерактивного создания
openspec workset list Просмотр сохранённых рабочих наборов --json для структурированных представлений
openspec workset remove <name> Удаление сохранённого представления --yes --json для неинтерактивного удаления

Эти параметры доступны для всех команд:

Параметр Описание
--version, -V Показать номер версии
--no-color Отключить цветной вывод
--help, -h Показать справку по команде

Инициализировать OpenSpec в проекте. Создаёт структуру папок и настраивает интеграции с ИИ-инструментами.

По умолчанию используются глобальные настройки: profile core, способ установки both, рабочие процессы propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Используйте --language <language>, чтобы добавить инструкцию о языке в openspec/config.yaml нового проекта. Для существующего проекта измените поле context конфигурации, чтобы OpenSpec не перезаписал специфичные для проекта инструкции.

Аргументы:

Аргумент Обязательный Описание
path Нет Целевой каталог (по умолчанию: текущий каталог)

Параметры:

Параметр Описание
--tools <list> Настроить ИИ-инструменты без диалога. Используйте all, none или список через запятую
--language <language> Указать язык артефактов при создании новой конфигурации
--force Автоматически очистить устаревшие файлы без prompt
--profile <profile> Переопределить глобальный profile для этого вызова init (core или custom)
--no-animation Показать статическую заставку вместо анимированной
--copilot-cloud Без prompt настроить файлы cloud coding agent GitHub Copilot
--no-copilot-cloud Без prompt пропустить файлы cloud coding agent GitHub Copilot

--profile custom использует рабочие процессы, выбранные в глобальной конфигурации (openspec config profile).

Анимация приветствия также отключается, если задана переменная среды OPENSPEC_NO_ANIMATION (любое значение, включая пустое), если NO_COLOR задана непустым значением или если в ОС включено уменьшение движения (Reduce Motion в macOS, отключённые анимации GNOME).

Поддерживаемые ID инструментов (--tools) — также принимается windsurf как псевдоним devin: amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

Этот список соответствует AI_TOOLS в src/core/config.ts. Пути навыков и команд каждого инструмента см. в разделе Поддерживаемые инструменты.

Примеры:

Окно терминала
# Interactive initialization
openspec init
# Initialize in a specific directory
openspec init ./my-project
# Non-interactive: configure for Claude and Cursor
openspec init --tools claude,cursor
# Non-interactive: configure global MiniMax Code skills
openspec init --tools minimax-code
# Configure for all supported tools
openspec init --tools all
# Override profile for this run
openspec init --profile core
# Skip prompts and auto-cleanup legacy files
openspec init --force

Что создаёт команда:

openspec/
├── specs/ # Your specifications (source of truth)
├── changes/ # Proposed changes
└── config.yaml # Project configuration
.claude/skills/ # Claude Code skills (if claude selected)
.cursor/skills/ # Cursor skills (if cursor selected)
.cursor/commands/ # Cursor OPSX commands (if delivery includes commands)
.agents/skills/ # Shared skills for AGENTS.md-compatible tools (if agents selected)
... (other tool configs)

Обновить файлы инструкций OpenSpec после обновления CLI. Повторно создаёт файлы конфигурации ИИ-инструментов с учётом текущего глобального profile, выбранных рабочих процессов и способа установки.

openspec update [path] [options]

Аргументы:

Аргумент Обязательный Описание
path Нет Целевой каталог (по умолчанию: текущий каталог)

Параметры:

Параметр Описание
--force Выполнить обновление, даже если файлы актуальны
--dry-run Показать, что изменило бы обновление, и ничего не записывать
--json С --dry-run вывести запланированные изменения в формате JSON

Пример:

Окно терминала
# Update instruction files after npm upgrade
npm install -g @fission-ai/openspec@latest
openspec update

Предварительный просмотр обновления:

--dry-run показывает, какие файлы обновление добавило бы, изменило или удалило, и ничего не записывает. Пути указаны относительно проекта; файлы за его пределами (навыки в домашнем каталоге) показаны с префиксом ~/.

Окно терминала
openspec update --dry-run --json
{
"changes": [
{ "path": ".claude/skills/openspec-explore/SKILL.md", "action": "update", "tool": "claude" },
{ "path": "~/.minimax/skills/openspec-propose/SKILL.md", "action": "add", "tool": "minimax-code" }
],
"notes": [],
"failures": []
}

План соответствует тому, что делает неинтерактивный запуск, и перечисляет каждый файл, который будет затронут: перемещения из прежнего каталога инструмента, сохранение глобальной конфигурации для установки, выполненной до появления profiles, файлы cloud coding agent Copilot и, с --force, очистку устаревших артефактов. Файлы, которые принадлежат самому OpenSpec, а не одному инструменту, имеют tool: "openspec". notes отмечает шаги, о которых спросили бы пользователя в терминале, каждый с устойчивым code: legacy-tool-directories (перемещение, отмеченное как выполненное) и legacy-artifacts (файлы старой структуры, которые обновление не трогает без --force). failures перечисляет инструменты, на которых завершилось бы реальное обновление, включая записи, которые оно не может выполнить (каталог на месте файла, нет права на запись); для такого инструмента план останавливается там, где остановилось бы обновление, и один неисправный инструмент не лишает вас остального плана. В обычном обновлении оба списка пусты. Полный справочник: openspec.dev/docs/cli.

Неудачный вызов --dry-run --json по-прежнему выводит ровно один JSON-документ: пустой план и массив status, при этом код завершения ненулевой.

Сначала обновите пакет. Файлы инструкций создаются установленной версией CLI, поэтому запуск openspec update на устаревшей версии сообщит, что всё актуально, но не добавит новые рабочие процессы из более поздних выпусков.

Чтобы выявить такую ситуацию, openspec update проверяет в реестре npm, не опубликована ли более новая версия CLI. Если у вас установлена устаревшая версия, команда предложит обновление:

A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

Если ответить «да», команда выполнит npm install -g @fission-ai/openspec@latest, а затем повторит обновление уже новым CLI, чтобы новые процессы установились за один запуск. Она подтверждает обновление, запрашивая версию установленного двоичного файла, а не полагаясь на код завершения npm. Если в PATH раньше находится другая установка, команда сообщит об этом, а не заявит об успехе. Если ответить «нет», она напечатает команду обновления и продолжит с установленной версией CLI. Ctrl-C останавливает команду.

Предложение появляется только в интерактивном терминале и только если пакет установлен через npm — это единственный случай, который исправляет npm install -g. Для остальных способов выводится соответствующая команда:

Способ установки OpenSpec Результат
Глобальная установка через npm В интерактивном терминале появится prompt, и обновление будет выполнено за вас; при перенаправленном выводе команда будет напечатана
Глобальная установка через pnpm, bun, yarn или volta Команда соответствующего менеджера: pnpm add -g …@latest, bun add -g …@latest, yarn global add …@latest или volta install …@latest
Зависимость проекта Подсказка обновить зависимость, поскольку файлом блокировки управляет менеджер пакетов проекта
Кэш npx / dlx npx @fission-ai/openspec@latest update — эта команда одновременно выполняет обновление, второй шаг не нужен
Клонирование через git Ничего — ваша версия определяется текущей веткой

Если команда что-либо выводит, она указывает каталог, из которого загружен CLI. Проверьте этот путь, если вы обновились, но в PATH по-прежнему используется устаревший shim.

Для запроса используется реестр из npm_config_registry, если npm экспортирует эту переменную; иначе — https://registry.npmjs.org. Файл .npmrc не читается: не следует позволять содержимому файла определять адрес исходящего запроса, тем более что .npmrc проекта хранится в репозитории. Для частного зеркала экспортируйте npm_config_registry или задайте OPENSPEC_NO_UPDATE_CHECK, чтобы полностью пропустить проверку. Проверка пропускается, если CI задана не явным значением отключения (false, 0, no, off или пустая строка), при NODE_ENV=test, а также если задана OPENSPEC_NO_UPDATE_CHECK (любое значение), DO_NOT_TRACK=1 или OPENSPEC_TELEMETRY=0. Она выполняется перед обновлением и задерживает его не более чем на 1,5 секунды; по истечении этого срока прекращается даже при молчаливой потере сетевых пакетов и не выдаёт ошибок, если реестр недоступен.

Как определяется актуальность: в файлах навыков записана версия, которая их создала; OpenSpec сравнивает её с установленной версией CLI. В файлах команд нет метки версии, поэтому для инструментов с командами, но без навыков (режим установки commands), OpenSpec сравнивает содержимое файлов с тем, что создал бы сейчас. Изменённые вручную файлы считаются устаревшими и перезаписываются. В режимах skills и both проверяется только записанная версия, поэтому вручную изменённый файл с актуальной версией остаётся нетронутым; для принудительной перезаписи используйте --force. В любом случае сгенерированные файлы принадлежат OpenSpec; храните собственные инструкции отдельно.


Бета-версия. Хранилища и связанные с ними функции (ссылки, рабочий контекст, рабочие наборы) — новые; названия команд, флаги, форматы файлов и вывод JSON могут меняться между выпусками. Руководство по сценариям использования см. в разделе Хранилища.

Хранилище — это отдельный репозиторий OpenSpec, зарегистрированный на данном компьютере, например репозиторий планирования или контрактов. После регистрации обычные команды (list, show, status, validate, new change, archive и др.) могут работать с ним из любого каталога с помощью --store <id>.

Создать и зарегистрировать локальное хранилище. Если в терминале аргументы не указаны, OpenSpec проведёт пользователя через настройку. Agents и сценариям следует передавать параметры явно и использовать --json.

Окно терминала
openspec store setup [id] [options]

Параметры:

Параметр Описание
--path <path> Каталог для хранилища (например, ~/openspec/<id>)
--remote <url> Сохранить основной удалённый URL в store.yaml нового хранилища
--init-git Инициализировать репозиторий Git и создать начальный коммит (по умолчанию)
--no-init-git Пропустить все действия Git: не запускать init и не создавать коммит
--json Вывод в формате JSON

Для неинтерактивного запуска (--json, сценарии, agents) необходимо указать и ID хранилища, и --path. В интерактивном терминале команда запрашивает путь и предлагает редактируемое расположение в доступном пользователю месте (например, ~/openspec/<id>); каталог данных под управлением OpenSpec по умолчанию не используется.

Примеры:

Окно терминала
openspec store setup
openspec store setup team-context
openspec store setup team-context --path ~/openspec/team-context --no-init-git
openspec store setup team-context --path ~/openspec/team-context --no-init-git --json

Зарегистрировать существующий каталог локального хранилища. В период бета-тестирования корень можно зарегистрировать до создания изменений, применения спецификаций или архивации изменений; в этом случае openspec/changes/, openspec/specs/ и openspec/changes/archive/ могут отсутствовать, пока обычные команды не создадут их. Репозиторий только с конфигурацией, объявляющей store: <id>, остаётся указателем на другое хранилище и не регистрируется как корень хранилища, пока указатель не удалён.

Окно терминала
openspec store register [path] [options]

Параметры:

Параметр Описание
--id <id> ID хранилища; по умолчанию берётся из метаданных или имени каталога
--yes Подтвердить создание метаданных хранилища для исправного корня OpenSpec
--json Вывод в формате JSON

Отменить локальную регистрацию хранилища, не удаляя файлы.

Окно терминала
openspec store unregister <id> [--json]

Используйте команду, если хранилище переместили или клонировали в другое место либо его больше не нужно отображать в OpenSpec на этом компьютере.

Отменить локальную регистрацию хранилища и удалить его локальный каталог.

Окно терминала
openspec store remove <id> [--yes] [--json]

В интерактивном терминале remove перед удалением показывает точный путь к папке. Agents, сценарии и пользователи режима JSON должны передать --yes, чтобы подтвердить удаление. OpenSpec не удаляет папку, если в ней нет соответствующих метаданных хранилища.

Вывести список локально зарегистрированных хранилищ.

Окно терминала
openspec store list [--json]
openspec store ls [--json]

Проверить локальную регистрацию хранилища, его метаданные и наличие Git.

Окно терминала
openspec store doctor [id] [--json]

Команда doctor выполняет только диагностику: сообщает об отсутствующих корнях, несоответствиях метаданных и ошибках локального реестра, не меняя хранилище.

В openspec/config.yaml проекта можно указать хранилища, от которых зависит работа:

schema: spec-driven
references:
- team-context

После этого вывод openspec instructions в данном репозитории (для отдельных артефактов и apply, как в JSON-режиме, так и в человекочитаемом) содержит индекс спецификаций каждого указанного хранилища: ID спецификаций, краткое описание из раздела Purpose и команду получения (openspec show <spec-id> --type spec --store <id>). Индекс обновляется при каждом запуске по зарегистрированной рабочей копии; содержимое спецификаций в вывод не копируется.

Ссылки предоставляют контекст только для чтения. Они не меняют место выполнения команд: работа ведётся в корне самого репозитория, а запись в указанное хранилище требует явного --store. Если ссылку не удаётся разрешить (например, хранилище не зарегистрировано на этом компьютере), в индексе появляется предупреждение с точной командой исправления, но инструкции всё равно создаются. Состояние ссылок можно проверить командой openspec doctor.

Сохранение адреса клонирования хранилища

Заголовок раздела «Сохранение адреса клонирования хранилища»

Хранилище может сохранять основной источник клонирования в своём версионируемом файле идентификации. Так подключение новых участников не остановится на шаге «зарегистрируйте хранилище»:

Окно терминала
openspec store setup team-context --path ~/openspec/team-context \
--remote git@github.com:acme/team-context.git

Удалённый URL записывается в .openspec-store/store.yaml первым коммитом, поэтому каждый клон сразу знает источник. Для существующего хранилища измените store.yaml вручную и создайте коммит. Команда store doctor показывает записанный URL и наблюдаемый Git origin рабочей копии; инструкции по совместному использованию в setup/register указывают этот адрес, а register также записывает origin рабочей копии в локальный реестр компьютера.

В объявлении ссылки также можно указать источник клонирования, чтобы коллега без хранилища получил полную команду исправления, готовую к копированию (git clone <remote> <path> && openspec store register <path> --id <id>):

references:
- { id: team-context, remote: "git@github.com:acme/team-context.git" }

Сохранение удалённого URL не является синхронизацией: OpenSpec не клонирует, не выполняет pull и не отправляет изменения самостоятельно.

В репозитории, где планирование полностью вынесено наружу (нет локальных openspec/specs/ или openspec/changes/), можно один раз объявить хранилище вместо передачи --store в каждой команде:

# openspec/config.yaml (the only file under openspec/)
store: team-context

Обычные команды автоматически выбирают объявленное хранилище; баннер корня и блок root в JSON сообщают source: "declared" и ID хранилища, а печатаемые подсказки по-прежнему содержат --store <id>. Объявление служит fallback, а не переопределением: явный --store всегда имеет приоритет, а каталог с настоящими папками планирования игнорирует указатель (с предупреждением). Чтобы превратить репозиторий-указатель в локальный корень OpenSpec, удалите строку store: и запустите openspec init — пока объявление присутствует, init не создаст каркас.

Глобальный вариант для всех репозиториев компьютера: openspec config set defaultStore <id> (см. раздел «Конфигурация»). Он используется, только если не удалось выбрать корень через --store, локальный корень или указатель проекта; в таком случае баннер корня и блок root JSON содержат source: "global_default".

Одна проверка в одном месте, только для чтения: исправен ли корень OpenSpec и доступны ли на этом компьютере связанные хранилища?

Окно терминала
openspec doctor [--store <id>] [--json]

В отчёте отдельно показаны состояние корня, метаданных хранилища (включая расхождение между сохранённым удалённым URL и origin рабочей копии, а также отставание рабочей копии от последней полученной upstream-ссылки) и ссылок (та же диагностика, что и в инструкциях, с командами клонирования для неразрешённых ссылок). При диагностике состояния любого уровня команда завершается с кодом 0 — agents анализируют массивы status; код 1 возвращается только при ошибках команды (нет корня, неизвестное хранилище). Doctor не клонирует, не синхронизирует и не исправляет данные. Чтобы получить сам собранный набор, а не его диагностику, используйте openspec context.

Всё, с чем связана работа согласно объявлениям OpenSpec, в одном рабочем наборе: корень OpenSpec и хранилища, на которые он ссылается.

Окно терминала
openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]

Краткий вывод JSON предназначен для agents (для каждого доступного хранилища указан способ получения данных; для неразрешённых элементов приведены те же команды исправления, что и в doctor). --code-workspace дополнительно создаёт файл рабочего пространства VS Code с корнем и доступными связанными хранилищами (каталоги ref:<id>). Это единственная операция записи команды; если файл уже существует, без --force она будет отклонена. Недоступные элементы указываются явно, а не угадываются.

«Рабочий контекст» — это собранный набор; поле context: в openspec/config.yaml — сведения о проекте, добавляемые в инструкции. Это разные понятия. Команда openspec doctor проверяет состояние набора, а openspec context показывает, из чего он состоит.

Бета-версия. Рабочие наборы — часть нового набора бета-функций; команды, флаги и форматы файлов могут меняться между выпусками. Пошаговое руководство см. в разделе Хранилища.

Рабочий набор — это личное именованное представление каталогов, которые вы открываете вместе (корень планирования и любые выбранные вами каталоги). Он хранится на вашем компьютере и повторно открывается по имени в инструменте. Набор полностью локален: не коммитится, не передаётся другим, не формируется из объявлений, а его удаление не затрагивает каталоги-участники.

Окно терминала
openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
openspec workset list [--json]
openspec workset open <name> [--tool <id>]
openspec workset remove <name> [--yes] [--json]

create запускает краткую пошаговую настройку (или принимает флаги --member в неинтерактивном режиме; первый участник считается основным — сеанс начинается в нём). open запускает выбранный инструмент: редакторы (VS Code, Cursor) открывают окно со всеми участниками и завершают работу; CLI agents (Claude Code, codex) занимают текущий терминал и запускают сеанс со всеми подключёнными участниками без предварительно заполненного prompt, завершаясь при выходе. Если при открытии каталог-участник отсутствует, он пропускается с сообщением; остальные каталоги открываются. Сохранённый выбор инструмента можно переопределить для конкретного открытия флагом --tool.

Поддержка нового инструмента настраивается, а не реализуется в коде. Каждый инструмент использует один из двух способов запуска: workspace-file (через созданный файл .code-workspace) или attach-dirs (флаг подключения для каждого участника). Ключ openers глобального config.json (откройте командой openspec config edit) позволяет добавлять инструменты или менять встроенные настройки по отдельным полям:

{
"openers": {
"zed": { "style": "workspace-file" },
"claude": { "attach_flag": "--dir" }
}
}

Состояние рабочих наборов хранится в worksets/ глобального каталога данных (сохранённые представления и сгенерированные файлы <name>.code-workspace, обновляемые при каждом открытии). Удаление этой папки полностью удаляет рабочие наборы.


Вывести список изменений или спецификаций проекта.

openspec list [options]

Параметры:

Параметр Описание
--specs Вывести спецификации вместо изменений
--changes Вывести список изменений (по умолчанию)
--sort <order> Сортировать по recent (по умолчанию) или name
--json Вывести результат в формате JSON

Примеры:

Окно терминала
# List all active changes
openspec list
# List all specs
openspec list --specs
# JSON output for scripts
openspec list --json

Вывод (текст):

Changes:
add-dark-mode No tasks just now

Показать интерактивный dashboard для просмотра спецификаций и изменений.

openspec view

Открывает интерфейс в терминале для навигации по спецификациям и изменениям проекта.


Показать подробную информацию об изменении или спецификации.

openspec show [item-name] [options]

Аргументы:

Аргумент Обязательный Описание
item-name Нет Имя изменения или спецификации (если не указано, команда спросит его)

Параметры:

Параметр Описание
--type <type> Указать тип: change или spec (определяется автоматически, если неоднозначности нет)
--json Вывести результат в формате JSON
--no-interactive Отключить prompts

Параметры для изменений:

Параметр Описание
--deltas-only Показать только дельта-спецификации (режим JSON)

Параметры для спецификаций:

Параметр Описание
--requirements Показать только требования без сценариев (режим JSON)
--no-scenarios Не включать содержимое сценариев (режим JSON)
-r, --requirement <id> Показать требование по индексу, начинающемуся с 1 (режим JSON)

Примеры:

Окно терминала
# Interactive selection
openspec show
# Show a specific change
openspec show add-dark-mode
# Show a specific spec
openspec show auth --type spec
# JSON output for parsing
openspec show add-dark-mode --json

Проверить изменения и спецификации на структурные ошибки, а требования MODIFIED в изменении — сравнить с основными спецификациями, которые они заменят.

openspec validate [item-name] [options]

Изменение без дельта-спецификаций не проходит проверку, если в его .openspec.yaml не задано skip_specs: true (для чистого рефакторинга, инструментов или документации — см. Рецепт 5).

Аргументы:

Аргумент Обязательный Описание
item-name Нет Объект для проверки (если не указано, команда спросит его)

Параметры:

Параметр Описание
--all Проверить все изменения и спецификации
--changes Проверить все изменения
--specs Проверить все спецификации
--archived Проверить, что все задачи архивированных изменений выполнены (для проверки перед коммитом)
--type <type> Указать тип, если имя неоднозначно: change или spec
--strict Включить строгий режим проверки
--json Вывести результат в формате JSON
--concurrency <n> Максимальное число параллельных проверок (по умолчанию: 6 или значение переменной OPENSPEC_CONCURRENCY)
--no-interactive Отключить prompts

Флаг --archived задаёт отдельную область проверки: он не проверяет дельта-спецификации (они уже применены при архивации), а убеждается, что в каждом изменении под changes/archive/ отмечены все флажки задач tasks.md. Если остались неотмеченные задачи, команда завершается с ненулевым кодом. Это позволяет обнаруживать изменения, архивированные до завершения работы; удобно использовать в pre-commit hook.

Примеры:

Окно терминала
# Interactive validation
openspec validate
# Validate a specific change
openspec validate add-dark-mode
# Validate all changes
openspec validate --changes
# Validate everything with JSON output (for CI/scripts)
openspec validate --all --json
# Strict validation with increased parallelism
openspec validate --all --strict --concurrency 12
# Fail if any archived change still has unchecked tasks
openspec validate --archived

Вывод (текст):

Validating add-dark-mode...
✓ proposal.md valid
✓ specs/ui/spec.md valid
⚠ design.md: missing "Technical Approach" section
1 warning found

Вывод (JSON):

{
"version": "1.0.0",
"results": {
"changes": [
{
"name": "add-dark-mode",
"valid": true,
"warnings": ["design.md: missing 'Technical Approach' section"]
}
]
},
"summary": {
"total": 1,
"valid": 1,
"invalid": 0
}
}

Архивировать завершённое изменение и объединить дельта-спецификации с основными.

openspec archive [change-name] [options]

Аргументы:

Аргумент Обязательный Описание
change-name Нет Изменение для архивации (если не указано, команда спросит его; обязательно, если на prompt некому ответить)

Параметры:

Параметр Описание
-y, --yes Пропустить prompts подтверждения. Обязательно, если на них некому ответить — например, при запуске через AI agent, заданием CI или с закрытым stdin
--skip-specs Пропустить обновление спецификаций при одной архивации. Если изменение никогда не будет содержать дельта-спецификации, вместо этого задайте skip_specs: true в его .openspec.yaml — тогда для архивации флаг не нужен
--no-validate Пропустить проверку (требуется подтверждение). Также отключает вывод возможностей из эксплуатации: без результата проверки ничего не удаляется

Примеры:

Окно терминала
# Interactive archive (asks which change, then confirms)
openspec archive
# Archive specific change
openspec archive add-dark-mode
# Archive without prompts (agents, CI, scripts)
openspec archive add-dark-mode --yes
# Archive a tooling change that doesn't affect specs
openspec archive update-ci-config --skip-specs

Вывод возможности из эксплуатации: добавьте маркер в метаданные изменения:

openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

Затем архивируйте изменение обычным способом:

Окно терминала
openspec archive retire-legacy --yes

Храните собственные метаданные: ключ верхнего уровня, который начинается со строчной x-, принадлежит вам. OpenSpec никогда не читает, не записывает и не сообщает о нём, поэтому openspec validate --strict остаётся успешным для изменения, в котором есть данные конкретного инструмента:

openspec/changes/add-dark-mode/.openspec.yaml
schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1

Имя после префикса вы выбираете сами, в любом регистре и написании, при условии что оно не пустое и не содержит пробелов. Есть два ограничения: сам префикс должен быть в нижнем регистре, поэтому X-Tracker по-прежнему будет отмечен, а расширения допускаются только на верхнем уровне: ключ внутри initiative: отклоняется независимо от имени. Любой другой неизвестный ключ верхнего уровня по-прежнему отмечается как не имеющий эффекта.

Если изменение удаляет последнее требование возможности, OpenSpec удаляет её текущий spec.md. Дельты остальных возможностей в том же изменении по-прежнему обновляют их основные спецификации. Без маркера архивация останавливается до изменения каких-либо файлов и предлагает добавить его.

Что делает команда:

  1. Проверяет изменение (если не указан --no-validate).
  2. Запрашивает подтверждение (если не указан --yes).
  3. Резервирует место для архива до изменения основных спецификаций.
  4. Проверяет и объединяет активные дельта-спецификации с openspec/specs/. Возможность, последнее требование которой удалено, выводится из эксплуатации и её файл спецификации удаляется, только если в .openspec.yaml изменения рядом с schema: задано retire_capabilities: true.
  5. Перемещает папку изменения в openspec/changes/archive/YYYY-MM-DD-<name>/.
  6. Если изменение спецификаций или окончательное перемещение завершается ошибкой до создания полного архива, восстанавливает спецификации, а изменение оставляет или возвращает на прежний активный путь.
  7. Если резервная копия успешно проверена, но не удалось удалить промежуточный исходный каталог, полный архив и зафиксированное состояние спецификаций сохраняются для восстановления.

Если терминал недоступен: AI agent, задание CI или любой процесс с закрытым stdin не сможет ответить на шаг 2, поэтому archive остановится, не изменив ничего, завершится с кодом 1 и укажет команду для повторного запуска — openspec archive <name> --yes со всеми остальными переданными флагами. Заранее укажите --yes и имя изменения, чтобы пропустить повторный запуск.


Эти команды поддерживают рабочий процесс OPSX на основе артефактов. Они полезны как пользователям для проверки хода работы, так и agents для определения следующих шагов.

Создать каталог изменения и при необходимости зафиксировать его метаданные в выбранном корне OpenSpec.

Окно терминала
openspec new change <name> [options]

Имена изменений должны быть в нижнем регистре и формате kebab-case: строчные буквы, цифры и одиночные дефисы. Пробелы, подчёркивания, заглавные буквы, несколько дефисов подряд, а также дефисы в начале или конце не допускаются. Имя может начинаться с цифры — например, можно пронумеровать изменения: 100-add-feature или 00001-add-auth.

Параметры:

Параметр Описание
--description <text> Описание для добавления в README.md
--goal <text> Необязательные метаданные цели изменения
--schema <name> Используемая схема рабочего процесса
--store <id> ID хранилища, используемого как корень OpenSpec (хранилище — зарегистрированный отдельный репозиторий OpenSpec)
--json Вывод в формате JSON

Примеры:

Окно терминала
openspec new change add-billing-api
openspec new change add-billing-api --store team-context --json

Показать состояние создания артефактов изменения.

openspec status [options]

Параметры:

Параметр Описание
--change <id> Имя изменения (если не указано, команда спросит его)
--schema <name> Переопределить схему (по умолчанию определяется по конфигурации изменения)
--json Вывод в формате JSON

Примеры:

Окно терминала
# Interactive status check
openspec status
# Status for specific change
openspec status --change add-dark-mode
# JSON for agent use
openspec status --change add-dark-mode --json

Вывод (текст):

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete
[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

У изменения с skip_specs: true этап спецификаций отображается как [~] specs (skipped: change declares skip_specs) и не учитывается в прогрессе.

Вывод (JSON):

{
"changeName": "add-dark-mode",
"schemaName": "spec-driven",
"isPlanningComplete": false,
"isComplete": false,
"applyRequires": ["tasks"],
"artifacts": [
{"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
{"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
{"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
{"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "requires": ["specs", "design"], "missingDeps": ["design"]}
]
}

isPlanningComplete показывает, существуют ли все артефакты планирования, кроме пропущенных; пропущенные артефакты считаются выполненными, хотя не создаются. Это поле не отражает завершённость задач реализации. isComplete сохранён как совместимый псевдоним с тем же значением.

Артефакты перечислены в порядке зависимостей: зависимость никогда не следует после требующего её артефакта. Артефакты, одновременно становящиеся готовыми (в spec-driven для specs и design требуется только proposal), сохраняют порядок объявления в схеме, а не сортируются по алфавиту. Поэтому первым нужно создать артефакт со статусом ready.


Получить подробные инструкции по созданию артефакта или выполнению задач. Команда нужна AI agents, чтобы определить, что делать дальше.

openspec instructions [artifact] [options]

Аргументы:

Аргумент Обязательный Описание
artifact Нет ID артефакта или интерфейс ввода рабочего процесса: apply либо archive

Параметры:

Параметр Описание
--change <id> Имя изменения (обязательно в неинтерактивном режиме)
--schema <name> Переопределить схему
--json Вывод в формате JSON

Особые случаи: используйте apply, чтобы получить инструкции по реализации задач. Используйте archive, чтобы получить актуальные входные данные архивации (context и operationGuidance) в режиме только для чтения для корректного изменения; команда ничего не архивирует и не меняет.

Примеры:

Окно терминала
# Get instructions for next artifact
openspec instructions --change add-dark-mode
# Get specific artifact instructions
openspec instructions design --change add-dark-mode
# Get apply/implementation instructions
openspec instructions apply --change add-dark-mode
# Get current archive operation inputs without archiving
openspec instructions archive --change add-dark-mode --json
# JSON for agent consumption
openspec instructions design --change add-dark-mode --json

Вывод содержит:

  • содержимое шаблона артефакта;
  • контекст проекта из конфигурации;
  • содержимое артефактов-зависимостей;
  • правила конфигурации для этого артефакта;
  • актуальный контекст проекта и соответствующие рекомендации для apply/archive.

При каждом вызове входные данные операций читаются из выбранного корня репозитория или хранилища. Контекст проекта — обязательный ввод для prompt: agents читают его и учитывают релевантные сведения, соглашения и ограничения проекта. Рекомендации для операций — необязательные дополнительные советы: agent рассматривает каждый пункт и следует только тем, которые уместны и совместимы со встроенным процессом. Оба поля отделены от явного выбора пользователя, состояния CLI, встроенных инструкций и правил артефактов. О конфликте контекста сообщается; конфликтующие или неприменимые рекомендации не выполняются, а причина объясняется. Это контракты поведения сгенерированных agents, а не проверяемые ограничения CLI. instructions archive возвращает только выбранное изменение, необязательные входные поля и метаданные корня; статический процесс архивации не включается.

Если артефакт пропущен из-за skip_specs: true, вывод содержит только предупреждение (в JSON добавляются поля skipped/warning); создавать артефакт нельзя.


Показать разрешённые пути шаблонов для всех артефактов схемы.

openspec templates [options]

Параметры:

Параметр Описание
--schema <name> Схема для просмотра (по умолчанию: spec-driven)
--json Вывод в формате JSON

Примеры:

Окно терминала
# Show template paths for default schema
openspec templates
# Show templates for custom schema
openspec templates --schema my-workflow
# JSON for programmatic use
openspec templates --json

Вывод (текст):

Schema: spec-driven
Templates:
proposal → ~/.openspec/schemas/spec-driven/templates/proposal.md
specs → ~/.openspec/schemas/spec-driven/templates/specs.md
design → ~/.openspec/schemas/spec-driven/templates/design.md
tasks → ~/.openspec/schemas/spec-driven/templates/tasks.md

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

openspec schemas [options]

Параметры:

Параметр Описание
--json Вывод в формате JSON
--store <id> Использовать зарегистрированное хранилище как корень OpenSpec

Пример:

Окно терминала
openspec schemas

Вывод:

Available schemas:
spec-driven (package)
The default spec-driven development workflow
Flow: proposal → specs → design → tasks
my-custom (project)
Custom workflow for this project
Flow: research → proposal → tasks

Команды для создания и управления схемами пользовательских рабочих процессов.

Создать новую схему в проекте.

openspec schema init <name> [options]

Аргументы:

Аргумент Обязательный Описание
name Да Имя схемы (kebab-case)

Параметры:

Параметр Описание
--description <text> Описание схемы
--artifacts <list> ID артефактов через запятую (по умолчанию: proposal,specs,design,tasks)
--default Установить схему по умолчанию для проекта
--no-default Не предлагать сделать схему схемой по умолчанию
--force Перезаписать существующую схему
--json Вывод в формате JSON

Примеры:

Окно терминала
# Interactive schema creation
openspec schema init research-first
# Non-interactive with specific artifacts
openspec schema init rapid \
--description "Rapid iteration workflow" \
--artifacts "proposal,tasks" \
--default

Что создаётся:

openspec/schemas/<name>/
├── schema.yaml # Schema definition
└── templates/
├── proposal.md # Template for each artifact
├── specs.md
├── design.md
└── tasks.md

Скопировать существующую схему в проект для настройки.

openspec schema fork <source> [name] [options]

Аргументы:

Аргумент Обязательный Описание
source Да Копируемая схема
name Нет Имя новой схемы (по умолчанию: <source>-custom)

Параметры:

Параметр Описание
--force Перезаписать существующий каталог назначения
--json Вывод в формате JSON

Пример:

Окно терминала
# Fork the built-in spec-driven schema
openspec schema fork spec-driven my-workflow

Проверить структуру схемы и её шаблоны.

openspec schema validate [name] [options]

Аргументы:

Аргумент Обязательный Описание
name Нет Схема для проверки (если не указана, проверяются все)

Параметры:

Параметр Описание
--verbose Показать подробные этапы проверки
--json Вывод в формате JSON

Пример:

Окно терминала
# Validate a specific schema
openspec schema validate my-workflow
# Validate all schemas
openspec schema validate

Показать источник загрузки схемы (полезно для отладки приоритета).

openspec schema which [name] [options]

Аргументы:

Аргумент Обязательный Описание
name Нет Имя схемы

Параметры:

Параметр Описание
--all Вывести все схемы с указанием источников
--json Вывод в формате JSON

Пример:

Окно терминала
# Check where a schema comes from
openspec schema which spec-driven

Вывод:

spec-driven resolves from: package
Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Приоритет источников схемы:

  1. Проект: openspec/schemas/<name>/
  2. Пользователь: ~/.local/share/openspec/schemas/<name>/
  3. Пакет: встроенные схемы

Просмотреть и изменить глобальную конфигурацию OpenSpec.

openspec config <subcommand> [options]

Подкоманды:

Подкоманда Описание
path Показать расположение файла конфигурации
list Показать все текущие настройки
get <key> Получить указанное значение
set <key> <value> Задать значение
unset <key> Удалить ключ
reset Сбросить настройки до значений по умолчанию
edit Открыть файл в $EDITOR
profile [preset] Настроить profile рабочего процесса интерактивно или с помощью предустановки

Примеры:

Окно терминала
# Show config file path
openspec config path
# List all settings
openspec config list
# Get a specific value
openspec config get telemetry.enabled
# Set a value (disable anonymous usage telemetry)
openspec config set telemetry.enabled false
# Set a string value explicitly
openspec config set user.name "My Name" --string
# Remove a custom setting
openspec config unset user.name
# Set a machine-level default store (fallback root when no --store,
# local root, or project store: pointer resolves)
openspec config set defaultStore team-plans
# Reset all configuration
openspec config reset --all --yes
# Edit config in your editor
openspec config edit
# Configure profile with action-based wizard
openspec config profile
# Fast preset: switch workflows to core (keeps delivery mode)
openspec config profile core

Отключение телеметрии: если telemetry.enabled не задан, телеметрия включена по умолчанию (модель отказа). Задайте false, чтобы отключить анонимную статистику использования и проверку версии в openspec update. Переменные среды имеют приоритет над конфигурацией: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1 и любое истинное значение CI (например, true, 1 или yes) отключают телеметрию независимо от конфигурации.

openspec config profile сначала показывает сводку текущих настроек, а затем предлагает выбрать:

  • изменить способ установки и рабочие процессы;
  • изменить только способ установки;
  • изменить только рабочие процессы;
  • сохранить текущие настройки и выйти.

Если оставить текущие настройки, изменения не записываются и prompt на обновление не появляется. Если конфигурация не меняется, но файлы текущего проекта не соответствуют глобальному profile или способу установки, OpenSpec выдаст предупреждение и предложит запустить openspec update. Нажатие Ctrl+C корректно отменяет процесс (без трассировки стека); код завершения — 130. В контрольном списке рабочих процессов [x] означает, что процесс выбран в глобальной конфигурации. Чтобы применить выбор к файлам проекта, выполните openspec update или выберите Apply changes to this project now?, когда команда предложит это в каталоге проекта.

Интерактивные примеры:

Окно терминала
# Delivery-only update
openspec config profile
# choose: Change delivery only
# choose delivery: Skills only
# Workflows-only update
openspec config profile
# choose: Change workflows only
# toggle workflows in the checklist, then confirm

Отправить отзыв об OpenSpec. Команда создаёт issue на GitHub.

openspec feedback <message> [options]

Аргументы:

Аргумент Обязательный Описание
message Да Краткое содержание отзыва; длинный текст сокращается в заголовке issue и полностью сохраняется в тексте

Параметры:

Параметр Описание
--body <text> Дополнительные сведения после краткого описания

Требования: GitHub CLI (gh) должен быть установлен, пользователь должен пройти аутентификацию.

Пример:

Окно терминала
openspec feedback "Add support for custom artifact types" \
--body "I'd like to define my own artifact types beyond the built-in ones."

Управлять автодополнением командной оболочки для CLI OpenSpec.

openspec completion <subcommand> [shell]

Подкоманды:

Подкоманда Описание
generate [shell] Вывести сценарий автодополнения в stdout
install [shell] Установить автодополнение для оболочки
uninstall [shell] Удалить установленное автодополнение

Поддерживаемые оболочки: bash, zsh, fish, powershell

Примеры:

Окно терминала
# Install completions (auto-detects shell)
openspec completion install
# Install for specific shell
openspec completion install zsh
# Generate script for manual installation (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec
# Uninstall
openspec completion uninstall

Windows (PowerShell): установить автодополнение для текущего хоста PowerShell:

Окно терминала
$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE сообщает OpenSpec, какой profile настроить в этом сеансе. Установщик создаёт отсутствующие каталоги profile и добавляет управляемый блок для загрузки OpenSpecCompletion.ps1. Перезагрузите profile, чтобы сразу включить автодополнение.

Чтобы удалить автодополнение для текущего хоста, выполните:

Окно терминала
$env:PROFILE = $PROFILE
openspec completion uninstall powershell

После удаления перезапустите PowerShell, чтобы очистить автодополнение текущего сеанса.

Автодополнение — opt-in. CLI один раз, в stderr, сообщает о нём при первом запуске команды в интерактивном терминале и больше не повторяет подсказку. Если автодополнение уже установлено, сообщение не выводится. Задайте OPENSPEC_NO_COMPLETIONS=1, чтобы полностью отключить эту подсказку.


Код Значение
0 Успех
1 Ошибка (не пройдена проверка, отсутствуют файлы и т. п.)

Переменная Описание
OPENSPEC_TELEMETRY Задайте 0, чтобы отключить телеметрию и проверку версии в openspec update (переопределяет telemetry.enabled в глобальной конфигурации)
DO_NOT_TRACK Задайте 1, чтобы отключить телеметрию и проверку версии в openspec update (стандартный сигнал DNT; переопределяет конфигурацию)
OPENSPEC_CONCURRENCY Стандартный уровень параллелизма пакетной проверки (по умолчанию: 6)
EDITOR или VISUAL Редактор для openspec config edit
NO_COLOR Отключить цветной вывод, если задана
OPENSPEC_NO_ANIMATION Отключить анимацию приветствия openspec init, если задана
OPENSPEC_NO_COMPLETIONS Задайте 1, чтобы отключить однократную подсказку об автодополнении
OPENSPEC_NO_UPDATE_CHECK Отключить проверку наличия более новой версии CLI в openspec update (любое значение, включая пустое). Проверка также пропускается, если задана CI (кроме false/0/no/off) или NODE_ENV=test
npm_config_registry Реестр для проверки версии в openspec update. Должен быть URL http(s); иначе используется https://registry.npmjs.org. Файл .npmrc не читается

HagiCode

HagiCode — агентная среда разработки. Насыщенные и удобные взаимодействия с интерфейсом делают планирование, работу агентов и проектные задачи понятными и доступными, превращая разработку в увлекательный процесс.

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

Перейти на HagiCodeЧитать документацию
  • УмныйРабочие процессы OpenSpec превращают намерение в исполнимый путь от предложения через дизайн и задачи до готового изменения.
  • ЭффективныйМультиагентное выполнение параллельно продвигает исследование, реализацию и проверку в нескольких репозиториях и с привычными Agent CLI.
  • ИнтересныйНасыщенные и удобные взаимодействия с интерфейсом делают планирование, работу агентов и проектные задачи понятными и доступными.

Скачать для Windows

Получить в Microsoft StoreВсе загрузки

Превращайте идеи в готовое ПО.

HagiCode — агентная среда разработки: рабочие процессы OpenSpec планируют изменение, мультиагентное выполнение его реализует, а Hero Scenario делает долгий путь наглядным, так что идеи становятся готовым ПО.

Умный
Рабочие процессы OpenSpec превращают намерение в путь от предложения до готового изменения.
Эффективный
Мультиагентное выполнение ведёт исследование, реализацию и проверку параллельно.
Увлекательный
Удобный интерфейс упрощает планирование, работу агентов и проектные задачи.