Урок 15.6. Справочник CLI openspec

Зачем это нужно

В уроке 15.4 было показано, что у OpenSpec две половины: слэш-команды /opsx:*, которые coding-агент выполняет в чате, и терминальный CLI openspec. Урок 15.5 - справочник по первой половине, этот урок - справочник по второй. Вместе они закрывают весь командный интерфейс, набросанный обзорно еще в уроке 2.10.

CLI нужен вам, даже если всю работу делает агент. Установка и обновление (init, update), проверка артефактов перед коммитом (validate), разбор состояния изменения (status), архивация из скрипта CI (archive --yes), конфигурация и диагностика (config, doctor) - все это терминальные команды. Кроме того, слэш-команды /opsx:* под капотом опираются именно на CLI: понимая его поверхность, вы понимаете, что агент делает с репозиторием. Это справочный урок: читать подряд не обязательно - удобно возвращаться к конкретной команде; полный набор флагов любой команды выводит openspec <command> --help.

Основная идея

CLI openspec обслуживает все, что происходит вокруг жизненного цикла изменения: настройку проекта, просмотр и валидацию артефактов, архивацию, схемы workflow, конфигурацию и работу со Store. Сама работа над изменением - explore, proposal, apply - идет в чате агента, но ее результат, каталоги и Markdown-файлы, обслуживается терминалом.

Через весь справочник проходят два принципа: большинство команд ориентированы на человека, но многие поддерживают --json для агентов и скриптов (несколько команд интерактивные и работают только в терминале); а команды, работающие с изменениями и спецификациями, действуют в корне OpenSpec - флаг --store <id> направляет тот же набор команд в зарегистрированный Store (урок 15.12).

Сводная таблица команд

Команды для человека и для агентов

Большинство команд спроектированы для человека в терминале, но шесть из них интерактивны и для скриптов не предназначены: openspec init (вопросы мастера), openspec view (дашборд), openspec workset open <name> (окно редактора или сессия терминального агента), openspec config edit (конфигурация в $EDITOR), openspec feedback (фидбэк через GitHub) и openspec completion install (автодополнение shell).

Остальные команды допускают программное использование через --json. Ключевые сценарии: openspec list --json, openspec show <item> --json, openspec validate --all --json (массовая проверка), openspec status --json, openspec instructions ... --json, openspec templates --json, openspec schemas --json (плюс --store <id> для выбора корня), все подкоманды store и workset (для store remove и workset remove в неинтерактивном режиме обязателен --yes), а также openspec new change <id> --json с --store <id>. Именно эти поверхности читают слэш-команды /opsx:* и скрипты CI.

Установка проекта: openspec init

Инициализирует OpenSpec в проекте: создает структуру каталогов и настраивает интеграции AI-инструментов. Значения по умолчанию берутся из глобальной конфигурации: профиль core, delivery both, workflows propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Аргумент path необязателен - по умолчанию текущий каталог.

Нюансы из оригинала:

• --profile custom использует workflows, выбранные на текущий момент в глобальной конфигурации (openspec config profile).
• Для существующего проекта языковую инструкцию добавляйте правкой поля context в конфигурации - тогда OpenSpec не перезапишет проектные указания.
• Анимация также отключается переменной OPENSPEC_NO_ANIMATION (любое значение, включая пустое), непустым NO_COLOR или системной настройкой «уменьшить движение» (Reduce Motion в macOS, отключенные анимации в GNOME).
• Список id инструментов в --tools большой - например, claude, cursor, codex, github-copilot, gemini, opencode, qwen; windsurf принимается как алиас devin. Полный список выводит openspec init --help.

# Интерактивная инициализация
openspec init

# Без интерактива: все поддерживаемые инструменты
openspec init --tools all

Что создает команда (для выбранных инструментов аналогично создаются их каталоги - .cursor/commands/ для OPSX-команд, .agents/skills/ для совместимых с AGENTS.md, и другие):

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)

Обновление файлов: openspec update

Перегенерирует файлы инструкций AI-инструментов после обновления CLI - по текущему глобальному профилю, выбранным workflows и режиму delivery.

openspec update [path] [options]

Единственная опция - --force: обновить файлы, даже если они считаются актуальными.

# Сначала обновите пакет, затем файлы в проекте
npm install -g @fission-ai/openspec@latest
openspec update

Важное предупреждение оригинала: файлы инструкций генерирует установленный CLI. Если запустить openspec update на устаревшей установке, он сообщит, что «все актуально», - и новые workflows из свежих релизов не появятся. Поэтому сначала обновляется пакет, потом запускается update.

