hermes-compatibility.md

Hermes Compatibility and Guardrails

This document makes the current Hermes support boundary explicit after the v1.8 provider-routed execution milestone. It should be read alongside Fork Ownership, Upstream Sync Workflow, and Hermes Install so future runtime work stays inside the approved seams.

Compatibility Matrix

Surface	Status	Validation evidence	Notes
Global Hermes install	supported	npm run test:hermes	--hermes --global writes command skills to ~/.hermes/skills/gsd-*/SKILL.md.
Project-linked external_dirs mode	supported	npm run test:hermes	--hermes --local writes .gsd-hermes/skills/gsd-*/SKILL.md and registers the absolute path in ~/.hermes/config.yaml under skills.external_dirs.
Hermes runtime selection in installer	supported	npm run test:hermes	Hermes is available through --hermes, runtime selection prompts, and --all.
Command discovery for /gsd-*	supported	npm run test:hermes	Phase 3 generates Hermes SKILL.md command skills with name: gsd-*; smoke with /gsd-help.
Core workflow execution	supported with degraded paths	npm run test:hermes	Covers new-project, discuss, plan, execute, verify, progress, settings, and update smoke coverage with documented fallbacks for unavailable Hermes runtime capabilities.
Update / uninstall / doctor	supported	npm run test:hermes	Phase 5 complete: global and project-linked lifecycle coverage includes reinstall updates, safe uninstall, read-only doctor diagnostics, and deterministic fixture coverage.
Upstream sync routine	supported maintenance workflow	npm run test:hermes plus npm test when feasible	Sync review stays anchored to governance docs and merge history from upstream/main so Hermes drift remains visible.
Native local Hermes install mode	out of scope	Documentation and docs tests	Project-linked mode uses skills.external_dirs instead.
Runtime model binding receipts	supported with conservative proof boundary	npm run test:hermes, tests/runtime-model-parity.test.cjs, SDK init tests	Resolver/workflow receipts and Hermes child-construction proof are supported; live provider wire-level enforcement is not claimed without sanitized provider request evidence.
Provider-routed CLI execution	supported with strict command-routing proof	npm run test:hermes, tests/hermes-provider-routing-regression.test.cjs, tests/provider-cli-dispatch.test.cjs	workflow.agent_execution_router: "provider-cli" routes OpenAI/GPT models to Codex CLI and Anthropic/Claude models to Claude Code CLI, or fails fast.

Runtime-Model Composition

Tracks how the Hermes v1.2 runtime-model adapter composes with upstream #2517 runtime-aware tier resolution (resolveTierEntry in get-shit-done/bin/lib/core.cjs) after the v1.3 sync. Composition contract per Phase 7 D-03: the Hermes adapter wraps upstream's resolver rather than replacing it, so runtime-aware token projection (Codex, OpenCode, etc.) stays available while Hermes-specific defaults remain Claude-safe.

