Урок 15.5. Справочник слэш-команд /opsx:*

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

В уроке 15.4 разобрано, что у OpenSpec два интерфейса: терминальный CLI для управления проектом и слэш-команды в чате coding-агента для работы над изменением. Исследование, планирование, реализация и архивация происходят именно в чате, поэтому набор слэш-команд - это инструмент, которым вы пользуетесь каждый день.

Этот урок - справочник, а не перевод документации подряд. Все команды из docs/commands.md сведены в компактные таблицы: одна строка на команду, точный синтаксис, аргументы, что происходит при выполнении и типовые сценарии применения. Взглянуть в таблицу быстрее, чем искать раздел в оригинале или вспоминать точное имя команды пакетной архивации.

Урок сознательно не отвечает на вопрос «какую команду выбрать в конкретной ситуации»: паттерны комбинирования команд под типовые задачи - новая фича, багфикс, рефакторинг - разобраны в уроке 15.8. Здесь только факты: что делает каждая команда, какие принимает аргументы и что происходит после вызова.

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

Команды OpenSpec покрывают весь жизненный цикл изменения: продумать (/opsx:explore), создать proposal (предложение об изменении) со всеми планирующими артефактами (/opsx:propose), реализовать задачи (/opsx:apply), привести артефакты в порядок (/opsx:update), слить дельта-спецификации (delta specs) в основные specs (/opsx:sync) и заархивировать (/opsx:archive). Расширенный набор добавляет пошаговое планирование, проверку реализации и пакетные операции: /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard.

Типовой путь профиля core (шаги explore → propose → apply → archive вы уже видели в уроке 2.10):

Пунктирные шаги необязательны: /opsx:verify рекомендуется запускать перед архивацией, а /opsx:sync в большинстве случаев не нужен - archive сам предложит синхронизацию.

Профили: core и расширенный набор

Команды разделены на два профиля:

core (профиль по умолчанию). Шесть команд быстрого пути: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive. Этого набора достаточно для полного цикла изменения.
Расширенный набор (expanded workflows). Шесть команд для пошагового контроля и пакетных операций: /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard. По умолчанию не устанавливаются.

Чтобы включить расширенные команды, выполните в терминале:

bash
openspec config profile   # выбрать workflows в интерактивном меню профиля
openspec update           # перегенерировать файлы команд в проекте

Дальше команды приведены в каноническом виде /opsx:<command>. В разных AI-инструментах написание отличается (/opsx-propose, $openspec-propose) - сводная таблица вариаций есть в конце урока, а механика регистрации команд разобрана в уроке 15.4.

Команды профиля core