openspec update умеет проверить это за вас: он спрашивает npm-registry, не опубликована ли более новая версия, и в интерактивном терминале предлагает обновиться (например: A newer OpenSpec CLI is available (v1.6.0 → v1.7.0). ? Upgrade to v1.7.0 now? (Y/n), с указанием каталога, откуда запущен CLI).

При согласии команда сама выполнит npm install -g @fission-ai/openspec@latest и перезапустит update уже новой версией; успех подтверждается опросом версии установленного бинарника, а не кодом выхода npm - если в PATH отвечает другая копия, OpenSpec сообщит об этом, а не будет заявлять успех. При отказе печатается команда, и update выполняется текущей версией. Ctrl-C останавливает команду.

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

Проверка версии использует registry из npm_config_registry (если npm его экспортирует) или https://registry.npmjs.org; файлы .npmrc не читаются. На приватном зеркале экспортируйте npm_config_registry или отключите проверку переменной OPENSPEC_NO_UPDATE_CHECK. Проверка не тормозит команду дольше 1,5 секунд и молчит при недоступном registry.

Как решается «актуальность»: файлы skills записывают версию, которая их сгенерировала, - OpenSpec сравнивает ее с версией CLI. Файлы команд не несут штампа версии, поэтому для инструментов с delivery commands содержимое сравнивается с тем, что было бы сгенерировано сейчас, - ручные правки считаются drift и перезаписываются. При delivery skills или both проверяется только записанная версия: hand-edited файл с совпадающей версией не трогается; переписать его принудительно можно --force. Вывод оригинала стоит запомнить: сгенерированные файлы принадлежат OpenSpec - свои инструкции держите отдельно.

Store: openspec store (beta)

Beta. Store и построенные на них функции (references, working context, worksets) - новая поверхность: имена команд, флаги, форматы файлов и JSON-вывод могут меняться между релизами.

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

store setup

Создает и регистрирует локальный Store. Без аргументов в терминале ведет интерактивное сопровождение; агентам и скриптам следует передавать явные входные данные и --json.

openspec store setup [id] [options]

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

openspec store setup
openspec store setup team-context --path ~/openspec/team-context --no-init-git --json

store register

Регистрирует существующий локальный каталог как Store.

openspec store register [path] [options]

Нюансы беты: корень можно зарегистрировать до появления изменений, примененных спецификаций или архива - каталоги openspec/changes/, openspec/specs/ и openspec/changes/archive/ могут отсутствовать, пока обычные команды их не создадут. Репозиторий-«указатель» с полем store: <id> сам Store не становится и не регистрируется, пока указатель не убран.

store unregister

Забывает локальную регистрацию Store, не удаляя файлы. Используйте, когда Store переехал, склонирован в другое место или больше не должен показываться на этой машине.

openspec store unregister <id> [--json]

store remove

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

openspec store remove <id> [--yes] [--json]

store list

Список локально зарегистрированных Store (алиас команды - openspec store ls).

openspec store list [--json]

store doctor

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

openspec store doctor [id] [--json]

Ссылки на Store из проекта

Проект может объявить, на какие Store опирается его работа, в openspec/config.yaml:

schema: spec-driven
references:
  - team-context

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

References - контекст только для чтения. Они не меняют место работы команд: работа остается в собственном корне репозитория, а запись в Store - всегда явное действие с --store. Неразрешимая ссылка (например, Store не зарегистрирован на машине) деградирует в предупреждение с точным исправлением, и instructions все равно генерируются. Сводное здоровье ссылок показывает openspec doctor.

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

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

Remote попадает в .openspec-store/store.yaml внутри начального коммита при создании через --remote; для существующего Store отредактируйте store.yaml вручную и закоммитьте. Запись remote - не синхронизация: OpenSpec никогда сам не выполняет clone, pull или push.

Store по умолчанию

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

# openspec/config.yaml (единственный файл под openspec/)
store: team-context

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

Машинный вариант покрывает все репозитории сразу: openspec config set defaultStore <id>. Он консультируется последним - после --store, локального корня и проектного указателя; в баннере и JSON это source: "global_default".

Диагностика связей: openspec doctor

Один вопрос в одном месте: здоров ли корень OpenSpec и доступны ли на этой машине Store, на которые он ссылается.

openspec doctor [--store <id>] [--json]

