Claude Env Setup

---
name: claude-env-setup
description: "Установка и обновление рабочего окружения агента: скилы, правила и команды этого набора плюс связанные инструменты (MCP-серверы, плагин EDT, локальная транскрибация, конвертеры документов, утилиты 1С). Работает и на чистой машине, и на уже настроенной - сначала снимает опись того, что стоит, потом показывает план и ставит ТОЛЬКО выбранное. Используй когда пользователь просит поставить или обновить скилы, настроить окружение с нуля, перенести набор на новую машину, доставить недостающие инструменты, проверить что из окружения отвалилось. Триггеры: установить скилы, настроить окружение, поставить на новой машине, обновить набор, доставить недостающее, что у меня стоит, проверить окружение, перенести конфигурацию агента."
argument-hint: "[install|update|check] [--only <компонент,...>]"
allowed-tools:
  - Bash
  - PowerShell
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
---

# Установка и обновление окружения агента

Ставит набор из этого репозитория и связанные с ним инструменты. Два сценария - **чистая машина**
и **дозагрузка на рабочей** - обслуживаются одним и тем же путем: сперва опись, потом план, потом
установка выбранного. Режим не спрашивается у пользователя, а выводится из описи.

> **Главное правило: не сломать то, что уже работает.** На рабочей машине у пользователя есть свои
> скилы, свои правки в наших, свои MCP-серверы и запущенные сеансы. Ни один шаг не имеет права
> перезаписать чужое молча. Механика защиты - `references/safety.md`, она обязательна к прочтению
> перед первой записью в любой файл конфигурации.

## Порядок работы

### Шаг 1. Опись

Снять фактическое состояние машины. Не спрашивать пользователя о том, что можно посмотреть.

```bash
# что уже установлено из набора
ls ~/.claude/skills ~/.claude/rules ~/.claude/commands 2>/dev/null | head -50
# конфигурация MCP: два разных файла, оба важны
python -c "import json,pathlib;p=pathlib.Path.home()/'.claude'/'settings.json';print(sorted(json.loads(p.read_text(encoding='utf-8')).get('mcpServers',{}))) if p.exists() else print('нет settings.json')"
python -c "import json,pathlib;p=pathlib.Path.home()/'.claude.json';print(sorted(json.loads(p.read_text(encoding='utf-8')).get('mcpServers',{}))) if p.exists() else print('нет .claude.json')"
# что реально отвечает
docker ps --format "{{.Names}}|{{.Image}}|{{.Ports}}|{{.Status}}" 2>/dev/null
# инструменты
node --version; python --version; git --version; ffmpeg -version 2>/dev/null | head -1
```

Занятость портов (Windows):

```powershell
# 12250 - порт AI-EDT по умолчанию; фактический берется из .mcp.json рабочей области, если файл есть
foreach ($p in 8002,8003,8004,8007,8008,8009,12250,6003,1234) {
  $c = Get-NetTCPConnection -LocalPort $p -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1
  if ($c) { "{0}: занят, PID {1} ({2})" -f $p, $c.OwningProcess, (Get-Process -Id $c.OwningProcess -EA SilentlyContinue).ProcessName }
  else { "$p : свободен" }
}
```

**Критерий завершения шага:** по каждому компоненту из `references/components.md` состояние известно -
одно из: `нет`, `есть и отвечает`, `есть, но не отвечает`, `есть, версия отличается`, `конфликт`
(порт или имя занято чужим). Компонент без определенного состояния - не "нет", а повод посмотреть
внимательнее.

### Шаг 2. План

Показать таблицу и **получить явный выбор пользователя**. Ничего не ставить до ответа.

```
| Компонент             | Сейчас                  | Предлагается            |
|-----------------------|-------------------------|-------------------------|
| скилы набора          | 61 из 104, 3 расходятся | доставить 43, 3 показать |
| ai-edt                | отвечает на 12250       | не трогать              |
| transcribe            | нет venv-whisper        | поставить (setup.py)    |
| 1c-syntax-checker-mcp | порт 8002 занят чужим   | разобраться, не ставить |
```

Правила плана:
- **Расхождение в существующем файле - не повод перезаписать.** Показать `diff`, спросить: оставить
  пользовательскую версию, взять версию набора, или слить руками.
- **Ничего лишнего.** Компонент, который не нужен пользователю, не ставится, даже если "полезен".
  Спрашивать группами (см. `references/components.md`, колонка "группа"), а не по одному из тридцати.
- Если чего-то не хватает как предусловия (нет Node, нет Docker, нет платформы 1С) - сказать прямо и
  не пытаться поставить зависимый компонент.

**Критерий завершения шага:** есть явный список выбранного пользователем. Пустой список - тоже
результат, тогда работа закончена.

### Шаг 3. Установка

Ставить по одному компоненту, в порядке зависимостей (`references/components.md`). После каждого -
его проверка из того же файла. Упавший компонент **не останавливает остальные**: пометить и идти
дальше, в итоге честно перечислить, что не встало и почему.

Агенты, хуки и инструменты набора (`agents/`, `hooks/`, `tools/`) ставятся не копированием, а
исполняемым установщиком из корня репозитория - он ведет манифест установленных файлов и не
затирает измененное снаружи:

```bash
python tools/install_home.py install --components agents,hooks,tools,commands   # установка
python tools/install_home.py --check                                    # 0 - совпадает с репозиторием
```

Обязательное перед первой записью: `references/safety.md` (резервные копии, слияние JSON вместо
перезаписи, что нельзя трогать никогда).

**Критерий завершения шага:** по каждому выбранному компоненту известен исход - `поставлен`,
`обновлен`, `пропущен (причина)`, `не встал (причина)`.

### Шаг 4. Проверка и отчет

Прогнать проверки установленного (не "должно работать", а фактический вызов). Затем отчет:

- что поставлено и обновлено;
- что не встало и почему, с конкретной следующей шагом для пользователя;
- что требует его действий руками (перезапуск Claude Code для подхвата MCP, вход в EDT, ключи API);
- что осталось нетронутым по его же решению.

**Критерий завершения шага:** ни одного "вероятно работает". Компонент либо проверен вызовом, либо
явно помечен как непроверяемый в этой среде (нет GPU, нет платформы 1С, нет сети).

## Что НЕ делает этот скил

- Не переносит пользовательские данные: голосовую базу `transcribe/voiceprints/`, `.env` с ключами,
  память проектов, планы. Их пользователь копирует сам - скил только напоминает.
- Не удаляет ничего. Даже устаревшие компоненты только помечаются в отчете.
- Не чинит сломанное окружение вслепую. Порт занят чужим процессом, контейнер unhealthy, venv
  битый - это диагноз в отчет, а не повод сносить и ставить заново.
- Не трогает запущенные сеансы 1С и EDT.

## Справочники

- `references/components.md` - каталог компонентов: что это, откуда берется, как обнаружить, как
  поставить, как проверить, какие грабли. Читать при работе с конкретным компонентом.
- `references/safety.md` - механика безопасности: резервные копии, слияние конфигов, порядок отката,
  список того, что нельзя трогать. Читать ДО первой записи.