138 lines
10 KiB
Markdown
138 lines
10 KiB
Markdown
# Design: OpenSpec в DSH
|
||
|
||
Issue: #42. Спека: `openspec/changes/dsh-openspec/specs/dsh-openspec/spec.md`.
|
||
Спайк: 24.10.2026, temp-проект `/tmp/openspec-spike-dPkz`, openspec 1.13.1.
|
||
|
||
## 1. Что показал спайк
|
||
|
||
| Проверка | Результат |
|
||
|---|---|
|
||
| `openspec init --tools agents` в пустом git-проекте | 6 скиллов в `.agents/skills/`, `openspec/config.yaml`, `openspec/{specs,changes/archive}`; AGENTS.md не создаётся |
|
||
| Команды | `Commands skipped for: agents (no adapter)` — слэш-команд адаптер не ставит |
|
||
| `--tools claude`, затем `--tools agents` | `.claude/skills` и `.claude/commands/opsx` остаются нетронутыми, `.agents/skills` добавляется рядом |
|
||
| Отличие agents-скиллов от claude-скиллов | одна строка подсказки (`/opsx:apply` → `/openspec-apply-change`) и `allowed-tools: Bash(openspec:*)` в frontmatter |
|
||
| `openspec new change` → `instructions` → `validate --strict` → `archive -y` | весь цикл без интерактивных вопросов; спека `probe` создалась, change ушёл в `openspec/changes/archive/2026-10-24-spike-test/` |
|
||
| `openspec change new` | команды нет; группа `new` скрыта из верхнего `--help`, но `openspec new change <name>` работает |
|
||
| DSH видит `.agents/skills` | да: сабагент, запущенный с cwd в worktree после `openspec init --tools agents`, получил в каталоге скиллов все шесть `openspec-*` |
|
||
|
||
Последняя строка — главная: проектный корень скиллов DSH действительно читает
|
||
`.agents/skills`, поэтому отдельный слой совместимости не нужен.
|
||
|
||
## 2. Решения
|
||
|
||
### R-1 (решение владельца). Скиллы живут в проекте, не глобально
|
||
|
||
`openspec init --tools agents` пишет `.agents/skills` в проект; в `~/.dsh/skills`
|
||
копии нет. Обоснование:
|
||
|
||
- версия скиллов совпадает с версией CLI проекта, `openspec update` их обновляет;
|
||
- глобальная копия стареет молча и не знает про `--store` и профили конкретного
|
||
проекта;
|
||
- если проект сделал init сам, глобальная копия даёт два скилла с одним именем;
|
||
поведение DSH при дублях не проверено, и проверять его незачем.
|
||
|
||
Цена: новый проект нужно один раз подключить (`--openspec` или `openspec init`).
|
||
Это осознанно: OpenSpec — свойство проекта, а не машины.
|
||
|
||
### R-2 (решение владельца). Слэш-команды нет
|
||
|
||
Вход — model-invocable скиллы: их `description` содержит «openspec propose»,
|
||
«openspec archive» и т.п., поэтому фраза владельца запускает воркфлоу без
|
||
команды. `/role` остаётся единственной командой бандла. Цена: в DSH нет
|
||
аналога `/opsx:*`, набирать команды вручную нельзя — только просить модель.
|
||
Это укладывается в то, как DSH уже работает с ролями.
|
||
|
||
### R-3. `--openspec` не создаёт OpenSpec-корень
|
||
|
||
Флаг добавляет agents-адаптер к проекту, который уже использует OpenSpec: если
|
||
`openspec/` нет, скрипт отказывается и печатает готовую команду. Иначе
|
||
`--openspec` в чужом каталоге молча завёл бы `openspec/`, `config.yaml` и
|
||
changes-каталог — побочный эффект, который не читается из названия флага.
|
||
|
||
### R-4. `--check` предупреждает, а не падает
|
||
|
||
Отсутствие `openspec` в PATH — `WARN`: guard, bootstrap, роли и SDD от него не
|
||
зависят. Код возврата `--check` меняют только `FAIL`-пункты (python3, git,
|
||
node, хуки, бандл).
|
||
|
||
### R-5. Проверка «DSH видит скиллы» — живая, не в тестах
|
||
|
||
Юнит-тест может проверить наличие и frontmatter файлов, но не то, что DSH
|
||
подхватил каталог. Поэтому в тестах — файлы и поведение `install.sh`, а
|
||
видимость проверяется один раз живой сессией (сабагент с cwd в проекте) и
|
||
фиксируется здесь.
|
||
|
||
## 3. Отличия от Claude Code
|
||
|
||
| Что | Claude Code | DSH |
|
||
|---|---|---|
|
||
| Куда ставит `openspec init` | `.claude/skills` + `.claude/commands/opsx/*` | `.agents/skills`, без команд |
|
||
| Вход | `/opsx:propose`, `/opsx:apply`, … | скиллы по имени/фразе; команды нет |
|
||
| Обновление | `openspec update` | `openspec update`, тот же генератор |
|
||
| Глобальная копия | нет | нет (R-1) |
|
||
|
||
Обе копии в одном репозитории — не дублирование ради дублирования: это два
|
||
клиента одного генератора. Расхождение ловится повторным `openspec init` /
|
||
`openspec update`, а не ручной синхронизацией.
|
||
|
||
## 4. Решения, принятые без обсуждения
|
||
|
||
- **2026-10-24. Скиллы `.agents/skills` коммитятся в репозиторий обвязки.**
|
||
Обвязка сама ведёт спеки через OpenSpec, а dogfooding — единственный способ
|
||
держать слой проверенным. Обоснование: если скиллы не закоммичены, первый же
|
||
DSH-прогон в этом репозитории их не увидит. Цена ошибки: лишние 6 каталогов
|
||
в диффе при обновлении openspec; лечится `openspec update` и отдельным
|
||
коммитом.
|
||
- **2026-10-24. `.openspec-target` (`agents`) коммитится вместе со скиллами.**
|
||
Это маркер адаптера, который пишет генератор; без него `openspec update` не
|
||
знает, какой адаптер обновлять. Цена ошибки: одна строка в диффе.
|
||
- **2026-10-24. Тест `--openspec` подставляет фейковый бинарь `openspec` в PATH.**
|
||
Тесты DSH-порта идут без внешних CLI (см. `dsh/tests/run.sh`); живой openspec
|
||
в тесте сделал бы набор зависимым от машины. Цена ошибки: тест не проверяет
|
||
настоящий генератор — это делает живая приёмка.
|
||
- **2026-10-24. Проверка скиллов в `--check` смотрит репозиторий обвязки
|
||
(`$ROOT`), а не cwd.** `install.sh` — скрипт установки обвязки, его `--check`
|
||
отвечает за состояние обвязки; проект проверяется флагом `--openspec`.
|
||
Цена ошибки: из чужого проекта `--check` покажет `WARN` о скиллах обвязки —
|
||
сообщение говорит, что делать.
|
||
|
||
## 5. Риски
|
||
|
||
- **Версия скиллов против CLI.** Скиллы генерирует CLI; если проект обновит
|
||
`openspec` и не выполнит `openspec update`, скиллы отстанут от CLI. `--check`
|
||
сравнивать версии не будет: он не знает, какой CLI у проекта. Признак —
|
||
`metadata.generatedBy` во frontmatter.
|
||
- **`.claude/commands/opsx` в DSH не работают** и остаются в репозитории для
|
||
Claude Code. Это не мёртвый груз, а второй клиент; в PORT.md написано явно.
|
||
- **DSH при дублях скиллов.** Не проверено и не проверяется, потому что
|
||
глобальной копии нет (R-1). Если кто-то поставит `openspec init --tools agents`
|
||
при уже скопированных вручную скиллах, поведение определит DSH.
|
||
- **`openspec init` пишет в проект.** Флаг `--openspec` запускается только по
|
||
явной команде и только при существующем `openspec/`; `adopt-project.sh` и
|
||
`new-project.sh` его не вызывают.
|
||
|
||
## 6. Приёмка
|
||
|
||
- `openspec validate dsh-openspec --strict` — change валиден.
|
||
- `bash dsh/tests/run.sh` — зелёный, включая новый `openspec.test.mjs`.
|
||
- Живая проверка DSH: сессия/сабагент с cwd в проекте после `openspec init
|
||
--tools agents` видит шесть `openspec-*` в каталоге скиллов; полный цикл
|
||
`new change → validate --strict → archive -y` проходит без Claude Code
|
||
(спайк 24.10.2026, транскрипт — в отчёте задачи).
|
||
- `/role` и bootstrap не изменились: тесты `role-skill.test.mjs`,
|
||
`bootstrap.test.mjs` и `sdd-skill.test.mjs` зелёные.
|
||
|
||
### Приёмка: прогон 24.10.2026
|
||
|
||
- CLI: openspec 1.13.1, temp-проект `/tmp/dsh-openspec-accept`, ветка `feat/probe`.
|
||
- `openspec init --tools agents`: шесть скиллов в `.agents/skills`; повторный
|
||
прогон идемпотентен, файлы не задвоились.
|
||
- `openspec new change probe` → `status` → `instructions proposal` → написаны
|
||
`proposal.md` и дельта `specs/probe/spec.md`.
|
||
- `openspec validate probe --strict` → `Change 'probe' is valid`.
|
||
- `openspec archive probe -y` → `Specs updated successfully.` / `Change 'probe'
|
||
archived as '2026-10-24-probe'.`, основная спека
|
||
`openspec/specs/probe/spec.md` создана.
|
||
- Видимость скиллов в DSH-сессии проверяет контроллер отдельным сабагентом;
|
||
результат дописывается сюда после прогона.
|