# Agent Guidelines for hermes-chatto-plugin

## Tests

`adapter.py` importiert aus `gateway.*` — das ist der Hermes Agent, nicht dieses
Repo. Ohne dessen Quellcode auf dem `PYTHONPATH` bricht schon das Einsammeln der
Tests mit `ModuleNotFoundError: No module named 'gateway'` ab. Also den Hermes
Agent selbst herunterladen und bereitlegen, bevor du Tests ausführst:

```bash
git clone https://github.com/NousResearch/hermes-agent.git /tmp/hermes
PYTHONPATH=/tmp/hermes uv run --with pyyaml pytest -q
```

`pyyaml` wird von `gateway.config` gebraucht und steckt nicht in unseren
Dev-Dependencies. Liegt der Checkout schon irgendwo, den Pfad einfach
wiederverwenden statt neu zu klonen.

## Capabilities

**Erweiterst du die Fähigkeiten des Adapters, pflege das Startup-Banner mit.**

Beim Registrieren loggt `_capabilities()` (in `adapter.py`), was das Plugin kann
— damit man beim Start sieht, was zur Verfügung steht, statt es aus dem Code
lesen zu müssen. Ob eine Fähigkeit als vorhanden gilt, wird aus echten Overrides
abgeleitet: sie zählt nur, wenn `ChattoAdapter` die Methode von
`BasePlatformAdapter` ersetzt. Das Label dazu steht aber in `_CAPABILITY_LABELS`
und wird *nicht* automatisch gefunden.

Beim Hinzufügen einer überschriebenen `BasePlatformAdapter`-Methode also:

1. Eintrag in `_CAPABILITY_LABELS` ergänzen (Methodenname → Bezeichnung, die für
   jemanden ohne Codekenntnis Sinn ergibt). Ohne diesen Schritt kann das Plugin
   die Sache zwar, sagt es aber nirgends.
2. Prüfen, ob der `platform_hint` in `register()` sie erwähnen muss. Der Hint
   geht in den System-Prompt und ist das Einzige, woraus das Modell erfährt, was
   der Kanal kann — fehlt der Hinweis, behilft sich der Agent mit der Shell.
3. Test in `TestRegistration` ergänzen, falls die Fähigkeit nutzerseitig sichtbar
   ist.

Umgekehrt gilt dasselbe: fällt eine Methode weg, verschwindet ihre Zeile von
selbst aus dem Log — der Eintrag in `_CAPABILITY_LABELS` sollte dann trotzdem
mit raus.

## Shell Scripts

**Always run `shellcheck` after editing any shell scripts.**

```bash
shellcheck path/to/script.sh
```

Or validate all shell scripts in the project:

```bash
find . -name "*.sh" -exec shellcheck {} \;
```

### Configuration

Project-specific shellcheck rules are defined in `.shellcheckrc`. Default severity is `error` to catch all issues.

### Why

- Prevents syntax errors and common pitfalls (e.g., missing quotes, unsafe variable expansions)
- Ensures portability across different shell environments
- Maintains code quality and security standards

### Integration

Consider adding a pre-commit hook for automatic validation:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.9.0
    hooks:
      - id: shellcheck
        args: [--severity=error]
```