claude-harness/openspec/changes/dsh-superpowers-git/specs/dsh-install/spec.md

Spec Delta: dsh-superpowers-git

Purpose

dsh/install.sh --skills получает superpowers из git сам: первый запуск — клон, следующие — обновление до последнего коммита default-ветки. Явные источники остаются приоритетнее и не ходят в сеть; ~/.claude — по-прежнему legacy-fallback с предупреждением.

ADDED Requirements

Requirement: Свежий superpowers из git

dsh/install.sh --skills MUST получать superpowers-скиллы из git, когда явный источник не задан: клонировать при отсутствии клона и обновлять при каждом следующем запуске.

• Репозиторий по умолчанию — https://github.com/obra/superpowers; $DSH_SUPERPOWERS_REPO MUST переопределять его (зеркала, локальные репозитории в тестах) и MUST применяться к уже существующему клону: перед fetch URL origin приводится к заданному репозиторию.
• Клон — git clone --depth 1 <repo> $DSH_HOME/superpowers.
• Обновление — git -C $DSH_HOME/superpowers fetch --depth 1 origin и git reset --hard FETCH_HEAD; рабочее дерево управляемое, локальные правки там не сохраняются.
• После клона/обновления источником MUST считаться $DSH_HOME/superpowers/skills (или сам каталог), только если в нём есть using-superpowers/SKILL.md.
• Вывод --skills MUST называть источник и git-версию: (source: <path>, git <short-sha>).
• --check MUST NOT выполнять сетевые операции: он показывает состояние существующего клона (ok: superpowers source (<path>, git <sha>)) и не создаёт $DSH_HOME/superpowers.

Scenario: Первый запуск клонирует источник

• WHEN $DSH_HOME/superpowers отсутствует, DSH_SUPERPOWERS_REPO указывает на репозиторий superpowers
• THEN --skills клонирует его в $DSH_HOME/superpowers, копирует скиллы в $DSH_HOME/skills и печатает git <sha>

Scenario: Повторный запуск обновляет клон

• WHEN клон уже есть, а в источнике появился новый коммит со скиллом
• THEN повторный --skills обновляет клон до нового коммита, и новый скилл оказывается в $DSH_HOME/skills

Scenario: Нет сети, клон есть

• WHEN обновление клона не удалось (недоступный репозиторий), но $DSH_HOME/superpowers содержит using-superpowers/SKILL.md
• THEN --skills печатает WARN, использует кэш, копирует скиллы и завершается кодом 0

Scenario: Нет сети и нет клона

• WHEN клонирование не удалось, клона и других источников нет, $DSH_HOME/skills пуст
• THEN --skills печатает FAIL с репозиторием и подсказкой --superpowers-from, код 1; недоклонированный каталог не остаётся на диске

Scenario: Ручная копия без git

• WHEN $DSH_HOME/superpowers существует, не является git-клоном и содержит using-superpowers/SKILL.md
• THEN каталог используется как есть, --skills печатает WARN о том, что он не будет обновляться

Scenario: --check не ходит в сеть

• WHEN клон существует, а DSH_SUPERPOWERS_REPO указывает на недоступный репозиторий
• THEN --check печатает ok: superpowers source (<path>, git <sha>), завершается без сетевых ошибок и ничего не клонирует

MODIFIED Requirements

Requirement: Источник superpowers задаётся при установке

dsh/install.sh --skills SHALL разрешать источник superpowers-скиллов в порядке приоритета.

• Порядок: --superpowers-from <dir> → $DSH_SUPERPOWERS_SOURCE → git-клон $DSH_HOME/superpowers (обновить существующий или склонировать из $DSH_SUPERPOWERS_REPO/https://github.com/obra/superpowers) → legacy-кэш Claude Code → legacy ~/.claude/skills.
• Для явного источника (--superpowers-from, $DSH_SUPERPOWERS_SOURCE) допускаются обе формы: корень superpowers (есть skills/using-superpowers/SKILL.md) или сам каталог skills; сеть при явном источнике MUST NOT использоваться.
• Явно заданный, но невалидный источник MUST приводить к FAIL и коду возврата 1: тихий откат на git/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, ничего не копируя из git/legacy-источников

Scenario: Явный источник не трогает git

• WHEN --superpowers-from задан, а $DSH_HOME/superpowers отсутствует
• THEN --skills не создаёт $DSH_HOME/superpowers

Requirement: Отсутствие источника не бывает тихим

Если источник superpowers не найден, --skills MUST различать первичную и повторную установку и MUST NOT завершаться успехом молча.

• Если $DSH_HOME/skills/using-superpowers/SKILL.md уже существует — WARN «источник не найден, копии сохранены» и код 0 (идемпотентный повтор).
• Если копий нет — FAIL с репозиторием ($DSH_SUPERPOWERS_REPO) и подсказкой --superpowers-from <dir>; код возврата 1.
• Локальные скиллы обвязки (dsh/skills/*: role, sdd) MUST ставиться в обоих случаях: они не зависят от superpowers.

Scenario: Первая установка без источника

• WHEN HOME пуст, $DSH_HOME/skills не существует, git-источник недоступен и других источников нет
• 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 с подсказкой на git-источник или --superpowers-from.
• --check: legacy-источник — WARN, git-клон/явный источник — ok, отсутствие — WARN с подсказкой, невалидный явный источник — FAIL и код 1.
• Runtime: bootstrap и резолвер ролей сохраняют порядок ~/.dsh → ~/.claude, но при выборе legacy-пути один раз за процесс пишут в лог предупреждение.
• Удаление fallback'ов — отдельное изменение; в этом change они не удаляются.

Scenario: Legacy-кэш как источник установки

• WHEN в HOME есть только кэш Claude Code с superpowers, $DSH_HOME пуст, git-источник недоступен
• 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, предупреждения нет