Команда	Назначение	Синтаксис и аргументы	Что происходит	Типовые сценарии
`/opsx:propose`	Создать изменение и все планирующие артефакты за один шаг; стартовая команда профиля `core`	`/opsx:propose [change-name-or-description]`; необязательный аргумент - имя в kebab-case или описание изменения на естественном языке	Создает `openspec/changes/<change-name>/`; генерирует артефакты, необходимые до реализации (для `spec-driven`: proposal, specs, design, tasks); останавливается, когда изменение готово к `/opsx:apply`	Самый быстрый сквозной путь от идеи до готового к реализации плана
`/opsx:explore`	«Партнер по размышлению»: продумать идеи и уточнить требования до создания изменения. Начинайте здесь, если не уверены	`/opsx:explore [topic]`; `topic` - необязательная тема для исследования	Открывает свободную исследовательскую беседу без формальной структуры; читает кодовую базу и отвечает на вопросы; сравнивает варианты подходов; строит диаграммы для ясности. По вашей просьбе или после согласия на предложение фиксирует результат: создает изменение через `openspec new change` и пишет названные вами артефакты либо обновляет артефакты существующего изменения. Может перейти в `/opsx:propose` (core) или `/opsx:new` (расширенный набор)	Требования неясны; нужно сравнить несколько подходов до решения; не хочется создавать изменение «на всякий случай»
`/opsx:apply`	Реализовать задачи из изменения: пройти по списку задач, написать код и отметить выполненное	`/opsx:apply [change-name]`; изменение определяется из контекста, если не указано	Читает `tasks.md` и находит незавершенные задачи; работает по ним по одной: пишет код, создает файлы, запускает тесты; отмечает выполненные задачи чекбоксами `[x]`	Реализация спланированного изменения; параллельные изменения - по имени; возобновление после прерывания
`/opsx:update`	Пересмотреть существующие планирующие артефакты изменения и сохранить их согласованность между собой; код никогда не трогает	`/opsx:update [change-name]`; изменение из контекста, если не указано	Читает артефакты через `openspec status --change <name> --json`; применяет названную вами правку либо ищет противоречия, если правка не названа; согласует остальные артефакты в любом направлении (правка `design.md` может откатиться вплоть до proposal); подтверждает каждую правку у вас, по одному артефакту за раз; в конце рекомендует следующий шаг: `/opsx:continue`, `/opsx:apply` или `/opsx:archive`	Решение изменилось по ходу работы; артефакты разошлись между собой после ручных правок; нужно уточнить план перед реализацией
`/opsx:sync`	Влить дельта-спецификации из изменения в основные specs. Необязательная команда: `archive` сам предложит синхронизацию, вручную обычно не нужна	`/opsx:sync [change-name]`; изменение из контекста, если не указано	Читает дельта-спецификации из каталога изменения; разбирает секции ADDED/MODIFIED/REMOVED/RENAMED; вливает изменения в `openspec/specs/`; сохраняет существующий контент, не упомянутый в дельте; изменение остается активным (не архивируется)	Ручной запуск нужен редко - типовые случаи в таблице «Когда запускать `/opsx:sync` вручную» ниже
`/opsx:archive`	Заархивировать завершенное изменение: финализировать и перенести в архив	`/opsx:archive [change-name]`; изменение из контекста, если не указано	Проверяет завершенность артефактов и задач (предупредит о незавершенных); предлагает синхронизировать дельта-спецификации, если они еще не синхронизированы; переносит каталог изменения в `openspec/changes/archive/YYYY-MM-DD-<name>/`; сохраняет все артефакты как audit trail	Завершение жизненного цикла изменения

Пример ответа агента на /opsx:propose:

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md
     ✓ specs/ui/spec.md
     ✓ design.md
     ✓ tasks.md
     Ready for implementation. Run /opsx:apply.

Диалог /opsx:explore выглядит как беседа, а не как выполнение команды: агент исследует код, взвешивает варианты - и фиксирует результат только с вашего согласия:

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle authentication for the mobile app?

AI:  Let me investigate your current auth setup...
     [Analyzes codebase]

     I see you're using session-based auth for the web app.
     For mobile, we have three main options:

     1. JWT tokens (stateless, works offline)
     2. OAuth2 (if you need third-party login)
     3. Extend current sessions (simpler, but requires connectivity)

     Which direction interests you?

You: Let's go with JWT.

AI:  That's a decision worth keeping. Want me to start a change called
     add-jwt-auth? Just the change folder, nothing else yet.

You: Yes.

AI:  Started openspec/changes/add-jwt-auth/. Say the word and I'll
     write the proposal, specs, and tasks from what we just worked out.

Правку для /opsx:update можно описать словами в той же строке - агент найдет затронутые артефакты сам:

You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage

AI:  Reading add-dark-mode artifacts...

     The design references localStorage in two places; tasks 1.3 covers
     localStorage persistence; the proposal doesn't mention storage.

     Proposed revisions:
     1. design.md - swap localStorage decision for cookie storage
     2. tasks.md - reword task 1.3 to cookie persistence

     Apply revision 1? (design.md)

Когда запускать `/opsx:sync` вручную

Ситуация	Запускать вручную?
Долго живущее изменение - specs нужны в основном наборе до архивации	да
Несколько параллельных изменений зависят от обновленной базы specs	да
Хотите отдельно посмотреть и поревьюить слияние	да
Быстрое изменение, идущее сразу в архивацию	нет - archive обработает синхронизацию сам

Расширенные команды workflow

Доступны после включения расширенного профиля (см. выше). Пара /opsx:new + /opsx:continue - пошагочная альтернатива «всему сразу» в /opsx:propose; /opsx:ff - промежуточный вариант.

