gaelic-ghost Choose Hermes Agent Workflow
Classify the requested outcome before opening broad documentation or changing configuration.
Route the Request
| Requested outcome | Use |
|---|---|
| Install, update, configure, run, secure, troubleshoot, or use Hermes | operate-hermes-agent |
| Create skills, plugins, providers, tools, hooks, desktop/dashboard extensions, or programmatic integrations | build-hermes-agent-extensions |
| Run Hermes inside Zed, Xcode, or another ACP client | operate-acp-agent-integration plus the client-owning workflow |
| Let Hermes discover, call, or be called by an independently operated peer agent | operate-a2a-agent-integration plus gateway operation for inbound service lifecycle |
| Decide between ACP, MCP, TUI gateway, API, terminal, or native host integration | choose-agent-integration-protocol |
| Run a messaging gateway, API server, webhook intake, messaging platform, or long-lived remote agent | operate-hermes-agent-gateway |
| Use Nous Portal, Tool Gateway, Nous Chat, subscription proxy, or Hermes Cloud | use-nous-research-services |
| Export Socket skills, translate Socket MCP, or classify Codex-to-Hermes portability | hermes-agent-compatibility |
Use more than one workflow when the request genuinely crosses boundaries. Keep one workflow in charge of each write surface.
Keep the Three Gateway Terms Separate
Hermes messaging gateway: the long-running Hermes process that connects messaging platforms, webhooks, and the API server.Nous Tool Gateway: Nous-hosted backends for web, media, browser, and optional cloud terminal tools.TUI gateway: the JSON-RPC protocol used by Hermes TUI and custom host integrations.ACP: the editor-to-agent protocol used when Zed, Xcode, or another client launches and renders Hermes throughhermes acp.A2A: the peer-agent protocol used when Hermes exchanges discovered messages or tasks with independently operated agents.
Never use an unqualified “gateway” in a decision or implementation note when more than one meaning is possible. Do not describe ACP as a gateway or as a general agent-to-agent protocol.
Select the Smallest Extension Surface
Prefer, in order:
- A skill for instructions plus existing tools or commands.
- MCP for an external tool server.
- Config-driven backends or shell hooks when Hermes already defines that surface.
- A standalone Python plugin for registered runtime behavior.
- A specialized provider, platform, memory, context, browser, search, media, secret, desktop, or dashboard extension only when that exact subsystem owns the behavior.
- A Hermes core contribution only when the behavior belongs in the upstream product rather than a user, project, or third-party extension.
Source and State Rules
- Refresh the official Hermes docs for claims that can drift; the project moves quickly.
- Inspect the installed Hermes version and active profile before diagnosing local behavior.
- Keep
~/.hermes/user state, project.hermes/state, standalone plugin source, and the upstream Hermes repository distinct. - Do not mutate Portal accounts, gateway services, messaging accounts, cloud deployments, or user-home configuration unless the user requested that action.
- Do not describe a Codex or Claude plugin manifest as a Hermes plugin.
Output Contract
Return:
workflow: the selected skill or combination.surface: the concrete Hermes runtime, configuration, hosted service, or source tree involved.reason: why that surface owns the request.state: local, project, hosted, or upstream state that may change.verification: the narrowest proof needed.
Read references/workflow-map.md when the request crosses multiple Hermes subsystems or uses an ambiguous “gateway,” “plugin,” “cloud,” or “provider” label.