Отчет разделяет здоровье корня, здоровье метаданных Store (включая расхождение записанного remote с наблюдаемым origin чекаута и отставание чекаута от последнего fetch) и здоровье ссылок (те же диагностики, что в instructions, с clone-исправлениями для неразрешимых ссылок). Находки любой серьезности дают exit code 0 - агенты читают массивы status; только ошибки самой команды (нет корня, неизвестный Store) дают 1. Doctor никогда не клонирует, не синхронизирует и не чинит. Чтобы получить сам собранный набор, а не его здоровье, используйте openspec context.

Рабочий контекст: openspec context

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

openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]

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

Не путайте: «рабочий контекст» - это собранный набор, а поле context: в openspec/config.yaml - проектный фон, injected в instructions. Первое отвечает на вопрос «что входит в набор» (openspec context), второе - «какой у проекта контекст», а здоров ли набор - openspec doctor.

Персональные worksets (beta)

Beta. Worksets - часть новой бета-поверхности: команды, флаги и форматы файлов могут меняться между релизами.

Workset - персональный именованный набор каталогов, с которыми вы работаете вместе: корень планирования плюс любые другие каталоги по вашему выбору. Он чисто локальный: не коммитится, не шарится, не выводится из объявлений; удаление workset никогда не трогает каталоги-участники.

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-агенты (Claude Code, codex) забирают этот терминал в сессию со всеми участниками и без предзаполненного промпта, завершаясь при вашем выходе. Отсутствующий в момент открытия каталог пропускается с пометкой - остальное открывается. Сохраненный инструмент можно переопределить на одно открытие флагом --tool.

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

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

Все состояние worksets лежит в папке worksets/ глобального каталога данных (сохраненные наборы плюс генерируемые <name>.code-workspace, перегенерируемые при каждом открытии); удаление папки стирает все следы.

Просмотр: list, view и show

openspec list

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

openspec list [options]

Пример текстового вывода (No tasks - в изменении еще нет чек-листа задач):

Changes:
  add-dark-mode     No tasks      just now

openspec view

Интерактивный дашборд для навигации по спецификациям и изменениям проекта. Команда без опций, только для терминала:

openspec view

openspec show

Подробности одного изменения или спецификации.

openspec show [item-name] [options]

Аргумент item-name необязателен - при отсутствии команда предложит выбор.

Для изменений есть --deltas-only - показать только дельта-спецификации (режим JSON). Для спецификаций в JSON-режиме: --requirements (только требования, без сценариев), --no-scenarios (исключить содержимое сценариев), -r, --requirement <id> - конкретное требование по индексу с единицы.

openspec show add-dark-mode
openspec show auth --type spec

Валидация: openspec validate

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

openspec validate [item-name] [options]

Изменение без единой дельта-спецификации не проходит валидацию, если в его .openspec.yaml не объявлено skip_specs: true - этот флаг для чистых рефакторингов, тулинга и работы с документацией.

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

openspec validate add-dark-mode
openspec validate --all --json
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-режим (--all --json - типовой вариант для CI) возвращает те же результаты структурно: по каждому элементу поля valid и warnings, плюс блок summary с числом валидных и невалидных.

Архивация: openspec archive

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

openspec archive [change-name] [options]

Аргумент change-name необязателен в интерактивном режиме; без терминала имя обязательно.

# Конкретное изменение
openspec archive add-dark-mode

# Без вопросов (агенты, CI, скрипты)
openspec archive add-dark-mode --yes

Что делает команда, по шагам оригинала:

1. Валидирует изменение (если нет --no-validate).
2. Спрашивает подтверждение (если нет --yes).
3. Занимает место в архиве до изменения основных спецификаций.
4. Валидирует и вливает активные дельта-спецификации в openspec/specs/; папка изменения переносится в openspec/changes/archive/YYYY-MM-DD-<name>/.
5. Если мутация спецификации или финальный перенос падают до полного закрепления архива - восстанавливает спецификации и оставляет (или возвращает) изменение по активному пути.

Отдельный случай - retirement возможности (capability). Добавьте маркер в метаданные изменения:

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

и архивируйте как обычно - openspec archive retire-legacy --yes.

Когда изменение удаляет последнее требование возможности, OpenSpec удаляет ее живой spec.md; остальные дельты того же изменения обновляют свои основные спецификации как обычно. Без маркера archive останавливается до изменения любых файлов и просит его добавить.

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

Workflow-команды

