Справочник
Навыки
Каждый навык OpenSpec: аргументы, что он создаёт и что возвращает в ответ.
Навыки делятся на два набора:
- Core: устанавливаются по умолчанию, составляют основной цикл планирования.
- Optional: устанавливаются только при добавлении через Профили.
Каждый навык рассчитан на проект, в котором уже используется OpenSpec. Перед первым шагом, выполняющим запись, навык проверяет наличие разрешённого корневого каталога. Если его нет, поведение зависит от способа вызова навыка:
- Автоматический выбор: ваш агент сам выбрал навык без упоминания OpenSpec с вашей стороны. Он пропускает использование OpenSpec и отвечает на запрос в обычном режиме, как если бы OpenSpec не был установлен.
- Явный запрос OpenSpec: вы упомянули OpenSpec, назвали навык или запустили его команду. Навык останавливается перед записью и спрашивает, как поступить: запустить
openspec initв текущем каталоге, указать хранилище через--store <id>или продолжить без OpenSpec. Он ждёт вашего ответа.
Команды всегда относятся ко второму случаю. Проект, чей файл openspec/config.yaml указывает на хранилище, которое эта машина не может разрешить (не зарегистрировано или строка store: некорректна), не считается неинициализированным: навык останавливается и выводит ошибку хранилища вместе со способом её исправления. Ни в одном из случаев навык не создаёт каталог openspec/ самостоятельно. В разделах ниже описано, что делает каждый навык, когда корневой каталог уже настроен.
| Навык | Назначение | Тип |
|---|---|---|
| openspec-explore | Продумать идею до того, как она станет предложением изменения | Core |
| openspec-propose | Создать предложение изменения со всеми артефактами планирования за один шаг | Core |
| openspec-apply-change | Реализовать задачи предложения изменения | Core |
| openspec-update-change | Пересмотреть план предложения изменения | Core |
| openspec-sync-specs | Объединить обновления спецификаций из предложения изменения в specs/ | Core |
| openspec-archive-change | Переместить завершённое предложение изменения в архив | Core |
| openspec-new-change | Начать предложение изменения как пустой каркас | Optional |
| openspec-continue-change | Создавать следующий артефакт планирования, по одному за раз | Optional |
| openspec-ff-change | Создать предложение изменения со всеми артефактами, необходимыми для реализации, за один проход | Optional |
| openspec-verify-change | Проверить соответствие реализации плану | Optional |
| openspec-bulk-archive-change | Архивировать сразу несколько предложений изменения | Optional |
| openspec-onboard | Изучить процесс, выполнив одно реальное предложение изменения от начала до конца | Optional |
В каждом разделе ниже указан навык, отвечающий за следующий шаг. Если ваш профиль исключает этот навык, установленные файлы никогда не упоминают его: передача управления заменяется на эквивалентную команду openspec или прямой запрос к вам, а строка, существующая только для ссылки на отсутствующий навык, не записывается вовсе. Таким образом, имеющиеся у вас навыки всегда передают управление только тем навыкам, которые у вас установлены. Какой набор вы получите, определяется в разделе Профили.
openspec-explore
Продумать идею до того, как она станет предложением изменения.
| Контракт | Описание |
|---|---|
| Аргументы | Тема: идея, проблема, сравнение или имя существующего предложения изменения для исследования в контексте. Если ничего не указано, переходит в режим исследования. |
| Создаёт | По умолчанию ничего. Только читает и исследует. По запросу фиксирует выводы: новое предложение изменения в openspec/changes/<name>/ или обновления для предложения, дизайна, спецификаций либо задач существующего изменения. Никогда не пишет код. |
| Ответ | Открытый диалог без обязательного выходного формата. Когда мысли оформляются, подводит итог по проблеме, подходу, открытым вопросам и следующим шагам, а также предлагает зафиксировать их. Решение за вами. Реализация здесь никогда не начинается. |
openspec-propose
Создать предложение изменения и сгенерировать все его артефакты планирования за один шаг.
| Контракт | Описание |
|---|---|
| Аргументы | Имя в формате kebab-case (add-dark-mode) или обычное текстовое описание. Если не указано ни то ни другое, запрашивает у вас. |
| Создаёт | openspec/changes/<name>/ со всеми артефактами, которые определяет схема, в порядке зависимостей (spec-driven: предложение, дельты спецификаций, дизайн, задачи). Никогда не пишет код. |
| Ответ | Созданные артефакты, готовые к проверке, и следующий шаг. На этом останавливается; реализация ожидает вызова openspec-apply-change. |
openspec-apply-change
Реализовать задачи предложения изменения, продвигаясь по списку до завершения или блокировки.
| Контракт | Описание |
|---|---|
| Аргументы | Имя предложения изменения (add-auth), необязательно. Если цель неоднозначна, выводит список активных предложений изменения и просит выбрать. |
| Создаёт | Код: минимальные изменения в файлах вашего проекта, которых требует каждая задача. В предложении изменения отмечает каждую выполненную задачу (- [ ] на - [x]) в отслеживаемом файле, определяемом по sourcePath и номеру строки line (начиная с единицы). Схема может отслеживать задачи в нескольких файлах. |
| Ответ | Прогресс по каждой задаче, затем общий итог (выполнено N/M задач). Когда всё готово: предлагает openspec-archive-change. При блокировке из-за отсутствующих артефактов: указывает на openspec-continue-change или на openspec status и openspec instructions, если этот навык не установлен (профиль core его исключает). При неясных задачах или ошибках: делает паузу и спрашивает. |
openspec-update-change
Пересмотреть существующие артефакты планирования предложения изменения и сохранить их согласованность друг с другом.
| Контракт | Описание |
|---|---|
| Аргументы | Имя предложения изменения (необязательно) плюс нужная вам правка. Если правка не указана, запускает проверку согласованности: артефакты сверяются друг с другом на предмет противоречий, пробелов и дублирования. |
| Создаёт | Редактирует файлы артефактов, которые уже существуют. Одно исключение: для артефакта, заданного через glob-шаблон (например, specs/**/*.md), у которого уже есть хотя бы один файл, может добавить недостающий сопутствующий файл после подтверждения пути с вашей стороны. Артефакт, у которого ещё нет файлов, — задача для openspec-continue-change. Без этого навыка (профиль core его исключает) указывает вместо этого на openspec status и openspec instructions. Никогда не пишет код. |
| Ответ | Показывает каждую предлагаемую правку и записывает её только после вашего подтверждения, по одному артефакту за раз. Завершается сводкой того, что было пересмотрено, и следующим шагом; реализация ожидает вызова openspec-apply-change. |
openspec-sync-specs
Объединить обновления спецификаций из предложения изменения в specs/ без его архивации.
| Контракт | Описание |
|---|---|
| Аргументы | Имя предложения изменения, необязательно. Вы также можете указать подмножество его дельта-спецификаций, и тогда синхронизируются только они. |
| Создаёт | Редактирует или создаёт openspec/specs/<capability-path>/spec.md для каждой дельта-спецификации, объединяя добавленные, изменённые, удалённые и переименованные требования в основную спецификацию. Никогда не пишет код. |
| Ответ | Сводка по каждой возможности с указанием добавленных, изменённых, удалённых или переименованных требований после того, как обновлённые спецификации пройдут валидацию. Предложение изменения остаётся активным; архивация ожидает вызова openspec-archive-change. |
openspec-archive-change
Переместить завершённое предложение изменения в архив.
| Контракт | Описание |
|---|---|
| Аргументы | Имя предложения изменения, необязательно. |
| Создаёт | Перемещает папку предложения изменения в openspec/changes/archive/YYYY-MM-DD-<name>/ (дата не добавляется, если имя уже начинается с неё). С вашего одобрения сначала синхронизирует необработанные дельта-спецификации. Если установлен openspec-sync-specs, запускает этот процесс. В противном случае самостоятельно объединяет дельта-спецификации в основные спецификации. Никогда не пишет код. |
| Ответ | Предупреждает и запрашивает подтверждение перед архивацией при наличии незавершённых артефактов или задач, а также спрашивает, нужно ли выполнить синхронизацию, если существуют дельта-спецификации. Завершается сводкой: имя, схема, расположение архива, статус синхронизации спецификаций и любые предупреждения. |
openspec-new-change
Начать предложение изменения как пустой каркас.
| Контракт | Описание |
|---|---|
| Аргументы | Имя в формате kebab-case (add-user-auth) или обычное текстовое описание, плюс имя схемы (только для процесса не по умолчанию). Если не указано ни то ни другое, спрашивает, что вы хотите создать. |
| Создаёт | openspec/changes/<name>/ как пустой каркас: пока без артефактов, никогда не пишет код. |
| Ответ | Имя и расположение каркаса, последовательность артефактов процесса, статус (выполнено 0/N) и шаблон первого артефакта. Составление артефактов ожидает вызова openspec-continue-change. |
openspec-continue-change
Создавать следующий артефакт планирования в предложении изменения, по одному за раз.
| Контракт | Описание |
|---|---|
| Аргументы | Имя предложения изменения, необязательно. Если выбор остаётся неоднозначным, просит выбрать из списка недавно изменённых. |
| Создаёт | Единственный следующий готовый к созданию артефакт в последовательности схемы, записанный в папку предложения изменения. Один артефакт за запуск, никогда не пишет код. |
| Ответ | Созданный артефакт, прогресс (выполнено N из M) и список артефактов, которые стали доступны благодаря этому. Когда планирование завершено, сообщает об этом; реализация переходит к openspec-apply-change. |
openspec-ff-change
Создать предложение изменения и все артефакты планирования, необходимые для реализации, за один проход.
| Контракт | Описание |
|---|---|
| Аргументы | Имя в формате kebab-case или обычное текстовое описание. Если не указано ни то ни другое, запрашивает у вас. Если предложение изменения с таким именем уже существует, предлагает продолжить работу над ним. |
| Создаёт | openspec/changes/<name>/ и все артефакты планирования, которых требует реализация, в порядке зависимостей (spec-driven: предложение, спецификации, дизайн, задачи), пропуская только артефакты, помеченные как пропущенные или условные. Никогда не пишет код. |
| Ответ | Имя и расположение предложения изменения, каждый созданный артефакт, а также любой пропущенный условный артефакт с указанием причины. На этом останавливается; реализация ожидает вызова openspec-apply-change. |
openspec-verify-change
Проверить соответствие реализации артефактам предложения изменения.
| Контракт | Описание |
|---|---|
| Аргументы | Имя предложения изменения, необязательно. При неоднозначности перечисляет предложения изменения, у которых есть артефакт задач, и просит выбрать. |
| Создаёт | Ничего. Читает артефакты предложения изменения и кодовую базу. Верификация работает только в режиме отчёта. |
| Ответ | Отчёт: таблица оценок по категориям «Полнота» (Completeness), «Корректность» (Correctness) и «Согласованность» (Coherence), затем проблемы уровней CRITICAL, WARNING и SUGGESTION с рекомендациями, а также итоговая оценка готовности к архивации. Ничего не меняет и не архивирует. |
openspec-bulk-archive-change
Архивировать сразу несколько предложений изменения.
| Контракт | Описание |
|---|---|
| Аргументы | Нет. Выводит список активных предложений изменения и просит выбрать любое количество (с возможностью выбрать все). Если активных предложений нет, сообщает об этом и останавливается. |
| Создаёт | openspec/changes/archive/YYYY-MM-DD-<name>/ для каждого архивируемого предложения изменения (имена, уже содержащие дату, сохраняют свой префикс). Дельты спецификаций каждого из них сначала синхронизируются через openspec-sync-specs. Никогда не пишет код. |
| Ответ | Таблица статусов по каждому предложению изменения и одно общее подтверждение для всего пакета, затем сводка по архивированным, пропущенным и завершившимся с ошибкой элементам, плюс результаты синхронизации спецификаций. Когда два предложения изменения затрагивают одну и ту же спецификацию, проверяет кодовую базу и синхронизирует реализованные дельты начиная с самых старых. |
openspec-onboard
Изучить процесс, выполнив одно реальное предложение изменения от начала до конца.
| Контракт | Описание |
|---|---|
| Аргументы | Нет. Сканирует вашу кодовую базу в поисках небольших стартовых задач и просит выбрать одну из них или описать собственную. |
| Создаёт | Реальное предложение изменения для выбранной задачи (по одному артефакту за раз), а затем реальный код после того, как вы подтвердите реализацию. В конце архивирует предложение изменения. |
| Ответ | Пошаговое руководство по полному циклу с пояснениями и паузами для вашего ввода: исследование, создание, построение каждого артефакта, реализация, архивация. Завершается кратким обзором и ссылкой на openspec-propose. Занимает около 15–20 минут. |