add Hermes plugin for Ponytail with command support and documentation

[salaamdev]

Issues

Closes #125
Closes #133

Summary

Adds native Hermes Agent plugin support to Ponytail, installable with one command, injects the active ruleset before every LLM turn, and exposes all Ponytail commands and skills through Hermes's plugin system.

Motivation

Hermes Agent is a gateway/agent framework with its own plugin API (hooks, skills, slash commands). This PR integrates Ponytail as a first-class Hermes plugin so Hermes users get the same always-on lazy-dev mode and command surface that Claude Code, Codex, OpenCode, Gemini, and pi users already have.

What it does

Install:

hermes plugins install DietrichGebert/ponytail --enable

Hooks registered:

• pre_llm_call — injects the mode-filtered Ponytail ruleset (from skills/ponytail/SKILL.md) as system context before each LLM turn. Supports lite/full/ultra modes, config via PONYTAIL_DEFAULT_MODE env or ~/.config/ponytail/config.json, and a review mode that loads the review skill.
• pre_gateway_dispatch — rewrites /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-help gateway slash commands into agent prompts (with access-control delegation to Hermes's _check_slash_access).

Slash commands:

• /ponytail [lite|full|ultra|off] — get/set runtime mode (process-local)
• /ponytail-review [target] — review diff for over-engineering
• /ponytail-audit [target] — whole-repo audit
• /ponytail-debt — harvest ponytail: shortcuts into a ledger
• /ponytail-help — quick reference

Skills: All bundled skills (ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-help) registered under the ponytail: namespace.

Files added/changed

File	Change
__init__.py	Plugin implementation (216 lines) — hooks, commands, skill registration, mode management, config resolution, gateway command rewriting
plugin.yaml	Plugin manifest — declares hooks, commands, and skills for hermes plugins install
after-install.md	Post-install instructions shown after hermes plugins install
tests/hermes-plugin.test.js	8 Node.js tests covering manifest consistency, skill registration, context injection, mode config, review mode, mode switching, gateway access denial, gateway rewrite
README.md	Agent count badge 13→14; Hermes install section; Commands host list updated
docs/agent-portability.md	Hermes Agent row added to adapter table

Testing

node --test tests/hermes-plugin.test.js

Tests verify:

• Manifest matches runtime skills/hooks/commands and package.json version
• All 5 skills registered under ponytail: namespace with correct SKILL.md paths
• build_injected_context('ultra') contains mode header, skill content, no frontmatter, no wrong-mode table rows
• Config resolution: PONYTAIL_DEFAULT_MODE env > config.json > default full; off returns empty; invalid command returns usage
• review mode loads the real review skill body
• /ponytail ultra changes mode, subsequent pre_llm_call injects ultra context
• Gateway rewrite returns null when _check_slash_access denies
• Gateway rewrite handles all skill commands and ignores unrelated text

Security note

In shared Hermes gateways, runtime mode (/ponytail) is process-local. Restrict /ponytail to trusted users with Hermes's slash-command access controls; the gateway rewrite hook delegates to _check_slash_access before rewriting commands.

Available commands in hermes after intalling the plugin

/ponytail
/ponytail ultra
/ponytail-review README.md
/ponytail-audit .
/ponytail-debt
/ponytail-help

[anupddas]

Hi @salaamdev,
Can I get more details please? Thanks.

[salaamdev]

Hi @salaamdev, Can I more details please? Thanks.

Working on it

[salaamdev]

Hi @salaamdev, Can I get more details please? Thanks.

hey i have updated the description of the pr with the detailed changes, i did not a stand alone docs since the readme changes are enough. let me know if there is anything else i should add/remove.

This has been tested with hermes connected to telegram/whatsapp and hermes cli

[anupddas]

Looks Good. Thanks @salaamdev