aep/claude-harness
1
0
Fork 0
Code Issues 13 Pull Requests 3 Actions Packages Projects Releases Wiki Activity
claude-harness/openspec/specs/dsh-install/spec.md

10 KiB
Raw Blame History

dsh-install Specification

Purpose

Слой установки DSH-обвязки: откуда берутся superpowers-скиллы и роли, что делает dsh/install.sh --skills/--roles, какие пути попадают в установленные инструкции. В Claude Code источником служит кэш плагина в ~/.claude; в DSH источник задаётся установщиком явно (аргумент, переменная или пиннинг в ~/.dsh), а ~/.claude остаётся только legacy-fallback'ом с предупреждением. Контракт нужен, чтобы свежая установка на машине без Claude Code проходила полный цикл #48 и чтобы путь ~/.claude не возвращался в runtime незаметно.

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 нет