hermes-plugin-development

Hermes Plugin Development

When to use

Load this skill when creating, modifying, debugging, reviewing, or releasing a standalone/native Hermes plugin. It especially applies when a plugin reads profile config or secrets, registers model tools or bundled skills, supports gateway multiplexing, or must load from HERMES_HOME/plugins/<slug> rather than from a development checkout.

Core design rules

1. Keep plugin capability at the edge; do not patch Hermes core for plugin-specific behavior.
2. Handlers return Hermes-compatible JSON strings unless the runtime contract explicitly requires an exception to propagate.
3. Keep model-facing schemas minimal. Tenant/project/profile authority comes from the active runtime profile, never caller-supplied model arguments.
4. Use Hermes-native profile resolution and credential scoping whenever available. Standalone fallbacks are compatibility paths, not alternate authority chains.
5. Fail closed before network or filesystem mutation when required profile config, credentials, or scope is absent.
6. Keep plugin.yaml tool/skill declarations exactly synchronized with real registrations.
7. Bundle skills using paths derived from the loaded package/plugin root; do not rely on the checkout working directory.

Strict-TDD workflow

1. Inspect the plugin manifest, registration entry point, schemas, handlers, config/secret helpers, and existing real-loader test.
2. Write one focused failing behavior test first and run it to record RED.
3. For security boundaries, include hostile ambient state and cross-profile adversarial fixtures rather than only happy-path mocks.
4. Make the smallest production change that turns the focused test GREEN.
5. Repeat for each independent behavior; do not batch unobserved production fixes ahead of tests.
6. Run the focused suite, then the complete plugin suite.
7. Run a real temporary-HERMES_HOME PluginManager.discover_and_load() smoke without adding the plugin directory to PYTHONPATH.
8. Compare exact loader registrations against the manifest, inspect git diff --check, stage only plugin-owned files, commit, and rerun post-commit verification.

Profile and multiplex safety

For any profile-aware plugin, treat the process environment as hostile ambient state under multiplexing:

• Active config/home must follow Hermes' ContextVar-scoped home resolver.
• Active credentials must follow Hermes' ContextVar-scoped secret resolver.
• An unscoped credential read in multiplex mode must remain a loud fail-closed error; generic handler wrappers must not swallow it.
• Non-secret routing values must come from the active profile's config.yaml, not process-global plugin env vars.
• Missing Gate/service URLs and tenant/project references must never fall back to localhost or placeholders such as current.

See references/multiplex-profile-isolation.md for the adversarial fixture, exact fallback rules, central tenant/project resolver pattern, and loader/manifest verification recipe.

Real loader compatibility gate

Copy the complete plugin into a temporary HERMES_HOME/plugins/<slug>, enable it in temporary config.yaml, and invoke the installed Hermes repository's real PluginManager. Set PYTHONPATH to Hermes only. Assert:

• plugin enabled with no loader error;
• exact expected tool names/count;
• exact qualified bundled skill names;
• representative handler behavior; and
• continued behavior across a second handler call.

A test-only PYTHONPATH=<plugin-dir> is invalid evidence because it can hide imports that fail under Hermes' namespaced directory loader.

Review checklist

• [ ] Test was observed failing before each production behavior change.
• [ ] No direct process-global profile routing under Hermes.
• [ ] No scoped-secret fallback after empty/error/unscoped reads.
• [ ] No model-selectable tenant/project authority.
• [ ] No localhost or current tenant fallback.
• [ ] Required config fails before I/O with redacted errors.
• [ ] Tool wrappers preserve fail-closed scope exceptions.
• [ ] Manifest equals real registrations.
• [ ] Focused tests, full plugin suite, and real loader smoke pass.
• [ ] Final staged paths are plugin-owned and git diff --check passes.

Common pitfalls

• Reading HERMES_HOME directly and therefore ignoring the per-turn override.
• Reading secret env vars directly and leaking another profile's process-global value.
• Catching UnscopedSecretError in a broad JSON error wrapper.
• Treating a default localhost URL as harmless configuration convenience.
• Duplicating project-reference fallback logic across tool modules.
• Verifying direct imports but never exercising Hermes' directory-plugin loader.
• Checking that one tool loaded while leaving plugin.yaml stale for several others.