151 lines
10 KiB
Markdown
151 lines
10 KiB
Markdown
# Spec Delta: dsh-install
|
||
|
||
## Purpose
|
||
|
||
Слой установки DSH-обвязки: откуда берутся superpowers-скиллы и роли, что
|
||
делает `dsh/install.sh --skills/--roles`, какие пути попадают в установленные
|
||
инструкции. В Claude Code источником служит кэш плагина в `~/.claude`; в DSH
|
||
источник задаётся установщиком явно (аргумент, переменная или пиннинг в
|
||
`~/.dsh`), а `~/.claude` остаётся только legacy-fallback'ом с предупреждением.
|
||
Контракт нужен, чтобы свежая установка на машине без Claude Code проходила
|
||
полный цикл #48 и чтобы путь `~/.claude` не возвращался в runtime незаметно.
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: Источник superpowers задаётся при установке
|
||
`dsh/install.sh --skills` SHALL разрешать источник superpowers-скиллов в
|
||
порядке приоритета и MUST NOT исполнять `git clone` и любые сетевые операции.
|
||
|
||
- Порядок: `--superpowers-from <dir>` → `$DSH_SUPERPOWERS_SOURCE` →
|
||
`$DSH_HOME/superpowers/skills` (пиннинг; допускается и корень
|
||
`$DSH_HOME/superpowers` с подкаталогом `skills/`) → legacy-кэш Claude Code →
|
||
legacy `~/.claude/skills`.
|
||
- Для явного источника (`--superpowers-from`, `$DSH_SUPERPOWERS_SOURCE`)
|
||
допускаются обе формы: корень superpowers (есть `skills/using-superpowers/SKILL.md`)
|
||
или сам каталог `skills`.
|
||
- Явно заданный, но невалидный источник MUST приводить к `FAIL` и коду
|
||
возврата 1: тихий откат на legacy запрещён.
|
||
- Копирование MUST быть заменой каталога назначения (`rm -rf` + `cp -R`), а не
|
||
симлинком: `~/.dsh/skills` не должен зависеть от каталога-источника.
|
||
|
||
#### Scenario: Явный источник без ~/.claude
|
||
- **WHEN** `HOME` — пустой temp-каталог без `~/.claude`, а `--superpowers-from`
|
||
указывает на каталог superpowers
|
||
- **THEN** `--skills` копирует скиллы в `$DSH_HOME/skills`, печатает источник и
|
||
завершается кодом 0
|
||
|
||
#### Scenario: Переменная окружения вместо флага
|
||
- **WHEN** задан `DSH_SUPERPOWERS_SOURCE=<dir>` и флаг `--superpowers-from` не передан
|
||
- **THEN** источник берётся из переменной; поведение совпадает с флагом
|
||
|
||
#### Scenario: Флаг важнее переменной
|
||
- **WHEN** заданы и `--superpowers-from`, и `DSH_SUPERPOWERS_SOURCE`
|
||
- **THEN** используется каталог из флага
|
||
|
||
#### Scenario: Невалидный явный источник
|
||
- **WHEN** `--superpowers-from` указывает на каталог без
|
||
`using-superpowers/SKILL.md`
|
||
- **THEN** `--skills` печатает `FAIL` с ожидаемой структурой и завершается
|
||
кодом 1, ничего не копируя из legacy-источников
|
||
|
||
#### Scenario: Пиннинг в ~/.dsh
|
||
- **WHEN** существует `$DSH_HOME/superpowers/skills/using-superpowers/SKILL.md`
|
||
и флаг/переменная не заданы
|
||
- **THEN** источником служит этот каталог, `--check` печатает
|
||
`ok: superpowers source (<path>)`
|
||
|
||
### Requirement: Отсутствие источника не бывает тихим
|
||
Если источник superpowers не найден, `--skills` MUST различать первичную и
|
||
повторную установку и MUST NOT завершаться успехом молча.
|
||
|
||
- Если `$DSH_HOME/skills/using-superpowers/SKILL.md` уже существует —
|
||
`WARN` «источник не найден, копии сохранены» и код 0 (идемпотентный повтор).
|
||
- Если копий нет — `FAIL` с готовой командой получения источника
|
||
(`git clone --depth 1 https://github.com/obra/superpowers ~/.dsh/superpowers`)
|
||
и код возврата 1.
|
||
- Локальные скиллы обвязки (`dsh/skills/*`: `role`, `sdd`) MUST ставиться в
|
||
обоих случаях: они не зависят от superpowers.
|
||
|
||
#### Scenario: Первая установка без источника
|
||
- **WHEN** `HOME` пуст, `$DSH_HOME/skills` не существует, источника нет
|
||
- **THEN** `--skills` печатает `FAIL`, код 1, но `$DSH_HOME/skills/role/SKILL.md`
|
||
и `$DSH_HOME/skills/sdd/SKILL.md` на месте
|
||
|
||
#### Scenario: Повторная установка без источника
|
||
- **WHEN** `$DSH_HOME/skills/using-superpowers/SKILL.md` уже есть, источника нет
|
||
- **THEN** `--skills` печатает `WARN`, код 0, установленные скиллы не удалены
|
||
|
||
### Requirement: ~/.claude — только legacy-fallback с предупреждением
|
||
superpowers-скиллы и роли MUST иметь рабочий путь `~/.dsh`; пути `~/.claude`
|
||
SHALL оставаться fallback'ом для машин, где `--skills --roles` ещё не
|
||
перезапускали, и MUST сопровождаться предупреждением.
|
||
|
||
- Установка: legacy-кэш Claude Code и `~/.claude/skills` допустимы как
|
||
источник, но `--skills` печатает `WARN: legacy superpowers source` с
|
||
подсказкой перейти на пиннинг/флаг.
|
||
- `--check`: legacy-источник — `WARN`, явный/пиннинг — `ok`, отсутствие —
|
||
`WARN` с подсказкой, невалидный явный источник — `FAIL` и код 1
|
||
(пользователь задал его сам, подсказка «нет источника» здесь неверна).
|
||
- Runtime: bootstrap и резолвер ролей сохраняют порядок `~/.dsh` → `~/.claude`,
|
||
но при выборе legacy-пути один раз за процесс пишут в лог предупреждение.
|
||
- Удаление fallback'ов — отдельное изменение; в этом change они не удаляются.
|
||
|
||
#### Scenario: Legacy-кэш как источник установки
|
||
- **WHEN** в `HOME` есть только кэш Claude Code с superpowers, `$DSH_HOME` пуст
|
||
- **THEN** `--skills` копирует скиллы и печатает `WARN: legacy superpowers source`
|
||
|
||
#### Scenario: Runtime-предупреждение
|
||
- **WHEN** bootstrap резолвит `using-superpowers` из `~/.claude/...`
|
||
- **THEN** в лог один раз за процесс попадает предупреждение с предложением
|
||
выполнить `dsh/install.sh --skills`
|
||
|
||
#### Scenario: ~/.dsh приоритетнее
|
||
- **WHEN** существуют и `~/.dsh/skills/using-superpowers/SKILL.md`, и legacy-копия
|
||
- **THEN** используется `~/.dsh`, предупреждения нет
|
||
|
||
### Requirement: Установленные инструкции DSH не ссылаются на ~/.claude
|
||
`dsh/install.sh --global` MUST писать `$DSH_HOME/AGENTS.md` так, чтобы пути
|
||
ролей указывали на DSH-слой, а формат инструкций не выдавался за runtime
|
||
Claude Code.
|
||
|
||
- Строки `~/.claude/roles` в установленной копии MUST заменяться на
|
||
`~/.dsh/roles`, а adapter-шапка MUST NOT называть пути `~/.claude`: в
|
||
установленном файле не остаётся ни одного такого пути. `global/CLAUDE.md` в
|
||
репозитории MUST NOT меняться (его читает Claude Code).
|
||
- Шапка установленного файла MUST говорить, что проектный `CLAUDE.md` /
|
||
`AGENTS.md` — это формат файлов инструкций DSH, а не запущенный Claude Code,
|
||
и что роли лежат в `~/.dsh/roles` (`--roles`), а superpowers-скиллы — в
|
||
`~/.dsh/skills` (`--skills`).
|
||
- Повторный `--global` обязан делать бэкап прежнего `AGENTS.md` (как сейчас).
|
||
|
||
#### Scenario: Пути ролей после установки
|
||
- **WHEN** выполнен `--global` во временный `DSH_HOME`
|
||
- **THEN** в `AGENTS.md` есть `~/.dsh/roles/dev.md` и нет ни одного пути
|
||
`~/.claude`
|
||
|
||
#### Scenario: global/CLAUDE.md не тронут
|
||
- **WHEN** выполнен `--global`
|
||
- **THEN** `global/CLAUDE.md` в репозитории побайтно не изменился
|
||
|
||
### Requirement: Чистый HOME без ~/.claude проходит установку
|
||
Установка, bootstrap и skill `role` MUST работать на машине, где Claude Code
|
||
никогда не устанавливался.
|
||
|
||
- `--global --skills --roles` с явным источником superpowers в пустом `HOME`
|
||
MUST создавать `$DSH_HOME/{AGENTS.md,skills/using-superpowers/SKILL.md,skills/role/SKILL.md,skills/sdd/SKILL.md,roles/dev.md}`.
|
||
- bootstrap MUST резолвить скилл из `$DSH_HOME/skills` при `home` этого HOME и
|
||
MUST NOT обращаться к `~/.claude`.
|
||
- Резолвер ролей MUST находить `$DSH_HOME/roles` при `home` этого HOME.
|
||
|
||
#### Scenario: Установка в чистый HOME
|
||
- **WHEN** `HOME` — пустой temp-каталог, `DSH_HOME=$HOME/.dsh`,
|
||
`--superpowers-from` указывает на каталог superpowers
|
||
- **THEN** `--global --skills --roles` завершается кодом 0, все перечисленные
|
||
файлы на месте, `--check` зелёный по skills и roles
|
||
|
||
#### Scenario: Bootstrap в чистом HOME
|
||
- **WHEN** `prepareBootstrap({ home: <temp HOME> })` вызывается после установки
|
||
- **THEN** выбранный путь — `$HOME/.dsh/skills/using-superpowers/SKILL.md`,
|
||
текст содержит маркер `<!-- DSH-HARNESS-BOOTSTRAP:... -->`, предупреждений о
|
||
legacy нет
|