# Harness 🛠️

**Универсальный менеджер скиллов, агентов, MCP-серверов и конфигов для Hermes и OpenCode.**

Репа-каталог, где живут ссылки на полезные skills, MCP-серверы, тулзы и агенты — с единым скриптом управления.

```
dev/harness/
├── agents/               # Определения агентов OpenCode (leader, fixer, devops, admin, ...)
├── catalog/              # Скиллы: git submodule'ы на внешние репы
│   └── jakubkrehel-skills/  # submodule → github.com/jakubkrehel/skills (11 скиллов UI)
├── scripts/
│   └── harness           # Основной CLI-скрипт
└── README.md
```

## Быстрый старт

```bash
./scripts/harness status            # Статус всей среды
./scripts/harness list catalog      # Что есть в каталоге скиллов
./scripts/harness list skills       # Установленные скиллы
./scripts/harness list agents       # Агенты: доступные в репо + установленные
./scripts/harness list mcp          # MCP-серверы Hermes
```

## Команды

### Установка скиллов

```bash
# Установить скилл из каталога
./scripts/harness install skill jakubkrehel-skills better-ui --target opencode
./scripts/harness install skill jakubkrehel-skills better-ui --target hermes
./scripts/harness install skill jakubkrehel-skills better-ui --target all

# Можно писать через слэш
./scripts/harness install skill jakubkrehel-skills/better-ui --target all

# Все скиллы из репозитория разом
./scripts/harness install skill jakubkrehel-skills --all --target opencode
./scripts/harness install skill jakubkrehel-skills --all --target all
```

Скиллы ставятся симлинками в соответствующие директории:

| Агент | Куда ставится |
|-------|--------------|
| Hermes | `~/.hermes/skills/catalog/<name>/` |
| OpenCode | `~/.claude/skills/<name>/` |
| OpenCode | `~/.config/opencode/skills/<name>/` |

### Управление скиллами

```bash
./scripts/harness list skills                 # Все скиллы
./scripts/harness list skills --target hermes # Только Hermes
./scripts/harness remove skill better-ui      # Удалить отовсюду
./scripts/harness remove skill better-ui --target hermes
```

### Агенты (только OpenCode)

Источник — `harness/agents/*.md`. Имя агента = имя файла без `.md`.

```bash
# Список: что есть в репо + что уже установлено
./scripts/harness list agents
./scripts/harness list agents --scope global          # только глобальные
./scripts/harness list agents --scope project --project ~/work/myrepo

# Установить одного / всех
./scripts/harness install agent leader                # в ~/.config/opencode/agents/
./scripts/harness install agent --all --scope global  # всех, глобально
./scripts/harness install agent devops --scope project --project ~/work/myrepo

# Удалить
./scripts/harness remove agent leader                 # отовсюду
./scripts/harness remove agent leader --scope global
```

| `--scope` | Куда ставится |
|-----------|--------------|
| `global` (по умолчанию) | `~/.config/opencode/agents/<name>.md` |
| `project` | `<project>/.opencode/agents/<name>.md` (по умолчанию — cwd) |

Ставятся симлинками, так что правки в репе сразу видны OpenCode. Все агенты имеют
`mode: all` (кроме `leader` — `primary`), чтобы лидер мог вызывать их как сабагентов.

> **Hermes агентов не поддерживает** — только runtime-делегирование через
> `delegate_task`. Пользовательских определений агентов у него нет, поэтому
> `install agent` работает только для OpenCode.

### MCP-серверы (Hermes)

```bash
# Добавить MCP по URL (HTTP SSE)
./scripts/harness configure hermes mcp add my-server http://localhost:8000/mcp

# Добавить MCP через команду (STDIO)
./scripts/harness configure hermes mcp add github npx \
  --env GITHUB_TOKEN=ghp_xxx \
  --arg -y --arg @modelcontextprotocol/server-github

# Список MCP
./scripts/harness list mcp

# Удалить MCP
./scripts/harness configure hermes mcp rm my-server
```

### Конфигурация Hermes

```bash
# Посмотреть конфиг
./scripts/harness configure hermes

# Установить параметры
./scripts/harness configure hermes --set model.default=gpt-4o
./scripts/harness configure hermes --set model.provider=openai
./scripts/harness configure hermes --set agent.max_turns=200
```

После изменения конфига скрипт автоматически перезапускает Hermes.

### Установка/обновление бинарников

```bash
./scripts/harness install opencode   # curl-установщик opencode.ai
./scripts/harness install hermes     # hermes update + рестарт сервисов
```

### Перезапуск

```bash
./scripts/harness restart hermes   # systemctl --user restart hermes-gateway + webui
./scripts/harness restart opencode # systemctl --user restart opencode + openchamber
```

### Обновление каталога

```bash
./scripts/harness update catalog   # git pull во всех репах внутри catalog/
```

## Как добавить скилл в каталог

Каталог — это **git submodule'ы**: в репе фиксируется ссылка на внешний репозиторий
и точный коммит, а не копия файлов.

```bash
git submodule add https://github.com/user/skills-repo.git catalog/user-skills
git commit -m "chore: add user-skills to catalog"
```

После этого `harness list catalog` покажет все найденные скиллы, а
`harness update catalog` подтянет свежие коммиты во всех submodule'ах.

Обычный клон (`git clone` внутрь `catalog/`) тоже работает — `update catalog`
обновит его через `git pull`, но такой каталог не попадёт в коммит репы
(вложенная репа не станет submodule автоматически).

## Как добавить агента

Положить `.md` файл в `agents/` репозитория — и он сразу виден через `harness list agents`.

Формат — как у OpenCode:

```markdown
---
description: "Что делает агент и когда его звать"
mode: all            # primary | subagent | all
temperature: 0.1
steps: 100
color: "#2563eb"
permission:
  task: deny
  bash: allow
  edit: allow
---

# Имя агента

Тело промпта: роль, принципы, порядок работы, что НЕ делать, формат ответа.
```

- `mode: all` — можно и вызвать напрямую, и делегировать из `leader` (сабагент).
- `mode: primary` — только как основной агент (Tab в UI). Такой агент **не** появится
  в `task`-инструменте лидера: OpenCode фильтрует список сабагентов по `mode !== "primary"`.

## Поддерживаемые форматы

- **Скиллы** — `SKILL.md` с YAML frontmatter (`name`, `description`); родной формат OpenCode и Hermes.
  Скиллы из `catalog/*/skills/<name>/SKILL.md` видны через `harness list catalog`.
- **Агенты** — `<name>.md` с frontmatter (`description`, `mode`, ...); формат OpenCode.
  Лежат в `agents/<name>.md`.

## Совместимость

| Фича | Hermes | OpenCode |
|------|--------|----------|
| Skills (SKILL.md) | ✅ `~/.hermes/skills/` | ✅ `~/.claude/skills/`, `~/.config/opencode/skills/` |
| Agents | ❌ (только `delegate_task` в рантайме) | ✅ `~/.config/opencode/agents/`, `<project>/.opencode/agents/` |
| MCP-серверы | ✅ `config.yaml mcp_servers` | 🟡 через `opencode.json` |
| Plugins | ✅ `.hermes/plugins/` | ❌ (не поддерживает) |
| Systemd service | ✅ gateway + webui | ✅ opencode + openchamber |
| CLI install/update | `hermes update` | curl install script |