Команда	Назначение	Синтаксис и аргументы	Что происходит	Типовые сценарии
`/opsx:new`	Создать заготовку (scaffold) нового изменения: только каталог и метаданные, без артефактов	`/opsx:new [change-name] [--schema <schema-name>]`; имя и схему агент спросит, если не заданы; схема по умолчанию - из конфигурации или `spec-driven`	Создает `openspec/changes/<change-name>/` и файл метаданных `.openspec.yaml` (схема, дата создания); показывает первый артефакт, готовый к созданию; дальнейшие артефакты - через `/opsx:continue` или `/opsx:ff`	Пошаговый контроль: сначала каркас, затем артефакты по одному или все сразу
`/opsx:continue`	Создать следующий артефакт по цепочке зависимостей - по одному за вызов	`/opsx:continue [change-name]`; изменение из контекста, если не указано	Опрашивает граф зависимостей артефактов; показывает, какие готовы, а какие заблокированы; создает первый готовый артефакт, читая файлы-зависимости для контекста; сообщает, что стало доступно после создания	Ревью каждого артефакта до перехода к следующему; сложные изменения, где нужен контроль
`/opsx:ff`	Fast-forward: создать все планирующие артефакты сразу	`/opsx:ff [change-name]`; изменение из контекста, если не указано	Создает все артефакты в порядке зависимостей; ведет todo-список прогресса; перед созданием каждого артефакта читает его зависимости; останавливается, когда все артефакты со статусом `apply-required` готовы	Ясное представление, что строите; небольшие и средние фичи; быстрее, чем `/opsx:continue`
`/opsx:verify`	Проверить, что реализация соответствует артефактам изменения: полнота, корректность, согласованность	`/opsx:verify [change-name]`; изменение из контекста, если не указано	Проверяет три измерения качества реализации (таблица ниже); ищет в кодовой базе свидетельства реализации; выдает проблемы с категориями CRITICAL, WARNING или SUGGESTION; не блокирует архивацию, но подсвечивает проблемы	Запуск перед `/opsx:archive`, чтобы поймать расхождения заранее; ревью работы агента до коммита; поиск дрейфа между артефактами и кодом
`/opsx:bulk-archive`	Заархивировать несколько завершенных изменений сразу, разрешив конфликты спецификаций между ними	`/opsx:bulk-archive [change-names...]`; конкретные изменения или выбор из списка, если не указаны	Перечисляет все завершенные изменения; валидирует каждое перед архивацией; находит конфликты specs между изменениями; разрешает их, сверяясь с фактически реализованным кодом; архивирует в хронологическом порядке	Параллельные потоки работы; накопившиеся завершенные изменения
`/opsx:onboard`	Интерактивное обучение полному workflow OpenSpec на вашей реальной кодовой базе	`/opsx:onboard`; аргументов нет	Проводит полный цикл workflow с комментариями на каждом шаге (фазы ниже): сканирует кодовую базу в поисках реального улучшения, создает настоящее изменение с реальными артефактами, реализует его и архивирует	Новые пользователи, изучающие workflow; занимает 15-30 минут

Статус артефактов, который показывает /opsx:continue (галочка - готово, ромб - доступно, кружок - заблокировано):

Artifact status:
✓ proposal    (done)
◆ specs       (ready)
◆ design      (ready)
○ tasks       (blocked - needs: specs, design)

Пример: `/opsx:bulk-archive`

Команда находит завершенные изменения, обнаруживает конфликт specs между add-dark-mode и update-footer и разрешает его, сверяясь с кодом:

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (8/8 tasks complete)
     - fix-login-bug (3/3 tasks complete)
     - update-footer (2/2 tasks complete)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will merge in chronological order:
     1. add-dark-mode (created Jan 20)
     2. update-footer (created Jan 22)

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-bug
     ✓ Archived update-footer
     Specs merged: add-dark-mode → update-footer

Что проверяет `/opsx:verify`

Измерение	Что валидируется
Completeness (полнота)	Все задачи выполнены, все требования реализованы, сценарии покрыты
Correctness (корректность)	Реализация соответствует замыслу спецификации, граничные случаи обработаны
Coherence (согласованность)	Решения из `design.md` отражены в коде, паттерны единообразны

Отчет команды построен по тем же трем измерениям; проблемы помечаются категорией (⚠ здесь - WARNING):

COMPLETENESS
✓ All 8 tasks in tasks.md are checked
✓ All requirements in specs have corresponding code
⚠ Scenario "System preference detection" has no test coverage

CORRECTNESS
✓ Implementation matches spec intent
✓ Edge cases from scenarios are handled
✓ Error states match spec definitions

COHERENCE
✓ Design decisions reflected in code structure
✓ Naming conventions consistent with design.md
⚠ Design mentions "CSS variables" but implementation uses Tailwind classes

