# Déploiement Superpowers (obra/superpowers) — Flotte Hermes Agent, Claude Code & Antigravity

**Instance auteur** : hermes-perso  
**Date** : 2026-08-18  
**Tags** : [hermes, superpowers, plugins, skills, tls, ssh, synology, claude-code, antigravity]  
**Statut** : valide

---

## Probleme

Déployer le framework de compétences et de méthodologie agentique **Superpowers** (`obra/superpowers`) de manière unifiée et sécurisée sur :
1. Les trois instances Hermes Agent NAS (`hermes-agent-nyora`, `hermes-agent-tt`, `hermes-agent-perso`) sous Docker.
2. Claude Code (extension VS Code / CLI).
3. Antigravity (`agy`).

Le déploiement sur le NAS a rencontré plusieurs blocages d'infrastructure critiques :
- Blocage réseau lors des requêtes/clones HTTPS vers `github.com` (handshake TLS 1.3 bloqué/timeout).
- Commandes `docker` introuvables lors des accès SSH non-interactifs.
- Présence d'un clone dormant précoce sur `hermes-agent-perso` sans support natif `.hermes-plugin`.

---

## Contexte et contraintes

- **Hôte** : Synology NAS DS920+ (DSM 7.x, Linux 4.4 kernel).
- **Conteneurs** : `nousresearch/hermes-agent:v2026.8.3` (UID 1026, GID 100, utilisateur `hermes`).
- **Gestionnaire de processus interne** : s6-overlay (`s6-rc`, `s6-supervise`).
- **Canari strict** : déploiement ordonné (`nyora` -> `tt` -> `perso`) avec tests Telegram bloquants (`@HermesNyoraBot`, `@HermesTTBot`, `@HermesPersoBot`). Tolérance zéro pour les régressions sur TT.

---

## Ce qui NE fonctionne PAS

| Tentative | Erreur obtenue | Raison de l'echec |
|-----------|----------------|-------------------|
| `hermes plugins install obra/superpowers` direct | `fatal: unable to access 'https://github.com/...': Failed to connect... Connection timed out` | Le handshake TLS 1.3 sortant vers `github.com` est intercepté/droppé sur le réseau NAS/Docker (CrowdSec / firewall Synology). Seul TLS 1.2 passe. |
| `docker exec ...` via SSH non-interactif | `sh: docker: command not found` (exit code 127) | Les sous-shells non-interactifs sur Synology DSM démarrent avec un `$PATH` minimal (`/usr/bin:/bin`) qui n'inclut pas `/usr/local/bin`. |
| Utilisation du clone existant `/opt/data/skills/superpowers` (du 17/06) | Inactif, non chargé par le plugin manager | Clone créé avant le support officiel Hermes Plugin (dossier `.hermes-plugin` absent). |
| `hermes skills update <nom>` pour découvrir de nouveaux skills | `No updates available` | La commande `skills update` ne découvre que les mises à jour de skills déjà installés, pas les nouveaux skills ajoutés à un tap distant. |

---

## Solution validee

### 1. Piège SSH PATH Synology

Toujours exporter explicitement le chemin `/usr/local/bin` dans toute commande SSH non-interactive :

```bash
ssh -p 22222 Best0f@192.168.100.33 "export PATH=/usr/local/bin:\$PATH; <commande>"
```

### 2. Contournement réseau TLS 1.2 (Système + Utilisateur)

Forcer Git en TLS 1.2 au niveau système (`/etc/gitconfig`) ET utilisateur (`/opt/data/home/.gitconfig`) dans chaque conteneur :

```bash
for c in hermes-agent-nyora hermes-agent-tt hermes-agent-perso; do
  docker exec $c git config --system http.sslVersion tlsv1.2
  docker exec -u hermes $c git config --global http.sslVersion tlsv1.2
done
```

### 3. Nettoyage du clone dormant sur hermes-agent-perso

Renommer le clone obsolète sans le supprimer :

```bash
docker exec hermes-agent-perso mv /opt/data/skills/superpowers /opt/data/skills/superpowers.STALE-pre-hermes-plugin-support-20260818
```

### 4. Déploiement canari séquentiel sur Hermes Agent

Pour chaque instance (`nyora`, puis `tt`, puis `perso`) :

```bash
# 1. Installation du plugin
docker exec -u hermes hermes-agent-<instance> hermes plugins install obra/superpowers --enable

# 2. Redémarrage du conteneur (chargement s6 propre)
docker restart hermes-agent-<instance>

# 3. Vérification locale
docker exec -u hermes hermes-agent-<instance> hermes plugins list --plain --no-bundled
docker logs --tail 40 hermes-agent-<instance>

# 4. Gate Bloquant Telegram : tester le bot correspondant avec une intention de création ("on va construire X")
# Confirmer le réflexe brainstorming avant de passer à l'instance suivante.
```

### 5. Claude Code (Extension VS Code & CLI)

Puisque le binaire `claude` est présent (`~/.local/bin/claude` — Cas A) :

```bash
claude plugin install superpowers@claude-plugins-official
```
*Note : Recharger la fenêtre VS Code (`Developer: Reload Window`) pour que l'extension prenne en compte le plugin partagé.*

### 6. Antigravity

Installation directe via le gestionnaire de plugins d'Antigravity :

```bash
agy plugin install https://github.com/obra/superpowers
```

---

## Verification

```bash
# 1. Hermes Agent
docker exec -u hermes hermes-agent-nyora hermes plugins list --plain --no-bundled
# Attendu: enabled user 6.3.0 superpowers

# 2. Claude Code
claude plugin list --json
# Attendu: "id": "superpowers@claude-plugins-official", "enabled": true

# 3. Antigravity
agy plugin list
# Attendu: "name": "superpowers", "components": ["skills", "hooks"]
```

---

## Pieges specifiques DSM / NAS

1. **TLS 1.3 dropping** : Tout outil effectuant des requêtes HTTPS directes vers GitHub (pip, npm, git) doit être configuré pour forcer TLS 1.2 si un timeout survient lors du handshake.
2. **Utilisateur hermes vs root** : `docker exec` exécute par défaut sous `root`. Les commandes `hermes plugins` et les fichiers de config utilisateur doivent impérativement être exécutés sous `-u hermes` (UID 1026) pour éviter des corruptions de permissions dans `/opt/data/`.
3. **Absence de hook post-compaction Hermes** : En cas de très longue session Telegram compactée dès son premier tour, le bootstrap Superpowers peut se désactiver. Ouvrir une session fraîche restaure l'amorçage.

---

## References

- [Repo upstream obra/superpowers](https://github.com/obra/superpowers)
- [Documentation Nous Research Hermes Agent](https://github.com/NousResearch/Hermes-Agent)
- [PROTOCOL-INFRA NAS DS920+](common/PROTOCOL-INFRA.md)