Команды этого раздела поддерживают артефакт-ориентированный workflow OPSX; они полезны и человеку (проверить прогресс), и агенту (понять следующий шаг). Архитектура этой связки разобрана в уроке 15.14.

openspec new change

Создает каталог изменения и необязательные метаданные в разрешенном корне OpenSpec. Имена изменений - только lowercase kebab-case: строчные буквы, цифры и одинарные дефисы. Запрещены пробелы, подчеркивания, заглавные буквы, подряд идущие дефисы, дефисы в начале и в конце. Начальная цифра разрешена - можно упорядочивать изменения префиксами: 100-add-feature, 00001-add-auth.

openspec new change <name> [options]

openspec new change add-billing-api
openspec new change add-billing-api --store team-context --json

openspec status

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

openspec status [options]

openspec status --change add-dark-mode
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 как [~] specs (skipped: change declares skip_specs) и исключает его из счета прогресса. В JSON-режиме команда возвращает те же данные структурно: changeName, schemaName, флаги isPlanningComplete и isComplete, список требований к apply (applyRequires) и массив artifacts с id, путем вывода, статусом и зависимостями каждого артефакта.

isPlanningComplete сообщает, существуют ли все непропущенные planning-артефакты; пропущенные считаются выполненными без создания. Реализованы ли задачи кода, поле не отражает. isComplete - совместимый алиас с тем же значением. Артефакты перечислены в порядке зависимостей - зависимость никогда не идет после того, кто ее требует, - а одновременно готовые становятся в порядке схемы, не по алфавиту. Поэтому первый элемент со статусом ready - артефакт, который писать следующим.

openspec instructions

Выдает обогащенные инструкции для создания артефакта или применения задач; основная команда, которой пользуются AI-агенты. Аргумент artifact - id артефакта либо поверхность workflow: apply или archive.

openspec instructions [artifact] [options]

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

openspec instructions design --change add-dark-mode
openspec instructions apply --change add-dark-mode

Вывод включает содержимое шаблона артефакта, контекст проекта из конфигурации, содержимое артефактов-зависимостей, правила артефакта из конфигурации, а для apply/archive - контекст проекта и подходящее operation guidance. Входные данные перечитываются из репозитория или Store при каждом вызове. Проектный контекст - обязательный вход (агент применяет уместные факты и ограничения), operation guidance - необязательный совет (выполняются только применимые записи, конфликтующий контекст репортится). Это поведенческие контракты для агентов, а не принудительные проверки CLI - их архитектура разобрана в уроке 15.14. Для артефакта, пропущенного через skip_specs: true, выводится только предупреждение (JSON добавляет поля skipped/warning) - артефакт создавать нельзя.

openspec templates

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

openspec templates [options]

openspec templates --schema my-workflow

Для каждой схемы выводятся разрешенные пути к шаблонам артефактов, например ~/.openspec/schemas/spec-driven/templates/proposal.md.

openspec schemas

Список доступных схем workflow с описаниями и потоками артефактов.

openspec schemas [options]

openspec schemas

Текстовый вывод перечисляет схемы с источником (package или project), описанием и потоком артефактов:

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

Управление схемами: openspec schema

Команды для создания и настройки собственных схем workflow. Зачем нужны кастомные схемы и как их проектировать - в уроке 15.13.

schema init

Создает новую схему в проекте; аргумент name обязателен, kebab-case.

openspec schema init <name> [options]

openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

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

openspec/schemas/<name>/
├── schema.yaml           # Schema definition
└── templates/            # A template for each artifact

schema fork

Копирует существующую схему в проект для кастомизации.

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

Имя новой схемы необязательно - по умолчанию <source>-custom. Опции: --force (перезаписать существующее место назначения) и --json.

openspec schema fork spec-driven my-workflow

schema validate

Валидирует структуру схемы и ее шаблоны.

openspec schema validate [name] [options]

Без имени проверяет все схемы. Опции: --verbose (подробные шаги валидации) и --json.

openspec schema validate my-workflow

schema which

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

openspec schema which [name] [options]

Опция --all перечисляет все схемы с их источниками, --json структурирует вывод. Например, spec-driven разрешается из пакета: .../node_modules/@fission-ai/openspec/schemas/spec-driven.

Приоритет схем:

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

Конфигурация: openspec config

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

openspec config <subcommand> [options]

# Отключить анонимную телеметрию использования
openspec config set telemetry.enabled false

# Store по умолчанию на уровне машины (fallback-корень, когда ни --store,
# локальный корень, ни проектный указатель store: не разрешились)
openspec config set defaultStore team-plans