SUMMARY
─────────────────────────────
Critical issues: 0
Warnings: 2
Ready to archive: Yes (with warnings)

Фазы `/opsx:onboard`

Приветствие и анализ кодовой базы
Поиск возможности для улучшения
Создание изменения (/opsx:new)
Написание proposal
Создание specs
Написание design
Создание задач
Реализация задач (/opsx:apply)
Верификация реализации
Архивация изменения
Итоги и следующие шаги

Начало диалога выглядит так:

You: /opsx:onboard

AI:  Welcome to OpenSpec!

     I'll walk you through the complete workflow using your actual codebase.
     We'll find something small to improve, create a proper change for it,
     implement it, and archive it.

     Let me scan your codebase for opportunities...

     [Analyzes codebase]

     I found a few things we could work on:
     1. Add input validation to the contact form
     2. Improve error messages in the auth flow
     3. Add loading states to async buttons

     Which interests you? (or suggest something else)

Важные детали

Поведенческие нюансы команд, которые стоит знать до первого запуска:

/opsx:explore никогда не пишет код - и вообще ничего не создает, пока вы не попросите или не согласитесь на его предложение. Умеет читать файлы и искать по кодовой базе; хорошо подходит для сравнения нескольких подходов до принятия решения.
/opsx:propose - самый быстрый сквозной путь. Если нужен пошаговый контроль артефактов, включите расширенный набор и используйте /opsx:new + /opsx:continue.
/opsx:new: давайте изменениям описательные имена (add-feature, fix-bug, refactor-module) и избегайте обезличенных (update, changes, wip). Схему можно задать не только флагом, но и в конфигурации проекта (openspec/config.yaml).
/opsx:continue: несколько артефактов могут стать доступными одновременно; созданные артефакты можно править до следующего вызова.
/opsx:ff быстрее /opsx:continue на простых изменениях; артефакты по-прежнему можно править после создания.
/opsx:apply: состояние выполнения хранится в чекбоксах tasks.md, поэтому после прерывания команда продолжит с места остановки; для параллельных изменений указывайте имя явно.
/opsx:update не начинает артефакт, у которого еще нет файлов, - для этого есть /opsx:continue (или openspec status и openspec instructions, если тот workflow не установлен). Для glob-артефактов вроде specs/**/*.md, где хотя бы один файл существует, update может предложить недостающий файл-компаньон - по инструкциям схемы и с подтверждением конкретного пути у вас. Новые файлы создаются только внутри каталога изменения; если файл по подтвержденному пути появился раньше создания, update остановится, а не перезапишет его. Пропущенные вами артефакты не трогаются. Если правка меняет сам замысел изменения - начните новое изменение, а не обновляйте старое.
/opsx:verify: предупреждения (WARNING) не блокируют архивацию, но указывают на возможные проблемы; категории CRITICAL и SUGGESTION - соответственно критичные проблемы и подсказки.
/opsx:sync - умное слияние, а не копирование: умеет добавлять сценарии к существующим требованиям без дублирования. После sync изменение остается активным; большинству пользователей команда не нужна напрямую - archive сам предложит синхронизацию.
/opsx:archive не блокируется незавершенными задачами, но предупредит о них; дельта-спецификации можно синхронизировать в момент архивации или заранее; перед архивацией рекомендуется прогнать /opsx:verify; заархивированные изменения сохраняются как история.
/opsx:bulk-archive: разрешение конфликтов specs агентное - команда сверяется с тем, что реально реализовано в коде; изменения архивируются в порядке создания; перед перезаписью содержимого specs запрашивается подтверждение.
/opsx:onboard работает с реальным кодом, а не с учебными примерами; созданное изменение можно оставить или отбросить.

Написание команд в разных AI-инструментах

Каноническое имя /opsx:<command> - не единственная форма: разные инструменты по-разному регистрируют файлы команд. Смысл команд одинаков, отличается только написание.

Форма файла команды	Синтаксис	Примеры инструментов
`.../commands/opsx/<id>.*`	`/opsx:propose`, `/opsx:apply`	Claude Code, Gemini CLI, Crush
`.../opsx-<id>.*`	`/opsx-propose`, `/opsx-apply`	Cursor, Devin Desktop, Copilot (IDE), Trae, Oh My Pi
только skills, без файлов команд	`/openspec-propose`, `/openspec-apply-change`	CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, Zed Agent, shared `.agents`
Kimi Code	`/skill:openspec-propose`	Kimi Code
Codex CLI	`$openspec-propose`	Codex

