trader-mcp/Hermes_Compatibility_Plan.md

Trader-MCP Hermes Compatibility Plan

This file turns TODO.md into a stepwise upgrade path toward hermes-mcp compatibility.

Goal

Prepare trader-mcp so Hermes can supervise strategy selection, risk posture, and switching without collapsing Trader into a monolith.

Trader should remain:

• strategy runtime
• execution feedback surface
• operator dashboard
• persistence owner for strategy state

Hermes should remain:

• selector
• supervisor
• regime interpreter
• switch/risk controller

Core design principles

1. Small interfaces.
2. Explicit ownership.
3. Human-readable strategy names.
4. Structured state over vibes.
5. Stable switch semantics.
6. Contract-first development.
7. Tests before expansion.

Canonical strategy set

Start with a small orthogonal registry:

• idle
• defensive
• trend_following
• mean_reversion
• grid
• breakout
• event_driven

Strategy ordering priority

1. idle
2. defensive
3. trend_following
4. mean_reversion
5. grid
6. breakout
7. event_driven

This is not a quality ranking. It is a sequencing plan for implementation and testing.

Ownership boundaries

Strategy owns

• its local logic
• its local state
• its local config
• its own render output
• its own explanation string

Trader runtime owns

• lifecycle
• persistence
• snapshots
• reconciliation
• dashboard presentation
• execution plumbing

Human observer owns

• inspection
• approval where configured
• operational overrides where explicitly allowed
• debugging and review

Hermes owns

• strategy enable/disable/switch decisions
• risk-mode changes
• uncertainty and confidence weighting
• regime interpretation
• execution-degradation-driven downranking

Upgrade phases

Phase 0, document the contract

Deliverables:

• Hermes_Trader_Contract_v0.1.md
• agreed strategy taxonomy
• agreed state and decision fields
• agreed control verbs

Acceptance criteria:

• every strategy has expects, avoids, and risk_profile
• Hermes request and Trader response shapes are machine readable
• no contract depends on hidden state

Phase 1, normalize the strategy registry

Deliverables:

• fold redundant names into the canonical set
• mark parameter variants as modes
• ensure strategy labels are stable and human-readable

Acceptance criteria:

• each strategy name maps to one conceptual regime
• no micro-strategy sprawl
• old names can be redirected or deprecated cleanly

Phase 2, expose Hermes-facing inspection tools

Deliverables:

• list_strategies
• get_strategy
• get_runtime_state
• get_recent_changes
• get_decision_history
• get_execution_state

Acceptance criteria:

• Hermes can inspect state without knowing internals
• dashboard and API show the same truth
• every response is structured and auditable

Phase 3, add control tools for Hermes

Deliverables:

• apply_control_decision
• switch_strategy
• set_risk_mode
• pause_strategy
• resume_strategy
• reconcile_state

Acceptance criteria:

• Hermes can control Trader through explicit verbs
• invalid or unsafe requests are rejected cleanly
• every transition records a reason and decision id

Phase 4, implement switching safety

Deliverables:

• confidence threshold
• minimum hold time
• hysteresis
• explicit emergency override path
• degraded execution fallback

Acceptance criteria:

• strategies do not flap on minor noise
• switching reasons are deterministic and testable
• defensive and idle are valid safe exits

Phase 5, implement initial strategies

Deliverables:

• idle
• defensive
• trend_following
• mean_reversion

Acceptance criteria:

• each one has metadata and tests
• each one returns clear state/explanation data
• each one can be selected by Hermes-compatible contract shapes

Phase 6, add structure strategies

Deliverables:

• grid
• breakout

Acceptance criteria:

• grid is clearly structure-based, not signal-based
• breakout is separated from trend-following
• tests cover the distinction

Phase 7, add event-aware behavior

Deliverables:

• event_driven
• event-risk metadata
• event-pressure aware selection logic

Acceptance criteria:

• Hermes can downrank normal strategies during event risk
• event handling remains temporary and explicit

Phase 8, feed back execution quality

Deliverables:

• fills
• slippage
• latency
• rejections
• stress
• degraded connectivity

Acceptance criteria:

• execution quality affects strategy selection
• Trader surfaces the feedback clearly
• Hermes can see why a strategy was penalized

Phase 9, tighten dashboards and audit trails

Deliverables:

• current strategy view
• why-active view
• recent changes timeline
• Hermes decision trace
• execution state panel

Acceptance criteria:

• a human can understand the system without reading code
• transitions are explainable from the UI

Tests to add

Contract tests

• strategy metadata validation
• Hermes request schema validation
• Trader response schema validation
• control verb validation

Runtime tests

• load/unload/switch transitions
• state snapshot and restore
• minimum hold enforcement
• hysteresis enforcement
• defensive fallback on degraded execution

Strategy tests

• expected regime matching
• avoided regime rejection
• deterministic state transitions
• readable explanation output

Integration tests

• Hermes decision to Trader control path
• Trader response parsing
• execution feedback influencing future selection

Suggested first implementation order

1. lock the contract paper
2. canonicalize the strategy registry
3. add metadata to current strategies
4. add validation tests
5. implement the inspection tools
6. implement the control tools
7. add switching safety
8. implement idle and defensive
9. implement trend_following and mean_reversion
10. add grid, breakout, and event_driven
11. wire execution feedback into selection
12. polish dashboard and traceability

Notes on ownership and scope

Trader should not become a second Hermes.

If a feature answers "what should the world do?", it belongs to Hermes. If a feature answers "how do we run the chosen strategy safely?", it belongs to Trader. If a feature answers "what happened and why?", it belongs to both through a shared contract.

Output philosophy

The end state should make Trader useful to Hermes, useful to humans, and still simple enough to debug.