# Сброс всей конфигурации
openspec config reset --all --yes

# Мастер настройки профиля и быстрый пресет core (режим delivery сохранится)
openspec config profile
openspec config profile core

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

openspec config profile начинает с сводки текущего состояния, затем предлагает выбор: поменять delivery + workflows, только delivery, только workflows или оставить как есть. При «оставить» ничего не пишется и предложение update не показывается; если конфиг не менялся, но файлы проекта рассинхронизированы с глобальным профилем, выводится предупреждение и подсказка openspec update. Ctrl+C чисто отменяет мастер (без stack trace) с кодом выхода 130. В чек-листе workflows отметка [x] означает выбор в глобальной конфигурации; чтобы применить выбор к файлам проекта, выполните openspec update или согласитесь на применение прямо в мастере внутри проекта.

Утилиты: feedback и completion

openspec feedback

Отправляет фидбэк о OpenSpec - создает GitHub issue.

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."

openspec completion

Управляет автодополнением OpenSpec в shell.

openspec completion <subcommand> [shell]

Поддерживаемые shell: bash, zsh, fish, powershell.

# Установка с автоопределением shell
openspec completion install

# Скрипт для ручной установки (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

Для PowerShell установка в текущий хост выглядит так:

$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE сообщает OpenSpec, какой профиль настраивать в этой сессии; установщик создает недостающие каталоги профиля и добавляет управляемый блок, подключающий OpenSpecCompletion.ps1; после удаления (openspec completion uninstall powershell в том же формате) перезапустите PowerShell, чтобы очистить текущую сессию.

Автодополнение - opt-in. CLI однократно упоминает его в stderr при первой команде в интерактивном терминале и больше никогда; подсказка не показывается, если автодополнение уже установлено. Переменная OPENSPEC_NO_COMPLETIONS=1 полностью подавляет подсказку.

Глобальные флаги, коды выхода и переменные окружения

Эти опции работают со всеми командами:

Коды выхода:

Переменные окружения:

Краткое резюме

Справочник CLI openspec - терминальная половина OpenSpec: она обслуживает проект и артефакты вокруг чат-цикла /opsx:*. Ключевое из урока:

• 31 команда в 12 категориях: установка (init, update), Store, диагностика (doctor, context), worksets, просмотр (list, view, show), валидация, архивация, workflow-поддержка (new change, status, instructions, templates, schemas), схемы (schema ...), конфигурация и утилиты.
• Интерактивные команды только для человека: init, view, workset open, config edit, feedback, completion install; остальные поддерживают --json, а разрушительные операции в неинтерактивном режиме требуют --yes.
• validate проверяет структуру и дельты; --archived ловит незакрытые задачи в архиве - готовый pre-commit hook. Изменение без дельт обязано объявлять skip_specs: true.
• archive вливает дельты в основные спецификации, переносит изменение в changes/archive/YYYY-MM-DD-<name>/, а без --yes в окружении с закрытым stdin останавливается с кодом 1 и подсказывает точную команду повторного запуска.
• Store и worksets - beta-поверхность: --store <id> направляет команды в отдельный репозиторий, references в конфигурации дают read-only контекст, doctor сводит здоровье связей.
• Глобальные флаги (--version, --no-color, --help), коды выхода 0/1 и семейство переменных окружения (OPENSPEC_TELEMETRY, OPENSPEC_NO_UPDATE_CHECK и другие) управляют поведением CLI без правки конфигов.

Вопросы для самопроверки

1. Чем openspec validate --archived отличается от openspec validate --all и почему первую удобно ставить в pre-commit hook?
2. Что произойдет, если AI-агент запустит openspec archive add-dark-mode без --yes в окружении с закрытым stdin?
3. Как openspec update решает, что файлы «актуальны», и почему при delivery commands ручные правки файлов команд перезаписываются, а при delivery skills - нет?
4. Какие команды остаются интерактивными («только для человека»), и как остальным работать с агентами и скриптами?
5. Как объявить Store по умолчанию в проекте и почему такое объявление - fallback, а не override?
6. По какому правилу openspec status упорядочивает артефакты и как по его выводу понять, какой артефакт писать следующим?

Что дальше

Справочники позади. Урок 15.7 - «Explore First: продумывание изменения до proposal»: как /opsx:explore превращает сырую идею в продуманный план без обязательств, прежде чем что-либо предлагать.

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md