Нюансы:

Devin Desktop против Devin Local: файлы .devin/workflows/opsx-*.md дают Devin Desktop команды вида /opsx-propose. У Devin Local workflows нет - используйте skills, которые OpenSpec записывает в .devin/skills/, например /openspec-propose; они работают в обоих агентах.
GitHub Copilot: команды (.github/prompts/*.prompt.md) доступны только в IDE-расширениях (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI сейчас не поддерживает кастомные prompt-файлы.

Точное написание для конкретного инструмента проще всего взять из файлов, которые OpenSpec сгенерировал при openspec init (подробнее - в уроке 15.4).

Устаревшие команды /openspec:*

Команды старого workflow «все сразу». Они все еще работают, но рекомендуются OPSX-команды.

Команда	Что делает
`/openspec:proposal`	Создает все артефакты сразу (proposal, specs, design, tasks)
`/openspec:apply`	Реализует изменение
`/openspec:archive`	Архивирует изменение

Когда их используют: существующие проекты на старом workflow; простые изменения, где не нужно поэтапное создание артефактов; предпочтение подхода «все или ничего». Миграция проста: legacy-изменения можно продолжать OPSX-командами - структура артефактов совместима.

Устранение неполадок

Симптом	Причина	Что делать
«Change not found»	Команда не смогла определить, над каким изменением работать	Укажите имя явно: `/opsx:apply add-dark-mode`; проверьте, что каталог изменения существует: `openspec list`; убедитесь, что вы в правильном каталоге проекта
«No artifacts ready»	Все артефакты либо завершены, либо заблокированы отсутствующими зависимостями	Запустите `openspec status --change <name>` - он покажет, что блокирует; создайте сначала недостающие артефакты-зависимости
«Schema not found»	Указанная схема не существует	Посмотрите список схем: `openspec schemas`; проверьте написание имени схемы; для кастомной схемы: `openspec schema init <name>`
Команды не распознаются	AI-инструмент не видит команды OpenSpec	Убедитесь, что проект инициализирован: `openspec init`; перегенерируйте skills: `openspec update`; для Claude Code проверьте, что существует каталог `.claude/skills/`; перезапустите инструмент, чтобы он подхватил новые skills
Артефакты генерируются неполными или некорректными	Агенту не хватает контекста или контроля	Добавьте контекст проекта в `openspec/config.yaml`; добавьте правила для отдельных артефактов; опишите изменение детальнее; используйте `/opsx:continue` вместо `/opsx:ff`

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

Справочник охватывает двенадцать OPSX-команд и три устаревших. Главные точки опоры:

Профиль по умолчанию core - шесть команд быстрого пути: propose, explore, apply, update, sync, archive; расширенный набор (new, continue, ff, verify, bulk-archive, onboard) включается через openspec config profile + openspec update.
У большинства команд аргумент [change-name] необязателен - изменение определяется из контекста; имя нужно указывать явно при параллельной работе.
/opsx:propose создает изменение со всеми артефактами за один шаг; пошаговая альтернатива - /opsx:new + /opsx:continue или /opsx:ff; /opsx:update согласует артефакты между собой и не трогает код.
/opsx:sync обычно не нужен вручную - archive сам предложит синхронизацию дельта-спецификаций; /opsx:verify перед архивацией подсвечивает расхождения, но не блокирует.
Написание команд зависит от инструмента: /opsx:propose, /opsx-propose, $openspec-propose - одна и та же команда при разных способах регистрации.

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

Чем /opsx:explore отличается от /opsx:propose и почему документация советует начинать с explore, когда вы не уверены в требованиях?
Какая разница между цепочкой /opsx:new + /opsx:continue и командой /opsx:ff, и что выбрать для небольшой фичи с ясным планом?
Почему /opsx:sync называют необязательной командой и в каких ситуациях ее все же запускают вручную?
Что /opsx:archive делает с дельта-спецификациями и в какой каталог попадает заархивированное изменение?
Какие три измерения проверяет /opsx:verify и блокируют ли предупреждения (WARNING) архивацию?
Как включить расширенные команды workflow и почему они недоступны сразу после установки?

Что дальше

Урок 15.6 - вторая половина справочника: терминальные команды openspec (init, update, validate, config, dashboard, feedback и другие) в таблицах с примерами и глобальными флагами.

Источники

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