These principles are the external anchor for the ralplan loop. Every Planner, Architect, and Critic subagent must read and honor them.
The bridge failed for 1.5 hours not because MQTT was broken, but because
the publish topic was hermes/agents/vader/dusk/req when the receiver
subscribed to hermes/agents/vader/dusk/msg. One token. The transport
was proven before the contract was verified. V2 must make the contract
visible, discoverable, and impossible to get wrong by accident.
The first bridge shipped CONNACK honesty, PUBACK round-trips, secret files, SHA-256 parity protocols, and a public topic API — all correct. None of it mattered because the contract was wrong. V2 must front-load contract verification (peer discovery, topic alignment check) before building infrastructure around a possibly-wrong contract.
V1 required: manual pip install, creating ~/.hermes/.env.bridge
with mode 600, rotating secrets by hand, and knowing the topic tree.
V2 must be: pip install conduit && conduit send --to dusk --method research --params '{...}' — one command, zero config, zero secrets
for public brokers. Config is additive, not prerequisite.
_connect() blocks on CONNACK rc=0. send blocks on PUBACK round-trip.
No phantom ok:true. No pending.json entries for undelivered messages.
This is non-negotiable. V2 carries this forward without compromise.
The Hermes agent doesn't need a CLI — it needs a skill that tells it when to delegate, how to send, how to poll, and what the contract looks like. The skill is the primary interface; the CLI is for operators and debugging. The skill must encode the contract so agents never have to guess topic trees.
Public broker → anonymous. Default topic convention → Hermes. Default
envelope → {request_id, from, to, method, params, ts}. Default agent
id → auto-detected from hostname or config. Everything configurable,
nothing required.
V1 was hardcoded for Vader→Dusk. V2 must work with any agent id. Peer discovery, topic construction, and inbox subscription must all be parameterized on agent id, not baked into the source.
V1 connects, publishes, and disconnects for every operation. V2 should support a long-lived connection with keepalive, reducing latency and broker load for frequent delegations.
If the target peer is offline, the message should be queued (locally or on the broker via retained messages) rather than dropped or reported as delivered. The honest transport must distinguish "broker accepted" from "peer received."
V1 was over-built for a contract it didn't know. V2 must ship the minimum: working CLI, working skill, working contract discovery. Add persistence, retry, encryption, and multi-hop routing only when real usage demands it. Pitfall #8 from hermes-agent-skill-authoring applies to the entire project, not just the skill.