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:

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:

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.
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.
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.

shellcheck path/to/script.sh

Or validate all shell scripts in the project:

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:

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

AGENTS.md 2.8 KB Historik Rå