Binding Path	Upstream #2517 Behavior	Hermes Adapter Post-Process	Example
model_overrides[agent] explicit	Skipped — overrides short-circuit before tier lookup.	Passes through as kind: 'explicit'; fully-qualified ID preserved.	model_overrides: { 'gsd-executor': 'openai/gpt-5.4' } → legacy/init token 'openai/gpt-5.4'.
profile: 'inherit'	Returns literal 'inherit' (upstream #2516 passthrough).	Legacy token 'inherit'; init token '' (empty per v1.2 semantics).	runtime: 'codex', model_profile: 'inherit' → legacy 'inherit', init ''.
resolve_model_ids: 'omit'	Not consulted — omit short-circuits in the Hermes adapter.	Returns empty token for both projections (kind: 'runtime-default').	resolve_model_ids: 'omit' → legacy '', init ''.
Runtime tier resolution	RUNTIME_PROFILE_MAP[runtime][tier] field-merge with model_profile_overrides.	If runtime is Claude-safe: alias (e.g. 'opus'); if runtime IS in KNOWN_RUNTIMES (codex, opencode, etc.): native ID (e.g. 'gpt-5.4').	runtime: 'codex', model_profile: 'quality' → 'gpt-5.4'.
workflow.cross_ai_execution: true	Not in upstream path.	Preserved as v1.2 HERM-04 fallback configuration; SDK exposes crossAiExecutionConfigured, CJS omits.	cross_ai_execution: true, profile: 'balanced' → legacy 'sonnet', init 'sonnet'.

Hermes is absent from KNOWN_RUNTIMES. Setting runtime: "hermes" emits a one-shot stderr warning (gsd: warning — config key "runtime" has unknown value "hermes") and falls through to the Claude-safe profile alias (e.g. 'opus' for quality). This is intentional: Hermes runs Claude-native semantics at the adapter level, so tier-based ID resolution via resolveTierEntry returns null and the v1.2 resolveAgentBinding path takes over. Non-Hermes runtimes selected by the same installer (Codex, OpenCode, etc.) DO consume resolveTierEntry and receive runtime-native IDs.

SDK/CJS contract asymmetry. sdk/src/query/runtime-model-contract.ts::resolveAgentBinding returns the superset shape with runtime, runtimeCapability, crossAiExecutionConfigured, and suggestedFix fields. The CJS adapter (get-shit-done/bin/lib/model-profiles.cjs::resolveAgentBinding) returns the v1.1-minimum intersection: {kind, agent, knownAgent, bindingKind, source, configuredModel, resolvedModel, modelToken, profile, resolveModelIds, rejectionReason?}. tests/runtime-model-parity.test.cjs asserts only the intersection so divergence is controlled and non-breaking.

Validation evidence: node --test tests/runtime-model-parity.test.cjs (enrolled in scripts/validate-hermes-compat.cjs::testFiles[] during Phase 7 Plan 01; 13 subtests green covering all five binding paths above).

Runtime Binding Receipt Layers

model_binding_receipts appear in plan-phase and execute-phase init payloads. They make model-binding intent and proof boundaries visible before runtime dispatch. They are deliberately more precise than a single yes/no flag: GSD resolver proof, workflow handoff proof, Hermes child-construction proof, and provider wire-level proof are separate layers.

Layer	Receipt/proof field	Meaning	Proof boundary
Resolver	resolved_by_gsd	GSD recognized the agent and resolved the configured model/profile/omit path into a binding token or an explicit rejection.	Proves GSD resolver behavior only.
Workflow handoff	passed_to_runtime	GSD has a non-empty explicit token ready for a runtime handoff.	Proves workflow payload construction, not provider use.
Hermes child construction	runtime_binding_channel, child construction tests	Hermes receives the intended child model through direct delegate_task(model=...) or batch tasks[].model.	Proves child AIAgent(model=...) construction, not live provider wire-level dispatch.
Provider-routed CLI command	agent_execution_bindings, provider-cli dispatcher tests	GSD selects hermes chat --model ... for hermes/* overrides, codex exec --model ... for OpenAI/GPT-family models, and claude -p --model ... for Anthropic/Claude-family models.	Proves deterministic command routing and normalized CLI model arguments, not provider wire-level API routing inside external CLI tools.
Provider diagnostics	sanitized provider metadata	Safe metadata can expose provider/model/proof source without raw headers, request bodies, messages, or secrets.	Diagnostic proof only; credentials and raw payloads must never be stored.
Provider wire-level proof	runtime_enforced when supported by sanitized request evidence	A provider request or wire-level capture proves the live child request used model=....	Highest-confidence proof; not claimed unless captured safely.

runtime_enforced=unknown is not failure and is not provider proof. It means GSD can show resolver intent, workflow handoff, and possibly Hermes child construction, but it has not captured sanitized provider request evidence proving live provider-side model=... dispatch. A subagent self-report is not proof and must not be treated as evidence of enforcement.

Phase 11 selects the canonical direct Hermes binding seam as delegate_task(model=...) for single child spawns and tasks[].model for batch spawns. delegation.model remains a global default/fallback, not a per-agent GSD override channel. ACP --model remains transport-specific and is only relevant when ACP subprocess routing is selected. Phase 11 proof stops at child AIAgent(model=...) construction; provider request or wire-level model=... proof remains a separate provider-instrumentation boundary.

Phase 12 adds fail-fast validation and proof tests: unsupported explicit Hermes bindings fail before spawn with actionable diagnostics, invalid explicit model tokens cannot silently fall back to the parent/default model, and Hermes Agent tests verify that GSD planner/executor overrides reach child AIAgent(model=...) construction.

Provider-Routed CLI Enforcement

model_overrides is the recommended strict route when operators need different GSD agents to run under different execution surfaces in a Hermes workflow. Use hermes/<model> for Hermes-native execution without workflow.agent_execution_* config, or plain openai/* / anthropic/* values for direct provider CLIs. The SDK emits agent_execution_bindings from model_overrides; /gsd-execute-phase consumes those bindings before legacy Task/delegate/cross-AI fallback paths.

Configured model	Provider family	Driver	Command proof
hermes/gpt-5.5	OpenAI/GPT	Hermes terminal tool	hermes chat --toolsets terminal,file --model gpt-5.5 ...
hermes/claude-opus-4-7	Anthropic/Claude	Hermes terminal tool	hermes chat --toolsets terminal,file --model claude-opus-4-7 ...
openai/gpt-5.5 or gpt-5.5	OpenAI/GPT	Codex CLI	codex exec --model gpt-5.5 ...
anthropic/claude-opus-4-7 or claude-opus-4-7	Anthropic/Claude	Claude Code CLI	claude -p --model claude-opus-4-7 ...

This mode intentionally fails fast for direct provider-CLI routes with unsupported families, missing cli_model, missing CLI binaries, or unavailable CLI authentication. For hermes/* routes, GSD renders hermes chat without --provider and leaves provider selection to the currently configured Hermes provider; failures should come from missing Hermes CLI/preflight or Hermes itself, not from GSD falling back to Codex/Claude. A valid per-agent binding has priority over workflow.cross_ai_execution; that legacy setting remains a whole-plan fallback and must not silently override per-agent provider routing.

Proof boundary: provider-routed mode proves that GSD chose the matching driver and passed the normalized --model argument. For Hermes-native routes, this proof also covers that GSD did not pass --provider; it does not prove what Hermes Agent, Anthropic, OpenAI, Codex CLI, or Claude Code CLI sends on the wire after that process starts. Wire-level proof would require separate sanitized provider diagnostics.

Provider-cli mode is separate from Hermes native delegate_task(model=...) child-construction proof. Native delegate proof applies only when GSD uses Hermes child spawning; provider-cli proof applies when GSD deliberately uses rendered commands (hermes chat, Codex CLI, or Claude Code CLI) for per-agent routing.

Do not log secrets while collecting receipt evidence. Provider requests or diagnostic captures must redact API keys, tokens, cookies, passwords, authorization headers, client secrets, and credential-bearing URLs. Raw provider headers, request bodies, messages, and connection strings must not be persisted.

Known Gaps

• Project-linked mode depends on ~/.hermes/config.yaml skills.external_dirs, so duplicate global and project-linked command names can depend on Hermes discovery order.
• ws@^8.20.0 is a direct root dependencies entry in package.json, not a transitive dep of @anthropic-ai/claude-agent-sdk (D-16 correction per Phase 7 RESEARCH §Pitfall 6). Hermes runtime does not itself require websocket infrastructure — ws is currently retained for SDK transport use. Verified via npm ls ws on 2026-04-24.

Adapter Guardrails

• Prefer adapter or shim changes over workflow rewrites.
• Do not claim a native local Hermes install mode.
• Keep Hermes patches concentrated in installer, runtime conversion, compatibility, documentation, and test layers.
• If a change touches get-shit-done/workflows/ broadly, stop and justify it against D-02 before implementation.
• Use merge history from upstream/main to review Hermes drift before broadening a patch.

Slash Command Inventory

Tracks Hermes-owned slash commands per Phase 7 D-11 compatibility boundary: Hermes runtime SKILL.md files keep /gsd-<cmd> dash form because Hermes discovery is dash-natural and portable across filesystems. Upstream-owned commands and tests may still carry the colon-namespace form from upstream #2543, but Hermes-owned user-facing docs should present dash-form commands. The table below maps each Hermes dash-form slash reference in user-facing Hermes docs to the skill path produced by bin/install.js::copyCommandsAsHermesSkills.

Slash Command (dash-form)	Source Doc	Produced Skill Path
/gsd-help	docs/hermes-install.md	~/.hermes/skills/gsd-help/SKILL.md (global) or <project>/.gsd-hermes/skills/gsd-help/SKILL.md (project-linked)
/gsd-progress	docs/hermes-install.md	~/.hermes/skills/gsd-progress/SKILL.md (global) or <project>/.gsd-hermes/skills/gsd-progress/SKILL.md
/gsd-new-project	docs/hermes-install.md	~/.hermes/skills/gsd-new-project/SKILL.md or <project>/.gsd-hermes/skills/gsd-new-project/SKILL.md
/gsd-discuss-phase	docs/hermes-install.md	~/.hermes/skills/gsd-discuss-phase/SKILL.md or <project>/.gsd-hermes/skills/gsd-discuss-phase/SKILL.md
/gsd-plan-phase	docs/hermes-install.md	~/.hermes/skills/gsd-plan-phase/SKILL.md or <project>/.gsd-hermes/skills/gsd-plan-phase/SKILL.md
/gsd-execute-phase	docs/hermes-install.md	~/.hermes/skills/gsd-execute-phase/SKILL.md or <project>/.gsd-hermes/skills/gsd-execute-phase/SKILL.md

Compatibility rationale (D-11). Upstream uses a colon-namespace slash-command form after #2543 for runtimes whose command resolver treats colons as namespace separators. Hermes uses flat directory-based skill discovery where filenames cannot contain colons on Windows filesystems, so Hermes SKILL.md skills are generated with dash-form names. The installer at bin/install.js::copyCommandsAsHermesSkills generates per-command directories named gsd-<cmd>/SKILL.md by iterating source command files in commands/gsd/*.md; Hermes skills receive appended runtime-compatibility notes via appendHermesRuntimeNote. Other runtimes receive upstream command names unchanged per D-10.

Audit completeness. The Hermes-owned paths that reference slash syntax are: bin/install.js skill-generation logic (runtime prefix gsd- from copyCommandsAsClaudeSkills delegate), docs/hermes-*.md user-facing guides, scripts/validate-hermes-compat.cjs + test files under tests/hermes-*.test.cjs. Upstream-owned paths (commands/gsd/*.md, agents/gsd-*.md, hooks/, get-shit-done/) are handled by upstream #2543 and kept as-is after Phase 6 merge per D-10, but should not be used to imply Hermes-owned public docs accept colon-form slash commands.

Validation evidence: tests/hermes-docs.test.cjs asserts that every slash command in this inventory corresponds to an expected source command file the installer converts into a Hermes skill (covered in the SLASH-02 describe block added in Phase 7 Plan 03).

Maintenance Contract

Run npm run test:hermes after Hermes adapter seam changes and after every upstream sync. Run npm test as the full-suite release gate when feasible.

When Hermes cannot support an upstream behavior immediately, record known gaps instead of claiming unsupported parity. Release notes and docs should preserve the distinction between supported behavior, supported degraded paths, and out-of-scope native local install semantics.

Phase Mapping

Surface	Target phase	Ownership label	Routing note
Global Hermes install	Phase 3	Hermes adapter seam	Supported through generated ~/.hermes/skills/gsd-* command skills.
Project-linked external_dirs mode	Phase 3	Hermes adapter seam	Supported through .gsd-hermes/skills plus ~/.hermes/config.yaml skills.external_dirs.
Hermes runtime selection in installer	Phase 2	Hermes adapter seam	Runtime selection belongs in installer surfaces, not a broad rewrite of the upstream workflow tree.
Command discovery for /gsd-*	Phase 3	Hermes adapter seam	Supported through Hermes SKILL.md command generation and discovery smoke checks.
Core workflow execution	Phase 4	Upstream base	Phase 4 complete: supported with degraded paths through deterministic fixture coverage plus documented degraded paths where Hermes needs them.
Update / uninstall / doctor	Phase 5	Hermes adapter seam	Phase 5 complete: supported through update/uninstall/doctor lifecycle tests and operator docs.
Upstream sync routine	Phase 6	Downstream governance	Sync review stays anchored to governance docs and merge history from upstream/main so Hermes drift remains visible.
Native local Hermes install mode	Phase 6	Downstream governance	This remains out of scope; later phases preserve the boundary rather than turning it into a supported mode.

The ownership labels above follow Fork Ownership: Upstream base stays merge-friendly, Hermes adapter seam contains bounded runtime work, and Downstream governance records the policy and compatibility truth that future phases must not overstate.